wx-bot CLI
A CLI that passes your WeChat messages to an agent through the official ClawBot (iLink) and sends replies back
- 206 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent reads personal WeChat chats and writes to them as the account owner, including voice messages, files and video
- The `chatlog_days` setting saves conversations as plain text in `<state_dir>/chatlog/` files, and the install script runs through `curl ... | bash`
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/lawrencewzen/wx-bot/main/install.sh | bashThe script from the README. For a source install there is `./install.sh --service`, which also sets up autostart. Read the script before running it.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads personal WeChat chats and writes to them as the account owner, including voice messages, files and video
- The `chatlog_days` setting saves conversations as plain text in `<state_dir>/chatlog/` files, and the install script runs through `curl ... | bash`
This is third-party code. Review the repository files before installing.
What it does
wx-bot connects your personal WeChat to an agent such as Grok Bot, Muse or another one that can accept a webhook or pull messages with a command. Messages arrive through Tencent's official ClawBot (iLink) interface, land in a local SQLite inbox first and are acknowledged only afterwards, so a failed delivery is retried. The agent receives a JSON event with `event_id`, `from_wxid`, `text`, `voice_text` and a list of attachments with local paths. There are two modes: webhook, where wx-bot POSTs to the agent's address, and pull, where the agent takes messages with `wx-bot inbox pull`. A reply goes out with `wx-bot send` carrying text, an image, a file or a video. Text, images, voice with transcription, files and video are supported. No port is opened to the outside: the local API listens on loopback only. The service reacts only to the WeChat account that signed in by QR code, and messages from friends are not handled.
Who it is for. People who run a personal agent on Grok Bot or Muse and want to write to it and get replies in WeChat without opening another app.
Good fit when
- A personal agent should answer WeChat messages and delivery must survive restarts
- You need a channel that forwards voice messages to the agent together with a transcript
- The agent runs behind NAT or in a cloud with no inbound ports: wx-bot is outbound only and opens no external port
- The chat history has to be reviewed later: `chatlog_days` enables daily files and `wx-bot chatlog` searches them
Not a fit when
- You need to answer friends or customers as a bot: the service handles only the account owner's messages
- You need Windows support: the README declares Linux and macOS
- The agent's cloud machine often sleeps or resets: wx-bot may stop and the QR sign-in has to be repeated
Example request
Connect my WeChat to yourself through wx-bot: install it per the repository instructions, show me the QR code for sign-in and check it with wx-bot health --grace 0.Limitations
The project is third party: it calls Tencent's official ClawBot (iLink) interface but is not a Tencent product. Messages can be received and sent only as the account that signed in by QR code, and replies work after the first message to ClawBot, otherwise `wx-bot send` returns a `no context_token` error.
When the agent's cloud machine sleeps or resets, the sign-in is lost and the QR has to be scanned again. One event can arrive several times, so the agent needs deduplication by `event_id`. WeChat does not render Markdown, so replies go as plain text.
How to disable. Run `wx-bot uninstall --yes`, and the `--keep-data` flag keeps the sign-in data. If you installed with autostart, stop the systemd or launchd service. The author describes the full removal procedure in `docs/agents/uninstall.md`.
FAQ
How do I install wx-bot?
Run `curl -fsSL https://raw.githubusercontent.com/lawrencewzen/wx-bot/main/install.sh | bash`, edit `~/.config/wx-bot/config.json` following the webhook or pull example, then `wx-bot login xiaox`, `wx-bot run` and `wx-bot health --grace 0`. A zero exit code from the last command means the install is complete.
What is the difference between webhook and pull?
With a webhook wx-bot POSTs to the agent's address and waits for a 2xx code. With pull the agent takes messages with `wx-bot inbox pull --lease 5m` and acknowledges them with `wx-bot inbox ack <event_id>`.
What if messages do not arrive?
Run `wx-bot health --grace 0` and follow its hints. If the logs show `expired` or `-14`, the sign-in expired and `wx-bot login <binding>` is needed. Messages from friends do not arrive by design.
Does wx-bot store the conversation?
Incoming events sit in a local SQLite inbox until acknowledged. A full daily chat log is enabled by the `chatlog_days` setting and is off by default because it is private data.
Is this an official Tencent product?
No. The project calls the official ClawBot (iLink) interface but, as the end of the README says, is not affiliated with Tencent.
Discussion
No questions or reviews yet.
Related
CLI toolsWeChat Automation API
wechat-automation-api
A skill for agents on Windows that sends text, images and files through an already running desktop WeChat, with an HTTP API and a queue as well
WeCom channel for OpenClaw: the agent replies in corporate WeChat, and personal WeChat connects through the same app
An MCP channel that passes WeChat messages into a Claude Code session and sends the agent's replies back to the same chat
Connects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
Claude Code interviews you about your business, then writes, tests and deploys a WhatsApp bot with per-customer memory
A CLI for messaging between agents: node identities, contact invitations, inboxes and relay connectivity
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| wx-bot (this card) | no | 206 | ||
| Claude Code WeChat Channel | no | OAuth | 311 | an MCP channel for a Claude Code session rather than a general bridge with webhooks and pull for any agent |
| openclaw-wechat | no | 152 | a WeCom channel for OpenClaw, whereas wx-bot works with a personal WeChat account and various agents |
README in short
The README is in Chinese. It covers the features (no lost messages, outbound-only traffic, owner account only, two delivery modes), a quick start by messaging the agent and a manual install, the event format, a table of operations commands and common failures. A separate `AGENTS.md` is addressed to agents.