古法编程

Appearance

OpenClaw 支持在一个 Gateway 进程内运行多个完全隔离的 Agent（智能体）。每个 Agent 拥有独立的工作区、Auth 配置和会话存储，通过 Binding 将不同渠道消息路由到指定 Agent。关键配置写入 openclaw.json，创建 Agent 用 openclaw agents add，查看绑定用 openclaw agents list --bindings。路由规则按 peer > guild > account > channel 优先级匹配，最具体者生效。

OpenClaw 多 Agent 配置：独立工作区、渠道账号与 Binding 路由 ​

在一个 Gateway 进程里运行多个隔离的 Agent——每个有独立 workspace、状态目录（agentDir）和会话历史——同时管理多个渠道账号（例如两个 WhatsApp 号码）。入站消息通过 Binding 路由到正确的 Agent。

Agent 是完整的人物作用域：工作区文件、Auth 配置、模型注册表和会话存储。agentDir 是磁盘状态目录，位于 ~/.openclaw/agents/<agentId>/。Binding 把渠道账号（如 Slack 工作区或 WhatsApp 号码）映射到其中一个 Agent。

一个 Agent 包含哪些独立资源 ​

一个 Agent 是一个完整的"大脑"，拥有自己的：

  • Workspace（文件、AGENTS.md / SOUL.md / USER.md、本地笔记、人格规则）
  • 状态目录（agentDir）：Auth 配置、模型注册表、per-agent 配置
  • 会话存储（聊天历史 + 路由状态）：~/.openclaw/agents/<agentId>/sessions

Auth 配置是 per-agent 的。每个 Agent 从自己的文件读取：

text
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

INFO

sessions_history 在这里也是更安全的跨会话回忆路径：它返回有限制的、消毒后的视图，而不是原始对话转储。助手回忆会剔除 thinking 标签、&lt;relevant-memories&gt; 脚手架、纯文本工具调用 XML 载荷（包括 &lt;tool_call&gt;...&lt;/tool_call&gt;、&lt;function_call&gt;...&lt;/function_call&gt;、&lt;tool_calls&gt;...&lt;/tool_calls&gt;、&lt;function_calls&gt;...&lt;/function_calls&gt; 以及截断的工具调用块）、降级的工具调用脚手架、泄露的 ASCII/全宽模型控制令牌以及格式错误的 MiniMax 工具调用 XML，然后再进行删减/截断。

WARNING

不要跨 Agent 复用 agentDir（会导致 Auth / 会话冲突）。Agent 在没有本地配置时可读取默认/main Agent 的 Auth 配置，但 OpenClaw 不会把 OAuth 刷新令牌克隆到次级 Agent 存储。如果需要独立的 OAuth 账号，从那个 Agent 登录；如果手动复制凭据，只复制可移植的静态 api_key 或 token 配置。

Skill 从每个 Agent 工作区加载，同时加载共享根目录（如 ~/.openclaw/skills），然后按配置的有效 Agent Skill 允许列表过滤。用 agents.defaults.skills 设置共享基线，用 agents.list[].skills 做 per-agent 替换。参考 Skills: per-agent vs shared 和 Skills: agent skill allowlists。

Gateway 可以运行 一个 Agent（默认）或 多个 Agent 并排。

INFO

工作区说明： 每个 Agent 的工作区是默认 cwd，不是硬沙箱。相对路径在工作区内解析，但绝对路径可以访问其他主机位置，除非启用了沙箱。参考 Sandboxing。

路径速查 ​

  • 配置：~/.openclaw/openclaw.json（或环境变量 OPENCLAW_CONFIG_PATH）
  • 状态目录：~/.openclaw（或 OPENCLAW_STATE_DIR）
  • 工作区：~/.openclaw/workspace（或 ~/.openclaw/workspace-<agentId>）
  • Agent 目录：~/.openclaw/agents/<agentId>/agent（或 agents.list[].agentDir）
  • 会话：~/.openclaw/agents/<agentId>/sessions

