OpenClaw 多 Agent + 双钉钉机器人 SOP（单网关）

场景：一台网关、两个 agent（如 main + k8sagent）；两个钉钉企业内部应用 / 两个机器人，各进对应群聊；会话与人设隔离；Skill 暂用公共目录（~/.openclaw/skills/ 等，两 agent 不做单独白名单拆分）。

路由方式：官方连接器 dingtalk-connector 支持 accounts 多账号，用 bindings.match.accountId 把不同机器人指到不同 agentId。说明见 钉钉 OpenClaw 官方连接器 README - 多 Agent 配置。

---

路径速查（Linux，示例用户主目录 ~）

项目	路径
总配置	~/.openclaw/openclaw.json
main 工作区	一般为 ~/.openclaw/workspace
k8sagent 工作区	一般为 ~/.openclaw/workspace/k8sagent（以 agents.list 为准）
会话落盘	~/.openclaw/agents/<agentId>/sessions/
公共 Skill	~/.openclaw/skills/（Skills）

---

一、前置

• OpenClaw 与 Gateway 已安装，可 openclaw gateway status。
• 已安装钉钉插件：openclaw plugins install @dingtalk-real-ai/dingtalk-connector（版本需满足连接器 README 中的 OpenClaw 最低版本）。
• 编辑配置前备份：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d%H%M)。

---

二、钉钉侧：新建第二个机器人（K8S 用）

1. 打开 钉钉开放平台 → 应用开发 → 企业内部应用 → 新建应用（与 main 所用应用分开）。
2. 为该应用开启 机器人 能力，消息接收选 Stream 模式。
3. 记录 Client ID（AppKey）、Client Secret（AppSecret）；完成 版本发布 与可见范围。
4. 在目标 K8S 运维群 中拉入该机器人；群内按策略 @机器人 发消息测试（后续在 OpenClaw 配好后验证）。

main 沿用原应用：第一个机器人的凭证继续给下面 accounts 里的 main（名称可自定义，与 bindings 一致即可）。

---

三、OpenClaw：新建 Agent

openclaw agents add k8sagent
# 或指定工作区
openclaw agents add k8sagent --workspace ~/.openclaw/workspace/k8sagent

openclaw agents list
openclaw agents set-default main

确认 main 为 default，agents.list 中已有 k8sagent。记下 k8sagent 的 Workspace（下文 $K8S_WS）。

---

四、人设（与 main 区分）

cd "$K8S_WS"   # 例如 ~/.openclaw/workspace/k8sagent
vim SOUL.md
# 可选：vim USER.md AGENTS.md

可参考与你场景相近的 SOUL.md 模板（自建示例仓库或团队内部模板均可）；勿在文中粘贴真实凭证、内网域名或真实群聊标识。

---

五、Skill（当前：公共技能）

• 技能继续放在 ~/.openclaw/skills/（及 bundled 等原有来源）；不要在 agents.list 里为 k8sagent / main 写 skills 白名单（除非你以后要按 name 裁剪）。
• 两 agent 共用同一套可见技能；区分对话靠 不同 agent 的会话 + SOUL，不靠 skill 拆分。

---

六、LLM 与 main 共用

• k8sagent 不要单独写 另一套 model / provider apiKey，继承 agents.defaults 或全局 models 即可与 main 同 Key。

---

七、配置 dingtalk-connector：多账号 + bindings

在 ~/.openclaw/openclaw.json 中：

1. 将钉钉连接器改为 channels.dingtalk-connector.accounts，每个机器人一个 key（示例用 main、k8sagent；名称可自定，但须 三处一致：accounts 的 key、bindings.match.accountId、agents.list 的 id 无混淆）。
2. 根级增加 bindings：accountId 与 accounts 下 key 一致，agentId 与 agents.list 的 id 一致。
3. gateway.auth.token 与连接器要求的认证方式保持与你线上一致（若连接器版本仍要求与网关 token 对齐，按当前插件文档填写）。

示例（请替换真实 clientId/clientSecret，并合并你现有的 gateway、models 等段落）：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace"
      },
      {
        "id": "k8sagent",
        "workspace": "~/.openclaw/workspace/k8sagent"
      }
    ]
  },
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "accounts": {
        "main": {
          "enabled": true,
          "clientId": "ding_第一个应用_AppKey",
          "clientSecret": "第一个应用_Secret"
        },
        "k8sagent": {
          "enabled": true,
          "clientId": "ding_第二个应用_AppKey",
          "clientSecret": "第二个应用_Secret"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "dingtalk-connector",
        "accountId": "main"
      }
    },
    {
      "agentId": "k8sagent",
      "match": {
        "channel": "dingtalk-connector",
        "accountId": "k8sagent"
      }
    }
  ],
  "plugins": {
    "allow": ["@dingtalk-real-ai/dingtalk-connector"]
  }
}

• 若此前 顶层写过单组 clientId/clientSecret，需 迁入 accounts 并删除顶层重复字段，避免与插件 schema 冲突（以 openclaw config validate 为准）。
• plugins.allow：按告警提示显式放行已信任的扩展 id（与 openclaw plugins list 中一致）。

---

八、重启与验证

openclaw config validate
openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

若执行 openclaw gateway restart 报错：systemctl is-enabled unavailable: Failed to connect to bus: No medium found，表示当前环境 无可用 systemd D-Bus（常见于无 systemd 的容器/精简会话）。可 pgrep -af openclaw 找到进程后 kill <PID>，再前台执行 openclaw gateway（或 openclaw gateway --help 中的前台子命令）；Docker 场景则 重启容器。

