@agent-wechat/cli 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +196 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# @agent-wechat/cli
|
|
2
|
+
|
|
3
|
+
Command-line tool for managing agent-wechat containers and interacting with WeChat.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @agent-wechat/cli
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
This installs the `wx` command globally.
|
|
12
|
+
|
|
13
|
+
## Prerequisites
|
|
14
|
+
|
|
15
|
+
- [Docker](https://docs.docker.com/get-docker/) installed and running
|
|
16
|
+
- An agent-wechat Docker image — pull from ghcr.io or build locally (see [Docker Image](#docker-image))
|
|
17
|
+
|
|
18
|
+
> **Note:** agent-wechat requires `SYS_PTRACE` and `seccomp=unconfined` to interact with the WeChat desktop process. It cannot run in serverless or restricted container environments (AWS Fargate, Cloud Run, etc.). Use a VM or bare-metal Docker host.
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Start the container
|
|
24
|
+
wx up
|
|
25
|
+
|
|
26
|
+
# Check status
|
|
27
|
+
wx status
|
|
28
|
+
|
|
29
|
+
# Log in (displays QR code in terminal)
|
|
30
|
+
wx auth login
|
|
31
|
+
|
|
32
|
+
# List chats
|
|
33
|
+
wx chats list
|
|
34
|
+
|
|
35
|
+
# Send a message
|
|
36
|
+
wx messages send <chatId> --text "Hello"
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Commands
|
|
40
|
+
|
|
41
|
+
### Container
|
|
42
|
+
|
|
43
|
+
| Command | Description |
|
|
44
|
+
|---------|-------------|
|
|
45
|
+
| `wx up` | Start the agent-wechat container |
|
|
46
|
+
| `wx down` | Stop and remove the container |
|
|
47
|
+
| `wx logs` | Tail container logs |
|
|
48
|
+
| `wx status` | Show container and login status |
|
|
49
|
+
|
|
50
|
+
### Auth
|
|
51
|
+
|
|
52
|
+
| Command | Description |
|
|
53
|
+
|---------|-------------|
|
|
54
|
+
| `wx auth login` | Log in to WeChat (shows QR code) |
|
|
55
|
+
| `wx auth logout` | Log out of WeChat |
|
|
56
|
+
| `wx auth status` | Check login status |
|
|
57
|
+
| `wx auth token` | Show current auth token |
|
|
58
|
+
| `wx auth token --regenerate` | Generate a new auth token |
|
|
59
|
+
|
|
60
|
+
Login options:
|
|
61
|
+
- `--timeout <seconds>` — login timeout (default: 300)
|
|
62
|
+
- `--new` — switch to a new account instead of existing
|
|
63
|
+
|
|
64
|
+
### Chats
|
|
65
|
+
|
|
66
|
+
| Command | Description |
|
|
67
|
+
|---------|-------------|
|
|
68
|
+
| `wx chats list` | List chats from WeChat |
|
|
69
|
+
| `wx chats get <chatId>` | Get details for a specific chat |
|
|
70
|
+
| `wx chats find <name>` | Search chats by display name |
|
|
71
|
+
| `wx chats open <chatId>` | Open a chat in the WeChat UI |
|
|
72
|
+
|
|
73
|
+
Options: `--limit <n>`, `--offset <n>`, `--json`
|
|
74
|
+
|
|
75
|
+
### Messages
|
|
76
|
+
|
|
77
|
+
| Command | Description |
|
|
78
|
+
|---------|-------------|
|
|
79
|
+
| `wx messages list <chatId>` | List messages in a chat |
|
|
80
|
+
| `wx messages send <chatId>` | Send a message |
|
|
81
|
+
| `wx messages media <chatId> <localId>` | Download a media attachment |
|
|
82
|
+
|
|
83
|
+
Send options:
|
|
84
|
+
- `--text "message"` — send text
|
|
85
|
+
- `--image photo.jpg` — send an image
|
|
86
|
+
- `--file document.pdf` — send a file
|
|
87
|
+
|
|
88
|
+
Media options:
|
|
89
|
+
- `--output <path>` — save to a specific file path
|
|
90
|
+
|
|
91
|
+
### Sessions
|
|
92
|
+
|
|
93
|
+
| Command | Description |
|
|
94
|
+
|---------|-------------|
|
|
95
|
+
| `wx session list` | List all sessions |
|
|
96
|
+
| `wx session create <name>` | Create a new session |
|
|
97
|
+
| `wx session start <id>` | Start a session |
|
|
98
|
+
| `wx session stop <id>` | Stop a session |
|
|
99
|
+
| `wx session delete <id>` | Delete a session |
|
|
100
|
+
|
|
101
|
+
### Debug
|
|
102
|
+
|
|
103
|
+
| Command | Description |
|
|
104
|
+
|---------|-------------|
|
|
105
|
+
| `wx screenshot [file]` | Save a screenshot (default: screenshot.png) |
|
|
106
|
+
| `wx a11y` | Dump the accessibility tree (`--format json|aria`) |
|
|
107
|
+
|
|
108
|
+
## Global Options
|
|
109
|
+
|
|
110
|
+
| Option | Description |
|
|
111
|
+
|--------|-------------|
|
|
112
|
+
| `-s, --session <name>` | Use a specific session (default: "default") |
|
|
113
|
+
| `-V, --version` | Show version |
|
|
114
|
+
| `-h, --help` | Show help |
|
|
115
|
+
|
|
116
|
+
## Configuration
|
|
117
|
+
|
|
118
|
+
The CLI reads configuration from environment variables and a local token file:
|
|
119
|
+
|
|
120
|
+
| Source | Description |
|
|
121
|
+
|--------|-------------|
|
|
122
|
+
| `AGENT_WECHAT_URL` | Server URL (default: `http://localhost:6174`) |
|
|
123
|
+
| `AGENT_WECHAT_TOKEN` | Auth token (overrides token file) |
|
|
124
|
+
| `~/.config/agent-wechat/token` | Auto-generated auth token |
|
|
125
|
+
|
|
126
|
+
The auth token is generated automatically on first run and shared with the container via a read-only volume mount.
|
|
127
|
+
|
|
128
|
+
## Running the Container
|
|
129
|
+
|
|
130
|
+
There are two ways to run the agent-wechat container.
|
|
131
|
+
|
|
132
|
+
> **Note:** agent-wechat requires `SYS_PTRACE` and `seccomp=unconfined` because it uses ptrace to interact with the WeChat desktop process. It cannot run in serverless or restricted container environments (AWS Fargate, Cloud Run, Azure Container Instances, etc.). Use a VM or bare-metal Docker host.
|
|
133
|
+
|
|
134
|
+
### Option 1: `wx up` (local development)
|
|
135
|
+
|
|
136
|
+
The simplest way. `wx up` pulls/starts the container with the right flags, volume mounts, and auth token:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
wx up
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
This starts a container named `agent-wechat` with:
|
|
143
|
+
- **Port 6174** — REST API (exposed to all interfaces)
|
|
144
|
+
- **Port 5900** — VNC (localhost only — use SSH tunnel for remote access)
|
|
145
|
+
- Persistent volumes for data and WeChat home directory
|
|
146
|
+
- Auth token from `~/.config/agent-wechat/token` (auto-generated on first run)
|
|
147
|
+
|
|
148
|
+
### Option 2: Docker Compose (production / networked)
|
|
149
|
+
|
|
150
|
+
For production or when running alongside other services (e.g., OpenClaw), use the `docker-compose.yml` in the repo root as a reference:
|
|
151
|
+
|
|
152
|
+
```yaml
|
|
153
|
+
services:
|
|
154
|
+
agent-wechat:
|
|
155
|
+
image: ghcr.io/thisnick/agent-wechat:latest
|
|
156
|
+
container_name: agent-wechat
|
|
157
|
+
security_opt:
|
|
158
|
+
- seccomp=unconfined
|
|
159
|
+
cap_add:
|
|
160
|
+
- SYS_PTRACE
|
|
161
|
+
ports:
|
|
162
|
+
- "6174:6174"
|
|
163
|
+
- "127.0.0.1:5900:5900"
|
|
164
|
+
volumes:
|
|
165
|
+
- agent-wechat-data:/data
|
|
166
|
+
- agent-wechat-home:/home/wechat
|
|
167
|
+
- ~/.config/agent-wechat/token:/data/auth-token:ro
|
|
168
|
+
restart: unless-stopped
|
|
169
|
+
|
|
170
|
+
volumes:
|
|
171
|
+
agent-wechat-data:
|
|
172
|
+
agent-wechat-home:
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Generate a token before starting:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
mkdir -p ~/.config/agent-wechat
|
|
179
|
+
openssl rand -hex 32 > ~/.config/agent-wechat/token
|
|
180
|
+
chmod 600 ~/.config/agent-wechat/token
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
If running alongside OpenClaw on the same Docker network, set `serverUrl` to `http://agent-wechat:6174` in your OpenClaw config.
|
|
184
|
+
|
|
185
|
+
### Building locally
|
|
186
|
+
|
|
187
|
+
To build the Docker image from source instead of pulling from ghcr.io:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
# From the repo root — auto-detects host architecture
|
|
191
|
+
pnpm build:image
|
|
192
|
+
|
|
193
|
+
# Or specify architecture
|
|
194
|
+
pnpm build:image:arm64
|
|
195
|
+
pnpm build:image:amd64
|
|
196
|
+
```
|