多 Agent 协作

OpenClaw 支持在单个 Gateway 中运行多个独立的 Agent。每个 Agent 拥有独立的工作空间、记忆和人格，适合为不同的人、项目或场景配置专用的 AI 助手。

为什么需要多 Agent？

单 Agent 模式下，所有消息都由同一个 Agent 处理，可能存在以下问题：

• 职责混淆：工作和生活的需求混在一起
• 人格冲突：不同场景需要不同的交互风格
• 数据隔离：不同用户的偏好和历史需要分离
• 权限控制：不同用途需要不同的工具权限

多 Agent 模式解决了这些问题：

维度	单 Agent	多 Agent
工作空间	共享	独立
记忆	共享	独立
人格	单一	可定制
权限	统一	可隔离

什么是"一个 Agent"？

一个 Agent 是一个完全独立的作用域，拥有：

• 工作空间（Workspace）：文件操作目录，包含 AGENTS.md、SOUL.md、MEMORY.md 等
• 状态目录（agentDir）：存储认证配置、模型注册、会话数据
• 会话存储：聊天历史和路由状态

每个 Agent 读取自己的配置和记忆，不会自动共享。如果需要共享凭证，需要手动复制 auth-profiles.json 到另一个 Agent 的 agentDir。

路径映射

项目	默认路径
主配置	~/.openclaw/openclaw.json
状态目录	~/.openclaw
默认工作空间	~/.openclaw/workspace
Agent 目录	~/.openclaw/agents/<agentId>/agent
Agent 会话	~/.openclaw/agents/<agentId>/sessions

单 Agent 模式（默认）

默认情况下，OpenClaw 运行单个 Agent：

• agentId 默认为 main
• 会话标识为 agent:main:<mainKey>
• 工作空间默认为 ~/.openclaw/workspace

配置多 Agent

使用 Agent 向导

# 创建新 Agent
openclaw agent create

# 按向导提示配置

手动配置

在 openclaw.json 中添加 Agent 配置：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work"
      },
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal"
      }
    ]
  }
}

创建 Agent 工作空间

每个 Agent 需要独立的工作空间：

# 创建工作空间目录
mkdir -p ~/.openclaw/workspace-work
mkdir -p ~/.openclaw/workspace-personal

# 创建必要的配置文件
touch ~/.openclaw/workspace-work/SOUL.md
touch ~/.openclaw/workspace-work/MEMORY.md

touch ~/.openclaw/workspace-personal/SOUL.md
touch ~/.openclaw/workspace-personal/MEMORY.md

绑定（Bindings）

绑定决定了消息如何路由到 Agent。

路由规则

绑定是确定性的，最具体的匹配优先：

1. peer 匹配（精确私聊/群聊 ID）
2. parentPeer 匹配（线程继承）
3. guildId + roles（Discord 角色路由）
4. guildId（Discord）
5. teamId（Slack）
6. accountId 匹配（渠道账号）
7. 渠道级别匹配（accountId: "*"）
8. 回退到默认 Agent

绑定示例

{
  "bindings": [
    {
      "channel": "telegram",
      "accountId": "personal",
      "agentId": "personal"
    },
    {
      "channel": "slack",
      "accountId": "work",
      "agentId": "work"
    },
    {
      "channel": "telegram",
      "peer": "GROUP_CHAT_ID",
      "agentId": "team"
    }
  ]
}

重要细节

• 省略 accountId 的绑定只匹配默认账号
• 使用 accountId: "*" 匹配渠道的所有账号
• 所有指定字段都必须匹配（AND 语义）

多账号支持

某些渠道支持多账号（如 WhatsApp），可以路由到不同的 Agent。

WhatsApp 多号示例

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "personal": {},
        "business": {}
      }
    }
  },
  "bindings": [
    {
      "channel": "whatsapp",
      "accountId": "personal",
      "agentId": "personal"
    },
    {
      "channel": "whatsapp",
      "accountId": "business",
      "agentId": "work"
    }
  ]
}

平台示例

Telegram 多 Bot

每个 Agent 使用不同的 Telegram Bot：