步骤	操作	期望
1	在 main 机器人所在群 @ 机器人提问	走 main，~/.openclaw/agents/main/sessions/ 有更新
2	在 K8S 机器人所在群 @ 机器人提问	走 k8sagent，人设符合 SOUL
3	openclaw agents list --bindings	能看到两条 accountId 路由

私聊若为 pairing：openclaw pairing list dingtalk-connector → openclaw pairing approve dingtalk-connector <码>。

---

九、备选：一个机器人、两个群分流

若坚持 单应用单机器人、按群进不同 agent：在 bindings 里用 match.peer（kind: "group" + 群 openConversationId），见 Channel Routing。群 ID 需从钉钉 API 或调试日志获取，网关默认日志未必打印。

---

十、常见问题（精简）

现象	处理
两机器人进同一 agent	检查 accountId 与 accounts 的 key、bindings 是否写错
config validate 报错	删废弃字段、严格 JSON；对照连接器 README
仍提示 plugins.allow	补全 plugins.allow 后重启

---

十一、回滚

cp ~/.openclaw/openclaw.json.bak.<时间戳> ~/.openclaw/openclaw.json
openclaw gateway restart

无 systemd 时重启方式见 第八节。

---

十二、执行清单

1. 备份 openclaw.json
2. 钉钉新建应用/机器人（K8S），拉进群
3. openclaw agents add k8sagent + set-default main
4. 编辑 $K8S_WS/SOUL.md
5. Skill 保持公共（~/.openclaw/skills/，不设 per-agent skills）
6. channels.dingtalk-connector.accounts（main + k8s）+ bindings + plugins.allow
7. validate → gateway restart（或第八节无 systemd 时的启停方式）→ agents list --bindings / 两群实测
8. 遇阻时查阅 第十三节「实践记录」

---

十三、实践记录与后续新增 Agent 参考

以下为本次落地过程中出现过的问题与结论，后续再新增 agent（例如 coder、ops）时可按条对照，减少重复踩坑。

13.1 配置位置与 CLI

情况	说明
配置文件	主配置为 ~/.openclaw/openclaw.json（或环境变量 OPENCLAW_CONFIG_PATH 指定路径）。
openclaw config file 报错	旧版 CLI 可能不支持该子命令；直接编辑上述文件即可。
openclaw config validate 输出 Config valid	表示 JSON/Schema 校验通过，不代表钉钉已连通；需再结合 channels status --probe 与群内实测。

13.2 多 Agent 与钉钉路由认知

情况	说明
新建 agent 是否要重配通道	不必为「多一个 agent」重装钉钉插件；同一网关下用 accounts + bindings 把不同机器人指到不同 agentId 即可。
同一群、同一机器人、靠话术切换 agent	不可靠；路由由 bindings（及 default） 决定，不能靠提示词切换。
openclaw agents list 显示 Routing rules: 0	表示 尚无 bindings，钉钉会走 default: true 的 agent；需配路由后才会出现 Routing rules: 1 等。
未配绑定时却像「进了 K8S 人设」	多为 当时 default 指向、main 的 SOUL 被改过，或 钉钉侧固定欢迎语；以 agents default 与 agents list --bindings 为准排查。
跑通后的列表特征	各 agent 下 Routing rules: 1，且列出 dingtalk-connector accountId=<与 accounts key 一致>，Providers: DingTalk <name>: configured，即路由与账号侧已对齐。

13.3 Skill 与隔离策略

情况	说明
公共 skill	技能放在 ~/.openclaw/skills/ 等公共路径，不写 agents.list[].skills 白名单时，多 agent 共用可见技能；会话 + SOUL + 路由 仍可区分场景。
无官方「迁移 skill」命令	OpenClaw 不会自动把 main 工作区 skill 拷到另一 agent；需 rsync/CI 或 白名单，见 Skills。
skills/ 目录	工作区下需 mkdir -p <workspace>/skills 才会存在；不自动创建。

13.4 钉钉机器人与多 OpenClaw 实例

情况	说明
一套 ClientId/Secret 多网关同时收 Stream	不推荐；Stream 侧通常 同一应用同时只宜接一个消费端，多实例会 抢连或不稳定。
复用旧机器人	仅当 原 OpenClaw 已停用该应用 后再迁到现网关；旧实例仍在线时请 新建钉钉应用。

13.5 日志与群 ID（单机器人按群分流时）

情况	说明
/tmp/openclaw/openclaw-*.log 只有 plugins.allow WARN	默认文件里 未必打印入站正文或 conversationId；grep conversation 常 无结果。
取群 openConversationId	优先用 钉钉开放平台：获取群会话 OpenConversationId 等接口；或提高日志级别 / 看连接器文档。

13.6 插件告警

情况	说明
plugins.allow is empty	在 openclaw.json 中配置 plugins.allow（与本机 openclaw plugins list 中扩展 id 一致），例如 ["@dingtalk-real-ai/dingtalk-connector"]，保存后重启网关。

13.7 后续新增 Agent 的推荐顺序

1. 钉钉：新建企业内部应用 + 机器人（Stream）→ 拉群。
2. OpenClaw：openclaw agents add <新id> → 编辑 $WS/SOUL.md。
3. 配置：在 channels...accounts 增加 新 key + bindings 增加 accountId → 新 agentId；plugins.allow 已包含连接器则无需改。
4. 校验：openclaw config validate → 按环境 重启网关（见第八节）→ openclaw agents list --bindings → 两机器人各测一轮。

---

十四、参考

• 钉钉连接器 README（多 Agent）
• OpenClaw Multi-Agent
• Channel Routing
• 装机与钉钉首接：见 OpenClaw 文档 中安装、Gateway 与 Channel（钉钉）相关章节；若你有内部装机 Checklist，建议单独维护在内网 Wiki，勿随博客外露主机账号与拓扑细节。