wechat

WechatUse — select the host platform first

This skill supports macOS Apple Silicon and experimental Windows x64. Never tell a Windows user that WechatUse has no Windows version. Plugin/skill version 1.18.15 is metadata; the runtime releases are independently versioned (macOS v1.18.13, Windows windows-v0.1.0).

• Windows: follow only the Windows section below. Do not apply macOS requirements, activation/setup commands, LLDB, Accessibility, shell installer or managed 4.1.9 instructions.
• macOS: skip the Windows section and follow the macOS section.
• Linux and Intel macOS do not have a supported native runtime.

Windows x64 (experimental)

A standalone package is published at https://github.com/leeguooooo/wechat-use/releases/tag/windows-v0.1.0 . It includes its runtime; do not install or invoke system Python to use that package. The tested WeChat build is 4.0.6.17, with limited login compatibility; not every Windows WeChat build is supported. No media, background send, automatic chat selection, HTTP Bridge or Wechaty support is provided.

Find the installed runtime before reinstalling

In PowerShell, first check Get-Command wechat-use -ErrorAction SilentlyContinue, then the default launcher:

& "$env:LOCALAPPDATA\Programs\wechat-use\wechat-use.cmd" doctor

For custom installations, read the installed skill's runtime.json: $CODEX_HOME\skills\wechat-use\runtime.json, or $env:USERPROFILE\.codex\skills\wechat-use\runtime.json if CODEX_HOME is unset. The standalone installer writes executable, args and mcp_args; invoke that exact executable with PowerShell's & operator. Older source installations may instead record python and script; use those recorded absolute paths with -X utf8, never a guessed python command. The Claude plugin supplies instructions; installing/updating it alone does not install the runtime.

If no runtime exists, download and run the official Windows installer:

Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/

The installer checks download hashes, installs a user-local CLI and Codex skill, and sends no messages. It does not require system Python. The package is not Authenticode-signed. See https://github.com/leeguooooo/wechat-use/blob/main/docs/windows.md for the supported scope.

Read, listen and send

doctor checks local readiness, not delivery or current login acceptance. Discover the current process/account; never reuse a remembered PID or switch an initialized state directory to another account.

History/search require exact usernames. Output is JSON (JSONL for listen); the first listener establishes a baseline unless --from-start is requested. Deduplicate by event_id and do not run concurrent listeners against one state directory. Keys are current-user DPAPI encrypted; never print or upload them.

Foreground send requires the already-open unambiguous chat and an empty draft; it raises the selected WeChat window. Honor existing send authorization, but do not send unsolicited test messages. On uncertain submission, inspect history before any further action; a server-backed row is not a read receipt.

For MCP use runtime.json's executable and mcp_args (["mcp"]). A source installation instead uses its recorded python with -X utf8 <script> mcp. This supports wechat_sessions, wechat_contacts, wechat_history and experimental wechat_send; commit defaults to false.

The old WeChat build can reject login. compat-version --pid ... only inspects by default; apply the explicit experimental --apply only when the user requests fixing that restriction. It is fingerprint-gated, changes one temporary field and saves a rollback journal; no promise of future login acceptance. The user performs QR/login confirmation.

Claude hook errors

This plugin defines no UserPromptSubmit hook. A Python-not-found hook error belongs to a separately configured hook, not to the standalone WeChat runtime. Inspect the named hook in Claude settings before changing it; preserve unrelated hooks and do not disable all hooks or reinstall WeChat. A non-blocking hook error does not establish that the CLI is unavailable. If this platform section is absent from the loaded skill, update the marketplace/plugin and reload Claude.

End of Windows instructions. On Windows, do not execute the macOS section below.

macOS only: stable CLI

Setup failures and user reports (v1.18.7+)

Release status: v1.18.13 is published; check GitHub Releases for subsequent versions. The capabilities below apply to the released build; users on older versions can upgrade with the README install command.

Do not require users to identify their macOS version or whether this is a fresh install before helping. The setup window collects redacted environment and service facts automatically. Read the WXS-… problem code from an error screenshot; if more detail is needed, the user can click “复制诊断信息” on any setup page, including a waiting page. The window also provides a minimal report when core cannot start. Never request keys.json, activation tokens, raw memory output, or private chat data.

