cc-haha 微信接入实战:扫码绑定、配对授权与 iLink 长轮询协议全解析
cc-haha 微信接入实战:扫码绑定、配对授权与 iLink 长轮询协议全解析
导读
本文围绕 cc-haha 的微信 IM 接入链路,完整讲解「扫码绑定机器人账号 → 配对码授权具体用户 → 选择项目开始对话 → 文本命令驱动会话与权限审批」的端到端流程,并深入到 adapters/wechat 与 adapters/common 的源码实现,揭示 iLink 长轮询、6 位一次性配对码、消息分片与附件解密等底层机制。读完本文,你既能照着手册在桌面端 5 分钟内完成接入,也能理解这套 adapter 为什么不需要任何开放平台资质,以及它只面向私聊、依赖文本命令的设计取舍。
微信接入的定位与能力边界
cc-haha 微信接入面向「只想用微信、不愿意再装一个 App」的用户。它的核心卖点是整个接入过程只需要扫一次码,不需要前往任何开放平台申请应用资质——因为 adapter 走的是 iLink 机器人通道,而 iLink 扫码绑定凭据(botToken + accountId)的动作发生在桌面端设置页。
从源码看,这条链路存在三个明确的设计边界:
- 只处理私聊,不面向群聊设计;
routeUserMessage只依据from_user_id逐条路由,没有群消息上下文处理逻辑(见 adapters/wechat/index.ts)。 - 权限审批只能靠回复文本命令,微信没有可配置的菜单或可点击按钮,因此
/allow、/always、/deny三个文本命令承担了审批入口。 - 输入类型有限:除文本外,还支持语音转出的文字、图片和文件附件。语音在
extractWechatText中通过voice_item.text直接以文字进入模型(adapters/wechat/protocol.ts)。
扫码绑定机器人账号
操作步骤
在桌面端完成绑定只需四步:
- 打开「设置」→「IM 接入」,切到「微信」Tab。
- 点击「扫码绑定」。
- 用微信扫描页面上显示的二维码,并在手机上确认登录。
- 等待页面状态变为「微信已绑定」。
绑定成功后,凭据会自动写入本机配置并重启 adapter,不需要再点「保存」。此时 Tab 中会出现「重新扫码」和「解除微信绑定」两个按钮。
需要特别强调:扫码绑定的是机器人账号本身,不等于放行所有微信联系人。谁能使用,还要看下一节的「配对」步骤。
底层实现:iLink 扫码登录协议
扫码绑定并不是黑盒,其完整协议实现在 adapters/wechat/protocol.ts,核心流程是两段式轮询:
- 发起登录:
startWechatLoginWithQr调用ilink/bot/get_bot_qrcode?bot_type=3,拿到qrcode(登录凭证)和qrcode_img_content(二维码图片地址),并记录startedAt时间戳(protocol.ts)。 - 轮询状态:
pollWechatLoginWithQr循环调用ilink/bot/get_qrcode_status?qrcode=...,状态机依次经历wait(等待扫码)→scaned(已扫码,请在微信中确认)→scaned_but_redirect(已扫码,正在切换微信网关)→confirmed(绑定成功,返回bot_token、ilink_bot_id、baseurl等凭据)或expired(二维码过期)。
几个源码级细节值得注意:
- 二维码有效期只有 5 分钟:
QR_LOGIN_TTL_MS = 5 * 60_000,isLoginFresh与purgeExpiredLogins负责清理过期的登录会话(protocol.ts)。所以「二维码提示过期」时,重新点「扫码绑定」生成新码即可。 - 网关会动态切换:微信服务端在扫码后可能返回
redirect_host,此时 adapter 会把后续 API 的currentApiBaseUrl切到https://${redirect_host},这就是「正在切换微信网关」的含义(protocol.ts)。 - 凭据落盘:确认成功后返回的
botToken/accountId会被桌面端写入本机配置(~/.claude/adapters.json的wechat段),并自动重启 adapter。adapter 启动时会校验这两个字段,缺失则直接报错退出(index.ts)。
授权具体用户:配对码与白名单
操作步骤
- 回到页面顶部的「配对管理」,点击「生成配对码」。
- 在微信里把这枚 6 位码发给刚绑定的机器人。
- 看到配对成功提示后即可直接发消息。
配对码有两个硬性约束:60 分钟内有效、只能用一次;重新生成后旧码立刻作废。另外也支持把已知的微信用户 ID 直接填进「允许的用户」(多个用逗号分隔),适合固定白名单场景,但不如配对码直观。
底层实现:配对状态机与暴力破解防护
配对逻辑全部集中在 adapters/common/pairing.ts,包括:
- 6 位安全码生成:
generatePairingCode从字母表ABCDEFGHJKMNPQRSTUVWXYZ23456789中随机取 6 个字符——排除了易混淆的 0/O/1/I/L,降低手动输入出错率(pairing.ts)。 - 一次性使用:
tryPair校验成功后,会把该用户写入pairedUsers并立即清空pairing.code/expiresAt/createdAt,旧码彻底作废(pairing.ts)。 - 速率限制:每个 userId 在 5 分钟内最多失败 5 次,超过后
isRateLimited直接拒绝继续尝试,防暴力枚举(pairing.ts)。 - 授权判定是并集:
isPaired返回pairedUsers与allowedUsers的并集;当两者都为空时默认拒绝一切访问(pairing.ts)。这也是 FAQ 里「扫码成功仍提示未授权」的根本原因——扫码只写入了机器人凭据,授权名单仍为空。
配对码对大小写和首尾空格不敏感(trim().toUpperCase() 后比较),对中文用户友好。
选项目并开始对话
配对成功后,第一条消息的流向取决于是否配置了「默认项目」:
- 配了「默认项目」:第一条消息直接在那个目录下开一条会话。
- 没配:机器人先列出最近用过的项目(最多 10 个,带编号、项目名、分支和绝对路径),回复编号、项目名或绝对路径即可完成选择。
从源码看,这个流程由 SessionSelectionController 与 showProjectPicker 协同完成:showProjectPicker 通过 httpClient.listRecentProjects() 拉取项目列表并渲染为「编号 + 项目名 + 路径」的文本(index.ts),而后续输入会先经过 sessionSelectionController.handleInput 匹配,再进入 startNewSession 用 httpClient.matchProject(query) 精确匹配项目(index.ts)。
会话建立后,同一个聊天窗口的消息会复用同一条会话——绑定关系持久化在 adapter-sessions.json(由 SessionStore 管理),桌面端重启后也能通过 restoreStoredSessionBinding 接回去(index.ts)。
常用的两个会话命令:
/new:清空当前绑定并重新选择项目;/new <编号、项目名或绝对路径>则直接在指定项目下开新会话。/clear:清空上下文但保留项目绑定(adapter 会先发/clear给桌面端会话,再回执确认,见 index.ts)。
支持的命令:聊天框即菜单
微信没有可配置的菜单,命令入口就是聊天框本身。配对成功后机器人会提示发 /help。formatImHelp 维护了一份完整命令清单(adapters/common/format.ts),结合 routeUserMessage 的分发逻辑(index.ts),核心命令如下:
| 命令 | 中文别名 | 作用 |
|---|---|---|
/help |
帮助 |
显示可用命令 |
/status |
状态 |
当前项目、分支、模型、运行状态和任务摘要 |
/projects |
项目列表 |
重新列出最近项目 |
/new |
新会话 |
清空当前绑定并重新选择项目 |
/new <编号、项目名或绝对路径> |
— | 直接在指定项目下开新会话 |
/clear |
清空 |
清空上下文,保留项目绑定 |
/stop |
停止 |
停止本轮生成(通过 bridge.sendStopGeneration 发停止信号) |
/allow <id> |
— | 允许某次权限请求 |
/always <id> |
— | 永久允许同类请求 |
/deny <id> |
— | 拒绝权限请求 |
/status 的实现值得展开:buildStatusText 会先恢复会话绑定,再通过 httpClient.getGitInfo 取仓库名与当前分支、通过 httpClient.getTasksForSession 汇总任务统计,最后交给 formatImStatus 渲染为「项目 / 分支 / 会话 / 模型 / 状态 / 待审批数 / 任务统计」的结构化文本(index.ts);状态标签(思考中、生成中、执行工具中、等待权限确认、空闲)由 format.ts 统一映射。注意:命令仅在不带附件时触发,带附件时会优先按媒体消息处理(index.ts)。
权限审批与消息表现
文本化的权限审批
当 Claude 请求敏感权限时,微信里会收到一条带 request id 的文本消息,形如「需要权限确认 requestId] / 工具: 工具名 / 输入预览」,其格式由 formatPermissionRequest 生成([format.ts)。回复以下任一命令即可完成审批:
/allow <requestId>— 允许这一次/always <requestId>— 永久允许同类请求/deny <requestId>— 拒绝
底层上,handleServerMessage 收到 permission_request 消息后,会把 requestId 加入该聊天的 pendingPermissions 集合并递增 pendingPermissionCount(index.ts);用户回复时 parsePermissionCommand 解析出 {requestId, allowed, rule},校验该 id 确实处于待确认状态后才通过 bridge.sendPermissionResponse 回传桌面端,并同步递减待审批计数(index.ts)。
消息投递机制
- 长轮询收消息:
pollLoop以 35 秒超时调用ilink/bot/getupdates,用get_updates_buf作为游标增量拉取,出错则退避 3 秒重试(index.ts)。 - 分片发送:正文按
WECHAT_TEXT_LIMIT = 3500字符上限分片(index.ts),分片算法优先在段落、换行、句号、空格处切分,保证阅读连贯(format.ts)。发送时携带context_token,失败会自动去掉 token 重发一次(index.ts)。 - 正在输入提示:
WechatTypingController在thinking、tool_executing、streaming期间每 5 秒向微信续一次 typing 状态,轮次结束发cancel(adapters/wechat/typing.ts);typing 依赖getconfig返回的typing_ticket,因此即使没有逐字流式文本,用户也能感知「机器人正在干活」。 - 附件处理:图片会以 base64 内联进模型输入(
type: 'image'),其他文件则以本机临时路径传给会话(type: 'file'+path),超出大小限制时checkAttachmentLimit会让机器人在微信里给出提示(index.ts)。
附件下载与解密
微信 CDN 上的图片/文件是加密存储的,adapters/wechat/media.ts 处理了完整链路:collectWechatMediaCandidates 从消息的 image_item / file_item 提取下载地址与密钥 → WechatMediaService.downloadCandidate 下载字节 → 用 AES-128-ECB 解密(密钥来自消息里的 aeskey)→ 写入 AttachmentStore 管理的工作目录。对应场景的 MIME 类型(png/jpg/gif/webp/pdf/txt)通过扩展名推断(media.ts)。
解除绑定:两种粒度
「解除绑定」支持两种粒度:
- 「解除微信绑定」:清掉整个机器人账号凭据和这个平台的授权名单,之后需要重新扫码。对应
WECHAT_ACCOUNT_ID/WECHAT_BOT_TOKEN从本机配置中清除。 - 「已配对用户」列表中的「解绑」:只撤销那一个人,其他人不受影响。被解绑的人需要重新发一枚新配对码。对应从
pairedUsers数组中移除该用户的userId。
本地开发启动与配置
发布版桌面端会自动把 adapter 作为 sidecar 拉起。只有从源码运行或单独调试时才需要手动启动:
cd adapters
bun install
bun run wechat
bun run wechat 对应 adapters/package.json 中的脚本 bun run wechat/index.ts(adapters/package.json)。
可选的环境变量覆盖(优先级:环境变量 > ~/.claude/adapters.json > 默认值,见 adapters/common/config.ts):
export WECHAT_ACCOUNT_ID="..."
export WECHAT_BOT_TOKEN="..."
export WECHAT_BASE_URL="https://ilinkai.weixin.qq.com"
export WECHAT_USER_ID="..."
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
各变量含义与默认值:
| 环境变量 | 作用 | 默认值 |
|---|---|---|
WECHAT_ACCOUNT_ID |
机器人账号 ID(iLink bot id) | 读 adapters.json,缺失则启动失败 |
WECHAT_BOT_TOKEN |
iLink 机器人令牌 | 读 adapters.json,缺失则启动失败 |
WECHAT_BASE_URL |
iLink API 网关地址 | https://ilinkai.weixin.qq.com |
WECHAT_USER_ID |
机器人的 ilink 用户 ID | 空 |
ADAPTER_SERVER_URL |
桌面端 WebSocket 服务地址 | ws://127.0.0.1:3456 |
补充两个与微信链路直接相关的全局配置:
CLAUDE_CONFIG_DIR:配置文件目录,默认~/.claude(config.ts)。adapters.json存凭据与授权,adapter-sessions.json存会话绑定。ADAPTER_ALLOWED_PROJECT_ROOTS:IM 会话可访问的项目根目录边界(路径分隔符分隔),未配置时默认收窄为「主目录 ∪ 默认项目目录」,且拒绝把/、/Users这类祖先目录当作边界(config.ts)。
正常使用桌面端不需要手动设置这些变量,扫码绑定会写好本机配置。
常见问题排查
扫码成功后发消息仍提示未授权:这是正常流程。扫码只写入机器人账号凭据,具体用户还要发配对码,或被写进「允许的用户」。可对照 adapters.json 里 wechat.allowedUsers / wechat.pairedUsers 是否有该用户的 userId。
二维码提示过期:重新点「扫码绑定」生成新的。微信扫码登录状态只在短时间内有效(源码中 QR_LOGIN_TTL_MS 为 5 分钟)。
adapter 启动时报缺少微信账号:WECHAT_ACCOUNT_ID/WECHAT_BOT_TOKEN 和 ~/.claude/adapters.json 里对应的 wechat.accountId/wechat.botToken 字段都没生效,先在设置页完成扫码绑定。adapter 启动时的校验逻辑见 index.ts。
收不到回复:依次确认:桌面端在运行;Tab 里显示「微信已绑定」;当前用户已配对或在「允许的用户」里;~/.claude/adapters.json 能正常写入;源码运行时还要确认 ADAPTER_SERVER_URL 指向正在运行的桌面服务。
重启后会话没接回来:检查 ~/.claude/adapter-sessions.json 能否正常写入,以及桌面端里那条会话是否还在。会话恢复依赖 restoreStoredSessionBinding 读取 SessionStore 的持久化绑定。
源码入口与测试
微信链路的完整实现分布如下:
- adapters/wechat/index.ts:adapter 主入口——长轮询循环、命令路由、会话管理、权限审批、附件收集。
- adapters/wechat/protocol.ts:iLink 协议层——扫码登录、
getupdates长轮询、sendmessage/sendtyping/getconfig的请求构造与错误断言。 - adapters/wechat/media.ts:微信 CDN 媒体下载、AES-128-ECB 解密与附件落地。
- adapters/wechat/typing.ts:「正在输入」状态的心跳保活。
- adapters/common/pairing.ts:6 位配对码生成、校验、速率限制与授权判定。
- adapters/common/config.ts:配置加载优先级、
adapters.json结构与项目根边界解析。 - adapters/common/format.ts:命令帮助、状态摘要、消息分片与权限消息格式化。
- adapters/common/session-store.ts / adapters/common/ws-bridge.ts / adapters/common/http-client.ts:会话持久化、桌面端 WebSocket 桥与 HTTP 客户端。
测试方面,adapters/wechat/tests/protocol.test.ts 覆盖了客户端版本号编码、纯文本/语音/引用文本抽取、图片与文件媒体候选收集、sendmessage/sendtyping 非零返回码的抛错行为;adapters/wechat/tests/typing.test.ts 覆盖 typing 指示器的启停。运行测试:cd adapters && bun run test:wechat。


