OpenClaw 多 Agent QQ Bot 配置完整指南

本文由OpenClaw QQBot生成

1. 概述

OpenClaw 是一个多 Agent AI 助手平台，支持：

多 Agent：同时运行多个独立人格的 AI 机器人
多 Channel：接入 QQ/Telegram/Discord/WhatsApp/Signal 等多种消息渠道
多 Account：同一渠道可配置多个账户（如多个 QQ Bot）
灵活路由：通过 Bindings 将不同渠道/账户/群组的消息路由到不同 Agent

本文档以 QQ Bot 为例，详述如何从零搭建多 Agent 多 Bot 体系。

2. 前置准备

2.1 安装 OpenClaw

npm install -g openclaw

2.2 注册 QQ 开放平台 Bot

访问 QQ 开放平台，扫码登录
创建 Bot 应用，获取 AppID 和 AppSecret
每个 Agent 需要独立的 QQ Bot 应用（独立的 AppID/AppSecret）

2.3 模型 Provider 配置

本文档使用自定义 Qwen Provider 示例：

{
  models: {
    mode: "merge",
    providers: {
      Qwen: {
        baseUrl: "https://your-api-endpoint/v1",
        apiKey: "sk-your-api-key",
        api: "openai-completions",
        models: [{
          id: "coder-model",
          name: "coder-model",
          api: "openai-completions",
          contextWindow: 128000,
          maxTokens: 8192,
        }],
      },
    },
  },
}

3. 核心概念

概念	说明
Agent	一个独立的 AI "大脑"，有自己的 workspace、session、persona
Workspace	Agent 的文件工作空间，包含 AGENTS.md、SOUL.md、USER.md 等
AgentDir	Agent 的状态目录，存放 auth-profiles、session store
Channel	消息渠道（QQ Bot、Telegram、Discord 等）
Account	同一渠道下的不同账户实例（如多个 QQ Bot）
Binding	路由规则，将 inbound 消息匹配到指定 Agent
Session	会话上下文，按 `agent:<agentId>:<channel>:<peer>` 隔离
Skill	注入系统提示的技能文件（SKILL.md），教 Agent 如何使用工具

4. 单 Bot 基础配置

最简单的 QQ Bot 配置（单 Agent）：

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
  agents: {
    defaults: {
      model: "Qwen/coder-model",
    },
  },
}

启动：

openclaw gateway start

添加渠道（交互式）：

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. 多 Bot 多 Agent 完整配置

