# @agent-wechat/agent-wechat 中文文档

规范地址：https://npmcn.com/package/%40agent-wechat/agent-wechat/

版本：1\.5\.1
npm 元数据更新时间：2026-11-05T02:54:08.740Z
中文译文更新时间：2026-11-06T03:38:54.377Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agent-wechat/agent-wechat
原文对照：https://npmcn.com/package/%40agent-wechat/agent-wechat/?lang=original
项目主页：https://github.com/thisnick/agent-wechat#readme
源码仓库：https://github.com/thisnick/agent-wechat

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：456 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2026-08-31T14:57:11.334Z
- 最新版本发布：2026-11-05T02:54:08.313Z
- 近 30 天下载量：5443（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 51 个）

## 中文简介

插件使用独立的本地守护进程 。 外部模式通过端点/ 连接到独立操作的守护进程, 包括本地服务器容器; Gateway 既不需要 `wx` 或多克的工具。 管理模式启动本地守护进程

## 安装

```sh
npm install @agent-wechat/agent-wechat
```

也可以使用：`pnpm add @agent-wechat/agent-wechat`、`yarn add @agent-wechat/agent-wechat`、`bun add @agent-wechat/agent-wechat`

## README

# OpenClaw WeChat 频道

插件使用独立的本地守护进程 。 外部模式通过端点/ 连接到独立操作的守护进程, 包括本地服务器容器; Gateway 既不需要 `wx` 或多克的工具。 管理模式启动自有本地守护进程并需要单独安装 `wx`。插件安装/启动从不下载或修复二进制。 旧的容器API配置需要明确的迁移.

发布后,将原生β与 `openclaw plugins install @agent-wechat/agent-wechat@beta` 或贴上它的确切版本。 马厩 `latest` 频道继续在β系列中选择旧的容器插件.

## 本地外部模式

