Qwen Code 接入微信：基于 iLink Bot API 的 WeChat 频道完整配置指南
【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code
微信是目前最主流的即时通讯平台之一。Qwen Code 在channels体系中内置了weixin频道适配器，让开发者可以直接用微信与终端里的 AI 编程 Agent 对话：发文字提问、发送截图让多模态模型分析、投递 PDF 或代码文件让 Agent 读取处理。与 Telegram 使用静态 Bot Token 不同，微信频道采用官方 iLink Bot API，通过扫码登录完成鉴权。本文以 weixin.md 为骨架，结合仓库内packages/channels/weixin/的完整实现源码，带你从零配置并理解微信频道的登录、收发消息、媒体解密与故障排查全流程。
前置条件
接入微信频道前需要准备两样东西：
- 一个可以扫码的微信账号（手机 App），用于完成登录鉴权；
- 可访问iLink Bot 平台（微信官方 Bot API）的权限。
微信频道不依赖静态 Bot Token，鉴权凭证完全来自扫码登录环节，这一点与 Telegram 频道有本质区别。
第一步：通过二维码登录
微信采用二维码鉴权而非静态 Token，登录命令为：
qwen channel configure-weixin命令执行后，终端会输出一个二维码 URL（QR code URL: ...），用微信手机 App 扫码并在手机上确认即可完成登录。凭证会被保存到~/.qwen/channels/weixin/account.json。
从源码看，这条命令的完整链路位于 configure.ts：
- 获取二维码：调用 iLink Bot API 的
GET /ilink/bot/get_bot_qrcode?bot_type=3接口获取二维码 ID（见 login.ts）； - 轮询扫码状态：每 1 秒轮询一次
get_qrcode_status接口，等待用户扫码并确认。轮询期间可能遇到scaned（已扫码待确认）、expired（二维码过期）等状态，二维码过期会自动刷新，最多重试 3 次；整体登录超时上限为 480 秒（8 分钟）； - 保存凭证：登录成功后返回
bot_token、baseurl、ilink_user_id等信息，写入account.json。
configure-weixin命令还支持两个子动作：
# 查看当前登录状态与保存时间 qwen channel configure-weixin status # 清除已保存的微信凭证（退出登录） qwen channel configure-weixin clear关于凭证文件的安全性，accounts.ts 的实现值得一提：写入时使用随机命名的临时文件并以wx（O_CREAT|O_EXCL）标志创建，再通过rename原子替换目标文件，文件权限为0600，可有效防止符号链接攻击与凭证被其他用户读取。clear动作还会顺带清扫中断写入残留的临时文件，避免存活 Token 长期滞留在磁盘上。
说明：微信频道不使用
token字段，凭证完全来自扫码登录步骤；account.json属于敏感文件，请勿提交到版本库或随意分享。
第二步：在 settings.json 中配置频道
登录完成后，将频道配置加入~/.qwen/settings.json：
{ "channels": { "my-weixin": { "type": "weixin", "senderPolicy": "pairing", "allowedUsers": [], "sessionScope": "user", "cwd": "/path/to/your/project", "model": "qwen3.5-plus", "instructions": "You are a concise coding assistant responding via WeChat. Keep responses under 500 characters. Use plain text only." } } }各字段含义与可选值如下（完整选项表见 Channel Overview）：
| 配置项 | 说明 |
|---|---|
type | 频道类型，微信固定为weixin |
senderPolicy | 谁能与 Bot 对话：allowlist（默认，仅allowedUsers内用户可用）、pairing（陌生人需配对码审批）、open（所有人可用，慎用） |
allowedUsers | 允许使用 Bot 的用户 ID 列表，配合allowlist与pairing使用 |
sessionScope | 会话隔离方式：user（每个用户一个会话，默认）、chat_thread、single（所有人共享一个会话） |
cwd | Agent 的工作目录，默认当前目录；不同频道可指向不同项目 |
model | 频道使用的模型。微信支持图片分析，需要配置多模态模型（如qwen3.5-plus） |
instructions | 注入到每个会话首条消息的系统指令 |
由于微信会剥离所有 Markdown 格式，示例中的instructions明确要求 Agent 使用纯文本、控制回复长度，这正是微信频道的最佳实践写法。
第三步：启动频道
# 只启动微信频道 qwen channel start my-weixin # 或一次性启动所有已配置的频道 qwen channel start启动后打开微信，向 Bot 发送一条消息：你会先看到"..."输入状态指示器（Agent 处理中），随后收到回复。
从源码看，启动的核心是 WeixinAdapter.ts 中的connect()：它会先读取account.json加载 Token（未配置时会抛出WeChat account not configured. Run "qwen channel configure-weixin" first.错误），然后调用 monitor.ts 的startPollLoop()启动长轮询循环，持续调用getupdates接口拉取新消息。值得注意的是，微信适配器会自动注入默认指令——如果配置里没有自定义instructions，会补上"简洁编程助手、回复控制在 500 字符内、使用纯文本"的默认提示，并追加[IMAGE: /path/to/file.png]图片发送标记的用法说明。
图片与文件：不只是文字
微信频道支持发送图片和文档给 Agent，而不只是纯文本。
图片：多模态视觉分析
发送截图、照片等图片后，Agent 会用视觉能力分析内容。这要求频道配置了多模态模型（如"model": "qwen3.5-plus"）。图片下载处理期间同样会显示"..."输入指示器。
底层实现路径见 WeixinAdapter.ts 与 media.ts：
- 消息中的图片以 CDN 引用（
encrypt_query_param+aes_key）形式到达，适配器调用downloadAndDecrypt()从https://novac2c.cdn.weixin.qq.com/c2c/download?encrypted_query_param=...下载密文； - 使用AES-128-ECB算法解密。
parseAesKey()兼容两种密钥编码：base64 解码后正好 16 字节的原始密钥，或 base64 解码后是 32 字符十六进制字符串（再转回 16 字节密钥）； - 解密后的图片转成 base64 与 MIME 类型挂载到消息信封上，作为视觉输入交给模型。
文件：任意文档交给 Agent 读取
发送 PDF、代码文件或任意文档后，Bot 会从微信 CDN 下载并解密，保存到本地临时目录，再由 Agent 用文件工具读取。文件支持任何模型，无需多模态能力。
文件处理同样是downloadAndDecrypt()解密，然后写入tmpdir()/channel-files/<uuid>/目录（见 WeixinAdapter.ts），并以附件形式传入 Agent。下载失败时会向用户返回明确的错误占位文本，而不是静默丢弃。
反向发送：Agent 给用户发图片
微信适配器还支持 Agent 在回复中以[IMAGE: /absolute/path/to/file.png]标记发送图片（见 WeixinAdapter.ts）。发送前 send.ts 的validateImagePath()会做严格的安全校验：
- 扩展名白名单：仅
.png、.jpg、.jpeg、.gif、.webp； - 大小上限 20 MB；
- 路径必须位于临时目录或频道
cwd工作目录内（防 AI 读取任意文件）； - 读取文件头 16 字节做 magic bytes 校验，确保扩展名与真实格式一致。
通过校验后，图片走"申请上传 URL → AES-128-ECB 加密上传 CDN → 携带 CDN 媒体引用发送消息"的四步流程（getuploadurl→uploadToCdn→sendmessage），并在服务端把 Markdown 统一转成纯文本。
配置选项
微信频道支持 Channel Overview 中列出的所有标准选项（见 Channel Overview），此外还有一个专属选项：
| 选项 | 说明 |
|---|---|
baseUrl | 覆盖 iLink Bot API 的基础地址（默认https://ilinkai.weixin.qq.com） |
该默认值定义在 accounts.ts，WeixinAdapter构造时优先读取配置中的baseUrl，其次使用登录凭证里保存的地址（WeixinAdapter.ts）。baseUrl一般无需修改，仅在企业内部网关或代理场景下使用。
与 Telegram 的关键差异
微信频道虽然与 Telegram 共享同一套 Channel 架构（统一经 ACP 连接同一个 Agent 进程），但在平台能力上差异明显：
| 维度 | 微信（Weixin） | Telegram |
|---|---|---|
| 鉴权方式 | 二维码扫码登录，会话可能过期 | 静态 Bot Token |
| 消息格式 | 仅纯文本，Markdown 自动剥离 | 支持富文本/Markdown |
| 处理中指示 | 原生"..."输入状态 | "Working..."文本消息 |
| 群聊 | iLink Bot 仅支持私聊（DM-only），不支持群聊 | 支持群聊（需配置groupPolicy） |
| 媒体加密 | CDN 上 AES-128-ECB 加密，适配器透明解密 | Bot API 直连下载 |
关于"输入状态"，微信适配器的实现细节非常讲究：iLink 的 typing 状态设置后很快过期，因此 WeixinAdapter.ts 会以4 秒间隔持续刷新TYPING状态（类似 Telegram 适配器对约 5 秒过期的 4 秒重复策略），并设置10 分钟的兜底上限——若某个回合迟迟未结束，keepalive 会自动回收并发送CANCEL，避免卡死会话无限期占用输入指示器。这一系列行为都有对应的单元测试覆盖（见 WeixinAdapter.test.ts，包括多会话共享聊天的指示器管理、过期会话清理、断线重连状态回收等场景）。
使用技巧
- 用纯文本指令：微信会剥离所有 Markdown，务必在
instructions中写明"Use plain text only"，否则 Agent 产出的格式化内容在微信里会显得杂乱； - 控制回复长度：微信气泡适合短文本，建议在指令中加字符上限（如"Keep responses under 500 characters"）；
- 会话过期处理：日志中出现
Session expired (errcode -14)说明微信登录已过期，停止频道后重新执行qwen channel configure-weixin扫码登录即可； - 限制访问：使用
senderPolicy: "pairing"或"allowlist"控制谁能与 Bot 对话。配对模式下陌生用户会收到 8 位配对码，运营者通过qwen channel pairing approve my-weixin <CODE>审批后该用户才可正常使用（详见 DM Pairing）。
故障排查
"WeChat account not configured"
尚未完成登录。先执行qwen channel configure-weixin完成二维码登录，再启动频道。
"Session expired (errcode -14)"
微信登录会话已过期。停止频道并重新运行qwen channel configure-weixin。
从源码看，errcode -14的处理在两层都有体现：
- api.ts 的
isRetryableError()将-14明确判为不可重试错误（重试无意义，必须重新登录），而-1（系统繁忙）与45011（频率限制）等瞬时错误则走指数退避重试（最多 3 次，基础延迟 1 秒）； - monitor.ts 的轮询循环遇到
-14时不会直接崩溃，而是打印日志并暂停 30 秒后继续轮询，给运营者留出重新登录的窗口。
Bot 不响应
- 查看终端输出中的错误信息；
- 确认频道正在运行（
qwen channel start my-weixin）； - 如果使用
senderPolicy: "allowlist"，确认你的微信用户 ID 已加入allowedUsers。
图片不工作
- 确认频道配置了支持视觉的模型（如
qwen3.5-plus）； - 查看终端中是否有 CDN 下载错误——下载超时（40 秒上限）或网络问题都会导致图片失败。另外请确认图片格式在支持列表（PNG/JPG/GIF/WebP）内且不超过 20 MB。
小结
微信频道是 Qwen Code Channel 体系中鉴权方式最特殊、媒体链路最复杂的一环：它用扫码登录替代静态 Token，用 AES-128-ECB 加密的 CDN 链路承载图片与文件，用原生"..."指示器替代文本式工作状态，并且只支持纯文本私聊。理解了 accounts.ts、login.ts、monitor.ts、media.ts 与 send.ts 这几条实现链路，你就能在遇到问题时快速定位是登录过期、轮询异常、CDN 下载失败还是媒体格式校验被拒。想要把 Qwen Code 的编码能力带到微信上，按照本文的"扫码登录 → 配置 settings.json → 启动频道"三步即可跑通。
【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
