命令行工具的微信桥接：本项目将微信消息桥接到本地运行的 Codex、Claude Code 和 OpenCode，同时把本地输出、审批请求与运行状态同步回微信。
项目围绕本地工作流设计，重点是保留本地原生终端体验：你仍然在本地使用原生 CLI 和高级启动参数，微信负责远程输入、结果回流与状态同步。
- 问题排查：上下文 token、网络代理、本地 endpoint、已知限制等常见问题。
- 运行配置：数据目录、上传大小限制、调试开关等环境变量。
- 开发说明：源码运行、测试、构建、打包和全局 smoke 验证。
- 发布说明：各版本变更与升级说明。
- 通信架构：三种 CLI 适配器的通信机制、PTY 依赖分析和技术决策。
本项目适合这样的使用场景：
- 你的主工作流仍在本地终端中进行；
- 你希望继续使用 Codex、Claude Code、OpenCode 等原生 CLI，而不是迁移到网页或托管机器人；
- 你希望离开电脑后，仍能通过微信向本地会话发送请求，并接收必要输出和状态更新。
本项目不试图把微信变成新的主工作界面。它的定位是：
- 本地 CLI 仍然是主工作界面，并保持原生的使用逻辑；
- 微信是远程入口，用来接入本地会话；
- 会话一致性、线程状态和审批流仍以本地会话为中心。
- Node.js
>= 24.0.0（建议直接安装官网 LTS 版本） - 已安装以下任意一种本地 CLI，并尽量保持最新版本：
发布版本可以直接从 npm 安装：
npm install -g cli-wechat-bridge@latest安装后，可以在任意项目目录中使用 wechat-daemon、wechat-codex-start、wechat-claude-start、wechat-opencode-start 等命令。
兼容性说明：旧包名 @unlinearity/cli-wechat-bridge 会继续同步发布，已经安装旧包名的用户可以正常升级；新用户优先使用更短的 cli-wechat-bridge。
安装遇到问题？（node-pty 原生模块）
本项目使用 node-pty 为 CLI 适配器提供完整终端模拟。Claude Code 适配器当前通过 PTY 交互模式工作，node-pty 不可用时会回退到兼容模式，但 Claude Code 在此模式下可能无法正常桥接；Codex 适配器主要通过 WebSocket RPC 通信，通常不受影响；OpenCode 适配器完全不依赖 node-pty。
Linux 用户（最常见）：需要原生模块编译工具：
# Debian / Ubuntu
sudo apt install build-essential python3
# RHEL / Fedora
sudo dnf groupinstall "Development Tools" && sudo dnf install python3
# Alpine
apk add build-base python3安装编译工具后重新安装：npm install -g cli-wechat-bridge@latest
macOS 用户：如遇编译问题，安装 Xcode 命令行工具：xcode-select --install
Windows 用户：
- 需要 Windows 10 1809（build 18309）或更高版本
- 如果 node-pty 加载失败，运行
npm rebuild node-pty或重新安装 - 确保已安装 Visual C++ Redistributable
运行 wechat-daemon --doctor 可快速检查环境状态。详见 问题排查。
全局安装后运行：
wechat-setup登录流程会：
- 获取微信登录二维码；
- 在终端打印二维码；
- 等待你在微信中扫码并确认；
- 保存本地登录凭据。
登录成功后，程序会清理旧的同步游标和上下文 token，避免旧会话状态污染新的登录状态。数据目录、状态文件和旧版本迁移说明见 问题排查。
首次安装或微信登录过期时，wechat-codex-start、wechat-claude-start、wechat-opencode-start 也会在前台提示扫码登录。
启动 bridge 后，建议先在微信里向 Bot 发送一条消息，例如 hello、你要执行的任务，或任意一句话。这样 bridge 能拿到最新的微信会话 context_token，之后本地终端中的输入、最终回复和审批提示才能稳定同步回微信。
如果冷启动或长时间闲置后直接从本地终端先发消息，bridge 通常仍会捕获这条本地输入并交给 Codex / Claude Code / OpenCode 处理，但回发到微信时可能因为旧的 context_token 失效而失败。表现是：本地已经有回复，微信暂时收不到；等你先从微信发来一条消息后，后续双向同步就能恢复正常。
先进入需要操作的项目目录：
cd D:\work\your-project然后选择一个单命令入口：
| 使用的本地 CLI | 启动命令 |
|---|---|
| Codex | wechat-codex-start |
| Claude Code | wechat-claude-start |
| OpenCode | wechat-opencode-start |
这些启动器会自动完成以下动作：
- 校验或刷新微信登录凭据；
- 如果当前目录已有
wechat-daemon，则委托 daemon 切换到对应 CLI； - 如果没有 daemon，则复用当前目录中已运行的 bridge，或在当前目录启动新的 bridge；
- 如果已有独立 bridge 正在服务其他目录，则停止旧 bridge 并切换到当前目录；
- 等待当前目录对应的本地 companion endpoint 就绪；
- 打开可见的本地 CLI 会话。
没有 daemon 时，wechat-codex-start / wechat-claude-start / wechat-opencode-start 仍按单活工作区切换器工作：
- 同一时间只有一个项目与微信对话；
- 在当前目录重复执行是幂等的；
- 如果当前目录已经有可见 companion / panel 在运行，则不会重复打开第二个窗口；
- 如果检测到可见端仍在运行但 worker 状态异常（如
stopped/error），会自动重启 bridge 再重新打开可见端； - 在其他目录执行会显式切换活动工作区。
如果你希望微信连接长期保持在线，并在 Codex / Claude Code / OpenCode 之间来回切换，可以在项目目录启动统一 daemon：
cd D:\work\your-project
wechat-daemon启动后，在微信里发送以下指令即可选择当前活动终端：
| 指令 | 行为 |
|---|---|
/codex |
切换到 Codex |
/claude |
切换到 Claude Code |
/opencode |
切换到 OpenCode |
daemon 启动后，后续切换都可以直接从微信发起；如果对应 CLI 还没有可见窗口，daemon 会自动打开或复用它，不需要再手动运行 wechat-codex、wechat-claude 或 wechat-opencode。
当前 daemon 行为如下：
- daemon 绑定启动时的工作目录；暂不支持在微信里切换工作目录；
- 启动时会自动接管并清理旧的单 bridge 进程、失效 lock 和旧 endpoint；
- 切换适配器不会关闭之前的 CLI；
- 如果对应适配器已经有可见 CLI 在运行，则直接复用；
- 如果还没有对应 CLI，daemon 会自动打开一个新的可见终端；
- Codex / Claude / OpenCode 的重要输出都会带上
[codex]、[claude]、[opencode]标签再发回微信； - 可以在微信里发送
/daemon-stop停止 daemon。
也可以在启动时指定初始 CLI：
wechat-daemon --adapter codex
wechat-daemon --adapter claude --profile work当同一工作目录已有 wechat-daemon 在运行时，wechat-codex-start / wechat-claude-start / wechat-opencode-start 会自动委托给 daemon：请求 daemon 切到对应 CLI，并在需要时打开可见终端，不会停止 daemon 或关闭其他 CLI。
如果你希望明确观察 bridge 与本地 CLI companion，也可以用两个终端分别启动。
| 适配器 | 终端 A：bridge | 终端 B：本地 companion |
|---|---|---|
| Codex | wechat-bridge-codex |
wechat-codex |
| Claude Code | wechat-bridge-claude |
wechat-claude |
| OpenCode | wechat-bridge-opencode |
wechat-opencode |
目前支持将本地文件发送到微信,微信也允许发送文件给本地 cli 解析 （注意模型本身要具备处理对应文件的能力！）
微信发来的图片和普通文件也会被接收并保存到本地：
- bridge 会将本地路径追加到转发给 Codex / Claude Code / OpenCode 的 prompt 中，模型可按需读取或解析这些文件；
- 当前不会自动 OCR 图片，也不会自动抽取 PDF / DOCX 正文；如需解析，由本地 CLI 根据路径完成。
- 具体保存位置见 问题排查。
| 适配器 | 当前状态 | 说明 |
|---|---|---|
codex |
已接入 | 双终端模式；本地 companion 作为线程权威；微信跟随本地线程 |
claude |
已接入 | wechat-bridge-claude + wechat-claude 的双终端 companion 模式；会话切换、最终回复与审批元数据按 Claude session 语义同步 |
opencode |
已接入 | OpenCode 适配器；wechat-bridge-opencode + wechat-opencode 的双终端 companion 模式；支持本地 session 切换跟随，微信侧支持 /new / /new-session |
OpenCode 模式下，微信侧支持 /new 或 /new-session 创建新 session；如果在本地 OpenCode CLI 中创建新 session，微信消息也会跟随新的 session。
| 类型 | 命令 |
|---|---|
| 登录与更新 | wechat-setup、wechat-check-update |
| 常驻 daemon | wechat-daemon |
| Codex | wechat-bridge-codex、wechat-codex、wechat-codex-start |
| Claude Code | wechat-bridge-claude、wechat-claude、wechat-claude-start |
| OpenCode | wechat-bridge-opencode、wechat-opencode、wechat-opencode-start |
适用于：
wechat-daemon
示例：
wechat-daemon --cwd D:\work\my-project
wechat-daemon --adapter codex
wechat-daemon --adapter claude --profile work支持参数：
--cwd <path>：指定 daemon 绑定的工作目录；--adapter <codex|claude|opencode>：启动 daemon 后立即切换到指定 CLI；--profile <name-or-path>：传给 daemon 创建的对应适配器；--no-open：只创建 bridge slot，不自动打开可见 CLI。
适用于：
wechat-bridgewechat-bridge-codexwechat-bridge-claudewechat-bridge-opencode
示例：
wechat-bridge --adapter codex --cwd D:\work\my-project
wechat-bridge-codex --cwd D:\work\my-project
wechat-bridge-claude --profile work
wechat-bridge-opencode --cwd D:\work\my-project
wechat-bridge-codex --lifecycle companion_bound支持参数：
--adapter <codex|claude|opencode>：通用入口wechat-bridge需要显式指定适配器；--cwd <path>：指定工作目录；--profile <name-or-path>：向适配器传入 profile；--lifecycle <persistent|companion_bound>：指定 bridge 生命周期；wechat-*-start会使用companion_bound。
示例：
wechat-codex-start --cwd D:\work\my-project
wechat-claude-start --profile work
wechat-opencode-start --cwd D:\work\my-project支持参数：
--cwd <path>：显式指定 bridge / companion 对应的工作目录；--profile <name-or-path>：转发给后台启动的wechat-bridge-codex/wechat-bridge-claude/wechat-bridge-opencode；--timeout-ms <ms>：等待当前目录 endpoint 的最长时间，默认15000。
高级用法：除上述启动器参数外，未知参数会继续透传给可见的底层 CLI。这样既能保留微信登录、工作区切换与 bridge 生命周期管理，也能启用 Codex / Claude Code 自己的高级启动模式。
wechat-codex-start --yolo
wechat-codex-start --model gpt-5.2 --yolo
wechat-claude-start --dangerously-skip-permissions
wechat-claude-start --model sonnet --dangerously-skip-permissions其中，--yolo 会传给 Codex；--dangerously-skip-permissions 会传给 Claude Code。它们只影响本地可见 CLI，不会覆盖 bridge 托管的 Codex remote 连接参数、Claude settings、微信登录状态或当前工作区锁。由于这两类参数会降低审批保护，建议只在可信工作区中使用。
| 指令 | 说明 |
|---|---|
| 普通文本 | 发送到当前活动会话 |
/codex / /claude / /opencode |
daemon 模式下切换活动 CLI；已有 CLI 会复用，没有则自动打开 |
/status |
查看 bridge 当前状态 |
/stop |
中断当前任务 |
/reset |
重建当前本地会话 |
/new 或 /new-session |
OpenCode 模式下新建 session |
/confirm / /deny |
处理 CLI 权限请求；需要一次性 code 的请求会在消息中提示具体确认格式 |
/daemon-stop |
daemon 模式下停止常驻进程 |
/bindings |
查看当前所有表情绑定 |
/bind [表情] /命令 |
绑定表情到指定命令 |
/unbind [表情] |
解除指定表情的绑定 |
说明：微信侧 /resume 目前暂时保持禁用；需要切换 Codex / Claude / OpenCode 会话时，优先在本地 companion 中使用原生 /resume、/new 或对应 CLI 命令，微信会跟随本地活动会话。
Daemon 模式支持将微信表情映射为命令，在微信中发送表情即可快速触发操作。（不过注意，第一次启动相关cli的时候，最好不要带消息，等启动完成再“表情+文本”快速给指定 cli 发送消息。
默认绑定：
| 表情 | 命令 | 说明 |
|---|---|---|
[OK] |
/confirm |
批准权限请求 |
[闭嘴] |
/stop |
中断当前任务 |
[拥抱] |
/claude |
切换到 Claude Code |
[强] |
/codex |
切换到 Codex |
[胜利] |
/opencode |
切换到 OpenCode |
[再见] |
/daemon-stop |
停止 daemon |
管理命令：
/bindings 查看当前所有绑定
/bind [表情] /命令 绑定表情到命令，如 /bind [微笑] /status
/unbind [表情] 解除绑定，如 /unbind [微笑]
触发规则：
- 表情必须出现在消息开头才会触发（如
[OK]触发，你好[OK]不触发）； - 如果表情后面还有文本（如
[拥抱]帮我写个脚本），会先执行命令再将剩余文本作为消息转发； - 大小写不敏感（
[OK]和[ok]等价）； - 修改后立即生效并持久化到
~/.cli-bridge/emoji-bindings.json，重启 daemon 后保留。
本项目采用“当前目录即当前工作区”的模型：
- 从哪个目录启动
wechat-bridge-codex/wechat-bridge-claude/wechat-bridge-opencode，哪个目录就是当前工作区； - 对应的本地 companion 必须连接同一工作区；
- 不同工作区的运行状态相互隔离。
目前支持两种运行模型：
- 独立 bridge：单 owner、单 bridge、单活动工作区；
wechat-daemon：单 owner、单 daemon、绑定一个启动工作区，但可在这个工作区内同时保留 Codex / Claude Code / OpenCode 三个 CLI slot。
对 wechat-codex-start / wechat-claude-start / wechat-opencode-start 来说，这意味着：
- 如果同一工作区已有 daemon，它们会委托 daemon 切换 CLI；
- 如果没有 daemon，它们会作为单活工作区切换器工作；
- 当前目录重复执行是幂等的；
- 在其他目录执行会触发工作区切换，而不是并行多开。
运行以下命令检查是否有新版本：
wechat-check-update该命令会显示：
- 当前安装的版本；
- 远程仓库的最新版本；
- 如果有更新，会提供详细的更新指引。
当启动 wechat-bridge 相关命令时（如 wechat-bridge-codex、wechat-bridge-claude），程序也会自动检查更新（每 24 小时一次）。自动检查在后台异步执行，不影响启动速度。
如果你使用 npm 全局安装，建议直接执行：
npm install -g cli-wechat-bridge@latest升级后请重启正在运行的 bridge 和 companion 终端，确保它们加载同一版本。
感谢 issue 反馈者和 PR 贡献者。
创作不易，如果觉得它有帮助或有意思，可以请喝杯奶茶。❤️
主要依赖：
- @opencode-ai/sdk：OpenCode session 和事件流客户端
- @modelcontextprotocol/sdk：MCP server 入口使用的 TypeScript SDK
- node-pty：本地 PTY / ConPTY 进程桥接
- qrcode-terminal：终端二维码输出
运行与开发基础：
- Node.js：运行发布包和 CLI 入口
- TypeScript：源码语言和构建工具链
- Bun：源码模式运行与测试工具
- ESLint：代码检查
社区与参考：
- Linux DO：学 AI，上 L 站！
- @tencent-weixin/openclaw-weixin：腾讯微信团队发布的 OpenClaw Weixin channel npm 包
- openclaw-weixin：早期 WeChat / Claude Code Channel 参考项目。
本项目采用双协议授权：
开源协议：AGPL-3.0
- 个人使用、学习、研究：完全免费
- 修改和衍生作品必须以相同协议（AGPL-3.0）开源
- 通过网络提供基于本项目的服务，也必须公开完整源代码
商业授权
如果你希望在闭源商业产品中使用本项目（不公开你的源代码），需要获得商业许可。请联系作者获取商业授权方案：
- GitHub: @UNLINEARITY