3.1 飞书接入教程

飞书是字节跳动推出的企业沟通协作平台，OpenClaw 支持机器人私聊和群组对话。

前置要求

• 飞书账号（需要企业管理员权限创建应用）
• OpenClaw 已安装并完成初始配置

安装飞书插件

飞书渠道需要单独安装插件：

# 从 npm 安装
openclaw plugins install @openclaw/feishu

# 或从本地源码安装（开发时）
openclaw plugins install ./extensions/feishu

创建飞书应用

1. 打开飞书开放平台

访问 飞书开放平台 登录。

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

2. 创建应用

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

3. 获取应用凭证

在应用的「凭证与基础信息」页面，复制：

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

⚠️ 注意：请妥善保管 App Secret，不要泄露。

4. 配置应用权限

在「权限管理」页面，点击「批量导入」，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "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": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

5. 启用机器人能力

在「应用能力 > 机器人」页面：

• 开启机器人能力
• 配置机器人名称

6. 配置事件订阅

在「事件订阅」页面：

• 选择「使用长连接接收事件」（WebSocket 模式）
• 添加事件：im.message.receive_v1（接收消息）

⚠️ 重要：此时网关需要已启动并添加了 Feishu 渠道，否则长连接会保存失败。

7. 发布应用

在「版本管理与发布」页面创建版本，提交审核并发布。

---

配置 OpenClaw

方式一：命令行添加（推荐）

openclaw channels add

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

方式二：配置文件

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "我的AI助手"
        }
      }
    }
  }
}

方式三：环境变量

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark（国际版）配置

如果使用国际版（Lark），需要设置域名：

{
  "channels": {
    "feishu": {
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx"
        }
      }
    }
  }
}

---

启动与测试

1. 启动网关

openclaw gateway

2. 验证状态

openclaw gateway status
openclaw channels status

3. 发送测试消息

在飞书中找到你的机器人，给它发送一条消息。

4. 配对授权

默认配对模式下，你需要批准配对码：

# 查看待审批列表
openclaw pairing list feishu

# 批准配对
openclaw pairing approve feishu <配对码>

批准后即可正常对话。

---

访问控制

私聊策略（dmPolicy）

值	说明
pairing	默认。陌生用户收到配对码，需批准
allowlist	仅 allowFrom 列表中的用户可对话
open	允许所有人（需设置 allowFrom: ["*"]）
disabled	完全禁止私聊

群组策略

值	说明
open	允许群组中所有人
allowlist	仅 groupAllowFrom 中的用户可使用
disabled	禁用群组消息

@提及设置

默认情况下，机器人需要 @提及才会在群组中响应。配置示例：

{
  "channels": {
    "feishu": {
      "groups": {
        "oc_xxx": {
          "requireMention": false  // 无需 @也可响应
        }
      }
    }
  }
}

---

获取 ID

获取群组 ID

方法一（推荐）：

1. 启动网关
2. 在群组中 @机器人发消息
3. 运行 openclaw logs --follow 查看日志中的 chat_id

获取用户 ID

方法一：

1. 给机器人发消息
2. 运行 openclaw logs --follow 查看日志中的 open_id

方法二：

openclaw pairing list feishu

---

高级配置

多账号配置

{
  "channels": {
    "feishu": {
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "主机器人"
        },
        "backup": {
          "appId": "cli_yyy",
          "appSecret": "yyy",
          "botName": "备用机器人",
          "enabled": false
        }
      }
    }
  }
}

流式输出

飞书支持实时流式卡片输出：

{
  "channels": {
    "feishu": {
      "streaming": true,
      "blockStreaming": true
    }
  }
}

消息引用

在群聊中引用用户消息：

{
  "channels": {
    "feishu": {
      "replyToMode": "all"  // off / first / all
    }
  }
}

---

常见问题

机器人在群组中不响应

• 检查是否已添加到群组
• 检查是否 @了机器人（默认需要 @提及）
• 检查 groupPolicy 是否为 disabled
• 查看日志：openclaw logs --follow

机器人收不到消息

• 检查应用是否已发布
• 检查事件订阅是否配置 im.message.receive_v1
• 检查是否选择了长连接模式
• 检查网关是否运行：openclaw gateway status

发送消息失败

• 检查应用是否有 im:message:send_as_bot 权限
• 检查应用是否已发布

---