OpenClaw 多 Agent 架构详解：原理、构建与使用

📅 2026-03-20 👤 Elaine 👁️ 11 次阅读 ⏱️ 6 分钟阅读 ❤️ 0 赞

OpenClaw AI Agent

🤖 OpenClaw 多 Agent 架构详解

    <p class="subtitle">原理、构建与使用 | 2026-03-20</p>

    <div class="info">
        <div class="info-title">📋 目录</div>
        <ul>
            <li><a href="#什么是-agent" style="color:#60a5fa;">什么是 Agent？</a></li>
            <li><a href="#多agent原理" style="color:#60a5fa;">多 Agent 原理</a></li>
            <li><a href="#核心概念" style="color:#60a5fa;">核心概念</a></li>
            <li><a href="#快速开始" style="color:#60a5fa;">快速开始</a></li>
            <li><a href="#构建方法" style="color:#60a5fa;">多 Agent 构建方法</a></li>
            <li><a href="#使用场景" style="color:#60a5fa;">使用场景示例</a></li>
            <li><a href="#路由机制" style="color:#60a5fa;">消息路由机制</a></li>
            <li><a href="#安全和隔离" style="color:#60a5fa;">安全与隔离</a></li>
            <li><a href="#总结" style="color:#60a5fa;">总结</a></li>
        </ul>
    </div>

    <h2 id="什么是-agent">🤔 什么是 Agent？</h2>

    <div class="section">
        <p><strong>Agent（智能体）</strong>是 OpenClaw 中的核心概念，每个 Agent 是一个<strong>完整隔离的"大脑"</strong>，拥有自己的：</p>
        <ul>
            <li><strong>Workspace</strong>：独立的工作空间，包含文件、AGENTS.md、SOUL.md、USER.md</li>
            <li><strong>Agent Dir</strong>：认证配置、模型注册表等状态目录</li>
            <li><strong>Session Store</strong>：聊天历史和路由状态</li>
            <li><strong>Auth Profiles</strong>：独立的认证信息</li>
        </ul>
    </div>

    <div class="info">
        <div class="info-title">💡 简单理解</div>
        <p>一个 Agent = 一个独立的 AI 人格 + 独立的工作记忆 + 独立的工具权限。你可以把它想象成<strong>一个独立的 AI 助手</strong>。</p>
    </div>

    <h2 id="多agent原理">🔬 多 Agent 原理</h2>

    <div class="section">
        <p>OpenClaw 支持在<strong>一个 Gateway 进程</strong>中运行多个 Agent，通过<strong>Bindings（绑定）</strong>将不同来源的消息路由到不同的 Agent。</p>
    </div>

    <div class="section">
        <h3>架构图</h3>
        <pre><code>                    ┌─────────────┐
                │   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 │
└─────────┘ └─────────┘ └─────────┘

    <h2 id="核心概念">📚 核心概念</h2>

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

    <h2 id="快速开始">🚀 快速开始</h2>

    <div class="section">
        <h3>Step 1：创建新的 Agent</h3>
        <pre><code># 使用命令行创建 Agent

openclaw agents add coding

查看所有 Agent

openclaw agents list

查看 Agent 绑定情况

