Setup & troubleshooting — wx-cli environment
Load this file when: (a) starting a run in a fresh environment where wx-cli hasn't been verified yet, or (b) any wx command fails.
Prerequisites
Before invoking the workflow, verify the environment. Run these checks in order; stop at the first failure and surface the exact next command the user needs.
- wx-cli installed — run
wx --version. If missing, tell the user to install it themselves (npm install -g @jackwener/wx-clior use one of the alternatives at https://github.com/jackwener/wx-cli). Do NOT auto-install — this repo forbids piped/silent installs. ~/.wx-clidirectory owned by the current user —sudo wx inithistorically chowned this directory to root, which breaks every subsequent non-sudowxcall. Check:ls -la ~/.wx-cli/ 2>/dev/null | head -5root(or anything other than$(whoami)), tell the user to repair it themselves:sudo chown -R $(whoami) ~/.wx-cli sudo rm -f ~/.wx-cli/daemon.pid ~/.wx-cli/daemon.sock wx daemon startsudoon the user's behalf.- wx-cli initialized —
wx sessionsshould return data. If it fails with "no keys" / "init required", instruct the user to runwx initwhile WeChat is running (on macOS,codesign --force --deep --sign - /Applications/WeChat.appfirst). Prefer non-sudo init; only fall back tosudo wx initif the user's wx-cli version requires it — and warn them that they'll need step 2's chown after. - WeChat 4.x running and logged in — required for the daemon to find data files.
wx-cli quick reference
| Command | Purpose |
|---|---|
wx --version |
Sanity-check that wx-cli is installed |
wx sessions --json |
List recent sessions; useful for verifying init and finding the user's own wxid |
wx contacts --query "<name>" --json |
Fuzzy-match contacts/groups by display name, remark, or wxid |
wx history "<group>" --since DATE --until DATE -n N --json |
Pull a group's messages within a date range as JSON |
wx members "<group>" --json |
List a group's members (rarely needed; mostly for completeness) |
wx stats "<group>" --since DATE |
wx-cli's built-in stats; we compute our own from wx history JSON so the format matches our digest |
wx daemon status / wx daemon stop / wx daemon logs --follow |
Daemon lifecycle (troubleshooting) |
All wx commands accept --json for machine-readable output. Default output is YAML — only use it for human eyeballing during debugging.
Troubleshooting
When a wx command fails, diagnose by the symptom, not by retrying blindly. Common patterns:
| Symptom | Cause | Fix (tell the user to run these — do NOT run sudo for them) |
|---|---|---|
Operation not permitted / Access denied to ~/.wx-cli |
Sandbox is on | Re-run the command with dangerouslyDisableSandbox: true. Persistent fix: /sandbox to allow ~/.wx-cli and the WeChat data dir. |
无法写入 /Users/<u>/.wx-cli / Permission denied |
~/.wx-cli is owned by root (legacy sudo wx init) |
sudo chown -R $(whoami) ~/.wx-cli && sudo rm -f ~/.wx-cli/daemon.{pid,sock} && wx daemon start |
wx history hangs / times out / returns nothing |
Daemon is stuck | wx daemon stop && rm -f ~/.wx-cli/daemon.{pid,sock} && wx daemon start, then retry |
no keys / init required after the daemon was working |
Keys went stale (WeChat restart, version upgrade) | Make sure WeChat is running, then wx init --force (non-sudo first; only sudo if your wx-cli version requires it) |
wx contacts returns zero rows for a group you know exists |
Group is folded into 折叠群 or the daemon hasn't indexed it yet | wx sessions --json and search there; if missing, run wx daemon stop && wx daemon start and retry |
Messages returned but --since / --until window looks wrong |
Date string not in YYYY-MM-DD format, or off-by-one timezone |
Confirm the dates are local-time YYYY-MM-DD. Re-filter the JSON by timestamp locally as a belt-and-suspenders step. |
| Empty result for a chat that should have activity | -n cap too low for a noisy group |
Raise -n (e.g. to 20000) and re-fetch |
Recovery order when nothing makes sense:
- Is WeChat running?
- Is
~/.wx-cliowned by$(whoami)? - Is the daemon healthy? (
wx daemon status) - Restart the daemon (
wx daemon stop && wx daemon start) - Last resort:
wx init --force(while WeChat is running)
Never auto-retry inside the skill — every failure should produce a clear diagnostic plus the exact command the user needs to run.