Claude Code Router AgentClaw 微信接入指南：用 QR 扫码登录或 Bot Token 把 Agent 消息推到微信

Claude Code Router AgentClaw 微信接入指南：用 QR 扫码登录或 Bot Token 把 Agent 消息推到微信

【免费下载链接】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）的 IM 中继能力：把 Claude App、Codex/ChatGPT App、OpenCode App 等受管 Agent 会话接到日常聊天窗口里。本文聚焦其中 WeChat（Weixin，微信）平台——即 CCR 中的Weixin iLink——的完整接入流程：推荐走 QR 扫码登录（无需手动复制任何 token），或使用第三方微信机器人服务提供的 Bot Token。读完本文，你可以完成扫码/Token 两种登录、把 Bot 绑定到 Agent Config、配置消息转发或锁屏 Handoff，并能看懂 CCR 源码中扫码会话、平台归一化与 Handoff 扫描的实现细节。

如果你是 AgentClaw 新手，建议先通读 AgentClaw 总览与配置，再回到本文处理微信这一个平台。

Weixin iLink 适合谁

Weixin 平台面向「希望在自己的日常聊天窗口里收到 Agent 消息」的个人用户。最简单的路径是 QR Login：不需要手动复制 token，用手机的微信扫码确认即可。

安全提醒：微信会话与账号安全强绑定——请使用专用的机器人账号，不要用承担支付、客服或重要联系人角色的主账号登录。

源码视角：平台别名归一化

在 UI 里你选择的是Weixin iLink，落到运行时的平台标识是weixin-ilink。从源码结构看，CCR 对平台名做了宽松的别名归一化：wechat、weixin、wx、weixin-ilink、weixin_ilink、ilink这些写法最终都会被标准化为weixin-ilink（见 env.ts 与 config.ts）。而该平台的默认认证方式就是qr_login——这解释了文档中「Choose QR Login (the default)」的说法：

// packages/core/src/config/config.ts function defaultBotGatewayAuthType(platform: string): string { if (platform === "weixin-ilink") { return "qr_login"; } ... }

（参见 config.ts#L193-L207）

方式一：QR Login（推荐）

操作步骤：

1. 打开 CCR 的Bot Management页面，点击Add Bot。
2. 平台选择Weixin iLink。
3. 认证方式选择QR Login（默认项）。
4. CCR 弹出一个二维码窗口。
5. 用手机微信扫码。
6. 在手机上确认登录。
7. 等待 CCR 显示登录成功。
8. 保存该 Bot。

二维码会过期。如果扫码页面提示已过期，关闭登录窗口重新发起即可。

扫码流程的源码级拆解

扫码窗口与扫码会话由两个模块协作完成：

1）桌面端二维码窗口。Electron 主进程中的 bot-gateway-qr-window-service.ts 会创建一个 460×760 的独立BrowserWindow（标题默认为 "Weixin Login"），窗口以sandbox: true、nodeIntegration: false的沙箱模式运行，且只允许加载 http/https 的扫码 URL，窗口内跳转一律交给系统浏览器。这与文档里「CCR opens a QR code window」「close the login window and start over」的操作一一对应。

2）扫码会话生命周期。核心逻辑在 qr-login-service.ts：

• startBotGatewayQrLogin首先强制校验「微信扫码登录只支持微信平台的扫码认证方式」（L54-L56），即platform必须是weixin-ilink且authType为qr_login，否则直接抛错；
• 随后通过 bot-gateway SDK 的 stdio 子进程客户端调用auth.qr.start，拿到sessionId和qrCodeUrl，并把会话注册进内存中的qrSessions；再次发起扫码时旧会话的客户端会被自动关闭，避免悬挂进程；
• UI 侧通过waitBotGatewayQrLogin轮询auth.qr.wait，状态为confirmed即登录成功；状态落入终止态（already_bound、confirmed、expired、failed，见 L534-L536）后，会话会被清理、客户端被关闭——这就是「二维码过期后必须重新生成」的机制来源；
• 若没有现成的 integration，服务会按integrations.list在同租户（默认ccr）下查找已有weixin-ilinkintegration 复用，否则生成weixin-ilink-<tenant>形式的 integrationId（L325-L360）。

3）登录成功后的凭据落点。扫码产生的会话凭据保存在本地状态目录。从源码看，若未显式配置stateDir，默认路径为 CCR 配置目录下的bot-gateway/<profile-slug>（env.ts#L275-L282），这也是排查「扫完码掉线」问题时值得检查的位置。

方式二：Bot Token

只有当你已经从外部微信机器人服务、iLink 服务或本地插件拿到了 token 时才使用此方式：

1. 从服务商控制台或本地插件输出中复制Bot Token。
2. 如果服务商还给了Account ID，一并复制。
3. 如果给了User ID，也复制下来。
4. 打开 CCR 的Bot Management，点击Add Bot。
5. 平台选Weixin iLink，认证方式选Bot Token。
6. 填入Bot Token，如有则填Account ID/User ID。
7. 保存 Bot。

表单字段的源码印证

UI 中 Weixin iLink 的认证字段定义见 profiles.ts#L199-L215：

{ value: "weixin-ilink", label: "Weixin iLink", auth: [ { value: "qr_login", label: "QR Login", fields: [] }, { value: "bot_token", label: "Bot Token", fields: [ { key: "botToken", label: "Bot Token", required: true, type: "password" }, { key: "accountId", label: "Account ID" }, { key: "userId", label: "User ID" } ] } ] }

