OpenClaw 配置多个飞书账号实战指南

从 v2.4 版本开始，OpenClaw 正式引入了**多飞书账号（Multi-Account）**配置的支持。这一特性使得单一 OpenClaw 实例能够同时挂载和管理多个飞书机器人，并路由给不同的 AI Agent 处理。

本文将基于实际配置示例，手把手教你如何快速搭建 OpenClaw 的多账号体系。

一、 为什么需要配置多账号？

在实际的企业应用场景中，单账号往往无法满足复杂的业务需求，多账号体系能够带来以下优势：

• 账号隔离：不同业务线使用独立的飞书机器人应用，避免消息和调用频率相互干扰。
• 多 Agent 分工：将不同的飞书账号绑定到不同的专业 AI Agent（如：代码助手、HR 知识问答助手等），实现专人专事。
• 环境分离：在同一个框架下实现"生产账号"与"测试账号"的彻底隔离，方便调试。

---

二、 快速开始（以新增 note 账号为例）

2.1 创建新的 Agent

首先，我们需要在 OpenClaw 中为新的飞书账号创建一个对应的 Agent。

# 方式一：创建 Agent 并自动生成对应的工作区
openclaw agents add note

# 方式二：创建 Agent 并手动指定工作区路径（推荐）
openclaw agents add note --workspace ~/.openclaw/workspace/note

执行成功后，系统会自动创建以下两个核心目录：

• 工作区目录 ：~/.openclaw/workspace/note/
• Agent 配置目录 ：~/.openclaw/agents/note/agent/

2.2 在飞书开放平台创建应用

接下来，前往飞书平台获取机器人凭证：

1. 访问 飞书开放平台 并登录。
2. 点击"创建企业自建应用"，填写应用名称（例如：Note助手）。
3. 在左侧菜单"凭证与基础信息"中，获取 App ID 和 App Secret。
4. 在左侧菜单"开发配置" -> "权限管理"中，按需添加以下权限：
   • im:message（获取单聊、群组消息）
   • im:message:send_as_bot （⚠️ 关键权限：以应用的身份发消息，必须开通）
   • im:group（获取群组信息，如需在群聊使用）
   • drive:drive / wiki:wiki（云盘与知识库权限，按 Agent 需求开通）
5. 在"事件订阅"中，推荐将接收方式设置为 WebSocket 长连接模式。
6. 最后，创建一个应用版本并申请发布/安装到企业中。

2.3 配置 openclaw.json

这是多账号配置最核心的一步。打开你的 openclaw.json 配置文件。

⚠️ 避坑指南：关于 Default Bot 的向后兼容

很多开发者在迁移多账号时，会习惯性把默认账号的凭证移到 accounts.default 节点下。请注意：Default Bot 的 appId 和 appSecret 必须保留在 channels.feishu 顶层！ 其他新增账号才放在 accounts 字典中。

完整的配置文件示例参考如下：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "connectionMode": "websocket",
      
      // ⚠️ Default Bot 的凭据必须放在顶层
      "appId": "cli_default_xxx",
      "appSecret": "***",
      "defaultAccount": "default",
      
      // 新增的多账号配置在此处
      "accounts": {
        "note": {
          "appId": "cli_note_xxx",
          "appSecret": "***"
        }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main", 
        "workspace": "~/.openclaw/workspace", 
        "default": true
      },
      {
        "id": "note", 
        "workspace": "~/.openclaw/workspace/note"
      }
    ]
  },
  "bindings": [
    {
      "type": "route",
      "agentId": "main",
      "match": {
        "channel": "feishu", 
        "accountId": "default"
      }
    },
    {
      "type": "route",
      "agentId": "note",
      "match": {
        "channel": "feishu", 
        "accountId": "note"
      }
    }
  ]
}

2.4 验证配置状态

修改完配置并重启服务后，使用以下命令检查服务运行状态：

# 1. 检查 Agent 列表及其通道绑定情况
openclaw agents list --bindings

# 2. 对飞书插件状态进行探针检测
openclaw channels status --probe

✅ 期望输出结果：

如果配置成功，你应该能看到所有的飞书账号均处于就绪状态：

- Feishu default: enabled, configured, running, works
- Feishu note: enabled, configured, running, works

---

三、 常见问题 (FAQ)

Q1：机器人能收到消息，但是无法回复？
A： 检查飞书开放平台是否开通了 im:message:send_as_bot 权限。如果在日志中看到 Feishu API 返回 code: 99991672，100% 是因为权限不足。请注意，添加权限后必须发布新版本才会生效。

Q2：给机器人发第一条私聊消息（DM），它完全没反应？
A： 这是因为你的 OpenClaw 开启了 pairing（配对审批）模式。首条消息会被拦截并生成一个配对请求。

解决方法：

# 1. 查看当前的配对请求，获取审批 CODE
openclaw pairing list --channel feishu --account note

# 2. 批准配对请求 (替换 <CODE> 为实际代码)
openclaw pairing approve feishu <CODE> --account note

Q3：执行状态检查时，Default Bot 显示 not configured？
A： 请回头检查 openclaw.json。大概率是你把 Default Bot 的 appId 和 appSecret 放进了 accounts.default 里面。请将它们提取回 channels.feishu 的顶层。

Q4：如何通过日志判断路由配置是否成功？
A： 查看控制台日志，如果配置正确，每次发消息都会按顺序打印以下关键词：

1. feishu[note]: received message ... （确认账号 note 收到消息）
2. feishu[note]: dispatching to agent （确认准备分发）
3. session=agent:note:feishu:direct:... （确认成功路由到 note agent）

---

四、 终极调试排查 Checklist

遇到机器人无响应时，请按以下顺序逐步排查，不要跳步：

• 1. 在线状态检查：Bot 的 WebSocket 连接是否已建立并在线？
• 2. Inbound 检查：OpenClaw 是否收到了来自飞书的消息事件日志？
• 3. 拦截器检查：是否被 Pairing（配对机制）或 Allowlist（白名单）拦截？
• 4. 路由检查：消息是否根据 Bindings 规则 Dispatch 到了正确的 Agent？
• 5. Agent 检查：目标 Agent（大模型）是否成功生成了文本回复？
• 6. Outbound 检查：调用 Feishu Send API 时是否成功（检查权限和网络）？

---

五、 核心经验总结

1. 凭证位置很关键 ：default bot 切勿完全迁移到 accounts 字典内，顶层必须保留其凭证以兼容老版本逻辑。
2. 收发权限是分开的 ：能收消息绝不代表能发消息，每次新建应用务必牢记开通 im:message:send_as_bot 并发布应用。
3. 熟悉 Pairing 机制 ：如果你发现新用户的首条私聊石沉大海，第一反应应该是去后台做 pairing approve。
4. 相信日志的判断 ：直觉往往会骗人，多看系统 Log。90% 的无响应问题都集中在：路由配置错位、未授权配对、飞书 API 作用域缺失 这三点上。