---
slug: "zlab-weixin-bridge"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/JasonLee-arch/zlab-weixin-bridge@master/README.md"
repo: "https://github.com/JasonLee-arch/zlab-weixin-bridge"
source_file: "README.md"
branch: "master"
---
# zlab-weixin-bridge 🤖💬

> WeChat bot bridge for [pi](https://pi.dev) — QR login, message polling, and auto-reply via the WeChat ilink API.

## Features

- ✅ **QR code login** — scan with your phone, no password
- ✅ **Message polling** — receive WeChat messages in real-time
- ✅ **Auto-reply** — pi auto-replies to WeChat messages through the normal conversation flow
- ✅ **Active push** — send WeChat messages proactively via tools
- ✅ **Contact persistence** — auto-save contacts who message you
- ✅ **Session continuity** — context tokens preserved across restarts
- ✅ **Token caching** — no need to re-scan every time

## Install

```bash
pi install npm:zlab-weixin-bridge
```

Or test without installing:

```bash
pi -e npm:zlab-weixin-bridge
```

## Usage

### 1. Login

Run the login command in pi:

```
/weixin-login
```

If it's the first time, you'll get a URL. Open it in your browser, scan the QR code with your phone's WeChat, and confirm.

On subsequent runs, cached tokens are reused automatically — no re-scan needed.

### 2. Send messages proactively

The LLM can use the `weixin_send` tool to push messages to anyone who has messaged the bot:

```
to: "xxx@im.wechat" (user ID, obtained automatically when they message you)
```

### 3. Manage contacts

| Command / Tool | Description |
|---|---|
| `weixin_contacts` | List all known contacts and their IDs |
| `weixin_alias` | Set a nickname for a contact |
| `weixin_status` | Check connection status |

## Tools registered

| Tool | Description |
|---|---|
| `weixin_login` | QR code login (or cached token recovery) |
| `weixin_send` | Send text message to a WeChat user |
| `weixin_status` | Check connection status |
| `weixin_contacts` | List known contacts |
| `weixin_alias` | Set alias for a contact |

## Commands registered

| Command | Description |
|---|---|
| `/weixin-login` | Login or recover session |
| `/weixin-status` | Quick status check |

## How it works

1. The extension logs into your personal WeChat account via ilink API (QR scan)
2. It polls for new messages in the background
3. Incoming messages are injected into pi as user messages
4. pi's response is automatically sent back via WeChat
5. Active messages can be sent via `weixin_send`

## Security

- The extension runs with your full system permissions
- Bot tokens are cached locally in `.pi/weixin/`
- Only message text is processed; media messages are ignored (for now)
- You can only message people who have messaged you first (WeChat API limitation)

## Limitations

- ❌ Cannot add friends or search contacts
- ❌ Cannot join or monitor group chats
- ❌ Only works for 1-on-1 messaging
- ❌ Media/file messages are not supported yet

## License

MIT