单 Agent 模式（默认） ​

什么都不做的话，OpenClaw 运行一个 Agent：

  • agentId 默认为 main
  • 会话以 agent:main:<mainKey> 键存储
  • 工作区默认为 ~/.openclaw/workspace（或 ~/.openclaw/workspace-&lt;profile&gt;，当设置了 OPENCLAW_PROFILE 时）
  • 状态目录默认在 ~/.openclaw/agents/main/agent

使用 Agent 助手工具 ​

用 wizard 添加一个新的隔离 Agent：

bash
openclaw agents add work

然后添加 bindings（或让 wizard 来做）以路由入站消息。

验证用：

bash
openclaw agents list --bindings

快速开始 ​

创建每个 Agent 工作区

用 wizard 或手动创建：

```bash
openclaw agents add coding
openclaw agents add social
```

每个 Agent 获得自己的工作区，包含 `SOUL.md`、`AGENTS.md` 和可选的 `USER.md`，以及专属的 `agentDir` 和会话存储（位于 `~/.openclaw/agents/<agentId>`）。

创建渠道账号

在每个目标渠道上创建账号，每个 Agent 一个账号：

- Discord：每个 Agent 一个 Bot，启用 Message Content Intent，复制每个 token
- Telegram：通过 BotFather 每个 Agent 一个 Bot，复制每个 token
- WhatsApp：为每个账号绑定不同手机号

```bash
openclaw channels login --channel whatsapp --account work
```

具体渠道指南：[Discord](/ai/ai-tools/openclaw/channels/discord)、[Telegram](/ai/ai-tools/openclaw/channels/telegram)、[WhatsApp](/ai/ai-tools/openclaw/channels/whatsapp)。

添加 Agent、账号和 Binding

在 `agents.list` 添加 Agent，在 `channels.&lt;channel&gt;.accounts` 添加渠道账号，用 `bindings` 连接它们（示例见下方）。

重启并验证

```bash
openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe
```

多个 Agent = 多人、多性格 ​

使用 多个 Agent，每个 agentId 成为一个完全隔离的性格：

  • 不同手机号/账号（按渠道 accountId 区分）
  • 不同性格（per-agent 工作文件如 AGENTS.md 和 SOUL.md）
  • 独立的 Auth + 会话（除非显式启用，否则不串扰）

这让多个人共享一台 Gateway 服务器，同时使他们的 AI"大脑"和数据隔离。

跨 Agent 的 QMD 记忆搜索 ​

如果某个 Agent 需要搜索另一个 Agent 的 QMD 会话记录，在该 Agent 配置下的 agents.list[].memorySearch.qmd.extraCollections 添加额外集合。用 agents.defaults.memorySearch.qmd.extraCollections 则每个 Agent 都会继承相同的共享会话集合。