openclaw agents list --bindings

    <div class="section">
        <h3>Step 2：配置 Agent 信息</h3>
        <p>创建 Agent 后，需要在配置文件中设置每个 Agent 的属性。</p>
        <pre><code># 配置文件 ~/.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"
}
]
}
}

    <h2 id="构建方法">🔧 多 Agent 构建方法</h2>

    <div class="section">
        <h3>基础配置结构</h3>
        <pre><code>{

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

    <div class="section">
        <h3>示例 1：按频道路由</h3>
        <p>WhatsApp 路由到一个 Agent，Telegram 路由到另一个 Agent。</p>
        <pre><code>{

"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" } }
]
}

    <div class="section">
        <h3>示例 2：同频道不同账号</h3>
        <p>同一个 Discord/Telegram，但不同的 Bot Token 绑定到不同 Agent。</p>
        <pre><code>{

"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" }
}
}
}
}

    <div class="section">
        <h3>示例 3：按人来路由（DM）</h3>
        <p>同一个 WhatsApp，但不同的人发给不同的 Agent。</p>
        <pre><code>{

"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" }
}
}
]
}

    <div class="section">
        <h3>示例 4：按群组路由</h3>
        <p>家庭群路由到家庭 Agent，技术群路由到技术 Agent。</p>
        <pre><code>{

"agents": {
"list": [
{ "id": "family", "workspace": "~/.openclaw/workspace-family" },
{ "id": "tech", "workspace": "~/.openclaw/workspace-tech" }
]
},
"bindings": [
{
"agentId": "family",
"match": {
"channel": "whatsapp",
"peer": { "kind": "group", "id": "[email protected]" }
}
},
{
"agentId": "tech",
"match": {
"channel": "whatsapp",
"peer": { "kind": "group", "id": "[email protected]" }
}
}
]
}

    <h2 id="使用场景">💡 使用场景示例</h2>

    <div class="section">
        <h3>场景 1：个人 + 工作分离</h3>
        <p>日常生活用轻量模型，工作用高级模型。</p>
        <pre><code>{

"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 配置 / }
}
}
}
}

    <div class="section">
        <h3>场景 2：不同 Bot 服务不同群组</h3>
        <pre><code>{

"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" }
}
}
}
}

    <div class="section">
        <h3>场景 3：家庭共享</h3>
        <p>家庭群用一个 Bot，限制它的工具权限保证安全。</p>
        <pre><code>{

"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": "[email protected]" }
}
}
]
}

    <h2 id="路由机制">🔀 消息路由机制</h2>

    <div class="section">
        <h3>路由优先级（从高到低）</h3>
        <ol>
            <li><strong>peer 匹配</strong>：精确的 DM/群组/频道 ID</li>
            <li><strong>parentPeer 匹配</strong>：线程继承</li>
            <li><strong>guildId + roles</strong>：Discord 角色路由</li>
            <li><strong>guildId</strong>：Discord 服务器</li>
            <li><strong>teamId</strong>：Slack</li>
            <li><strong>accountId 匹配</strong>：频道账号</li>
            <li><strong>channel 匹配</strong>：频道级别</li>
            <li><strong>fallback</strong>：默认 Agent</li>
        </ol>
    </div>

    <div class="section">
        <h3>路由规则说明</h3>
        <ul>
            <li>匹配是<strong>确定性的</strong>，最具体的匹配优先</li>
            <li>同一级别多个匹配时，配置顺序决定（第一个胜出）</li>
            <li>多个条件同时满足时（peer + guildId），需要<strong>同时满足</strong>（AND 语义）</li>
        </ul>
    </div>

    <div class="info">
        <div class="info-title">💡 路由示例</div>
        <pre><code># peer 绑定优先于 channel 绑定

bindings: [
{ "agentId": "opus", "match": { "channel": "whatsapp", "peer": { "id": "+15551234567" } } },
{ "agentId": "chat", "match": { "channel": "whatsapp" } } // 默认
]

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

    </div>

    <h2 id="安全和隔离">🔒 安全与隔离</h2>

    <div class="section">
        <h3>Per-Agent 沙箱和工具限制</h3>
        <p>从 v2026.1.6 开始，每个 Agent 可以有独立的沙箱和工具限制：</p>
        <pre><code>{

"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"]
}
}
]
}
}

    <div class="section">
        <h3>认证隔离</h3>
        <ul>
            <li>每个 Agent 的认证信息是<strong>独立的</strong></li>
            <li>Auth Profiles 存储在 <code>~/.openclaw/agents/&lt;agentId&gt;/agent/auth-profiles.json</code></li>
            <li>不同 Agent 之间不会共享认证信息</li>
        </ul>
    </div>

    <div class="section">
        <h3>会话隔离</h3>
        <ul>
            <li>每个 Agent 有独立的会话存储</li>
            <li>会话 Key 格式：<code>agent:&lt;agentId&gt;:&lt;sessionKey&gt;</code></li>
            <li>不同 Agent 的会话完全隔离</li>
        </ul>
    </div>

    <div class="warning">
        <div class="warning-title">⚠️ 注意事项</div>
        <ul>
            <li>不要在不同的 Agent 之间共享 <code>agentDir</code>（会导致认证/会话冲突）</li>
            <li>如果想共享认证，手动复制 <code>auth-profiles.json</code></li>
            <li>工具限制是<strong>工具级别</strong>的，不是 Skill 级别</li>
        </ul>
    </div>

    <h2 id="总结">📝 总结</h2>

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

    <div class="section">
        <h3>快速命令回顾</h3>
        <pre><code># 创建新 Agent

openclaw agents add <name>

查看 Agent 列表

openclaw agents list

查看绑定情况

openclaw agents list --bindings

重启 Gateway

openclaw gateway restart

检查频道状态

openclaw channels status --probe