wechat（wechat 开发）

wechat — macOS CLI

Unified CLI for WeChat on macOS. Send messages in pure background (zero UI flash) AND query the local SQLCipher databases for sessions, contacts, chat history, group members, Moments, favorites.

Fast path (read this first)

Send a WeChat message in one call:

wechat send "早上好" Lisa                 # fuzzy name match (remark / nick / alias)
wechat send "hi" filehelper              # wxid — zero DB lookup, fastest
wechat send "提醒一下" 20590343959@chatroom  # group wxid (ends in @chatroom)

Resolution rules (applied in order):

1. RECIPIENT matches a wxid shape (wxid_…, …@chatroom, gh_…, biz_…, or reserved like filehelper) → skip all DB work and send directly.
2. Otherwise, search the local contact DB (remark / nickname / alias / wxid) with session-recency bias:

- single match → send - multiple matches but only one has recent activity (30d) → send to that one - otherwise → exit 2 + JSON {"status":"ambiguous","candidates":[...]}; the agent picks and retries with the explicit wxid

On ambiguous, a sample response:

{
  "status": "ambiguous",
  "hint": "Lisa",
  "candidates": [
    {"wxid": "lishuang683451", "display_name": "lisa", "last_seen": "2026-04-20 05:34:55"},
    {"wxid": "wxid_xxx", "display_name": "Lisa (另一个)", "last_seen": ""}
  ],
  "note": "multiple matches; pass one of the wxids explicitly: wechat send <text> <wxid>"
}

Agent should: read candidates[0].wxid, retry wechat send "<text>" <wxid>. Don't ask the user unless the top candidate has no recent activity or multiple candidates do.

HTTP Bridge for agent integration (v1.10+)

wechat-bridge is a separate binary that wraps the daemon's RPCs as a stable localhost HTTP surface. Use this when wiring WeChat into agent platforms (Hermes, n8n, Dify, LangChain, custom bots) — HTTP is cheaper to integrate than spawning the CLI per call.

# Start bridge (binds 127.0.0.1:18400 by default)
wechat-bridge &

# Health + send-readiness
curl http://127.0.0.1:18400/health

# Send
curl -X POST http://127.0.0.1:18400/send \
  -H 'Content-Type: application/json' \
  -d '{"wxid":"filehelper","text":"hi"}'

# SSE message stream
curl -N 'http://127.0.0.1:18400/messages/stream'

Endpoints:

SSE payload shape (v1.10.28 — Wechaty-aligned + isMentioned)

/messages/stream emits event: messages carrying a JSON array of:

{
  messageId: string,
  chatId: string,                // wxid (DM) or groupid@chatroom
  senderId: string,              // in group: sender's wxid; in DM: the other party's wxid
  senderName: string,
  chatName: string,
  isGroup: boolean,
  body: string,                  // human-readable text. For URL / quote / mini_program, body is the title — raw XML is NOT exposed here.
  hasMedia: boolean,
  mediaType: "image"|"voice"|"video"|"file"|"",
  mediaUrls: string[],           // first entry is CDN URL when applicable
  mentionedIds: string[],        // v1.10.25+ — authoritative @-mention list from WeChat msgsource <atuserlist>
  isMentioned: boolean,          // v1.10.28+ — bridge-authoritative "this row @-mentions ME". Self-sent rows are always false.
  quotedParticipant: string,     // v1.10.27+ — populated from refer.fromUser on quote replies
  botIds: string[],              // legacy heuristic self-marker; NEW consumers should rely on fromSelf instead
  fromSelf: boolean,             // v1.10.25+ — bridge-authoritative "this row was produced by our own POST /send"; DROP THESE to avoid self-echo loops
  messageKind: "text"|"image"|"audio"|"video"|"contact"|"emoticon"|"location"|
               "url"|"attachment"|"mini_program"|"chat_history"|"transfer"|
               "red_envelope"|"recalled"|"system"|"unknown",  // v1.10.27+, aligned to Wechaty's MessageType enum
  urlLink?:     { title, description, url, thumbUrl },                             // present iff messageKind=url
  miniProgram?: { title, description, appId, username, pagePath, thumbUrl },        // present iff messageKind=mini_program
  refer?:       { svrId, fromUser, chatUser, displayName, content },              // present on quote replies
  recall?:      { replacedMsgId, text },                                            // present iff messageKind=recalled
  media?:       { aesKey, md5, cdnUrl, cdnThumbUrl, length, durationSeconds, localPath },  // structured metadata for image/audio/video/attachment
  timestamp: number,
}

