diff --git a/docs/zh-CN/channels/whatsapp.md b/docs/zh-CN/channels/whatsapp.md index d705df7ad..baae03208 100644 --- a/docs/zh-CN/channels/whatsapp.md +++ b/docs/zh-CN/channels/whatsapp.md @@ -1,44 +1,44 @@ --- read_when: - - 处理 WhatsApp/网页渠道行为或收件箱路由 + - 处理 WhatsApp/Web 渠道行为或收件箱路由 summary: WhatsApp 渠道支持、访问控制、投递行为和运维 title: WhatsApp x-i18n: - generated_at: "2026-05-02T07:07:26Z" + generated_at: "2026-05-02T20:13:33Z" model: gpt-5.5 provider: openai - source_hash: 0a38b2338056b55364577c72b643dac28ebb0006cdc61b480555e6079fb71573 + source_hash: bb8afa93f0470e0454cf59e19193d8c2f204db63b428a4de579e93f01bf3ee62 source_path: channels/whatsapp.md workflow: 16 --- -Status：通过 WhatsApp Web（Baileys）达到生产就绪状态。Gateway 网关拥有已关联的会话。 +Status: 通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关拥有已关联的会话。 ## 安装（按需） - 新手引导（`openclaw onboard`）和 `openclaw channels add --channel whatsapp` - 会在你首次选择 WhatsApp 插件时提示安装它。 + 会在你第一次选择 WhatsApp 插件时提示安装它。 - 当插件尚未存在时，`openclaw channels login --channel whatsapp` 也会提供安装流程。 - 开发渠道 + git checkout：默认使用本地插件路径。 -- Stable/Beta：当当前软件包已发布时，使用 npm 包 `@openclaw/whatsapp`。 +- Stable/Beta：在当前包已发布时使用 npm 包 `@openclaw/whatsapp`。 -仍可手动安装： +仍然可以手动安装： ```bash openclaw plugins install @openclaw/whatsapp ``` -如果 npm 报告 OpenClaw 所有的软件包已弃用或缺失，请使用当前打包的 OpenClaw 构建或本地 checkout，直到 npm 软件包发布节奏跟上。 +如果 npm 报告 OpenClaw 拥有的包已弃用或缺失，请使用当前打包的 OpenClaw 构建或本地 checkout，直到 npm 包发布列车跟上。 - 默认私信策略是对未知发送者进行配对。 + 默认私信策略是为未知发送者配对。 跨渠道诊断和修复手册。 - 完整的渠道配置模式和示例。 + 完整渠道配置模式和示例。 @@ -98,13 +98,13 @@ openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - 配对请求会在 1 小时后过期。待处理请求每个渠道最多 3 个。 + 配对请求会在 1 小时后过期。每个渠道最多保留 3 个待处理请求。 -OpenClaw 建议尽可能用单独号码运行 WhatsApp。（渠道元数据和设置流程针对该设置进行了优化，但也支持个人号码设置。） +OpenClaw 建议尽可能在单独的号码上运行 WhatsApp。（渠道元数据和设置流程针对该设置进行了优化，但也支持个人号码设置。） ## 部署模式 @@ -115,7 +115,7 @@ OpenClaw 建议尽可能用单独号码运行 WhatsApp。（渠道元数据和 - 为 OpenClaw 使用单独的 WhatsApp 身份 - 更清晰的私信允许列表和路由边界 - - 降低自聊混淆的概率 + - 降低自聊混淆的可能性 最小策略模式： @@ -133,7 +133,7 @@ OpenClaw 建议尽可能用单独号码运行 WhatsApp。（渠道元数据和 - 新手引导支持个人号码模式，并写入适合自聊的基线配置： + 新手引导支持个人号码模式，并写入适合自聊的基线： - `dmPolicy: "allowlist"` - `allowFrom` 包含你的个人号码 @@ -153,20 +153,21 @@ OpenClaw 建议尽可能用单独号码运行 WhatsApp。（渠道元数据和 ## 运行时模型 -- Gateway 网关拥有 WhatsApp socket 和重连循环。 -- 重连看门狗使用 WhatsApp Web 传输活动，而不仅是入站应用消息量，因此安静的已关联设备会话不会仅仅因为最近没人发送消息就被重启。如果传输帧持续到达但在看门狗窗口内没有处理任何应用消息，更长的应用静默上限仍会强制重连；对于最近活跃会话的临时重连，首次恢复窗口中的应用静默检查会使用正常消息超时。 -- Baileys socket 计时在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制打开握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。 -- 出站发送要求目标账号有活跃的 WhatsApp 监听器。 +- Gateway 网关拥有 WhatsApp 套接字和重连循环。 +- 重连看门狗使用 WhatsApp Web 传输活动，而不只是入站应用消息量，因此安静的已关联设备会话不会仅因为最近没人发送消息而重启。如果传输帧持续到达但在看门狗窗口内没有处理任何应用消息，较长的应用静默上限仍会强制重连；对于最近活跃会话的一次瞬时重连之后，该应用静默检查会在第一个恢复窗口使用正常消息超时。 +- Baileys 套接字时序在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制打开握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。 +- 出站发送要求目标账号存在活跃的 WhatsApp 监听器。 - Status 和广播聊天会被忽略（`@status`、`@broadcast`）。 -- 重连看门狗跟随 WhatsApp Web 传输活动，而不仅是入站应用消息量：当传输帧持续存在时，安静的已关联设备会话会保持在线，但传输停滞会在后续远端断开路径之前很早触发重连。 -- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会把私信折叠到智能体主会话）。 +- 重连看门狗跟随 WhatsApp Web 传输活动，而不只是入站应用消息量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在更晚的远端断开路径之前触发重连。 +- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。 - 群组会话是隔离的（`agent::whatsapp:group:`）。 -- WhatsApp Web 传输会遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道专用 WhatsApp 代理设置。 -- 启用 `messages.removeAckAfterReply` 时，OpenClaw 会在可见回复送达后清除 WhatsApp ack reaction。 +- WhatsApp 频道/Newsletters 可以使用其原生 `@newsletter` JID 作为显式出站目标。出站 newsletter 发送使用渠道会话元数据（`agent::whatsapp:channel:`），而不是私信会话语义。 +- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道特定的 WhatsApp 代理设置。 +- 启用 `messages.removeAckAfterReply` 时，OpenClaw 会在可见回复送达后清除 WhatsApp ack 反应。 -## 插件钩子与隐私 +## 插件钩子和隐私 -WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标识符、发送者姓名和会话关联字段。因此，除非你显式选择启用，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子载荷： +WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标识符、发送者名称和会话关联字段。因此，除非你显式选择加入，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子载荷： ```json5 { @@ -180,7 +181,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 } ``` -你可以将选择启用范围限定到一个账号： +你可以将选择加入限定到一个账号： ```json5 { @@ -198,7 +199,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 } ``` -只应对你信任可接收入站 WhatsApp 消息内容和标识符的插件启用此项。 +仅对你信任能接收入站 WhatsApp 消息内容和标识符的插件启用此项。 ## 访问控制和激活 @@ -213,14 +214,16 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 `allowFrom` 接受 E.164 风格号码（内部会规范化）。 - 多账号覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）优先于该账号的渠道级默认值。 + `allowFrom` 是私信发送者访问控制列表。它不会限制显式出站发送到 WhatsApp 群组 JID 或 `@newsletter` 频道 JID。 + + 多账号覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）会优先于该账号的渠道级默认值。 运行时行为细节： - - 配对会持久化到渠道 allow-store，并与配置的 `allowFrom` 合并 - - 定时自动化和 Heartbeat 接收者回退会使用显式投递目标或配置的 `allowFrom`；私信配对批准不会隐式成为 cron 或 Heartbeat 接收者 + - 配对会持久化在渠道允许存储中，并与配置的 `allowFrom` 合并 + - 定时自动化和 Heartbeat 收件人回退使用显式投递目标或配置的 `allowFrom`；私信配对批准不会隐式成为 cron 或 Heartbeat 收件人 - 如果未配置允许列表，则默认允许已关联的自身号码 - - OpenClaw 从不自动配对出站 `fromMe` 私信（你从已关联设备发送给自己的消息） + - OpenClaw 绝不会自动配对出站 `fromMe` 私信（你从已关联设备发送给自己的消息） @@ -228,36 +231,36 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 群组访问有两层： 1. **群组成员允许列表**（`channels.whatsapp.groups`） - - 如果省略 `groups`，所有群组都有资格 + - 如果省略 `groups`，所有群组都符合条件 - 如果存在 `groups`，它会作为群组允许列表（允许 `"*"`） 2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`） - `open`：绕过发送者允许列表 - `allowlist`：发送者必须匹配 `groupAllowFrom`（或 `*`） - - `disabled`：阻止所有群组入站消息 + - `disabled`：阻止所有群组入站 发送者允许列表回退： - 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom` - 发送者允许列表会在提及/回复激活之前评估 - 注意：如果完全不存在 `channels.whatsapp` 块，运行时群组策略回退是 `allowlist`（并记录警告日志），即使设置了 `channels.defaults.groupPolicy`。 + 注意：如果完全不存在 `channels.whatsapp` 块，即使设置了 `channels.defaults.groupPolicy`，运行时群组策略回退仍为 `allowlist`（并记录警告日志）。 - 群组回复默认要求提及。 + 默认情况下，群组回复需要提及。 提及检测包括： - - 显式 WhatsApp 提及机器人身份 + - 对机器人身份的显式 WhatsApp 提及 - 配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 已授权群组消息的入站语音备注转录 + - 授权群组消息的入站语音备注转录 - 隐式回复机器人检测（回复发送者匹配机器人身份） - 安全注意事项： + 安全说明： - - 引用/回复只满足提及门禁；它**不会**授予发送者授权 + - 引用/回复仅满足提及门控；它**不会**授予发送者授权 - 使用 `groupPolicy: "allowlist"` 时，即使非允许列表发送者回复了允许列表用户的消息，仍会被阻止 会话级激活命令： @@ -265,26 +268,26 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 - `/activation mention` - `/activation always` - `activation` 会更新会话状态（不是全局配置）。它受所有者门禁控制。 + `activation` 更新会话状态（不是全局配置）。它受所有者门控。 ## 个人号码和自聊行为 -当已关联的自身号码也存在于 `allowFrom` 中时，会激活 WhatsApp 自聊保护： +当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活： - 跳过自聊轮次的已读回执 -- 忽略可能会 ping 到你自己的 mention-JID 自动触发行为 +- 忽略否则会 ping 你自己的提及 JID 自动触发行为 - 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]` ## 消息规范化和上下文 - 传入的 WhatsApp 消息会被包装在共享入站信封中。 + 传入 WhatsApp 消息会包装在共享入站信封中。 - 如果存在引用回复，上下文会以这种形式追加： + 如果存在引用回复，上下文会按以下形式追加： ```text [Replying to id:] @@ -293,12 +296,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 ``` 可用时也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 - 当被引用回复目标是可下载媒体时，OpenClaw 会通过常规入站媒体存储保存它，并将其暴露为 `MediaPath`/`MediaType`，使智能体可以检查被引用的图片，而不是只能看到 ``。 + 当引用回复目标是可下载媒体时，OpenClaw 会通过正常入站媒体存储保存它，并将其作为 `MediaPath`/`MediaType` 暴露出来，以便智能体检查被引用的图片，而不只是看到 ``。 - 仅媒体入站消息会使用如下占位符进行规范化： + 仅媒体入站消息会使用如下占位符规范化： - `` - `` @@ -306,19 +309,19 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 - `` - `` - 当正文只有 `` 时，已授权群组语音备注会在提及门禁前转录，因此在语音备注中说出机器人提及可以触发回复。如果转录仍未提及机器人，转录会保留在待处理群组历史中，而不是保留原始占位符。 + 当正文仅为 `` 时，授权群组语音备注会在提及门控之前转录，因此在语音备注中说出机器人提及可以触发回复。如果转录文本仍未提及机器人，转录文本会保留在待处理群组历史中，而不是保留原始占位符。 - 位置正文使用简短坐标文本。位置标签/评论和联系人/vCard 详情会呈现为 fenced 不受信任元数据，而不是内联提示文本。 + 位置正文使用简洁的坐标文本。位置标签/评论和联系人/vCard 详情会渲染为 fenced 不受信任元数据，而不是内联提示文本。 - 对于群组，未处理消息可以被缓冲，并在机器人最终被触发时注入为上下文。 + 对于群组，未处理消息可以缓冲，并在机器人最终被触发时作为上下文注入。 - 默认限制：`50` - 配置：`channels.whatsapp.historyLimit` - 回退：`messages.groupChat.historyLimit` - - `0` 表示禁用 + - `0` 禁用 注入标记： @@ -328,7 +331,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 - 接受的入站 WhatsApp 消息默认启用已读回执。 + 默认会为接受的入站 WhatsApp 消息启用已读回执。 全局禁用： @@ -342,7 +345,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 } ``` - 按账号覆盖： + 每账号覆盖： ```json5 { @@ -358,12 +361,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 } ``` - 即使全局启用，自聊轮次也会跳过已读回执。 + 即使全局启用，给自己的聊天回合也会跳过已读回执。 -## 投递、分块和媒体 +## 送达、分块和媒体 @@ -374,23 +377,23 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 - - 支持图片、视频、音频（PTT 语音便笺）和文档载荷 - - 音频媒体通过 Baileys `audio` 载荷并带 `ptt: true` 发送，因此 WhatsApp 客户端会将其渲染为按住说话语音便笺 - - 回复载荷会保留 `audioAsVoice`；即使提供商返回 MP3 或 WebM，面向 WhatsApp 的 TTS 语音便笺输出也会保持在此 PTT 路径上 - - 原生 Ogg/Opus 音频会以 `audio/ogg; codecs=opus` 发送，以兼容语音便笺 - - 非 Ogg 音频，包括 Microsoft Edge TTS MP3/WebM 输出，会在 PTT 投递前使用 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus - - `/tts latest` 会将最新的助手回复作为一条语音便笺发送，并抑制对同一回复的重复发送；`/tts chat on|off|default` 控制当前 WhatsApp 聊天的自动 TTS - - 通过视频发送上的 `gifPlayback: true` 支持动画 GIF 播放 - - 发送多媒体回复载荷时，说明文字会应用到第一个媒体项；但 PTT 语音便笺会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端不会一致地渲染语音便笺说明文字 - - 媒体源可以是 HTTP(S)、`file://` 或本地路径 + - 支持图片、视频、音频（PTT 语音留言）和文档载荷 + - 音频媒体会通过 Baileys `audio` 载荷并带 `ptt: true` 发送，因此 WhatsApp 客户端会将其渲染为按住说话语音留言 + - 回复载荷会保留 `audioAsVoice`；即使提供商返回 MP3 或 WebM，WhatsApp 的 TTS 语音留言输出也会继续走这条 PTT 路径 + - 原生 Ogg/Opus 音频会以 `audio/ogg; codecs=opus` 发送，以兼容语音留言 + - 非 Ogg 音频，包括 Microsoft Edge TTS MP3/WebM 输出，会先用 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus，再进行 PTT 送达 + - `/tts latest` 会将最新的智能体回复作为一条语音留言发送，并抑制对同一回复的重复发送；`/tts chat on|off|default` 控制当前 WhatsApp 聊天的自动 TTS + - 通过视频发送中的 `gifPlayback: true` 支持动画 GIF 播放 + - 发送多媒体回复载荷时，字幕会应用到第一个媒体项；但 PTT 语音留言会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端不会一致地渲染语音留言字幕 + - 媒体来源可以是 HTTP(S)、`file://` 或本地路径 - 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - - 单账号覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` - - 图片会自动优化（调整大小/质量扫描）以满足限制 + - 按账号覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` + - 图片会自动优化（调整大小/质量扫描）以符合限制 - 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应 @@ -398,16 +401,16 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标 ## 回复引用 -WhatsApp 支持原生回复引用，出站回复会显式引用入站消息。使用 `channels.whatsapp.replyToMode` 控制它。 +WhatsApp 支持原生回复引用，出站回复会可见地引用入站消息。用 `channels.whatsapp.replyToMode` 控制它。 | 值 | 行为 | | ----------- | --------------------------------------------------------------------- | -| `"off"` | 从不引用；作为普通消息发送 | +| `"off"` | 永不引用；作为普通消息发送 | | `"first"` | 仅引用第一个出站回复分块 | | `"all"` | 引用每个出站回复分块 | -| `"batched"` | 引用队列中的批量回复，同时让即时回复不带引用 | +| `"batched"` | 引用排队的批量回复，同时让即时回复不引用 | -默认值为 `"off"`。单账号覆盖使用 `channels.whatsapp.accounts..replyToMode`。 +默认值是 `"off"`。按账号覆盖使用 `channels.whatsapp.accounts..replyToMode`。 ```json5 { @@ -423,16 +426,16 @@ WhatsApp 支持原生回复引用，出站回复会显式引用入站消息。 `channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情反应的范围： -| 级别 | 确认反应 | 智能体主动发起的反应 | 描述 | -| ------------- | -------- | -------------------- | ---------------------------------------------- | -| `"off"` | 否 | 否 | 完全不使用反应 | -| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） | -| `"minimal"` | 是 | 是（保守） | 确认 + 带保守指引的智能体反应 | -| `"extensive"` | 是 | 是（鼓励） | 确认 + 带鼓励指引的智能体反应 | +| 级别 | 确认反应 | 智能体主动反应 | 描述 | +| ------------- | -------- | -------------- | -------------------------------------- | +| `"off"` | 否 | 否 | 完全不使用反应 | +| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） | +| `"minimal"` | 是 | 是（保守） | 确认 + 带保守指导的智能体反应 | +| `"extensive"` | 是 | 是（鼓励） | 确认 + 带鼓励指导的智能体反应 | 默认值：`"minimal"`。 -单账号覆盖使用 `channels.whatsapp.accounts..reactionLevel`。 +按账号覆盖使用 `channels.whatsapp.accounts..reactionLevel`。 ```json5 { @@ -447,7 +450,7 @@ WhatsApp 支持原生回复引用，出站回复会显式引用入站消息。 ## 确认反应 WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。 -确认反应受 `reactionLevel` 控制 — 当 `reactionLevel` 为 `"off"` 时会被抑制。 +确认反应受 `reactionLevel` 门控，当 `reactionLevel` 为 `"off"` 时会被抑制。 ```json5 { @@ -466,11 +469,11 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 行为说明： - 在入站消息被接受后立即发送（回复前） -- 失败会被记录，但不会阻止正常回复投递 -- 群组模式 `mentions` 会在由提及触发的轮次上发送反应；群组激活 `always` 会作为此检查的绕过 +- 失败会记录日志，但不会阻塞正常回复送达 +- 群组模式 `mentions` 会对由提及触发的回合发送反应；群组激活 `always` 会作为此检查的绕过项 - WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`） -## 多账号和凭据 +## 多账号和凭证 @@ -480,17 +483,17 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - + - 当前认证路径：`~/.openclaw/credentials/whatsapp//creds.json` - 备份文件：`creds.json.bak` - - 旧版 `~/.openclaw/credentials/` 中的默认认证仍会在默认账号流程中被识别/迁移 + - `~/.openclaw/credentials/` 中的旧版默认认证仍会被识别/迁移，用于默认账号流程 - + `openclaw channels logout --channel whatsapp [--account ]` 会清除该账号的 WhatsApp 认证状态。 - 当 Gateway 网关可达时，退出登录会先停止所选账号的实时 WhatsApp 监听器，避免已关联的会话在下次重启前继续接收消息。`openclaw channels remove --channel whatsapp` 也会在禁用或删除账号配置前停止实时监听器。 + 当 Gateway 网关 可达时，登出会先停止所选账号的实时 WhatsApp 监听器，使已关联会话在下次重启前不会继续接收消息。`openclaw channels remove --channel whatsapp` 也会在禁用或删除账号配置前停止实时监听器。 在旧版认证目录中，`oauth.json` 会被保留，而 Baileys 认证文件会被移除。 @@ -509,7 +512,7 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - 症状：渠道 Status 报告未关联。 + 症状：渠道状态报告未关联。 修复： @@ -521,11 +524,11 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - 症状：已关联账号反复断开连接或尝试重连。 + 症状：已关联账号反复断开连接或反复尝试重连。 - 安静账号可以在正常消息超时后继续保持连接；当 WhatsApp Web 传输活动停止、套接字关闭，或应用级活动在更长的安全窗口后仍保持静默时，watchdog 会重启。 + 静默账号可以在正常消息超时之后保持连接；当 WhatsApp Web 传输活动停止、套接字关闭，或应用层活动静默超过更长的安全窗口时，看门狗会重启。 - 如果日志显示重复的 `status=408 Request Time-out Connection was lost`，请调整 `web.whatsapp` 下的 Baileys 套接字时序。先将 `keepAliveIntervalMs` 缩短到低于你的网络空闲超时时间，并在缓慢或高丢包链路上增大 `connectTimeoutMs`： + 如果日志显示重复的 `status=408 Request Time-out Connection was lost`，请调整 `web.whatsapp` 下的 Baileys 套接字时序。先将 `keepAliveIntervalMs` 缩短到低于你的网络空闲超时，并在慢速或丢包链路上增大 `connectTimeoutMs`： ```json5 { @@ -546,32 +549,32 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 openclaw logs --follow ``` - 如果 `~/.openclaw/logs/whatsapp-health.log` 显示 `Gateway inactive`，但 `openclaw gateway status` 和 `openclaw channels status --probe` 显示 Gateway 网关和 WhatsApp 状态正常，请运行 `openclaw doctor`。在 Linux 上，Doctor 会警告仍在调用 `~/.openclaw/bin/ensure-whatsapp.sh` 的旧版 crontab 条目；请使用 `crontab -e` 移除这些过期条目，因为 cron 可能缺少 systemd 用户总线环境，并导致该旧脚本误报 Gateway 网关健康状态。 + 如果 `~/.openclaw/logs/whatsapp-health.log` 显示 `Gateway inactive`，但 `openclaw gateway status` 和 `openclaw channels status --probe` 显示 Gateway 网关 与 WhatsApp 健康，请运行 `openclaw doctor`。在 Linux 上，Doctor 会警告仍在调用 `~/.openclaw/bin/ensure-whatsapp.sh` 的旧版 crontab 条目；请用 `crontab -e` 移除这些过期条目，因为 cron 可能缺少 systemd 用户总线环境，导致旧脚本误报 Gateway 网关 健康状态。 如有需要，请使用 `channels login` 重新关联。 - - 症状：`openclaw channels login --channel whatsapp` 在显示可用 QR 码之前失败，并出现 `status=408 Request Time-out` 或 TLS 套接字断开。 + + 症状：`openclaw channels login --channel whatsapp` 在显示可用 QR 码之前失败，并出现 `status=408 Request Time-out` 或 TLS 套接字断开连接。 - WhatsApp Web 登录使用 Gateway 网关主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、小写变体和 `NO_PROXY`）。请确认 Gateway 网关进程继承了代理环境变量，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。 + WhatsApp Web 登录使用 Gateway 网关 主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、小写变体以及 `NO_PROXY`）。确认 Gateway 网关 进程继承了代理环境变量，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。 - 当目标账号没有活动的 Gateway 网关监听器时，出站发送会快速失败。 + 当目标账号没有活动 Gateway 网关 监听器时，出站发送会快速失败。 - 请确保 Gateway 网关正在运行且账号已关联。 + 确保 Gateway 网关 正在运行且账号已关联。 - 转录行记录智能体生成的内容。WhatsApp 投递会单独检查：只有在 Baileys 为至少一条可见文本或媒体发送返回出站消息 ID 后，OpenClaw 才会将自动回复视为已发送。 + 转录行记录智能体生成的内容。WhatsApp 送达会单独检查：只有当 Baileys 针对至少一次可见文本或媒体发送返回出站消息 ID 后，OpenClaw 才会将自动回复视为已发送。 - 确认反应是独立的回复前回执。成功发送反应并不证明之后的文本或媒体回复已被 WhatsApp 接受。 + 确认反应是独立的回复前回执。反应成功并不能证明后续文本或媒体回复已被 WhatsApp 接受。 - 检查 Gateway 网关日志中的 `auto-reply delivery failed` 或 `auto-reply was not accepted by WhatsApp provider`。 + 检查 Gateway 网关 日志中是否有 `auto-reply delivery failed` 或 `auto-reply was not accepted by WhatsApp provider`。 @@ -587,40 +590,40 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp/Telegram Gateway 网关运行。 + WhatsApp Gateway 网关 运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp/Telegram Gateway 网关 运行。 -## 系统提示词 +## 系统提示 -WhatsApp 通过 `groups` 和 `direct` 映射支持 Telegram 风格的群组和直接聊天系统提示词。 +WhatsApp 支持通过 `groups` 和 `direct` 映射为群组和直接聊天配置 Telegram 风格的系统提示。 群组消息的解析层级： -首先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根 `groups` 映射（不进行深度合并）。然后在生成的单一映射上执行提示词查找： +有效的 `groups` 映射会先确定：如果账号定义了自己的 `groups`，它会完全替换根 `groups` 映射（不做深度合并）。随后提示查找会在得到的单个映射上运行： -1. **群组专用系统提示词**（`groups[""].systemPrompt`）：当特定群组条目存在于映射中**且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符并且不应用系统提示词。 -2. **群组通配系统提示词**（`groups["*"].systemPrompt`）：当特定群组条目完全不存在于映射中，或它存在但未定义 `systemPrompt` 键时使用。 +1. **群组专属系统提示**（`groups[""].systemPrompt`）：当映射中存在特定群组条目**且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），通配符会被抑制，且不会应用系统提示。 +2. **群组通配系统提示**（`groups["*"].systemPrompt`）：当映射中完全不存在特定群组条目，或该条目存在但未定义 `systemPrompt` 键时使用。 直接消息的解析层级： -首先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根 `direct` 映射（不进行深度合并）。然后在生成的单一映射上执行提示词查找： +有效的 `direct` 映射会先确定：如果账号定义了自己的 `direct`，它会完全替换根 `direct` 映射（不做深度合并）。随后提示查找会在得到的单个映射上运行： -1. **直接聊天专用系统提示词**（`direct[""].systemPrompt`）：当特定对端条目存在于映射中**且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符并且不应用系统提示词。 -2. **直接聊天通配系统提示词**（`direct["*"].systemPrompt`）：当特定对端条目完全不存在于映射中，或它存在但未定义 `systemPrompt` 键时使用。 +1. **直接聊天专属系统提示**（`direct[""].systemPrompt`）：当映射中存在特定对端条目**且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），通配符会被抑制，且不会应用系统提示。 +2. **直接聊天通配系统提示**（`direct["*"].systemPrompt`）：当映射中完全不存在特定对端条目，或该条目存在但未定义 `systemPrompt` 键时使用。 -`dms` 仍然是轻量级的每个私信历史覆盖存储桶（`dms..historyLimit`）。提示词覆盖位于 `direct` 下。 +`dms` 仍是轻量的按私信历史覆盖桶（`dms..historyLimit`）。提示覆盖位于 `direct` 下。 -**与 Telegram 多账号行为的区别：** 在 Telegram 中，多账号设置会有意对所有账号抑制根级 `groups`，即使某些账号没有定义自己的 `groups` 也是如此，以防机器人接收它不属于的群组消息。WhatsApp 不应用此保护：根级 `groups` 和根级 `direct` 始终会被未定义账号级覆盖项的账号继承，无论配置了多少个账号。在多账号 WhatsApp 设置中，如果你想要按账号设置群组或私聊提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。 +**与 Telegram 多账号行为的区别：** 在 Telegram 中，多账号设置会刻意对所有账号抑制根级 `groups`，即使某些账号没有定义自己的 `groups`，也是如此。这是为了防止机器人接收它不属于的群组消息。WhatsApp 不应用这项保护：只要账号没有定义账号级覆盖项，它们始终会继承根级 `groups` 和根级 `direct`，无论配置了多少个账号。在多账号 WhatsApp 设置中，如果你希望按账号设置群组或私信提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。 重要行为： - `channels.whatsapp.groups` 既是按群组配置的映射，也是聊天级群组允许列表。在根级或账号作用域中，`groups["*"]` 表示该作用域“允许所有群组”。 -- 只有当你已经希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍然希望只有固定的一组群组 ID 有资格进入处理，不要使用 `groups["*"]` 作为提示词默认值。请改为在每个显式允许的群组条目上重复该提示词。 -- 群组准入和发送者授权是两个独立检查。`groups["*"]` 会扩大可以进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍然由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 分别控制。 -- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已通过 `dmPolicy` 加 `allowFrom` 或配对存储规则准入后，提供默认的直聊配置。 +- 只有在你已经希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍然只希望固定的一组群组 ID 符合条件，请不要使用 `groups["*"]` 作为提示词默认值。改为在每个显式允许的群组条目上重复该提示词。 +- 群组准入和发送者授权是两个独立检查。`groups["*"]` 会扩大可进入群组处理流程的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 +- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则准入后，提供默认的私信聊天配置。 示例： @@ -668,7 +671,7 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持 Telegram 风格的群组和 - [配置参考 - WhatsApp](/zh-CN/gateway/config-channels#whatsapp) -重点 WhatsApp 字段： +高信号 WhatsApp 字段： - 访问：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups` - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel` diff --git a/docs/zh-CN/cli/directory.md b/docs/zh-CN/cli/directory.md index 674591900..b1a53c9f8 100644 --- a/docs/zh-CN/cli/directory.md +++ b/docs/zh-CN/cli/directory.md @@ -1,34 +1,34 @@ --- read_when: - - 你想查找某个渠道的联系人、群组或自身 ID + - 你想查找某个渠道的联系人/群组/自身标识符 - 你正在开发一个渠道目录适配器 summary: '`openclaw directory` 的 CLI 参考（自身、对等方、群组）' title: 目录 x-i18n: - generated_at: "2026-05-02T05:25:38Z" + generated_at: "2026-05-02T20:13:39Z" model: gpt-5.5 provider: openai - source_hash: dcd0be284c0ec1aa347084d84f7001f1e2f47977ec5198025ba303297858aaab + source_hash: 011f762d6f53605a37bd12b31c767594c0efa5681da4b2aabe7fb358751b1542 source_path: cli/directory.md workflow: 16 --- # `openclaw directory` -对支持目录查询的渠道进行查找（联系人/对等方、群组以及“me”）。 +用于支持目录查找的渠道（联系人/对等方、群组和 “me”）。 -## 通用标志 +## 常用标志 -- `--channel `：渠道 id/别名（配置多个渠道时必填；仅配置一个渠道时自动使用） -- `--account `：账号 id（默认值：渠道默认账号） +- `--channel `：渠道 ID/别名（配置了多个渠道时必需；仅配置一个时自动使用） +- `--account `：账号 ID（默认：渠道默认值） - `--json`：输出 JSON ## 说明 - `directory` 用于帮助你找到可粘贴到其他命令中的 ID（尤其是 `openclaw message send --target ...`）。 -- 对于许多渠道，结果由配置支持（允许列表/已配置群组），而不是来自实时提供商目录。 -- 已安装的渠道插件仍然可以省略目录支持；在这种情况下，该命令会报告不支持的目录操作，而不是重新安装插件。 -- 默认输出为用制表符分隔的 `id`（有时还有 `name`）；如需编写脚本，请使用 `--json`。 +- 对于许多渠道，结果由配置支持（允许列表/已配置群组），而不是实时提供商目录。 +- 已安装的渠道插件仍然可以省略目录支持；在这种情况下，命令会报告不支持的目录操作，而不是重新安装插件。 +- 默认输出是用制表符分隔的 `id`（有时还有 `name`）；脚本使用请加 `--json`。 ## 将结果用于 `message send` @@ -39,16 +39,16 @@ openclaw message send --channel slack --target user:U012ABCDEF --message "hello" ## ID 格式（按渠道） -- WhatsApp：`+15551234567`（私信），`1234567890-1234567890@g.us`（群组） -- Telegram：`@username` 或数字聊天 id；群组使用数字 id +- WhatsApp：`+15551234567`（私信）、`1234567890-1234567890@g.us`（群组）、`120363123456789@newsletter`（Channel/Newsletter 外发目标） +- Telegram：`@username` 或数字聊天 ID；群组是数字 ID - Slack：`user:U…` 和 `channel:C…` - Discord：`user:` 和 `channel:` - Matrix（插件）：`user:@user:server`、`room:!roomId:server` 或 `#alias:server` - Microsoft Teams（插件）：`user:` 和 `conversation:` -- Zalo（插件）：用户 id（Bot API） -- Zalo Personal / `zalouser`（插件）：来自 `zca` 的会话串 id（私信/群组）（`me`、`friend list`、`group list`） +- Zalo（插件）：用户 ID（Bot API） +- Zalo Personal / `zalouser`（插件）：来自 `zca` 的会话串 ID（私信/群组）（`me`、`friend list`、`group list`） -## 自身（“me”） +## 自己（"me"） ```bash openclaw directory self --channel zalouser diff --git a/docs/zh-CN/cli/message.md b/docs/zh-CN/cli/message.md index 2b48a955c..ea97df9f2 100644 --- a/docs/zh-CN/cli/message.md +++ b/docs/zh-CN/cli/message.md @@ -2,20 +2,20 @@ read_when: - 添加或修改消息 CLI 操作 - 更改出站渠道行为 -summary: CLI 参考：`openclaw message`（发送 + 渠道操作） +summary: '`openclaw message` 的 CLI 参考（发送 + 渠道操作）' title: 消息 x-i18n: - generated_at: "2026-05-02T02:28:50Z" + generated_at: "2026-05-02T20:13:39Z" model: gpt-5.5 provider: openai - source_hash: f429acc2c81f33d1ade543ab1170220e293077e1d1721ac0940937de3d19f0d2 + source_hash: 6b73a50da34838f80ad5d0d266f5c66f95436f8535e6312296ae022918b1ab55 source_path: cli/message.md workflow: 16 --- # `openclaw message` -用于发送消息和渠道操作的单个出站命令 +用于发送消息和渠道操作的单一出站命令 （Discord/Google Chat/iMessage/Matrix/Mattermost（插件）/Microsoft Teams/Signal/Slack/Telegram/WhatsApp）。 ## 用法 @@ -27,33 +27,33 @@ openclaw message [flags] 渠道选择： - 如果配置了多个渠道，则必须提供 `--channel`。 -- 如果只配置了一个渠道，它会成为默认值。 +- 如果只配置了一个渠道，它会成为默认渠道。 - 值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost 需要插件） -- 当存在 `--channel` 或带渠道前缀的目标时，`openclaw message` 会将所选渠道解析到其所属插件；否则，它会加载已配置的渠道插件来推断默认渠道。 +- 当存在 `--channel` 或带渠道前缀的目标时，`openclaw message` 会将所选渠道解析到拥有它的插件；否则，它会加载已配置的渠道插件来推断默认渠道。 目标格式（`--target`）： -- WhatsApp：E.164 或群组 JID -- Telegram：聊天 ID 或 `@username` -- Discord：`channel:` 或 `user:`（或 `<@id>` 提及；原始数字 ID 会被视为渠道） +- WhatsApp：E.164、群组 JID，或 WhatsApp Channel/Newsletter JID（`...@newsletter`） +- Telegram：聊天 id 或 `@username` +- Discord：`channel:` 或 `user:`（或 `<@id>` 提及；原始数字 id 会被视为频道） - Google Chat：`spaces/` 或 `users/` -- Slack：`channel:` 或 `user:`（接受原始渠道 ID） -- Mattermost（插件）：`channel:`、`user:` 或 `@username`（裸 ID 会被视为渠道） +- Slack：`channel:` 或 `user:`（接受原始频道 id） +- Mattermost（插件）：`channel:`、`user:` 或 `@username`（裸 id 会被视为频道） - Signal：`+E.164`、`group:`、`signal:+E.164`、`signal:group:`，或 `username:`/`u:` -- iMessage：句柄、`chat_id:`、`chat_guid:` 或 `chat_identifier:` -- Matrix：`@user:server`、`!room:server` 或 `#alias:server` -- Microsoft Teams：会话 ID（`19:...@thread.tacv2`）或 `conversation:` 或 `user:` +- iMessage：handle、`chat_id:`、`chat_guid:`，或 `chat_identifier:` +- Matrix：`@user:server`、`!room:server`，或 `#alias:server` +- Microsoft Teams：会话 id（`19:...@thread.tacv2`）或 `conversation:` 或 `user:` 名称查找： -- 对于受支持的提供商（Discord/Slack 等），像 `Help` 或 `#help` 这样的渠道名称会通过目录缓存解析。 +- 对于支持的提供商（Discord/Slack 等），像 `Help` 或 `#help` 这样的渠道名称会通过目录缓存解析。 - 缓存未命中时，如果提供商支持，OpenClaw 会尝试实时目录查找。 ## 常用标志 - `--channel ` - `--account ` -- `--target `（发送/投票/读取等操作的目标渠道或用户） +- `--target `（用于 send/poll/read 等的目标渠道或用户） - `--targets `（可重复；仅广播） - `--json` - `--dry-run` @@ -61,13 +61,13 @@ openclaw message [flags] ## SecretRef 行为 -- `openclaw message` 会在运行所选操作前解析受支持渠道的 SecretRefs。 -- 在可能时，解析范围会限定到当前操作目标： - - 设置了 `--channel` 时按渠道范围限定（或从 `discord:...` 这类带前缀目标推断） - - 设置了 `--account` 时按账号范围限定（渠道全局项 + 所选账号表面） - - 省略 `--account` 时，OpenClaw 不会强制使用 `default` 账号 SecretRef 范围 -- 无关渠道上未解析的 SecretRefs 不会阻止定向消息操作。 -- 如果所选渠道/账号的 SecretRef 未解析，该操作会以失败关闭方式终止。 +- `openclaw message` 会在运行所选操作之前解析受支持渠道的 SecretRefs。 +- 尽可能将解析范围限定到活动操作目标： + - 设置了 `--channel` 时按渠道限定（或从 `discord:...` 这类带前缀目标推断） + - 设置了 `--account` 时按账号限定（渠道全局项 + 所选账号表面） + - 省略 `--account` 时，OpenClaw 不会强制使用 `default` 账号 SecretRef 作用域 +- 不相关渠道上未解析的 SecretRefs 不会阻止有目标的消息操作。 +- 如果所选渠道/账号的 SecretRef 未解析，该命令会针对该操作关闭失败。 ## 操作 @@ -77,13 +77,13 @@ openclaw message [flags] - 渠道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/Matrix/Microsoft Teams - 必需：`--target`，以及 `--message`、`--media` 或 `--presentation` - 可选：`--media`、`--presentation`、`--delivery`、`--pin`、`--reply-to`、`--thread-id`、`--gif-playback`、`--force-document`、`--silent` - - 共享呈现载荷：`--presentation` 会发送语义块（`text`、`context`、`divider`、`buttons`、`select`），核心会通过所选渠道声明的能力来渲染它们。请参阅 [Message Presentation](/zh-CN/plugins/message-presentation)。 - - 通用投递偏好：`--delivery` 接受诸如 `{ "pin": true }` 的投递提示；当渠道支持时，`--pin` 是置顶投递的简写。 + - 共享 presentation 载荷：`--presentation` 发送语义块（`text`、`context`、`divider`、`buttons`、`select`），核心会通过所选渠道声明的能力进行渲染。参见 [Message Presentation](/zh-CN/plugins/message-presentation)。 + - 通用投递偏好：`--delivery` 接受诸如 `{ "pin": true }` 的投递提示；当渠道支持时，`--pin` 是固定投递的简写。 - 仅 Telegram：`--force-document`（将图片和 GIF 作为文档发送，以避免 Telegram 压缩） - - 仅 Telegram：`--thread-id`（论坛主题 ID） + - 仅 Telegram：`--thread-id`（论坛主题 id） - 仅 Slack：`--thread-id`（线程时间戳；`--reply-to` 使用同一字段） - Telegram + Discord：`--silent` - - 仅 WhatsApp：`--gif-playback` + - 仅 WhatsApp：`--gif-playback`；WhatsApp Channels/Newsletters 使用其原生 `@newsletter` JID 寻址。 - `poll` - 渠道：WhatsApp/Telegram/Discord/Matrix/Microsoft Teams @@ -96,7 +96,7 @@ openclaw message [flags] - 渠道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix - 必需：`--message-id`、`--target` - 可选：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid` - - 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在支持的地方清除自己的反应；请参阅 /tools/reactions） + - 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在支持的情况下清除自己的反应；参见 /tools/reactions） - 仅 WhatsApp：`--participant`、`--from-me` - Signal 群组反应：需要 `--target-author` 或 `--target-author-uuid` @@ -124,14 +124,14 @@ openclaw message [flags] - 渠道：Discord/Slack/Matrix - 必需：`--message-id`、`--target` -- `pins`（列表） +- `pins`（列出） - 渠道：Discord/Slack/Matrix - 必需：`--target` - `permissions` - 渠道：Discord/Matrix - 必需：`--target` - - 仅 Matrix：当启用 Matrix 加密且允许验证操作时可用 + - 仅 Matrix：当 Matrix 加密已启用且允许验证操作时可用 - `search` - 渠道：Discord @@ -142,7 +142,7 @@ openclaw message [flags] - `thread create` - 渠道：Discord - - 必需：`--thread-name`、`--target`（渠道 ID） + - 必需：`--thread-name`、`--target`（频道 id） - 可选：`--message-id`、`--message`、`--auto-archive-min` - `thread list` @@ -152,7 +152,7 @@ openclaw message [flags] - `thread reply` - 渠道：Discord - - 必需：`--target`（线程 ID）、`--message` + - 必需：`--target`（线程 id）、`--message` - 可选：`--media`、`--reply-to` ### 表情符号 @@ -177,13 +177,13 @@ openclaw message [flags] - 渠道：Discord - 必需：`--guild-id`、`--sticker-name`、`--sticker-desc`、`--sticker-tags`、`--media` -### 角色 / 渠道 / 成员 / 语音 +### 角色 / 频道 / 成员 / 语音 - `role info`（Discord）：`--guild-id` - `role add` / `role remove`（Discord）：`--guild-id`、`--user-id`、`--role-id` - `channel info`（Discord）：`--target` - `channel list`（Discord）：`--guild-id` -- `member info`（Discord/Slack）：`--user-id`（Discord 还需 `--guild-id`） +- `member info`（Discord/Slack）：`--user-id`（Discord 还需要 `--guild-id`） - `voice status`（Discord）：`--guild-id`、`--user-id` ### 事件 @@ -192,9 +192,9 @@ openclaw message [flags] - `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time` - 可选：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type` -### 审核（Discord） +### 内容治理（Discord） -- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除超时） +- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除 timeout） - `kick`：`--guild-id`、`--user-id`（+ `--reason`） - `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`） - `timeout` 也支持 `--reason` @@ -202,7 +202,7 @@ openclaw message [flags] ### 广播 - `broadcast` - - 渠道：任何已配置渠道；使用 `--channel all` 定向所有提供商 + - 渠道：任何已配置渠道；使用 `--channel all` 以面向所有提供商 - 必需：`--targets ` - 可选：`--message`、`--media`、`--dry-run` @@ -223,9 +223,9 @@ openclaw message send --channel discord \ --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}' ``` -核心会根据渠道能力，将同一个 `presentation` 载荷渲染为 Discord 组件、Slack 块、Telegram 内联按钮、Mattermost props，或 Teams/Feishu 卡片。完整合约和回退规则请参阅 [Message Presentation](/zh-CN/plugins/message-presentation)。 +核心会根据渠道能力，将同一个 `presentation` 载荷渲染为 Discord 组件、Slack 块、Telegram 行内按钮、Mattermost props，或 Teams/Feishu 卡片。完整契约和回退规则请参见 [Message Presentation](/zh-CN/plugins/message-presentation)。 -发送更丰富的呈现载荷： +发送更丰富的 presentation 载荷： ```bash openclaw message send --channel googlechat --target spaces/AAA... \ @@ -269,14 +269,14 @@ openclaw message poll --channel msteams \ --poll-option Pizza --poll-option Sushi ``` -在 Slack 中反应： +在 Slack 中添加反应： ``` openclaw message react --channel slack \ --target C123 --message-id 456 --emoji "✅" ``` -在 Signal 群组中反应： +在 Signal 群组中添加反应： ``` openclaw message react --channel signal \ @@ -284,14 +284,14 @@ openclaw message react --channel signal \ --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000 ``` -通过通用呈现发送 Telegram 内联按钮： +通过通用 presentation 发送 Telegram 行内按钮： ``` openclaw message send --channel telegram --target @mychat --message "Choose:" \ --presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}' ``` -通过通用呈现发送 Teams 卡片： +通过通用 presentation 发送 Teams 卡片： ```bash openclaw message send --channel msteams \ @@ -306,7 +306,7 @@ openclaw message send --channel telegram --target @mychat \ --media ./diagram.png --force-document ``` -## 相关 +## 相关内容 - [CLI 参考](/zh-CN/cli) -- [智能体发送](/zh-CN/tools/agent-send) +- [Agent 发送](/zh-CN/tools/agent-send)