CLI WeChat Bridge

简体中文 · English

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

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

文档导航

• Telegram 接入：创建机器人、配对操作者、启动 CLI 或附加当前 Codex 会话。
• 问题排查：上下文 token、网络代理、本地 endpoint、已知限制等常见问题。
• Codex 通道连接 skill（实验性）：$codex-bridge skill 与 --attach-current-session，把当前 Codex 会话（0.162+ 共享 daemon 模式）接入微信、企业微信或 Telegram。
• 运行配置：共享数据目录、界面语言、上传大小限制、调试开关等环境变量。
• 开发说明：源码运行、测试、构建、打包和全局 smoke 验证。
• 发布说明：各版本变更与升级说明。
• 通信架构：各 CLI 适配器的通信机制、PTY / RPC 依赖分析和技术决策。

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

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

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

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

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

二、快速开始

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 安装/更新：

npm install -g cli-wechat-bridge@latest

兼容性说明：旧包名 @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；Pi 直接继承可见 companion 的真实终端，也不需要 node-pty 模拟。

较新 npm 在 Linux 上阻止安装脚本： 如果安装输出提示 cli-wechat-bridge 和 node-pty 的 install/postinstall scripts 未被 allowScripts 允许，请执行一次干净重装：

npm uninstall -g cli-wechat-bridge
npm install -g cli-wechat-bridge@latest --allow-scripts=cli-wechat-bridge,node-pty

cli-wechat-bridge@latest 必须写在同一条安装命令中。不要只运行 npm install -g --allow-scripts=...；缺少包名时，npm 会尝试读取当前目录的 package.json，并可能报 ENOENT /home//package.json。

如需让后续全局升级继续允许这两个已确认的脚本，可以先写入用户级配置：

npm config set allow-scripts=cli-wechat-bridge,node-pty --location=user

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

安装编译工具后，使用上面的 --allow-scripts=cli-wechat-bridge,node-pty 命令重新安装。

macOS 用户：如遇编译问题，安装 Xcode 命令行工具：xcode-select --install

Windows 用户：

• 需要 Windows 10 1809（build 18309）或更高版本
• 如果 node-pty 加载失败，运行 npm rebuild node-pty 或重新安装
• 确保已安装 Visual C++ Redistributable

运行 wechat-daemon --doctor 可快速检查环境状态。详见 问题排查。

3. 完成登录（均可配置，看个人喜好）

3.1 微信登录

全局安装后运行：

wechat-setup

二维码默认使用 small 模式；如果 Windows 终端中的小二维码字符渲染异常，可使用

wechat-setup --qr-mode normal

切换为普通模式。

登录流程会：

1. 获取微信登录二维码；

2. 在终端打印二维码；

3. 等待你在微信中扫码并确认；

4. 保存本地登录凭据。

登录成功后，程序会清理旧的同步游标和上下文 token，避免旧会话状态污染新的登录状态。数据目录、状态文件和旧版本迁移说明见 问题排查。

首次安装或微信登录过期时，四个直接启动命令也会在前台提示扫码登录。

3.2 企业微信接入

企业微信使用官方智能机器人长连接，不需要公网回调地址。接入流程如下：

1. 在企业微信客户端的“工作台 → 智能机器人”中创建 API 模式机器人，选择“使用长连接”，取得 Bot ID 和 Secret；

2. 运行 wecom-setup，输入 Bot ID 和 Secret；

3. 在企业微信中与机器人单聊，发送终端显示的 /pair 完成一次性操作者配对；

3.3 Telegram 接入

Telegram 使用官方 Bot API 长轮询，不需要公网回调地址，本机需能访问 api.telegram.org。Telegram 从 1.2.3 起提供上述全局命令；源码安装步骤见开发说明。

1. 在 Telegram 中打开 @BotFather，发送 /newbot，按提示创建机器人并取得 Bot Token（官方创建说明）。
2. 在本地终端运行 telegram-setup，输入 Bot Token。
3. 打开新建机器人的私聊，点击 Start，在 10 分钟内发送终端显示的 /pair <六位配对码>。配对必须使用你之后操控 CLI 的 Telegram 账号。
4. 终端显示 Telegram operator pairing completed. 即完成；凭据和操作者身份保存到 ~/.cli-bridge/telegram/account.json，下次启动会自动使用。
5. 进入目标项目目录，运行 telegram-daemon --adapter codex，或选择下表中的 telegram-* 直接启动命令，然后在机器人私聊中发送任务。