Missing system developer-tool authorization is detected before initialization and uses “授权并继续” with the native macOS administrator confirmation. Preserve existing login and grants. Do not suggest reinstalling or globally resetting permissions for an unexplained initialization failure. A v1.18.6 error window can use its existing “修复安装” button to upgrade once to the current release; then follow the specific diagnosis rather than repeatedly reinstalling.

Unified CLI for WeChat on macOS. Send messages and query the encrypted local databases for sessions, contacts, chat history, group members, Moments, favorites. Conversation selection runs inside the managed clone without activating or raising its windows.

Managed WeChat 4.1.9 (v1.18.0+)

The installer automatically copies a supported local 4.1.9 or downloads a pinned Tencent DMG (no prompt). It installs ~/Applications/WeChat-4.1.9-wechat-use.app with its own bundle ID and sandbox container, disables that clone's updates, and saves ~/.wx-rs/managed-wechat.json.

All CLI, daemon, HTTP bridge, and MCP operations default to that clone. Check its current state first and reuse an existing login. If it is closed, launch it with open -g "$HOME/Applications/WeChat-4.1.9-wechat-use.app". Request first-time login only when it is actually required, then run wechat-use init. Do not substitute open -a WeChat, sign the primary /Applications/WeChat.app, remove the managed selection, or fall back to the primary when the clone is closed. Only 4.1.9 receives ongoing compatibility work. When repairing installation, rerun the installer; do not download the latest WeChat.

Unified setup and recovery (v1.18.6+)

Use wechat-use setup --json to inspect the current setup stage without opening UI. For a normal user, the curl installer and interactive wechat-use init use the same native setup window. It preserves existing activation, login and keys, selects compatible installed developer tools for the tool only, starts the official background service, and verifies actual service ownership and permissions.

If a user action is needed, run wechat-use setup or open ~/Applications/WechatUseSetup.app. Let the window handle activation, login, system authorization, drag-and-drop and rechecking. Do not give users sequences of doctor, init, launchctl, or xcode-select repair commands. Never launch a Terminal-owned daemon as a permission workaround. The service must be owned by the official bridge.

The bridge's /setup/status remains available before keys or Accessibility grants are ready. It is diagnostic only; sending remains gated. Setup control uses local signals to the validated launchd process, not an unauthenticated HTTP write endpoint.

An unconfirmed setup test is persisted and is not automatically replayed after closing or reopening the window. --skip-verify explicitly skips sending; permission readiness alone is not delivery evidence. Human identity confirmation and actual macOS grants remain user-controlled.

User setup guide

Background execution

When System Settings shows the tool enabled but the actual launchd bridge still rejects Accessibility, do not treat the displayed switch as proof. Check the installed path and signature, refresh only that tool's switch, and recheck a freshly loaded official service. If those checks still fail, the specific old permission entry may be stale. An authorized local computer-control agent can remove and re-add only the failing tool entry using the current installed binary. Identify the exact row before each action; do not use blind coordinates or reset other apps' permissions. Preserve the dedicated WeChat process and keys. Afterwards verify HTTP health, the daemon's real Accessibility result, and that its parent is the official bridge. A user identity challenge remains a user action.

Normal operations must preserve the user's foreground window. Do not call open -a, activate/raise/unminimize the clone, switch applications, or use foreground/global hotkeys as routine preparation. Use process-targeted input and background conversation navigation, and verify the exact recipient. This also applies to installation, initialization, permission errors, and service recovery. Return actionable diagnostics without automatically opening Settings, Finder, permission dialogs, or retrying a send. doctor --fix-tcc is an explicit interactive recovery command and opens System Settings. Foreground recovery is a last resort only after available background methods are shown to be unavailable. Never activate and blindly resend an unconfirmed message; inspect delivery first. A blank AX snapshot alone does not justify foreground recovery or restarting WeChat.

Fast path (read this first)

Send a WeChat message in one call:

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:

Agent should: read candidates[0].wxid, retry wechat-use 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.

Endpoints:

Account readiness and image sends

Image sending and self-message reads resolve the current account in each message shard; File Transfer Assistant warmup samples are no longer required on the managed 4.1.9 path. /health reports wechat.state and wechat.account_state separately from daemon liveness. not_ready means the account is not ready for sending; needs_wechat_login in doctor requires completing WeChat login, not reinitializing or deleting caches. WeChat may still require phone confirmation or a QR login. The tool never bypasses that confirmation.