json5
{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
      memorySearch: {
        qmd: {
          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
        },
      },
    },
    list: [
      {
        id: "main",
        workspace: "~/workspaces/main",
        memorySearch: {
          qmd: {
            extraCollections: [{ path: "notes" }], // 解析为工作区内路径 -> 集合名 "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

额外集合路径可在 Agent 间共享，但当路径在 Agent 工作区外时，集合名称必须显式指定。工作区内的路径保持 Agent 作用域，因此每个 Agent 拥有独立的会话搜索集合。

一个 WhatsApp 号码，多人使用（DM 拆分） ​

可以在 一个 WhatsApp 账号 下把不同 DM 路由到不同 Agent。用发送者 E.164 号（如 +15551234567）匹配 peer.kind: "direct"。回复仍从同一 WhatsApp 号码发出（没有 per-agent 发送者身份）。

INFO

直接聊天会折叠到 Agent 的 main session key，因此真正隔离需要每个用户一个 Agent。

示例：

json5
{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

注意：

  • DM 的访问控制是每个 WhatsApp 账号全局的（配对/allowlist），不是 per-agent。
  • 对于共享群组，把群组绑定到一个 Agent，或使用 Broadcast groups。

路由规则（消息如何选择 Agent） ​

Binding 是确定性的，最具体者优先：

peer 匹配

精确的 DM / 群组 / 频道 ID。

parentPeer 匹配

线程继承。

guildId + roles

Discord 角色路由。

guildId

Discord。

teamId

Slack。

accountId 匹配（针对某渠道）

per-account 回退。

渠道级匹配

`accountId: "*"`。

默认 Agent

回退到 `agents.list[].default`，否则第一条，默认 `main`。

平局处理和 AND 语义

- 如果多个 Binding 在同一层级匹配，按配置顺序排在前面的优先。
- 如果 Binding 设置了多个匹配字段（如 `peer` + `guildId`），所有指定字段必须同时满足（AND 语义）。

账号作用域细节

- 省略 `accountId` 的 Binding 只匹配默认账号。
- 使用 `accountId: "*"` 做渠道级回退，覆盖所有账号。
- 如果后来为同一 Agent 添加了同名 Binding 并指定了显式 accountId，OpenClaw 会把已有的渠道级 Binding 升级为账号作用域，而不是重复创建。

多账号 / 多手机号 ​

支持 多账号 的渠道（如 WhatsApp）用 accountId 标识每个登录。每个 accountId 可路由到不同 Agent，因此一台服务器可以托管多个手机号而不混会话。

如果想为省略 accountId 的 Binding 指定渠道级默认账号，设置 channels.&lt;channel&gt;.defaultAccount（可选）。未设置时，OpenClaw 回退到 default（如存在），否则按排序取第一个配置的账号 ID。

支持此模式的常见渠道：

  • whatsapp、telegram、discord、slack、signal、imessage
  • irc、line、googlechat、mattermost、matrix、nextcloud-talk
  • zalo、zalouser、nostr、feishu

概念 ​

  • agentId：一个"大脑"（工作区、per-agent Auth、per-agent 会话存储）
  • accountId：一个渠道账号实例（如 WhatsApp 账号"personal" vs "biz"）
  • binding：按 (channel, accountId, peer) 及可选的 guild/team ID 将入站消息路由到 agentId
  • 直接聊天折叠为 agent:<agentId>:<mainKey>（per-agent "main"；session.mainKey）

平台配置示例 ​

每个 Agent 一个 Discord Bot

每个 Discord Bot 账号对应一个唯一的 `accountId`。把每个账号绑定到一个 Agent，并为每个 Bot 维护 allowlist。

```json5
{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
  ],
  channels: {
    discord: {
      groupPolicy: "allowlist",
      accounts: {
        default: {
          token: "DISCORD_BOT_TOKEN_MAIN",
          guilds: {
            "123456789012345678": {
              channels: {
                "222222222222222222": { allow: true, requireMention: false },
              },
            },
          },
        },
        coding: {
          token: "DISCORD_BOT_TOKEN_CODING",
          guilds: {
            "123456789012345678": {
              channels: {
                "333333333333333333": { allow: true, requireMention: false },
              },
            },
          },
        },
      },
    },
  },
}
```

- 把每个 Bot 邀请到 guild，启用 Message Content Intent。
- Token 放在 `channels.discord.accounts.&lt;id&gt;.token`（默认账号可使用 `DISCORD_BOT_TOKEN` 环境变量）。

每个 Agent 一个 Telegram Bot

```json5
{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
  ],
  channels: {
    telegram: {
      accounts: {
        default: {
          botToken: "123456:ABC...",
          dmPolicy: "pairing",
        },
        alerts: {
          botToken: "987654:XYZ...",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
      },
    },
  },
}
```

- 通过 BotFather 为每个 Agent 创建一个 Bot，复制每个 token。
- Token 放在 `channels.telegram.accounts.&lt;id&gt;.botToken`（默认账号可使用 `TELEGRAM_BOT_TOKEN` 环境变量）。

每个 Agent 一个 WhatsApp 号码

启动 Gateway 前先连接每个账号：

```bash
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz
```

`~/.openclaw/openclaw.json`（JSON5）：

```js
{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    ],
  },

  // 确定性路由：第一个匹配优先（最具体者排前面）。
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // 可选的 per-peer 覆盖（例如把特定群组路由到 work agent）。
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // 默认关闭：Agent 间的消息传递必须显式启用并加入 allowlist。
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // 可选覆盖。默认：~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // 可选覆盖。默认：~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}
```

常见模式 ​

WhatsApp 日常 + Telegram 深度工作

按渠道拆分：把 WhatsApp 路由到快速日用 Agent，Telegram 路由到 Opus Agent。

```json5
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}
```

注意：

- 如果某渠道有多个账号，在 Binding 里加上 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 想单独把某个 DM/群组路由到 Opus 而其余保持聊天 Agent 处理，添加一条 `match.peer` 的 Binding；peer 匹配永远优先于渠道级规则。

同一渠道，一个 peer 到 Opus

保持 WhatsApp 在快速 Agent 上，但把其中一个 DM 路由到 Opus：

```json5
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    {
      agentId: "opus",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}
```

Peer Binding 永远优先，所以把它们放在渠道级规则上面。

家庭 Agent 绑定到 WhatsApp 群组

把专用家庭 Agent 绑定到单个 WhatsApp 群组，使用 @提及 门控和更严格的工具策略：

```json5
{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: [
            "exec",
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}
```

注意：

- 工具 allow/deny 列表限制的是 **工具**，不是技能。如果某个技能需要运行二进制文件，确保 `exec` 已允许且该二进制存在于沙箱中。
- 如需更严格的门控，设置 `agents.list[].groupChat.mentionPatterns` 并保持渠道的群组 allowlist 启用状态。

Per-Agent 沙箱和工具配置 ​

每个 Agent 可以拥有独立的沙箱和工具限制：

js
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // 个人 Agent 不启用沙箱
        },
        // 无工具限制 - 所有工具可用
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // 总是启用沙箱
          scope: "agent",  // 每个 Agent 一个容器
          docker: {
            // 容器创建后可选的单次设置命令
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // 只允许 read
          deny: ["exec", "write", "edit", "apply_patch"],    // 拒绝其他
        },
      },
    ],
  },
}

