多Agent接入多企业微信机器人 Skill (v1.0)

在同一个 OpenClaw 实例中，多个 Agent 各自绑定不同的企业微信 Bot，独立接收和发送消息。每个 Agent 可拥有独立的人设、模型和工作空间，实现角色分工与资源隔离。

架构原理

企微用户 ──→ Bot A ──→ WeCom Plugin ──→ binding match ──→ Agent A (人设A + 模型A)
企微用户 ──→ Bot B ──→ WeCom Plugin ──→ binding match ──→ Agent B (人设B + 模型B)
企微用户 ──→ Bot C ──→ WeCom Plugin ──→ binding match ──→ Agent C (人设C + 模型C)

关键依赖：
1. WeCom Plugin (@wecom/wecom-openclaw-plugin) — 提供多账号 + bindings 支持
2. openclaw.json — 配置 channels.wecom.accounts（多Bot账号）和 bindings（Agent路由绑定）
3. 每个 Agent — 在 agents.list 中独立定义，各自有独立的 workspace/SOUL/模型配置

人设隔离设计

每个 Agent 通过独立 workspace 实现物理级别的人设隔离：

~/.openclaw/
├── workspace/                 → Agent A
│   ├── SOUL.md                ── 角色定义（你是谁）
│   ├── USER.md                ── 用户画像（为谁工作）
│   ├── TOOLS.md               ── 工具偏好
│   └── AGENTS.md              ── 行为规则
│
├── workspace-b/               → Agent B
│   ├── SOUL.md                ── 完全不同的角色
│   ├── USER.md
│   └── ...
│
└── workspace-c/               → Agent C
    └── ...

人设配置要点

模型独立配置

每个 Agent 可以在其 agent/models.json 中指定专属模型，不依赖全局配置。

配置文件层级

~/.openclaw/agents/<agent-id>/agent/models.json

配置示例

{
  "providers": {
    "openai": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "***",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "contextWindow": 128000,
          "maxTokens": 4096
        }
      ]
    },
    "deepseek": {
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "***",
      "api": "openai-completions",
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash"
        }
      ]
    }
  }
}

模型隔离的最佳实践

场景 1：各角色用不同模型
- 主 Agent 用 GPT-4o（综合能力强）
- 财务分析 Agent 用 DeepSeek（成本低、数学好）
- 客服 Agent 用 Claude Haiku（速度快、便宜）

场景 2：不同模型提供方
- 财务 Agent 用自建推理服务器（数据不出域）
- 运营 Agent 用公有云模型

场景 3：模型继承
- 如果某个 Agent 没有 models.json，会自动继承全局配置的 models.providers
- 在 global defaults 中设置 model.primary 作为兜底

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-v4-flash"
      }
    }
  }
}

模型策略配置

在 Agent 的 agents.list 中可以指定默认模型：

{
  "agents": {
    "list": [
      {
        "id": "my-agent",
        "name": "我的Agent",
        "model": {
          "primary": "gpt-4o"
        }
      }
    ]
  }
}

快速配置指南

如果尚未配置多账号

1. 在 企业微信后台 创建多个智能体 Bot
2. 记录每个 Bot 的 BotID 和 Secret
3. 执行以下步骤完成配置

步骤 1：添加企微 Bot 账号

# 交互式添加（推荐）
openclaw channels add

# 或 CLI 直接配置
openclaw config set channels.wecom.accounts.<accountId>.botId <BOT_ID>
openclaw config set channels.wecom.accounts.<accountId>.secret <BOT_SECRET>
openclaw config set channels.wecom.accounts.<accountId>.name "显示名称"
openclaw config set channels.wecom.accounts.<accountId>.dmPolicy "open"

步骤 2：创建设置 Agent

在 openclaw.json 的 agents.list 中定义 Agent（已有则跳过）：