Ordinary files, videos and cards are not supported by native send yet.

Images over HTTP

The image path must name a file on the bridge host. Native requests accept image_path (or imagePath); Hermes requests use imagePath. Omit the text field for an image-only request. Send text and images separately; combining both in one request is rejected instead of silently dropping content.

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

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

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 resolves the authoritative mention 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 / ….
• For messageKind: "image", do not inline base64 image bytes in chat responses. Call wechat-use image get <messageId> --chat <chatId> --json, parse absolutePath, then use the host agent's file/image Read capability on that path. Default --from auto (since v1.13.11) tries the daemon's in-memory lookup first (fast, works when the user has opened the image at least once in WeChat) and falls back to CDN replay only on miss. If the result is image not yet viewed in WeChat (cache empty), and CDN fallback failed, ask the user to open the image once in WeChat and retry. cdn-expired or needs local-decrypt adaptation means neither path can recover this image — surface that to the user instead of guessing.
• 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 wechatuse_ token → HTTP 401 / 402 on /send. Bridge cannot bypass activation.

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 resolve to a known wxid. No silent default to "current chat" — that flag (--current-chat) was removed pre-1.13; if the resolver can't find a recipient, stop and ask the user.

Correct flows for "给 XXX 发 YYY":

1. Just try it: wechat-use 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 "XXX": ask the user for the wxid (or have them confirm a candidate from wechat-use contacts --query XXX --brief).

Hard rules (the agent MUST follow):

• DO NOT guess or fabricate a wxid. If resolution fails, escalate to the user.
• 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-use contacts followed by wechat-use 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:

If missing:

Step 2 — Initialize the already-logged-in managed WeChat:

On the managed WeChat 4.1.9 this scans the existing process for per-database keys; it does not need to quit and relaunch WeChat. Keep the existing account, container and login state. Reuse cached keys while queries work, including after a daemon restart; only rescan when keys are missing or fail to decrypt.

If WeChat itself is on a login screen, the user must complete that genuine login challenge. Do not manufacture a new challenge by restarting a logged-in clone, replacing its bundle identity, or deleting its local account data.

Step 3 — Check service permissions:

Check the running daemon's daemon_accessibility result and the bridge's health. Accessibility belongs to the installed helper identities; a signed upgrade should retain those grants. If missing, run wechat-use init --fix-tcc: it opens the correct pane, selects the binaries in Finder for drag-and-drop, then automatically rechecks the running daemon. Do not ask the user to find hidden paths or type recovery commands themselves.

Step 4 — Verify a send without manual chat selection:

The daemon reads the selected chat identity and uses background conversation navigation to select the exact requested recipient before typing. It checks the identity again before Enter. Missing build calibration, ambiguous context, a changed recipient, or an unavailable target stops the send before dispatch. Do not ask the user to click filehelper or send a warmup message as a normal setup step. The current local candidate requires a matching recipient-context calibration; distribution of this calibration is still pending and must be tested before release.

Only a verified record in the requested chat counts as delivery. A delivery_verify_timeout can be a delayed delivery: inspect history before retrying. If automatic preparation fails, keep the diagnostic output and run wechat-use doctor --json; do not restart the logged-in WeChat or reactivate its account as a workaround.

An empty AX tree or blank automation screenshot is not proof that WeChat is blank, logged out, or frozen. Use process/CLI/database evidence and the user's visible state before diagnosing it. Never quit/relaunch a logged-in clone just to recover an automation snapshot.

Send failure modes (agent self-recovery table)

When wechat-use send returns {ok: false, …} or stderr matches the reason: slot in the support payload, use the playbook below before asking the user to debug. Diagnose in the background and request human action only for a confirmed step that cannot be completed there. Never infer permission to take focus from a failed send.

Key principle: every reason: slot is stable enum; the support payload includes ax_trusted, input_monitoring, binary_fingerprint, cli_version, daemon_version — match on those exact field names, not on the human-readable Chinese error message (it may evolve across releases).