INFO

setupCommand 位于 sandbox.docker 下，在容器创建时执行一次。当解析出的 scope 为 "shared" 时，per-agent 的 sandbox.docker.* 覆盖会被忽略。

好处：

  • 安全隔离：为不信任的 Agent 限制工具
  • 资源控制：对特定 Agent 启用沙箱，其他保持主机运行
  • 灵活策略：每个 Agent 可设置不同权限

INFO

tools.elevated 是全局且基于发送者的，不能 per-agent 配置。如果需要对每个 Agent 做边界限制，用 agents.list[].tools 拒绝 exec。如需群组定位，使用 agents.list[].groupChat.mentionPatterns，这样 @提及 可以准确映射到预期 Agent。

详细示例参考 Multi-agent sandbox and tools。

相关 ​

常见问题 ​

如何创建新 Agent？ ​

使用 openclaw agents add <agentId> 命令，例如 openclaw agents add work。该命令会创建包含 SOUL.md、AGENTS.md 和可选 USER.md 的工作区，以及独立的 agentDir 和会话存储。

多个 Agent 能用不同模型吗？ ​

可以。在每个 Agent 配置的 agents.list[].model 字段指定主模型。如果某个 Agent 未设置，将使用全局或默认模型。

如何限制 Agent 的工具权限？ ​

在 agents.list[].tools 中设置 allow 和 deny 列表。例如只允许 read 工具，拒绝 exec、write、edit、apply_patch。注意 tools.elevated 是全局设置，不支持 per-agent。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策