中文文档

Reverse-engineered TypeScript client for QClaw's WeChat Access API.

QClaw (管家 OpenClaw) is a Tencent Electron desktop app that wraps an OpenClaw AI Gateway service. It authenticates exclusively through WeChat OAuth2 QR-code login and communicates with Tencent backend servers via a jprx gateway protocol. This library implements that protocol as a standalone TypeScript module.

Extracted from QClaw.app -> Contents/Resources/app.asar (unencrypted). The API service class (tS / openclawApiService) was found in the bundled renderer at out/renderer/assets/platform-QEsQ5tXh.js.

npm install qclaw-wechat-client # or pnpm add qclaw-wechat-client

pnpm install # install dependencies pnpm build # bundle with tsdown pnpm typecheck # type-check only

import { QClawClient } from "qclaw-wechat-client"; import type { WxLoginStateData, WxLoginData } from "qclaw-wechat-client"; const client = new QClawClient({ env: "production" }); // Step 1 - get login state (CSRF token) const stateRes = await client.getWxLoginState({ guid: "machine-id" }); const state = QClawClient.unwrap<WxLoginStateData>(stateRes)?.state; // Step 2 - show QR code to user const qrUrl = client.buildWxLoginUrl(state!); console.log("Scan this:", qrUrl); // Step 3 - exchange auth code (from WeChat redirect) for session const loginRes = await client.wxLogin({ guid: "machine-id", code: authCode, state: state! }); // Step 4 - build OpenClaw config patch const channelToken = QClawClient.unwrap<WxLoginData>(loginRes)?.openclaw_channel_token; const config = await client.buildPostLoginConfig(channelToken!); // -> { channels: { "wechat-access": { token } }, models: { providers: { qclaw: { apiKey } } } }

The included example walks through the full WeChat login flow with an echo bot:

pnpm demo # interactive full-flow demo (login + AGP echo bot)

QClawClient.getEnvUrls("production") // environment URLs without instantiation QClawClient.getWxLoginConfig("production") // WeChat OAuth config QClawClient.Endpoints // all endpoint path constants QClawClient.unwrap<T>(response) // unwrap Tencent nested envelope

The library also includes a full implementation of the AGP (Agent Gateway Protocol) -- the WebSocket protocol used for real-time message exchange between your agent and WeChat users.

This is a server-push channel: the server sends session.prompt when a WeChat user messages your agent, and you stream back AI responses via session.update + session.promptResponse.

import { AGPClient } from "qclaw-wechat-client"; import type { PromptMessage, CancelMessage } from "qclaw-wechat-client"; const client = new AGPClient( { url: "wss://mmgrcalltoken.3g.qq.com/agentwss", token: channelToken, // from wxLogin or refreshChannelToken }, { onConnected() { console.log("Connected! Waiting for messages..."); }, onPrompt(msg: PromptMessage) { const { session_id, prompt_id, content } = msg.payload; const text = content.map(b => b.text).join(""); console.log(`User says: ${text}`); // Stream a response client.sendMessageChunk(session_id, prompt_id, "Hello "); client.sendMessageChunk(session_id, prompt_id, "World!"); // Finalize the turn client.sendTextResponse(session_id, prompt_id, "Hello World!"); }, onCancel(msg: CancelMessage) { const { session_id, prompt_id } = msg.payload; client.sendCancelledResponse(session_id, prompt_id); }, onError(err) { console.error(err); }, }, ); client.start();

All messages are JSON text frames with a unified envelope:

{ "msg_id": "uuid-v4", "guid": "device-id", "user_id": "user-id", "method": "session.prompt", "payload": { ... } }

Downlink (server -> client):

• session.prompt -- user message with session_id, prompt_id, agent_app, content
• session.cancel -- abort an in-progress turn

Uplink (client -> server):

• session.update -- streaming chunks: message_chunk, tool_call, tool_call_update
• session.promptResponse -- final answer with stop_reason: end_turn | cancelled | error | refusal

• Auto-reconnect: exponential backoff (3s base, 1.5x multiplier, 25s cap)
• Heartbeat: native WS ping every 20s, pong timeout = 2x interval
• System wakeup detection: timer drift > 15s triggers reconnect
• Message dedup: Set of processed msg_ids, cleaned every 5min (max 1000)

All endpoints are POST requests to {jprxGateway}{endpoint}.

Headers:

Content-Type : application/json X-Version : 1 X-Token : <loginKey from userInfo, fallback "m83qdao0AmE5"> X-Guid : <machine GUID> X-Account : <userId> X-Session : "" X-OpenClaw-Token : <JWT> (when logged in) 

Body:

{ "...endpoint-specific params", "web_version": "1.4.0", "web_env": "release" }

1. Token renewal - if the response contains an X-New-Token header, the client auto-updates the stored JWT
2. Session expiry - if common.code === 21004 anywhere in the nested response, all auth state is cleared
3. Success - ret === 0 and common.code === 0
4. Data extraction - actual payload is at data.resp.data || data.data || data (Tencent envelope)

The WxLoginConfig interface exposes per-environment OAuth settings:

The OAuth scope (snsapi_login) is hardcoded in buildWxLoginUrl().

After login, the Electron app writes these to the gateway config:

channels: wechat-access: token: <openclaw_channel_token> # from wxLogin response wsUrl: <wss://...> # injected by main process per environment models: providers: qclaw: apiKey: <key> # from createApiKey response baseUrl: <https://...> # injected by main process per environment

Protected paths (not overwritten during config template merges):

• channels.wechat-access.token
• channels.wechat-access.wsUrl
• models.providers.qclaw.apiKey

MIT