CLI WeChat Bridge

CLI Chat Bridge

  简体中文 · English

命令行工具的微信、企业微信与 Telegram 桥接：本项目将微信、企业微信或 Telegram 消息桥接到本地运行的 Codex、Claude Code、OpenCode 和 Pi，同时把本地输出、审批请求与运行状态同步回对应通道。

项目围绕本地工作流设计，重点是保留本地原生终端体验：你仍然在本地使用原生 CLI 和高级启动参数，微信、企业微信或 Telegram 负责远程输入、结果回流与状态同步。

文档导航

- 渐进桥接模式：从一个干净的单桥接开始，按打开的窗口逐级扩展为 L1 多 CLI、L2 同类型多实例或 L3 多目录，附架构图。
- Telegram 接入：创建机器人、配对操作者、启动 CLI。
- 问题排查：上下文 token、网络代理、本地 endpoint、已知限制等常见问题。
- Codex 通道连接 skill（实验性）：在 Codex 会话中调用 $codex-bridge skill，把当前 Codex 会话（0.162+ 共享 daemon 模式）接入微信、企业微信或 Telegram。
- 运行配置：共享数据目录、界面语言、上传大小限制、调试开关等环境变量。
- 开发说明：源码运行、测试、构建、打包和全局 smoke 验证。
- 发布说明：各版本变更与升级说明。
- 通信架构：各 CLI 适配器的通信机制、PTY / RPC 依赖分析和技术决策。

一、这个项目解决什么问题？

本项目适合这样的使用场景：

- 你的主工作流仍在本地终端中进行；
- 你希望继续使用 Codex、Claude Code、OpenCode、Pi 等原生 CLI，而不是迁移到网页或托管机器人；
- 你希望离开电脑后，仍能通过微信、企业微信或 Telegram 向本地会话发送请求，并接收必要输出和状态更新。

本项目不试图把微信、企业微信或 Telegram 变成新的主工作界面。它的定位是：

- 本地 CLI 仍然是主工作界面，并保持原生的使用逻辑；
- 微信、企业微信或 Telegram 是远程入口，用来接入本地会话；
- 会话一致性、线程状态和审批流仍以本地会话为中心。

渐进桥接模式

桥接默认是一个干净的单桥接：只开一个 CLI 时，回复不带标签，聊天软件里只出现单 CLI 的命令。之后随你在本机打开的窗口逐级扩展：同一目录再开另一种 CLI 进入 L1 多 CLI，再开同一种 CLI 进入 L2 同类型多实例，在其他目录打开进入 L3 多目录；升级只升不降。每一级的架构图、指令和规则见渐进桥接模式，速查表见第 6 节。

二、快速开始

1. 环境要求

- Node.js >= 22.13.0（建议直接安装官网 LTS 版本）
- 已安装以下任意一种本地 CLI，并尽量保持最新版本：
  - Codex（常规桥接已验证 0.149.x–0.161.x；当前会话 attach 需 0.162+ 共享 daemon）
  - Claude Code
  - OpenCode（同时支持 1.18.x 与 2.0.x）
  - Pi（通过原生 TUI extension 接入；需要本机可执行 pi 命令）
- Bridge 仅调用安装在 PATH 中、可直接执行的独立 CLI；不会发现或调用 ChatGPT.app 等桌面应用内部捆绑的私有可执行文件。
- 已准备一个远程通道：个人微信使用 wechat-setup，企业微信使用 wecom-setup，Telegram 使用 telegram-setup

2. 安装与更新

发布版本可以直接从 npm 安装/更新。新用户优先使用更短的 cli-chat-bridge（项目即将使用的新名称，从 1.3.0 起同步发布）：

也可以安装内容完全相同的 cli-wechat-bridge：

兼容性说明：旧包名 @unlinearity/cli-wechat-bridge 会继续同步发布，已经安装旧包名的用户可以正常升级。三个包提供相同的命令，只安装其中一个即可；要切换包名，请先 npm uninstall -g 当前的包，否则 npm 会因 EEXIST…