OpenClaw 部署及飞书机器人对接指南

openclaw onboard --install-daemon

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

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

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

配置完成后检查状态：

openclaw gateway status

若显示 running，基础环境已就绪。此时可通过 Web UI 进行调试：

openclaw dashboard

浏览器将自动打开 http://127.0.0.1:18789，进入控制面板。

飞书机器人配置全流程

此部分为核心环节，分为飞书侧应用创建、OpenClaw 侧配置、联调测试三步。

1. 安装飞书插件

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

openclaw plugins install @openclaw/feishu

安装后重启网关：

openclaw gateway restart

2. 飞书开放平台：创建应用

登录 飞书开放平台，国际版请使用 https://open.larksuite.com/app。

创建企业自建应用

1. 点击「创建企业自建应用」
2. 填写应用名称（例如'我的 AI 助手'）、描述及图标

获取凭证

在「凭证与基础信息」页面复制两项关键信息：

• App ID（格式：cli_xxxxxxxxx）
• App Secret

安全提示：App Secret 属于敏感信息，请勿泄露或提交至代码仓库。

配置权限

进入「权限管理」→「批量开通」，粘贴以下 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 等权限。

开启机器人能力

进入「应用能力」→「机器人」，开启能力并设置机器人名称。

配置事件订阅（关键步骤）

进入「事件与回调」：

1. 选择「使用长连接接收事件」（WebSocket 方式）
2. 添加事件：搜索并勾选 im.message.receive_v1

⚠️ 重要：务必选择「长连接」而非「Webhook」。长连接无需公网 IP 和域名，适合个人开发者。

前置条件：配置前请确保 OpenClaw Gateway 正在运行，否则飞书无法检测 WebSocket 连接，导致保存失败。

发布应用

1. 进入「版本管理与发布」
2. 创建版本并提交审核
3. 等待管理员审批（企业自建应用通常秒批）

注意：未发布的应用即使配置完成也无法生效。

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

4. 首次联调

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

openclaw pairing approve feishu <配对码>

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

常见问题排查

以下是实际配置中常见的问题及解决方案。

事件订阅保存失败

现象：飞书平台配置长连接时保存无反应或报错。

原因：OpenClaw Gateway 未启动，飞书无法建立 WebSocket 连接。

解决：

openclaw gateway start
openclaw gateway status
# 确认状态为 running 后再去飞书平台配置

机器人不回复消息

排查清单：

1. 应用是否已 发布？（最常见原因）
2. 事件订阅是否添加了 im.message.receive_v1？
3. 是否选择了 「长连接」 模式？
4. 权限是否已全部开通？
5. Gateway 是否在运行？

实时查看日志辅助定位：

openclaw logs --follow

群聊内机器人不响应

现象：私聊正常，群聊 @机器人 无反应。

原因：默认配置下群聊需 @提及，且机器人必须加入群聊。

解决：

1. 确认机器人已加入群聊
2. 发送消息时 @机器人
3. 若希望免 @回复，修改配置：

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

群 ID 获取方法：启动 Gateway 后在群里 @机器人，通过 openclaw logs --follow 查找 chat_id。

权限不足报错

现象：消息发送失败、读取文件报错。

原因：飞书权限粒度较细，缺少特定权限会导致操作失败。

常用权限对照：

注意：新增权限后需重新发布应用版本才能生效。

配对码一直未收到

现象：发送消息后未触发配对流程。

原因：Gateway 未成功连接飞书 WebSocket。

解决：查看详细日志排查连接状态：

openclaw logs --follow

检查是否有 feishu 连接成功的日志，若有 error 则根据错误信息修正 App ID/Secret。

Node.js 版本过低

现象：安装报错或启动异常。

原因：OpenClaw 依赖 Node.js 22+，系统默认可能为 18 或 20。

解决：

node --version
nvm install 22
nvm use 22
openclaw gateway restart

验证与常用命令

跑完流程后，建议逐项确认：

# 1. 检查安装版本
openclaw --version

# 2. 确认 Gateway 状态
openclaw gateway status

# 3. 查看已安装插件
openclaw plugins list
# 应能看到 @openclaw/feishu

# 4. 检查飞书连接状态
openclaw status
# 应显示 feishu: connected

# 5. 飞书实测
# 发送一条消息，收到 AI 回复即表示成功

常用命令速查

飞书内置命令

核心配置要点

1. 顺序原则：先装插件，后配飞书；先跑 Gateway，后配事件订阅。
2. 发布机制：权限配置完成后，务必记得发布应用版本。
3. 日志优先：遇到问题优先查看 openclaw logs --follow。
4. 版本关注：如遇接口变动，请以官方文档为准。