@agent-wechat/wechat 0.7.6 → 0.7.7

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.
Files changed (2) hide show
  1. package/README.md +84 -57
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,17 +1,95 @@
1
1
  # @agent-wechat/wechat
2
2
 
3
- OpenClaw channel plugin for WeChat. Polls the agent-wechat REST API for inbound messages and dispatches replies through OpenClaw's agent runtime.
3
+ OpenClaw channel plugin for WeChat. Connects your OpenClaw bot to WeChat using [agent-wechat](https://github.com/thisnick/agent-wechat).
4
4
 
5
5
  ## Prerequisites
6
6
 
7
- - [Docker](https://docs.docker.com/get-docker/) installed and running (or a hosted agent-wechat instance)
8
- - OpenClaw installed and configured
7
+ - **A WeChat account logged in on your phone** — This account will be used by the bot. You must keep it logged in on your phone at all times. If you log out on the phone, the bot loses its connection.
8
+
9
+ - **A second screen** — WeChat login requires scanning a QR code with your phone camera. You'll need the QR code displayed on a screen separate from the phone running WeChat (e.g., a computer monitor, tablet, or another phone).
10
+
11
+ - **An agent-wechat server** — Either self-hosted via Docker or provided by someone else. You'll need the server URL and authentication token.
9
12
 
10
13
  > **Note:** The agent-wechat container requires `SYS_PTRACE` and `seccomp=unconfined` (ptrace access to 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.
11
14
 
12
15
  ## Setup
13
16
 
14
- ### 1. Start the agent-wechat container
17
+ ### 1. Install the extension
18
+
19
+ ```bash
20
+ openclaw plugins install @agent-wechat/wechat
21
+ ```
22
+
23
+ ### 2. Configure the channel
24
+
25
+ ```bash
26
+ # Uses defaults (localhost:6174, token from ~/.config/agent-wechat/token)
27
+ openclaw channels add --channel wechat
28
+
29
+ # Override server URL and token
30
+ openclaw channels add --channel wechat --url <url> --token <token>
31
+ ```
32
+
33
+ Or edit `~/.openclaw/openclaw.json` directly:
34
+
35
+ ```json
36
+ {
37
+ "channels": {
38
+ "wechat": {
39
+ "enabled": true,
40
+ "serverUrl": "http://localhost:6174",
41
+ "dmPolicy": "open",
42
+ "groupPolicy": "open"
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ For local setups, the token is automatically read from `~/.config/agent-wechat/token` (shared with the CLI and container), so you don't need to set it in the config. When connecting to a remote server, add the `token` field.
49
+
50
+ ### 3. Restart the gateway
51
+
52
+ Restart your OpenClaw gateway so it picks up the new channel config:
53
+
54
+ ```bash
55
+ openclaw gateway restart
56
+ ```
57
+
58
+ ### 4. Log in to WeChat
59
+
60
+ Ask your bot to log in to WeChat:
61
+
62
+ > "Log in to WeChat"
63
+
64
+ Your bot should generate a QR code image. Alternatively, use the CLI:
65
+
66
+ ```bash
67
+ openclaw channels login --channel wechat
68
+ ```
69
+
70
+ ### 5. Scan the QR code
71
+
72
+ Display the QR code on a screen separate from the phone running WeChat. WeChat's login QR scanner uses the camera only — it cannot scan from the phone's photo gallery.
73
+
74
+ Scan the QR code using WeChat's built-in scanner (tap **+** > **Scan**) with the account you want the bot to use. Then tap **Login** on the confirmation screen.
75
+
76
+ You only need to do this once — the session persists across container restarts.
77
+
78
+ ### 6. Configure DM and group policies
79
+
80
+ Once connected, configure how the bot handles direct messages and group chats. You can ask your bot to help you, or edit the config directly. See the Configuration Reference below.
81
+
82
+ ## Limitations
83
+
84
+ - **The WeChat account must stay logged in on your phone.** Logging out on the phone disconnects the bot. One workaround: after the bot is logged in, you can uninstall and reinstall WeChat on your phone — the bot session persists. On Android, you can also run WeChat in a separate profile (Work Profile or Private Space) to keep the bot account isolated.
85
+
86
+ - **Only one desktop session.** Once the bot is logged in as a "desktop" client, you cannot simultaneously use WeChat on another computer or WeChat Web.
87
+
88
+ - **Infrastructure updates disconnect the bot.** If the agent-wechat server restarts or updates, the bot will be disconnected. When this happens, ask your bot to log in again. If the disconnection was brief, you may not need a new QR code scan.
89
+
90
+ ## Starting the agent-wechat Server
91
+
92
+ If you need to run the server yourself:
15
93
 
16
94
  **Option A: CLI** (quickest for local use)
17
95
 
@@ -54,58 +132,7 @@ chmod 600 ~/.config/agent-wechat/token
54
132
  docker compose up -d
55
133
  ```
56
134
 
57
- If running alongside OpenClaw on the same Docker network, set `serverUrl` to `http://agent-wechat:6174` in the channel config below.
58
-
59
- **Option C: Hosted instance**
60
-
61
- If someone has provisioned a hosted agent-wechat instance for you, you'll receive a server URL and auth token. Skip to step 2 — just provide the URL and token during channel setup.
62
-
63
- ### 2. Install the extension
64
-
65
- ```bash
66
- openclaw plugins install @agent-wechat/wechat
67
- ```
68
-
69
- ### 3. Log in to WeChat
70
-
71
- ```bash
72
- openclaw channels login --channel wechat
73
- ```
74
-
75
- This displays a QR code in your terminal — scan it with WeChat on your phone. You only need to do this once (the session persists across container restarts).
76
-
77
- If you installed the CLI, you can also use `wx auth login`.
78
-
79
- ### 4. Configure the channel
80
-
81
- Run the setup wizard:
82
-
83
- ```bash
84
- openclaw channels setup wechat
85
- ```
86
-
87
- Or edit `~/.openclaw/openclaw.json` directly:
88
-
89
- ```json
90
- {
91
- "channels": {
92
- "wechat": {
93
- "enabled": true,
94
- "serverUrl": "http://localhost:6174"
95
- }
96
- }
97
- }
98
- ```
99
-
100
- For local setups, the token is automatically read from `~/.config/agent-wechat/token` (shared with the CLI and container), so you don't need to set it in the config. For hosted instances, add the `token` field with the token you were given.
101
-
102
- ### 5. Run the gateway
103
-
104
- ```bash
105
- openclaw gateway run --verbose
106
- ```
107
-
108
- The WeChat monitor starts polling the agent-wechat server for new messages. Make sure the agent-wechat container is running.
135
+ If running alongside OpenClaw on the same Docker network, set `serverUrl` to `http://agent-wechat:6174` in the channel config.
109
136
 
110
137
  ## Configuration Reference
111
138
 
@@ -115,7 +142,7 @@ All config lives under `channels.wechat` in OpenClaw's config file:
115
142
  |-----|------|---------|-------------|
116
143
  | `enabled` | boolean | `false` | Enable the WeChat channel |
117
144
  | `serverUrl` | string | — | agent-wechat REST API URL |
118
- | `token` | string | — | Auth token (required for hosted instances) |
145
+ | `token` | string | — | Auth token (auto-read from `~/.config/agent-wechat/token` for local setups) |
119
146
  | `dmPolicy` | `"open" \| "allowlist" \| "disabled"` | `"disabled"` | Who can DM the bot |
120
147
  | `allowFrom` | string[] | `[]` | wxid allowlist for DMs (when policy is `allowlist`) |
121
148
  | `groupPolicy` | `"open" \| "allowlist" \| "disabled"` | `"disabled"` | Group message policy |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-wechat/wechat",
3
- "version": "0.7.6",
3
+ "version": "0.7.7",
4
4
  "type": "module",
5
5
  "files": [
6
6
  "dist",