WeBot

A push notification assistant for Weixin, powered by ClawBot. Think of it as Bark — but entirely inside Weixin, with no extra app to install.

Note: Currently only Weixin (微信) is supported. WeChat (the international version) is not yet supported by ClawBot.

Why

Bark is great for push notifications on iOS, but it requires installing a separate app. If you already live in Weixin, why not receive notifications right there?

WeBot turns a Weixin account into a push endpoint. Any system that can make an HTTP request — CI/CD pipelines, monitoring alerts, cron jobs, home automation, scripts — can push messages directly to your Weixin.

How It Works

WeBot uses ClawBot (via weixin-agent-sdk) to connect to Weixin as a bot. It keeps a long-polling session with the Weixin API and exposes a simple HTTP push API.

External System                        Weixin
  (curl, webhook,        ┌──────────┐
   CI/CD, script)  ────► │  WeBot   │ ────► Your Weixin
                          │          │       (push notification)
  POST /api/send          │ HTTP API │
  + Bearer token          │ + WX Bot │
                          └──────────┘

1. You message the bot first from Weixin — this is required by the Weixin platform to establish a session.
2. The bot replies with your user ID and the push API details (token + endpoint), ready to copy and use.
3. From then on, any HTTP POST /api/send with your user ID will deliver a message to your Weixin.

Optionally, you can enable OpenAI to give the bot AI chat capabilities — but the core use case is push notifications.

Quick Start

Prerequisites

• Node.js >= 22
• A Weixin account

Setup

# Clone
git clone https://github.com/missuo/webot.git
cd webot

# Install dependencies
pnpm install

# Link your Weixin account (scan QR code in terminal)
pnpm run login

# Configure
cp .env.example .env
# Edit .env — set API_TOKEN (required)

Run

pnpm start

Then send any message to the bot from Weixin. It will reply with something like:

Push API ready:
POST /api/send
Authorization: Bearer your-secret-token
Body: {"userId": "your-user-id", "text": "..."}

Now you can push messages from anywhere:

curl -X POST https://your-server.com/api/send \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"userId": "your-user-id", "text": "Deploy succeeded ✅"}'

Configuration

All configuration is via .env. See .env.example.

Variable	Required	Default	Description
API_TOKEN	Yes	—	Bearer token for the push API
OPENAI_API_KEY	No	—	OpenAI API key (enables AI chat)
OPENAI_BASE_URL	No	—	Custom OpenAI-compatible API endpoint
OPENAI_MODEL	No	gpt-4o	Chat model name
IMAGE_MODEL	No	dall-e-3	Image generation model
SYSTEM_PROMPT	No	—	System prompt for the AI agent
HTTP_PORT	No	3000	HTTP server port

API Reference

POST /api/send

Push a message to a Weixin user. Requires Authorization: Bearer <API_TOKEN>.

{
  "userId": "user-id",
  "text": "Hello from API",
  "accountId": "optional-bot-account-id"
}

Status	Response
200	{"ok": true}
400	{"error": "userId and text are required"}
401	{"error": "Unauthorized"}
500	{"error": "..."}

GET /

Health check. Returns {"status": "ok"}.

Note: You can only push messages to users who have previously messaged the bot. This is a Weixin platform requirement — each session is initiated by the user.

Deployment

# Start in background
docker compose up -d

# View logs to scan the QR code for Weixin login
docker compose logs -f

On first run, you will see a QR code in the logs. Scan it with your Weixin app to link the bot account. The login token is persisted in a Docker volume — you only need to scan once unless it expires.

After the QR code is scanned and the bot is running, press Ctrl+C to exit the log viewer. The container continues running in the background.

To check logs later:

docker compose logs -f

License

MIT