{
  "agents": {
    "list": [
      {
        "id": "my-new-agent",
        "name": "我的新Agent",
        "workspace": "~/.openclaw/workspace-my-new-agent"
      }
    ]
  }
}

步骤 3：建立绑定关系

将 Bot 账号绑定到对应 Agent：

openclaw config set bindings '[{"agentId":"my-new-agent","match":{"channel":"wecom","accountId":"my-new-bot-account"}}]'

> ⚠️ 此命令会覆盖所有 bindings。如需追加，先读取现有 bindings 再合并。

合并方式：

# 读取当前 bindings → 追加新条目 → 写回
openclaw config get bindings
# 然后在结果数组中追加你的新绑定
openclaw config set bindings '<完整数组>'

步骤 4：重启 Gateway

openclaw gateway restart

步骤 5：验证

向对应 Bot 发送一条消息，确认消息被路由到正确的 Agent。

新 Agent 创建清单

当你需要为团队新增一个角色时，按以下步骤：

1️⃣ 在企业微信后台创建 Bot

1. 登录 企业微信后台
2. 进入「智能体」→「创建智能体」
3. 设置 Bot 名称、头像、描述
4. 发布后获取 BotID 和 Secret
5. 将 Bot 拉入需要工作的群聊

2️⃣ 在 OpenClaw 中创建 Agent

# 创建 Agent 工作目录
mkdir -p ~/.openclaw/workspace-<agent-id>

# 创建基础人设文件
cat > ~/.openclaw/workspace-<agent-id>/SOUL.md << 'EOF'
# SOUL.md - 你是谁

[在这里定义 Agent 的人设、语气、行为准则]

- **角色**: 客服助理
- **语气**: 热情专业
- **原则**: 首问负责制
EOF

cat > ~/.openclaw/workspace-<agent-id>/USER.md << 'EOF'
# USER.md - 你的服务对象

[描述 Agent 为谁服务、服务场景]
EOF

# 可选：配置专属模型
mkdir -p ~/.openclaw/agents/<agent-id>/agent
cat > ~/.openclaw/agents/<agent-id>/agent/models.json << 'EOF'
{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "***",
      "api": "openai-completions",
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash"
        }
      ]
    }
  }
}
EOF

# 添加 Agent 到配置文件
openclaw config set agents.list[#] '{
  "id": "<agent-id>",
  "name": "<显示名称>",
  "workspace": "~/.openclaw/workspace-<agent-id>"
}'

3️⃣ 添加 Bot 账号

openclaw config set channels.wecom.accounts.<accountId>.botId <BOT_ID>
openclaw config set channels.wecom.accounts.<accountId>.secret <BOT_SECRET>
openclaw config set channels.wecom.accounts.<accountId>.name "<显示名称>"
openclaw config set channels.wecom.accounts.<accountId>.dmPolicy "open"
openclaw config set channels.wecom.accounts.<accountId>.welcomeText "你好！我是<显示名称>"
openclaw config set channels.wecom.accounts.<accountId>.streamPlaceholderContent "正在思考..."

4️⃣ 建立绑定

# 先读取当前 bindings
BINDINGS=$(openclaw config get bindings --json 2>/dev/null || echo "[]")

# 用 python 合并追加
python3 -c "
import json
existing = json.loads('$BINDINGS')
existing.append({
    'agentId': '<agent-id>',
    'match': {
        'channel': 'wecom',
        'accountId': '<accountId>'
    }
})
print(json.dumps(existing))
" | openclaw config set bindings --stdin

5️⃣ 重启并验证

openclaw gateway restart
# 登录对应 Bot 的企微，发一条消息测试
# 确认消息到达正确的 Agent，且 Agent 使用配置的模型回复

配置诊断工具

运行诊断

scripts/diagnose.py

输出示例：

🧩 多Agent多企微Bot - 配置诊断报告
================================================================

