Agent（智能体）是 OpenClaw 中的核心概念，每个 Agent 是一个完整隔离的"大脑"，拥有自己的：

Workspace：独立的工作空间，包含文件、AGENTS.md、SOUL.md、USER.md
Agent Dir：认证配置、模型注册表等状态目录
Session Store：聊天历史和路由状态
Auth Profiles：独立的认证信息

🔬 多 Agent 原理

OpenClaw 支持在一个 Gateway 进程中运行多个 Agent，通过Bindings（绑定）将不同来源的消息路由到不同的 Agent。

架构图

                    ┌─────────────┐
                    │   Gateway   │
                    │   Process   │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
   ┌─────────┐       ┌─────────┐       ┌─────────┐
   │ Agent  │       │ Agent  │       │ Agent  │
   │  main  │       │ coding │       │ alerts │
   │ (默认) │       │ (编程) │       │ (告警) │
   └────┬────┘       └────┬────┘       └────┬────┘
        │                  │                  │
   Workspace           Workspace           Workspace
   ~/.openclaw/       ~/.openclaw/      ~/.openclaw/
   workspace-main     workspace-coding   workspace-alerts

                    ┌─────────────┐
                    │  Bindings   │
                    │   Router    │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
   ┌─────────┐       ┌─────────┐       ┌─────────┐
   │ Telegram │       │ Discord │       │ DingTalk│
   │ Bot 1   │       │ Bot 2   │       │ Channel │
   └─────────┘       └─────────┘       └─────────┘

📚 核心概念

🚀 快速开始

概念	说明
`agentId`	Agent 的唯一标识，如 "main"、"coding"、"alerts"
`accountId`	频道账号实例，如 WhatsApp 的 "personal" 或 "biz"
`binding`	路由规则，将消息绑定到特定 Agent
`workspace`	Agent 的工作空间目录
`agentDir`	Agent 的状态目录（认证、模型配置）

Step 1：创建新的 Agent

# 使用命令行创建 Agent
openclaw agents add coding

# 查看所有 Agent
openclaw agents list

# 查看 Agent 绑定情况
openclaw agents list --bindings

Step 2：配置 Agent 信息

创建 Agent 后，需要在配置文件中设置每个 Agent 的属性。

# 配置文件 ~/.openclaw/openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "main",           // Agent ID
        "name": "主助手",         // Agent 名称
        "workspace": "~/.openclaw/workspace-main",
        "agentDir": "~/.openclaw/agents/main/agent"
      },
      {
        "id": "coding",
        "name": "编程助手",
        "workspace": "~/.openclaw/workspace-coding",
        "agentDir": "~/.openclaw/agents/coding/agent"
      }
    ]
  }
}

🔧 多 Agent 构建方法

基础配置结构

{
  "agents": {
    "list": [
      // 在这里定义所有 Agent
    ]
  },
  "bindings": [
    // 在这里定义路由规则
  ],
  "channels": {
    // 在这里配置频道账号
  }
}

示例 1：按频道路由

WhatsApp 路由到一个 Agent，Telegram 路由到另一个 Agent。

{
  "agents": {
    "list": [
      {
        "id": "chat",
        "name": "日常助手",
        "workspace": "~/.openclaw/workspace-chat"
      },
      {
        "id": "work",
        "name": "工作助手",
        "workspace": "~/.openclaw/workspace-work"
      }
    ]
  },
  "bindings": [
    { "agentId": "chat", "match": { "channel": "whatsapp" } },
    { "agentId": "work", "match": { "channel": "telegram" } }
  ]
}

示例 2：同频道不同账号

同一个 Discord/Telegram，但不同的 Bot Token 绑定到不同 Agent。

{
  "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": {
      "accounts": {
        "default": { "token": "BOT_TOKEN_MAIN" },
        "coding": { "token": "BOT_TOKEN_CODING" }
      }
    }
  }
}

示例 3：按人来路由（DM）

同一个 WhatsApp，但不同的人发给不同的 Agent。

{
  "agents": {
    "list": [
      { "id": "alice", "workspace": "~/.openclaw/workspace-alice" },
      { "id": "bob", "workspace": "~/.openclaw/workspace-bob" }
    ]
  },
  "bindings": [
    {
      "agentId": "alice",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+8613812345678" }
      }
    },
    {
      "agentId": "bob",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+8613987654321" }
      }
    }
  ]
}

示例 4：按群组路由

家庭群路由到家庭 Agent，技术群路由到技术 Agent。

{
  "agents": {
    "list": [
      { "id": "family", "workspace": "~/.openclaw/workspace-family" },
      { "id": "tech", "workspace": "~/.openclaw/workspace-tech" }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "group", "id": "family_group_id@g.us" }
      }
    },
    {
      "agentId": "tech",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "group", "id": "tech_group_id@g.us" }
      }
    }
  ]
}

💡 使用场景示例

