OpenClaw 多代理路由完全指南：一个 Gateway 进程运行多个独立 AI 助手

OpenClaw 支持在同一个 Gateway 进程中运行多个完全隔离的 AI 代理（Agent），每个代理拥有独立的工作区、认证配置和会话存储，还能绑定不同的聊天平台账号（比如两个不同的 WhatsApp 号码）。本文详解多代理架构的核心概念和配置方式。

核心概念：Agent 与 Binding#

理解 OpenClaw 多代理架构，先要分清两个概念：

• Agent（代理）：一个完整的「人设」作用域，包括工作区文件、认证配置、模型注册表和会话存储
• Binding（绑定）：把一个渠道账号（一个 Slack 工作区、一个 WhatsApp 号码等）映射到某个 Agent

入站消息通过 Binding 路由到正确的 Agent——这是多代理架构能同时服务多个身份/多个团队的关键机制。

每个 Agent 独立拥有什么#

认证配置按 Agent 独立存放，路径为：

路径配置对照表#

⚠️ 重要安全警告：切勿跨代理复用 agentDir#

永远不要在多个 Agent 之间复用同一个 agentDir——这会导致认证/会话状态冲突。

有一个细节需要特别注意：当某个次级 Agent 的本地 OAuth 凭据过期、且刷新失败时，OpenClaw 会读取默认/主 Agent 同一 Profile ID 的凭据，并采用两者中最新的 Token——但不会把刷新令牌复制到次级 Agent 的存储中。

正确做法：

• 如果需要完全独立的 OAuth 账号，请从那个 Agent 本身登录
• 如果要手动复制凭据，只复制可移植的静态 api_key 或 token Profile
• OAuth 刷新材料默认不可移植（可以通过 copyToAgents 显式让某个 Profile 支持复制）

工作区不是硬沙箱#

每个 Agent 的工作区是其默认 cwd，而不是硬性沙箱。相对路径会在工作区内解析，但绝对路径可以访问主机上的其他位置，除非启用了沙箱化。如果需要严格隔离，需要额外配置 Sandboxing。

Skills 加载规则#

Skills 从每个 Agent 的工作区，加上共享根目录（如 ~/.openclaw/skills）加载，然后按该 Agent 的有效 Skill 白名单过滤：

{
  "agents": {
    "defaults": {
      "skills": ["weather", "web-search"]
    },
    "list": [
      {
        "agentId": "content-curator",
        "skills": ["web-search", "web-fetch", "session-logs"]
      }
    ]
  }
}

注意：agents.list[].skills 是替换默认列表，而不是与默认列表合并——显式配置的条目会完全覆盖 agents.defaults.skills。

跨会话安全查询：sessions_history#

如果需要让一个 Agent 查看其他会话的历史，sessions_history 是比直接读取原始记录更安全的方式：

它返回一个有边界、经过脱敏处理的视图，而不是原始对话转储——会自动剥离思考块签名、工具结果 Payload 细节、<relevant-memories> 脚手架内容、工具调用 XML 标签（<tool_call>、<function_call> 及其各种变体），然后按字节大小截断和限制输出。

典型应用场景#

总结#

OpenClaw 的多代理路由机制，让一台机器上的单个 Gateway 进程就能承载多个完全独立的 AI 身份——各自拥有工作区、记忆、认证和渠道绑定。核心要记住的安全边界是：永远不要跨 Agent 复用 agentDir，需要独立 OAuth 账号时从对应 Agent 本身登录。

来源：Multi-agent routing — OpenClaw 官方文档