📡 企微 Bot 账号 (4 个)
  📍 agent-a (客服Bot)      BotID: xxx...
  📍 agent-b (财务Bot)      BotID: xxx...
  📍 agent-c (运营Bot)      BotID: xxx...
  📍 agent-d (销售Bot)      BotID: xxx...

🤖 Agent 列表 (4 个)
  ✅ agent-a → SOUL.md ✅ → models.json ✅
  ✅ agent-b → SOUL.md ✅ → 无独立模型(继承全局)
  ✅ agent-c → SOUL.md ✅ → models.json ✅
  ✅ agent-d → SOUL.md ✅ → models.json ✅

🔗 Agent-Bot 绑定关系 (4 条)
  ✅ agent-a → agent-a (客服Bot)
  ✅ agent-b → agent-b (财务Bot)
  ✅ agent-c → agent-c (运营Bot)
  ✅ agent-d → agent-d (销售Bot)

================================================================
✅ 配置完整！所有 Bot 账号均已绑定 Agent。

诊断工具自动检查：
- 所有 Bot 账号是否已绑定 Agent
- 每个 Agent 是否有 SOUL.md（人设文件）
- 每个 Agent 是否有独立模型配置或继承全局
- 未绑定的账号和闲置 Agent 列表

常见问题

Q: Agent 回复后，消息是从哪个 Bot 发出的？

A: 由 bindings 决定。消息通过哪个 Bot 进入，就通过哪个 Bot 回复。每个 Bot 独立收发。

Q: 多个 Bot 可以绑到同一个 Agent 吗？

A: 可以。同一个 Agent 可以处理多个 Bot 账号的消息。这时 Agent 可通过 accountId 字段判断消息来源，按来源做不同回复策略。

Q: Agent 之间的人设会互相干扰吗？

A: 不会。每个 Agent 的 SOUL.md、USER.md、AGENTS.md 存放在独立的 workspace 目录中，OpenClaw 启动时各自加载自己的配置文件。这是物理隔离，不是逻辑隔离。

Q: 模型配置的优先级是怎样的？

A: agent/models.json > agents.list[].model.primary > agents.defaults.model.primary > 全局 models.providers

Q: 如果某个 Agent 没有 models.json 会怎样？

A: 自动继承全局配置中的模型提供方。通过 agents.defaults.model.primary 可以指定一个兜底模型。建议至少给全局配一套可用模型。

Q: 如何让 Agent 主动推送消息到企微群？

A: Agent 内部使用 exec 调用 WeCom Bot API：

# 获取 Token
TOKEN=$(curl -s "https://qyapi.weixin.qq.com/cgi-bin/bot/gettoken?bot_id=<BOT_ID>&bot_secret=<SECRET>" | python3 -c "import json,sys;print(json.load(sys.stdin).get('access_token',''))")
# 发送 Markdown 消息
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/bot/send?access_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"markdown","markdown":{"content":"# 报告标题\n正文内容..."}}'

Q: 配置完后 Bot 没反应怎么办？

A: 按以下顺序排查：
1. 确认 openclaw gateway restart 已执行
2. 确认企微 Bot 已正确配置
3. 运行 diagnose 检查绑定关系和人设完整性
4. 检查 Gateway 日志：openclaw gateway log --lines 50
5. 确认企微 Bot 的 IP 白名单包含服务器 IP

Q: 动态 Agent 路由（dynamicAgents）和多账号绑定的区别？

A:
- 动态 Agent 路由：自动为每个用户/群创建临时 Agent，适合客服/用户隔离场景
- 多账号绑定：手动将固定 Bot 绑定到固定 Agent，适合角色分工场景（如：财务Bot→财务Agent、运营Bot→运营Agent）
- 两者可以同时使用，不冲突

Q: 已有 Agent 如何切换模型？

A: 编辑对应 Agent 的 agent/models.json 文件，或通过 CLI 配置：

openclaw config set agents.list[?(@.id=='<agent-id>')].model.primary "gpt-4o"
openclaw gateway restart

重启后新模型生效。