gem-hunter

qclaw-wechat-client

Warning

This project is being unmaintained. It is recommended to switch to WeChat's official iLink protocol. 该项目已不再维护。我们推荐使用微信团队官方的iLink协议（基于微信ClawBot）。

Origin

Install

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

Development

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

Quick start

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 } } } }

Demo

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

API

new QClawClient(options?)

Properties

Methods

Authentication

Keys & tokens

Invite codes

Device management

Updates

Config helpers

Static methods

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

AGP WebSocket Client

Quick start (WebSocket)

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();

new AGPClient(config, callbacks?)

Callbacks

Send methods

Lifecycle methods

AGP Protocol

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

Connection features

HTTP Protocol details

Request format

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)

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

Response handling

Environment URLs

WeChat OAuth

OpenClaw config paths

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

License