README.md - CodeWhale

README.md

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	![终端打印的登录二维码](../../docs/assets/weixin-bridge-qr-login.png)
49
50	二维码下方同时打印原始 URL，二维码显示异常时可手动打开。扫码窗口 5 分钟。
51
52	### 微信端验证信道效果
53
54	登录成功后，在微信里给这个 bot 发一条 `/status`。收到任何回复即表示链路已打通。
55
56	![微信端 /status 验证](../../docs/assets/weixin-bridge-status-verify.jpg)
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
73	登录凭证保存在 `WEIXIN_STATE_DIR`，再次启动无需重新扫码。线程映射与长轮询游标
74	写入同一目录，启动时会自动创建并探测可写性 —— 不可写则立即报错退出。
75
76	注意：bridge 不读取 `.env` 文件，手动运行时环境变量必须通过 `export` 传入，
77	或使用 `node --env-file=.env src/index.mjs`。
78
79	systemd 部署时把变量写入 env 文件并由单元引用：
80
81	```bash
82	cd integrations/weixin-bridge
83	npm install --omit=dev
84	cp .env.example /etc/codewhale/weixin-bridge.env
85	sudoedit /etc/codewhale/weixin-bridge.env
86	node src/index.mjs
87	```
88
89	## 命令
90
91	- `/status`
92	- `/threads`
93	- `/new`
94	- `/resume <thread_id>`
95	- `/model <name\|default>`
96	- `/interrupt`
97	- `/compact`
98	- `/allow <approval_id> [remember]`
99	- `/deny <approval_id>`
100
101	其他所有内容均作为 Codewhale 提示发送。
102
103	## 首次配对
104
105	1. 设置 `WEIXIN_ALLOW_UNLISTED=true` 启动 bridge。
106	2. 扫码登录后，在微信中发送 `/status`。
107	3. Bridge 返回 runtime 状态；若你不在白名单，则返回拒绝消息，其中带有你的 `user_id`。
108	4. 将 `user_id` 加入 `WEIXIN_CHAT_ALLOWLIST`。
109	5. 将 `WEIXIN_ALLOW_UNLISTED` 改回 `false` 并重启 bridge。
110
111	## 环境变量
112
113	\| 变量 \| 必填 \| 说明 \|
114	\|------\|------\|------\|
115	\| `CODEWHALE_RUNTIME_URL` \| 否 \| Runtime HTTP 地址（默认 `http://127.0.0.1:7878`） \|
116	\| `CODEWHALE_RUNTIME_TOKEN` \| 是 \| Runtime Bearer 令牌 \|
117	\| `CODEWHALE_WORKSPACE` \| 否 \| 工作区路径（默认 cwd） \|
118	\| `CODEWHALE_MODEL` \| 否 \| 模型名称（默认 `auto`） \|
119	\| `CODEWHALE_MODE` \| 否 \| 运行模式（默认 `agent`） \|
120	\| `WEIXIN_CHAT_ALLOWLIST` \| 否 \| 逗号分隔的允许用户 ID \|
121	\| `WEIXIN_ALLOW_UNLISTED` \| 否 \| 首次配对模式（默认 `false`） \|
122	\| `WEIXIN_STATE_DIR` \| 否 \| 状态持久化目录（默认 `/var/lib/codewhale-weixin-bot-bridge`） \|
123	\| `WEIXIN_THREAD_MAP_PATH` \| 否 \| 线程映射文件路径（默认 `<WEIXIN_STATE_DIR>/thread-map.json`） \|
124	\| `WEIXIN_MAX_REPLY_CHARS` \| 否 \| 单条回复最大字符数（默认 `3500`） \|
125	\| `CODEWHALE_TURN_TIMEOUT_MS` \| 否 \| Turn 超时（默认 `900000`） \|
126	\| `WEIXIN_LONGPOLL_TIMEOUT_MS` \| 否 \| 长轮询超时（默认 `35000`） \|
127
128	旧的 `WEXIN_*`（拼写错误）变量名仍作为已弃用别名被识别，启动时会打印一次弃用警告。
129
130	## 架构
131
132	```
133	微信客户端 ──getUpdates 长轮询──▶ Weixin Bot Bridge ──HTTP──▶ codewhale serve --http
134	◀──sendMessage── (127.0.0.1:7878)
135	```
136
137	Bridge 通过扫码获取 `bot_token`，然后长轮询 `POST /ilink/bot/getupdates`
138	以接收消息，并通过 `POST /ilink/bot/sendmessage` 发送回复。
139	所有消息均带有 `context_token` 以维持会话上下文。
140
141	## 与 wechat-bridge 的区别
142
143	\| 特性 \| wechat-bridge \| weixin-bot-bridge \|
144	\|------\|---------------\|-------------------\|
145	\| 账号类型 \| 微信公众号 \| 个人微信 \|
146	\| 登录方式 \| App ID + Secret 配置 \| 扫码登录 \|
147	\| 消息协议 \| 公众号回调 + 客服消息 \| iLink Bot 长轮询 + sendMessage \|
148	\| 公网需求 \| 需要（回调 URL） \| 不需要 \|
149	\| 消息类型 \| 仅文本 \| 文本/图片/语音/视频/文件（MVP仅文本） \|
150

150 lines MARKDOWN