cc-haha 微信接入实战指南:扫码绑定、配对授权与会话管理完整解析

原创2026-09-21 16:20:541,987 阅读
文章标签:人工智能AI 应用AI Agent代码智能体工具调用MCP ClientsAgent 编排Agent 工作流桌面应用移动开发前端GUI 自动化AI 技能后端Vibe Coding

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。

第一步:扫码绑定机器人账号

绑定流程全部在桌面端完成,具体步骤:

  1. 打开 Settings → IM Adapters,切换到 WeChat 标签页;
  2. 点击 Scan to Bind(扫码绑定);
  3. 用微信扫描二维码,并在手机上确认登录;
  4. 等待状态变为 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 的编码结果。

第二步:授权用户——配对码与白名单

扫码只完成了"机器人能登录",任何人能否使用取决于授权:

  1. 回到页面顶部,在 Pairing(配对) 区域点击 Generate Code(生成配对码);
  2. 把生成的 六位配对码 发给已绑定的微信机器人;
  3. 配对确认后,即可直接发消息对话。

配对码规则(见 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 拼接默认 CDN https://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 是否可写,以及该会话是否仍存在于桌面端。

源码地图

微信适配器的完整实现路径:

运行 cd adapters && bun test wechat/ 可复现协议与输入状态相关的全部单元测试。

登录后查看全文
cc-haha