cc-haha 微信接入实战指南:扫码绑定、配对授权与会话管理完整解析
cc-haha 微信接入实战指南:扫码绑定、配对授权与会话管理完整解析
微信接入(WeChat Integration)是 cc-haha 项目中一个极具特色的 IM 通道:它不需要注册任何开发者平台,用户在桌面端 Settings → IM Adapters 里扫一次二维码即可让机器人账号登录,随后通过六位配对码完成个人授权,直接在微信私聊中驱动 Claude Code 完成项目选择、会话管理与工具审批。读完本文,你将掌握从扫码绑定、配对授权、命令使用到源码级运行原理(长轮询收消息、3500 字分片发送、输入状态心跳、AES 加密附件解密)的完整链路。
微信接入的能力边界与适用场景
在 cc-haha 的八类 IM 适配器中(Telegram、Feishu、WeChat、DingTalk、WhatsApp、WeCom、QQ、Slack),微信是"零平台注册"方案的典型代表:绑定机器人的完整流程就是一次二维码扫描,没有 AppID、AppSecret、回调 URL 或审核流程。
代价体现在两处(见 docs/en/im/wechat.md 开头):
- 权限审批只能靠文本回复,无法像部分平台那样渲染可点击的按钮卡片;
- 只支持私聊(private chats),群聊消息不在处理范围内。
作为补偿,微信通道支持的消息类型相当丰富:纯文本、语音转写文本(voice transcription)、图片、文件附件均可进入模型输入。
从源码看,这一能力边界与 protocol.ts 中的消息结构一一对应:extractWechatText() 会优先提取 type === 1 的文本项,其次读取 type === 3 的语音转写文本,而 collectWechatMediaCandidates() 则负责识别 type === 2 的图片与 type === 4 的文件,详见 adapters/wechat/protocol.ts 与 adapters/wechat/media.ts。
第一步:扫码绑定机器人账号
绑定流程全部在桌面端完成,具体步骤:
- 打开 Settings → IM Adapters,切换到 WeChat 标签页;
- 点击 Scan to Bind(扫码绑定);
- 用微信扫描二维码,并在手机上确认登录;
- 等待状态变为 WeChat is bound(微信已绑定)。
绑定成功后,凭据会自动写入本地配置,适配器自行重启,无需手动保存。之后标签页会提供 Rescan(重新扫码) 与 Unbind WeChat account(解绑微信账号) 两个操作。
需要特别强调的是:绑定机器人账号 ≠ 允许所有微信联系人使用。谁可以使用由下一步的配对码决定。
源码视角:二维码登录协议
protocol.ts 完整封装了微信 iLink 开放协议,默认网关为 https://ilinkai.weixin.qq.com(WECHAT_DEFAULT_BASE_URL),登录链路包含两个核心调用:
startWechatLoginWithQr()请求ilink/bot/get_bot_qrcode获取二维码数据;pollWechatLoginWithQr()轮询ilink/bot/get_qrcode_status,返回状态机为wait → scaned → confirmed,中间可能经过scaned_but_redirect(此时会把currentApiBaseUrl切换为服务端下发的redirect_host,实现网关跳转),超时则进入expired。
两个值得注意的常量:
- 二维码有效期(
QR_LOGIN_TTL_MS)为 5 分钟,过期后需要重新生成——这正是文档 Troubleshooting 中"QR code expired"一节的由来; - 请求头会携带模拟客户端的
iLink-App-Id: bot与iLink-App-ClientVersion(由buildClientVersion('2.1.7')按大/小/补丁号编码为 24 位整数),测试用例 adapters/wechat/tests/protocol.test.ts 验证了2.1.7 → (2 << 16) | (1 << 8) | 7的编码结果。
第二步:授权用户——配对码与白名单
扫码只完成了"机器人能登录",任何人能否使用取决于授权:
- 回到页面顶部,在 Pairing(配对) 区域点击 Generate Code(生成配对码);
- 把生成的 六位配对码 发给已绑定的微信机器人;
- 配对确认后,即可直接发消息对话。
配对码规则(见 docs/en/im/wechat.md):
- 有效期为 60 分钟;
- 一次性使用,配对成功后立即失效;
- 生成新码会使旧码立即作废。
另一种方式是白名单:已知的微信用户 ID 可直接填入 Allowed Users(允许用户),用逗号分隔。这种方式适合固定名单,但灵活性不如配对码。
源码视角:配对实现的工程细节
配对逻辑集中在 adapters/common/pairing.ts:
- 字符集安全设计:配对码从
ABCDEFGHJKMNPQRSTUVWXYZ23456789中随机抽取,刻意排除了易混淆的0/O/1/I/L; - 防爆破限流:每个用户 ID 在 5 分钟窗口内最多允许 5 次失败尝试(
RATE_LIMIT_MAX_ATTEMPTS = 5),超限后tryPair()直接返回 false; - 大小写与空格容错:比对时对输入做
trim().toUpperCase(); - 持久化原子写:配对结果写入
~/.claude/adapters.json,采用"先写临时文件再renameSync"的方式保证原子性,文件权限为0o600; - 一次性语义:配对成功后把
file.pairing重置为{ code: null, expiresAt: null, createdAt: null },从机制上保证码不可复用。
授权判定 isAllowedUser() 的语义是 allowedUsers 与 pairedUsers 的并集,且默认关闭——当两者都为空时任何用户都会被拒绝,必须先配对。
项目与会话:默认目录、项目选择与持久化
机器人收到第一条消息时如何确定工作目录,取决于是否配置了 Default Project(默认项目):
- 已设置 Default Project:第一条被接受的消息直接在该目录下打开会话;
- 未设置:机器人会列出最近的项目(最多 10 个,含分支名与真实路径,见
index.ts的showProjectPicker()),用户回复编号、项目名或绝对路径即可选择。
会话行为规则:
- 同一聊天中的后续消息复用该会话;
- 会话映射在桌面端重启后依然有效;
/new用于切换项目;/clear只清空上下文,保留项目绑定。
源码视角:会话绑定如何跨重启存活
这依赖两个持久化组件:
SessionStore(adapters/common/session-store.ts):把chatId → { sessionId, workDir, updatedAt }写入~/.claude/adapter-sessions.json,采用读后刷新(refresh())+ 原子写;restoreStoredSessionBinding()(adapters/common/session-recovery.ts)在启动或新消息到达时恢复绑定;WsBridge(adapters/common/ws-bridge.ts):维护chatId → sessionId的 WebSocket 连接,默认连到桌面端服务ws://127.0.0.1:3456,带 30 秒心跳与指数退避重连(1s → 30s,最多 10 次),并通过按 chatId 串行化的 handler 链避免消息处理竞态。
/new <查询> 的目标解析由 httpClient.matchProject() 完成:精确匹配项目名、编号或绝对路径;若匹配到多个项目会要求进一步精确,无匹配则提示 发送 /projects 查看完整列表。
命令参考
微信没有可配置的菜单,聊天框是唯一入口。配对成功后机器人会建议发送 /help。完整命令如下(中文别名与英文等价):
| 命令 | 中文别名 | 作用 |
|---|---|---|
/help |
帮助 |
显示可用命令 |
/status |
状态 |
显示项目、分支、模型、运行状态与任务摘要 |
/projects |
项目列表 |
重新列出最近项目 |
/new |
新会话 |
清除当前绑定并选择项目 |
/new <编号、项目名或绝对路径> |
— | 直接在该项目中新建会话 |
/clear |
清空 |
清空上下文,保留项目绑定 |
/stop |
停止 |
停止当前生成 |
源码视角:命令分发与状态报告
- 命令路由在
routeUserMessage()(adapters/wechat/index.ts)中完成:/help、/status、/projects、/new、/stop、/clear均有独立分支,且全部要求无附件(!hasAttachments前置判断); /status的数据来源是buildStatusText():通过httpClient.getGitInfo()取仓库名与分支,通过getTasksForSession()统计 pending / in_progress / completed 任务数,最终由formatImStatus()(adapters/common/format.ts)渲染为多行文本,包含模型名与运行时状态(思考中 / 生成中 / 执行工具中 / 等待权限确认 / 空闲);/clear实现为通过桥接发送"/clear"控制消息给桌面端会话,而不是本地清内存;/stop调用bridge.sendStopGeneration()向会话发送停止信号。
权限审批:文本回复代替按钮
由于微信无法渲染可点击按钮,权限请求会以包含 request ID 的文本形式送达。三种审批方式:
/allow <requestId>— 允许一次/always <requestId>— 持久化该匹配规则的审批(永久允许)/deny <requestId>— 拒绝
源码视角:审批解析与快捷输入
- 请求到达时,
handleServerMessage()收到permission_request事件,把requestId加入待审批集合,并发送formatPermissionRequest()+formatPermissionInstructions()两段文本(含工具名与输入预览); - 用户回复由
parsePermissionCommand()(adapters/common/permission.ts)解析,正则^\/(allow|always|allow-always|deny)\s+(\S+)提取动作与 ID; - 当只有一个待审批请求时,还支持快捷输入:
1/y/yes/允许表示允许一次,2/always/永久允许表示永久允许,3/n/no/拒绝表示拒绝; - 决策通过
bridge.sendPermissionResponse(chatId, requestId, allowed, rule)回传桌面端,并同步递减待审批计数、从集合中移除该 ID。
消息收发与附件处理的底层机制
文档描述的行为——长轮询收消息、长回复分片、输入状态指示、图片内联、文件下载到本地临时目录、超大附件回执——在源码中均有精确实现:
- 长轮询:
pollLoop()循环调用getWechatUpdates()(ilink/bot/getupdates),单次超时 35 秒(GET_UPDATES_TIMEOUT_MS),通过get_updates_buf游标增量拉取;异常时退避 3 秒重试。消息去重由MessageDedup(adapters/common/message-dedup.ts)以message_id:seq:create_time_ms为键完成,TTL 10 分钟、容量上限 5000 条; - 长回复分片:
sendText()用splitMessage(text, 3500)(WECHAT_TEXT_LIMIT = 3500字符)切分,优先在段落、换行、句号边界断开(见format.ts的splitMessage());流式输出先进入 3 秒 / 200 字符的MessageBuffer攒批(getBlockBuffer()),message_complete时统一 flush; - 输入状态指示:
WechatTypingController(adapters/wechat/typing.ts)在thinking、tool_executing等状态时启动,每 5 秒发送一次sendtyping心跳(微信输入态会快速过期),回合结束发送cancel;测试用例 adapters/wechat/tests/typing.test.ts 验证了"立即发送 + 持续保活 + 停止时 cancel"以及"同一聊天不重复创建定时器"两个行为; - 图片内联:图片经
downloadCandidate()下载、AES-128-ECB 解密(图片的aeskey需从 hex 转为 base64,文件则直接使用 base64 key)后转为 base64 内联进AttachmentRef,由服务端写入~/.claude/uploads/{sessionId}/并转换为ImageBlockParam; - 文件落地:非图片文件写入
AttachmentStore解析出的本地路径(~/.claude/im-downloads/wechat/{sessionId}/),以@"path"形式注入提示词;24 小时后自动 GC; - 附件限制:
checkAttachmentLimit()强制单张图片 ≤ 10 MB、单个文件 ≤ 30 MB,超限直接拒收并在聊天里给出提示;下载失败的附件也会收到明确回执(N 个附件下载失败,已跳过); - CDN 兜底:当媒体缺
full_url时,用encrypt_query_param拼接默认 CDNhttps://findermp.video.qq.com/251/20304/stodownload下载。
解绑:两级操作
文档明确区分两个层级的解绑:
- Unbind WeChat account(解绑微信账号):清除机器人凭据以及该平台的全部授权列表(白名单 + 配对用户),之后需重新扫码绑定;
- Unbind(解绑单个用户):在 Paired Users 列表中对应名字旁的操作,只撤销该用户,此人之后需要重新获取配对码。
从源码运行与开发
打包版桌面端会自动拉起 sidecar(微信适配器进程);只有从源码开发时才需要手动运行:
cd adapters
bun install
bun run wechat
可选环境变量覆盖(默认值以源码为准):
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"
正常桌面端使用无需设置任何环境变量——扫码绑定会直接写入本地配置。
源码视角:配置加载优先级
配置加载逻辑见 adapters/common/config.ts,优先级为 环境变量 > ~/.claude/adapters.json > 默认值。微信相关字段完整列表:
| 字段 | 环境变量 | 说明 |
|---|---|---|
wechat.accountId |
WECHAT_ACCOUNT_ID |
扫码绑定返回的机器人账号 ID |
wechat.botToken |
WECHAT_BOT_TOKEN |
机器人令牌(请求头 Authorization: Bearer ...) |
wechat.baseUrl |
WECHAT_BASE_URL |
iLink 网关,默认 https://ilinkai.weixin.qq.com |
wechat.userId |
WECHAT_USER_ID |
扫码登录返回的用户 ID |
wechat.allowedUsers |
— | 白名单(逗号分隔) |
wechat.pairedUsers |
— | 已配对用户列表 |
wechat.defaultWorkDir |
— | 默认工作目录 |
wechat.allowedProjectRoots |
— | 允许访问的项目根目录边界 |
此外,loadConfig() 启动时若发现 wechat.botToken 或 wechat.accountId 缺失,会直接报错退出并提示先扫码绑定(对应 Troubleshooting 中的"adapter reports a missing WeChat account")。
常见问题排查
扫码成功后仍提示未授权。 这是预期行为。扫码只保存机器人凭据,个人用户仍需发送配对码或进入 Allowed Users。
二维码过期。 点击 Scan to Bind 重新生成。微信登录二维码寿命很短(源码中 QR_LOGIN_TTL_MS 为 5 分钟)。
适配器报"缺少微信账号"。 说明环境变量或 ~/.claude/adapters.json 中的 wechat.accountId / wechat.botToken 均未生效。先在 Settings 中完成扫码绑定。
没有回复。 依次确认:桌面端正在运行;标签页显示 WeChat is bound;发送者已配对或在白名单中;~/.claude/adapters.json 可写。源码运行时还要确认 ADAPTER_SERVER_URL 指向正在运行的桌面端服务。
重启后会话未恢复。 检查 ~/.claude/adapter-sessions.json 是否可写,以及该会话是否仍存在于桌面端。
源码地图
微信适配器的完整实现路径:
- 协议层:adapters/wechat/protocol.ts — iLink 二维码登录、getupdates 长轮询、sendmessage / getconfig / sendtyping 协议封装与消息结构解析;
- 主逻辑:adapters/wechat/index.ts — 消息路由、命令分发、权限审批、会话管理、附件收集;
- 媒体处理:adapters/wechat/media.ts — 图片/文件候选提取、CDN 下载、AES-128-ECB 解密与落地;
- 输入状态:adapters/wechat/typing.ts — 5 秒心跳的 typing 控制器;
- 测试:adapters/wechat/tests/protocol.test.ts、adapters/wechat/tests/typing.test.ts;
- 公共支撑:adapters/common/pairing.ts(配对码)、adapters/common/session-store.ts(会话持久化)、adapters/common/ws-bridge.ts(WebSocket 桥接)、adapters/common/http-client.ts(桌面端 HTTP API)、adapters/common/config.ts(配置加载)、adapters/common/format.ts 与 adapters/common/permission.ts(格式化与权限解析)。
运行 cd adapters && bun test wechat/ 可复现协议与输入状态相关的全部单元测试。