The full JSON Schema is committed at wx/schema/sse-payload-v1.10.28.schema.json and enforced by a contract test in the daemon build.

Consumer checklist:

• Filter self-echo with fromSelf === true. Do NOT use senderId === myWxid — in DM both directions share the same senderId.
• In groups, only respond when isGroup && isMentioned — the daemon already does the wxid-vs-atuserlist comparison, so don't reimplement mentionedIds.includes(myWxid) yourself (your wxid may be a remark / lookup that the daemon resolves correctly). The bridge will also drop non-@ group rows automatically when WECHAT_BRIDGE_GROUP_MENTION_ONLY=1.
• Need the URL only? mediaUrls[0]. Need aesKey + md5 to decrypt or verify? media.cdnUrl / media.aesKey / ….
• Expect body for URL / quote / mini_program to be the human title. If you were previously parsing raw <appmsg> XML from body, migrate to the dedicated urlLink / miniProgram / refer objects.
• Backward compatible: every pre-v1.10.25 field is preserved in name + type. New fields are additive.

Security notes for agents:

• Bridge binds 127.0.0.1 — not exposed to LAN without tunnelling.
• Set WECHAT_BRIDGE_BEARER=<secret> env var to require Authorization: Bearer <secret> on non-/health routes. Use this if tunnelling via Tailscale / SSH.
• Activation gating is enforced inside wechatd, not in the bridge. A missing / expired wxp_act_ token → HTTP 401 / 402 on /send. Bridge cannot bypass subscription.

Command groups

All query commands default to YAML output (agent-friendly, low token). Add --json to get JSON.

🛑 Safety rules (CRITICAL — read before calling send)

Every send call must specify --wxid OR --current-chat explicitly. No silent default. Reason: "给 Lisa 发早上好" without wxid resolution can hit the wrong chat (boss, family, etc.) — consequences are severe.

Correct flows for "给 XXX 发 YYY":

1. Just try it: wechat send "YYY" XXX. Fast-path resolver (see top of this doc) handles wxid-shaped targets instantly and fuzzy-matches names against the local contact DB with session-recency bias.
2. On exit 2 + status: "ambiguous": if candidates[0] has last_seen within ~30 days and others are stale/empty, the CLI already auto-picked it and returned success. If it truly was ambiguous (multiple candidates with recent activity), pick one yourself by asking the user — don't guess.
3. On "no contact matches": either ask the user for the wxid, or tell them to open the chat in WeChat and use wechat send "YYY" --current-chat (3s Ctrl-C abort).

Hard rules (the agent MUST follow):

• DO NOT guess or fabricate a wxid. If resolution fails, escalate to the user.
• DO NOT silently send to the current chat without explicit --current-chat.
• DO NOT scan the filesystem / grep logs / use AppleScript to hunt for a wxid. The CLI already searches the local contact DB via the fast path — trust it. If it can't find the recipient, stop and ask the user.
• DO NOT invoke wechat contacts followed by wechat send as two separate calls unless the first fast-path send already told you it was ambiguous. The one-liner saves ~400ms and one agent round-trip.

Capability matrix

Agent: first-use setup

Step 1 — Check wechat is on PATH:

command -v wechat

If missing:

curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-skill/main/install.sh | bash
# Ensure ~/.local/bin is on PATH
case "${SHELL##*/}" in
  fish) fish_add_path "$HOME/.local/bin" ;;
  zsh)  grep -q '.local/bin' ~/.zshrc  2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc ;;
  bash) grep -q '.local/bin' ~/.bashrc 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc ;;
esac
export PATH="$HOME/.local/bin:$PATH"

Step 2 — Run wechat init (required before any query command):

wechat init

This restarts WeChat (closes current session + relaunches) in order to capture the decryption key at login. Tell the user:

"Going to briefly close and relaunch WeChat to extract the local database key. Any draft messages in WeChat will be lost — confirm before proceeding. After WeChat relaunches, you must click 「进入 WeChat」 (or scan QR if no cached account) within ~5 minutes — the key is only written during that sign-in."

Key is only written to memory during the login moment, so init attaches LLDB with a conditional breakpoint and waits up to 300 s. If the user misses the window or WeChat was already logged in before init ran, the breakpoint never fires — rerun wechat init --force.

Result saved to ~/.wx-rs/key.hex (mode 0600) + ~/.wx-rs/config.json. Re-run init whenever WeChat restarts.

init also prints the detected WeChat version/build and the wechat.dylib SHA-256 fingerprint check. If the hash isn't in the verified set (e.g. Tencent pushed a hot-fix dylib), send/query may silently fail at the LLDB layer — reinstall the official dmg from https://mac.weixin.qq.com/en and verify the auto-update toggle at WeChat → 设置 → 通用 → 「有更新时自动升级」 is off.

Step 3 — (For send only) Accessibility permission:

Run wechat doctor. If the terminal hasn't been granted Accessibility yet, this pops the native macOS dialog and opens the Privacy & Security → Accessibility pane directly — no hunting. Toggle the terminal app ON, then quit + relaunch the terminal (macOS requires a restart for the permission to take effect).

If you prefer the manual path: System Settings → Privacy & Security → Accessibility → add the terminal app you're using (Terminal / iTerm / Warp / …).

Step 4 — (For send only) One-time InputView bootstrap per WeChat session:

send needs WeChat's in-memory InputView address. The first send after each WeChat restart prompts:

[bootstrap] 等待抓取 InputView 地址。请在 WeChat 打开任意聊天，输入任意短消息，按回车。（每次 WeChat 重启后只需这一次）

User types any short message (e.g. .) into any WeChat chat (filehelper is the safe test target) and presses Enter. The tool snapshots the InputView pointer via an LLDB breakpoint on the real send call, then the pending wechat send continues automatically. Cache lives in ~/.wechat/state.json until the next WeChat restart.

There is no separate wechat bootstrap subcommand in v1.7+ — the bootstrap step only runs when needed, inline.

Usage — send

# Known wxid → direct
wechat send --text "你好 🎉" --wxid filehelper
wechat send --text "会议 5 分钟后开始" --wxid lishuang683451

# Unknown wxid → look up via contacts first
wechat contacts --query Lisa       # returns lishuang683451 + variants
wechat send --text "早上好" --wxid lishuang683451

# Explicit current-chat with 3s abort window
wechat send --text "..." --current-chat

# Heap-mode (no AX; needs user-typed seed text)
wechat send --text "..." --wxid <id> --mode heap --seed "xxxxxxxxxx"

send arguments

Usage — query

# Sessions (recent conversations)
wechat sessions -n 20                           # all types
wechat sessions --filter private,group          # only real chats
wechat unread --filter private,group            # unread human chats

# Contacts
wechat contacts --query 李                     # fuzzy match nickname/remark/wxid
wechat contacts -n 500                          # list all

# History
wechat history "张三" -n 2000
wechat history "AI 星球" --since 2026-04-01 --until 2026-04-15 -n 200

# Search
wechat search "会议纪要"
wechat search "报销" --in "财务群" --since 2026-01-01

