English | 中文
🐋 Whale Girl
A local-first AI companion for WeChat. She replies in group chats, remembers what people tell her, and can also send stickers, voice messages, and daily diary entries.
Everything is controlled from one Windows launcher. There is no browser UI; 127.0.0.1:8787 only serves the local HTTP API.
Just want to run it? Download whale-girl-*-setup.exe from Releases.
The installer includes Node.js, Python 3.12 and the .NET 10 desktop runtime, so no extra downloads are needed.
What it does
- WeChat replies — answers @-mentions and her name in groups, keeps a conversation going while it is alive, and stays quiet when the topic ends.
- Memory — records facts from private chats, compresses older group history, and stays silent when an image or sticker cannot be read.
- Human-like delivery — splits a reply into short bubbles, avoids trailing punctuation, and rewrites repeated or parroted replies once.
- Extras — stickers, Moments reading and manual interaction, Markdown diary, voice replies, web search, hot lists, and basic group admin.
- One control panel — start, stop, configure, and diagnose everything from
WhaleLauncher.exe.
Requirements
- Windows 10 or 11
- A logged-in WeChat 4.x account (a secondary account is recommended)
- One model API key: DeepSeek, Zhipu GLM, SiliconFlow, Qwen, Doubao, OpenCode, or any OpenAI-compatible endpoint
- Optional: Ollama or another local OpenAI-compatible server
- Administrator rights for WeChat UI automation
- Install into an ASCII-only path such as
D:\whale-girl; Chinese characters in the path can break WeChat automation
Install and first run
- Download
whale-girl-*-setup.exe from Releases and run it.
- Open the Whale Girl desktop shortcut.
- In the launcher, open Settings, choose a model provider, and fill in the API key.
- Open WeChat bridge, select the account, then press Start.
- Wait until the Status page shows both the kernel and the bridge as running.
The installer bundles the Node.js runtime, Python 3.12, wechatauto, and the .NET 10 desktop runtime. The launcher prefers bundled runtimes and falls back to PATH only when needed. No npm install is required.
Main features
| Feature | What it does |
|---|
| WeChat group replies | Replies to @-mentions and her name; ignores unrelated arguments |
| Memory | Remembers owner facts and compresses old group conversations |
| Stickers | 27 built-in images plus custom categories; sending is off by default |
| Moments | Reads the selected account's local cache; manual like, comment, and copy-draft |
| Diary | Writes at most one Markdown entry per day to data/diary/YYYY/MM-DD.md |
| Voice | Transcribes incoming voice; optional voice replies through BreezeBlue, MiniMax, or SiliconFlow |
| Search | Bing with a 360 fallback, Bilibili/Weibo hot lists, Toutiao, and link extraction |
| Group admin | Mute/unmute, switch model, change tone, clear memory, and low-battery good-night |
| Diagnostics | Built-in logs, account checks, UIA self-test, and update checks |
Detailed behavior and configuration are documented under docs/.
Updates and stopping
- Update: open Check for updates in the launcher. It reads
release-manifest.json, downloads the official installer, verifies SHA256, and installs over the old version. data/ and config.json are preserved.
- Stop: press Stop in the launcher, then close it. The kernel and bridge stop together.
- Optional cleanup: after closing the launcher, run
powershell -File scripts\stop-all.ps1 if a process is left behind. It writes data\PAUSED so nothing restarts automatically.
- Resume: open
WhaleLauncher.exe and press Start; the pause marker is cleared.
Configuration
Most settings live in the launcher's Settings page. Advanced users can edit config.json directly. The template is config/config.example.json; config.json is git-ignored.
| Field | Meaning |
|---|
provider / deepseek.apiKey | Model provider and key |
persona.master.names / persona.master.wxids | Who counts as the owner |
gateway.wechat.inboundToken | Bridge token; change it from the default |
group.requireAt | Whether group messages must @ the bot first |
chat.privateMaxChars | Reply length limit |
diary.enabled / diary.time | Daily diary switch and generation time |
The full field list is in docs/设置说明.md. Owner and admin rules are explained there as well.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