telegram-setup          # 创建本地配置并完成操作者配对
telegram-setup --check  # 检查已配置的 Bot Token 是否有效

同一个 Bot Token 同时只运行一个 bridge／daemon；重新运行 telegram-setup 配对前，先停止正在使用这个机器人的桥接进程。

如果要将 当前 Codex 会话接入 Telegram，在该项目目录中使用：

telegram-codex --attach-current-session

此方式需要 Codex >= 0.162 的共享 daemon 会话；成功输出 Attached Codex daemon thread ，不会打开新的可见 CLI。同一目录有多个活会话时可追加 --codex-thread-id ，详见 Codex 通道连接说明。

4. 先从微信发一条同步消息（仅微信）

启动 bridge 后，建议先在微信里向 Bot 发送一条消息，例如 hello、你要执行的任务，或任意一句话。这样 bridge 能拿到最新的微信会话 context_token，之后本地终端中的输入、最终回复和审批提示才能稳定同步回微信。

如果冷启动或长时间闲置后直接从本地终端先发消息，bridge 通常仍会捕获这条本地输入并交给 Codex / Claude Code / OpenCode / Pi 处理，但回发到微信时可能因为旧的 context_token 失效而失败。表现是：本地已经有回复，微信暂时收不到；等你先从微信发来一条消息后，后续双向同步就能恢复正常。

5. 直接启动本地 CLI

先进入需要操作的项目目录：

cd D:\work\your-project

然后选择一个单命令入口：

没有 daemon 时，四个直接命令按单个活动工作区切换器工作：

• 同一时间只有一个项目与所选的微信、企业微信或 Telegram 通道对话；
• 如果检测到可见端仍在运行但 worker 状态异常（如 stopped / error），会自动重启 bridge 再重新打开可见端；
• 在其他目录执行会显式切换活动工作区。

6. 常驻 daemon 模式（支持多 CLI 切换）

如果你希望远程通道连接长期保持在线，并在 Codex / Claude Code / OpenCode / Pi 之间来回切换，可以在项目目录启动统一 daemon：

cd D:\work\your-project
wechat-daemon

企业微信使用同样的 daemon 工作流：

wecom-daemon --adapter claude

Telegram 使用 telegram-daemon --adapter codex，支持同样的 CLI 切换指令。

启动后，在对应远程通道里发送以下指令即可选择当前活动终端：

daemon 启动后，后续切换都可以直接从对应远程通道发起；如果对应 CLI 还没有可见窗口，daemon 会自动打开或复用它，不需要再手动运行适配器命令。

当前 daemon 行为如下：

• daemon 绑定启动时的工作目录；暂不支持从远程通道切换工作目录；
• 启动时会自动接管并清理旧的单 bridge 进程、失效 lock 和旧 endpoint；
• 如果还没有对应 CLI，daemon 会自动打开一个新的可见终端；
• Codex / Claude / OpenCode / Pi 的重要输出都会带上 [codex]、[claude]、[opencode]、[pi] 标签再发回对应远程通道；
• 可以在对应远程通道里发送 /daemon-stop 停止 daemon。

也可以在启动时指定初始 CLI：

wechat-daemon --adapter codex
wechat-daemon --adapter claude --profile work

当同一工作目录已有对应通道的 daemon 在运行时，直接启动命令会自动委托给 daemon：请求 daemon 切到对应 CLI，并在需要时打开可见终端，不会停止 daemon 或关闭其他 CLI。

三、适配器支持情况

目前支持将本地文件发送到微信、企业微信或 Telegram，这些通道也允许发送文件给本地 CLI 解析（注意模型本身要具备处理对应文件的能力！）

微信、企业微信或 Telegram 发来的图片和普通文件也会被接收并保存到本地：

• bridge 会将本地路径追加到转发给 Codex / Claude Code / OpenCode / Pi 的 prompt 中，模型可按需读取或解析这些文件；
• 当前不会自动 OCR 图片，也不会自动抽取 PDF / DOCX 正文；如需解析，由本地 CLI 根据路径完成。
• Telegram 附件保存到 ~/.cli-bridge/telegram/inbound-attachments/，也支持接收视频、语音和音频文件。其他通道的具体保存位置见 问题排查。