# Group members
wechat members "AI 星球"

# Stats
wechat stats "AI 星球" --since 2026-01-01

# Export
wechat export "张三" --format markdown -o zhang.md
wechat export "AI 星球" --format json -o ai.json -n 5000

# Incremental (since last checkpoint saved in ~/.wechat/state.json)
wechat new-messages            # advances checkpoint
wechat new-messages --peek     # read-only; does NOT advance checkpoint

# Favorites
wechat favorites                          # all
wechat favorites --type image             # text / image / voice / video / article / card / file / location
wechat favorites --query "会议"

# Moments
wechat sns-feed                           # recent locally-cached posts
wechat sns-feed --user "张三" -n 50
wechat sns-search "婚礼" --user "李四"
wechat sns-notifications                   # unread by default
wechat sns-notifications --include-read

Usage — realtime listen (v1.3)

wechat listen streams new incoming WeChat messages to stdout as they arrive (latency <500ms). Requires the background daemon.

# One-time: start the daemon (keep running in a separate terminal or `&`)
wechat daemon start

# Stream all new messages
wechat listen

# Stream only messages from one chat (server-side filter)
wechat listen --wxid filehelper

# JSONL output for agent consumption
wechat listen --format json

# Trigger a shell command per message — the handler sees WECHAT_MSG_* env vars
wechat listen --on-message "./ai-reply.sh"
wechat listen --wxid lisa --on-message 'echo "[$(date +%H:%M)] $WECHAT_MSG_SENDER_WXID: $WECHAT_MSG_TEXT" >> log.txt'

--on-message env vars

Safety notes:

• Content is passed via env vars, not shell-interpolated into the command. Safe against $(rm -rf) style injection.
• Handler runs async (one subprocess per message); if it takes longer than messages arrive, handlers will pile up. Keep handlers fast or add your own queueing.

Daemon lifecycle

wechat daemon start              # foreground; or `wechat daemon start &` for background
wechat daemon status             # socket + pid + uptime
wechat daemon ping               # round-trip latency sanity check
wechat daemon stop               # graceful shutdown

The daemon caches each SQLCipher DB connection so wechat sessions / contacts / history / unread run in <30ms (vs 400-500ms without it). It also powers wechat listen by watching message_*.db-wal file changes.

Fuzzy chat resolution

history / search --in / stats / export / members accept a <chat> argument that is matched against (in order): exact wxid → remark → nick_name → alias. If ambiguous, the most-recently-active match is picked. Use wechat contacts --query... first if you need to disambiguate.

Output format

All query commands emit YAML by default. Add --json for JSON:

wechat sessions --json | jq '.[] | select(.chat_type=="private" and .unread>0)'
wechat new-messages --json                # ideal for agents consuming incremental updates

When to invoke this skill (agent triggers)

Send:

• "给 Lisa 发消息：..."
• "发微信通知我妈 '到家了'"
• "提醒 XXX 会议 5 分钟后开始"
• "send to filehelper..."

Query:

• "微信里 Lisa 最近说了什么" → wechat history Lisa
• "搜一下群里谁提过报销" → wechat search 报销
• "AI 星球群有多少人 / 谁发言最多" → wechat members + wechat stats
• "有哪些未读消息" → wechat unread
• "导出我和张三的聊天记录" → wechat export 张三 -o...
• "朋友圈里有没有人提到婚礼" → wechat sns-search 婚礼
• "XXX 的朋友圈" → wechat sns-feed --user XXX
• "最近收藏了什么" → wechat favorites

Realtime:

• "帮我盯着 Lisa 发来的消息，收到就自动回复 XXX" → wechat daemon start then wechat listen --wxid <lisa-wxid> --on-message "..."
• "把微信消息接进我的 AI assistant" → wechat listen --format json --on-message "curl -X POST..."
• "监控这个群谁提到 '会议'，马上通知我" → wechat listen --wxid <group> + handler that greps

