AI 代理

AI 代理 🤖

AI 代理是 OpenClaw 的”大脑”，负责理解消息并生成回复。

🎯 什么是代理？

代理是一个 AI 程序，能够：

理解自然语言
执行任务
调用工具
保持对话记忆

┌─────────────┐
│  用户消息   │
└──────┬──────┘
       ↓
┌─────────────┐
│  AI 代理    │  理解 → 思考 → 行动
│  (Pi/GPT)   │
└──────┬──────┘
       ↓
┌─────────────┐
│  AI 回复    │
└─────────────┘

🏗️ 代理类型

1. Pi Agent（默认）

Pi 是 OpenClaw 的默认代理：

基于 Claude 或 GPT 模型
专为对话设计
支持工具调用
本地运行，无需云端

配置示例：

{
  agents: {
    default: {
      type: "pi",
      model: "claude-3.5-sonnet",
      temperature: 0.7,
      maxTokens: 4096
    }
  }
}

2. 远程代理

可以配置云端 AI 服务：

提供商	模型	特点
OpenAI	GPT-4/GPT-3.5	强大但需联网
Anthropic	Claude	优秀的推理能力
Google	Gemini	多模态支持
Local	Ollama	完全本地运行

配置示例：

{
  agents: {
    openai: {
      type: "openai",
      apiKey: "${OPENAI_API_KEY}",
      model: "gpt-4"
    }
  }
}

3. 自定义代理

开发者可以创建自己的代理：

// 自定义代理示例
class MyAgent {
  async handleMessage(message: string, context: Context) {
    // 自定义处理逻辑
    return "自定义回复";
  }
}

🔧 代理配置

基本参数

{
  agents: {
    defaults: {
      // 默认代理设置
      type: "pi",
      model: "claude-3.5-sonnet",
      temperature: 0.7,
      maxTokens: 4096,

      // 会话设置
      session: {
        maxHistory: 20,  // 保留多少轮对话
        timeout: 300     // 会话超时时间（秒）
      }
    },

    // 特定代理列表
    list: [
      {
        id: "support",
        name: "客服助手",
        model: "claude-3.5-sonnet",
        temperature: 0.3,  // 更确定的回答
        systemPrompt: "你是一个专业的客服助手..."
      },
      {
        id: "creative",
        name: "创意助手",
        model: "gpt-4",
        temperature: 0.9,  // 更有创意的回答
        systemPrompt: "你是一个充满创意的助手..."
      }
    ]
  }
}

关键参数解释

参数	说明	推荐值
temperature	创造性程度	0.3-0.9
maxTokens	最大回复长度	2048-4096
topP	采样多样性	0.9-1.0
systemPrompt	系统提示词	根据用途定制

🎭 系统提示词 (System Prompt)

系统提示词定义了代理的行为和个性：

{
  agents: {
    list: [
      {
        id: "assistant",
        systemPrompt: `
你是一个乐于助人的 AI 助手。

特点：
- 友好、耐心的语气
- 回答简洁明了
- 不确定时诚实说明
- 使用中文回复

限制：
- 不执行危险操作
- 不泄露敏感信息
- 遵守当地法律法规
        `
      }
    ]
  }
}

提示词工程技巧

明确角色：“你是一个专业的程序员”
定义边界：“不要提供医疗建议”
指定格式：“用列表形式回答”
设置语气：“用友好、专业的语气”

🛠️ 工具调用

代理可以使用工具来扩展能力：

用户："今天北京天气怎么样？"
代理：我需要查询天气 → 调用天气工具
天气工具：返回天气数据
代理：根据数据生成回复

可用工具

工具	功能	示例
web_search	网页搜索	”搜索 OpenClaw 最新版本”
web_fetch	获取网页内容	”读取这个 URL”
file_read	读取文件	”查看 workspace.txt”
file_write	写入文件	”保存笔记”
image_generate	生成图像	”画一只猫”
browser	浏览器自动化	”打开网页并点击”

工具配置

{
  tools: {
    // 允许/拒绝特定工具
    allow: ["web_search", "file_read"],
    deny: ["file_write", "exec"],

    // 工具配置文件
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"
      }
    },

    image: {
      provider: "openai",
      apiKey: "${OPENAI_API_KEY}"
    }
  }
}

🎨 多代理系统

场景路由

根据对话场景选择不同代理：

{
  agents: {
    routing: {
      rules: [
        {
          pattern: "^/code",
          agent: "programmer"
        },
        {
          pattern: "^/support",
          agent: "support"
        },
        {
          pattern: ".*",
          agent: "default"
        }
      ]
    }
  }
}

代理切换

用户可以在对话中切换代理：

用户：/agent programmer
系统：已切换到程序员代理

用户：帮我写个 Python 脚本
程序员代理：好的，我来帮你...

🧠 记忆和上下文

会话记忆

代理记住当前对话：

用户：我叫小明
代理：你好小明！

用户：我的名字是什么？
代理：你叫小明

长期记忆

跨会话保持重要信息：

{
  agents: {
    defaults: {
      memory: {
        enabled: true,
        storage: "local",  // 本地存储
        maxEntries: 100   // 最多100条记忆
      }
    }
  }
}

🔒 安全考虑

代理权限

限制代理的能力：

{
  agents: {
    defaults: {
      permissions: {
        canExecuteCode: false,   // 禁止执行代码
        canAccessInternet: true, // 允许上网
        canModifyFiles: false,   // 禁止修改文件
        canDeleteData: false     // 禁止删除数据
      }
    }
  }
}

沙箱隔离

敏感操作在沙箱中运行：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "strict",  // strict / normal / off
        allowedPaths: ["~/.openclaw/workspace"],
        blockedPaths: ["/etc", "/usr"]
      }
    }
  }
}

📊 性能优化

响应速度

流式输出：实时显示生成内容
并发处理：同时处理多个消息
缓存机制：缓存常用回复

成本控制

使用远程代理时注意：

{
  agents: {
    defaults: {
      costControl: {
        maxTokensPerDay: 100000,
        maxRequestsPerHour: 100,
        alertThreshold: 0.8  // 80%时告警
      }
    }
  }
}