| 1 | # Weixin Bot Bridge |
| 2 | |
| 3 | 此 bridge 让微信个人账号通过扫码登录控制本地 `codewhale serve --http` runtime。 |
| 4 | 使用腾讯 iLink Bot 协议（参考 `@tencent-weixin/openclaw-weixin`）。 |
| 5 | |
| 6 | 此 bridge 直接使用**个人微信账号**扫码登录授权，通过长轮询 `getUpdates` 收发消息。 |
| 7 | |
| 8 | |
| 9 | ## Quick Start |
| 10 | |
| 11 | ### 终端发起 |
| 12 | |
| 13 | #### 方式一、双终端启动 |
| 14 | |
| 15 | 第一个终端启动 runtime： |
| 16 | |
| 17 | ```bash |
| 18 | export CODEWHALE_RUNTIME_TOKEN="$(openssl rand -hex 32)" |
| 19 | codewhale serve --http --host 127.0.0.1 --port 7878 --auth-token "$CODEWHALE_RUNTIME_TOKEN" |
| 20 | ``` |
| 21 | |
| 22 | 第二个终端启动 bridge： |
| 23 | |
| 24 | ```bash |
| 25 | cd integrations/weixin-bridge |
| 26 | export CODEWHALE_RUNTIME_TOKEN="<与上面相同的 token>" |
| 27 | export WEIXIN_ALLOW_UNLISTED=true |
| 28 | npm start |
| 29 | ``` |
| 30 | |
| 31 | |
| 32 | |
| 33 | #### 方式二、单终端启动 |
| 34 | |
| 35 | 一条命令同时启动 runtime 和 bridge，自动生成并共用 token： |
| 36 | |
| 37 | ```bash |
| 38 | cd integrations/weixin-bridge |
| 39 | npm run bridge |
| 40 | ``` |
| 41 | |
| 42 | 按 `Ctrl-C` 同时停止两者。 |
| 43 | |
| 44 | ### 微信端扫码接应 |
| 45 | |
| 46 | 首次启动会打印文本二维码，用微信扫码登录： |
| 47 | |
| 48 |  |
| 49 | |
| 50 | 二维码下方同时打印原始 URL，二维码显示异常时可手动打开。扫码窗口 5 分钟。 |
| 51 | |
| 52 | ### 微信端验证信道效果 |
| 53 | |
| 54 | 登录成功后，在微信里给这个 bot 发一条 `/status`。收到任何回复即表示链路已打通。 |
| 55 | |
| 56 |  |
| 57 | |
| 58 | |
| 59 | |
| 60 | |
| 61 | ## 安全模型 |
| 62 | |
| 63 | - `codewhale serve --http` 绑定于 `127.0.0.1`。 |
| 64 | - `/v1/*` runtime 调用使用 `CODEWHALE_RUNTIME_TOKEN`。 |
| 65 | - 微信用户必须加入白名单，除非首次配对时设置 `WEIXIN_ALLOW_UNLISTED=true`。 |
| 66 | - 仅支持私聊；暂不支持群聊。 |
| 67 | - 工具审批通过文本命令：`/allow <approval_id>` 或 `/deny <approval_id>`。 |
| 68 | - bridge 主动向微信服务器发起长轮询请求，无需公网端口。 |
| 69 | |
| 70 | ## 产品边界与验证 |
| 71 | |
| 72 | 此目录是个人微信 iLink 与已有 Codewhale Engine 之间的消息适配器。 |
| 73 | 模型调用、工具执行、线程和审批仍由 Engine 管理。每个状态目录只能由一个 |
| 74 | bridge 进程使用；白名单与本地 Runtime token 是操作员配置，不是多租户客户账户绑定。 |
| 75 | |
| 76 | 托管助手应通过已登录的 Codewhale 账户配对微信，并恢复同一个 Agent、对话和 |
| 77 | 工作区。正常套餐内的计算可自动启动或恢复；额外费用和有后果的操作使用已有 |
| 78 | 授权与审批机制。账户、套餐、Computer 生命周期及计费由已有控制平面负责， |
| 79 | 此 bridge 不实现这些托管服务。 |
| 80 | |
| 81 | 本地模拟测试不代表真实扫码、腾讯消息收发、跨地区可用性、长期主动通知或 |
| 82 | 托管 Computer 已验证。腾讯公开协议描述的是当前客户端行为，并非完整服务器 |
| 83 | 合同；成功的发送接口响应也不等于收件人送达回执。 |
| 84 | |
| 85 | |
| 86 | ## 设置 |
| 87 | |
| 88 | 登录凭证保存在 `WEIXIN_STATE_DIR`，再次启动无需重新扫码。线程映射与长轮询游标 |
| 89 | 写入同一目录，启动时会自动创建并探测可写性 —— 不可写则立即报错退出。 |
| 90 | |
| 91 | 提示先持久化，再由后台任务交给 Engine；执行期间仍可收到 `/allow`、`/deny` |
| 92 | 和 `/interrupt`。同一个 bot 账户重启后会恢复已接受的确切 turn，保存的回答与 |
| 93 | 待发送消息不会因事件连接断开而丢弃。旧状态没有账户绑定时，需要明确建立新 |
| 94 | 绑定；更换 bot 账户不会自动继承旧对话或发送旧回答。 |
| 95 | |
| 96 | Engine 必须同时声明 `turn_operation_idempotency` 和 `turn_operation_lookup` |
| 97 | 能力，bridge 才会查询并恢复没有收到确认的提交。旧 Engine 的不确定提交会 |
| 98 | 保留供操作员核对，不会自动重新执行。发送结果不确定时，回答保留在私有的 |
| 99 | 线程映射文件中；`/status` 会提示，bridge 不会自动重发。操作员须先核对 |
| 100 | Engine turn 与微信记录，避免重复执行或重复发送。仍有待核对工作时， |
| 101 | `/new`、`/resume` 和新提示不会覆盖它。 |
| 102 | |
| 103 | 注意：bridge **不读取 `.env` 文件**，手动运行时环境变量必须通过 `export` 传入， |
| 104 | 或使用 `node --env-file=.env src/index.mjs`。 |
| 105 | |
| 106 | systemd 部署时把变量写入 env 文件并由单元引用： |
| 107 | |
| 108 | ```bash |
| 109 | cd integrations/weixin-bridge |
| 110 | npm install --omit=dev |
| 111 | cp .env.example /etc/codewhale/weixin-bridge.env |
| 112 | sudoedit /etc/codewhale/weixin-bridge.env |
| 113 | node src/index.mjs |
| 114 | ``` |
| 115 | |
| 116 | ## 命令 |
| 117 | |
| 118 | - `/status` |
| 119 | - `/threads` |
| 120 | - `/new` |
| 121 | - `/resume <thread_id>` |
| 122 | - `/model <name|default>` |
| 123 | - `/interrupt` |
| 124 | - `/compact` |
| 125 | - `/allow <approval_id> [remember]` |
| 126 | - `/deny <approval_id>` |
| 127 | |
| 128 | 其他所有内容均作为 Codewhale 提示发送。 |
| 129 | |
| 130 | ## 首次配对 |
| 131 | |
| 132 | 1. 设置 `WEIXIN_ALLOW_UNLISTED=true` 启动 bridge。 |
| 133 | 2. 扫码登录后，在微信中发送 `/status`。 |
| 134 | 3. Bridge 返回 runtime 状态和当前发送者的 `user_id`。 |
| 135 | 4. 将 `user_id` 加入 `WEIXIN_CHAT_ALLOWLIST`。 |
| 136 | 5. 将 `WEIXIN_ALLOW_UNLISTED` 改回 `false` 并重启 bridge。 |
| 137 | |
| 138 | ## 环境变量 |
| 139 | |
| 140 | | 变量 | 必填 | 说明 | |
| 141 | |------|------|------| |
| 142 | | `CODEWHALE_RUNTIME_URL` | 否 | Runtime HTTP 地址（默认 `http://127.0.0.1:7878`） | |
| 143 | | `CODEWHALE_RUNTIME_TOKEN` | **是** | Runtime Bearer 令牌 | |
| 144 | | `CODEWHALE_WORKSPACE` | 否 | 工作区路径（默认 cwd） | |
| 145 | | `CODEWHALE_MODEL` | 否 | 模型名称（默认 `auto`） | |
| 146 | | `CODEWHALE_MODE` | 否 | 运行模式（默认 `agent`） | |
| 147 | | `WEIXIN_CHAT_ALLOWLIST` | 否 | 逗号分隔的允许用户 ID | |
| 148 | | `WEIXIN_ALLOW_UNLISTED` | 否 | 首次配对模式（默认 `false`） | |
| 149 | | `WEIXIN_STATE_DIR` | 否 | 状态持久化目录（默认 `/var/lib/codewhale-weixin-bot-bridge`） | |
| 150 | | `WEIXIN_THREAD_MAP_PATH` | 否 | 线程映射文件路径（默认 `<WEIXIN_STATE_DIR>/thread-map.json`） | |
| 151 | | `WEIXIN_MAX_REPLY_CHARS` | 否 | 单条回复最大字符数（默认 `3500`） | |
| 152 | | `CODEWHALE_TURN_TIMEOUT_MS` | 否 | 单次事件观察连接的时限（默认 `900000`）；断开后恢复观察，不中止 Engine turn | |
| 153 | | `WEIXIN_LONGPOLL_TIMEOUT_MS` | 否 | 长轮询超时（默认 `35000`） | |
| 154 | |
| 155 | 旧的 `WEXIN_*`（拼写错误）变量名仍作为已弃用别名被识别，启动时会打印一次弃用警告。 |
| 156 | |
| 157 | ## 架构 |
| 158 | |
| 159 | ``` |
| 160 | 微信客户端 ──getUpdates 长轮询──▶ Weixin Bot Bridge ──HTTP──▶ codewhale serve --http |
| 161 | ◀──sendMessage── (127.0.0.1:7878) |
| 162 | ``` |
| 163 | |
| 164 | Bridge 通过扫码获取 `bot_token`，然后长轮询 `POST /ilink/bot/getupdates` |
| 165 | 以接收消息，并通过 `POST /ilink/bot/sendmessage` 发送回复。 |
| 166 | 所有消息均带有 `context_token` 以维持会话上下文。 |
| 167 | |
| 168 | ## 微信与企业微信 |
| 169 | |
| 170 | 本目录使用个人微信 iLink 扫码授权。`integrations/wecom-bridge` 使用企业微信 |
| 171 | 企业应用协议，是另一种账户和传输。微信公众号接口同样是独立路线；当前目录 |
| 172 | 不提供公众号回调、群聊或图片/文件上传下载。 |
| 173 | |
| 174 | 协议参考：[腾讯官方客户端](https://github.com/Tencent/openclaw-weixin)及其 |
| 175 | [协议说明](https://github.com/Tencent/openclaw-weixin/blob/main/docs/protocol.md)。 |
| 176 |