LaunchAgent / TCC handbook for agents: if you ever need to manually reset responsibility chains (e.g. user's machine has a customized LaunchAgent layout), use launchctl bootout + launchctl bootstrap — never launchctl kickstart -k. kickstart doesn't re-read plist EnvironmentVariables and doesn't reset launchd's responsibility-chain cache. The install.sh upgrade flow is the reference implementation.

Usage — send

send arguments

send --json 三态契约 (v1.13.20+)

所有 --json 输出都带顶层 ok: bool,agent 直接 if (r.ok) {...} else {...} 不需要解析三套 schema:

stderr 仍然有 human-readable 错误描述(给终端用户看);agent 只需 parse stdout JSON。

Usage — query

history --json payload shape (stable contract for agents)

顶层包装(history / sessions / unread / search / digest 全一致):

不是裸数组。jq 要 .rows[] 不是 .[]。meta.order 是 v1.16.12+ 加的字段,告诉 你 rows 是 "desc"(新→老,history 默认)还是 "asc"(老→新,digest 默认 / wechat history --order asc)。别拿 rows[0] 当"最新"也别当"最老",先看 meta.order。

meta.status 取值:ok / windowed(传了 --since/--until)/ possibly_stale (SessionTable 比 history 领先 > 24h,大概率分片漂)/ possibly_stale_unknown_shards (磁盘有新分片 daemon 不认,要重跑 wechat-use init)。

v1.16.19+ 时间窗回灌(history): meta.now_unix 是查询时的本机 epoch; meta.since_resolved / meta.until_resolved 是 --since / --until 自然语言解析后的 实际 epoch(没传不出现)。自然语言 --since "2 days ago" 解析完后,agent 不用重算时区, 直接拿这三个值跟用户复述"实际查的是 X 到 Y, 当下 Z"。

每条 message row 字段(snake_case):

字段稳定性:增加 = 默认 null / 缺省;不会重命名 / 改类型(契约由 v1.10.27 起的 SSE schema 单测守)。

想跨 chat 拉"我说过什么": 用 wechat-use sent --since "7 days ago" --json(v1.16.12+), 比手动遍历 sessions + filter 干净得多。

群名歧义: wechat-use history "AI 星球" 可能匹配多个(同名群 + 同名联系人)。 撞歧义时 CLI 会列出候选 + 报错,改用 --chat <wxid> 或 --chat <chatroom_id@chatroom> 明确指定。

v1.16.19+ user alias: 长群名 / emoji 前缀群名 fuzzy 经常 miss(詹密群 / 季景铭郡业主三群),用 alias map 一劳永逸:

Resolver 优先级:wxid-shape > alias > contact.db fuzzy。wechat-use send / history / digest / search / recalled / sent / listen --wxid 全部 共享同一查找(写到 ~/.wx-rs/aliases.json)。

Voice — agents reading group history just work (v1.13.25+)

After running wechat-use audio setup once (~2-3 minutes downloads ~1.5GB medium model + builds silk-decoder), wechat-use history automatically transcribes voice messages so the agent sees the spoken content in display_text (and structured in media.transcript) — no more [语音消息] placeholders breaking conversation context. Transcripts are cached by SHA-256 of the audio blob, so re-reading the same chat is near-instant.

Opt-out (skip transcribe to keep history fast / private):

The media.transcript_status field on each audio row tells the agent where the text came from: cached / transcribed / no_deps (run wechat-use audio setup) / failed / skipped_svr_id_zero / invalid_input.

wechat-use doctor reports audio readiness in two rows so machine consumers can check default-model status without parsing strings:

• audio_transcribe_setup — overall ffmpeg / whisper-cli / silk-decoder presence. Always ok: true (audio is optional; missing tools must not flip overall doctor status to needs_init).
• audio_transcribe_default_model — ggml-medium.bin exists. ok reflects reality, but excluded from the overall status calculation so a user without medium still sees status: "ok". Read this row's ok field directly to know whether wechat-use history default transcribe will work.

For a single voice file outside history:

wechat-use audio transcribe --json defaults to redacting the transcript text (only metadata in JSON output) so agents can't accidentally log private conversation text. Pass --include-transcript to opt in.

Voice — manual decode if you skip audio setup

wechat-use audio get <svr_id> writes the raw .silk bytes locally (pure local DB read; no debugging interface / in-memory lookup / CDN). To play / share without going through audio transcribe:

Note: SNS / Moments commands (sns-feed, sns-search, sns-notifications) and the legacy bootstrap subcommand were removed in the v1.13 line. The data is still in sns.db if you query it directly with sqlcipher, but no first-class CLI surface yet — track via roadmap.

Usage — realtime listen (v1.3)

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

--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

The daemon caches each encrypted local DB connection so wechat-use sessions / contacts / history / unread run in <30ms (vs 400-500ms without it). It also powers wechat-use 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-use contacts --query ... first if you need to disambiguate.

Output format

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

When to invoke this skill (agent triggers)

Send:

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

Query:

• "微信里 Lisa 最近说了什么" → wechat-use history Lisa
• "搜一下群里谁提过报销" → wechat-use search 报销
• "AI 星球群有多少人 / 谁发言最多" → wechat-use members + wechat-use stats
• "有哪些未读消息" → wechat-use unread
• "导出我和张三的聊天记录" → wechat-use export 张三 -o ...
• "XX 群里那张图是什么" → wechat-use history "XX群" -n 50 (找 message_kind: image 的 local_id) → wechat-use image get <local_id> --chat <chat_id>
• "最近收藏了什么" → wechat-use favorites

Realtime:

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

Example user utterances and the right first call:

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

🔐 Security / data scope

• Everything runs 100% locally — no data leaves the machine.
• wechat-use 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 — reuses cached database keys when valid and otherwise scans the running managed clone through the macOS public debugging interface. Preserve the existing login; do not restart WeChat as routine initialization. The debugging interface detaches after capture.

Query commands — load the captured material + discovered DB paths from local config and read the encrypted local databases directly. When the background daemon is running, queries are routed over a local Unix socket to a persistent connection pool — cuts latency 5-10×.

listen — watches the on-disk message databases for changes and pushes each new row to subscribed CLI processes over the daemon socket. Zero network traffic; runs entirely locally.

send — uses macOS Accessibility API to silently target the chat input, then drives WeChat's normal send pipeline via the local debugging interface. Zero window activation / focus steal.

Caveats

• macOS arm64 only. Only the independent WeChat 4.1.9 clone receives ongoing support — run wechat-use doctor to confirm your specific build is in the adaptation set. Other versions may need adaptation work.
• 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:

Upgrade to latest (safe, idempotent) — wechat-use upgrade (see "## Upgrade" below). On a version without that command, re-run the installer:

Both pull 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:

• A wechat-use command printed wechat-use X is available, or wechat-use upgrade --check shows current -> latest
• wechat --version is more than one minor behind the latest release tag at https://github.com/leeguooooo/wechat-use/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 adaptation data (watch https://github.com/leeguooooo/wechat-use/releases for a note)

Stopping WeChat's auto-update (highly recommended, v1.16.33+):

After wechat-use init succeeds + wechat-use send works on the current build, run:

This locks the MacUpdate directory under WeChat's container with chflags uchg so Tencent's silent dylib hot-update can't replace the binary. The current adaptation profile stays valid until the user explicitly runs wechat-use update-guard enable to restore. wechat-use doctor shows wechat_update_guard as ✓ when disabled. Pure user-level reversible — does not touch the WeChat binary, NSUserDefaults, or TCC.

Adapting a brand-new WeChat build that isn't in the verified list (v1.16.32+):

If wechat-use doctor shows wechat_dylib_fingerprint ✗ (not in verified list) AND wechat-use send fails with "build not supported":

This hashes the local dylib, runs literal_scan to verify SQLCipher key extraction, pattern-matches three routing anchors against the ARM64 slice, and POSTs the derived numerical shifts to the adaptation queue. Does not upload binary bytes. Read-side commands (history / sessions / unread / sent) keep working via the literal_scan fallback while waiting for send adaptation.

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

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.

Upgrade

The launcher command below is pending the next release that includes it. v1.18.13 and earlier still require the documented install.sh command to upgrade.

When any wechat-use command prints wechat-use X is available, tell the user and offer to run wechat-use upgrade (updates the CLI only; add --skills to also refresh this skill — plugin, git checkout or installer-managed copy of wechat-use only). Check without changing anything: wechat-use upgrade --check (or --json). Pin a release with --tag vX.Y.Z. It never sends a WeChat message or asks for login. The user may also just say "升级 wechat-use" / "upgrade wechat-use". This is unrelated to wechat-use update-guard, which blocks WeChat's own auto-update.

If the skill came from somewhere upgrade can't refresh:

• Claude Code plugin: claude plugin update wechat-use@leeguooooo-plugins
• Whole family: curl -fsSL https://raw.githubusercontent.com/leeguooooo/plugins/main/upgrade-use-family.sh | sh

Support

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