OpenClaw 安装与飞书机器人对接全流程指南

四、初始配置（onboard 向导）

安装完成后，运行初始化向导：

openclaw onboard --install-daemon

向导将引导你完成以下配置：

1. AI 模型密钥：输入 Anthropic / OpenAI / Google 等平台的 API Key。
2. Gateway 设置：默认端口为 18789，通常无需修改。
3. 聊天渠道：此处可先跳过，后续单独配置飞书。

💡 --install-daemon 参数会将 Gateway 注册为系统服务，实现开机自启。

配置完成后检查服务状态：

openclaw gateway status

若显示 running，则基础环境已就绪。此时可通过以下命令打开 Web 控制面板：

openclaw dashboard

浏览器将自动跳转至 http://127.0.0.1:18789。

五、飞书机器人配置全流程

飞书对接分为三步：飞书侧创建应用 → OpenClaw 侧配置插件 → 联调测试。

5.1 安装飞书插件

OpenClaw 通过插件支持飞书，需先行安装：

openclaw plugins install @openclaw/feishu

安装完成后重启 Gateway：

openclaw gateway restart

5.2 飞书开放平台：创建应用

1. 登录平台：访问 飞书开放平台 并登录。（国际版 Lark 请访问 https://open.larksuite.com/app）
2. 创建应用：点击「创建企业自建应用」，填写名称、描述并选择图标。
3. 获取凭证：在「凭证与基础信息」页面，复制 App ID（格式：cli_xxxxxxxxx）与 App Secret。请妥善保管 App Secret，切勿泄露或提交至代码仓库。
4. 配置权限：进入「权限管理」，点击「批量开通」，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "contact:user.employee_id:readonly"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

💡 此为最小权限集。若需操作文档或多维表格，可后续追加 docx:document、bitable:app 等权限。

5. 开启机器人能力：进入「应用能力」→「机器人」，开启该能力并设置名称。
6. 配置事件订阅：进入「事件与回调」：
   • 选择「使用长连接接收事件」（WebSocket 模式）。
   • 添加事件：搜索并勾选 im.message.receive_v1（接收消息 v1）。

   🚨 关键提示：务必选择「长连接」。该模式无需公网 IP 或域名，对个人开发者更友好。配置前请确保 OpenClaw Gateway 已处于运行状态，否则飞书无法建立连接导致保存失败。

7. 发布应用：进入「版本管理与发布」，创建版本并提交审核。企业自建应用通常可快速通过。

   ⚠️ 注意：应用必须发布后配置才会生效。

5.3 OpenClaw 侧配置

方式一：交互式向导（推荐）

openclaw channels add

选择 Feishu，按提示输入 App ID 和 App Secret。

方式二：手动编辑配置文件 编辑 ~/.openclaw/openclaw.json，追加飞书配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxx",
          "appSecret": "你的AppSecret"
        }
      }
    }
  }
}

保存后重启服务：

openclaw gateway restart

5.4 首次联调

1. 在飞书中找到该机器人，发送任意消息（如'你好'）。
2. 机器人将回复一个 配对码（Pairing Code）。
3. 在终端执行确认命令：

openclaw pairing approve feishu <配对码>

4. 配对成功后，再次发送消息即可收到 AI 回复。

六、常见问题排查

问题 1：事件订阅保存失败

• 现象：飞书平台配置长连接时点击保存无响应或报错。
• 原因：OpenClaw Gateway 未运行，飞书无法检测到 WebSocket 端点。
• 解决：

openclaw gateway start
openclaw gateway status  # 确认状态为 running

服务启动后再返回飞书平台保存配置。

问题 2：机器人不回复消息

• 排查清单：
  1. 应用是否已发布？（最常见原因）
  2. 事件订阅是否已添加 im.message.receive_v1？
  3. 是否选择了「长连接」模式？
  4. 权限是否已完整开通？
  5. Gateway 是否正常运行？
• 日志排查：

openclaw logs --follow

发送消息后观察终端输出，定位具体报错。

问题 3：群聊中 @机器人 无响应

• 原因：默认需 @机器人 才会触发响应，且机器人必须已加入该群。
• 解决：
  1. 确认机器人已入群。
  2. 发送消息时务必 @机器人。
  3. 若需免 @ 回复，修改配置：

{
  "channels": {
    "feishu": {
      "groups": {
        "oc_你的群ID": {
          "requireMention": false
        }
      }
    }
  }
}

💡 获取群 ID：启动 Gateway 后在群内 @机器人，通过 openclaw logs --follow 查看日志中的 chat_id。

问题 4：权限不足导致功能异常

• 现象：消息发送失败、无法读取文件或操作文档报错。
• 解决：飞书权限为细粒度控制。按需补充权限后，必须重新发布应用版本方可生效。常用权限对照： | 场景 | 所需权限 | | --- | --- | | 收发消息 | im:message, im:message:send_as_bot | | 读取群消息 | im:message.group_at_msg:readonly | | 操作文档 | docx:document, docx:document:readonly | | 操作多维表格 | bitable:app | | 云盘操作 | drive:drive, drive:file |

问题 5：未收到配对码

• 原因：Gateway 未成功建立飞书 WebSocket 连接。
• 解决：运行 openclaw logs --follow 检查连接日志。若出现 error，通常为 App ID 或 App Secret 填写错误。

问题 6：Node.js 版本过低

• 现象：安装或启动时报错。
• 解决：OpenClaw 要求 Node.js 22+。使用 nvm 升级：

nvm install 22
nvm use 22
openclaw gateway restart

七、验证清单

完成配置后，建议按以下顺序验证：

# 1. 检查版本
openclaw --version
# 2. 检查 Gateway 状态
openclaw gateway status
# 3. 确认插件已安装
openclaw plugins list
# 4. 检查飞书连接状态
openclaw status  # 应显示 feishu: connected
# 5. 飞书端发送测试消息，确认收到 AI 回复

八、常用命令速查

飞书端内置指令

核心注意事项

1. 先装插件，后配飞书：确保 @openclaw/feishu 插件已正确安装。
2. 先跑 Gateway，后配事件订阅：长连接依赖本地服务在线。
3. 配完权限，务必发布应用：权限变更需新版本生效。
4. 遇错先看日志：openclaw logs --follow 是最高效的排查手段。

本文基于 OpenClaw 2026.3.2 版本编写，飞书开放平台配置流程截至 2026 年 3 月。实际界面或参数可能随版本更新略有差异，请以 官方文档 为准。