可以确认：Bot Token是唯一必填项，Account ID与User ID均为可选项；且与 QR Login 一致，微信平台的accountId/userId/botAgent/routeTag字段会在配置合并时被特殊处理（profiles.ts#L846）。

配置如何进入运行时：CCR 会把凭据打包进环境变量CCR_BOT_GATEWAY_CREDENTIALS_JSON、认证类型写入CCR_BOT_GATEWAY_AUTH_TYPE、平台写入CCR_BOT_GATEWAY_PLATFORM（env.ts#L25-L76）。此外源码会主动过滤掉 webhook 相关的键值（sanitizeBotGatewayRecord），因为 Weixin iLink 走的是长连接：integration 配置被强制写入transport: "websocket"（env.ts#L234-L247）。

在 CCR 中完成绑定

无论用哪种登录方式，都需要把 Bot 绑定到一个 Agent Config：

1. 打开Agent Config，编辑要挂接该 Bot 的配置项。
2. 打开Bot开关，并选择刚保存的 Bot。
3. 按需开启Forward agent messages或Handoff（见下节）。
4. 从 CCR 重新打开对应的 Agent App。

配置合并的优先级在源码中是明确的三级覆盖：全局botGateway→ 当前 Bot 保存的botGateway（按botConfigId从botConfigs中取出）→ Agent Config 自身的botGateway，后者优先（env.ts#L85-L101）。也就是说，同一个 Agent 上配置覆盖 Bot 级、Bot 级覆盖全局配置；credentials、handoff、integrationConfig三个对象字段做浅合并而非整体替换。

前提提醒（来自 AgentClaw setup）：该 Agent 的Entry mode必须包含 App，且当前受支持的受管 App 为 Claude App、Codex/ChatGPT App、OpenCode App、ZCode App 和 WorkBuddy App；纯 CLI 型 Agent 不转发 Bot 消息。AgentClaw 只在受管 App 存活期间在线。

Forward 还是 Handoff：两种消息模式

• Forward agent messages：无论屏幕是否锁定，把每条新的 Agent 消息都转发到微信。适合希望每一行输出都进微信的场景。
• Handoff：只在屏幕锁定后转发。配合Idle seconds（空闲秒数）与 Wi-Fi/蓝牙目标手机设备使用。若只想在锁屏时收到提醒，用 Handoff 而不开 Forward。

Handoff 的源码细节

Handoff 参数同样通过环境变量下发，默认值可以直接从 env.ts#L16-L23 读到：

const handoff = bot.handoff ?? { enabled: false, idleSeconds: 30, // 空闲阈值默认 30 秒 phoneBluetoothTargets: [], phoneWifiTargets: [], screenLock: true, // 默认依赖锁屏事件 userIdle: true // 默认依赖用户空闲判定 };

对应运行时变量为CCR_BOT_HANDOFF_ENABLED、CCR_BOT_HANDOFF_IDLE_SECONDS、CCR_BOT_HANDOFF_SCREEN_LOCK等（env.ts#L55-L60）。

关于 Wi-Fi/蓝牙目标设备：handoff-scan-service.ts 负责扫描候选设备——Wi-Fi 目标通过arp -a解析局域网 ARP 表（L8-L14），蓝牙目标在 macOS 上依次尝试blueutil、system_profiler、ioreg，在 Windows 上通过 PowerShell 的Get-PnpDevice -Class Bluetooth采集。按 AgentClaw setup 文档的说明，这些 Wi-Fi/蓝牙目标目前是实验性设置，尚不影响运行期 Handoff 判定，实际 Handoff 以锁屏与空闲时间为准。

验证是否工作

1. 从 CCR 打开该 Agent，触发一条消息。
2. 检查微信：确认 Bot 收到了消息并正常回复。
3. 锁定屏幕，等待超过你设置的空闲阈值，确认新的 Agent 消息进入了微信。

判断标准：微信里出现了 Agent 的消息，并且你在微信中回复后 Agent 继续运行，即接入成功。

更完整的验证手段（来自 AgentClaw setup）：在 IM 中发送/project current确认 Bot 在线、/session list列出会话，发送一条普通消息确认 Agent 执行并在同一会话中回复；关闭 Agent App 后 Bot 应转为离线。/session doctor与 Profile 卡片展示同类运行时诊断（连接状态、最近事件与投递、待发队列数量、脱敏错误）。

常见问题排查

关键文件索引

• 平台文档：Weixin iLink 设置、AgentClaw 总览与配置
• 运行时环境装配（平台/认证归一化、Handoff 默认值、环境变量）：env.ts
• 扫码登录会话管理（start/wait/cancel、终止态）：qr-login-service.ts
• 桌面端扫码窗口（Electron 沙箱 BrowserWindow）：bot-gateway-qr-window-service.ts
• Wi-Fi/蓝牙 Handoff 目标扫描：handoff-scan-service.ts
• Bot 表单字段定义（botToken/accountId/userId）：profiles.ts
• 平台与认证归一化（配置层）：config.ts
• 环境变量装配测试：bot-gateway-env.test.mjs

适用前提与限制：以上流程基于 CCR Desktop（Electron 应用），AgentClaw 仅在受管 Agent App 由 CCR 打开并存活期间在线；Weixin iLink 的 QR Login 是默认且推荐方式，Bot Token 仅适用于已持有第三方服务 token 的用户；Wi-Fi/蓝牙 Handoff 目标为实验性配置。

【免费下载链接】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