claude-code-router AgentClaw 飞书（Feishu/Lark）接入实战：从企业自建应用到锁屏接力

claude-code-router AgentClaw 飞书（Feishu/Lark）接入实战：从企业自建应用到锁屏接力

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

AgentClaw 是 claude-code-router（CCR）为本地 Agent 提供 IM 接入层的功能：Claude Code、Codex、OpenCode 等 Agent 仍在本机运行、保留工作区与会话，由飞书机器人担任远程入口，让你在电脑锁屏、离开工位后继续查看 Agent 输出并回复。本文基于仓库文档 feishu.md，完整讲解飞书企业自建应用的创建、权限与事件订阅配置，以及在 CCR「Bot 管理」中的接线与验证流程，读完后你可以在飞书群或应用会话中稳定运行自己的本地 Agent，并按需开启「锁屏接力」。

AgentClaw 飞书通道适合谁

飞书通道适合希望在飞书群或应用会话里接收 Agent 消息的团队或个人。CCR 通过App Secret 认证方式连接飞书自建应用：你既可以在工位上实时看到转发过来的 Agent 输出，也可以在离开电脑后通过飞书继续驱动同一台机器上的会话。

若你刚接触 AgentClaw，建议先阅读 AgentClaw 总览 与 使用和配置，再回到本页完成单个平台的接入。

需要说明的边界：AgentClaw 的完整 Bot 转发、接力、Projects/Sessions 等能力，目前只覆盖由 CCR 管理的App 型入口（如 Claude App、Codex/ChatGPT App、OpenCode App、ZCode App、WorkBuddy App）；纯 CLI 型 Agent（如 Claude Code CLI、Codex CLI）可以走 CCR 的模型路由，但不会把 Bot 消息转发到 IM。

你会用到的字段

接入飞书时，CCR 只要求 3 个字段，其中前两个必填：

其中Domain对应的是飞书（中国大陆）与 Lark（海外）这两套不同域名体系的差异。仓库源码也印证了这一设计：在 bot-gateway/env.ts 中，平台名做归一化时会把lark统一归一化为feishu，说明同一套 Bot 网关同时服务于飞书与 Lark，只是底座域不同。

第一步：创建企业自建应用

1. 登录飞书开放平台并进入开发者后台。
2. 点击创建应用。
3. 选择企业自建应用。
4. 填写应用名称（例如CCR）。
5. 填写应用描述并上传图标。
6. 创建应用。

创建时选择「企业自建应用」即可使用 App Secret 认证，这是 CCR 飞书通道默认采用的认证类型。事实上从源码看，飞书（连同钉钉、企业微信）的默认认证方式就是app_secret，见 bot-gateway/env.ts 中defaultBotGatewayAuthType的实现。

第二步：复制 App ID 与 App Secret

1. 打开刚创建的应用。
2. 打开基础信息。
3. 进入凭证与基础信息。
4. 复制App ID。
5. 复制App Secret。

这两个值就是 CCR 里必填的App ID与App Secret。App Secret 相当于应用的访问密钥，不要提交到公开仓库或分享到群里。

第三步：开启机器人能力

1. 在应用后台打开应用能力。
2. 点击添加应用能力。
3. 找到机器人，添加或启用它。
4. 设置机器人名称与头像。

没有开启机器人能力时，飞书聊天窗口可能看不到输入框，也收不到用户消息。这是飞书接入最常见的第一步排查点。

第四步：申请消息权限

1. 打开开发配置。
2. 进入权限管理。
3. 添加「应用身份」权限。
4. 至少开通「读取用户发给机器人的单聊消息」权限。
5. 若需要在群里被 @ 后回复，开通「读取群聊中 @ 机器人的消息」权限。
6. 若要 Agent 能回复消息，开通「以应用身份发送消息」权限。
7. 保存。

不同租户后台的权限显示名称可能略有差异。当你看到im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:message:send_as_bot这类标识时，优先勾选这些消息相关的权限，它们与机器人收发行为直接对应。

这组权限决定了 Bot 网关能读到什么、能回什么：

• im:message.p2p_msg:readonly：读取用户发给机器人的单聊消息；
• im:message.group_at_msg:readonly：读取群聊中被 @ 的消息；
• im:message:send_as_bot：以应用（机器人）身份发送消息。

第五步：配置事件订阅

1. 打开事件与回调。
2. 选择长连接（WebSocket）模式。
3. 添加事件im.message.receive_v1。
4. 保存。

选择长连接模式意味着飞书平台会主动把新消息推送到应用的长连接上，无需为 CCR 提供可被外网访问的回调地址——这与 CCR 本地 Bot 网关的定位一致：事件订阅是 Agent 收到消息后真正进入执行流程的「入口事件」。

第六步：发布或安装应用

1. 打开版本管理与发布，创建新版本。
2. 确认可见范围——测试阶段先选你自己或一个小范围成员即可。
3. 提交发布。
4. 若企业启用了审核机制，需等待审核通过。
5. 在飞书客户端中找到该应用，或把机器人加入目标群。

发布动作决定机器人对哪些成员可用。应用未发布到当前成员的可见范围，往往是「聊天窗口没有输入框」或「机器人没响应」的隐藏原因。

在 CCR 中接入（Bot 管理）

应用在飞书侧就绪后，回到 CCR 界面完成接线：

