---
title: 微信接入
nav_title: 微信
description: 在设置页扫码登录微信机器人账号，再用配对码授权具体微信用户。
order: 3
---

# 微信接入

适合只想用微信、不愿意再装一个 App 的人：整个接入就是扫一次码，不需要去任何开放平台申请。代价是权限审批只能靠回复文本命令，没有可点的按钮；而且只处理私聊，不面向群聊设计。

除文本外，微信这条链路还支持语音转出的文字、图片和文件附件。

## 扫码绑定机器人账号

1. 打开「设置」→「IM 接入」，切到「微信」Tab。
2. 点「扫码绑定」。
3. 用微信扫描页面上的二维码，并在手机上确认登录。
4. 等页面状态变成「微信已绑定」。

![未绑定时的扫码入口](../images/im/wechat/wechat01.png)

绑定成功后凭据会自动写入本机配置并重启 adapter，不需要再点「保存」。这时 Tab 里会出现「重新扫码」和「解除微信绑定」两个按钮。

![绑定成功后的状态](../images/im/wechat/wechat03.png)

扫码绑定的是机器人账号本身，不等于放行所有微信联系人。谁能用，还要看下一步。

## 授权具体用户

1. 回到页面顶部的「配对管理」，点「生成配对码」。
2. 在微信里把这枚 6 位码发给刚绑定的机器人。
3. 看到配对成功提示后就能直接发消息。

![在微信里发送配对码并开始对话](../images/im/wechat/wechat02.jpg)

配对码 60 分钟内有效、只能用一次，重新生成后旧码立刻作废。

也可以把已知的微信用户 ID 直接填进「允许的用户」，多个用逗号分隔。这适合固定白名单，但不如配对码直观。

## 选项目并开始对话

配了「默认项目」的话，第一条消息就直接在那个目录下开会话。没配的话，机器人会先列出最近用过的项目，回复编号、项目名或绝对路径即可。

之后同一个聊天窗口的消息会复用同一条会话，桌面端重启也能接回去。发 `/new` 重新选项目，发 `/clear` 清空上下文但保留项目绑定。

## 支持的命令

微信没有可配置的菜单，命令入口就是聊天框。配对成功后机器人会提示发 `/help`。

- `/help` 或 `帮助` — 显示可用命令
- `/status` 或 `状态` — 当前项目、分支、模型、运行状态和任务摘要
- `/projects` 或 `项目列表` — 重新列出最近项目
- `/new` 或 `新会话` — 清空当前绑定并重新选择项目
- `/new <编号、项目名或绝对路径>` — 直接在指定项目下开新会话
- `/clear` 或 `清空` — 清空上下文，保留项目绑定
- `/stop` 或 `停止` — 停止本轮生成

## 权限审批与消息表现

Claude 请求敏感权限时，微信里会收到一条带 request id 的文本消息。回复其中一条：

- `/allow <requestId>` — 允许这一次
- `/always <requestId>` — 永久允许同类请求
- `/deny <requestId>` — 拒绝

回复走长轮询接收，正文按微信的长度上限分片发送，思考和工具执行期间会尽量显示「正在输入」。图片会以内联图片进入模型输入，其他文件会以本机临时路径传给会话，超出大小限制时机器人会在微信里提示。

## 解除绑定

两种粒度：

- 「解除微信绑定」清掉整个机器人账号凭据和这个平台的授权名单，之后要重新扫码。
- 在「已配对用户」列表里点某个用户右侧的「解绑」，只撤销那一个人，其他人不受影响。被解绑的人要重新发一枚新配对码。

## 本地开发启动

发布版桌面端会自动把 adapter 作为 sidecar 拉起。只有从源码运行或单独调试时才需要手动启动：

```bash
cd adapters
bun install
bun run wechat
```

可选的环境变量覆盖：

```bash
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"
```

正常使用桌面端不需要手动设置这些，扫码绑定会写好本机配置。

## 常见问题

**扫码成功后发消息仍提示未授权**：这是正常流程。扫码只写入机器人账号凭据，具体用户还要发配对码，或被写进「允许的用户」。

**二维码提示过期**：重新点「扫码绑定」生成新的，微信的扫码登录状态只在短时间内有效。

**adapter 启动时报缺少微信账号**：`WECHAT_ACCOUNT_ID`/`WECHAT_BOT_TOKEN` 和 `~/.claude/adapters.json` 里的对应字段都没生效，先在设置页完成扫码绑定。

**收不到回复**：依次确认桌面端在运行、Tab 里显示「微信已绑定」、当前用户已配对或在「允许的用户」里、`~/.claude/adapters.json` 能正常写入；源码运行时还要确认 `ADAPTER_SERVER_URL` 指向正在跑的桌面服务。

**重启后会话没接回来**：检查 `~/.claude/adapter-sessions.json` 能否正常写入，以及桌面端里那条会话是否还在。

## 源码入口

`adapters/wechat/` 下的 `index.ts`、`protocol.ts`、`media.ts`，以及 `adapters/common/` 下的 `pairing.ts`、`session-store.ts`、`ws-bridge.ts`、`http-client.ts`。