程序员阿江(Relakkes)
814c02a786
Connecting Feishu meant creating a bot by hand on the open platform and pasting an App ID and App Secret back. Feishu also exposes an RFC 8628 device-authorization flow, so the desktop can now render a QR code, and confirming it in the app creates the bot and stores its credentials directly. `adapters/feishu/registration.ts` implements that protocol rather than importing `registerApp` from `@larksuiteoapi/node-sdk@1.73`: the repository pins 1.60 for the chat client, and the SDK runs the whole poll inside one un-cancellable promise where the desktop needs the stateless begin/poll pair the DingTalk registration already uses. The scan is create-only, so it can never rewrite the configuration of a bot the user already runs, and it pre-fills exactly the scopes, events and callbacks this adapter calls. International tenants finish on Lark's domain, which is now persisted and honoured by the client. WeCom, QQ and Slack join the same session model. WeCom and QQ bind by scanning; Slack has no scan flow, so it uses an app manifest that pre-fills the scopes and Socket Mode. All three run over long connections, so no public callback URL is needed, and all three accept private chats only — pairing authorizes one person, and answering in a group would extend that authorization to everyone else in the room. They are built on a new `adapters/common/chat-runtime.ts` instead of a fourth copy of the loop the five existing adapters each carry. A platform supplies a `ChatPort` — how to say something, how to open a streaming reply, optionally how to send an image — and the runtime owns pairing, command routing, session restore, permission bookkeeping and the translation of the server's stream. The existing five are deliberately left on their own copies; migrating them is a separate change with its own regression surface. Attachments are downloaded through a deferred loader that runs after the pairing gate and inside the per-chat queue. Resolving them eagerly would let an unpaired stranger make the adapter fetch bytes and write them under ~/.claude/im-downloads — on Slack with the bot token attached — and would let a slow attachment overtake a text message sent after it. The sidecar launcher's per-adapter branches become one table. It is declared above the mode dispatch on purpose: `runAdapters` is hoisted and runs at module top level, so a table declared below it is still in its temporal dead zone when the adapters mode reads it — which type checks, lints and unit tests all miss, and only the compiled binary reveals. Verified with the checks `check:impact` selects: adapters, server, desktop, electron, policy, chat-contract, agent-flow, docs, native (sidecar compile, packaging and an adapters-mode smoke against the real binary) and coverage. The scan flows themselves are not verified against live platforms — that needs real WeCom, QQ and Slack accounts and would create real bots. Claude-Session: https://claude.ai/code/session_01CCGoP316AK7wdQG3Ms6Uwq
6.2 KiB
title, nav_title, description, order
| title | nav_title | description | order |
|---|---|---|---|
| 飞书接入 | 飞书 | 在设置页扫码直接创建飞书机器人，在飞书单聊里驱动桌面端并用卡片批权限。 | 1 |
飞书接入
适合国内团队：在桌面端点一下扫码，用飞书扫一扫就把机器人建出来，App ID 和 App Secret 自动写进本机配置。权限审批是可点的交互卡片，还能把常用命令做成机器人菜单。限制是只处理单聊（p2p），不处理群聊；改机器人菜单要回开放平台发一次新版本。
扫码创建机器人
- 打开「设置」→「IM 接入」，切到「飞书」Tab。
- 点「扫码创建」，页面上会出现一张二维码。
- 用飞书扫码。确认页上会预填好机器人的名字、说明，以及这个适配器真正会用到的权限、事件订阅和卡片回调——不多申请一项。
- 确认后 App ID 和 App Secret 会自动写入
~/.claude/adapters.json，适配器随即重启。
二维码 10 分钟内有效，过期后点一下重新生成。绑定成功后按钮变成「重新扫码」，旁边多一个「解除机器人绑定」。
扫码只会新建机器人，不会绑定你已有的那一个——否则这个流程可能悄悄改掉你在跑的机器人的回调配置。
「Encrypt Key」和「Verification Token」留空即可：消息走 WebSocket 长连接，用不到这两个值。
::: tip 也可以手动创建 不想扫码，或者要复用已有机器人，就用官方 OpenClaw 模板建一个，再把 App ID 和 App Secret 填进「飞书」Tab 下方的输入框。桌面端在没有凭据时也会显示这个入口。 :::
给机器人取个名字，点创建。
创建成功后把App ID和App Secret留着，下一步要填进桌面端。
配置机器人菜单
这一步可选，但配了之后在飞书里就能点按钮切项目、开新会话，不用手打命令。
进入飞书开放平台，选中刚创建的机器人。
打开「机器人菜单」。
依次添加三个命令，每个都是一样的填法：菜单名称自定，命令填下面的值。
/projects— 列出最近项目并切换/new— 开一条新会话/clear— 清空当前上下文
三个都加完后保存。
菜单只有发布后才生效，点「创建新版本并发布」。
手动填凭据
扫码创建的机器人不需要这一步——凭据已经写好了。只有用模板手动创建、或者要复用已有机器人时才需要：
- 打开「设置」→「IM 接入」，切到「飞书」Tab。
- 把 App ID 和 App Secret 填进「App ID」和「App Secret」。
- 「Encrypt Key」和「Verification Token」留空即可，长连接模式不需要。
- 需要长时间流式更新同一张卡片时，勾上「流式卡片模式」。
- 点「保存」。
「允许的用户」可以留空。留空时只有完成配对的人能用，这通常就是你想要的。
配对
回到页面顶部的「配对管理」，点「生成配对码」，会出现一枚 6 位码。这一步会立即写入本机配置，不需要再点保存。
在飞书里私聊刚创建的机器人，随便发一条消息，按提示把这枚码发过去。
看到配对成功提示，就可以直接对话了。
配对码 60 分钟内有效、只能用一次，重新生成后旧码立刻作废。
支持的命令
除菜单按钮外，聊天框里随时可以打：
/help或帮助/status或状态/projects或项目列表/new或新会话/clear或清空/stop或停止
权限审批与消息表现
Claude 请求敏感权限时，飞书里会收到一张交互卡片，点「允许」或「拒绝」，结果直接回传给桌面端会话。
普通回复走飞书的富文本消息，流式内容优先原地更新同一条消息，完成后过长的正文会自动分片发送。
本地开发启动
发布版桌面端会自动把 adapter 作为 sidecar 拉起。只有从源码运行或单独调试时才需要手动启动：
cd adapters
bun install
bun run feishu
可选的环境变量覆盖：
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
常见问题
二维码扫了没反应：扫码走 accounts.feishu.cn，确认本机能访问。国际版租户（Lark）在确认后会自动切到 accounts.larksuite.com 完成，不用手动切换。
扫完提示已过期：二维码 10 分钟有效，点「重新扫码」再生成一张。
收不到消息：确认机器人已发布（改过菜单要重新「创建新版本并发布」），以及聊天窗口是和机器人的单聊而不是群。
权限卡片点了没反应：一般是卡片回调能力没随版本发布，回开放平台重新发一次版本。
一直提示未授权：检查配对码是否还在 60 分钟有效期内、发的是不是当前这一枚（重新生成后旧码失效），以及这个飞书账号是否已经出现在桌面端的「已配对用户」列表里。
重启后会话没接回来：检查 ~/.claude/adapter-sessions.json 能否正常写入，以及桌面端里那条会话是否还在。
源码入口
adapters/feishu/index.ts（运行时）、adapters/feishu/registration.ts（扫码创建），以及 adapters/common/ 下的 pairing.ts、session-store.ts、ws-bridge.ts、http-client.ts。