wechatAiclaw/DEBUG.md

本地调试说明

1. 启动开发环境

./run-dev.sh

• 前端：http://localhost:3000（管理页、登录等）
• 后端：http://localhost:8000（API）
• .env 会被自动加载，可配置 WECHAT_UPSTREAM_BASE_URL、KEY 等

2. 账号 key 与消息接收

• 登录页使用的 key 需要与后端「消息接收」使用同一 key，否则收不到该账号消息。
• 在 .env 中设置 KEY=你的key（或 WECHAT_WS_KEY=你的key、WS_KEY=你的key），与登录时填的 key 一致即可。

3. 消息接收：WS 与回调两种方式

不设 CALLBACK_BASE_URL（默认，适合本地）

• 不配置 CALLBACK_BASE_URL 时，后端用 WebSocket 连接 7006 的 GetSyncMsg 拉取消息。
• 7006 若拒绝 WS，日志会出现 WS disconnected ... server rejected WebSocket，消息可能收不到，但不影响登录、发消息、联系人等接口调试。

使用回调（7006 主动 POST 到本机）

• 7006 在公网，无法直接访问你本机的 localhost，需要先用 ngrok 把本机 8000 暴露到公网，再设回调。

一键用 ngrok 调通（推荐）：

1. 先配置 ngrok（仅首次）：ngrok 需登录并配置 authtoken，否则会报 ERR_NGROK_4018。

   • 打开 https://dashboard.ngrok.com/get-started/your-authtoken 复制 token
   • 执行：ngrok config add-authtoken <你的token>

2. 终端 1：执行

   ./run-ngrok.sh
   

   脚本会启动 ngrok http 8000，并把得到的公网隧道地址自动写入 .env 的 CALLBACK_BASE_URL（不会把 signup/dashboard 等链接误写成回调地址）。

3. 终端 2：启动服务

   ./run-dev.sh
   

   后端启动时会读取 CALLBACK_BASE_URL 并向 7006 注册 SetCallback，新消息会由 7006 POST 到你的 ngrok 地址。

4. 打开 http://localhost:3000 登录，用同一 key 收发消息即可验证回调是否生效。

手动步骤（不用脚本时）：

1. 终端运行 ngrok http 8000，记下输出的 https 地址（如 https://xxxx.ngrok-free.app）。
2. 在 .env 中增加或修改：CALLBACK_BASE_URL=https://xxxx.ngrok-free.app。
3. 执行 ./run-dev.sh（若已在运行则重启）。之后新消息由 7006 POST 到 https://xxxx.ngrok-free.app/api/callback/wechat-message，不再走 WS。

4. 手动模拟回调（不暴露公网也可测接口）

不跑隧道时，可直接用 curl 测回调接口是否正常：

# 替换成你的 key
curl -X POST 'http://localhost:8000/api/callback/wechat-message?key=HBpEnbtj9BJZ' \
  -H 'Content-Type: application/json' \
  -d '{"MsgList":[{"FromUserName":"wxid_test","Content":"你好","MsgType":1}]}'

返回 {"ok":true} 且后端无报错即表示回调入口和 _on_ws_message 逻辑正常。

5. 查看日志

• 后端：backend/data/logs/app.log（或控制台）
• 搜索 SetCallback、callback/wechat-message、WS disconnected 等便于排查消息接收问题。

6. 只调试后端 API

source .venv/bin/activate
cd "$(dirname "$0")"
uvicorn backend.main:app --host 0.0.0.0 --port 8000

再用浏览器或 Postman 访问 http://localhost:8000/docs 调试接口。