5.1 架构示意

                    ┌──────────────────────────────────────┐
                    │          OpenClaw Gateway             │
                    │         (ws://127.0.0.1:18789)       │
                    │                                      │
  QQ Bot A (chief)  │   QQ Bot B (backend)                  │
  AppID: 1903755093 │   AppID: 1903806986                   │
        │           │         │                             │
  ┌─────┴─────┐     │   ┌─────┴─────┐                       │
  │ account:   │     │   │ account:  │                       │
  │  default   │     │   │  backend  │                       │
  └─────┬─────┘     │   └─────┬─────┘                       │
        │           │         │                             │
        ▼           │         ▼                             │
  ┌──────────┐      │   ┌──────────┐                        │
  │ binding  │      │   │ binding  │                        │
  │ → chief  │      │   │ →backend │                        │
  └────┬─────┘      │   └────┬─────┘                        │
       │            │        │                              │
       ▼            │        ▼                              │
  ┌──────────┐      │   ┌──────────┐                        │
  │  chief   │      │   │ backend  │                        │
  │ workspace │     │   │ workspace │                       │
  └──────────┘      │   └──────────┘                        │
                    │                                      │
  QQ Bot C (fe)     │   QQ Bot D (skills)                   │
  AppID: 1903806984 │   AppID: 1903806211                   │
        │           │         │                             │
  ┌─────┴─────┐     │   ┌─────┴─────┐                       │
  │ account:  │     │   │ account:  │                       │
  │ frontend  │     │   │  skills   │                       │
  └─────┬─────┘     │   └─────┬─────┘                       │
        ▼            │         ▼                              │
  ┌──────────┐      │   ┌──────────┐                        │
  │ binding  │      │   │ binding  │                        │
  │ →frontend│      │   │ →skills  │                        │
  └────┬─────┘      │   └────┬─────┘                        │
       │            │        │                              │
       ▼            │        ▼                              │
  ┌──────────┐      │   ┌──────────┐                        │
  │frontend  │      │   │  skills  │                        │
  │ workspace │     │   │ workspace │                       │
  └──────────┘      │   └──────────┘                        │
                    └──────────────────────────────────────┘

5.2 完整配置

{
  // ===== Agent 定义 =====
  agents: {
    defaults: {
      model: "Qwen/coder-model",
      workspace: "~/.openclaw/workspace",
    },
    list: [
      {
        id: "chief",
        name: "总助",
        default: true,
        workspace: "~/.openclaw/workspace/chief",
        agentDir: "~/.openclaw/agents/chief/agent",
        tools: { profile: "full" },
      },
      {
        id: "backend",
        name: "后端工程师",
        workspace: "~/.openclaw/workspace/backend",
        agentDir: "~/.openclaw/agents/backend/agent",
        tools: { profile: "full" },
      },
      {
        id: "frontend",
        name: "前端工程师",
        workspace: "~/.openclaw/workspace/frontend",
        agentDir: "~/.openclaw/agents/frontend/agent",
        tools: { profile: "full" },
      },
      {
        id: "skills",
        name: "平台工程师",
        workspace: "~/.openclaw/workspace/skills",
        agentDir: "~/.openclaw/agents/skills/agent",
        tools: { profile: "full" },
      },
    ],
  },

  // ===== QQ Bot 多账户 =====
  channels: {
    qqbot: {
      enabled: true,
      // 默认账户（chief）
      appId: "1903755093",
      clientSecret: "chief-secret-here",
      accounts: {
        backend: {
          enabled: true,
          appId: "1903806986",
          clientSecret: "backend-secret-here",
        },
        frontend: {
          enabled: true,
          appId: "1903806984",
          clientSecret: "frontend-secret-here",
        },
        skills: {
          enabled: true,
          appId: "1903806211",
          clientSecret: "skills-secret-here",
        },
      },
    },
  },

  // ===== 路由 Bindings =====
  bindings: [
    { agentId: "chief",    match: { channel: "qqbot", accountId: "default" } },
    { agentId: "backend",  match: { channel: "qqbot", accountId: "backend" } },
    { agentId: "frontend", match: { channel: "qqbot", accountId: "frontend" } },
    { agentId: "skills",   match: { channel: "qqbot", accountId: "skills" } },
  ],
}

6. 路由规则详解

6.1 匹配优先级（从高到低）

Peer 匹配 — 精确匹配 DM 用户 ID / 群组 ID / 频道 ID
ParentPeer 匹配 — 线程继承父级绑定
GuildId + Roles — Discord 角色路由
GuildId — Discord 服务器路由
TeamId — Slack 团队路由
AccountId — 渠道账户匹配
Channel 通配 — accountId: "*" 渠道级兜底
Fallback — 默认 Agent（default: true 或列表第一个）

6.2 绑定示例

bindings: [
  // 最高优先级：按用户路由（特定用户走特定 Agent）
  {
    agentId: "chief",
    match: {
      channel: "qqbot",
      peer: { kind: "direct", id: "C05F69920A0D6F25F889144170D405E9" },
    },
  },
  // 次优先级：按账户路由
  { agentId: "backend", match: { channel: "qqbot", accountId: "backend" } },
  // 最低优先级：渠道兜底
  { agentId: "chief", match: { channel: "qqbot" } },
]

6.3 重要规则

同优先级多条匹配时，配置中靠前的先匹配
多字段绑定为 AND 关系（所有条件都需满足）
省略 accountId 的绑定只匹配默认账户
使用 accountId: "*" 可匹配所有账户

7. QQ Bot 多账户配置

7.1 目标格式

格式	说明	示例
`qqbot:c2c:OPENID`	私聊（C2C）	`qqbot:c2c:C05F69920A0D6F25F889144170D405E9`
`qqbot:group:GROUP_OPENID`	群聊	`qqbot:group:xxx@group`
`qqbot:channel:CHANNEL_ID`	频道消息	`qqbot:channel:xxx`

7.2 OpenID 重要注意

每个 Bot 对同一用户的 OpenID 不同！
Bot A 收到的用户 OpenID 不能用于 Bot B 发消息。

因此每个 Agent 需要维护自己的 OpenID 映射：

chief 账户   → 用户 openid: C05F69920A0D6F25F889144170D405E9
backend 账户 → 用户 openid: 8D2E478C69CA1B37D66B5901FC912B97
frontend 账户 → 用户 openid: B3F0FCDE84C2DBEE7649EAAE9B202F0B
skills 账户  → 用户 openid: F5A41550DEE83CC03EF0988C5AC5BA2C

7.3 凭证配置方式

// 方式 1：明文（不推荐生产环境）
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_SECRET",
    },
  },
}