{
  "channels": {
    "telegram": {
      "accounts": {
        "personal": {
          "botToken": "PERSONAL_BOT_TOKEN"
        },
        "work": {
          "botToken": "WORK_BOT_TOKEN"
        }
      }
    }
  },
  "bindings": [
    {
      "channel": "telegram",
      "accountId": "personal",
      "agentId": "personal"
    },
    {
      "channel": "telegram",
      "accountId": "work",
      "agentId": "work"
    }
  ]
}

Discord 多 Bot

{
  "channels": {
    "discord": {
      "accounts": {
        "gaming": {
          "token": "GAMING_BOT_TOKEN"
        },
        "dev": {
          "token": "DEV_BOT_TOKEN"
        }
      }
    }
  },
  "bindings": [
    {
      "channel": "discord",
      "accountId": "gaming",
      "agentId": "personal"
    },
    {
      "channel": "discord",
      "accountId": "dev",
      "agentId": "work"
    }
  ]
}

私聊分流（同一 WhatsApp）

一个 WhatsApp 号码，不同私聊路由到不同 Agent：

{
  "bindings": [
    {
      "channel": "whatsapp",
      "peer": "+15551234567",
      "agentId": "alice"
    },
    {
      "channel": "whatsapp",
      "peer": "+15559876543",
      "agentId": "bob"
    }
  ]
}

注意：直接聊天会合并到 Agent 的 main 会话，因此真正的隔离需要每个人一个 Agent。

群组绑定

将特定群组绑定到专用 Agent：

{
  "bindings": [
    {
      "channel": "whatsapp",
      "peer": "GROUP_ID",
      "agentId": "family"
    }
  ]
}

Per-Agent 配置

沙箱和工具限制

每个 Agent 可以有独立的沙箱和工具配置：

{
  "agents": {
    "list": [
      {
        "id": "trusted",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "sandboxed",
        "sandbox": {
          "mode": "docker"
        },
        "tools": {
          "deny": ["exec", "browser"]
        }
      }
    ]
  }
}

模型配置

不同 Agent 可以使用不同的模型：

{
  "agents": {
    "list": [
      {
        "id": "fast",
        "model": "anthropic/claude-sonnet-4-6"
      },
      {
        "id": "smart",
        "model": "anthropic/claude-opus-4-6"
      }
    ]
  }
}

工作空间隔离

每个 Agent 的工作空间是其默认工作目录，而非硬性沙箱：

• 相对路径解析到工作空间内
• 绝对路径可以访问主机其他位置（除非启用沙箱）

启用沙箱

对于需要严格隔离的场景，可以启用 Docker 沙箱：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

这会让非 main 会话在 Docker 容器中运行。

Agent CLI 命令

# 列出所有 Agent
openclaw agent list

# 创建新 Agent
openclaw agent create

# 查看 Agent 详情
openclaw agent info <agent-id>

# 测试 Agent
openclaw agent --message "测试" --agent <agent-id>

最佳实践

职责单一

每个 Agent 应该有明确的职责范围：

• work - 工作相关的代码、文档
• personal - 生活、日程
• family - 家庭群组专用

命名清晰

使用一目了然的命名：

• work、personal、family ✓
• agent1、agent2 ✗

配置独立人格

为每个 Agent 定制 SOUL.md：

work/SOUL.md：

# 你是谁

你是一位专业的软件开发助手。

## 风格
- 技术性语言
- 简洁直接
- 提供代码示例

## 职责
- 代码审查
- 技术问答
- 文档编写

personal/SOUL.md：

# 你是谁

你是一位友好的生活助手。

## 风格
- 轻松随意
- 关心用户感受
- 提供建议和提醒

## 职责
- 日程管理
- 提醒通知
- 生活建议

常见问题

Agent 之间无法通信

Agent 默认是隔离的。如果需要通信，需要通过 Gateway 的会话工具实现。

消息路由错误

检查绑定规则的优先级和匹配条件。使用 openclaw status 查看当前路由状态。

配置不生效

确保 JSON 格式正确，重启 Gateway 使配置生效。

下一步

• 渠道接入 - 配置消息渠道
• 浏览器自动化 - Agent 浏览器能力
• 最佳实践 - 生产环境配置