Architecture
wx serve speaks WeChat’s own protocol, like the desktop app does. No WeChat app, screen or browser runs anywhere.
Your WeChat profile stays the main store. History, contacts and media are kept in the same encrypted format WeChat for Linux uses, either in a profile the daemon created or in an existing one used with --official. Messages the daemon sends or receives are written there as if the app had handled them.
The daemon keeps its own data separately: login credentials, queued sends and downloads, the event log, and anything the profile has no place for.
Every client uses the same HTTP API. The CLI is a thin client for it. The OpenClaw plugin follows the event stream and calls the same routes, and so can any other agent plugin or app. See HTTP API.
Inside the daemon
| Part | Job |
|---|---|
| Account worker | One per account: holds the connection to WeChat, keeps the login alive, and coordinates account changes and recovery |
| Sync | Receives new messages through a push connection, falling back to polling if the connection drops |
| Profile reader/writer | Reads history through a small pool of consistent snapshots; keeps one writer for supported database layouts |
| Job queue | Runs sends, downloads, recalls and read notices, and remembers them across restarts |
| Event log | Records every committed change so clients can replay what they missed |
| HTTP server | Serves /v1, checks tokens and scopes, streams events |
For an owned profile using SQLite’s WAL journal mode, the worker briefly pauses writes to capture each request’s database and event position. It then releases the writer while the request reads and formats its results. Up to four reads per account can run together, with eight across the daemon. Profiles using other journal modes keep serialized reads; the daemon does not change their journal mode.
Downloads have a separate limit: two per account and four across the daemon. Network waits release the account writer, which checks the login and job state again before saving a result. Sticker operations, contact and room lookups, group changes and recalls also release the writer during network waits. Conflicting operations keep their ordering guards; logout and credential checks still apply before results are saved.
Added-pack lists and already indexed message media use consistent read snapshots. Discovering and registering missing media still uses the writer. Pending media is rechecked for files that may already exist in the official profile.
All clients of one daemon share a short-lived sticker metadata cache. It keeps up to 64 catalog/detail/caption responses of at most 128 KiB each for 60 seconds in memory, and combines simultaneous requests for the same metadata. Restarting clears it. Entries are separated by account and authenticated session; logout removes that account’s entries. Membership and media availability are read from the profile and existing media records, not from this cache.
See Rust crate architecture for packages and dependencies, and Rust libraries for direct library use.