/add-wechat

name: add-wechat
description: Add WeChat (personal) channel integration via Tencent's official iLink Bot API. Uses long-polling and QR scan — no webhook, no ToS risk, no paid token.

Add WeChat Channel

Adds WeChat support via **iLink Bot API** — the first-party Tencent API for personal WeChat bots (different from WeCom / Official Account).

**Why this is different from wechaty/PadLocal:**

• Official Tencent API — no ToS violation, no ban risk
• Free — no PadLocal token required
• No public webhook URL needed — uses long-poll
• Works with any personal WeChat account

Prerequisites

• A **personal WeChat account** with the mobile app installed
• A phone to scan the QR code for login
• Node.js >= 20 (already required by NanoClaw)

Install

NanoClaw doesn't ship channels in trunk. This skill copies the WeChat adapter in from the `channels` branch.

1. Copy the adapter and its registration test

Fetch the `channels` branch from the configured remote that carries it, then overwrite the skill-owned files with the canonical registry copies:

src/channels/wechat.ts
src/channels/wechat-registration.test.ts

2. Append the self-registration import

Append to `src/channels/index.ts` (skip if the line is already present):

import './wechat.js';

3. Install the library (pinned)

wechat-ilink-client@0.1.0

4. Build and validate

pnpm run build

pnpm exec vitest run src/channels/wechat-registration.test.ts

Both must be clean before proceeding. `wechat-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `wechat`. It goes red if the `import './wechat.js';` line is deleted or drifts, if the barrel fails to evaluate (so the channel genuinely would not register), or if `wechat-ilink-client` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. Importing is safe: the adapter opens its long-poll connection only in `setup()` (at host startup), never at import.

End-to-end message delivery against a real WeChat account is verified manually once the service is running — see Credentials and Wire your first DM above.

Credentials

Unlike most channels, WeChat requires **no pre-configured API keys**. Auth happens via QR code scan from your phone.

1. Enable the channel

Add to `.env`:

WECHAT_ENABLED=true

2. Start the service and scan the QR

Restart NanoClaw.

Run from your NanoClaw project root:

source setup/lib/install-slug.sh
systemctl --user restart $(systemd_unit)              # Linux
# or
launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS

The adapter will print a **QR URL** to the logs and save it to `data/wechat/qr.txt`:

tail -f logs/nanoclaw.log | grep WeChat
# or
cat data/wechat/qr.txt

Open the URL in a browser (it renders a QR code), then:

1. Open WeChat on your phone 2. Use its built-in QR scanner (top-right "+" → Scan) 3. Approve the authorization on your phone 4. Auth credentials are saved to `data/wechat/auth.json` — do not commit this file

The bot is now connected as your WeChat account.

Wire your first DM

A successful QR login alone isn't enough — the adapter still needs to be wired to an agent group before it can respond.

**Prerequisite: the host service must be running.** The wire script creates the wiring through `ncl`, which talks to the running host over a Unix socket — there is no offline mode.

1. Trigger the first inbound message

Have a different WeChat account send a message to the bot account. This auto-creates a `messaging_groups` row with the sender's `platform_id` and the `unknown_sender_policy` the WeChat adapter declares.

2. Run the wire script

pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts

Interactive flow: the script lists all unwired WeChat messaging groups, asks which agent group to wire it to, and runs `ncl wirings create` — engage mode/pattern and priority come from the WeChat adapter's declared channel defaults, so a wiring created here matches one created by `/manage-channels` or the approval-card flow.

With `request_approval` as the sender policy, the next DM from a stranger fires an approval card to the admin — admin taps Approve/Deny, approved users are added as members and their queued message replays through the agent.

Non-interactive:

pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts \
  --platform-id wechat:wxid_xxxxx \
  --agent-group ag-xxxxx \
  --non-interactive

Flags:

• `--platform-id <id>` — wire a specific messaging group (default: most recent unwired)
• `--agent-group <id>` — target agent group (default: prompt; auto-picked when only one exists)
• `--sender-policy public|strict|request_approval` — override the messaging group's `unknown_sender_policy` (default: leave whatever the WeChat adapter declared when the row was auto-created)
• `--session-mode shared|per-thread` — default `shared`

Equivalent raw `ncl` invocation (host must be running):

ncl wirings create --messaging-group-id <mg-id> --agent-group-id <ag-id> --session-mode shared

3. Test

Have the sender message the bot again — the agent should respond.

Operational notes

• **Only one instance can use a given token at a time.** Don't run multiple NanoClaw instances pointing to the same `data/wechat/auth.json`.
• **Re-login on session expiry:** if you see `WeChat: session expired` in logs, delete `data/wechat/auth.json` and restart — you'll be asked to re-scan.
• **Sync cursor persistence:** `data/wechat/sync-buf.txt` holds the long-poll cursor. Deleting it replays recent history on next start; don't delete it in normal operation.
• **Account safety:** this uses the official Tencent API, so account bans for bot automation aren't a risk. That said, don't spam — normal r