1. 打开 CCR 的Bot 管理页面，点击添加 Bot。
2. 平台选择飞书（Feishu）。
3. 认证方式选择App Secret。
4. 填写App ID与App Secret。
5. 若使用 Lark 或特殊域环境，填写Domain。
6. 保存该 Bot。
7. 打开Agent 配置，编辑要接 Bot 的 Agent 配置。
8. 打开Bot开关并选择刚保存的 Bot。
9. 按需打开转发 Agent 消息或接力（见下一节）。
10. 从 CCR 重新打开 Agent。

最后一步至关重要：AgentClaw 是「跟随 CCR 托管的 Agent App 生命周期」工作的，只有在 CCR 管理下的 Agent App 存活期间，Bot 才会保持在线。这也是 setup.md 明确要求的入口模式必须包含 App（如App only或CLI & App）的原因。

从实现层面看，把 Bot 挂到 Agent 配置后，CCR 会在启动 Agent 时向 Bot 网关进程注入一组CCR_BOT_GATEWAY_*环境变量（见 bot-gateway/env.ts），其中包括：

• CCR_BOT_GATEWAY_PLATFORM：本次运行的平台，如feishu；
• CCR_BOT_GATEWAY_AUTH_TYPE：认证方式，如app_secret；
• CCR_BOT_GATEWAY_CREDENTIALS_JSON：App ID、App Secret 等凭据；
• CCR_BOT_GATEWAY_CONFIG_JSON：Domain、transport（websocket）等集成配置；
• CCR_BOT_HANDOFF_*系列：接力开关、空闲秒数、屏幕锁/用户空闲判定等。

值得注意的是，env.ts 中resolveBotGatewayConfig会根据打开的 surface 判断：只有当 surface 为app时 Bot 网关才会启用，否则一律把enabled置为false。这从源码上解释了「CLI 单独启动的 Agent 不参与 Bot 转发」这一行为边界。

转发还是接力：两种消息模式

• 转发 Agent 消息（Forward agent messages）：无论锁不锁屏都持续把 Agent 的可见输出转发到飞书。适合需要完整记录、团队观察或远程调试的场景。
• 接力（Handoff）：只在电脑锁屏且经过设定的空闲时间后，才把后续交互转入飞书。配合空闲秒数与目标设备使用。

若只想在锁屏后收到提醒，使用接力即可，不要同时开启转发 Agent 消息，否则工位上的输出也会被镜像进飞书。

接力的判定逻辑在仓库中有明确体现：handoff 配置包含enabled、idleSeconds、screenLock、userIdle等字段（env.ts），空闲秒数默认值为 30。也就是说接力按「屏幕锁 + 用户空闲」双重条件触发；Wi-Fi/蓝牙手机目标仍属于实验性配置，不会影响当前运行时判定。

Agent 进入飞书会话后，可以通过命令切换工作区与会话，例如：

/project list /project use 1 /session list /session use 1

然后直接发送自然语言消息即可驱动 Agent；也可以一句话开启新会话：

/session new 修复登录问题

当 Agent 请求授权或输入时，飞书若支持卡片按钮可直接点击；否则使用文本命令应答：

/session approve /session deny /session answer 使用第二个选项

查看状态与诊断：

/session status /session doctor /session deliveries

按 agentclaw.md 的约定，Bot 只暴露/project与/session两个公共命令域，其余/命令会返回未知命令提示；普通自然语言消息会作为提示词进入 Agent。

测试验证

1. 从 CCR 打开 Agent，触发一条消息。
2. 到飞书确认应用能收到消息并回复。
3. 群内使用前，先把应用加入目标群并确认成员可见。

如何判断接入成功：飞书会话里能看到 Agent 的输出，你在飞书里回复后 Agent 能继续执行。更严谨的验证方式（摘自 setup 文档）包括：在 IM 中发送/project current确认 Bot 在线且能读取当前 Project；发送/session list确认会话列表；发送一条普通消息确认 Agent 会跑并回复；锁屏并等待超过接力空闲秒数后，确认后续 Agent 消息进入飞书。

常见问题与排查

• 认证失败：重新复制 App ID 与 App Secret，确认没有多余空格或串行字符。
• 聊天窗口没有输入框：依次检查机器人能力是否开启、事件订阅是否配置、应用是否发布到当前成员的可见范围。
• 群里没有响应：先 @ 机器人测试，并确认事件订阅包含im.message.receive_v1，同时开通了「读取群聊中 @ 机器人的消息」权限。
• Lark / 特殊域：确认 CCR 中 Domain 填写的是平台实际要求的域名值，避免使用中国大陆飞书默认域。

参考与延伸阅读

• 本主题英文原稿：docs/src/content/docs/en/agentclaw/feishu.md，中文版见 docs/src/content/docs/zh/agentclaw/feishu.md
• AgentClaw 总览（三种模式、支持矩阵、命令域）：docs/src/content/docs/en/agentclaw.md
• AgentClaw 使用与配置总流程：docs/src/content/docs/en/agentclaw/setup.md
• Bot 网关运行时环境变量与平台归一化实现：packages/core/src/agents/bot-gateway/env.ts
• 接力目标设备扫描（Wi-Fi/蓝牙）实现：packages/core/src/agents/bot-gateway/handoff-scan-service.ts

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router