wechat ilink agent bridge

Skill text to copy

---
name: wechat-ilink-agent-bridge
description: Connect an agent runtime, including Muse, to WeChat through Tencent's ClawBot/iLink backend using outbound HTTPS, QR login, long polling, a file-based inbox/outbox, and local secret storage. Use when a user wants an agent to receive and reply to WeChat messages without exposing an inbound port or building a direct phone-to-agent tunnel.
---

# WeChat iLink Agent Bridge

Use this Skill to connect an agent runtime to WeChat through Tencent's `openclaw-weixin`/iLink backend.

## Scope

This Skill provides an agent-agnostic bridge plus a Muse adapter example. It does **not** require an inbound public port, port forwarding, or a direct connection between the phone and the agent machine. Both sides talk outbound to Tencent's backend.

Do not promise that every network needs no VPN/proxy. The tested setup worked without a China-side inbound tunnel; the agent host still needs working outbound HTTPS to the iLink backend and may inherit platform-specific proxy requirements.

## Source discipline

Treat these as separate evidence classes:

1. **Current upstream behavior** — verified against Tencent's public `Tencent/openclaw-weixin` repository and protocol reference.
2. **Observed/tested behavior** — behavior reproduced in the source deployment on 2026-10-11. It is useful operational evidence, but not a permanent server contract.
3. **Integration guidance** — recommendations in this Skill.

If current upstream documentation conflicts with an old observation, follow current upstream wire format first and preserve the observation in troubleshooting notes.

## Hard safety rules

- Never print, paste into chat, commit, or upload `bot_token`.
- Treat `binding.json`, message payloads, context tokens, cursors, and runtime state as private runtime data.
- Keep `secure/` mode `0700`; secret files mode `0600` where the OS supports it.
- Keep `secure/`, `state/`, `inbox/`, `outbox/`, generated QR/login artifacts, logs, and local environment files out of Git.
- Do not expose an inbound listener unless the user explicitly asks for a different architecture.
- Do not silently bind a multi-user/shared bot to the first stranger who messages it. First-message auto-binding is acceptable only for a private single-user deployment the user controls.
- On session-expired error `-14`, stop and require re-login instead of creating a restart loop.

## Workflow

### 1. Inspect the environment

Confirm:

- Python 3 is available.
- The runtime can make outbound HTTPS requests to the iLink backend.
- The working directory is private to the user.
- If a service manager is used, determine its actual user and `HOME` rather than assuming `/root` or `/home/hatch`.

Copy `templates/relay.py` into the deployment directory. Recommended layout:

```text
wechat-bridge/
├─ relay.py
├─ inbox/
│  ├─ done/
│  └─ ignored/
├─ outbox/
│  ├─ sent/
│  └─ bad/
├─ secure/
└─ state/
```

### 2. Login

Run:

```bash
python relay.py login
```

Current upstream flow creates the QR code with:

```http
POST /ilink/bot/get_bot_qrcode?bot_type=3
```

and polls status with:

```http
GET /ilink/bot/get_qrcode_status?qrcode=...
```

The login command must never echo the token. Present `qrcode_img_content` to the user using the runtime's normal QR/image capability or open the returned URL when appropriate. After `confirmed`, store credentials only under `secure/`.

### 3. Start the relay

Run:

```bash
python relay.py daemon
```

The daemon must:

- drain `outbox/` before **and** after each long poll;
- persist `get_updates_buf` so restarts continue from the last cursor;
- preserve one stable `client_id` per outbound file across retries;
- carry the inbound `context_token` back on a reply when available;
- treat absent `ret` as not automatically being an error, while rejecting explicit non-zero `ret`/`errcode` according to the operation;
- stop with exit code `14` on session expiration (`-14`).

### 4. Bind the intended user

Prefer binding the QR-login identity returned as `ilink_user_id` (with `ilink_bot_id` as the bot id) when the backend supplies both values. The reference relay does this automatically.

For compatibility with the original private Muse deployment, first-message binding is available only when `WECHAT_BRIDGE_AUTO_BIND_FIRST=1` is explicitly set. In that mode:

- `bound_user_id` = inbound `from_user_id`;
- `bot_user_id` = inbound `to_user_id`.

Do not enable first-message binding for shared or ambiguous deployments; use explicit pairing/approval instead.

### 5. Agent worker loop

The agent-side worker should poll `inbox/*.json` on a modest interval (the tested Muse setup used 5 seconds), claim each file once, and:

1. Parse the user text and `context_token`.
2. Verify `from_user_id` against `secure/binding.json`.
3. Ignore mismatches without replying.
4. Produce a plain-text reply suitable for WeChat.
5. Write `outbox/<name>.reply.json` containing at least:

```json
{"to_user_id":"<from_user_id>","context_token":"<same token>","text":"<reply>"}
```

6. Move the inbound file to `inbox/done/` only after the reply file is durable.
7. If the host runtime supports a primary-chat audit trail, append a concise summary there without secrets.

See `examples/muse.md` for the Muse-specific adapter.

### 6. Service installation

Use `templates/wechat-bridge.service` and `templates/ensure-service.sh` as starting points. Substitute the actual runtime user/home/path. If the host requires outbound proxy variables, inject them explicitly into the service environment; do not assume an interactive shell environment is inherited by systemd.

### 7. Acceptance checks

Verify all of the following:

- inbound WeChat text produces one inbox file;
- the bound user receives one reply;
- a retry reuses the same outbound `client_id`;
- an unbound user is ignored;
- restart resumes from the stored cursor;
- secrets and runtime state are absent from `git status`;
- expired authentication stops rather than loops.

## Refere

SKILL.md from the repo, MIT licence. Read it before pasting. Muse asks before it acts.