Example user utterances and the right first call:

• "给 Lisa 发消息：会议 5 分钟后开始" → wechat contacts --query Lisa → wechat send --wxid... --text...
• "send to filehelper today's summary" → wechat send --text... --wxid filehelper
• "查一下 XXX 群最近谁发言最多" → wechat stats "XXX"

🔐 Security / data scope

• Everything runs 100% locally — no data leaves the machine.
• wechat init caches the raw DB key in ~/.wechat/keys.json (mode 0600). Treat that key like a password — anyone with keys.json + a copy of ~/Library/Containers/com.tencent.xinWeChat/... can decrypt all your WeChat data.
• Never commit ~/.wechat/ to git. Never paste the key into chat windows. If leaked: logout + re-login WeChat to rotate the key.

Mechanism (brief)

init — restarts WeChat, sets an LLDB breakpoint at a known write offset, reads the 32-byte raw key as it is written to a register during startup. No codesign --force --deep on WeChat.app, no sudo. Immediately detaches after capture.

Query commands — load the raw key + discovered DB paths from ~/.wechat/keys.json, open each .db via the sqlcipher CLI with WeChat's PRAGMAs (cipher_compat=4, kdf_iter=256000, cipher_page_size=4096, HMAC_SHA512, PBKDF2_HMAC_SHA512), run SELECTs in JSON mode, parse. When the background daemon is running, queries are routed over a local Unix socket to a persistent SQLCipher connection pool — amortizes PBKDF2 cost and cuts latency 5-10×.

listen — watches message_*.db-wal files for mtime changes, queries Msg_* tables for rows newer than the last seen create_time, decodes content (zstd-decompressed if needed), strips the group <sender>:\n prefix, and pushes each new row to subscribed CLI processes over the daemon socket. Zero network traffic; runs entirely locally against the on-disk WeChat databases.

send — uses macOS Accessibility API to set AXHidden=True (silent hide) + setValue into chat_input_field, then LLDB-WriteMemory overwrites InputView+0x2B8 with target wxid SSO std::string, then LLDB expression cold-calls mmui::InputView::Send(0) via its RVA. Zero window activation / focus steal.

Caveats

• macOS arm64 only, WeChat 4.1.8 verified. Other versions may need offset rediscovery.
• Binary is a standalone native executable (GitHub Releases). install.sh auto-clears macOS Gatekeeper quarantine attribute.
• Not a WeChat API. Userland research artifact. Can break on any WeChat update.
• LICENSE forbids commercial use — see LICENSE + DISCLAIMER.md.

Updating the CLI

Before starting a session, the agent should check that wechat is reasonably current. The binary is self-contained; upgrading just means pulling a newer release.

Check current version:

wechat --version

Upgrade to latest (safe, idempotent) — re-run install.sh with --force, or without it (it overwrites by default):

curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-skill/main/install.sh | bash

That pulls the latest tagged release binary from GitHub, re-installs to ~/.local/bin/wechat, and re-clears any Gatekeeper quarantine attribute. No data is lost — ~/.wechat/keys.json + state.json are untouched.

When to upgrade:

• wechat --version is more than one minor behind the latest release tag at https://github.com/leeguooooo/wechat-skill/releases
• A command that the user asks for doesn't exist yet (the capability matrix on this page reflects the latest release; older binaries may be missing commands)
• WeChat itself was updated — new versions may need a fresh wechat release to track shifted offsets (watch https://github.com/leeguooooo/wechat-skill/releases for a note)

Updating the skill metadata (this SKILL.md itself, when the agent is installed via skills.sh):

# refresh skill files (including this SKILL.md) from the public repo
npx skills update leeguooooo/wechat-skill -g

If the agent sees wechat: command not found after an npx skills update, it still needs to run install.sh — skill updates do not include the binary.

Support

• Issues → https://github.com/leeguooooo/wechat-skill/issues