Skip to content

nightsailer/wechat-clawbot

BranchesTags

Repository files navigation

wechat-clawbot

中文版 | English

WeChat iLink Bot SDK with multi-user, multi-endpoint gateway for AI backends (Claude Code, Codex, custom bots).

Ported from @tencent-weixin/openclaw-weixin (TypeScript), synced with upstream v2.1.1.

WeChat Bot Constraint: Each WeChat account can create only one Bot, and that Bot is exclusively bound to the creator's WeChat account (1:1). Multiple people cannot share a single Bot. The gateway manages multiple Bots (each from a different WeChat user) routing to multiple endpoints.

Two operating modes:

  • Channel Mode — single-user, single-endpoint MCP bridge for Claude Code
  • Gateway Mode (v0.4.0+) — multi-user, multi-endpoint routing gateway

New to this project? Read the Usage Guide for step-by-step scenarios covering deployment, daily operations, SDK development, and more.

Channel Mode:
  ┌─────────────────────────────────────────────────────┐
  │  WeChat ──> iLink API ──> [bridge] ──> Claude Code  │
  └─────────────────────────────────────────────────────┘

Gateway Mode:
  ┌─────────────────────────────────────────────────────┐
  │                ┌──> MCP SSE  ──> Claude Code        │
  │  WeChat Bots ──┤──> SDK WS   ──> Custom Bot         │
  │                └──> HTTP     ──> Webhook Service    │
  └─────────────────────────────────────────────────────┘