Pi 按全权限本地代理运行：bridge 不增加工具审批层，并传入 --approve 信任当前项目的配置、扩展与其他本地文件；该参数不是逐项工具审批开关；读写文件和执行命令均使用启动 Pi 桥接命令的本地用户权限。原生 TUI 的主题、快捷键、模型选择和 extension UI 都会保留。wechat-pi / wecom-pi / telegram-pi 本身就是被对应远程通道接管的 Pi TUI；不要再启动第二个 Pi 进程同时写入同一个 session 文件。Pi 0.85.0 及更新版本要求 Node.js >=22.19.0，低于该版本时 wechat-pi / wecom-pi / telegram-pi 会在启动前明确提示。

Codex 示例

Claude Code 示例

OpenCode / Pi 示例

OpenCode 模式下，微信、企业微信和 Telegram 侧都支持 /new 或 /new-session 创建新 session；如果在本地 OpenCode CLI 中创建新 session，远程通道消息也会跟随新的 session。

四、终端侧命令说明

所有命令都在目标项目目录中执行。wechat-* 使用个人微信，wecom-* 使用企业微信，telegram-* 使用 Telegram；三类入口的适配器名称和参数保持一致。

4.1 全局入口

1.1.5 已移除完成弃用周期的 wechat-*-start 别名；请直接使用上表中的入口。公开的 wechat-bridge* 命令和 Shell adapter 也已移除，内部 bridge runtime 由直接命令和 daemon 自动管理。

4.2 常驻 daemon

企业微信和 Telegram daemon 使用相同参数，例如 wecom-daemon --adapter claude --profile work 或 telegram-daemon --adapter claude --profile work。daemon 绑定启动时的工作目录；具体的远程通道控制指令见下一章。

4.3 直接启动适配器

通用参数：

--yolo 会传给 Codex，--dangerously-skip-permissions 会传给 Claude Code；这些参数只影响本地可见 CLI，不会覆盖内部 runtime、通道凭据或工作区锁。对应的企业微信或 Telegram 入口只需将命令前缀替换为 wecom- 或 telegram-。

4.4 更新

直接启动命令也支持 --doctor，用于检查选定适配器和当前工作区而不启动 CLI。

五、微信 / 企业微信 / Telegram 侧支持的指令

以下通用指令同时适用于微信、企业微信和 Telegram。普通文本会发送到当前活动会话；带 [prompt] 的适配器切换指令会先切换 CLI，再转发剩余文本。

5.1 通用控制指令

语言切换及启动环境变量的优先级见 界面语言。

Claude 的 AskUserQuestion 会转发题目、选项说明和文字预览。单题可回复 /answer 1 或自定义文本；多题可回复 /answer 1=Yes;2=2;3=1,2;4=1，多选值以逗号分隔。答案一次提交全部题目。hook 超时或断开连接后，远程问题会清除，并提示在本地终端作答或使用 /stop。升级后需重启 daemon 和可见 Claude 窗口。

Claude Code 的模型、计划模式控制需要可见 CLI 处于空闲原生提示符，且没有待审批、本地草稿或打开的弹窗。操作会短暂打开原生选择器并等待确认；控制期间操作本地键盘会取消远程控制。Claude Code 使用选择器的 s（仅当前会话）切换模型，需要 CLI 支持此选项；/plan off 会恢复进入计划模式前的 permission mode，没有记录时恢复 default。

OpenCode 的控制不依赖可见 TUI 的输入框、菜单或当前面板。桥接通过 OpenCode server 的会话 API 查询已连接模型、提交模型与 primary agent，并回读 session 确认结果；微信、企业微信和 Telegram 消息直接通过 SDK 提交，同时显式携带已生效的 agent、model 和 variant。OpenCode 的 /plan 选择 plan primary agent；缺少该 agent 时会提示错误，/plan off 没有历史记录时恢复 build 或首个非 plan primary agent。

Codex、Claude Code 和 OpenCode 的审批按到达顺序逐项处理：每次 /confirm 或 /deny 只处理当前显示的一项，再提示下一项；本地终端已处理的请求会同步移除。子代理的权限请求仍由所属父任务接收，审批不会切换当前会话或改变回复目标。升级后请重启已打开的 CLI 窗口，旧 companion 仍可显示状态，但需要重启才能远程审批。

