weixin-standalone-api

中文文档

独立的微信机器人 API 服务（不依赖 OpenClaw 运行时）。

功能

• 手机微信扫码登录
• 入站消息轮询 + 本地事件队列
• 文本/图片发送接口
• 账号与 worker 管理接口

运行要求

• Node.js >=22
• 可访问的微信 iLink bot 后端

安装

npm i -g @dadb/weixin-standalone-api

或：

npm i @dadb/weixin-standalone-api

启动

WEIXIN_STANDALONE_TOKEN='replace_me' \
WEIXIN_STANDALONE_HOST='127.0.0.1' \
WEIXIN_STANDALONE_PORT='8788' \
weixin-standalone-api

环境变量

• WEIXIN_STANDALONE_TOKEN：API 访问令牌，空则不鉴权
• WEIXIN_STANDALONE_HOST：默认 127.0.0.1
• WEIXIN_STANDALONE_PORT：默认 8788
• WEIXIN_STANDALONE_STATE_DIR：默认 ./.weixin-standalone
• WEIXIN_BASE_URL：默认 https://ilinkai.weixin.qq.com
• WEIXIN_CDN_BASE_URL：默认 https://novac2c.cdn.weixin.qq.com/c2c
• WEIXIN_BOT_TYPE：默认 "3"

鉴权

设置了 WEIXIN_STANDALONE_TOKEN 后，除 /healthz 外都要带：

Authorization: Bearer <WEIXIN_STANDALONE_TOKEN>

返回格式

成功：

{ "requestId": "uuid", "data": {} }

失败：

{ "requestId": "uuid", "error": "错误信息" }

API 说明

GET /healthz

POST /v1/login/qr/start

请求体：

{ "accountId": "可选", "botType": "可选", "baseUrl": "可选" }

返回：

{ "requestId": "...", "data": { "sessionKey": "...", "qrcodeUrl": "..." } }

POST /v1/login/qr/wait

请求体：

{ "sessionKey": "...", "timeoutMs": 480000 }

返回：

{ "requestId": "...", "data": { "connected": true, "accountId": "xxx-im-bot", "userId": "[email protected]" } }

GET /v1/accounts

POST /v1/workers/start

请求体：

{ "accountId": "xxx-im-bot" }

POST /v1/workers/stop

请求体：

{ "accountId": "xxx-im-bot" }

POST /v1/messages/text

请求体：

{
  "accountId": "xxx-im-bot",
  "to": "[email protected]",
  "text": "hello",
  "contextToken": "可选"
}

说明：contextToken 是上游会话关键字段；不传则尝试命中缓存 (accountId,to)。

POST /v1/messages/image

请求体（本地文件）：

{
  "accountId": "xxx-im-bot",
  "to": "[email protected]",
  "filePath": "/tmp/a.jpg",
  "text": "可选",
  "contextToken": "可选"
}

请求体（远程 URL）：

{
  "accountId": "xxx-im-bot",
  "to": "[email protected]",
  "imageUrl": "https://example.com/a.jpg",
  "text": "可选",
  "contextToken": "可选"
}

约束：filePath/imageUrl 二选一；imageUrl 必须 https；最大 20MB。

GET /v1/events?accountId=xxx-im-bot&limit=100&cursor=<eventId>

参数：accountId 必填，limit 可选（1..500，默认 100），cursor 可选。

POST /v1/events/ack

请求体：

{ "accountId": "xxx-im-bot", "ids": ["event-id-1", "event-id-2"] }

返回：

{ "requestId": "...", "data": { "acked": 2 } }

最小联调流程

1. 启动服务
2. 调 /v1/login/qr/start
3. 手机微信扫码
4. 调 /v1/login/qr/wait 直到 connected=true
5. 调 /v1/accounts 看账号和 worker
6. 调 /v1/events 拉入站消息
7. 用事件里的 contextToken 调 /v1/messages/text 或 /v1/messages/image
8. 调 /v1/events/ack 确认消费

开发与发布

npm install
npm run dev
npm run typecheck
npm run build
npm run version:bump
npm publish

English

Standalone Weixin bot API server without OpenClaw runtime dependency.

Features

• QR login via mobile Weixin app
• inbound polling + local event queue
• send text/image APIs
• account and worker management

Install

npm i -g @dadb/weixin-standalone-api

Run

WEIXIN_STANDALONE_TOKEN='replace_me' \
WEIXIN_STANDALONE_HOST='127.0.0.1' \
WEIXIN_STANDALONE_PORT='8788' \
weixin-standalone-api

Environment Variables

• WEIXIN_STANDALONE_TOKEN: bearer auth token, optional
• WEIXIN_STANDALONE_HOST: default 127.0.0.1
• WEIXIN_STANDALONE_PORT: default 8788
• WEIXIN_STANDALONE_STATE_DIR: default ./.weixin-standalone
• WEIXIN_BASE_URL: default https://ilinkai.weixin.qq.com
• WEIXIN_CDN_BASE_URL: default https://novac2c.cdn.weixin.qq.com/c2c
• WEIXIN_BOT_TYPE: default "3"

Auth

When token is set, all endpoints except /healthz require:

Authorization: Bearer <WEIXIN_STANDALONE_TOKEN>

Response

Success:

{ "requestId": "uuid", "data": {} }

Error:

{ "requestId": "uuid", "error": "message" }

Endpoints

• GET /healthz
• POST /v1/login/qr/start
• POST /v1/login/qr/wait
• GET /v1/accounts
• POST /v1/workers/start
• POST /v1/workers/stop
• POST /v1/messages/text
• POST /v1/messages/image
• GET /v1/events
• POST /v1/events/ack

Minimal Flow

1. Start server
2. Call /v1/login/qr/start
3. Scan QR with mobile Weixin app
4. Poll /v1/login/qr/wait until connected=true
5. Pull inbound events from /v1/events
6. Reply with /v1/messages/text or /v1/messages/image
7. Ack via /v1/events/ack