ca62d1b24f
The WeChat and DingTalk IM docs were behind the actual desktop adapter flow, especially around QR binding versus user pairing and how users discover slash commands when no platform menu exists. This records the setup path with screenshots and nudges paired users toward /help from the bot itself. Constraint: DingTalk does not expose the same menu setup path documented for Feishu, so command discovery must work through chat text. Rejected: Document commands only in VitePress | users may be on mobile when they need the commands. Confidence: high Scope-risk: narrow Directive: Keep IM command docs aligned with adapters/common/format.ts when adding commands. Tested: cd adapters && bun test common/ dingtalk/ wechat/ Tested: cd adapters && bunx tsc --noEmit Tested: bun run check:docs Tested: bun run check:adapters Not-tested: Live WeChat or DingTalk message delivery with real platform accounts
6.3 KiB
微信接入
微信 Adapter 的接入教程。桌面端扫码绑定机器人账号后，再用配对码授权具体微信用户。
适用场景
微信方案适合个人私聊远程使用。当前实现支持文本聊天、语音转文字内容、图片和文件附件、项目选择、状态查看、停止生成和权限审批。
当前只按私聊用户维度授权和保存会话，不面向微信群聊设计。
实现入口：adapters/wechat/index.ts
1. 扫码绑定微信机器人账号
打开桌面端 设置 -> IM 接入 -> 微信。
在微信标签页里：
- 点击「扫码绑定」。
- 使用微信扫描页面里的二维码。
- 在微信里确认登录。
- 等待页面显示绑定成功。
- 点击保存，或确认当前配置已经写入本地。
扫码成功后，桌面端会把微信网关返回的 accountId、botToken、baseUrl 和 userId 写入 ~/.claude/adapters.json 的 wechat 配置。发布版桌面端会重启 adapter sidecar，让新凭据立即生效。
绑定成功后，微信标签页会显示「微信已绑定」，并提供「重新扫码」和「解除微信绑定」：
注意：扫码绑定的是机器人账号凭据，不等于把所有微信用户都授权了。用户访问仍然走 allowedUsers + pairedUsers 授权模型。
2. 授权具体微信用户
推荐走配对码：
- 在
设置 -> IM 接入顶部的「配对管理」里点击「生成配对码」。 - 把 6 位配对码发给微信里的机器人。
- 看到配对成功提示后，就可以直接发送自然语言消息。
配对码有效期 60 分钟，一次性使用。重新生成配对码后，旧码会失效。
也可以把已知微信用户 ID 手动写进微信标签页的 Allowed Users。这种方式适合固定账号白名单，但一般没有配对码直观。
3. 选择项目并开始对话
如果已经配置默认项目，发送任意消息会直接在该目录下创建或复用 Claude Code session。
如果没有配置默认项目，微信 adapter 会返回最近项目列表。回复编号、项目名或绝对路径后，会新建会话并绑定到当前微信用户。
后续消息会复用 ~/.claude/adapter-sessions.json 里的 chat 到 session 映射。发送 /new 可以重新选择项目并开启新会话。
支持的命令
微信没有可配置菜单，命令入口就是聊天框。配对成功后，bot 会提示发送 /help；后续随时发 /help 或 帮助 都能看到当前支持的命令。
/help或帮助— 显示可用命令/status或状态— 查看当前会话的项目、分支、模型、运行状态和任务摘要/projects或项目列表— 重新显示最近项目列表/new或新会话— 清空当前 chat 绑定的 session，并重新选择项目/new <编号、项目名或绝对路径>— 直接在指定项目下新建会话/clear或清空— 清空当前会话上下文，保留项目绑定/stop或停止— 向当前 session 发送stop_generation
权限审批
当 Claude 请求敏感权限时，微信 adapter 会发送一条文本审批消息，里面包含 request id。
在微信里回复：
/allow <requestId>— 允许一次权限请求/always <requestId>— 永久允许同类权限请求/deny <requestId>— 拒绝一次权限请求
审批结果会通过 WebSocket 桥接回桌面端 session。
返回消息的表现
- 使用
getupdates长轮询接收微信消息。 - 文本回复按 3500 字左右分片发送。
- thinking 和工具执行期间会尽量发送微信 typing 状态。
- 图片会以内联图片形式进入模型输入；非图片文件会以本地临时文件路径传给会话。
- 附件会走公共大小限制检查，超限时 adapter 会在微信里返回提示。
解绑
有两种解绑：
- 解绑微信机器人账号：在微信标签页点击「解绑微信账号」，会清空
wechat.accountId、wechat.botToken、wechat.userId、allowedUsers和pairedUsers。 - 解绑某个用户：在「已配对用户」列表里点击对应微信用户右侧的「解绑」，只移除该用户的
pairedUsers记录。
解绑机器人账号后需要重新扫码绑定。解绑用户后，该用户需要重新发送新的配对码才能继续使用。
本地开发启动
发布版桌面端会自动启动 adapter 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"
正常桌面端使用不需要手动设置这些环境变量，扫码绑定会写入本地配置。
常见问题
扫码成功后发消息仍提示未授权
这是正常授权流程的一部分。扫码绑定只写入机器人账号凭据；具体微信用户还需要发送配对码，或被加入 Allowed Users。
页面显示二维码过期
重新点击「扫码绑定」生成新二维码。微信二维码登录状态只在短时间内有效。
adapter 启动时报缺少微信账号
说明 WECHAT_ACCOUNT_ID / WECHAT_BOT_TOKEN 和 ~/.claude/adapters.json 里的 wechat.accountId / wechat.botToken 都没有生效。先在桌面端微信标签页完成扫码绑定。
收不到回复
优先检查：
- 桌面端是否正在运行。
- 微信标签页是否显示已绑定。
- 当前用户是否已经配对或在
Allowed Users中。 ~/.claude/adapters.json是否能正常写入。- 本地开发时
ADAPTER_SERVER_URL是否指向正在运行的 Desktop server WebSocket 地址。
会话没恢复
检查 ~/.claude/adapter-sessions.json 是否能正常写入，以及 Desktop server 里的 session 是否仍存在。
源码入口
adapters/wechat/index.tsadapters/wechat/protocol.tsadapters/wechat/media.tsadapters/common/pairing.tsadapters/common/session-store.tsadapters/common/ws-bridge.tsadapters/common/http-client.ts