OpenClaw 使用教程

Appearance

飞书（Feishu / Lark）对接（完整指南） ​

目标：把 OpenClaw 接入飞书/飞书国际版（Lark），实现私聊/群聊收发消息，并可做配对控制。

0) 先了解：为什么飞书推荐用 WebSocket 长连接 ​

  • 不需要公网回调地址（无需暴露 webhook URL）
  • Gateway 启动后，插件通过飞书的“事件订阅长连接”接收消息

1) 飞书侧配置（开放平台） ​

1.1 创建自建应用 ​

  1. 打开：https://open.feishu.cn/app
  2. 创建「企业自建应用」
  3. 在「凭证与基础信息」复制：
    • App ID（形如 cli_xxx）
    • App Secret

Lark（国际版）使用：https://open.larksuite.com/app

1.2 权限（Scopes） ​

在「权限管理」中给机器人消息能力（至少需要能收/发消息；更完整权限可按你的使用范围增加）。

1.3 事件订阅（长连接） ​

在「事件订阅」里选择 使用长连接接收事件，并订阅：

  • im.message.receive_v1

⚠️ 注意：部分情况下飞书后台要求你先启动/配置好客户端（OpenClaw）后，长连接订阅才能保存。

1.4 发布应用 ​

在「版本管理与发布」创建版本并发布（企业自建应用通常需要管理员确认）。

2) OpenClaw 侧配置 ​

2.1 用向导添加（推荐） ​

bash
openclaw channels add

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

2.2 通过配置文件添加（示例） ​

编辑 ~/.openclaw/openclaw.json：

json5
{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "我的AI助手"
        }
      }
    }
  }
}
  • dmPolicy: "pairing"：私聊默认需要配对批准（更安全）。
  • Lark（国际版）可设置：channels.feishu.domain: "lark"。

3) 启动与测试 ​

bash
openclaw gateway status
openclaw logs --follow

在飞书里给机器人发消息：

  • 默认会收到配对码
  • 在本机批准：
bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

4) 群聊行为（常见设置） ​

4.1 群里不回应：优先检查 ​

  • 机器人是否已加入群
  • 是否需要 @（默认很多配置会要求 @ 才响应）
  • groupPolicy 是否禁用

4.2 常用配置示例（概念） ​

json5
{
  channels: {
    feishu: {
      groupPolicy: "open",
      groups: {
        // 某个群不需要 @
        oc_xxx: { requireMention: false }
      }
    }
  }
}

5) 故障排查清单 ​

  • openclaw gateway status：网关是否运行
  • openclaw logs --follow：是否收到飞书事件/是否鉴权失败
  • 检查 App 是否已发布、权限是否足够、事件订阅是否为长连接并包含 im.message.receive_v1

参考 ​

  • OpenClaw 官方渠道文档（飞书）：docs → channels/feishu