Features

  • Full ilink API client — getUpdates long-poll, sendMessage, getConfig, sendTyping, with iLink-App-Id / iLink-App-ClientVersion protocol headers
  • Multi-Bot account support — QR code login with IDC redirect, credential storage, stale account cleanup (each Bot is 1:1 bound to its creator's WeChat account)
  • Media pipeline — AES-128-ECB encrypted CDN upload/download with full_url direct-URL support, image/video/file/voice
  • Context token persistence — survives process restarts, disk-backed with change detection
  • SILK transcoding — voice message to WAV conversion (optional)
  • Message processing — inbound conversion, slash commands, debug mode, error notices
  • Claude Code Channel — MCP server bridging WeChat messages into Claude Code sessions
  • Gateway mode — multi-user, multi-endpoint routing gateway with delivery queue, session management, admin API, and SDK client library
  • Secure logging — automatic redaction of sensitive fields (tokens, authorization) in log output
  • Async-first — built on httpx + anyio with shared connection pools

Requirements

  • Python 3.10+
  • uv (recommended) or pip

Installation

uv add wechat-clawbot

Or with pip:

pip install wechat-clawbot

Optional extras:

uv add "wechat-clawbot[gateway]"  # Gateway mode (+pyyaml, uvicorn)
uv add "wechat-clawbot[sdk]"      # SDK client (+websockets)
uv add "wechat-clawbot[silk]"     # SILK voice transcoding
uv add "wechat-clawbot[socks]"    # SOCKS proxy support
Extra Dependencies Use case
Core (no extra) anyio, httpx, pydantic, cryptography, qrcode, mcp Channel mode (Claude Code)
[gateway] +pyyaml, uvicorn Gateway mode (clawbot-gateway CLI)
[sdk] +websockets SDK client (ClawBotClient)
[silk] +graiax-silkcoder SILK voice transcoding
[socks] +httpx[socks] SOCKS proxy support

Channel Mode (Single-User)

Quick Start — Claude Code Channel

1. Login with WeChat QR code

wechat-clawbot-cc setup

Scan the terminal QR code with WeChat. Credentials are saved to ~/.claude/channels/wechat/account.json.

2. Register the MCP server

claude mcp add wechat -- wechat-clawbot-cc serve

3. Start Claude Code with the WeChat channel

claude --dangerously-load-development-channels server:wechat

Send a message in WeChat ClawBot, and Claude will reply.

Bridge Mode (via Gateway)

If you already have a running Gateway, use bridge mode instead of direct QR login. The bridge connects to the Gateway's SSE endpoint and forwards WeChat messages to your AI client.

Claude Code with bridge mode:

# Register MCP server in bridge mode
claude mcp add wechat -- wechat-clawbot-cc serve --gateway http://localhost:8765 --endpoint my-project

# Start Claude Code with WeChat channel
claude --dangerously-load-development-channels server:wechat

WeChat messages are pushed into the Claude Code session via notifications/claude/channel. Claude replies using the wechat_reply tool.

Codex with bridge mode:

# Register MCP server in bridge mode
codex mcp add wechat -- wechat-clawbot-cc serve --gateway http://localhost:8765 --endpoint my-project

Codex does not support channel push. The bridge adapts via:

  • Sends notifications/resources/updated when new messages arrive
  • Codex calls wechat_get_messages tool to fetch pending messages
  • Codex calls wechat_reply tool to send replies

Bridge mode flags:

Flag Description
--gateway <url> Gateway URL (e.g. http://localhost:8765)
--endpoint <id> Endpoint ID in the gateway (required)
--api-key <key> Gateway auth key (optional, matches gateway admin_token)

Direct single-user mode is unaffected — omitting --gateway works exactly as before.

Quick Start — Python SDK

import asyncio
from wechat_clawbot.api.client import WeixinApiOptions, get_updates, send_message
from wechat_clawbot.api.types import (
    MessageType, MessageState, MessageItemType,
    SendMessageReq, WeixinMessage, MessageItem, TextItem,
)

async def main():
    opts = WeixinApiOptions(base_url="https://ilinkai.weixin.qq.com", token="your-bot-token")

    # Long-poll for messages
    resp = await get_updates(base_url=opts.base_url, token=opts.token)
    for msg in resp.msgs or []:
        print(f"From: {msg.from_user_id}, Text: {msg.item_list}")

    # Send a reply
    await send_message(opts, SendMessageReq(msg=WeixinMessage(
        to_user_id="user@im.wechat",
        client_id="my-client-id",
        message_type=MessageType.BOT,
        message_state=MessageState.FINISH,
        item_list=[MessageItem(type=MessageItemType.TEXT, text_item=TextItem(text="Hello!"))],
        context_token="token-from-getupdates",
    )))

asyncio.run(main())

Gateway Mode (v0.4.0+)

The gateway provides multi-Bot, multi-endpoint routing: multiple WeChat Bot accounts (each exclusively owned by a different WeChat user) can route messages to multiple upstream AI endpoints. Each Bot owner independently selects, switches, and binds endpoints via in-chat commands.

Architecture

  • Accounts (downstream) — one or more WeChat Bot accounts (each 1:1 bound to its creator's WeChat account), each polling ilink API
  • Endpoints (upstream) — AI backends connected via MCP SSE, SDK WebSocket, or HTTP webhook
  • Router — resolves each inbound message to an endpoint based on active selection, @mention, or /command
  • Session store — per-user state (active endpoint, bindings, context tokens) persisted to disk
  • Delivery queue — SQLite-backed durable queue with retry logic
  • Admin API — separate HTTP server with Bearer token auth for management

Quick Start

# 1. Initialize configuration
clawbot-gateway init

# 2. Add a WeChat Bot account (scans QR code)
clawbot-gateway account add

# 3. Edit ~/.clawbot-gateway/gateway.yaml to configure endpoints

# 4. Start the gateway
clawbot-gateway start

Configuration Example

# ~/.clawbot-gateway/gateway.yaml
gateway:
  host: 0.0.0.0
  port: 8765
  admin_port: 8766
  admin_token: "your-secret-token"
  log_level: info

accounts:
  main-bot:
    credentials: ~/.clawbot-gateway/accounts/main-bot.json

endpoints:
  claude:
    name: "Claude Code"
    type: mcp            # MCP clients connect to gateway SSE
  my-bot:
    name: "My Bot"
    type: sdk            # SDK clients connect via WebSocket
  webhook-service:
    name: "Webhook"
    type: http           # Gateway POSTs messages to this URL
    url: "https://example.com/webhook"
    api_key: "optional-bearer-token"

routing:
  strategy: active-endpoint   # also: prefix, smart
  mention_prefix: "@"
  gateway_commands: ["/"]     # prefix(es) that trigger gateway commands

authorization:
  mode: allowlist             # also: open, invite-code
  default_endpoints: []       # endpoints auto-bound to new users
  admins: ["admin-user-id@im.wechat"]

archive:
  enabled: false
  path: ~/.clawbot-gateway/archive.db
  retention_days: 0           # 0 = keep forever

WeChat Commands

Users interact with the gateway through in-chat commands:

Command Description
/list List available endpoints
/use <name> Switch active endpoint
/to <name> <message> Send one-off message to a specific endpoint
/status Show current session status
/bind <name> Bind to an endpoint
/unbind <name> Unbind from an endpoint
/help Show help message
/admin Show system info (admin only)

Sub-Channel Types

Type Transport Direction Use Case
mcp SSE + JSON-RPC Client connects to gateway (/mcp/{id}/sse) Claude Code / MCP-compatible clients
sdk WebSocket Client connects to gateway (/sdk/{id}/ws) Custom bots using ClawBotClient SDK
http Webhook POST Gateway POSTs to endpoint URL; endpoint callbacks via /http/{id}/callback Third-party services, n8n, Zapier

SDK Client Example

import asyncio
from wechat_clawbot.sdk import ClawBotClient

async def main():
    async with ClawBotClient(
        gateway_url="http://localhost:8765",
        endpoint_id="my-bot",
    ) as client:
        async for msg in client.messages():
            print(f"From {msg.sender_id}: {msg.text}")
            await client.reply(msg.sender_id, f"Echo: {msg.text}")

asyncio.run(main())

Admin API

The admin API runs on admin_port (default 8766), protected by Bearer token when admin_token is set.

Method Endpoint Description
GET /api/status Gateway status overview
GET /api/accounts List Bot accounts
GET /api/endpoints List endpoints with status
POST /api/endpoints Add an endpoint
DELETE /api/endpoints/{id} Remove an endpoint
GET /api/users List users
POST /api/users/{id}/bind Bind user to endpoint
POST /api/users/{id}/unbind Unbind user from endpoint
GET /api/invites List invite codes
POST /api/invites Create invite code

CLI Reference

Command Description
clawbot-gateway init Initialize configuration
clawbot-gateway start Start the gateway
clawbot-gateway stop Stop the gateway
clawbot-gateway status Show gateway status
clawbot-gateway account add Add Bot account via QR login
clawbot-gateway account list List configured accounts
clawbot-gateway account remove <id> Remove an account
clawbot-gateway account status [id] Show account status
clawbot-gateway endpoint list List endpoints
clawbot-gateway endpoint add <id> [--name NAME] [--type TYPE] [--url URL] Add an endpoint
clawbot-gateway endpoint remove <id> Remove an endpoint
clawbot-gateway user list List all users
clawbot-gateway user info <id> Show user info
clawbot-gateway user allow <id> Add user to allowlist
clawbot-gateway user block <id> Block a user
clawbot-gateway user bind <uid> <eid> Bind user to endpoint
clawbot-gateway user unbind <uid> <eid> Unbind user from endpoint
clawbot-gateway invite list List active invite codes
clawbot-gateway invite create <eid> [--max-uses N] [--ttl HOURS] Create invite code
clawbot-gateway logs [-n LINES] [--endpoint ID] [--user ID] View message archive

All commands support --json for machine-readable output, --gateway <url> for remote management, --admin-token <token> for admin API authentication, and --config <path> for specifying the gateway.yaml path.

Environment variables:

Variable Description
CLAWBOT_GATEWAY_URL Default gateway admin URL (alternative to --gateway)
CLAWBOT_ADMIN_TOKEN Default admin Bearer token (alternative to --admin-token)
CLAWBOT_GATEWAY_CONFIG Path to gateway.yaml (alternative to --config)

Project Structure

src/wechat_clawbot/
  api/              # ilink HTTP API client and protocol types
  auth/             # QR login, account storage, pairing
  cdn/              # AES-128-ECB crypto, CDN upload/download
  config/           # Pydantic configuration schema
  media/            # Media download, MIME types, SILK transcoding
  messaging/        # Inbound conversion, send, slash commands, process pipeline
  monitor/          # Long-poll monitor loop
  storage/          # State directory, sync buffer persistence
  util/             # Logger, ID generation, redaction
  claude_channel/   # Claude Code MCP Channel bridge (CLI + server)
  gateway/          # Multi-Bot, multi-endpoint routing gateway (v0.4.0+)
    channels/       #   Sub-channel implementations (MCP, SDK, HTTP)
    admin.py        #   Admin HTTP API server
    app.py          #   Main gateway orchestrator
    cli.py          #   CLI entry point (clawbot-gateway)
    config.py       #   gateway.yaml schema and loader
    delivery.py     #   SQLite-backed delivery queue
    router.py       #   Message routing engine
    session.py      #   User session/state persistence
    endpoint_manager.py  # Endpoint registry with health tracking
    invite.py       #   Invite code system
    auth.py         #   Authorization module (allowlist/open/invite-code)
    archive.py      #   Message archive sidecar (SQLite)
    types.py        #   Core dataclasses and enums
  sdk/              # ClawBotClient library for custom bots

Development

git clone https://github.com/nightsailer/wechat-clawbot.git
cd wechat-clawbot
uv sync

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

Documentation

  • Usage Guide — Scenario-based guide: deployment, team setup, SDK development, webhook integration, maintenance, and troubleshooting
  • Python SDK API — Public API reference for wechat-clawbot
  • iLink Bot Protocol — WeChat ClawBot iLink API protocol reference

License

MIT

About

Python SDK for the WeChat ClawBot ilink API, with a built-in multi-user gateway for AI backends (Claude Code, Codex, custom bots).

Topics

weixin wechat wechat-sdk weixin-sdk claude-code clawbot

Resources

Readme

License

MIT license
Activity

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v0.3.0 Latest
Mar 29, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages