--- read_when: - 你想连接一个飞书/Lark 机器人 - 你正在配置飞书渠道 summary: 飞书机器人概览、功能和配置 title: 飞书 x-i18n: generated_at: "2026-03-16T06:21:11Z" model: gpt-5.4 provider: openai source_hash: 951e78c5c7264471382f863fa896a15ddeaf0717ef782da20d0f1b3eb23396ba source_path: channels/feishu.md workflow: 15 --- # 飞书机器人 飞书（Lark）是企业用于消息沟通与协作的团队聊天平台。此插件通过平台的 WebSocket 事件订阅将 OpenClaw 连接到飞书/Lark 机器人，因此无需暴露公共 webhook URL 即可接收消息。 --- ## 捆绑插件 飞书随当前的 OpenClaw 版本一同捆绑提供，因此无需单独安装插件。 如果你使用的是较旧版本，或使用了不包含捆绑飞书的自定义安装，请手动安装： ```bash openclaw plugins install @openclaw/feishu ``` --- ## 快速开始 有两种方式可添加飞书渠道： ### 方法 1：设置向导（推荐） 如果你刚安装 OpenClaw，请运行设置向导： ```bash openclaw onboard ``` 向导会引导你完成以下步骤： 1. 创建飞书应用并收集凭证 2. 在 OpenClaw 中配置应用凭证 3. 启动 Gateway 网关 ✅ **配置完成后**，检查 Gateway 网关状态： - `openclaw gateway status` - `openclaw logs --follow` ### 方法 2：CLI 设置 如果你已经完成初始安装，可通过 CLI 添加该渠道： ```bash openclaw channels add ``` 选择 **Feishu**，然后输入 App ID 和 App Secret。 ✅ **配置完成后**，管理 Gateway 网关： - `openclaw gateway status` - `openclaw gateway restart` - `openclaw logs --follow` --- ## 第 1 步：创建飞书应用 ### 1. 打开飞书开放平台 访问 [Feishu Open Platform](https://open.feishu.cn/app) 并登录。 Lark（国际版）租户应使用 [https://open.larksuite.com/app](https://open.larksuite.com/app)，并在飞书配置中设置 `domain: "lark"`。 ### 2. 创建应用 1. 点击 **Create enterprise app** 2. 填写应用名称和描述 3. 选择应用图标 ![Create enterprise app](../images/feishu-step2-create-app.png) ### 3. 复制凭证 在 **Credentials & Basic Info** 中，复制： - **App ID**（格式：`cli_xxx`） - **App Secret** ❗ **重要：**请将 App Secret 妥善保密。 ![Get credentials](../images/feishu-step3-credentials.png) ### 4. 配置权限 在 **Permissions** 中，点击 **Batch import** 并粘贴： ```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:read", "cardkit:card:write", "contact:user.employee_id:readonly", "corehr:file:download", "event:ip_list", "im:chat.access_event.bot_p2p_chat:read", "im:chat.members:bot_access", "im:message", "im:message.group_at_msg:readonly", "im:message.p2p_msg:readonly", "im:message:readonly", "im:message:send_as_bot", "im:resource" ], "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"] } } ``` ![Configure permissions](../images/feishu-step4-permissions.png) ### 5. 启用机器人能力 在 **App Capability** > **Bot** 中： 1. 启用机器人能力 2. 设置机器人名称 ![Enable bot capability](../images/feishu-step5-bot-capability.png) ### 6. 配置事件订阅 ⚠️ **重要：**在设置事件订阅前，请确保： 1. 你已经为飞书运行过 `openclaw channels add` 2. Gateway 网关正在运行（`openclaw gateway status`） 在 **Event Subscription** 中： 1. 选择 **Use long connection to receive events**（WebSocket） 2. 添加事件：`im.message.receive_v1` ⚠️ 如果 Gateway 网关未运行，长连接设置可能无法保存。 ![Configure event subscription](../images/feishu-step6-event-subscription.png) ### 7. 发布应用 1. 在 **Version Management & Release** 中创建版本 2. 提交审核并发布 3. 等待管理员批准（企业应用通常会自动批准） --- ## 第 2 步：配置 OpenClaw ### 使用向导配置（推荐） ```bash openclaw channels add ``` 选择 **Feishu**，然后粘贴你的 App ID 和 App Secret。 ### 通过配置文件进行配置 编辑 `~/.openclaw/openclaw.json`： ```json5 { channels: { feishu: { enabled: true, dmPolicy: "pairing", accounts: { main: { appId: "cli_xxx", appSecret: "xxx", botName: "My AI assistant", }, }, }, }, } ``` 如果你使用 `connectionMode: "webhook"`，请同时设置 `verificationToken` 和 `encryptKey`。飞书 webhook 服务器默认绑定到 `127.0.0.1`；只有在你明确需要不同绑定地址时，才设置 `webhookHost`。 #### Verification Token 和 Encrypt Key（webhook 模式） 使用 webhook 模式时，请在配置中同时设置 `channels.feishu.verificationToken` 和 `channels.feishu.encryptKey`。获取这些值的方法如下： 1. 在飞书开放平台中，打开你的应用 2. 前往 **Development** → **Events & Callbacks**（开发配置 → 事件与回调） 3. 打开 **Encryption** 标签页（加密策略） 4. 复制 **Verification Token** 和 **Encrypt Key** 下图展示了 **Verification Token** 的位置。**Encrypt Key** 位于同一个 **Encryption** 区域中。 ![Verification Token location](../images/feishu-verification-token.png) ### 通过环境变量配置 ```bash export FEISHU_APP_ID="cli_xxx" export FEISHU_APP_SECRET="xxx" ``` ### Lark（国际版）域名 如果你的租户位于 Lark（国际版），请将域名设置为 `lark`（或完整域名字串）。你可以在 `channels.feishu.domain` 设置，也可以按账户设置（`channels.feishu.accounts..domain`）。 ```json5 { channels: { feishu: { domain: "lark", accounts: { main: { appId: "cli_xxx", appSecret: "xxx", }, }, }, }, } ``` ### 配额优化标志 你可以使用两个可选标志来减少飞书 API 使用量： - `typingIndicator`（默认 `true`）：设为 `false` 时，跳过“正在输入”反应调用。 - `resolveSenderNames`（默认 `true`）：设为 `false` 时，跳过发送者资料查询调用。 你可以在顶层或按账户进行设置： ```json5 { channels: { feishu: { typingIndicator: false, resolveSenderNames: false, accounts: { main: { appId: "cli_xxx", appSecret: "xxx", typingIndicator: true, resolveSenderNames: false, }, }, }, }, } ``` --- ## 第 3 步：启动并测试 ### 1. 启动 Gateway 网关 ```bash openclaw gateway ``` ### 2. 发送测试消息 在飞书中找到你的机器人并发送一条消息。 ### 3. 批准配对 默认情况下，机器人会回复一个配对码。批准它： ```bash openclaw pairing approve feishu ``` 批准后，你就可以正常聊天了。 --- ## 概览 - **飞书机器人渠道**：由 Gateway 网关管理的飞书机器人 - **确定性路由**：回复始终返回到飞书 - **会话隔离**：私信共享主会话；群组彼此隔离 - **WebSocket 连接**：通过飞书 SDK 建立长连接，无需公共 URL --- ## 访问控制 ### 私信 - **默认**：`dmPolicy: "pairing"`（未知用户会收到配对码） - **批准配对**： ```bash openclaw pairing list feishu openclaw pairing approve feishu ``` - **Allowlist 模式**：设置 `channels.feishu.allowFrom`，填入允许的 Open ID ### 群聊 **1. 群组策略**（`channels.feishu.groupPolicy`）： - `"open"` = 允许群组中的所有人（默认） - `"allowlist"` = 仅允许 `groupAllowFrom` - `"disabled"` = 禁用群消息 **2. 提及要求**（`channels.feishu.groups..requireMention`）： - `true` = 需要 @ 提及（默认） - `false` = 无需提及也会回复 --- ## 群组配置示例 ### 允许所有群组，要求 @ 提及（默认） ```json5 { channels: { feishu: { groupPolicy: "open", // Default requireMention: true }, }, } ``` ### 允许所有群组，无需 @ 提及 ```json5 { channels: { feishu: { groups: { oc_xxx: { requireMention: false }, }, }, }, } ``` ### 仅允许特定群组 ```json5 { channels: { feishu: { groupPolicy: "allowlist", // Feishu group IDs (chat_id) look like: oc_xxx groupAllowFrom: ["oc_xxx", "oc_yyy"], }, }, } ``` ### 限制哪些发送者可以在群组中发消息（发送者 allowlist） 除了允许群组本身外，该群组中的**所有消息**还会按发送者 `open_id` 进行限制：只有列在 `groups..allowFrom` 中的用户，其消息才会被处理；其他成员发送的消息会被忽略（这是完整的发送者级限制，而不只是对 `/reset` 或 `/new` 等控制命令生效）。 ```json5 { channels: { feishu: { groupPolicy: "allowlist", groupAllowFrom: ["oc_xxx"], groups: { oc_xxx: { // Feishu user IDs (open_id) look like: ou_xxx allowFrom: ["ou_user1", "ou_user2"], }, }, }, }, } ``` --- ## 获取群组/用户 ID ### 群组 ID（`chat_id`） 群组 ID 看起来像 `oc_xxx`。 **方法 1（推荐）** 1. 启动 Gateway 网关并在群里 @ 提及机器人 2. 运行 `openclaw logs --follow` 并查找 `chat_id` **方法 2** 使用飞书 API 调试器列出群聊。 ### 用户 ID（`open_id`） 用户 ID 看起来像 `ou_xxx`。 **方法 1（推荐）** 1. 启动 Gateway 网关并向机器人发送私信 2. 运行 `openclaw logs --follow` 并查找 `open_id` **方法 2** 检查配对请求中的用户 Open ID： ```bash openclaw pairing list feishu ``` --- ## 常用命令 | Command | Description | | --------- | -------------- | | `/status` | 显示机器人状态 | | `/reset` | 重置会话 | | `/model` | 显示/切换模型 | > 注意：飞书暂不支持原生命令菜单，因此命令必须以文本形式发送。 ## Gateway 网关管理命令 | Command | Description | | -------------------------- | -------------------------- | | `openclaw gateway status` | 显示 Gateway 网关状态 | | `openclaw gateway install` | 安装/启动 Gateway 网关服务 | | `openclaw gateway stop` | 停止 Gateway 网关服务 | | `openclaw gateway restart` | 重启 Gateway 网关服务 | | `openclaw logs --follow` | 跟踪 Gateway 网关日志 | --- ## 故障排除 ### 机器人在群聊中没有响应 1. 确保机器人已加入群组 2. 确保你 @ 提及了机器人（默认行为） 3. 检查 `groupPolicy` 未设置为 `"disabled"` 4. 检查日志：`openclaw logs --follow` ### 机器人未接收到消息 1. 确保应用已发布并获批准 2. 确保事件订阅包含 `im.message.receive_v1` 3. 确保已启用**长连接** 4. 确保应用权限完整 5. 确保 Gateway 网关正在运行：`openclaw gateway status` 6. 检查日志：`openclaw logs --follow` ### App Secret 泄露 1. 在飞书开放平台中重置 App Secret 2. 在你的配置中更新 App Secret 3. 重启 Gateway 网关 ### 消息发送失败 1. 确保应用具有 `im:message:send_as_bot` 权限 2. 确保应用已发布 3. 查看日志以获取详细错误信息 --- ## 高级配置 ### 多账户 ```json5 { channels: { feishu: { defaultAccount: "main", accounts: { main: { appId: "cli_xxx", appSecret: "xxx", botName: "Primary bot", }, backup: { appId: "cli_yyy", appSecret: "yyy", botName: "Backup bot", enabled: false, }, }, }, }, } ``` `defaultAccount` 用于控制当出站 API 未显式指定 `accountId` 时，使用哪个飞书账户。 ### 消息限制 - `textChunkLimit`：出站文本分块大小（默认：2000 个字符） - `mediaMaxMb`：媒体上传/下载限制（默认：30 MB） ### 流式传输 飞书通过交互式卡片支持流式回复。启用后，机器人会在生成文本时更新卡片。 ```json5 { channels: { feishu: { streaming: true, // 启用流式卡片输出（默认 true） blockStreaming: true, // 启用分块流式传输（默认 true） }, }, } ``` 将 `streaming: false` 设为等待完整回复生成后再发送。 ### ACP 会话 飞书支持以下 ACP 场景： - 私信 - 群组话题会话 飞书 ACP 由文本命令驱动。没有原生斜杠命令菜单，因此请直接在会话中使用 `/acp ...` 消息。 #### 持久化 ACP 绑定 使用顶层类型化 ACP 绑定，将飞书私信或话题会话固定到持久化 ACP 会话。 ```json5 { agents: { list: [ { id: "codex", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, }, ], }, bindings: [ { type: "acp", agentId: "codex", match: { channel: "feishu", accountId: "default", peer: { kind: "direct", id: "ou_1234567890" }, }, }, { type: "acp", agentId: "codex", match: { channel: "feishu", accountId: "default", peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" }, }, acp: { label: "codex-feishu-topic" }, }, ], } ``` #### 从聊天中按线程绑定 ACP 生成 在飞书私信或话题会话中，你可以就地生成并绑定一个 ACP 会话： ```text /acp spawn codex --thread here ``` 说明： - `--thread here` 适用于私信和飞书话题。 - 绑定后的私信/话题中的后续消息会直接路由到该 ACP 会话。 - v1 不支持针对通用的非话题群聊。 ### 多智能体路由 使用 `bindings` 将飞书私信或群组路由到不同的智能体。 ```json5 { agents: { list: [ { id: "main" }, { id: "clawd-fan", workspace: "/home/user/clawd-fan", agentDir: "/home/user/.openclaw/agents/clawd-fan/agent", }, { id: "clawd-xi", workspace: "/home/user/clawd-xi", agentDir: "/home/user/.openclaw/agents/clawd-xi/agent", }, ], }, bindings: [ { agentId: "main", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxx" }, }, }, { agentId: "clawd-fan", match: { channel: "feishu", peer: { kind: "direct", id: "ou_yyy" }, }, }, { agentId: "clawd-xi", match: { channel: "feishu", peer: { kind: "group", id: "oc_zzz" }, }, }, ], } ``` 路由字段： - `match.channel`：`"feishu"` - `match.peer.kind`：`"direct"` 或 `"group"` - `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） 查找提示请参见 [获取群组/用户 ID](#get-groupuser-ids)。 --- ## 配置参考 完整配置：[Gateway 网关配置](/gateway/configuration) 关键选项： | Setting | Description | Default | | ------------------------------------------------- | -------------------------------- | ---------------- | | `channels.feishu.enabled` | 启用/禁用渠道 | `true` | | `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | | `channels.feishu.connectionMode` | 事件传输模式 | `websocket` | | `channels.feishu.defaultAccount` | 出站路由的默认账户 ID | `default` | | `channels.feishu.verificationToken` | webhook 模式必填 | - | | `channels.feishu.encryptKey` | webhook 模式必填 | - | | `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` | | `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` | | `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` | | `channels.feishu.accounts..appId` | App ID | - | | `channels.feishu.accounts..appSecret` | App Secret | - | | `channels.feishu.accounts..domain` | 按账户覆盖 API 域名 | `feishu` | | `channels.feishu.dmPolicy` | 私信策略 | `pairing` | | `channels.feishu.allowFrom` | 私信 allowlist（`open_id` 列表） | - | | `channels.feishu.groupPolicy` | 群组策略 | `open` | | `channels.feishu.groupAllowFrom` | 群组 allowlist | - | | `channels.feishu.groups..requireMention` | 要求 @ 提及 | `true` | | `channels.feishu.groups..enabled` | 启用群组 | `true` | | `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | | `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | | `channels.feishu.streaming` | 启用流式卡片输出 | `true` | | `channels.feishu.blockStreaming` | 启用分块流式传输 | `true` | --- ## dmPolicy 参考 | Value | Behavior | | ------------- | ---------------------------------------------------- | | `"pairing"` | **默认。**未知用户会收到配对码；必须获批准后才能使用 | | `"allowlist"` | 只有 `allowFrom` 中的用户可以聊天 | | `"open"` | 允许所有用户（要求 `allowFrom` 中有 `"*"`） | | `"disabled"` | 禁用私信 | --- ## 支持的消息类型 ### 接收 - ✅ 文本 - ✅ 富文本（post） - ✅ 图片 - ✅ 文件 - ✅ 音频 - ✅ 视频 - ✅ 贴纸 ### 发送 - ✅ 文本 - ✅ 图片 - ✅ 文件 - ✅ 音频 - ⚠️ 富文本（部分支持）