aamp-wechat-bridge

Local bridge daemon that connects a QR-authenticated WeChat bot session to a target AAMP agent.

Install

npm install
npm run build

Usage

Initialize local bridge config and mailbox identity, then scan the QR code to login and start the daemon:

./dist/index.js init

If the target Agent prints a pairing URL, initialize and authorize the bridge in one step:

./dist/index.js init --pairing-url "aamp://[email protected]&pair_code=abc123"

The bridge sends pair.request from its own AAMP mailbox with dispatchContextRules={ "source": ["wechat"] }, so the Agent can accept future WeChat dispatches without manual sender policy editing. The Agent replies with pair.respond to indicate success or a failure reason.

If you only want to write the local config without logging in or starting:

./dist/index.js init --no-start

login, start, and run remain available for existing configs:

./dist/index.js login
./dist/index.js start

Inspect current config and login state:

./dist/index.js status

Desktop and other non-interactive clients can use JSON output:

./dist/index.js init --json --no-start --target-agent [email protected]
./dist/index.js login --json
./dist/index.js status --json
./dist/index.js start --json

login --json emits JSONL events such as wechat.qr.created, wechat.qr.status, and wechat.login.completed, so desktop clients can render the QR code and login progress without parsing terminal output.

By default, bridge config and runtime state are stored under ~/.aamp/wechat-bridge/.

What it does

The bridge is designed for users who want to keep WeChat bot credentials on their own machine rather than in a hosted bridge service.

It can:

• authenticate through terminal QR scan
• poll the WeChat bot gateway directly without depending on WeClaw or OpenClaw
• provision or reuse an AAMP mailbox identity for the bridge
• dispatch each chat turn as a fresh task.dispatch
• preserve sticky conversation state through X-AAMP-Session-Key
• map task.ack to the WeChat typing indicator
• translate task.result and task.help_needed back into WeChat text replies

Dispatch context

Each dispatch sent by the bridge includes WeChat-specific routing metadata in X-AAMP-Dispatch-Context, including:

• source=wechat
• wechat_account_id
• wechat_sender_id
• wechat_context_token

Each dispatch also carries a separate X-AAMP-Session-Key header for sticky conversation routing.

The key design rule is:

• each user message becomes a new task.dispatch
• session continuity is expressed through X-AAMP-Session-Key, not by reusing the same taskId

Runtimes such as aamp-openclaw-plugin and aamp-acp-bridge can use that session key to keep multiple turns inside the same underlying agent session.

Current limitations

• direct messages only; no group chat support yet
• media attachments are currently summarized as text notes instead of being relayed natively