@agent-wechat/agent-wechat 1.0.0-beta.8 → 1.0.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 +62 -2
- package/dist/index.js +1754 -417
- package/openclaw.plugin.json +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -23,6 +23,12 @@ Configure plugin defaults under `plugins.entries.agent-wechat.config` (or the sa
|
|
|
23
23
|
|
|
24
24
|
The external service remains independently owned. Plugin stop closes its stream and never stops/logs out the daemon or cancels its sends. Remote endpoints require verified HTTPS or an encrypted tunnel terminating at loopback. Set `AGENT_WECHAT_TOKEN` in the Gateway process environment, or use a configured OpenClaw secret provider. The plugin resolves `native.token` through the pinned OpenClaw SDK; `native.tokenFile` is removed. Tokens contain 32–1024 printable ASCII bytes without spaces. An explicit unresolved reference fails startup without falling back to another token. The API token needs read/media/send/login for the selected account, plus read-state only when automatic whole-thread read marking is enabled; do not grant admin solely to run the plugin. Normal sender/DM/group/mention policy remains in `channels.agent-wechat`; defaults remain closed.
|
|
25
25
|
|
|
26
|
+
## Login tool
|
|
27
|
+
|
|
28
|
+
`wechat_login` is available to configured agents through OpenClaw's tool policy, including from other channels while WeChat is offline. Use `{"action":"status"}` to inspect the account, `{"action":"start"}` to start or resume login and display the returned QR image, then `{"action":"wait","timeoutMs":30000}` to check scan/approval completion. Repeated starts reuse the pending operation. For a new operation, `force: true` uses QR instead of saved trust. Waits are bounded and report the operation ID and state. Cancelling a tool call leaves the submitted login operation available for a later call.
|
|
29
|
+
|
|
30
|
+
The tool also accepts `disconnect` (retain saved trust), `logout` (durable native logout) and `forget` with `confirm: true` (remove local authentication, retain history). It stays bound to the configured daemon/account. Apply OpenClaw tool allow/deny policies to control which agents can manage login. The tool is directly callable so the daemon's PNG reaches the model as image content.
|
|
31
|
+
|
|
26
32
|
## Native managed mode
|
|
27
33
|
|
|
28
34
|
```json
|
|
@@ -60,12 +66,36 @@ By default, `readPolicy: "on_inbound"` marks a whole thread read after its incom
|
|
|
60
66
|
|
|
61
67
|
A whole-thread read also clears earlier unread messages in that thread, including messages the model did not receive. The daemon freezes the latest local message boundary, checks the expected version, updates local unread state and submits one native read-status notification. Server acceptance alone does not prove that a phone badge changed. A lost notification response remains `needs_review` and is never automatically resubmitted. Pending reads survive a Gateway restart and retry independently of model execution or new SSE traffic. `readPolicy: "never"` disables both local and remote marking, including previously queued reads. Crashes during an unfinished dispatch retain `needs_review`; the plugin does not automatically duplicate model turns or uncertain outgoing sends.
|
|
62
68
|
|
|
63
|
-
The optional `readPolicy: "on_model_dispatch"` instead requires a confirmed model handoff. OpenClaw **2026.10.
|
|
69
|
+
The optional `readPolicy: "on_model_dispatch"` instead requires a confirmed model handoff. OpenClaw **2026.10.7** lacks `onPreparedAgentRunStart`, so its released public hooks provide a bounded compatibility path. Before dispatch, the adapter persists an immutable manifest binding the exact new message ID/version/content hash, policy hash, source and supplied asset hashes, and context roles. Text requires the exact current input and host-created message/account/session facts plus a matching `model_call_started`. Media additionally waits for the same run's `agent_end` snapshot and source-turn identity. Image bytes/MIME/length must match the frozen supplied representation; file/video/voice references must appear in the exact current body. Image count, model selection and reply delivery alone cannot confirm a model handoff. Unknown, omitted, rewritten, merged or ambiguous inputs remain unconfirmed. Host/provider history formats can prevent confirmation even when a reply was delivered; use `on_inbound` for ordinary bot read behavior.
|
|
64
70
|
|
|
65
71
|
The model-handoff compatibility path requires the operator's explicit host permission, `plugins.entries.agent-wechat.hooks.allowConversationAccess: true`. It observes only run IDs issued by this adapter and never enables that permission itself. Without the grant, or on an unsupported host, the explicit `on_model_dispatch` policy leaves messages unread and status reports `handoffUnconfirmed`. The older `onAgentRunStart` also reports direct tools and early lifecycle phases and is never used as proof. Access and mention gates still precede model dispatch; a rejected message does not itself trigger a read.
|
|
66
72
|
|
|
67
73
|
Images exceeding the host's bounded representation, or formats requiring conversion, receive a separately stored JPEG still preview using the public SDK image processor. The original stays intact; both hashes are recorded and the model input labels the preview. Prepared images fit within 5 MiB and at most 1200 pixels per side (or a smaller configured limit). Files and videos can be supplied as available local references; this does not claim their contents were analyzed. Voice retains its verified file and includes configured transcription output or an explicit unavailable status. A placeholder does not confirm a model handoff under `on_model_dispatch`; default `on_inbound` can mark a thread after successfully handling an explicit expired/unsupported status.
|
|
68
74
|
|
|
75
|
+
## Message recalls
|
|
76
|
+
|
|
77
|
+
`wechat_recall` recalls a message sent by the configured WeChat account in the current conversation. Pass `{"messageId":"<opaque stored ID>","serverId":"<exact decimal server ID>"}` using both values from the same verified send receipt or `wechat_history` entry. The server ID stays a string, including values larger than JavaScript's safe integer range. A local opaque ID can be reused, so an old reference with a different server ID is rejected. Send/job/operation IDs cannot replace a stored message ID.
|
|
78
|
+
|
|
79
|
+
The tool uses OpenClaw's trusted account, conversation and requester context. It accepts no account or thread selector, rechecks normal requester policy, and requires an own outgoing message; owner status and archive access do not widen recall permission. The daemon makes the final eligibility decision. The account token requires `read` and `send` permission. Normal OpenClaw tool policy can disable `wechat_recall`.
|
|
80
|
+
|
|
81
|
+
An exact recalled placeholder may lose its original sender attribution in the official profile. Repeating the tool with that placeholder inspects its retained recalled state through the daemon and cannot start another native recall; the result labels this `action: "inspect_recalled"`.
|
|
82
|
+
|
|
83
|
+
Every target gets a stable idempotency key and a durable operation. Only an exact successful receipt reports `recalled` or `already_recalled`. Rejections, `pending` and `needs_review` remain explicit. A lost response or cancellation does not cause another automatic POST or cancel the daemon's action. Retain the reported operation ID and key for inspection; do not submit a replacement action to resolve uncertainty.
|
|
84
|
+
|
|
85
|
+
Native text, image, file, video and voice delivery results return actual stored message IDs after account/thread/server-identity verification. `meta.messageIds` preserves each verified receipt for split voice notes, alongside the durable send/job ID. Accepted media jobs may publish their stored receipts slightly later; the adapter inspects the same job for up to ten seconds and requires every accepted voice chunk's receipt. If stored receipts remain unavailable, the result leaves `messageId` empty and reports `receiptState: "needs_review"` with `retryable: false`; acceptance is not a reason to resend. Failed, partial and uncertain jobs do not enter that receipt wait.
|
|
86
|
+
|
|
87
|
+
Incoming `message.recalled` events are consumed independently of slow media and model work, including recalls of own or unmentioned messages. The consumer persists the event cursor together with a tombstone, removes recalled body/quote content and attachment references from its custody records, and invalidates pending model proofs. Tombstones survive restart and suppress a late original. Attachment retrieval, transcription, model dispatch and later automatic reply delivery recheck the selected messages so late work cannot reinsert recalled input. A quote's unrelated comment remains available after its recalled original is removed.
|
|
88
|
+
|
|
89
|
+
Received quotes use the parsed embedded content delivered by WeChat's server protocol and included in the normal message response's `quote` field. Text and link details render immediately; image metadata can retrieve verified bytes under the reply's own message ID. Other quoted media keeps the current comment and an unavailable attachment status. Local recall suppression and quoted-author admission still apply, including in history tools. A stored original never replaces the embedded excerpt; quote display needs no separate quote endpoint.
|
|
90
|
+
|
|
91
|
+
If a source-local message ID later names a different exact thread/server target, the consumer admits that new message with a separate host turn and reply key. Completion callbacks, media results and read receipts captured for the old target cannot overwrite the new custody record.
|
|
92
|
+
|
|
93
|
+
Stored-history tools return a recalled placeholder; media tools return terminal `status: "recalled"`, `reason: "message_recalled"`, `retryable: false` without attachment paths or image blocks. Recall does not erase an already submitted model input, an existing OpenClaw transcript, a completed action, or attachment bytes retained by OpenClaw's storage policy. An affected in-flight turn is held for review and its later automatic reply is suppressed; the plugin does not claim retroactive transcript correction.
|
|
94
|
+
|
|
95
|
+
Old media handles whose stored source changed, or whose source identity cannot be verified, return terminal `unavailable` with `media_source_changed` or `media_identity_unavailable`. They expose no cached path and are not retried automatically. Fresh stored-message discovery can select the intended current message and its bound cached asset without resending a WeChat message.
|
|
96
|
+
|
|
97
|
+
`node scripts/native-recall-model-smoke.mjs` builds the actual plugin and runs the pinned Gateway against synthetic native HTTP/SSE and a local provider. It checks registered tool discovery and exact-target execution, stable repeated keys, another thread's rejection, recall intake while provider/media requests are blocked, late-output suppression, out-of-order recall custody and one dispatch for a new exact occupant of a reused source ID. It makes no real account or native protocol exchange.
|
|
98
|
+
|
|
69
99
|
## Stored-history tools
|
|
70
100
|
|
|
71
101
|
The agent can look beyond the recent inbound buffer using the selected native account's local profile:
|
|
@@ -137,12 +167,42 @@ Run `node scripts/native-model-smoke.mjs` and `node scripts/native-media-model-s
|
|
|
137
167
|
|
|
138
168
|
Native text/media sends retain daemon intent/job identity and caller idempotency. Text waits for accepted submission; media jobs preserve partial and uncertain outcomes rather than resending. Ordinary audio remains a file; only explicit `audioAsVoice` requests independently encoded voice. Sender/group/mention gates run before retrieval/transcription. Verified voice may use the configured OpenClaw transcription runtime after admission. Native QR login uses a durable daemon operation and authenticated PNG retrieval. Logout commits local inhibition before at most one authenticated native logout, reporting the remote outcome separately; saved-device revocation remains unverified. Explicitly confirmed forgetting removes local auth while retaining history; disconnect retains reusable trust.
|
|
139
169
|
|
|
170
|
+
## Outgoing attachment sizes
|
|
171
|
+
|
|
172
|
+
`channels.agent-wechat.mediaMaxMb` limits both incoming retained attachments and
|
|
173
|
+
outgoing sources in MiB. Outgoing sources must also fit the selected kind's
|
|
174
|
+
native limit: ordinary files have a 512 MiB ceiling (536,870,912 bytes);
|
|
175
|
+
video sources allow 50 MiB; images and voice retain 26,214,383 bytes. Native File Transfer PDFs passed
|
|
176
|
+
acceptance, recipient opening and cold byte verification at 32 MiB and 50 MiB.
|
|
177
|
+
Full-client 512 MiB send validation remains pending. The 50 MiB file also passed
|
|
178
|
+
real OpenClaw storage; see the [native capability checklist](../native-client-rust/FEATURES.md).
|
|
179
|
+
Raising `mediaMaxMb` cannot extend the kind-specific limit. Kind selection occurs
|
|
180
|
+
before staging, using the local extension or HTTP content type. Ordinary audio
|
|
181
|
+
is a file unless `audioAsVoice` selects voice.
|
|
182
|
+
|
|
183
|
+
For ordinary files above 26,214,383 bytes, the adapter polls the same submitted
|
|
184
|
+
job for up to an hour, allowing upload and exact readback before final
|
|
185
|
+
message submission. A timeout or status-poll failure preserves the job ID and idempotency key and never
|
|
186
|
+
automatically sends another copy. Unsupported cache-hit responses or uncertain
|
|
187
|
+
reservations/submissions require inspection. See [Send attachments](https://thisnick.github.io/agent-wechat/use/media/)
|
|
188
|
+
for CLI, HTTP API and SDK examples.
|
|
189
|
+
|
|
190
|
+
Video sends default to a prepared H.264/AAC playback copy and thumbnail. For one
|
|
191
|
+
video attachment, the regular message tool accepts
|
|
192
|
+
`channelData: { "agent-wechat": { "videoQuality": "original" } }` to include the
|
|
193
|
+
unchanged source too; `"normal"` selects playback only. Set `mediaMaxMb` to allow
|
|
194
|
+
the source size. `forceDocument` (or host alias `asDocument`) sends the media as
|
|
195
|
+
an ordinary file and cannot be combined with video quality. Video jobs poll the
|
|
196
|
+
same job for up to an hour. See the native capability checklist for separate
|
|
197
|
+
server, recipient and local-writeback validation.
|
|
198
|
+
|
|
199
|
+
|
|
140
200
|
## Optional Gateway facade
|
|
141
201
|
|
|
142
202
|
Set `native.gatewayFacade: {"enabled": true}` to register `/plugins/agent-wechat/native` on the Gateway. The default is disabled. A custom prefix must remain namespaced under `/plugins/...`; changing daemon configuration requires a Gateway reload.
|
|
143
203
|
|
|
144
204
|
The actual Gateway authenticates requests before the proxy runs. Its bearer is never forwarded to the daemon; the plugin uses its private daemon token reference. Routes are restricted to the configured account, with no daemon-wide token/account administration. Binary bodies, byte ranges, status codes and SSE are preserved within explicit size limits. Client disconnect/plugin shutdown closes upstream streaming work without cancelling durable sends.
|
|
145
205
|
|
|
146
|
-
`scripts/native-gateway-smoke.mjs` tests the built plugin on an isolated OpenClaw **2026.10.
|
|
206
|
+
`scripts/native-gateway-smoke.mjs` tests the built plugin on an isolated OpenClaw **2026.10.7** Gateway with synthetic loopback data: auth rejection, separate credentials, account boundaries, Range206, SSE and cancellation. This transport test is separate from the local model-boundary test above; neither uses an external model provider or a real WeChat account.
|
|
147
207
|
|
|
148
208
|
See [native deployment examples](../../deploy/native/README.md) and [native CLI installation](../cli/README.md).
|