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

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