Add WeChat Channel

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