{"id":47632440,"url":"https://github.com/nightsailer/wechat-clawbot","last_synced_at":"2026-04-01T23:50:07.088Z","repository":{"id":346147744,"uuid":"1188485900","full_name":"nightsailer/wechat-clawbot","owner":"nightsailer","description":"Python SDK for the WeChat ClawBot ilink API, with a built-in multi-user gateway for AI backends (Claude Code, Codex, custom bots).","archived":false,"fork":false,"pushed_at":"2026-03-30T03:34:16.000Z","size":401,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-30T05:59:31.614Z","etag":null,"topics":["claude-code","clawbot","wechat","wechat-sdk","weixin","weixin-sdk"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nightsailer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T06:20:03.000Z","updated_at":"2026-03-30T05:34:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nightsailer/wechat-clawbot","commit_stats":null,"previous_names":["nightsailer/wechat-clawbot"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nightsailer/wechat-clawbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightsailer%2Fwechat-clawbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightsailer%2Fwechat-clawbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightsailer%2Fwechat-clawbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightsailer%2Fwechat-clawbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nightsailer","download_url":"https://codeload.github.com/nightsailer/wechat-clawbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightsailer%2Fwechat-clawbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","clawbot","wechat","wechat-sdk","weixin","weixin-sdk"],"created_at":"2026-04-01T23:50:06.319Z","updated_at":"2026-04-01T23:50:07.016Z","avatar_url":"https://github.com/nightsailer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wechat-clawbot\n\n[中文版](README.zh.md) | English\n\nWeChat iLink Bot SDK with multi-user, multi-endpoint gateway for AI backends (Claude Code, Codex, custom bots).\n\nPorted from [@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) (TypeScript), synced with upstream v2.1.1.\n\n\u003e **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.\n\nTwo operating modes:\n\n- **Channel Mode** — single-user, single-endpoint MCP bridge for Claude Code\n- **Gateway Mode** (v0.4.0+) — multi-user, multi-endpoint routing gateway\n\n\u003e **New to this project?** Read the [Usage Guide](docs/guide.md) for step-by-step scenarios covering deployment, daily operations, SDK development, and more.\n\n```\nChannel Mode:\n  ┌─────────────────────────────────────────────────────┐\n  │  WeChat ──\u003e iLink API ──\u003e [bridge] ──\u003e Claude Code  │\n  └─────────────────────────────────────────────────────┘\n\nGateway Mode:\n  ┌─────────────────────────────────────────────────────┐\n  │                ┌──\u003e MCP SSE  ──\u003e Claude Code        │\n  │  WeChat Bots ──┤──\u003e SDK WS   ──\u003e Custom Bot         │\n  │                └──\u003e HTTP     ──\u003e Webhook Service    │\n  └─────────────────────────────────────────────────────┘\n```\n\n## Features\n\n- **Full ilink API client** — getUpdates long-poll, sendMessage, getConfig, sendTyping, with `iLink-App-Id` / `iLink-App-ClientVersion` protocol headers\n- **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)\n- **Media pipeline** — AES-128-ECB encrypted CDN upload/download with `full_url` direct-URL support, image/video/file/voice\n- **Context token persistence** — survives process restarts, disk-backed with change detection\n- **SILK transcoding** — voice message to WAV conversion (optional)\n- **Message processing** — inbound conversion, slash commands, debug mode, error notices\n- **Claude Code Channel** — MCP server bridging WeChat messages into Claude Code sessions\n- **Gateway mode** — multi-user, multi-endpoint routing gateway with delivery queue, session management, admin API, and SDK client library\n- **Secure logging** — automatic redaction of sensitive fields (tokens, authorization) in log output\n- **Async-first** — built on httpx + anyio with shared connection pools\n\n## Requirements\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n\n## Installation\n\n```bash\nuv add wechat-clawbot\n```\n\nOr with pip:\n\n```bash\npip install wechat-clawbot\n```\n\nOptional extras:\n\n```bash\nuv add \"wechat-clawbot[gateway]\"  # Gateway mode (+pyyaml, uvicorn)\nuv add \"wechat-clawbot[sdk]\"      # SDK client (+websockets)\nuv add \"wechat-clawbot[silk]\"     # SILK voice transcoding\nuv add \"wechat-clawbot[socks]\"    # SOCKS proxy support\n```\n\n| Extra | Dependencies | Use case |\n|-------|-------------|----------|\n| Core (no extra) | anyio, httpx, pydantic, cryptography, qrcode, mcp | Channel mode (Claude Code) |\n| `[gateway]` | +pyyaml, uvicorn | Gateway mode (clawbot-gateway CLI) |\n| `[sdk]` | +websockets | SDK client (ClawBotClient) |\n| `[silk]` | +graiax-silkcoder | SILK voice transcoding |\n| `[socks]` | +httpx[socks] | SOCKS proxy support |\n\n## Channel Mode (Single-User)\n\n### Quick Start — Claude Code Channel\n\n### 1. Login with WeChat QR code\n\n```bash\nwechat-clawbot-cc setup\n```\n\nScan the terminal QR code with WeChat. Credentials are saved to `~/.claude/channels/wechat/account.json`.\n\n### 2. Register the MCP server\n\n```bash\nclaude mcp add wechat -- wechat-clawbot-cc serve\n```\n\n### 3. Start Claude Code with the WeChat channel\n\n```bash\nclaude --dangerously-load-development-channels server:wechat\n```\n\nSend a message in WeChat ClawBot, and Claude will reply.\n\n### Bridge Mode (via Gateway)\n\nIf 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.\n\n**Claude Code with bridge mode:**\n\n```bash\n# Register MCP server in bridge mode\nclaude mcp add wechat -- wechat-clawbot-cc serve --gateway http://localhost:8765 --endpoint my-project\n\n# Start Claude Code with WeChat channel\nclaude --dangerously-load-development-channels server:wechat\n```\n\nWeChat messages are pushed into the Claude Code session via `notifications/claude/channel`. Claude replies using the `wechat_reply` tool.\n\n**Codex with bridge mode:**\n\n```bash\n# Register MCP server in bridge mode\ncodex mcp add wechat -- wechat-clawbot-cc serve --gateway http://localhost:8765 --endpoint my-project\n```\n\nCodex does not support channel push. The bridge adapts via:\n- Sends `notifications/resources/updated` when new messages arrive\n- Codex calls `wechat_get_messages` tool to fetch pending messages\n- Codex calls `wechat_reply` tool to send replies\n\n**Bridge mode flags:**\n\n| Flag | Description |\n|------|-------------|\n| `--gateway \u003curl\u003e` | Gateway URL (e.g. `http://localhost:8765`) |\n| `--endpoint \u003cid\u003e` | Endpoint ID in the gateway (required) |\n| `--api-key \u003ckey\u003e` | Gateway auth key (optional, matches gateway admin_token) |\n\n**Direct single-user mode is unaffected** — omitting `--gateway` works exactly as before.\n\n## Quick Start — Python SDK\n\n```python\nimport asyncio\nfrom wechat_clawbot.api.client import WeixinApiOptions, get_updates, send_message\nfrom wechat_clawbot.api.types import (\n    MessageType, MessageState, MessageItemType,\n    SendMessageReq, WeixinMessage, MessageItem, TextItem,\n)\n\nasync def main():\n    opts = WeixinApiOptions(base_url=\"https://ilinkai.weixin.qq.com\", token=\"your-bot-token\")\n\n    # Long-poll for messages\n    resp = await get_updates(base_url=opts.base_url, token=opts.token)\n    for msg in resp.msgs or []:\n        print(f\"From: {msg.from_user_id}, Text: {msg.item_list}\")\n\n    # Send a reply\n    await send_message(opts, SendMessageReq(msg=WeixinMessage(\n        to_user_id=\"user@im.wechat\",\n        client_id=\"my-client-id\",\n        message_type=MessageType.BOT,\n        message_state=MessageState.FINISH,\n        item_list=[MessageItem(type=MessageItemType.TEXT, text_item=TextItem(text=\"Hello!\"))],\n        context_token=\"token-from-getupdates\",\n    )))\n\nasyncio.run(main())\n```\n\n## Gateway Mode (v0.4.0+)\n\nThe 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.\n\n### Architecture\n\n- **Accounts** (downstream) — one or more WeChat Bot accounts (each 1:1 bound to its creator's WeChat account), each polling ilink API\n- **Endpoints** (upstream) — AI backends connected via MCP SSE, SDK WebSocket, or HTTP webhook\n- **Router** — resolves each inbound message to an endpoint based on active selection, `@mention`, or `/command`\n- **Session store** — per-user state (active endpoint, bindings, context tokens) persisted to disk\n- **Delivery queue** — SQLite-backed durable queue with retry logic\n- **Admin API** — separate HTTP server with Bearer token auth for management\n\n### Quick Start\n\n```bash\n# 1. Initialize configuration\nclawbot-gateway init\n\n# 2. Add a WeChat Bot account (scans QR code)\nclawbot-gateway account add\n\n# 3. Edit ~/.clawbot-gateway/gateway.yaml to configure endpoints\n\n# 4. Start the gateway\nclawbot-gateway start\n```\n\n### Configuration Example\n\n```yaml\n# ~/.clawbot-gateway/gateway.yaml\ngateway:\n  host: 0.0.0.0\n  port: 8765\n  admin_port: 8766\n  admin_token: \"your-secret-token\"\n  log_level: info\n\naccounts:\n  main-bot:\n    credentials: ~/.clawbot-gateway/accounts/main-bot.json\n\nendpoints:\n  claude:\n    name: \"Claude Code\"\n    type: mcp            # MCP clients connect to gateway SSE\n  my-bot:\n    name: \"My Bot\"\n    type: sdk            # SDK clients connect via WebSocket\n  webhook-service:\n    name: \"Webhook\"\n    type: http           # Gateway POSTs messages to this URL\n    url: \"https://example.com/webhook\"\n    api_key: \"optional-bearer-token\"\n\nrouting:\n  strategy: active-endpoint   # also: prefix, smart\n  mention_prefix: \"@\"\n  gateway_commands: [\"/\"]     # prefix(es) that trigger gateway commands\n\nauthorization:\n  mode: allowlist             # also: open, invite-code\n  default_endpoints: []       # endpoints auto-bound to new users\n  admins: [\"admin-user-id@im.wechat\"]\n\narchive:\n  enabled: false\n  path: ~/.clawbot-gateway/archive.db\n  retention_days: 0           # 0 = keep forever\n```\n\n### WeChat Commands\n\nUsers interact with the gateway through in-chat commands:\n\n| Command | Description |\n|---------|-------------|\n| `/list` | List available endpoints |\n| `/use \u003cname\u003e` | Switch active endpoint |\n| `/to \u003cname\u003e \u003cmessage\u003e` | Send one-off message to a specific endpoint |\n| `/status` | Show current session status |\n| `/bind \u003cname\u003e` | Bind to an endpoint |\n| `/unbind \u003cname\u003e` | Unbind from an endpoint |\n| `/help` | Show help message |\n| `/admin` | Show system info (admin only) |\n\n### Sub-Channel Types\n\n| Type | Transport | Direction | Use Case |\n|------|-----------|-----------|----------|\n| `mcp` | SSE + JSON-RPC | Client connects to gateway (`/mcp/{id}/sse`) | Claude Code / MCP-compatible clients |\n| `sdk` | WebSocket | Client connects to gateway (`/sdk/{id}/ws`) | Custom bots using `ClawBotClient` SDK |\n| `http` | Webhook POST | Gateway POSTs to endpoint URL; endpoint callbacks via `/http/{id}/callback` | Third-party services, n8n, Zapier |\n\n### SDK Client Example\n\n```python\nimport asyncio\nfrom wechat_clawbot.sdk import ClawBotClient\n\nasync def main():\n    async with ClawBotClient(\n        gateway_url=\"http://localhost:8765\",\n        endpoint_id=\"my-bot\",\n    ) as client:\n        async for msg in client.messages():\n            print(f\"From {msg.sender_id}: {msg.text}\")\n            await client.reply(msg.sender_id, f\"Echo: {msg.text}\")\n\nasyncio.run(main())\n```\n\n### Admin API\n\nThe admin API runs on `admin_port` (default 8766), protected by Bearer token when `admin_token` is set.\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/status` | Gateway status overview |\n| GET | `/api/accounts` | List Bot accounts |\n| GET | `/api/endpoints` | List endpoints with status |\n| POST | `/api/endpoints` | Add an endpoint |\n| DELETE | `/api/endpoints/{id}` | Remove an endpoint |\n| GET | `/api/users` | List users |\n| POST | `/api/users/{id}/bind` | Bind user to endpoint |\n| POST | `/api/users/{id}/unbind` | Unbind user from endpoint |\n| GET | `/api/invites` | List invite codes |\n| POST | `/api/invites` | Create invite code |\n\n### CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `clawbot-gateway init` | Initialize configuration |\n| `clawbot-gateway start` | Start the gateway |\n| `clawbot-gateway stop` | Stop the gateway |\n| `clawbot-gateway status` | Show gateway status |\n| `clawbot-gateway account add` | Add Bot account via QR login |\n| `clawbot-gateway account list` | List configured accounts |\n| `clawbot-gateway account remove \u003cid\u003e` | Remove an account |\n| `clawbot-gateway account status [id]` | Show account status |\n| `clawbot-gateway endpoint list` | List endpoints |\n| `clawbot-gateway endpoint add \u003cid\u003e [--name NAME] [--type TYPE] [--url URL]` | Add an endpoint |\n| `clawbot-gateway endpoint remove \u003cid\u003e` | Remove an endpoint |\n| `clawbot-gateway user list` | List all users |\n| `clawbot-gateway user info \u003cid\u003e` | Show user info |\n| `clawbot-gateway user allow \u003cid\u003e` | Add user to allowlist |\n| `clawbot-gateway user block \u003cid\u003e` | Block a user |\n| `clawbot-gateway user bind \u003cuid\u003e \u003ceid\u003e` | Bind user to endpoint |\n| `clawbot-gateway user unbind \u003cuid\u003e \u003ceid\u003e` | Unbind user from endpoint |\n| `clawbot-gateway invite list` | List active invite codes |\n| `clawbot-gateway invite create \u003ceid\u003e [--max-uses N] [--ttl HOURS]` | Create invite code |\n| `clawbot-gateway logs [-n LINES] [--endpoint ID] [--user ID]` | View message archive |\n\nAll commands support `--json` for machine-readable output, `--gateway \u003curl\u003e` for remote management, `--admin-token \u003ctoken\u003e` for admin API authentication, and `--config \u003cpath\u003e` for specifying the gateway.yaml path.\n\n**Environment variables:**\n\n| Variable | Description |\n|----------|-------------|\n| `CLAWBOT_GATEWAY_URL` | Default gateway admin URL (alternative to `--gateway`) |\n| `CLAWBOT_ADMIN_TOKEN` | Default admin Bearer token (alternative to `--admin-token`) |\n| `CLAWBOT_GATEWAY_CONFIG` | Path to `gateway.yaml` (alternative to `--config`) |\n\n## Project Structure\n\n```\nsrc/wechat_clawbot/\n  api/              # ilink HTTP API client and protocol types\n  auth/             # QR login, account storage, pairing\n  cdn/              # AES-128-ECB crypto, CDN upload/download\n  config/           # Pydantic configuration schema\n  media/            # Media download, MIME types, SILK transcoding\n  messaging/        # Inbound conversion, send, slash commands, process pipeline\n  monitor/          # Long-poll monitor loop\n  storage/          # State directory, sync buffer persistence\n  util/             # Logger, ID generation, redaction\n  claude_channel/   # Claude Code MCP Channel bridge (CLI + server)\n  gateway/          # Multi-Bot, multi-endpoint routing gateway (v0.4.0+)\n    channels/       #   Sub-channel implementations (MCP, SDK, HTTP)\n    admin.py        #   Admin HTTP API server\n    app.py          #   Main gateway orchestrator\n    cli.py          #   CLI entry point (clawbot-gateway)\n    config.py       #   gateway.yaml schema and loader\n    delivery.py     #   SQLite-backed delivery queue\n    router.py       #   Message routing engine\n    session.py      #   User session/state persistence\n    endpoint_manager.py  # Endpoint registry with health tracking\n    invite.py       #   Invite code system\n    auth.py         #   Authorization module (allowlist/open/invite-code)\n    archive.py      #   Message archive sidecar (SQLite)\n    types.py        #   Core dataclasses and enums\n  sdk/              # ClawBotClient library for custom bots\n```\n\n## Development\n\n```bash\ngit clone https://github.com/nightsailer/wechat-clawbot.git\ncd wechat-clawbot\nuv sync\n\n# Run tests\nuv run pytest tests/ -v\n\n# Lint\nuv run ruff check src/ tests/\n\n# Format\nuv run ruff format src/ tests/\n```\n\n## Documentation\n\n- **[Usage Guide](docs/guide.md)** — Scenario-based guide: deployment, team setup, SDK development, webhook integration, maintenance, and troubleshooting\n- [Python SDK API](docs/api.md) — Public API reference for wechat-clawbot\n- [iLink Bot Protocol](docs/ilink-protocol.md) — WeChat ClawBot iLink API protocol reference\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnightsailer%2Fwechat-clawbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnightsailer%2Fwechat-clawbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnightsailer%2Fwechat-clawbot/lists"}