WeChat Codex

把微信消息桥接到本地 codex CLI 的命令行工具。

当前已经跑通的主链路：

• 微信扫码登录
• 长轮询接收微信消息
• 每个微信用户绑定一个长期 Codex 会话
• 微信里发送 /reset 立即开启一个新的 Codex 会话
• 文本消息转发给本地 Codex，并把文本结果回到微信
• 单实例运行保护，避免重复消费同一条消息

环境要求

• Node.js >= 22
• 本机已安装并可直接执行 codex
• 当前机器能访问腾讯微信后端接口

本地开发安装

npm install

安装方式

方式一：直接从 npm 安装

发布到 npm 后，可以直接全局安装：

npm install -g @cloxi/wechat-codex-cli

安装完成后可直接使用：

wechat-codex login
wechat-codex run

方式二：从本地 tgz 包安装

如果你想先本地验证，或者暂时不走 npm registry，可以先打包：

npm pack

然后全局安装生成的压缩包：

npm install -g ./cloxi-wechat-codex-cli-0.1.1.tgz

安装完成后同样直接使用：

wechat-codex login
wechat-codex run

登录微信

第一次使用先登录一次：

npm run bridge:login

全局安装后等价命令是：

wechat-codex login

命令会输出一个 QR URL。把这个链接对应的二维码用微信扫码并在手机上确认。

登录成功后，账号凭证会保存在用户级状态目录：

~/.wechat-codex/weixin/accounts/<accountId>.json

一键启动 Bridge

如果本地只有一个已登录微信账号，直接启动：

npm run bridge

全局安装后等价命令是：

wechat-codex run

这个命令会：

• 自动编译
• 自动识别唯一已登录微信账号
• 启动微信长轮询
• 把微信文本消息转发给本地 Codex

如果本地有多个已登录账号，需要显式指定：

WEIXIN_ACCOUNT_ID='<your-account-id>' npm run bridge

如果你要指定 Codex 工作目录，也可以显式传：

WORKSPACE_DIR='/path/to/project' npm run bridge

全局安装后同理：

WEIXIN_ACCOUNT_ID='<your-account-id>' WORKSPACE_DIR='/path/to/project' wechat-codex run

在微信里怎么测试

普通连续会话

直接给 bot 发消息即可，例如：

只回复 hello

后续消息会继续进入同一个 Codex 会话。

开启一个新的 Codex 会话

在微信里发送：

/reset

这会：

• 中断当前任务
• 清空当前会话队列
• 新建一个新的 Codex 会话

然后再发下一条消息，例如：

只回复 fresh-start

这条消息就会进入全新的 Codex 会话。

常用命令

npm run bridge:login
npm run bridge
npm test
npm run typecheck
npm run build
npm pack

运行方式说明

CLI 支持两个模式：

• login
• run

编译后等价命令分别是：

node dist/src/main.js login
node dist/src/main.js run

当前限制

• 当前主要验证的是文本链路
• 媒体输入/输出链路还没有完整收口
• 日志现在偏调试风格，后续还会整理
• 这是本地单机 bridge，不是服务端多实例部署方案

排障提示

No saved Weixin account found

说明还没登录，先执行：

npm run bridge:login

Multiple saved Weixin accounts found

说明本地保存了多个微信账号。启动时显式指定：

WEIXIN_ACCOUNT_ID='<your-account-id>' npm run bridge

Bridge is already running with pid ...

说明已经有一个 run 实例在运行。不要重复启动第二个。

状态目录

本地状态默认在：

~/.wechat-codex/

其中关键文件包括：

• ~/.wechat-codex/weixin/accounts/*.json
• ~/.wechat-codex/weixin/accounts/*.sync.json
• ~/.wechat-codex/conversations/*.json

state/ 已加入 .gitignore，不会提交到仓库。

发布前检查

建议每次发布前都执行：

npm test
npm run typecheck
npm run build
npm pack

然后确认 tarball 里只包含 CLI 运行所需文件。