Windows desktop WeChat vision-assisted daily chat proxy prototype.
This first version is intentionally read-only by default:
- It detects WeChat windows.
- It screenshots a configured chat region.
- It uses a vision model to extract recent chat events.
- It deduplicates messages.
- It can generate a suggested daily-chat reply.
- It can manually send text when you explicitly run the
sendcommand. - It does not auto-send replies unless
--auto-sendis explicitly enabled.
cd E:\WeChatCustomerBot
copy config.example.json config.json
$env:BOT_LLM_API_KEY="your-api-key"
$env:PYTHONPATH="E:\WeChatCustomerBot\src"
python -m wechat_customer_bot list-windows
python -m wechat_customer_bot watch --hwnd 132854 --suggestUse an independent WeChat private chat window where possible. Do not use group chats for automation.
To allow automatic sending for a specific independent private chat window:
python -m wechat_customer_bot watch --hwnd 132854 --auto-sendOnly suggest decisions are sent. ignore and handoff decisions are never auto-sent.
For multiple windows, use one serial watcher instead of starting multiple watch processes:
python -m wechat_customer_bot watch-many --hwnd 4329172 --hwnd 2362606 --auto-sendThis avoids concurrent window activation and reduces the chance of reading the wrong window.
wechat_relay watches the WeChat 4.x main window of the account logged in on this PC,
forwards every new private/group message to one chat (your main account), and sends your
replies back to the right sender.
How it works:
- Unread red badges in the session list are detected locally from pixels (no model call).
- The bot opens the chat and reads the title bar and the messages in one vision-model call
(
qwen3.6:35bon soclaas, ~1-4s). Left/right is then decided from pixels (green bubble, avatar side), not by the model. - To open a chat by name, the vision model lists the session-list rows (or the search results) and the click is snapped to the avatar found locally at that position; the chat's title is then read back by the vision model and must match exactly before anything is typed. Windows OCR is only used for right-click menu items.
- New messages are found by anchoring on the last messages seen in that chat.
- It forwards them as one message per chat and then waits in the main chat, so every new message elsewhere shows up as a badge. Messages arriving in the open main chat get no badge, so its messages area is compared with the last read every second (pixels only) and read again when it changed. A verified title bar is cached by its pixels, so going back to a chat usually needs no title read.
- Images are copied with WeChat's own
复制menu and sent as originals. Voice bubbles are converted with WeChat's own转文字before reading.
Forward format:
#12【群】专业班子
张三:今天几点开会?
李四:[图片] 会议室白板
Reply from the main account by quoting a forwarded message and typing, or with
#12 内容. /截图 #12 (or /截图 会话名, or /截图 while quoting a forward) sends a
screenshot of that chat as it looks right now. /暂停 30 keeps the bot's hands off the
mouse and keyboard for 30 minutes (then it resumes by itself); /停止 shuts it down and
start_relay.ps1 does not restart it. /list shows recent chats, /help shows usage.
Whenever the bot opens a chat (to reply, to take a screenshot, or by mistake) it reads it and relays anything new, because opening a chat clears its unread badge.
Setup:
cd E:\zt-toys\WeChatBot
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt winocr
copy relay.example.json relay.json # edit forward_to if needed
# put SOCLAAS_API_KEY / SOCLAAS_BASE_URL into data\relay\soclaas.env
$env:PYTHONPATH="src"; .\.venv\Scripts\python.exe -m wechat_relay layout # check detection
.\start_relay.ps1Requirements and limits:
- WeChat light theme, main window not minimized; the bot drives mouse and keyboard, so do not use this PC while it runs.
- If the same account reads messages on a phone first, the PC badge disappears and the message is not forwarded.
- Only messages visible on screen are read; very long bursts are marked as possibly incomplete.
With pool_group set in relay.json, the bot watches the API account pool and posts risk
alerts to that one group (strict name match). Once a
minute a background thread runs ssh <pool_ssh_host> and, on the server itself, curls the
gateway's read-only monitoring API on 127.0.0.1:18320 with the token in
/etc/aiproxy/pool-monitor.token (the token never leaves the server):
/api/monitoring/account-pool/snapshot: 5-minute success rate, eligible accounts./api/monitoring/account-pool/auth-health: each account's authorization state with its email. Served to direct loopback requests only; anything through nginx or a tunnel (which always carriesX-Forwarded-For/X-Real-IP) gets 403.
Alerts: an account whose authorization is not healthy (401 授权失效 / 403 封号 / 403 禁止访问
/ other 授权异常) and its recovery; the 5-minute success rate below
pool_success_threshold (default 80%, at least pool_min_requests requests, two polls in
a row; a reminder every pool_realert_minutes while it stays low) and its recovery; no
eligible account left; the monitor unreachable for 3 polls. What was reported is kept in
state.json so a restart does not repeat it. /号池 开|关 in the main chat switches it.
Scheduled reports: at each pool_report_times (SGT, default ["09:00", "21:00"], []
for none) the group gets one line of state followed by the /号池 overview picture. A slot is
skipped while alerts are muted, while monitoring is off, and when the bot was not running
within pool_report_grace_minutes (30) of it; each slot is reported at most once
(last_report in state.json).
Group commands (window mode; anyone in the group, read-only except muting). With
pool_commands on, the group window is read with the vision model at most once every
pool_read_interval_sec (10 s) when its pixels change:
| Command | Answer |
|---|---|
/号池 (/状态) |
5-minute success rate, eligible accounts, queue, remaining quota, auth problems |
/账号 |
every account: email, pool (号池中 / 等待区 / 休息区), authorization state |
/趋势 [6h|30分钟|1天] |
success rate per time slot (default 1 hour, at most 1 day, ≤ 12 lines) |
/静音 [30分钟|2h] |
hold alerts (default 30 min, at most 12 h); the state is posted when it ends |
/取消静音 |
alerts back on now |
/帮助 |
this list |
@BQ7 /号池 and a full-width / work too. The same commands (except /帮助) are accepted in
the main chat.
/号池, /账号 and /趋势 answer with a picture (pool_charts.py, Pillow, 1080 px wide,
drawn at 2x and downsampled); the low-success-rate and empty-pool alerts are followed by
the trend / overview picture. Layout follows public status pages (an overall banner, a row
of per-period slots colored by health); colors are status colors only where they mean
good/bad, request volume and success rate are two panels rather than a dual axis. If a
picture cannot be drawn the text answer goes out instead; "pool_images": false turns
pictures off.
Speed: the pool server is reached through one long-lived ssh session (a command costs one
round trip, ~0.5 s, instead of a ~3 s handshake). Argument-free commands (/号池, /账号,
/趋势) are spotted with Windows OCR on the newest line of the group (~0.15 s) and answered
before the vision model reads the chat; everything else, and anything OCR misreads, waits
for the model's read, which skips what OCR already answered.
Members of the ops group (only that group) can delete and add pool accounts, always in two
steps: the bot posts a preview with a 4-digit code, and nothing changes until someone
replies /确认 <code> within pool_admin_confirm_sec (120 s). /取消 drops what is waiting;
a code works once.
| In the group | Preview |
|---|---|
/删除 邮箱 (/删号) |
the account, its pool and authorization state; close emails are suggested when nothing matches |
a .json file |
read from the file WeChat saved under wechat_files_dir/wxid_*/msg/file/YYYY-MM/ |
| account JSON pasted as text | copied through WeChat's own 复制 menu (the clipboard), never read off the screenshot |
The server side is a local-only endpoint of the pool gateway
(POST /api/monitoring/account-pool/bot/accounts/{import,delete}[-preview]) with its own
write token, /etc/aiproxy/pool-bot-admin.token (root only); requests through nginx or a
tunnel get 403 even with the token. It reuses the admin console's import and delete code: a
deleted account file is backed up first, and the provider runtime restarts for a few
seconds. Account JSON crosses the ssh session base64-encoded through echo (never on a
command line), stays in the bot's memory only until confirmed or expired, and neither the
bot's log nor its replies show a token. The main chat refuses these commands.
The reply advisor loads:
E:\WeChatCustomerBot\skills\wechat-tt-customer-service\SKILL.md
The raw exports stay local under data\raw_wechat and are ignored by git. The distilled notes are under data\distilled.
Voice bubbles are detected as voice. The current safe behavior is:
- if WeChat already shows a text transcript, treat the transcript as text
- if there is no visible transcript, do not guess the content
- return
handoffand let the administrator or a later UI workflow perform WeChat's built-in "转文字"
Automatic right-click "转文字" is not enabled yet because it needs per-window menu calibration.
The bot should not automatically handle:
- transfers, payments, collections, or loan requests
- verification codes, passwords, accounts, or private information
- meetups, addresses, schedules, or promises with real-world consequences
- serious emotional conflict, threats, complaints, or legal/illegal topics
- voice messages without visible transcript
- unclear screenshots or images
High-risk events should be handed to the human user.