ai_member_only/wechat_msg_crawler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7b9139bd8f
wechat_msg_crawler/README.md

347 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div align="center">
# WeChat CLI
**Query your local WeChat data from the command line.**
[![npm version](https://img.shields.io/npm/v/@canghe_ai/wechat-cli.svg)](https://www.npmjs.com/package/@canghe_ai/wechat-cli)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg)](https://github.com/freestylefly/wechat-cli)
Chat history · Contacts · Sessions · Favorites · Statistics · Export
[中文文档](README_CN.md)
</div>
---
## ✨ Highlights
- **🚀 Zero-config install** — `npm install -g` and you're done, no Python needed
- **📦 11 commands** — sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages, init
- **🤖 AI-first** — JSON output by default, designed for LLM agent tool calls
- **🔒 Fully local** — on-the-fly SQLCipher decryption, data never leaves your machine
- **📊 Rich analytics** — top senders, message type breakdown, 24-hour activity charts
- **📝 Flexible export** — Markdown or plain text, with time range filtering
---
## 📥 Installation (For Humans)
AI Agents — skip ahead to "Installation (For AI Agents)" below.
### npm (Recommended)
```bash
npm install -g @canghe_ai/wechat-cli
```
> Currently ships a **macOS arm64** binary. Other platforms can use the pip method below. PRs with additional platform binaries are welcome.
**Update to the latest version:**
```bash
npm update -g @canghe_ai/wechat-cli
```
### pip
```bash
pip install wechat-cli
```
Requires Python >= 3.10.
### From Source
```bash
git clone https://github.com/freestylefly/wechat-cli.git
cd wechat-cli
pip install -e .
```
---
## 📥 Installation (For AI Agents)
Simply paste the following prompt into Claude Code, OpenClaw, or any AI coding agent:
```bash
帮我配置并安装：npm install -g @canghe_ai/wechat-cli
```
For example, in Claude Code:
![install-claude-code-1](image/install-claude-code-1.png)
Note: Make sure you have Node.js installed first. You can ask your agent to set it up if needed.
---
## 🚀 Quick Start
### Step 1 — Initialize
Make sure WeChat is running, then:
```bash
# macOS/Linux: may need sudo for memory scanning
sudo wechat-cli init
# Windows: run in a terminal with sufficient privileges
wechat-cli init
```
This auto-detects your WeChat data directory, extracts encryption keys, and saves config to `~/.wechat-cli/`.
![init-claude-code-1](image/init-claude-code-1.png)
On macOS, you'll need to run the `sudo` command and enter your password:
![init-claude-code-2](image/init-claude-code-2.png)
If you have multiple WeChat accounts logged in locally, you'll be prompted to choose one. Select the account you're currently using (the default is the first one):
![init-claude-code-3](image/init-claude-code-3.png)
If you're unsure which WeChat account is currently active, navigate to the data folder and sort by modification date to find out:
![init-claude-code-4](image/init-claude-code-4.png)
#### macOS: `task_for_pid failed` Error
On some macOS systems, `init` may fail with `task_for_pid failed` even when running with `sudo`. This is due to macOS security restrictions on process memory access.
**WeChat CLI will automatically attempt to fix this** by re-signing WeChat with the required entitlement (original entitlements are preserved). Just follow the on-screen instructions:
1. The tool will re-sign WeChat automatically
2. Quit WeChat completely (not just minimize)
3. Reopen WeChat and log in
4. Run `sudo wechat-cli init` again
If auto re-signing fails, you can do it manually:
```bash
# Quit WeChat first, then:
sudo codesign --force --sign - --entitlements /dev/stdin /Applications/WeChat.app <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.get-task-allow</key>
<true/>
</dict>
</plist>
EOF
```
> **Heads up:** Re-signing WeChat is safe and will **not** cause account issues or bans. However, it may affect WeChat's auto-update mechanism. If WeChat prompts you to update but fails, simply re-download and install WeChat from the official website, then re-run `sudo wechat-cli init`.
### Step 2 — Use It
```bash
wechat-cli sessions # Recent chats
wechat-cli history "Alice" --limit 20 # Chat messages
wechat-cli search "deadline" --chat "Team" # Search messages
```
---
## 🤖 Using with AI Agents
WeChat CLI is designed as an AI agent tool. All commands output structured JSON by default.
### Claude Code
Add to your project's `CLAUDE.md`:
```markdown
## WeChat CLI
You can use `wechat-cli` to query my local WeChat data.
Common commands:
- `wechat-cli sessions --limit 10` — list recent chats
- `wechat-cli history "NAME" --limit 20 --format text` — read chat history
- `wechat-cli search "KEYWORD" --chat "CHAT_NAME"` — search messages
- `wechat-cli contacts --query "NAME"` — search contacts
- `wechat-cli unread` — show unread sessions
- `wechat-cli new-messages` — get messages since last check
- `wechat-cli members "GROUP"` — list group members
- `wechat-cli stats "CHAT" --format text` — chat statistics
```
Then in conversation you can ask Claude things like:
- "Check my unread WeChat messages"
- "Search for messages about the project deadline in the Team group"
- "Who sent the most messages in the AI group this week?"
### OpenClaw / MCP Integration
WeChat CLI works with any AI tool that can execute shell commands:
```bash
# Get recent conversations
wechat-cli sessions --limit 5
# Read specific chat
wechat-cli history "Alice" --limit 30 --format text
# Search with filters
wechat-cli search "report" --type file --limit 10
# Monitor for new messages (great for cron/automation)
wechat-cli new-messages --format text
```
---
## 📖 Command Reference
### `sessions` — Recent Chats
```bash
wechat-cli sessions # Last 20 sessions
wechat-cli sessions --limit 10 # Last 10
wechat-cli sessions --format text # Human-readable
```
### `history` — Chat Messages
```bash
wechat-cli history "Alice" # Last 50 messages
wechat-cli history "Alice" --limit 100 --offset 50
wechat-cli history "Team" --start-time "2026-04-01" --end-time "2026-04-03"
wechat-cli history "Alice" --type link # Only links
wechat-cli history "Alice" --format text
```
**Options:** `--limit`, `--offset`, `--start-time`, `--end-time`, `--type`, `--format`
### `search` — Search Messages
```bash
wechat-cli search "hello" # Global search
wechat-cli search "hello" --chat "Alice" # In specific chat
wechat-cli search "meeting" --chat "TeamA" --chat "TeamB" # Multiple chats
wechat-cli search "report" --type file # Only files
```
**Options:** `--chat` (repeatable), `--start-time`, `--end-time`, `--limit`, `--offset`, `--type`, `--format`
### `contacts` — Contact Search & Details
```bash
wechat-cli contacts --query "Li" # Search contacts
wechat-cli contacts --detail "Alice" # Contact details
wechat-cli contacts --detail "wxid_xxx" # By WeChat ID
```
Returns: nickname, remark, WeChat ID, bio, avatar URL, account type.
### `members` — Group Members
```bash
wechat-cli members "Team Group" # All members (JSON)
wechat-cli members "Team Group" --format text
```
### `stats` — Chat Statistics
```bash
wechat-cli stats "Team Group"
wechat-cli stats "Alice" --start-time "2026-04-01" --end-time "2026-04-03"
wechat-cli stats "Team Group" --format text
```
Returns: total messages, type breakdown, top 10 senders, 24-hour activity distribution.
### `export` — Export Conversations
```bash
wechat-cli export "Alice" --format markdown # To stdout
wechat-cli export "Alice" --format txt --output chat.txt # To file
wechat-cli export "Team" --start-time "2026-04-01" --limit 1000
```
**Options:** `--format markdown|txt`, `--output`, `--start-time`, `--end-time`, `--limit`
### `favorites` — WeChat Bookmarks
```bash
wechat-cli favorites # Recent bookmarks
wechat-cli favorites --type article # Articles only
wechat-cli favorites --query "machine learning" # Search
```
**Types:** text, image, article, card, video
### `unread` — Unread Sessions
```bash
wechat-cli unread # All unread sessions
wechat-cli unread --limit 10 --format text
```
### `new-messages` — Incremental New Messages
```bash
wechat-cli new-messages # First: return unread + save state
wechat-cli new-messages # Subsequent: only new since last call
```
State saved at `~/.wechat-cli/last_check.json`. Delete to reset.
---
## 🔍 Message Type Filter
The `--type` option (on `history` and `search`):
| Value | Description |
|-------|-------------|
| `text` | Text messages |
| `image` | Images |
| `voice` | Voice messages |
| `video` | Videos |
| `sticker` | Stickers/emojis |
| `location` | Location shares |
| `link` | Links and app messages |
| `file` | File attachments |
| `call` | Voice/video calls |
| `system` | System messages |
---
## 🖥️ Platform Support
| Platform | Status | Notes |
|----------|--------|-------|
| macOS (Apple Silicon) | ✅ Supported | Bundled arm64 binary |
| macOS (Intel) | ✅ Supported | x86_64 binary needed |
| Windows | ✅ Supported | Reads Weixin.exe process memory |
| Linux | ✅ Supported | Reads /proc/pid/mem, requires root |
---
## 🔧 How It Works
WeChat stores chat data in SQLCipher-encrypted SQLite databases locally. WeChat CLI:
1. **Extracts keys** — scans WeChat process memory for encryption keys (`init`)
2. **Decrypts on-the-fly** — transparent page-level AES-256-CBC decryption with caching
3. **Queries locally** — all data stays on your machine, no network access
---
## 📄 License
[Apache License 2.0](LICENSE)
---
## ⭐ Star History
[![Star History Chart](https://api.star-history.com/svg?repos=freestylefly/wechat-cli&type=Date)](https://star-history.com/#freestylefly/wechat-cli&Date)
Reference in New Issue View Git Blame Copy Permalink