Skip to content

Architecture

Your machine HTTP HTTP + events HTTP WeChat protocol wx CLI OpenClaw plugin Other agents and apps WeChat servers wx serve WeChat profilehistory, contacts, media Daemon datacredentials, jobs, events

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

PartJob
Account workerOne per account: holds the connection to WeChat, keeps the login alive, and coordinates account changes and recovery
SyncReceives new messages through a push connection, falling back to polling if the connection drops
Profile reader/writerReads history through a small pool of consistent snapshots; keeps one writer for supported database layouts
Job queueRuns sends, downloads, recalls and read notices, and remembers them across restarts
Event logRecords every committed change so clients can replay what they missed
HTTP serverServes /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.