// 方式 2：文件引用
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/secret.txt",
    },
  },
}

// 方式 3：环境变量（仅默认账户）
// QQBOT_APP_ID=xxx QQBOT_CLIENT_SECRET=xxx

8. Agent 隔离与独立空间

8.1 每个 Agent 的独立路径

# chief Agent
workspace:  ~/.openclaw/workspace/chief/
agentDir:   ~/.openclaw/agents/chief/agent/
sessions:   ~/.openclaw/agents/chief/sessions/

# backend Agent
workspace:  ~/.openclaw/workspace/backend/
agentDir:   ~/.openclaw/agents/backend/agent/
sessions:   ~/.openclaw/agents/backend/sessions/

8.2 每个 Agent 工作空间文件

每个 Agent 工作空间根目录包含：

文件	用途
`AGENTS.md`	Agent 行为规范、角色定义、派单模板
`SOUL.md`	人格、语气、行为边界
`USER.md`	服务对象（老板）偏好与期望
`IDENTITY.md`	身份信息（名称、头衔、emoji）
`TOOLS.md`	本地工具配置（摄像头、SSH 等）
`MEMORY.md`	长期记忆（每次 DM 启动加载）
`BOOTSTRAP.md`	启动引导上下文（可选）
`HEARTBEAT.md`	心跳检查清单

8.3 文件分类管理

workspace/<agent>/
├── AGENTS.md
├── SOUL.md
├── USER.md
├── IDENTITY.md
├── MEMORY.md
├── memory/
│   └── YYYY-MM-DD/
│       └── YYYY-MM-DD.md    # 每日记忆日志
├── skills/                   # 技能相关文件
├── scripts/                  # 脚本和自动化
├── configs/                  # 配置文件
├── temp/                     # 临时文件
└── docs/                     # 文档文件

9. 消息发送与 OpenID 映射

9.1 通过 message 工具发消息

Agent 内部使用 message 工具：

{
  "action": "send",
  "channel": "qqbot",
  "to": "qqbot:c2c:<该Bot账户对应的用户openid>",
  "message": "你好，这是来自 backend bot 的消息"
}

9.2 通过 CLI 派发消息

由于 gateway WebSocket 连接存在 pairing 限制，推荐使用 CLI 嵌入式模式：

openclaw agent \
  --agent <agentId> \
  --message "<任务描述，要求用 message 工具发送到指定 QQ>" \
  --deliver --channel qqbot \
  --reply-to "qqbot:c2c:<该agent对应的用户openid>" \
  --reply-account <agentId>

9.3 实际示例

让 backend bot 发自我介绍：

openclaw agent \
  --agent backend \
  --message "用 message 工具发自我介绍。action=send, channel=qqbot, to=qqbot:c2c:8D2E478C69CA1B37D66B5901FC912B97。说明你是后端bot。" \
  --deliver --channel qqbot \
  --reply-to "qqbot:c2c:8D2E478C69CA1B37D66B5901FC912B97" \
  --reply-account backend

10. Agent 主动发消息

10.1 Agent 内置 message 工具

在会话中，Agent 可直接调用：

message(action=send, channel=qqbot, to=qqbot:c2c:<openid>, message="内容")

10.2 跨 Agent 通信

{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["chief", "frontend", "backend", "skills"],
    },
    sessions: {
      visibility: "all",  // 允许跨 Agent 会话访问
    },
  },
}

可用工具：

sessions_list — 列出可见会话
sessions_history — 获取会话历史（已过滤）
sessions_send — 向其他会话发送消息
sessions_spawn — 派生子 Agent 任务
subagents — 管理子 Agent

11. 工具与权限控制

11.1 工具 Profile

Profile	包含工具
`full`	无限制
`coding`	文件/运行时/Web/会话/记忆/媒体
`messaging`	仅消息发送 + 会话列表/历史
`minimal`	仅 session_status

11.2 工具组

组	工具
`group:fs`	read, write, edit, apply_patch
`group:runtime`	exec, process, code_execution
`group:web`	web_search, web_fetch
`group:sessions`	sessions_list/history/send/spawn, subagents
`group:memory`	memory_search, memory_get
`group:messaging`	message
`group:ui`	browser, canvas
`group:media`	image, image_generate, music_generate, video_generate, tts