配置插件默认值 `plugins.entries.agent-wechat.config` (或同为 `native` 频道中的配置 :

```json
{
  "native": {
    "mode": "external",
    "accountId": "example",
    "endpoint": "http://127.0.0.1:6174",
    "token": { "source": "env", "provider": "default", "id": "AGENT_WECHAT_TOKEN" },
    "consumerStateDir": "/private/openclaw-native-consumer",
    "readPolicy": "on_inbound"
  }
}
```

对外服务仍然独立自主。 插件停止关闭其流并永不停止/ 日志退出守护进程或取消它的发送 。 远程端点需要经过验证的HTTPS或加密隧道以回转结束. 设定 `AGENT_WECHAT_TOKEN` 在Gateway进程环境中,或使用已配置的 OpenClaw 秘密提供者。 插件解析 `native.token` 通过被钉住的OpenClaw SDK; `native.tokenFile` 删除。 Tokens 包含 32–1024 可打印的 ASCII 字节,没有空格 。 明确未解决的引用失败启动而不返回到另一个符号 。 API 令牌需要读取/ 介质/ send/ login 对于所选择的账户, 并且只有在启用自动全程读取标记时, 才会加上读取状态; 不要只授予管理员来运行插件 。 正常发件人/DM/组/mention政策仍在 `channels.agent-wechat`页:1.

## 登录工具

`wechat_login` 可以通过 OpenClaw 工具策略配置代理,包括 WeChat 下线时从其他渠道。 使用 `{"action":"status"}` 检查账户, `{"action":"start"}` 开始或恢复登录并显示返回的 QR 图像,然后 `{"action":"wait","timeoutMs":30000}` 检查扫描/批准完成情况。 重复开始再使用待处理操作. 对于新的行动, `force: true` 使用QR 而不是保存信任。 等候者被限制,并报告行动ID和状态. 取消一个工具调用会让所提交的登录操作可用于以后的调用.

该工具也接受 `disconnect` (保留了信任), `logout` (可持久本地登录)和 `forget` 与 `confirm: true` (删除本地认证,保留历史). 它仍然绑定在已配置的守护进程/ 账户上 。 应用 OpenClaw 工具允许/ 否定策略来控制哪些代理可以管理登录 。 该工具可直接调用,因此守护进程PNG作为图像内容到达模型.

## 本地管理模式

```json
{
  "native": {
    "mode": "managed",
    "accountId": "example",
    "executable": "/opt/agent-wechat/bin/wx",
    "listen": "127.0.0.1:6174",
    "dataDir": "/private/native-store",
    "token": { "source": "env", "provider": "default", "id": "AGENT_WECHAT_TOKEN" },
    "consumerStateDir": "/private/openclaw-native-consumer",
    "readPolicy": "never"
  }
}
```

提供本地可执行和账户登记。 选择 `executable` 决定 `wx` 一次来自绝对信任的 PATH 条目。 该插件通过直接选择已经安装的校验和验证的ELF有效载荷,支持被测试的npm发射装置布局. 它从不引用安装器或外壳. 拒绝未知的包装/旧容器的共性指数。 管理起动拒绝一个被占用的端口,并且需要认证的准备状态匹配拥有的孩子PID,存储路径,服务器身份和进程生成;它从不采用或终止另一个进程. 停止向自己的孩子发出优雅的终止 并有限度的升级。 报告出现出乎意料的儿童/流故障;在此增量中没有执行自动程序崩溃重新启动.

被管理的启动通过一个私有的 stdin 管道发送解析的令牌; 它不创建令牌文件,也不将令牌放入参数或守护进程环境中. 管理 `serverConfig` 必须省略 `tokenFile`。重新装入/重新启动网关,以改变证书或秘密提供者的配置.

保留 `dataDir` 财务报告和审定财务报表 `consumerStateDir` 以明显的恒有山岳盟誓, 守护进程拥有官方格式的剖面图/侧车数据;消费者目录持有私人收录/dedultation/model-handoff/读取收受绑定在服务器和账户身份. 可执行升级也不去除. 一个配置了 OpenClaw 账户映射到此增量中一个选中的本地守护进程账户, 而守护进程本身则支持独立的账户槽 .

## 通话

呼叫默认已禁用 。 通讯 许可列表不允许调用 : `calls.inboundAllowFrom`, (中文(简体) ), `calls.outboundAllowTo` 财务报告和审定财务报表 `calls.outboundToolAllowFrom` 授予单独的许可。 守护进程 API 令牌 也需要账户的 `calls` 范围。 这个 适配器支持被绑定的主机的 OpenAI 响应音频桥并需要提供者准备 在打电话之前 代理咨询默认关闭; 安全只读 另有要求 `allowConsultSessionPersistence: true` 因为 OpenClaw可以存储其单独的每个呼叫代理会话. 原生后端还在 仅限于过期的孤立测试;综合电话验证不完整. 见 [电话指南](https://thisnick.github.io/agent-wechat/reference/calls/) 用于连接和限制.

## 本地信件生命周期和验证限制

适配器使用无记名头和小数字符串的日记光标来消耗账户范围SSE. 它在识别光标之前坚持保管;确认独立于未读状态。 只有明确的生活,进入,承诺的资源才能进入模式. 支持的图像,短语音,视频,文件和合格贴纸通过有界媒体检索和散列验证进入OpenClaw管理的存储. 等待的媒体在没有模型发送或阅读收据的情况下保留监护权。 过期/ 不支持附件保留了明确的状态; 原始 XML 永远不会成为附件 。 在同步批发前的补进/进口/提取,未知的出处和发送的消息不会成为自动的模型输入. 分组录入使用结构化准确的自觉事实;未知元数据或显示 `@names` 从来没有满足一个提到门。 联系人和团体使用各自独立的目录.

每一个已准备好的附件都会在信件正文中提供其原有的 OpenClaw 管理路径和 `Attachments` 元数据,包括图像。 括号中的文件引用环绕路径, 如 `[Image file: <path>]` 或者说 `[Local file: <path>]`,因此OpenClaw在扫描快速文本时不会自动加载正本或带有图像扩展名的文件. 可能占用单独准备的图像预览 `MediaPath` 而原始文件仍然可以通过自己的路径访问。 文件,语音和视频保留了明确的本地引用;可用的路径并不声称模型分析了文件.

在需要注明的组中,发送人接收的未提及电文作为上下文保留,没有检索、抄录、模式转接或读取通知。 在再次检查当前发件人政策后, 下一个被接受的非命令消息包含此上下文 . `messages.groupChat.historyLimit` 控制每组窗口(默认为50个,最大为200个;零禁用)。 消费者商店总共保留了最多1 000个缓冲组信息。 上下文保存在重新启动的网关中 。 发送时,所选上下文在解剖学上与持久的转弯记录一起被消耗,因此一个不确定的转弯不会自动再次提供. 原文提及的事实保持不变;历史记录与触发信息分开.

团体追赶最多用三个工人来取回媒体,保留每一个经过核实的原始路径,只选择最新准备好的图像为视觉准备的代表. 尚未提交或尚未提交的历史附件仍然具有明确的地位,并不阻碍目前提及的内容。 触发性扣押在尚未解决时,继续维持自己的调度。 语音转录只在录入和激活后运行. 命令不会排出缓冲上下文 .

默认, `readPolicy: "on_inbound"` 标记在其发送信件被长期存储、通过发送者/组/磁盘检查并完成正常的OpenClaw入境处理后读取的整条线索。 已建成的指令在没有调用模型时也符合条件. 这项政策不检查模型投入或要求 `hooks.allowConversationAccess`。被忽略的消息,等待媒体和处理失败不会启动读取。 阅读整合处理的手段;它不声称模型分析了附件.

一个全行读也清除了该线程中早先未读到的信息,包括模型没有收到的信息. 守护进程会冻结最新的本地信件边界,检查预期的版本,更新本地未读状态并提交一个本地读状态通知. 仅凭服务器接受并不能证明手机徽章已经改变. 通知答复丢失 `needs_review` ,从不自动重新提交。 等待读取从一个Gateway重启和重试中存活下来,独立于模型执行或新的SSE流量. `readPolicy: "never"` 禁用本地和远程标记,包括先前排队的读取。 未完成发送时的崩溃保留 `needs_review`;插件不会自动重复模型转折或不确定的出发.

可选 `readPolicy: "on_model_dispatch"` 而是需要确认型号的交接 打开Claw **第2026.10.9号决定** 缺少 `onPreparedAgentRunStart`,因此其所发布的公用悬钩提供了有界相容性路径. 在发送前,适配器会坚持一个不可改变的表单,将准确的新消息ID/版本/内容散列,政策散列,源头和提供的资产散列,以及上下文角色绑定起来. 文本需要准确的当前输入和主机创建的信件/账户/会话事实加匹配 `model_call_started`媒体在等待同样的跑步 `agent_end` 快照和源头转动身份. 图像字节/MIME/长度必须与所提供被冻结的表示值相匹配;文件/视频/语音参考值必须出现在准确的当前正文中。 仅凭图像计数,模型选择和回复发送无法确认模型交接. 未知、遗漏、重写、合并或模棱两可的投入仍未证实。 主机/提供者历史格式可以阻止确认,即使答复已经送达;使用 `on_inbound` 对于普通的机器人读取行为.

模式手动兼容路径需要操作员的明确主机权限, `plugins.entries.agent-wechat.hooks.allowConversationAccess: true`它只观察该适配器发布的ID,而从未允许这种许可。 没有赠款,或者在一个没有支持的东道主身上 `on_model_dispatch` 政策未读信息并提交状况报告 `handoffUnconfirmed`老年人 `onAgentRunStart` 还报告了直接工具和早期生命周期阶段,从未被用作证据。 访问和提及闸门仍然在模式发送之前;被拒绝的消息本身不会触发读取.

超过主机的受限表示,或需要转换的格式,接收一个单独存储的JPEG仍然使用公共SDK图像处理器预览. 原作保持完好无损;两种散列均被收录并被模型输入标记为预览. 所制成的图像符合5 MiB 和每侧最多1200像素(或一个更小的配置限制). 文件和视频可以作为本地的参考材料提供;这并不意味着其内容得到了分析。 语音保留其已核实的文件并包括已配置的转录输出或明确的不可用状态. 占位符不确认模式在 `on_model_dispatch`; 默认 `on_inbound` 可以在成功处理已明确过期/ 不支持状态后标记线索.

## 信件回顾

`wechat_recall` 回顾当前对话中配置的 WeChat 账户发送的消息 。 过 `{"messageId":"<opaque stored ID>","serverId":"<exact decimal server ID>"}` 使用同一经核实的寄件收据中的两种值,或 `wechat_history` 输入。 服务器ID保留了字符串,包括大于JavaScript安全整数范围的值. 本地不透明的ID可以被再用,因此拒绝使用一个具有不同服务器ID的旧引用. 发送/工作/操作 ID不能替换存储的消息ID .

该工具使用OpenClaw的可信任账户,谈话和请求者上下文. 它不接受账户或线程选择器,重新检查普通请求者政策,并且需要自发发送的消息;所有者状态和归档访问不会扩大召回权限. 守护进程做出最终的资格决定. 帐号要求 `read` 财务报告和审定财务报表 `send` 允许。 普通 OpenClaw 工具策略可以禁用 `wechat_recall`。 。 。 .

确切的被召回的占位符可能会失去官方简介中其原始发件人的归属. 用该占位符重复工具会通过守护进程检查其保留被召回的状态,并且无法启动另一个本地召回;结果会标注此值 `action: "inspect_recalled"`。 。 。 .

每个目标都有一个稳定的特能钥匙和一个持久的操作. 只有准确的收货报告 `recalled` 或者说 `already_recalled`拒绝, `pending` 财务报告和审定财务报表 `needs_review` 继续明确。 丢失的响应或取消不会导致另一个自动 POST 或取消守护进程的行为. 保留报告的行动ID和检查钥匙;不提交解决不确定性的替换行动.

原生文本,图像,文件,视频和语音传送结果在账户/线程/服务器-身份验证后返回实际存储的信息ID. `meta.messageIds` 保存每张已核实的分声符收据,同时保存持久发送/工作ID。 被接受的媒体工作可能会稍晚一点公布其存储的收据;适配器检查同一工作长达10秒,并需要每个被接受的语音块的收据. 如果存储的收据仍未提供,则结果为 `messageId` 空和报告 `receiptState: "needs_review"` 与 `retryable: false`;接受不是重新发送的理由。 失败、 部分和不确定的工作不会输入收据等待 .

来了 `message.recalled` 事件独立于缓慢的媒体和模型工作,包括回顾自己或未提及的信息。 消费者坚持将事件光标和墓碑放在一起,从保管记录中删除被召回的体/引号内容和附件参考资料,并宣布有待模型证明无效。 墓碑幸存了重启并压制了后期原作. 附件检索、抄录、模型发送和后来的自动回复发送重新检查所选信件,因此工作迟到,无法重新插入回想输入。 引文中的不相干的评论在被取出原作后仍可查取.

收到引文时使用 WeChat 服务器协议交付的解析后嵌入内容,并包含在普通信件响应中 `quote` 字段。 文本和链接细节立即渲染;图像元数据可以在回复自己的消息ID下检索已校验的字节. 其他被引用的媒体保留当前评论和无法获取附件状态 。 地方召回的压制和引文作者的承认仍然适用,包括历史工具。 被存储的正本从不取代嵌入式摘录;引文显示不需要单独的引文结尾.

如果一个源-本地消息ID后来给一个不同的精确线程/服务器目标取名,消费者会承认该新消息带有单独的主机转会并回复密钥. 完成回调,媒体结果和读取为旧目标捕获的收据不能覆盖新的保管记录.

存储历史工具返回一个召回的占位符;媒体工具返回终端 `status: "recalled"`, (中文(简体) ), `reason: "message_recalled"`, (中文(简体) ), `retryable: false` 没有附件路径或图像块。 召回不会抹去已经提交的模型输入,现有的OpenClaw记录,一个已完成的动作,或者被OpenClaw存储策略所保留的附加字节. 受影响的飞行中转弯举行审查,其随后的自动答复被压制;插件不要求追溯记录更正.

存储源已改变或源身份无法验证的旧媒体控件返回终端 `unavailable` 与 `media_source_changed` 或者说 `media_identity_unavailable`。它们不会显示缓存路径,也不会自动重试。 新鲜存储消息的发现可以在不重新发送WeChat消息的情况下选择预定的当前消息及其绑定的缓存资产.

`node scripts/native-recall-model-smoke.mjs` 构建实际的插件,并运行被绑定的Gateway来对抗合成本地HTTP/SSE和一个本地供应商. 它检查注册工具的发现和精确目标执行,稳定的重复键,另一个线程的拒绝,在提供者/媒体请求被阻断时召回摄入,延迟输出压制,出令召回保管,以及一次发送新的精确占用再利用源ID. 它没有真实的账户或本地协议交换.

## 储存的历史工具

代理可以使用选中的本地账户的本地配置来超越最近的入境缓冲:

| 工具 | 投入(`?` 表示可选) | 产出 |
| --- | --- | --- |
| `wechat_history` | `{ limit?, cursor? }` | 存储信件, 最新的第一, 与 `nextCursor`, (中文(简体) ), `sourceGeneration` 财务报告和审定财务报表 `coverage` |
| `wechat_search` | `{ query, limit?, cursor? }` | 相同的页面形状, 通过大小写不敏感子字符串过滤 |
| `wechat_message` | `{ messageId }` | 一个存储的消息 |
| `wechat_media` | `{ messageId, download?, quality? }` | 媒体状态、可选校验的文件路径和图像内容 |

存储的信件包括 `id`, (中文(简体) ), `threadId`,无效 `serverId`, (中文(简体) ), `senderId`, (中文(简体) ), `direction` 财务报告和审定财务报表 `createdAt`数字 `type`边框 `body`,以及 `bodyTruncated`。其可选性 `attachment` 描述符包含 `kind`, (中文(简体) ), `messageId` 财务报告和审定财务报表 `retrievalTool: "wechat_media"`。信件ID和服务器ID仍为字符串;使用不透明 `id` 精确的检索和媒体检索.

媒体结果包括: `messageId`, (中文(简体) ), `threadId`, (中文(简体) ), `status` 财务报告和审定财务报表 `retryable`,可选 `attachment`实际数 `variant`, (中文(简体) ), `jobId`, (中文(简体) ), `reason` 显示 `body`已准备好的附件 `kind`, (中文(简体) ), `filename`,经核实的本地 `path` 财务报告和审定财务报表 `mime`; 图像质量可能是 `full`, (中文(简体) ), `standard` 或者说 `thumbnail`。无法获取的结果绝不是本地路径。 OpenClaw 将结构化输出包成 `details` 文本 `content`; 现成图像额外提供了图像内容块.

例如,代理人可以打电话 `wechat_search` 与 `{"query":"project notes"}` 在当前的对话中。 这四个默认工具仅限于当前由可信任的OpenClaw上下文衍生的WeChat账户和线程. 拥有归档访问权限的所有人和代理在使用默认工具时也有同样的限制. 默认工具不会接受线索/账户选择器,插件会拒绝来自另一个对话或账户的信息或资产. 重新检查请求者和历史发送者的政策。 缺少或相冲突的可信任的对话上下文隐藏了默认工具;webchat和其他频道不能使用.

历史/搜索返回不透明字符串消息 ID、 限定文本预览、 覆盖元数据以及 `nextCursor`。用相同的工具、查询和线程将光标递回;页数限制为1-50(默认为20)。 搜索查询仅限于256个UTF-8字节. 长信息体被标记为短发. 发件人过滤的页面可能为空并仍有续作. 搜索封面为本地存储历史,不获取缺失的远程历史,也不保留官方的FTS索引. 媒体消息收到类型/状态描述;这些工具不会返回原始传输 XML 或下载附件. 历史,搜索和确切信息查询只读. 其附件描述名称 `wechat_media` 和没有自动检索媒体的准确消息ID。 这些工具都没有标记已读的对话,发送消息或修改入境的消费者光标. 查找需要选中账户的 API `read` 范围,并且仍受OpenClaw工具政策的约束。 使用 OpenClaw 的紧凑工具目录,代理商会通过历史/搜索/消息搜索 `tool_search` 并引用返回的工具 `tool_call`。媒体工具可直接调用为 `wechat_media`:被绑定主机的通用包装将嵌入的图像块序列化为JSON文本,而直接引用则保留图像内容用于视觉.

`wechat_media` 接受 `{"messageId":"<returned opaque ID>"}`。它可以在访问资产之前验证信件/线程/发送录入,首先使用缓存字节,检查身份、散列和大小,并将已核实的字节保存到OpenClaw管理的媒体商店。 文件,视频和语音返回本地路径;图像还返回一个已设定的预览,作为视觉的图像内容. 此检索本身不转录语音或分析文件/视频. 缓存的字节在CDN过期后仍然可用.

缺失的媒体默认请求持久守护进程传输,有2秒的边界等待. 待定的结果包括 `jobId` 当知道且没有声称的本地路径时; 稍后用相同的消息ID调用同一个工具来检查。 守护进程拥有并复制传输, 因此取消一个工具引用不会取消已提交的工作 。 使用 `download: false` 仅限缓存媒体. `quality` 默认为 `best` (最佳缓存图像、正常视频或解码声音) `original`, (中文(简体) ), `standard`, (中文(简体) ), `thumbnail`, (中文(简体) ), `normal` 财务报告和审定财务报表 `encoded` 变体很严格,可能无法使用。 结果报告了实际变异和明确的待决、过期、无支持、无结果或规模太大的情况。 永不自动重试 `retryable: false` 或确认过期。 媒体工具需要账户范围 API `read` 财务报告和审定财务报表 `media` 允许,包括下载请求。 Raw XML, 已签名的运输 URL 和密钥从未返回 .

`node scripts/native-history-model-smoke.mjs` 使用本地账户/媒体/模式定型来练习被绑定的Gateway:持久组内环境、原始文件路径、一个带有经核实的散列的预览、一个作为文件发送的PNG仍是一个参考、直接图像传送、实际工具发现、两个被标注的搜索呼叫、在媒体访问之前拒绝另一个线索附件、一个请求的图像下载,其准确图像字节到达视觉,以及一个缓存文件路径到达提供者。 CI对Linux两种架构进行此检查.

当资产元数据识别出一个已存在的下载任务时,会检索那些缩小任务范围而不是提交另一个传输的民调. 终端任务的理由和可重试性被保留,包括在缓存-只保存模式中;此工具不会自动重试失败的任务. 仅拒绝服务不归为终止服务.

### 特权存档工具

在已配置的本地 WeChat 账户中, 有五个可选工具在每一个线索上读取 :

| 工具 | 投入(`?` 表示可选) | 产出 |
| --- | --- | --- |
| `wechat_archive_threads` | `{ query?, limit?, cursor? }` | 线索页面 : `id`, (中文(简体) ), `peerId`, (中文(简体) ), `kind`, (中文(简体) ), `displayName`, (中文(简体) ), `unreadCount`,加上标注和覆盖 |
| `wechat_archive_search` | `{ query, threadId?, limit?, cursor? }` | 横跨所有线索的信件页; 可选 `threadId` 缩小范围 |
| `wechat_archive_history` | `{ threadId, limit?, cursor? }` | 任何选中线索的首发信件页面 |
| `wechat_archive_message` | `{ messageId }` | 从任何线索发出一条信息 |
| `wechat_archive_media` | `{ messageId, download?, quality? }` | 从任何线索中验证附件状态/路径和图像内容 |

信件/页面/媒体输出形状,界限和下载行为与上面的默认工具相匹配. 归档附件描述符名称 `wechat_archive_media` 作为他们的检索工具。 线索查询匹配本地存储的ID并显示名称. 搜索使用守护进程全账户 `GET /v1/accounts/{accountId}/messages?query=...` 端点;其不透明的光标绑定了账户,查询和线程选择,并保留了本地编辑,删除和新来者的会籍/顺序. 搜索以有限快照能力读取本地配置文件; 它不会回填远程历史 。 一个没有这个结束点的更古老的守护进程必须升级,以便全账户搜索.

在 OpenClaw 配置访问 `~/.openclaw/openclaw.json`,合并到您现有的指定代理条目中:

```json
{
  "agents": {
    "ownership": "explicit",
    "entries": {
      "main": {
        "tools": { "alsoAllow": ["wechat_archive_*"] }
      },
      "group-bot": {
        "tools": { "deny": ["wechat_archive_*"] }
      }
    }
  }
}
```

OpenClaw针对工具执行和目录发现执行这些政策. 这个 `main` 名字没有隐含的特权。 使用单个工具名授予子集 。 如果一个特工已经 `tools.allow`,将归档名称添加到该列表中,而不是合并 `allow` 财务报告和审定财务报表 `alsoAllow`全球拒绝仍然胜过每个代理人的许可。 选择工具没有选择政策,但 `profile: "full"`, (中文(简体) ), `*`, (中文(简体) ), `group:plugins`,或整个允许 `agent-wechat` 插件还选中它们; 对于只保留当前线程访问的代理商, 添加一个明确的每代理拒绝 .

没有插件权限列表,所有者例外或归档发送/线程过滤器. 主机授权的存档引用可以从任何频道读取所配置的账户,包括分组引用. 使用 OpenClaw 的发件人政策或路由组流量到一个没有归档工具的代理, 当这些运行应该有更窄的访问权限时. 归档工具仍然绑定在所配置的账户上,并验证信件/资产的身份,散列和大小. 他们从来不接受任意的文件路径或其他账户选择器. 正常的账户/托盘范围检查和援引取消围栏仍然适用.

历史/搜索/信息/线程读取从不发送信件,读取标记线程或更改输入光标. Archive 媒体可以提交相同的受约束,被解码的下载任务 `wechat_media`;它仍然可以直接调用,所以实际的图像块到达了视觉.

运行 `node scripts/native-archive-tools-smoke.mjs` 以三个单独的路由代理来检查被封存的网关:不提供可选工具的赠款,有明确拒绝的完整概况,以及存档赠款。 它检查发现和被猜出的名称引用拒绝,跨行搜索 pagination,其他发件人历史/媒体,未变的默认工具范围,在提供者输入中核实的图像字节和一个被缓存的文件路径. 本测试中的所有消息,账户数据和模型响应都是合成的. CI在Linux x64和ARM64上运行.

运行 `node scripts/native-model-smoke.mjs` 财务报告和审定财务报表 `node scripts/native-media-model-smoke.mjs` 在安装工作空间依赖后。 他们使用实际被钉住的Gateway,一个本地模型和合成守护进程/文件. 检查覆盖默认输入读取没有对话权限,命令没有模式调用,当前提供商输入,图像散列和预览准备,参考/特兰描述发送,全程读取请求,失联/重开恢复,重复预防,只文本模式上省略图像,明确模式接取权限,永不读取政策和组路由行为. Transcription使用真实的SDK,并明确配置了本地定型CLI;它不测试语音识别精度. 同时期文本投入被序列化为不同的模型转换;合并输入拒绝对明确的模型政策有单位覆盖。 这些检查确立了本地运行时间行为,而不是外部提供者接受,语义分析或消耗.

原生文字/媒体发送保留守护进程意图/工作身份和召唤者一能. 文本等待被接受的提交;媒体工作保留部分和不确定的结果,而不是再发行。 普通音频仍为文件; 只有明文 `audioAsVoice` 请求独立编码的声音。 发送者/ 组/ mention 门在检索/ 标记前运行 。 已验证的声音可能使用已配置的 OpenClaw 记录录入后的运行时间 。 原生QR登录使用持久守护进程操作并认证了PNG检索. 登出在最多一次经认证的本地登出之前会进行局部抑制,分别报告远程结果;被保存的设备撤销仍未核实。 明确确认遗忘在保留历史的同时删除本地认证; 断开保留可重复使用的信任 .

## 正在发送的附件大小

`channels.agent-wechat.mediaMaxMb` 限制收到的保留附件和 miB中输出源。输出源还必须符合所选类型 本地限制:普通文件有512个米B上限(536 870 912字节); 视频源允许50个米B;图像和语音保留了26,214,383字节. 本地文件传输 PDF 通过 在32个MiB和50个MiB进行接收、接收和冷字节核查. 全客户端 512 MiB 发送验证尚未确定. 50个 MiB 文件也通过 真实 OpenClaw 存储; 参见 [本地能力核对表](https://npmcn.com/package/%40agent-wechat/native-client-rust/FEATURES.md)。 。 。 . 抚养 `mediaMaxMb` 无法扩展特定种类的限制。 选中对象 中,使用本地扩展名或 HTTP 内容类型。 普通音频 是文件, 除非 `audioAsVoice` 选择语音.

对于超过26,214,383字节的普通文件,适配器的民调结果相同 任务最长1小时,允许在定稿前上传和准确回读 消息提交。 超时或状态出错保留了工作ID和一能键,永远不会 自动发送另一个副本。 不支持的缓存- hit 响应或不确定 保留/提交书需要检查。 见 [发送附件](https://thisnick.github.io/agent-wechat/use/media/) 用于CLI,HTTP API和SDK等示例.

视频向已准备好的H.264/AAC回放副本和缩略图发送默认. 一个 视频附件, 正则信件工具接受 `channelData: { "agent-wechat": { "videoQuality": "original" } }` 列入 来源不变; `"normal"` 只选择重播。 设定 `mediaMaxMb` 允许 来源大小. `forceDocument` (或主机别名) `asDocument`将媒体作为 普通文件,不能与视频质量结合。 视频工作调查 同一个工作最长一个小时。 参见本地能力清单 服务器、收件人和本地写回验证.

## 可选的网关外观

设定 `native.gatewayFacade: {"enabled": true}` 注册 `/plugins/agent-wechat/native` 在门口。 默认已禁用 。 自定义前缀必须保持名称空格 `/plugins/...`; 更改守护进程配置需要加载网关.

代理运行前, 实际的 Gateway 认证请求 。 它的负载者从未被转发到守护进程;插件使用它的私人守护进程符号引用. 路由仅限于已配置的账户,没有全守护进程代号/账户管理. 二进制体,字节范围,状态代码和SSE在明确尺寸限度内保留. 客户端断接/ 插件关机会关闭上游流线工作而不取消持久的发送 .

`scripts/native-gateway-smoke.mjs` 在孤立的 OpenClaw 上测试已建插件 **第2026.10.9号决定** 具有合成回回回回回数据的网关:认证拒绝,单独证书,账户边界,Range206,SSE和取消. 这种传输测试与上面的本地模型边界测试是分开的;既不使用外部模型提供者,也不使用真实的WeChat账户.

见 [本地部署实例](https://npmcn.com/package/deploy/native/README.md) 财务报告和审定财务报表 [本地 CLI 安装](https://npmcn.com/package/%40agent-wechat/cli/README.md)。 。 。 .

## 常见问题

### @agent-wechat/agent-wechat 是什么？

插件使用独立的本地守护进程 。 外部模式通过端点/ 连接到独立操作的守护进程, 包括本地服务器容器; Gateway 既不需要 wx 或多克的工具。 管理模式启动本地守护进程

### 如何安装 @agent-wechat/agent-wechat？

在项目目录运行 npm install @agent-wechat/agent-wechat，或使用 pnpm add / yarn add / bun add。

### @agent-wechat/agent-wechat 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agent-wechat\_\_agent-wechat 是否存在。

### @agent-wechat/agent-wechat 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agent-wechat/agent-wechat 可以商用吗？

@agent-wechat/agent-wechat 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-wechat/agent-wechat 的下载量有多少？

根据 npm 官方下载统计，@agent-wechat/agent-wechat 在 2026/10/05 – 2026/11/03 这 30 天内被下载 5,443 次，日均约 181 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agent-wechat/agent-wechat 还在维护吗？

最新版本 1\.5\.1 发布于 2026/11/05（1 天前）；至今共发布 51 个版本，其中过去 12 个月发布了 51 个；首次发布于 2026/08/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。