场景 1：个人 + 工作分离

日常生活用轻量模型，工作用高级模型。

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "name": "个人助手",
        "model": { "primary": "minimax-portal/MiniMax-M2.5" },
        "workspace": "~/.openclaw/workspace-personal"
      },
      {
        "id": "work",
        "name": "工作助手",
        "model": { "primary": "minimax-portal/MiniMax-M2.7" },
        "workspace": "~/.openclaw/workspace-work"
      }
    ]
  },
  "bindings": [
    { "agentId": "personal", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "whatsapp", "accountId": "work" } }
  ],
  "channels": {
    "whatsapp": {
      "accounts": {
        "personal": { /* 个人 WhatsApp 配置 */ },
        "work": { /* 工作 WhatsApp 配置 */ }
      }
    }
  }
}

场景 2：不同 Bot 服务不同群组

{
  "agents": {
    "list": [
      { "id": "general", "workspace": "~/.openclaw/workspace-general" },
      { "id": "coding", "workspace": "~/.openclaw/workspace-coding" },
      { "id": "alerts", "workspace": "~/.openclaw/workspace-alerts" }
    ]
  },
  "bindings": [
    { "agentId": "general", "match": { "channel": "discord", "accountId": "default" } },
    { "agentId": "coding", "match": { "channel": "discord", "accountId": "coding-bot" } },
    { "agentId": "alerts", "match": { "channel": "discord", "accountId": "alerts-bot" } }
  ],
  "channels": {
    "discord": {
      "accounts": {
        "default": { "token": "GENERAL_BOT_TOKEN" },
        "coding-bot": { "token": "CODING_BOT_TOKEN" },
        "alerts-bot": { "token": "ALERTS_BOT_TOKEN" }
      }
    }
  }
}

场景 3：家庭共享

家庭群用一个 Bot，限制它的工具权限保证安全。

{
  "agents": {
    "list": [
      {
        "id": "family",
        "name": "家庭助手",
        "workspace": "~/.openclaw/workspace-family",
        "identity": { "name": "家庭 Bot" },
        "groupChat": {
          "mentionPatterns": ["@家庭", "@family"]
        },
        "tools": {
          "allow": ["read", "exec", "sessions_list", "sessions_history"],
          "deny": ["write", "edit", "apply_patch", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "group", "id": "family_group_id@g.us" }
      }
    }
  ]
}

🔀 消息路由机制

路由优先级（从高到低）

peer 匹配：精确的 DM/群组/频道 ID
parentPeer 匹配：线程继承
guildId + roles：Discord 角色路由
guildId：Discord 服务器
teamId：Slack
accountId 匹配：频道账号
channel 匹配：频道级别
fallback：默认 Agent

路由规则说明

匹配是确定性的，最具体的匹配优先
同一级别多个匹配时，配置顺序决定（第一个胜出）
多个条件同时满足时（peer + guildId），需要同时满足（AND 语义）

💡 路由示例

# peer 绑定优先于 channel 绑定
bindings: [
  { "agentId": "opus", "match": { "channel": "whatsapp", "peer": { "id": "+15551234567" } } },
  { "agentId": "chat", "match": { "channel": "whatsapp" } }  // 默认
]

# 结果：发给 +15551234567 的消息路由到 "opus"，其他 WhatsApp 消息路由到 "chat"

🔒 安全与隔离

Per-Agent 沙箱和工具限制

从 v2026.1.6 开始，每个 Agent 可以有独立的沙箱和工具限制：

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" },  // 不沙箱
        "tools": { "allow": ["*"] }      // 所有工具可用
      },
      {
        "id": "untrusted",
        "workspace": "~/.openclaw/workspace-untrusted",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read", "sessions_list"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

认证隔离

每个 Agent 的认证信息是独立的
Auth Profiles 存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
不同 Agent 之间不会共享认证信息

会话隔离

每个 Agent 有独立的会话存储
会话 Key 格式：agent:<agentId>:<sessionKey>
不同 Agent 的会话完全隔离

⚠️ 注意事项

不要在不同的 Agent 之间共享 agentDir（会导致认证/会话冲突）
如果想共享认证，手动复制 auth-profiles.json
工具限制是工具级别的，不是 Skill 级别

📝 总结

✅ 多 Agent 优势

人格分离：工作/生活用不同人格，互不干扰
资源优化：不同 Agent 用不同模型，节省成本
安全隔离：敏感操作在沙箱中运行
团队共享：多人共用一个 Gateway 服务器
专业分工：编程助手、告警助手等各司其职

快速命令回顾

# 创建新 Agent
openclaw agents add <name>

# 查看 Agent 列表
openclaw agents list

# 查看绑定情况
openclaw agents list --bindings

# 重启 Gateway
openclaw gateway restart

# 检查频道状态
openclaw channels status --probe

🤖 OpenClaw 多 Agent 架构详解

🤔 什么是 Agent？