11.3 按 Agent 限制工具

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          allow: ["exec", "read", "sessions_list", "sessions_history", "sessions_send", "session_status"],
          deny: ["write", "edit", "browser", "canvas"],
        },
      },
    ],
  },
}

12. 记忆系统配置

12.1 记忆架构

MEMORY.md           ← 长期记忆，每次 DM 启动加载
memory/
└── YYYY-MM-DD.md   ← 每日日志，今天+昨天自动加载

12.2 记忆工具

memory_search — 语义搜索（需要配置 embedding provider）
memory_get — 读取指定记忆文件

12.3 Dreaming（实验性）

后台记忆巩固机制，自动将短期记忆提升为长期记忆：

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: { enabled: true },
        },
      },
    },
  },
}

13. 文件管理规范

13.1 分类规则

分类	路径	用途
记忆文件	`memory/YYYY-MM-DD/YYYY-MM-DD.md`	每日记忆日志
记忆附件	`memory/YYYY-MM-DD/`	当日相关特殊主题文件
技能文件	`skills/`	技能相关文件
脚本文件	`scripts/`	脚本和自动化文件
配置文件	`configs/`	配置文件
临时文件	`temp/`	临时文件
文档文件	`docs/`	文档文件

13.2 执行规则

新文件必须归入对应分类目录
每日启动时创建/写入当日记忆日志
重要决策、任务状态、阻塞点写入当日记忆

14. CLI 常用命令

14.1 Gateway 管理

openclaw gateway status    # 查看状态
openclaw gateway start     # 启动
openclaw gateway stop      # 停止
openclaw gateway restart   # 重启

14.2 Agent 管理

openclaw agents list --bindings          # 列出所有 Agent 及绑定
openclaw agents add <id>                 # 添加新 Agent
openclaw agent --agent <id> --message "任务" --deliver --channel qqbot

14.3 Channel 管理

openclaw channels add --channel qqbot --token "AppID:AppSecret"
openclaw channels add --channel qqbot --account <name> --token "..."
openclaw channels status --probe         # 探测渠道状态

14.4 配置管理

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.model.primary "Qwen/coder-model"
openclaw configure                     # 交互式配置向导
openclaw onboard                       # 完整初始化向导

14.5 诊断

openclaw doctor                        # 健康检查
openclaw doctor --non-interactive      # 非交互模式
openclaw doctor --fix                  # 自动修复
openclaw status                        # 运行状态
openclaw logs                          # 查看日志

14.6 记忆

openclaw memory status                 # 记忆索引状态
openclaw memory search "查询内容"       # 语义搜索
openclaw memory index --force          # 重建索引

14.7 Cron

openclaw cron list                     # 列出定时任务
openclaw cron add --every "30m" --message "提醒"

15. 安全机制

15.1 Gateway 认证

{
  gateway: {
    auth: {
      mode: "token",        // token | none | trusted-proxy
      token: "your-secret-token",
    },
    bind: "loopback",       // loopback | 0.0.0.0
    port: 18789,
  },
}

15.2 DM 访问控制

{
  channels: {
    qqbot: {
      dmPolicy: "allowlist",    // pairing | allowlist | open | disabled
      allowFrom: ["openid1", "openid2"],
    },
  },
}

15.3 沙箱隔离

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",   // off | non-main | all
        scope: "agent",     // session | agent | shared
      },
    },
  },
}

15.4 Exec 审批

{
  tools: {
    exec: {
      ask: "on-miss",   // off | on-miss | always
      security: "allowlist",  // deny | allowlist | full
    },
  },
}

16. 故障排查

16.1 常见问题

问题	原因	解决方案
Bot 回复"去了火星"	凭证未配置或 Gateway 未启动	检查 appId/clientSecret，启动 Gateway
收不到消息	AppID/AppSecret 不正确	到 QQ 开放平台核对
主动消息发不出	用户近期未与 Bot 交互	QQ 平台限制，需用户先发消息
Gateway pairing required	WebSocket 认证失败	清理锁文件，确保 token 正确
Agent 上下文溢出	内容过大超过模型限制	分段处理，或写入文件

16.2 诊断流程

# 1. 检查整体状态
openclaw status

# 2. 运行诊断
openclaw doctor

# 3. 查看 Agent 绑定
openclaw agents list --bindings

# 4. 探测渠道连通性
openclaw channels status --probe

