OpenClaw Gateway 对接 Lark/飞书配置指南

iX.
10 3月, 2026
, ,

本文介绍如何通过 OpenClaw 官方 Feishu 插件，以 WebSocket 长连接模式将 AI Agent 接入 Lark（国际版）或飞书（国内版）。整个方案无需暴露公网端口，只需服务器能访问外网即可。

 

前置条件

  • OpenClaw Gateway 已运行
  • 能访问 open.larksuite.com（Lark 国际版）或 open.feishu.cn（飞书国内版）

第一步：创建 Lark Bot 应用

1. 打开开发者后台

版本地址
Lark（国际版）https://open.larksuite.com/app
飞书（国内版）https://open.feishu.cn/app

2. 创建应用

点击「创建企业自建应用」，填写应用名称和描述，选择图标。

3. 获取凭证

在「凭证与基础信息」页面复制：

  • App ID — 格式如 cli_xxxxxxxxxx
  • App Secret — 妥善保管，不要泄露

4. 启用机器人能力

「应用能力」→「机器人」→ 开启机器人能力，配置机器人名称。

5. 配置权限（Permissions & Scopes）

在「权限管理」→「批量导入」，根据版本粘贴对应 JSON。

Lark 国际版：

{
  "scopes": {
    "tenant": [
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly",
      "docs:document.content:read",
      "docx:document:readonly",
      "event:ip_list",
      "im:chat",
      "im:chat.members:read",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "docx:document:readonly"
    ]
  }
}

飞书国内版：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly",
      "docs:document.content:read",
      "docx:document:readonly",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "docx:document:readonly",
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

关键权限说明：

  • im:message.p2p_msg:readonly — 私聊必须，没有这个 scope bot 收不到 DM
  • contact:contact.base:readonly — 解析用户信息，缺少会在日志中产生 scope 警告

6. 配置事件订阅（Event Subscriptions）

⚠️ 这一步和权限配置是两个不同的页面，不要混淆。

在「事件与回调」页面：

  1. 订阅方式选择「使用长连接接收事件（Long Connection / WebSocket）」
  2. 添加事件：im.message.receive_v1（接收消息）

没有这个事件订阅，WebSocket 连上了也收不到任何消息。

7. 发布应用

⚠️ 事件订阅的改动需要手动发布才生效，权限变更会自动发布。

「版本管理与发布」→ 创建版本 → 发布。

第二步：配置 OpenClaw Gateway

启用插件

openclaw plugins install @openclaw/feishu

编辑 openclaw.json

在 ~/.openclaw/openclaw.json 中添加 feishu channel 配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "lark",        // Lark 国际版用 "lark"，飞书国内版用 "feishu"
      "accounts": {
        "default": {
          "appId": "cli_xxx",
          "appSecret": "xxx",  // 直接写明文，SecretRef 在 feishu 插件中可能不工作
          "botName": "My Bot"
        }
      }
    }
  }
}

⚠️ 已知问题：feishu 插件的 appSecret 使用 SecretRef（{ "source": "file", ... }）可能导致认证失败（400 Bad Request），建议直接写明文字符串。

添加 Binding

将 feishu channel 绑定到目标 agent：

{
  "bindings": [
    {
      "agentId": "my-agent",
      "match": { "channel": "feishu", "accountId": "default" }
    }
  ]
}

重启网关

feishu 插件变更需要重启（不支持 hot-reload）：

systemctl --user restart openclaw-gateway

第三步：启动并测试

验证启动日志

feishu[default]: bot open_id resolved: ou_xxx     ← appSecret 认证成功
feishu[default]: WebSocket client started          ← 长连接已建立

如果看到 AxiosError: Request failed with status code 400，说明 appSecret 没有正确传递。

私聊测试

  1. 在 Lark 中找到机器人，发送一条消息
  2. 首次会收到配对码（pairing code）
  3. 在服务器上批准：
openclaw pairing approve feishu <配对码>

群聊测试

  1. 将 bot 拉入群组
  2. @bot 发送消息
  3. 确认收到回复

访问控制策略

私聊策略（dmPolicy）

值行为
"pairing"默认。未知用户收到配对码，管理员批准后才能对话
"allowlist"仅 allowFrom 列表中的 open_id 可对话
"open"允许所有人
"disabled"禁止私聊

群组策略（groupPolicy）

值行为
"open"默认。所有群组都响应（需 @bot）
"allowlist"仅 groupAllowFrom 中的群组 ID 响应
"disabled"忽略所有群消息

配置示例

{
  "channels": {
    "feishu": {
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["oc_29a03bca80fba72243ef5be7508e9558"],
      "groups": {
        "oc_xxx": { "requireMention": false }
      }
    }
  }
}

故障排除

问题排查方法
bot 收不到任何消息① 事件订阅是否添加了 im.message.receive_v1？② 修改后是否 Publish 发布？③ 订阅方式是否选了 Long Connection？
私聊无回复检查是否有 im:message.p2p_msg:readonly 权限，发布后生效
群聊无回复bot 是否已加入群组？是否 @了 bot？groupPolicy 是否为 "disabled"？
日志 400 Bad RequestappSecret 未正确传递，改用明文字符串而非 SecretRef
日志 scope 警告添加缺少的 scope（如 contact:contact.base:readonly），发布后生效
WebSocket 连接后无事件事件订阅改动未发布 — 需手动 Publish
access not configured正常的 pairing 流程，用 openclaw pairing approve feishu <CODE> 批准

常用命令速查

命令说明
openclaw pairing list feishu查看待审批配对
openclaw pairing approve feishu <CODE>批准配对
openclaw channels status查看渠道连接状态
systemctl --user restart openclaw-gateway重启网关

参考链接

Previous Post
No Comment
Add Comment
comment url