Claude Code 默认在 bridge 生成的启动设置中添加 WebFetch(domain:*) 权限规则，允许常规联网请求直接通过；现有拒绝规则和沙箱限制仍生效。设置 CLI_BRIDGE_STRICT_APPROVAL=1 可关闭此自动放行；仅有本地网络弹窗、没有 PermissionRequest Hook 的请求需要在终端处理。

Pi 的 /model 通过已连接原生 TUI extension 读取当前 scoped model 列表；没有 scoped models 时使用 model registry 中可用的模型，并通过 pi.setModel() 切换。Pi 的 /plan 仍由可选扩展定义，不作为 bridge 的通用控制命令。

模型列表绑定当前会话、CLI 进程和操作者；切换会话或 daemon 活动 CLI 后请重新发送 /model。

「正在输入」状态与回复投递

从微信派发任务后，聊天窗口会显示原生的「对方正在输入…」状态，并以 5 秒心跳保持，直到回复送达、任务失败或 daemon 关闭。typing 凭证按联系人从微信官方配置端点获取并自动刷新，获取失败时整体静默降级，不影响消息收发。

微信较长的回复现在作为一条完整消息发出，不再按固定长度拆分，与微信官方机器人客户端的行为一致。若服务器拒收超长消息，既有的重试与待发队列机制仍会记录失败，回复不会无声丢失。

Telegram 任务运行期间也会保持原生的「正在输入」提示，较长回复按 Telegram 的消息长度限制自动拆分投递。

daemon IPC（外部程序接入）

wechat-daemon、wecom-daemon 与 telegram-daemon 在本地开放带 token 认证的 IPC 接口，外部程序（网页面板、脚本、自建机器人前端等）可以将文本按与聊天消息完全一致的处理规则下发给任意 CLI，或借用通道发送消息：忙碌时拒绝、有待审批或结构化输入时等待、Codex 本地任务期间自动排队，回复始终发回所属会话，输入被拒绝或失败时自动回滚状态。接口语义见 docs/development.md。Claude 原生菜单名称被终端宽度截断或无法唯一识别时，桥接会提示刷新或扩大终端；OpenCode 只有在 server 回读确认后才报告切换成功。

5.2 会话恢复与本地同步

所有适配器的 /resume 都只处理 daemon / bridge 启动目录内的最近 root thread/session，并等待当前任务进入 idle。有任务、审批或待回答问题时请先处理或使用 /stop；仍处于 active 状态的 Codex thread，以及仍在运行的 Claude background session，不允许从远程通道接管。OpenCode 和 Pi 的本地 session 切换会使之前的编号列表失效；如果切换发生在远程任务执行期间，bridge 会先中断旧任务。

5.3 daemon 表情绑定

Daemon 模式支持将消息开头的表情映射为命令。表情绑定对微信、企业微信和 Telegram daemon 均使用同一份配置，修改后立即生效并持久化到 ~/.cli-bridge/emoji-bindings.json。

表情必须出现在消息开头才会触发；表情后面的文本会在执行命令后继续转发；匹配不区分大小写。

六、致谢 & License

感谢支持

感谢 issue 反馈者和 PR 贡献者。

创作不易，如果觉得它有帮助或有意思，可以请喝杯奶茶。❤️

相关链接

此项目也在 AtomGit 托管

主要依赖：

• @opencode-ai/sdk：OpenCode session 和事件流客户端
• @wecom/aibot-node-sdk：企业微信智能机器人 WebSocket 长连接客户端
• @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 参考项目。

License

本项目采用双协议授权：

开源协议：AGPL-3.0-or-later

• 个人使用、学习、研究：完全免费
• 修改和衍生作品必须以相同协议（AGPL-3.0-or-later）开源，并保留版权声明
• 通过网络提供基于本项目的服务（包括仅供内部或私有部署使用的服务），也必须向服务使用者提供完整对应源代码（AGPL 第 13 条网络条款）
• 无论修改由人类还是 AI 工具完成，只要修改后的版本被发布或对外提供服务，发布方都有义务以 AGPL-3.0-or-later 公开完整源码；仅自用不分发则无此义务
• 每个源文件头部的 SPDX 声明构成协议通知的一部分，不得删除或篡改

商业授权

如果你希望在闭源商业产品中使用本项目（不公开你的源代码），需要获得商业许可。请联系作者获取商业授权方案：

• GitHub: @UNLINEARITY