# 5. 查看日志
openclaw logs

# 6. 检查配置
openclaw config get

16.3 QQ 连通性测试

curl -v https://api.q.qq.com/api/v3

16.4 锁文件清理

rm -f ~/.openclaw/agents/*/sessions/*.lock

17. 完整配置实例

以下是基于实际运行环境的完整配置参考：

{
  // ===== 模型配置 =====
  models: {
    mode: "merge",
    providers: {
      Qwen: {
        baseUrl: "https://your-endpoint/v1",
        apiKey: "sk-your-key",
        api: "openai-completions",
        models: [{
          id: "coder-model",
          name: "coder-model",
          contextWindow: 128000,
          maxTokens: 8192,
        }],
      },
    },
  },

  // ===== Gateway =====
  gateway: {
    mode: "local",
    auth: { mode: "token", token: "your-token" },
    port: 18789,
    bind: "loopback",
  },

  // ===== Agent 定义 =====
  agents: {
    defaults: {
      model: "Qwen/coder-model",
      workspace: "~/.openclaw/workspace",
      subagents: {
        allowAgents: ["backend", "frontend", "skills"],
      },
    },
    list: [
      {
        id: "chief", name: "总助", default: true,
        workspace: "~/.openclaw/workspace/chief",
        agentDir: "~/.openclaw/agents/chief/agent",
        tools: { profile: "full" },
      },
      {
        id: "backend", name: "后端工程师",
        workspace: "~/.openclaw/workspace/backend",
        agentDir: "~/.openclaw/agents/backend/agent",
        tools: { profile: "full" },
      },
      {
        id: "frontend", name: "前端工程师",
        workspace: "~/.openclaw/workspace/frontend",
        agentDir: "~/.openclaw/agents/frontend/agent",
        tools: { profile: "full" },
      },
      {
        id: "skills", name: "平台工程师",
        workspace: "~/.openclaw/workspace/skills",
        agentDir: "~/.openclaw/agents/skills/agent",
        tools: { profile: "full" },
      },
    ],
  },

  // ===== QQ Bot 多账户 =====
  channels: {
    qqbot: {
      enabled: true,
      appId: "chief-app-id",
      clientSecret: "chief-secret",
      accounts: {
        backend: {
          enabled: true,
          appId: "backend-app-id",
          clientSecret: "backend-secret",
        },
        frontend: {
          enabled: true,
          appId: "frontend-app-id",
          clientSecret: "frontend-secret",
        },
        skills: {
          enabled: true,
          appId: "skills-app-id",
          clientSecret: "skills-secret",
        },
      },
    },
  },

  // ===== 路由绑定 =====
  bindings: [
    { agentId: "chief",    match: { channel: "qqbot", accountId: "default" } },
    { agentId: "backend",  match: { channel: "qqbot", accountId: "backend" } },
    { agentId: "frontend", match: { channel: "qqbot", accountId: "frontend" } },
    { agentId: "skills",   match: { channel: "qqbot", accountId: "skills" } },
  ],

  // ===== 会话 =====
  session: {
    dmScope: "per-channel-peer",
  },

  // ===== 工具 =====
  tools: {
    profile: "coding",
    agentToAgent: {
      enabled: true,
      allow: ["chief", "frontend", "backend", "skills"],
    },
    sessions: { visibility: "all" },
  },

  // ===== 定时任务 =====
  cron: {
    enabled: true,
  },

  // ===== 插件 =====
  plugins: {
    entries: {
      "qwen": { enabled: true },
      "memory-core": {
        config: { dreaming: { enabled: true } },
      },
    },
  },
}

附录：关键注意事项

OpenID 隔离：每个 QQ Bot 账户对同一用户的 OpenID 不同，发消息时必须使用对应账户的 OpenID
replay-account：CLI 派单时 --reply-account 决定用哪个 Bot 账号发送
session 隔离：不同 Agent 的 session 完全隔离，不共享对话历史（除非显式启用 sessions.visibility: "all" 并通过 sessions_history 读取）
Gateway 热重载：大部分配置修改无需重启，Gateway 会自动检测并应用
配置验证：OpenClaw 对配置做严格校验，未知字段会导致启动失败
Agent 互调：需同时开启 tools.agentToAgent.enabled 和 tools.sessions.visibility: "all"
消息长度限制：QQ 平台对单条消息有长度限制，超长内容建议使用文件发送（<qqmedia> 标签）