From 002f1e7ae90bb926791fb040a90f662e3bf96607 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 00:21:46 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/automation/tasks.md | 166 +++++---- docs/zh-CN/channels/matrix.md | 538 ++++++++++++++------------- docs/zh-CN/plugins/manifest.md | 309 ++++++++------- docs/zh-CN/providers/models.md | 21 +- docs/zh-CN/providers/runway.md | 18 +- docs/zh-CN/tools/video-generation.md | 103 ++--- 6 files changed, 580 insertions(+), 575 deletions(-) diff --git a/docs/zh-CN/automation/tasks.md b/docs/zh-CN/automation/tasks.md index f5ca4ae32..bbb4dfb56 100644 --- a/docs/zh-CN/automation/tasks.md +++ b/docs/zh-CN/automation/tasks.md @@ -1,56 +1,56 @@ --- read_when: - - 检查正在进行中或最近完成的后台工作 - - 调试分离式智能体运行的投递失败问题 - - 了解后台运行如何与会话、cron 和 heartbeat 关联 + - 检查正在进行中或最近完成的后台工作时 + - 调试分离式智能体运行的投递失败时 + - 了解后台运行如何与会话、cron 和 heartbeat 关联时 summary: 用于跟踪 ACP 运行、子智能体、隔离的 cron 作业以及 CLI 操作的后台任务 title: 后台任务 x-i18n: - generated_at: "2026-04-05T23:52:42Z" + generated_at: "2026-04-06T00:20:21Z" model: gpt-5.4 provider: openai - source_hash: 68ba60b352c8d8fc57fed081856581107c6c0eb09ef4047264c3052abc30520d + source_hash: 5fc757b30e2d9c1b5c4d9c8ff21cdc406835af207a83ee6076b63c348ad07781 source_path: automation/tasks.md workflow: 15 --- # 后台任务 -> **在找调度方式？** 请参阅 [自动化与任务](/zh-CN/automation)，以选择合适的机制。本页介绍的是如何**跟踪**后台工作，而不是如何调度它。 +> **在找调度功能？** 请参阅 [自动化与任务](/zh-CN/automation)，以选择合适的机制。本页介绍的是如何**跟踪**后台工作，而不是如何调度它。 后台任务用于跟踪**在你的主对话会话之外**运行的工作： ACP 运行、子智能体生成、隔离的 cron 作业执行，以及由 CLI 发起的操作。 -任务**不会**替代会话、cron 作业或 heartbeat——它们是用于记录分离式工作何时发生、发生了什么以及是否成功的**活动账本**。 +任务**不会**取代会话、cron 作业或 heartbeat——它们是记录分离式工作发生了什么、何时发生以及是否成功的**活动台账**。 -并非每次智能体运行都会创建任务。Heartbeat 轮次和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成以及 CLI 智能体命令都会创建任务。 +并非每次智能体运行都会创建任务。Heartbeat 回合和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成以及 CLI 智能体命令都会创建任务。 ## TL;DR -- 任务是**记录**，不是调度器——cron 和 heartbeat 决定工作_何时_运行，任务负责跟踪_发生了什么_。 -- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。Heartbeat 轮次不会。 +- 任务是**记录**，不是调度器——cron 和 heartbeat 决定工作_何时_运行，任务跟踪_发生了什么_。 +- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。Heartbeat 回合不会。 - 每个任务都会经历 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。 -- 只要 cron 运行时仍然拥有该作业，cron 任务就会保持存活；而基于聊天的 CLI 任务只会在其所属的运行上下文仍处于活动状态时保持存活。 -- 完成机制是推送驱动的：分离式工作完成时可以直接通知，或唤醒请求者会话 / heartbeat，因此轮询状态通常不是正确的方式。 -- 隔离的 cron 运行和子智能体完成时，会尽力在最终清理记账之前清理其子会话中已跟踪的浏览器标签页 / 进程。 -- 在后代子智能体工作仍在排空期间，隔离 cron 的投递会抑制过时的中间父级回复；如果最终的后代输出先到达，则优先使用该输出。 +- 只要 cron 运行时仍然拥有该作业，cron 任务就会保持活动状态；而基于聊天的 CLI 任务只会在其所属运行上下文仍处于活动状态时保持活动。 +- 完成是由推送驱动的：分离式工作在结束时可以直接通知，或唤醒请求方会话 / heartbeat，因此状态轮询循环通常不是正确方式。 +- 隔离的 cron 运行和子智能体完成时，会尽最大努力在最终清理记账前，清理其子会话所跟踪的浏览器标签页 / 进程。 +- 隔离的 cron 投递会在后代子智能体工作仍在排空时抑制过期的中间父级回复，并且在后代最终输出先于投递到达时优先使用该输出。 - 完成通知会直接投递到某个渠道，或排队等待下一次 heartbeat。 -- `openclaw tasks list` 会显示所有任务；`openclaw tasks audit` 会显示问题。 -- 终态记录会保留 7 天，之后自动清理。 +- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 用于发现问题。 +- 终态记录会保留 7 天，然后自动清理。 ## 快速开始 ```bash -# 列出所有任务（最新优先） +# 列出所有任务（最新的在前） openclaw tasks list # 按运行时或状态筛选 openclaw tasks list --runtime acp openclaw tasks list --status running -# 显示特定任务的详情（按 ID、run ID 或 session key） +# 显示特定任务的详细信息（按 ID、run ID 或 session key） openclaw tasks show # 取消正在运行的任务（终止子会话） @@ -78,18 +78,20 @@ openclaw tasks flow cancel | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | | ACP 后台运行 | `acp` | 生成子 ACP 会话时 | `done_only` | | 子智能体编排 | `subagent` | 通过 `sessions_spawn` 生成子智能体时 | `done_only` | -| Cron 作业（所有类型） | `cron` | 每次 cron 执行时（主会话和隔离式都包括） | `silent` | -| CLI 操作 | `cli` | 通过 Gateway 网关 运行的 `openclaw agent` 命令 | `silent` | +| Cron 作业（所有类型） | `cron` | 每次 cron 执行时（主会话和隔离模式都算） | `silent` | +| CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` | | 智能体媒体作业 | `cli` | 基于会话的 `video_generate` 运行 | `silent` | -主会话 cron 任务默认使用 `silent` 通知策略——它们会创建记录用于跟踪，但不会生成通知。隔离式 cron 任务默认也使用 `silent`，但由于它们在自己的会话中运行，因此可见性更高。 +主会话 cron 任务默认使用 `silent` 通知策略——它们会创建用于跟踪的记录，但不会生成通知。隔离的 cron 任务也默认使用 `silent`，但由于它们在自己的会话中运行，因此可见性更高。 -基于会话的 `video_generate` 运行同样使用 `silent` 通知策略。它们仍会创建任务记录，但完成结果会作为内部唤醒返回给原始智能体会话，以便智能体自行编写后续消息并附加已完成的视频。 +基于会话的 `video_generate` 运行也使用 `silent` 通知策略。它们仍会创建任务记录，但完成结果会作为内部唤醒返回给原始智能体会话，这样智能体就可以自行编写后续消息并附加生成完成的视频。 + +当某个基于会话的 `video_generate` 任务仍处于活动状态时，该工具还会充当保护机制：在同一会话中重复调用 `video_generate` 时，会返回活动任务状态，而不是启动第二个并发生成。若你想从智能体侧显式查询进度 / 状态，请使用 `action: "status"`。 **不会创建任务的情况：** -- Heartbeat 轮次——主会话；参见 [Heartbeat](/zh-CN/gateway/heartbeat) -- 普通交互式聊天轮次 +- Heartbeat 回合——主会话；参见 [Heartbeat](/zh-CN/gateway/heartbeat) +- 普通交互式聊天回合 - 直接 `/command` 响应 ## 任务生命周期 @@ -109,47 +111,47 @@ stateDiagram-v2 | 状态 | 含义 | | ----------- | -------------------------------------------------------------------------- | | `queued` | 已创建，等待智能体启动 | -| `running` | 智能体轮次正在执行 | +| `running` | 智能体回合正在执行中 | | `succeeded` | 已成功完成 | | `failed` | 已因错误完成 | -| `timed_out` | 超过已配置的超时时间 | +| `timed_out` | 超过配置的超时时间 | | `cancelled` | 由操作员通过 `openclaw tasks cancel` 停止 | -| `lost` | 在 5 分钟宽限期后，运行时丢失了权威性后端状态 | +| `lost` | 在 5 分钟宽限期后，运行时丢失了权威性支撑状态 | -状态转换会自动发生——当关联的智能体运行结束时，任务状态会更新为对应结果。 +状态转换会自动发生——当关联的智能体运行结束时，任务状态会更新为相应结果。 -`lost` 是运行时感知的： +`lost` 是感知运行时类型的： -- ACP 任务：后端 ACP 子会话元数据已消失。 -- 子智能体任务：后端子会话已从目标智能体存储中消失。 -- Cron 任务：cron 运行时不再将该作业视为活动状态。 -- CLI 任务：隔离式子会话任务使用子会话；基于聊天的 CLI 任务则改用活动运行上下文，因此残留的渠道 / 群组 / 直接会话行不会让它们继续保持存活。 +- ACP 任务：其底层 ACP 子会话元数据已消失。 +- 子智能体任务：其底层子会话已从目标智能体存储中消失。 +- Cron 任务：cron 运行时不再将该作业标记为活动。 +- CLI 任务：隔离的子会话任务使用子会话；而基于聊天的 CLI 任务则改用实时运行上下文，因此残留的渠道 / 群组 / 直连会话行不会让它们继续保持活动。 ## 投递和通知 -当任务进入终态时，OpenClaw 会通知你。共有两种投递路径： +当任务进入终态时，OpenClaw 会通知你。有两种投递路径： -**直接投递**——如果任务具有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 也会在可用时保留已绑定的线程 / 话题路由，并且在放弃直接投递之前，可以从请求者会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补齐缺失的 `to` / account。 +**直接投递**——如果任务有渠道目标（即 `requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留已绑定的线程 / 主题路由，并且可以在直接投递放弃前，先用请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）补全缺失的 `to` / 账号。 -**会话排队投递**——如果直接投递失败，或未设置来源，更新会作为系统事件排入请求者会话，并在下一次 heartbeat 时显示出来。 +**会话排队投递**——如果直接投递失败，或未设置来源，则更新会作为系统事件排入请求方会话，并在下一次 heartbeat 时呈现。 -任务完成会立即触发一次 heartbeat 唤醒，因此你可以很快看到结果——无需等到下一次计划中的 heartbeat tick。 +任务完成会立即触发 heartbeat 唤醒，这样你可以尽快看到结果——你不必等到下一次计划中的 heartbeat tick。 -这意味着常规工作流是基于推送的：启动一次分离式工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或进行明确审计时，才去轮询任务状态。 +这意味着常见工作流是基于推送的：只需启动一次分离式工作，然后让运行时在完成时唤醒或通知你。只有在你需要调试、干预或显式审计时，才去轮询任务状态。 ### 通知策略 -控制你会收到多少关于每个任务的信息： +控制你会听到每个任务的多少信息： -| 策略 | 会投递什么 | +| 策略 | 会投递的内容 | | --------------------- | ----------------------------------------------------------------------- | | `done_only`（默认） | 仅终态（succeeded、failed 等）——**这是默认值** | | `state_changes` | 每次状态转换和进度更新 | | `silent` | 完全不通知 | -在任务运行期间更改策略： +在任务运行时更改策略： ```bash openclaw tasks notify state_changes @@ -163,7 +165,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` -输出列：任务 ID、类型、状态、投递、运行 ID、子会话、摘要。 +输出列：任务 ID、类型、状态、投递、Run ID、子会话、摘要。 ### `tasks show` @@ -171,7 +173,7 @@ openclaw tasks list [--runtime ] [--status ] [--j openclaw tasks show ``` -查找标记接受任务 ID、运行 ID 或会话键。会显示完整记录，包括时间、投递状态、错误和终态摘要。 +查找标记接受任务 ID、run ID 或 session key。显示完整记录，包括时间信息、投递状态、错误和终态摘要。 ### `tasks cancel` @@ -179,7 +181,7 @@ openclaw tasks show openclaw tasks cancel ``` -对于 ACP 和子智能体任务，这会终止子会话。状态会切换为 `cancelled`，并发送投递通知。 +对于 ACP 和子智能体任务，这会终止子会话。状态会转为 `cancelled`，并发送一条投递通知。 ### `tasks notify` @@ -193,15 +195,15 @@ openclaw tasks notify openclaw tasks audit [--json] ``` -显示运维问题。检测到问题时，结果也会显示在 `openclaw status` 中。 +用于发现运维问题。检测到问题时，结果也会显示在 `openclaw status` 中。 -| 发现项 | 严重性 | 触发条件 | +| 发现项 | 严重级别 | 触发条件 | | ------------------------- | -------- | ----------------------------------------------------- | -| `stale_queued` | warn | 已排队超过 10 分钟 | -| `stale_running` | error | 已运行超过 30 分钟 | -| `lost` | error | 运行时支持的任务归属已消失 | +| `stale_queued` | warn | 排队超过 10 分钟 | +| `stale_running` | error | 运行超过 30 分钟 | +| `lost` | error | 运行时支撑的任务所有权已消失 | | `delivery_failed` | warn | 投递失败且通知策略不是 `silent` | -| `missing_cleanup` | warn | 终态任务没有清理时间戳 | +| `missing_cleanup` | warn | 终态任务没有 cleanup 时间戳 | | `inconsistent_timestamps` | warn | 时间线违规（例如结束早于开始） | ### `tasks maintenance` @@ -211,20 +213,20 @@ openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` -用它来预览或应用任务与 Task Flow 状态的对账、清理时间戳写入和清理删除。 +使用它来预览或应用任务及 Task Flow 状态的协调、清理时间戳记录和清理删除。 -对账是运行时感知的： +协调是感知运行时类型的： -- ACP / 子智能体任务会检查其后端子会话。 -- Cron 任务会检查 cron 运行时是否仍然拥有该作业。 -- 基于聊天的 CLI 任务会检查其所属的活动运行上下文，而不仅仅是聊天会话行。 +- ACP / 子智能体任务会检查其底层子会话。 +- Cron 任务会检查 cron 运行时是否仍拥有该作业。 +- 基于聊天的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。 -完成清理同样是运行时感知的： +完成清理同样是感知运行时类型的： -- 子智能体完成时，会尽力在继续执行通知后的清理之前，关闭该子会话中已跟踪的浏览器标签页 / 进程。 -- 隔离式 cron 完成时，会尽力在运行完全拆除之前，关闭该 cron 会话中已跟踪的浏览器标签页 / 进程。 -- 隔离式 cron 投递会在需要时等待后代子智能体的后续处理完成，并抑制过时的父级确认文本，而不是将其作为结果通知。 -- 子智能体完成投递会优先选择最新可见的 assistant 文本；如果该文本为空，则回退到已清洗的最新 tool / toolResult 文本，而仅有超时工具调用的运行则可折叠为简短的部分进度摘要。 +- 子智能体完成时，会尽最大努力在继续公告清理前关闭该子会话跟踪的浏览器标签页 / 进程。 +- 隔离的 cron 完成时，会尽最大努力在运行彻底拆除前关闭该 cron 会话跟踪的浏览器标签页 / 进程。 +- 隔离的 cron 投递会在需要时等待后代子智能体的后续处理完成，并抑制过期的父级确认文本，而不是将其公告出去。 +- 子智能体完成投递会优先采用最新可见的助手文本；如果该文本为空，则回退为净化后的最新 tool / toolResult 文本，而仅由超时工具调用构成的运行则可以折叠为简短的部分进度摘要。 - 清理失败不会掩盖真实的任务结果。 ### `tasks flow list|show|cancel` @@ -235,15 +237,15 @@ openclaw tasks flow show [--json] openclaw tasks flow cancel ``` -当你关心的是编排型 Task Flow，而不是某一条单独的后台任务记录时，请使用这些命令。 +当你关心的是编排中的 Task Flow，而不是某一条单独的后台任务记录时，请使用这些命令。 ## 聊天任务面板（`/tasks`） -在任意聊天会话中使用 `/tasks`，即可查看与该会话关联的后台任务。面板会显示活动中和最近完成的任务，包括运行时、状态、时间，以及进度或错误详情。 +在任意聊天会话中使用 `/tasks` 可查看关联到该会话的后台任务。该面板会显示活动和最近完成的任务，以及它们的运行时、状态、时间信息，以及进度或错误详情。 -当当前会话没有可见的关联任务时，`/tasks` 会回退显示智能体本地任务计数，这样你仍然可以获得概览，同时不会泄露其他会话的详情。 +当当前会话没有可见的关联任务时，`/tasks` 会回退为智能体本地任务计数，这样你仍然可以获得概览，而不会泄露其他会话的详情。 -如需完整的操作员账本，请使用 CLI：`openclaw tasks list`。 +如需查看完整的操作员台账，请使用 CLI：`openclaw tasks list`。 ## 状态集成（任务压力） @@ -253,68 +255,68 @@ openclaw tasks flow cancel Tasks: 3 queued · 2 running · 1 issues ``` -该摘要会报告： +该摘要报告： - **active**——`queued` + `running` 的数量 - **failures**——`failed` + `timed_out` + `lost` 的数量 -- **byRuntime**——按 `acp`、`subagent`、`cron`、`cli` 的细分 +- **byRuntime**——按 `acp`、`subagent`、`cron`、`cli` 分项统计 -`/status` 和 `session_status` 工具都使用清理感知的任务快照：优先显示活动任务，隐藏过时的已完成行，只有在没有活动工作剩余时才显示最近失败项。这样可以让状态卡片聚焦于当前真正重要的内容。 +`/status` 和 `session_status` 工具都使用“感知清理状态”的任务快照：会优先显示活动任务，隐藏过期的已完成记录，并且仅在没有活动工作剩余时才显示最近失败项。这样可以让状态卡片聚焦于当前真正重要的内容。 ## 存储和维护 ### 任务存储位置 -任务记录持久化在 SQLite 中，路径为： +任务记录会持久化到以下 SQLite 位置： ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -注册表会在 Gateway 网关 启动时加载到内存中，并将写入同步到 SQLite，以便在重启后仍能保持持久性。 +注册表会在 Gateway 网关启动时加载到内存中，并将写入同步到 SQLite，以便在重启后仍具备持久性。 ### 自动维护 -每 **60 秒** 会运行一次清理器，处理三件事： +清扫器每 **60 秒**运行一次，并处理三件事： -1. **对账**——检查活动任务是否仍然具有权威的运行时后端。ACP / 子智能体任务使用子会话状态，cron 任务使用活动作业归属，基于聊天的 CLI 任务使用其所属运行上下文。如果该后端状态消失超过 5 分钟，任务会被标记为 `lost`。 -2. **清理时间戳写入**——为终态任务设置 `cleanupAfter` 时间戳（`endedAt + 7 days`）。 -3. **清理删除**——删除已超过其 `cleanupAfter` 日期的记录。 +1. **协调**——检查活动任务是否仍有权威性的运行时支撑。ACP / 子智能体任务使用子会话状态，cron 任务使用活动作业所有权，而基于聊天的 CLI 任务使用所属运行上下文。如果该支撑状态消失超过 5 分钟，则任务会被标记为 `lost`。 +2. **清理时间戳记录**——为终态任务设置 `cleanupAfter` 时间戳（`endedAt + 7 days`）。 +3. **清理删除**——删除超过其 `cleanupAfter` 日期的记录。 -**保留期**：终态任务记录会保留 **7 天**，之后自动清理。无需任何配置。 +**保留期**：终态任务记录会保留 **7 天**，然后自动清理。无需任何配置。 ## 任务与其他系统的关系 ### 任务与 Task Flow -[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个 flow 在其生命周期内可以通过托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排 flow。 +[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个流程在其生命周期内可能通过受管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排中的流程。 -详情请参阅 [Task Flow](/zh-CN/automation/taskflow)。 +详见 [Task Flow](/zh-CN/automation/taskflow)。 ### 任务与 cron -cron 作业**定义**存储在 `~/.openclaw/cron/jobs.json` 中。**每一次** cron 执行都会创建一条任务记录——无论是主会话还是隔离式执行。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪，但不会生成通知。 +cron 作业的**定义**位于 `~/.openclaw/cron/jobs.json`。**每次** cron 执行都会创建任务记录——无论是主会话模式还是隔离模式。主会话 cron 任务默认使用 `silent` 通知策略，因此它们只做跟踪，不生成通知。 参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。 ### 任务与 heartbeat -Heartbeat 运行属于主会话轮次——它们不会创建任务记录。任务完成时，可以触发 heartbeat 唤醒，以便你及时看到结果。 +Heartbeat 运行属于主会话回合——它们不会创建任务记录。当任务完成时，它可以触发 heartbeat 唤醒，让你及时看到结果。 参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 ### 任务与会话 -一个任务可能会引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（启动它的人）。会话是对话上下文；任务则是在其之上的活动跟踪。 +一个任务可能会引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（发起者）。会话是对话上下文；任务则是在其之上的活动跟踪。 ### 任务与智能体运行 -任务的 `runId` 会链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态——你无需手动管理生命周期。 +任务的 `runId` 会链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态——你不需要手动管理生命周期。 ## 相关内容 -- [自动化与任务](/zh-CN/automation)——所有自动化机制总览 +- [自动化与任务](/zh-CN/automation)——所有自动化机制一览 - [Task Flow](/zh-CN/automation/taskflow)——位于任务之上的流程编排 - [计划任务](/zh-CN/automation/cron-jobs)——调度后台工作 -- [Heartbeat](/zh-CN/gateway/heartbeat)——周期性主会话轮次 +- [Heartbeat](/zh-CN/gateway/heartbeat)——周期性的主会话回合 - [CLI：任务](/cli/index#tasks)——CLI 命令参考 diff --git a/docs/zh-CN/channels/matrix.md b/docs/zh-CN/channels/matrix.md index 7b50fc3f6..84a72a635 100644 --- a/docs/zh-CN/channels/matrix.md +++ b/docs/zh-CN/channels/matrix.md @@ -5,10 +5,10 @@ read_when: summary: Matrix 支持状态、设置和配置示例 title: Matrix x-i18n: - generated_at: "2026-04-05T22:31:55Z" + generated_at: "2026-04-06T00:21:45Z" model: gpt-5.4 provider: openai - source_hash: ddd4f14094388b1a4cd542a5956fcf47f7d6734b7a11fde1d6125b3f0d7202c9 + source_hash: 5506f966d78d5f09d597c4850088f8ee1c91cf4d5f6a7b5cade80d89b5bdf1bc source_path: channels/matrix.md workflow: 15 --- @@ -16,13 +16,13 @@ x-i18n: # Matrix Matrix 是 OpenClaw 的 Matrix 内置渠道插件。 -它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、表情回应、投票、位置和 E2EE。 +它使用官方的 `matrix-js-sdk`，并支持私信、房间、线程、媒体、反应、投票、位置和 E2EE。 ## 内置插件 -Matrix 作为当前 OpenClaw 版本中的内置插件发布，因此普通的打包构建不需要单独安装。 +Matrix 作为内置插件随当前的 OpenClaw 版本一起提供，因此普通的打包构建不需要单独安装。 -如果你使用的是较旧版本，或排除了 Matrix 的自定义安装，请手动安装： +如果你使用的是较旧的构建版本，或者使用了排除 Matrix 的自定义安装，请手动安装： 从 npm 安装： @@ -36,19 +36,19 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -有关插件行为和安装规则，请参阅 [插件](/zh-CN/tools/plugin)。 +有关插件行为和安装规则，请参阅 [Plugins](/zh-CN/tools/plugin)。 ## 设置 1. 确保 Matrix 插件可用。 - - 当前打包的 OpenClaw 版本已内置该插件。 - - 较旧版本或自定义安装可以使用上述命令手动添加。 + - 当前打包的 OpenClaw 版本已内置它。 + - 较旧/自定义安装可以使用上面的命令手动添加它。 2. 在你的 homeserver 上创建一个 Matrix 账户。 3. 使用以下任一方式配置 `channels.matrix`： - `homeserver` + `accessToken`，或 - `homeserver` + `userId` + `password`。 4. 重启 Gateway 网关。 -5. 与机器人发起私信，或邀请它加入房间。 +5. 与机器人开始私信，或邀请它加入一个房间。 交互式设置路径： @@ -57,23 +57,23 @@ openclaw channels add openclaw configure --section channels ``` -Matrix 向导实际会询问以下内容： +Matrix 向导实际会询问的内容： - homeserver URL - 认证方式：访问令牌或密码 - 仅当你选择密码认证时才需要用户 ID -- 可选的设备名称 +- 可选设备名称 - 是否启用 E2EE - 是否现在配置 Matrix 房间访问 需要注意的向导行为： -- 如果所选账户已存在 Matrix 认证环境变量，并且该账户的认证信息尚未保存到配置中，向导会提供环境变量快捷方式，并且只会为该账户写入 `enabled: true`。 -- 当你以交互方式添加另一个 Matrix 账户时，输入的账户名称会被规范化为配置和环境变量中使用的账户 ID。例如，`Ops Bot` 会变成 `ops-bot`。 -- 私信允许列表提示可立即接受完整的 `@user:server` 值。显示名称仅在实时目录查找找到唯一精确匹配时才有效；否则向导会要求你使用完整的 Matrix ID 重试。 -- 房间允许列表提示可直接接受房间 ID 和别名。它们也可以实时解析已加入房间的名称，但在设置期间无法解析的名称只会按原样保留，后续会被运行时允许列表解析忽略。建议优先使用 `!room:server` 或 `#alias:server`。 -- 运行时的房间/会话标识使用稳定的 Matrix 房间 ID。房间声明的别名仅用作查找输入，不会作为长期会话键或稳定群组标识。 -- 若要在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 +- 如果所选账户已存在 Matrix 认证环境变量，且该账户尚未在配置中保存认证信息，向导会提供一个环境变量快捷方式，并且只会为该账户写入 `enabled: true`。 +- 当你以交互方式添加另一个 Matrix 账户时，输入的账户名称会被规范化为配置和环境变量中使用的账户 ID。例如，`Ops Bot` 会变为 `ops-bot`。 +- 私信允许列表提示可立即接受完整的 `@user:server` 值。显示名称仅在实时目录查找找到一个精确匹配时可用；否则向导会要求你使用完整的 Matrix ID 重试。 +- 房间允许列表提示可直接接受房间 ID 和别名。它们也可以实时解析已加入房间的名称，但在设置期间无法解析的名称只会按输入原样保留，之后会被运行时允许列表解析忽略。优先使用 `!room:server` 或 `#alias:server`。 +- 运行时房间/会话标识使用稳定的 Matrix 房间 ID。房间声明的别名仅用作查找输入，不会作为长期会话键或稳定的群组标识。 +- 如需在保存前解析房间名称，请使用 `openclaw channels resolve --channel matrix "Project Room"`。 基于令牌的最小设置： @@ -106,10 +106,11 @@ Matrix 向导实际会询问以下内容： } ``` -Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 +Matrix 将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 默认账户使用 `credentials.json`；命名账户使用 `credentials-.json`。 +当那里存在缓存凭证时，即使当前认证未直接在配置中设置，OpenClaw 也会在设置、Doctor 和渠道状态发现中将 Matrix 视为已配置。 -对应的环境变量（在未设置配置键时使用）： +环境变量等价项（当未设置配置键时使用）： - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -118,7 +119,7 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -对于非默认账户，请使用按账户作用域划分的环境变量： +对于非默认账户，请使用带账户作用域的环境变量： - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -132,15 +133,15 @@ Matrix 会将缓存的凭证存储在 `~/.openclaw/credentials/matrix/` 中。 - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -对于规范化后的账户 ID `ops-bot`，请使用： +对于规范化账户 ID `ops-bot`，请使用： - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` Matrix 会对账户 ID 中的标点进行转义，以避免带作用域的环境变量发生冲突。 -例如，`-` 会变成 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。 +例如，`-` 会变为 `_X2D_`，因此 `ops-prod` 会映射为 `MATRIX_OPS_X2D_PROD_*`。 -只有当这些认证环境变量已存在，且所选账户尚未在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。 +仅当这些认证环境变量已存在，且所选账户尚未在配置中保存 Matrix 认证信息时，交互式向导才会提供环境变量快捷方式。 ## 配置示例 @@ -181,9 +182,9 @@ Matrix 会对账户 ID 中的标点进行转义，以避免带作用域的环境 ## 流式预览 -Matrix 回复流式传输为选择启用功能。 +Matrix 回复流式传输为可选启用。 -当你希望 OpenClaw 发送单条实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成后将其最终定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： +当你希望 OpenClaw 发送一条实时预览回复、在模型生成文本时原地编辑该预览，并在回复完成时将其定稿时，请将 `channels.matrix.streaming` 设置为 `"partial"`： ```json5 { @@ -196,34 +197,34 @@ Matrix 回复流式传输为选择启用功能。 ``` - `streaming: "off"` 是默认值。OpenClaw 会等待最终回复并一次性发送。 -- `streaming: "partial"` 会为当前助手消息块创建一条可编辑的预览消息，并使用普通 Matrix 文本消息。这会保留 Matrix 旧式的“先预览后完成”通知行为，因此标准客户端可能会在第一段流式预览文本出现时通知，而不是在最终完成的消息块出现时通知。 -- `streaming: "quiet"` 会为当前助手消息块创建一条可编辑的静默预览通知。仅当你还为最终完成的预览编辑配置了接收方推送规则时才使用此选项。 -- `blockStreaming: true` 会启用独立的 Matrix 进度消息。启用预览流式传输后，Matrix 会保留当前消息块的实时草稿，并将已完成的消息块保留为单独消息。 -- 当启用预览流式传输且 `blockStreaming` 为关闭状态时，Matrix 会原地编辑实时草稿，并在消息块或整个轮次结束时最终完成该事件。 -- 如果预览内容已无法放入单个 Matrix 事件中，OpenClaw 会停止预览流式传输并回退到普通的最终发送方式。 -- 媒体回复仍会正常发送附件。如果过期预览已无法安全复用，OpenClaw 会在发送最终媒体回复前将其撤回。 +- `streaming: "partial"` 会为当前智能体块创建一条可编辑的预览消息，并使用普通 Matrix 文本消息。这会保留 Matrix 传统的“先预览后通知”行为，因此标准客户端可能会对第一段流式预览文本发出通知，而不是对完成后的内容块发出通知。 +- `streaming: "quiet"` 会为当前智能体块创建一条可编辑的静默预览通知。仅当你还为已完成的预览编辑配置了接收者推送规则时，才使用此选项。 +- `blockStreaming: true` 会启用单独的 Matrix 进度消息。启用预览流式传输后，Matrix 会保留当前块的实时草稿，并将已完成的块保留为单独消息。 +- 当预览流式传输开启且 `blockStreaming` 关闭时，Matrix 会原地编辑实时草稿，并在块或轮次结束时将同一事件定稿。 +- 如果预览内容不再适合放入单个 Matrix 事件，OpenClaw 会停止预览流式传输并回退到普通最终发送。 +- 媒体回复仍会正常发送附件。如果过期预览无法再安全复用，OpenClaw 会在发送最终媒体回复之前将其删除。 - 预览编辑会产生额外的 Matrix API 调用。如果你希望采用最保守的速率限制行为，请保持关闭流式传输。 `blockStreaming` 本身不会启用草稿预览。 -请使用 `streaming: "partial"` 或 `streaming: "quiet"` 来启用预览编辑；如果你还希望已完成的助手消息块以单独进度消息形式保留，再额外添加 `blockStreaming: true`。 +请使用 `streaming: "partial"` 或 `streaming: "quiet"` 进行预览编辑；如果你还希望已完成的智能体块作为单独的进度消息保留可见，再额外添加 `blockStreaming: true`。 -如果你需要标准 Matrix 通知而不配置自定义推送规则，请使用 `streaming: "partial"` 获得“先预览后完成”的行为，或者保持 `streaming` 关闭以仅发送最终内容。对于 `streaming: "off"`： +如果你需要标准 Matrix 通知而不想配置自定义推送规则，请使用 `streaming: "partial"` 以获得“先预览”行为，或者保持 `streaming` 关闭以仅在最终完成时发送。使用 `streaming: "off"` 时： -- `blockStreaming: true` 会将每个已完成的消息块作为普通的会通知 Matrix 消息发送。 -- `blockStreaming: false` 只会将最终完成的回复作为普通的会通知 Matrix 消息发送。 +- `blockStreaming: true` 会将每个已完成的块作为普通可通知的 Matrix 消息发送。 +- `blockStreaming: false` 仅发送最终完成的回复，作为普通可通知的 Matrix 消息。 -### 自托管静默最终预览的推送规则 +### 自托管静默定稿预览的推送规则 -如果你运行的是自己的 Matrix 基础设施，并希望静默预览仅在消息块或最终回复完成时通知，请设置 `streaming: "quiet"`，并为最终完成的预览编辑添加每用户推送规则。 +如果你运行自己的 Matrix 基础设施，并希望静默预览仅在一个块或最终回复完成时才通知，请设置 `streaming: "quiet"`，并为已定稿的预览编辑添加按用户划分的推送规则。 -这通常是接收方用户的设置，而不是 homeserver 全局配置变更： +这通常是接收用户侧的设置，而不是 homeserver 全局配置更改： -开始前的快速对应关系： +开始前的快速说明： -- recipient user = 应接收通知的人 -- bot user = 发送回复的 OpenClaw Matrix 账户 -- 对下面的 API 调用使用接收方用户的访问令牌 -- 在推送规则中将 `sender` 与机器人用户的完整 MXID 进行匹配 +- 接收用户 = 应该收到通知的人 +- 机器人用户 = 发送回复的 OpenClaw Matrix 账户 +- 对以下 API 调用使用接收用户的访问令牌 +- 在推送规则中将 `sender` 与机器人用户的完整 MXID 匹配 1. 配置 OpenClaw 使用静默预览： @@ -237,11 +238,11 @@ Matrix 回复流式传输为选择启用功能。 } ``` -2. 确保接收方账户已经能收到普通的 Matrix 推送通知。静默预览规则只有在该用户已有正常工作的 pusher/设备时才会生效。 +2. 确保接收账户已经可以接收普通 Matrix 推送通知。静默预览规则仅在该用户已有正常工作的推送器/设备时才有效。 -3. 获取接收方用户的访问令牌。 - - 使用接收消息用户的令牌，而不是机器人的令牌。 - - 复用现有客户端会话令牌通常是最简单的方式。 +3. 获取接收用户的访问令牌。 + - 使用接收用户的令牌，而不是机器人的令牌。 + - 复用现有客户端会话令牌通常最简单。 - 如果你需要签发一个新的令牌，可以通过标准 Matrix Client-Server API 登录： ```bash @@ -258,7 +259,7 @@ curl -sS -X POST \ }' ``` -4. 验证接收方账户是否已存在 pusher： +4. 验证接收账户已经具有推送器： ```bash curl -sS \ @@ -266,9 +267,9 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -如果这里没有返回活动的 pusher/设备，请先修复普通 Matrix 通知，再添加下面的 OpenClaw 规则。 +如果这里没有返回活动的推送器/设备，请先修复普通 Matrix 通知，然后再添加下面的 OpenClaw 规则。 -OpenClaw 会为已最终完成的纯文本预览编辑打上以下标记： +OpenClaw 会用以下标记标识已定稿的纯文本预览编辑： ```json { @@ -276,7 +277,7 @@ OpenClaw 会为已最终完成的纯文本预览编辑打上以下标记： } ``` -5. 为每个应收到这类通知的接收方账户创建一个 override 推送规则： +5. 为每个应接收这些通知的接收账户创建一条覆盖推送规则： ```bash curl -sS -X PUT \ @@ -306,18 +307,18 @@ curl -sS -X PUT \ }' ``` -在运行命令前，请替换以下值： +运行命令前请替换以下值： - `https://matrix.example.org`：你的 homeserver 基础 URL -- `$USER_ACCESS_TOKEN`：接收方用户的访问令牌 -- `@bot:example.org`：你的 OpenClaw Matrix 机器人 MXID，而不是接收方用户的 MXID +- `$USER_ACCESS_TOKEN`：接收用户的访问令牌 +- `@bot:example.org`：你的 OpenClaw Matrix 机器人 MXID，而不是接收用户的 MXID 该规则会根据事件发送者进行评估： -- 使用接收方用户的令牌进行认证 -- 将 `sender` 与 OpenClaw 机器人 MXID 进行匹配 +- 使用接收用户的令牌进行认证 +- 将 `sender` 与 OpenClaw 机器人 MXID 匹配 -6. 验证规则是否存在： +6. 验证该规则是否存在： ```bash curl -sS \ @@ -325,41 +326,41 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview" ``` -7. 测试一次流式回复。在静默模式下，房间应显示一条静默草稿预览，而最终的原地编辑会在消息块或轮次完成时触发一次通知。 +7. 测试一条流式回复。在静默模式下，房间应显示一条静默草稿预览，而最终的原地编辑应在块或轮次结束时通知一次。 说明： -- 请使用接收方用户的访问令牌创建规则，而不是机器人的。 -- 新建的用户自定义 `override` 规则会插入到默认抑制规则之前，因此不需要额外的排序参数。 -- 这仅影响 OpenClaw 可安全原地最终完成的纯文本预览编辑。媒体回退和过期预览回退仍使用普通 Matrix 发送方式。 -- 如果 `GET /_matrix/client/v3/pushers` 显示没有 pusher，则表示该用户的此账户/设备尚未启用正常工作的 Matrix 推送投递。 +- 请使用接收用户的访问令牌创建规则，而不是机器人的令牌。 +- 新的用户定义 `override` 规则会插入到默认抑制规则之前，因此不需要额外的排序参数。 +- 这仅影响 OpenClaw 可以安全原地定稿的纯文本预览编辑。媒体回退和过期预览回退仍使用普通 Matrix 发送。 +- 如果 `GET /_matrix/client/v3/pushers` 显示没有推送器，则该用户尚未为此账户/设备启用正常工作的 Matrix 推送传递。 #### Synapse 对于 Synapse，上述设置通常本身就足够： -- 不需要为 OpenClaw 最终预览通知做特殊的 `homeserver.yaml` 变更。 -- 如果你的 Synapse 部署已经能发送普通 Matrix 推送通知，那么用户令牌加上上面的 `pushrules` 调用就是主要设置步骤。 -- 如果你在反向代理或 worker 后运行 Synapse，请确保 `/_matrix/client/.../pushrules/` 能正确到达 Synapse。 -- 如果你使用 Synapse worker，请确保 pusher 运行健康。推送投递由主进程或 `synapse.app.pusher` / 已配置的 pusher worker 处理。 +- 无需为已定稿的 OpenClaw 预览通知做任何特殊的 `homeserver.yaml` 更改。 +- 如果你的 Synapse 部署已经能发送普通 Matrix 推送通知，那么上面的用户令牌 + `pushrules` 调用就是主要设置步骤。 +- 如果你在反向代理或 workers 后面运行 Synapse，请确保 `/_matrix/client/.../pushrules/` 能正确到达 Synapse。 +- 如果你运行 Synapse workers，请确保 pushers 状态健康。推送传递由主进程或 `synapse.app.pusher` / 已配置的 pusher workers 处理。 #### Tuwunel -对于 Tuwunel，请使用上面展示的相同设置流程和推送规则 API 调用： +对于 Tuwunel，请使用与上方相同的设置流程和 push-rule API 调用： -- 最终预览标记本身不需要 Tuwunel 专用配置。 -- 如果该用户的普通 Matrix 通知已经正常工作，那么用户令牌加上上面的 `pushrules` 调用就是主要设置步骤。 -- 如果通知看起来会在用户于另一台设备活跃时消失，请检查是否启用了 `suppress_push_when_active`。Tuwunel 在 2025 年 9 月 12 日发布的 Tuwunel 1.4.2 中添加了此选项，它可能会有意在一台设备活跃时抑制向其他设备推送。 +- 对于已定稿预览标记本身，不需要任何 Tuwunel 特定配置。 +- 如果该用户的普通 Matrix 通知已经正常工作，那么上面的用户令牌 + `pushrules` 调用就是主要设置步骤。 +- 如果当用户在另一台设备上活跃时通知似乎消失，请检查是否启用了 `suppress_push_when_active`。Tuwunel 在 2025 年 9 月 12 日发布的 Tuwunel 1.4.2 中添加了此选项，它可能会在一台设备处于活跃状态时，有意抑制发送到其他设备的推送。 -## 加密与验证 +## 加密和验证 -在加密的（E2EE）房间中，出站图片事件使用 `thumbnail_file`，因此图片预览会与完整附件一起加密。未加密房间仍使用纯文本的 `thumbnail_url`。无需配置——插件会自动检测 E2EE 状态。 +在加密（E2EE）房间中，出站图片事件使用 `thumbnail_file`，因此图片预览会与完整附件一起加密。未加密房间仍使用普通的 `thumbnail_url`。无需配置 —— 插件会自动检测 E2EE 状态。 -### 机器人到机器人房间 +### 机器人对机器人房间 默认情况下，来自其他已配置 OpenClaw Matrix 账户的 Matrix 消息会被忽略。 -当你确实需要智能体之间的 Matrix 通信时，请使用 `allowBots`： +当你有意启用智能体之间的 Matrix 通信时，请使用 `allowBots`： ```json5 { @@ -377,12 +378,12 @@ curl -sS \ ``` - `allowBots: true` 会在允许的房间和私信中接受来自其他已配置 Matrix 机器人账户的消息。 -- `allowBots: "mentions"` 仅在这些消息在房间中明确提及此机器人时接受。私信仍然允许。 -- `groups..allowBots` 可覆盖某个房间的账户级设置。 +- `allowBots: "mentions"` 仅当这些消息在房间中明确提及此机器人时才接受。私信仍然允许。 +- `groups..allowBots` 会覆盖单个房间的账户级设置。 - OpenClaw 仍会忽略来自同一 Matrix 用户 ID 的消息，以避免自回复循环。 -- Matrix 在这里不提供原生机器人标记；OpenClaw 将“机器人发送”视为“由此 OpenClaw Gateway 网关上另一已配置 Matrix 账户发送”。 +- Matrix 在这里不提供原生机器人标记；OpenClaw 将“机器人撰写”视为“由此 OpenClaw Gateway 网关上的另一个已配置 Matrix 账户发送”。 -在共享房间中启用机器人到机器人通信时，请使用严格的房间允许列表和提及要求。 +在共享房间中启用机器人到机器人流量时，请使用严格的房间允许列表和提及要求。 启用加密： @@ -424,7 +425,7 @@ openclaw matrix verify status --include-recovery-key --json openclaw matrix verify bootstrap ``` -多账户支持：使用 `channels.matrix.accounts` 配置每个账户的凭证和可选的 `name`。共享模式请参阅 [配置参考](/zh-CN/gateway/configuration-reference#multi-account-all-channels)。 +多账户支持：使用 `channels.matrix.accounts` 配置每个账户的凭证和可选 `name`。共享模式请参阅 [Configuration reference](/zh-CN/gateway/configuration-reference#multi-account-all-channels)。 详细引导诊断： @@ -432,7 +433,7 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -在引导前强制重置全新的交叉签名身份： +在引导前强制执行全新的交叉签名身份重置： ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -444,7 +445,7 @@ openclaw matrix verify bootstrap --force-reset-cross-signing openclaw matrix verify device "" ``` -详细的设备验证信息： +详细设备验证信息： ```bash openclaw matrix verify device "" --verbose @@ -456,7 +457,7 @@ openclaw matrix verify device "" --verbose openclaw matrix verify backup status ``` -详细的备份健康诊断： +详细备份健康诊断： ```bash openclaw matrix verify backup status --verbose @@ -468,24 +469,24 @@ openclaw matrix verify backup status --verbose openclaw matrix verify backup restore ``` -详细的恢复诊断： +详细恢复诊断： ```bash openclaw matrix verify backup restore --verbose ``` -删除当前服务器备份并创建新的备份基线。如果无法干净地加载已存储的备份密钥，此重置还可以重新创建秘密存储，以便未来冷启动时能加载新的备份密钥： +删除当前服务器备份并创建全新的备份基线。如果无法干净地加载已存储的备份密钥，此重置还可以重新创建秘密存储，以便未来的冷启动可以加载新的备份密钥： ```bash openclaw matrix verify backup reset --yes ``` -所有 `verify` 命令默认都很简洁（包括安静的内部 SDK 日志），仅在使用 `--verbose` 时显示详细诊断。 -编写脚本时请使用 `--json` 以获得完整的机器可读输出。 +所有 `verify` 命令默认都很简洁（包括安静的内部 SDK 日志），只有在使用 `--verbose` 时才显示详细诊断。 +在脚本中使用时，请使用 `--json` 以获取完整的机器可读输出。 -在多账户设置中，如果你未传递 `--account `，Matrix CLI 命令会使用隐式的 Matrix 默认账户。 -如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作将停止并要求你明确选择账户。 -当你希望验证或设备操作明确针对某个命名账户时，请使用 `--account`： +在多账户设置中，除非你传递 `--account `，否则 Matrix CLI 命令会使用隐式的 Matrix 默认账户。 +如果你配置了多个命名账户，请先设置 `channels.matrix.defaultAccount`，否则这些隐式 CLI 操作将停止并要求你显式选择一个账户。 +当你希望验证或设备操作显式针对某个命名账户时，请使用 `--account`： ```bash openclaw matrix verify status --account assistant @@ -493,40 +494,40 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -当某个命名账户的加密被禁用或不可用时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 +当某个命名账户禁用了加密或加密不可用时，Matrix 警告和验证错误会指向该账户的配置键，例如 `channels.matrix.accounts.assistant.encryption`。 -### “已验证”的含义 +### “已验证”是什么意思 -只有当此 Matrix 设备被你自己的交叉签名身份验证后，OpenClaw 才会将其视为已验证。 +只有当此 Matrix 设备由你自己的交叉签名身份验证后，OpenClaw 才会将其视为已验证。 实际上，`openclaw matrix verify status --verbose` 会暴露三个信任信号： - `Locally trusted`：此设备仅被当前客户端信任 - `Cross-signing verified`：SDK 报告该设备已通过交叉签名验证 -- `Signed by owner`：该设备已由你自己的自签名密钥签名 +- `Signed by owner`：该设备由你自己的自签名密钥签名 只有在存在交叉签名验证或所有者签名时，`Verified by owner` 才会变为 `yes`。 -仅有本地信任还不足以让 OpenClaw 将该设备视为完全已验证。 +仅有本地信任不足以让 OpenClaw 将设备视为完全已验证。 -### 引导会执行什么 +### bootstrap 的作用 -`openclaw matrix verify bootstrap` 是用于修复和设置加密 Matrix 账户的命令。 -它会按顺序执行以下所有操作： +`openclaw matrix verify bootstrap` 是用于加密 Matrix 账户的修复和设置命令。 +它会按顺序完成以下所有操作： -- 引导秘密存储，并尽可能复用现有恢复密钥 +- 引导秘密存储，并在可能时复用现有恢复密钥 - 引导交叉签名并上传缺失的公开交叉签名密钥 - 尝试标记并交叉签名当前设备 -- 如果服务器端尚不存在房间密钥备份，则创建一个新的备份 +- 如果尚不存在，则创建新的服务器端房间密钥备份 -如果 homeserver 要求交互式认证才能上传交叉签名密钥，OpenClaw 会先尝试无认证上传，然后尝试使用 `m.login.dummy`，当配置了 `channels.matrix.password` 时再尝试使用 `m.login.password`。 +如果 homeserver 要求交互式认证以上传交叉签名密钥，OpenClaw 会先尝试不带认证上传，然后尝试 `m.login.dummy`，如果配置了 `channels.matrix.password`，则再尝试 `m.login.password`。 -仅当你明确希望丢弃当前交叉签名身份并创建新身份时，才使用 `--force-reset-cross-signing`。 +仅当你有意丢弃当前交叉签名身份并创建一个新的身份时，才使用 `--force-reset-cross-signing`。 -如果你明确希望丢弃当前房间密钥备份，并为未来消息建立新的备份基线，请使用 `openclaw matrix verify backup reset --yes`。 -仅当你接受无法恢复的旧加密历史将继续不可用，并且接受 OpenClaw 可能在无法安全加载当前备份秘密时重新创建秘密存储时，才应这样做。 +如果你有意丢弃当前房间密钥备份，并为未来消息开始一个新的备份基线，请使用 `openclaw matrix verify backup reset --yes`。 +只有在你接受无法恢复的旧加密历史将继续不可用，并且接受 OpenClaw 可能在当前备份密钥无法安全加载时重新创建秘密存储的情况下，才这样做。 -### 全新的备份基线 +### 全新备份基线 -如果你希望未来的加密消息继续正常工作，并接受失去无法恢复的旧历史，请按顺序运行以下命令： +如果你希望未来的加密消息继续正常工作，并接受丢失无法恢复的旧历史，请按顺序运行以下命令： ```bash openclaw matrix verify backup reset --yes @@ -534,59 +535,59 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -当你希望明确针对某个命名 Matrix 账户时，请为每个命令添加 `--account `。 +当你希望显式针对某个命名 Matrix 账户时，请为每条命令添加 `--account `。 ### 启动行为 -当 `encryption: true` 时，Matrix 默认将 `startupVerification` 设为 `"if-unverified"`。 -在启动时，如果此设备仍未验证，Matrix 会在另一个 Matrix 客户端中请求自验证，在已有待处理请求时跳过重复请求，并在重启后重试前应用本地冷却时间。 -默认情况下，创建请求成功后的重试间隔会比请求失败后的重试间隔更长。 -如果你想禁用自动启动请求，请设置 `startupVerification: "off"`；如果你想缩短或延长重试窗口，请调整 `startupVerificationCooldownHours`。 +当 `encryption: true` 时，Matrix 默认将 `startupVerification` 设置为 `"if-unverified"`。 +启动时，如果此设备仍未验证，Matrix 将在另一个 Matrix 客户端中请求自验证，在已有待处理请求时跳过重复请求，并在重启后重试前应用本地冷却时间。 +默认情况下，失败的请求尝试会比成功创建请求后更快重试。 +将 `startupVerification: "off"` 设置为禁用自动启动请求，或者调整 `startupVerificationCooldownHours` 以获得更短或更长的重试窗口。 启动时还会自动执行一次保守的加密引导流程。 -该流程会优先尝试复用当前的秘密存储和交叉签名身份，并避免重置交叉签名，除非你运行显式的引导修复流程。 +该流程会优先尝试复用当前秘密存储和交叉签名身份，并避免重置交叉签名，除非你运行显式的引导修复流程。 -如果启动时发现损坏的引导状态，并且已配置 `channels.matrix.password`，OpenClaw 可以尝试更严格的修复路径。 -如果当前设备已经带有所有者签名，OpenClaw 会保留该身份，而不是自动重置它。 +如果启动时发现引导状态损坏，且已配置 `channels.matrix.password`，OpenClaw 可以尝试更严格的修复路径。 +如果当前设备已经由所有者签名，OpenClaw 会保留该身份，而不是自动重置它。 -从之前公开的 Matrix 插件升级时： +从之前公开的 Matrix 插件升级： - OpenClaw 会在可能的情况下自动复用同一个 Matrix 账户、访问令牌和设备身份。 -- 在执行任何可操作的 Matrix 迁移变更之前，OpenClaw 会在 `~/Backups/openclaw-migrations/` 下创建或复用恢复快照。 +- 在运行任何可操作的 Matrix 迁移更改之前，OpenClaw 会在 `~/Backups/openclaw-migrations/` 下创建或复用恢复快照。 - 如果你使用多个 Matrix 账户，请在从旧的平面存储布局升级前设置 `channels.matrix.defaultAccount`，这样 OpenClaw 才知道应将共享的旧状态分配给哪个账户。 - 如果之前的插件在本地存储了 Matrix 房间密钥备份解密密钥，启动时或运行 `openclaw doctor --fix` 时会自动将其导入新的恢复密钥流程。 -- 如果在准备迁移后 Matrix 访问令牌发生变化，启动时现在会在放弃自动备份恢复前扫描同级 token-hash 存储根目录，查找待恢复的旧状态。 -- 如果同一账户、homeserver 和用户的 Matrix 访问令牌之后再次变化，OpenClaw 现在会优先复用该账户/homeserver/用户组合下最完整的现有 token-hash 存储根目录，而不是从空的 Matrix 状态目录开始。 -- 在下次 Gateway 网关启动时，已备份的房间密钥会自动恢复到新的加密存储中。 -- 如果旧插件中存在从未备份过的仅本地房间密钥，OpenClaw 会明确发出警告。由于这些密钥无法从之前的 rust 加密存储中自动导出，因此在手动恢复之前，一些旧的加密历史可能仍然不可用。 -- 完整的升级流程、限制、恢复命令和常见迁移消息，请参阅 [Matrix 迁移](/zh-CN/install/migrating-matrix)。 +- 如果在准备迁移之后 Matrix 访问令牌发生了变化，启动时现在会扫描同级 token-hash 存储根目录，以查找待恢复的旧状态，然后才会放弃自动备份恢复。 +- 如果同一账户、homeserver 和用户的 Matrix 访问令牌之后再次更改，OpenClaw 现在会优先复用最完整的现有 token-hash 存储根目录，而不是从空的 Matrix 状态目录开始。 +- 在下一次 Gateway 网关启动时，已备份的房间密钥会自动恢复到新的加密存储中。 +- 如果旧插件中存在从未备份过的仅本地房间密钥，OpenClaw 会明确发出警告。由于这些密钥无法从之前的 rust 加密存储中自动导出，因此某些旧的加密历史在手动恢复之前可能仍不可用。 +- 完整升级流程、限制、恢复命令和常见迁移消息，请参阅 [Matrix migration](/zh-CN/install/migrating-matrix)。 -加密运行时状态按账户、用户和 token-hash 根目录组织，路径为 +加密运行时状态按每个账户、每个用户的 token-hash 根目录组织，位于 `~/.openclaw/matrix/accounts//__//`。 -当这些功能被使用时，该目录包含同步存储（`bot-storage.json`）、加密存储（`crypto/`）、 +该目录在这些功能被使用时包含同步存储（`bot-storage.json`）、加密存储（`crypto/`）、 恢复密钥文件（`recovery-key.json`）、IndexedDB 快照（`crypto-idb-snapshot.json`）、 -线程绑定（`thread-bindings.json`）以及启动验证状态（`startup-verification.json`）。 -当令牌变化但账户身份保持不变时，OpenClaw 会为该账户/homeserver/用户组合复用最佳现有根目录，以便先前的同步状态、加密状态、线程绑定和启动验证状态继续可见。 +线程绑定（`thread-bindings.json`）和启动验证状态（`startup-verification.json`）。 +当令牌变化但账户身份保持不变时，OpenClaw 会为该 account/homeserver/user 元组复用最佳的现有根目录，因此先前的同步状态、加密状态、线程绑定和启动验证状态仍然可见。 ### Node 加密存储模型 -此插件中的 Matrix E2EE 在 Node 中使用官方 `matrix-js-sdk` 的 Rust 加密路径。 -当你希望加密状态在重启后仍然保留时，该路径需要基于 IndexedDB 的持久化。 +此插件中的 Matrix E2EE 在 Node 中使用官方 `matrix-js-sdk` Rust 加密路径。 +当你希望加密状态在重启后仍能保留时，该路径需要基于 IndexedDB 的持久化。 -OpenClaw 目前在 Node 中通过以下方式提供支持： +OpenClaw 目前在 Node 中通过以下方式提供该能力： -- 使用 `fake-indexeddb` 作为 SDK 所需的 IndexedDB API shim +- 使用 `fake-indexeddb` 作为 SDK 所期望的 IndexedDB API shim - 在 `initRustCrypto` 之前，从 `crypto-idb-snapshot.json` 恢复 Rust 加密 IndexedDB 内容 -- 在初始化后和运行期间，将更新后的 IndexedDB 内容持久化回 `crypto-idb-snapshot.json` -- 通过建议性文件锁对 `crypto-idb-snapshot.json` 的快照恢复和持久化进行串行化，以避免 Gateway 网关运行时持久化和 CLI 维护在同一快照文件上发生竞争 +- 在初始化之后和运行时，将更新后的 IndexedDB 内容持久化回 `crypto-idb-snapshot.json` +- 使用建议性文件锁对 `crypto-idb-snapshot.json` 的快照恢复和持久化进行串行化，以避免 Gateway 网关运行时持久化与 CLI 维护在同一快照文件上发生竞争 -这是兼容性/存储层处理，不是自定义加密实现。 +这是兼容性/存储层面的处理，不是自定义加密实现。 该快照文件属于敏感运行时状态，并以严格的文件权限存储。 -在 OpenClaw 的安全模型下，Gateway 网关主机和本地 OpenClaw 状态目录已经位于受信任的操作员边界内，因此这主要是运行可靠性问题，而不是单独的远程信任边界。 +在 OpenClaw 的安全模型下，Gateway 网关主机和本地 OpenClaw 状态目录已经位于受信任的操作员边界内，因此这主要是一个操作层面的持久性问题，而不是单独的远程信任边界。 计划中的改进： -- 为持久化的 Matrix 密钥材料添加 SecretRef 支持，以便恢复密钥和相关的存储加密秘密可以来自 OpenClaw 秘密提供商，而不仅限于本地文件 +- 为持久化 Matrix 密钥材料添加 SecretRef 支持，以便恢复密钥和相关的存储加密密钥可以来自 OpenClaw secrets providers，而不仅仅是本地文件 ## 配置文件管理 @@ -597,33 +598,33 @@ openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -当你希望明确针对某个命名 Matrix 账户时，请添加 `--account `。 +当你希望显式针对某个命名 Matrix 账户时，请添加 `--account `。 -Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析后的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户的覆盖项）中。 +Matrix 可直接接受 `mxc://` 头像 URL。当你传入 `http://` 或 `https://` 头像 URL 时，OpenClaw 会先将其上传到 Matrix，然后将解析得到的 `mxc://` URL 回写到 `channels.matrix.avatarUrl`（或所选账户的覆盖项）中。 ## 自动验证通知 Matrix 现在会将验证生命周期通知直接作为 `m.notice` 消息发布到严格的私信验证房间中。 -其中包括： +这包括： - 验证请求通知 -- 验证就绪通知（带有明确的“通过表情符号验证”指引） +- 验证就绪通知（带明确的“通过表情符号验证”指引） - 验证开始和完成通知 - SAS 详情（表情符号和十进制），如可用 -来自另一 Matrix 客户端的传入验证请求会被 OpenClaw 跟踪并自动接受。 -对于自验证流程，当表情符号验证可用时，OpenClaw 还会自动启动 SAS 流程并确认自身一侧。 -对于来自其他 Matrix 用户/设备的验证请求，OpenClaw 会自动接受请求，然后等待 SAS 流程正常继续。 -你仍需要在你的 Matrix 客户端中比较表情符号或十进制 SAS，并在那里确认“它们匹配”，以完成验证。 +来自另一个 Matrix 客户端的传入验证请求会被 OpenClaw 跟踪并自动接受。 +对于自验证流程，当表情符号验证可用时，OpenClaw 也会自动启动 SAS 流程并确认自己这一侧。 +对于来自另一个 Matrix 用户/设备的验证请求，OpenClaw 会自动接受请求，然后等待 SAS 流程正常继续。 +你仍然需要在你的 Matrix 客户端中比对表情符号或十进制 SAS，并在那里确认“它们匹配”，以完成验证。 -OpenClaw 不会盲目自动接受自己发起的重复流程。当已有自验证请求待处理时，启动流程会跳过创建新请求。 +OpenClaw 不会盲目自动接受自发起的重复流程。若自验证请求已经处于待处理状态，启动时会跳过创建新请求。 验证协议/系统通知不会转发到智能体聊天流水线，因此不会产生 `NO_REPLY`。 ### 设备清理 -由 OpenClaw 管理的旧 Matrix 设备可能会在账户中累积，使加密房间的信任关系更难判断。 -使用以下命令列出它们： +由 OpenClaw 管理的旧 Matrix 设备可能会在账户中不断累积，使加密房间中的信任关系更难判断。 +可使用以下命令列出它们： ```bash openclaw matrix devices list @@ -637,65 +638,65 @@ openclaw matrix devices prune-stale ### 直接房间修复 -如果私信状态不同步，OpenClaw 可能会留下陈旧的 `m.direct` 映射，使其指向旧的单人房间而不是当前活跃的私信。要检查某个对端的当前映射，请使用： +如果私信状态不同步，OpenClaw 可能会留下过期的 `m.direct` 映射，使其指向旧的单人房间而不是当前的私信。可使用以下命令检查某个对端的当前映射： ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -使用以下命令修复： +使用以下命令修复它： ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -修复会将 Matrix 特定逻辑保留在插件内部： +修复逻辑将 Matrix 特定逻辑保留在插件内部： -- 它优先选择已经映射在 `m.direct` 中的严格 1:1 私信 -- 否则会回退到与该用户当前已加入的任意严格 1:1 私信 -- 如果不存在健康的私信，它会创建一个新的直接房间，并重写 `m.direct` 使其指向该房间 +- 它优先选择已经在 `m.direct` 中映射的严格 1:1 私信 +- 否则回退到与该用户当前已加入的任意严格 1:1 私信 +- 如果不存在健康的私信，则创建一个新的直接房间，并重写 `m.direct` 使其指向该房间 -修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他直接消息流程再次指向正确的房间。 +修复流程不会自动删除旧房间。它只会选择健康的私信并更新映射，以便新的 Matrix 发送、验证通知和其他私信流程再次指向正确的房间。 ## 线程 Matrix 支持对自动回复和消息工具发送同时使用原生 Matrix 线程。 -- `dm.sessionScope: "per-user"`（默认）会使 Matrix 私信路由按发送方作用域处理，因此多个私信房间在解析到同一对端时可以共享一个会话。 -- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离为自己的会话键，同时仍使用普通的私信认证和允许列表检查。 -- 显式 Matrix 会话绑定仍优先于 `dm.sessionScope`，因此已绑定的房间和线程会保持其选择的目标会话。 -- `threadReplies: "off"` 会将回复保持在顶层，并将传入的线程消息保留在父会话中。 -- `threadReplies: "inbound"` 仅当传入消息本来就在某个线程中时，才会在线程内回复。 -- `threadReplies: "always"` 会将房间回复保持在以触发消息为根的线程中，并从第一次触发消息开始，通过匹配的线程作用域会话路由该会话。 +- `dm.sessionScope: "per-user"`（默认）会让 Matrix 私信路由按发送者范围处理，因此多个私信房间在解析到同一对端时可以共享一个会话。 +- `dm.sessionScope: "per-room"` 会将每个 Matrix 私信房间隔离为各自独立的会话键，同时仍使用普通的私信认证和允许列表检查。 +- 显式 Matrix 会话绑定仍然优先于 `dm.sessionScope`，因此绑定的房间和线程会保留其选定的目标会话。 +- `threadReplies: "off"` 会让回复保持在顶层，并让传入的线程消息继续使用父级会话。 +- `threadReplies: "inbound"` 仅当传入消息本来就在该线程中时，才在线程内回复。 +- `threadReplies: "always"` 会让房间回复始终保留在线程中，并以触发消息为线程根，从第一条触发消息开始通过匹配的线程范围会话路由该对话。 - `dm.threadReplies` 仅覆盖私信的顶层设置。例如，你可以保持房间线程隔离，同时让私信保持扁平。 -- 传入的线程消息会将线程根消息作为额外智能体上下文一并包含。 -- 现在，当目标是同一房间或同一私信用户目标时，消息工具发送会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。 -- 仅当当前会话元数据能够证明是在同一 Matrix 账户上的同一私信对端时，同会话私信用户目标复用才会生效；否则 OpenClaw 会回退到普通的按用户作用域路由。 -- 当 OpenClaw 发现某个 Matrix 私信房间与同一共享 Matrix 私信会话中的另一个私信房间发生冲突时，如果启用了线程绑定以及 `dm.sessionScope` 提示，它会在该房间中发布一次性的 `m.notice`，提示可使用 `/focus` 作为逃生入口。 -- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及线程绑定的 `/acp spawn` 现在都可在 Matrix 房间和私信中使用。 +- 传入的线程消息会将线程根消息作为额外的智能体上下文。 +- 当目标是同一房间或同一私信用户目标时，消息工具发送现在会自动继承当前 Matrix 线程，除非显式提供了 `threadId`。 +- 仅当当前会话元数据能证明是同一 Matrix 账户上的同一私信对端时，才会启用同会话私信用户目标复用；否则 OpenClaw 会回退到普通的按用户范围路由。 +- 当 OpenClaw 发现某个 Matrix 私信房间与另一个私信房间在同一个共享 Matrix 私信会话上发生冲突时，如果启用了线程绑定且存在 `dm.sessionScope` 提示，它会在该房间发布一条一次性的 `m.notice`，其中包含 `/focus` 逃生入口。 +- Matrix 支持运行时线程绑定。`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 和线程绑定的 `/acp spawn` 现在都可在 Matrix 房间和私信中使用。 - 当 `threadBindings.spawnSubagentSessions=true` 时，顶层 Matrix 房间/私信中的 `/focus` 会创建一个新的 Matrix 线程，并将其绑定到目标会话。 -- 在现有 Matrix 线程内运行 `/focus` 或 `/acp spawn --thread here` 时，会改为绑定当前线程。 +- 在现有 Matrix 线程内运行 `/focus` 或 `/acp spawn --thread here` 时，则会改为绑定当前线程。 ## ACP 会话绑定 -Matrix 房间、私信和现有 Matrix 线程都可以被转换为持久化 ACP 工作区，而无需改变聊天界面。 +Matrix 房间、私信和现有 Matrix 线程都可以转换为持久的 ACP 工作区，而无需更改聊天界面。 -面向操作员的快捷流程： +面向操作员的快速流程： - 在你希望继续使用的 Matrix 私信、房间或现有线程中运行 `/acp spawn codex --bind here`。 -- 在顶层 Matrix 私信或房间中，当前私信/房间会保持为聊天界面，后续消息会路由到新创建的 ACP 会话。 -- 在现有 Matrix 线程中，`--bind here` 会将当前线程原地绑定。 +- 在顶层 Matrix 私信或房间中，当前私信/房间会继续作为聊天界面，后续消息会路由到新生成的 ACP 会话。 +- 在现有 Matrix 线程内，`--bind here` 会将当前线程原地绑定。 - `/new` 和 `/reset` 会原地重置同一个已绑定 ACP 会话。 - `/acp close` 会关闭 ACP 会话并移除绑定。 说明： - `--bind here` 不会创建子 Matrix 线程。 -- `threadBindings.spawnAcpSessions` 仅在 `/acp spawn --thread auto|here` 时需要，此时 OpenClaw 需要创建或绑定子 Matrix 线程。 +- `threadBindings.spawnAcpSessions` 仅在 `/acp spawn --thread auto|here` 时需要，因为此时 OpenClaw 需要创建或绑定一个子 Matrix 线程。 ### 线程绑定配置 -Matrix 继承 `session.threadBindings` 中的全局默认值，也支持按渠道覆盖： +Matrix 会继承来自 `session.threadBindings` 的全局默认值，同时也支持按渠道覆盖： - `threadBindings.enabled` - `threadBindings.idleHours` @@ -703,64 +704,64 @@ Matrix 继承 `session.threadBindings` 中的全局默认值，也支持按渠 - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Matrix 线程绑定生成标志为选择启用： +Matrix 线程绑定的生成标志为可选启用： - 设置 `threadBindings.spawnSubagentSessions: true` 以允许顶层 `/focus` 创建并绑定新的 Matrix 线程。 - 设置 `threadBindings.spawnAcpSessions: true` 以允许 `/acp spawn --thread auto|here` 将 ACP 会话绑定到 Matrix 线程。 -## 表情回应 +## 反应 -Matrix 支持出站表情回应操作、入站表情回应通知以及入站确认表情回应。 +Matrix 支持出站反应操作、入站反应通知和入站确认反应。 -- 出站表情回应工具受 `channels["matrix"].actions.reactions` 控制。 -- `react` 会向特定 Matrix 事件添加一个表情回应。 -- `reactions` 会列出特定 Matrix 事件当前的表情回应摘要。 -- `emoji=""` 会移除机器人账户自己在该事件上的所有表情回应。 -- `remove: true` 仅移除机器人账户的指定表情回应。 +- 出站反应工具受 `channels["matrix"].actions.reactions` 控制。 +- `react` 会向特定 Matrix 事件添加一个反应。 +- `reactions` 会列出特定 Matrix 事件当前的反应摘要。 +- `emoji=""` 会移除机器人账户在该事件上的所有自有反应。 +- `remove: true` 仅移除机器人账户的指定表情反应。 -确认表情回应使用标准 OpenClaw 解析顺序： +确认反应使用标准的 OpenClaw 解析顺序： - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- 智能体身份表情符号回退值 +- 智能体身份表情符号回退 -确认表情回应作用域按以下顺序解析： +确认反应范围按以下顺序解析： - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -表情回应通知模式按以下顺序解析： +反应通知模式按以下顺序解析： - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` -- 默认值：`own` +- 默认：`own` 当前行为： -- `reactionNotifications: "own"` 会在新增的 `m.reaction` 事件指向机器人创作的 Matrix 消息时转发这些事件。 -- `reactionNotifications: "off"` 会禁用表情回应系统事件。 -- 表情回应移除目前仍不会被综合成系统事件，因为 Matrix 将其表现为 redaction，而不是独立的 `m.reaction` 移除事件。 +- `reactionNotifications: "own"` 会在新增的 `m.reaction` 事件针对机器人撰写的 Matrix 消息时将其转发。 +- `reactionNotifications: "off"` 会禁用反应系统事件。 +- 反应移除仍不会被合成为系统事件，因为 Matrix 将其表示为删除操作，而不是独立的 `m.reaction` 移除事件。 ## 历史上下文 -- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，有多少条最近的房间消息会作为 `InboundHistory` 包含进来。 -- 它会回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用。 -- Matrix 房间历史仅限房间本身。私信仍然使用普通会话历史。 -- Matrix 房间历史是“待处理消息”模式：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时对该窗口进行快照。 -- 当前触发消息不会包含在 `InboundHistory` 中；它会保留在该轮次的主入站正文里。 -- 对同一 Matrix 事件的重试会复用原始历史快照，而不会漂移到更新的房间消息。 +- `channels.matrix.historyLimit` 控制当 Matrix 房间消息触发智能体时，作为 `InboundHistory` 包含多少条最近的房间消息。 +- 它会回退到 `messages.groupChat.historyLimit`。设为 `0` 可禁用。 +- Matrix 房间历史仅限房间。私信仍使用普通会话历史。 +- Matrix 房间历史是待处理式的：OpenClaw 会缓冲尚未触发回复的房间消息，然后在提及或其他触发到来时对该窗口进行快照。 +- 当前触发消息不会包含在 `InboundHistory` 中；它会保留在该轮次的主入站正文中。 +- 对同一 Matrix 事件的重试会复用原始历史快照，而不是漂移到更新的房间消息。 ## 上下文可见性 -Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取到的回复文本、线程根消息和待处理历史。 +Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文，例如获取到的回复文本、线程根和待处理历史。 -- `contextVisibility: "all"` 是默认值。补充上下文会按接收原样保留。 +- `contextVisibility: "all"` 是默认值。补充上下文会按接收时原样保留。 - `contextVisibility: "allowlist"` 会将补充上下文过滤为通过当前房间/用户允许列表检查的发送者。 -- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 类似，但仍会保留一条显式引用回复。 +- `contextVisibility: "allowlist_quote"` 的行为与 `allowlist` 相同，但仍会保留一条显式引用的回复。 -此设置影响的是补充上下文的可见性，而不是入站消息本身能否触发回复。 +此设置影响的是补充上下文的可见性，而不是入站消息本身是否可以触发回复。 触发授权仍来自 `groupPolicy`、`groups`、`groupAllowFrom` 和私信策略设置。 ## 私信和房间策略示例 @@ -786,60 +787,60 @@ Matrix 支持共享的 `contextVisibility` 控制，用于补充房间上下文 } ``` -有关提及门控和允许列表行为，请参阅 [群组](/zh-CN/channels/groups)。 +有关提及门控和允许列表行为，请参阅 [Groups](/zh-CN/channels/groups)。 -Matrix 私信的配对示例： +Matrix 私信配对示例： ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -如果某个尚未获批的 Matrix 用户在批准前持续给你发送消息，OpenClaw 会复用同一个待处理配对代码，并可能在短暂冷却后再次发送提醒回复，而不是签发新代码。 +如果一个尚未获批的 Matrix 用户在获批前持续向你发送消息，OpenClaw 会复用同一个待处理配对码，并可能在短暂冷却后再次发送提醒回复，而不是生成新的配对码。 -共享的私信配对流程和存储布局请参阅 [配对](/zh-CN/channels/pairing)。 +共享的私信配对流程和存储布局请参阅 [Pairing](/zh-CN/channels/pairing)。 -## Exec 审批 +## 执行审批 -Matrix 可以作为某个 Matrix 账户的 exec 审批客户端。 +Matrix 可以充当 Matrix 账户的执行审批客户端。 - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers`（可选；会回退到 `channels.matrix.dm.allowFrom`） -- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） +- `channels.matrix.execApprovals.approvers`（可选；回退到 `channels.matrix.dm.allowFrom`） +- `channels.matrix.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -审批人必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，并且至少能解析出一名审批人时，Matrix 会自动启用原生 exec 审批；审批人可来自 `execApprovals.approvers` 或 `channels.matrix.dm.allowFrom`。将 `enabled: false` 设为显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置审批路由或 exec 审批回退策略。 +审批者必须是 Matrix 用户 ID，例如 `@owner:example.org`。当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批者时，Matrix 会自动启用原生执行审批，无论该审批者来自 `execApprovals.approvers` 还是 `channels.matrix.dm.allowFrom`。设置 `enabled: false` 可显式禁用 Matrix 作为原生审批客户端。否则，审批请求会回退到其他已配置的审批路由或执行审批回退策略。 -目前 Matrix 原生路由仅支持 exec： +当前原生 Matrix 路由仅支持 exec： -- `channels.matrix.execApprovals.*` 仅控制 exec 审批的原生私信/渠道路由。 -- 插件审批仍使用共享的同聊天 `/approve` 加上任何已配置的 `approvals.plugin` 转发。 -- 当 Matrix 能安全推断审批人时，它仍可复用 `channels.matrix.dm.allowFrom` 来进行插件审批授权，但不会公开单独的原生插件审批私信/渠道扇出路径。 +- `channels.matrix.execApprovals.*` 仅控制执行审批的原生私信/渠道路由。 +- 插件审批仍使用共享的同聊天 `/approve`，以及任何已配置的 `approvals.plugin` 转发。 +- 当 Matrix 能安全推断审批者时，它仍可复用 `channels.matrix.dm.allowFrom` 用于插件审批授权，但不会公开单独的原生插件审批私信/渠道分发路径。 -投递规则： +发送规则： -- `target: "dm"` 会将审批提示发送到审批人私信 -- `target: "channel"` 会将提示发送回发起的 Matrix 房间或私信 -- `target: "both"` 会同时发送到审批人私信和发起的 Matrix 房间或私信 +- `target: "dm"` 会将审批提示发送到审批者的私信 +- `target: "channel"` 会将提示发回原始 Matrix 房间或私信 +- `target: "both"` 会同时发送到审批者私信和原始 Matrix 房间或私信 -Matrix 审批提示会在主审批消息上加入表情快捷方式： +Matrix 审批提示会在主要审批消息上预置反应快捷方式： - `✅` = 允许一次 - `❌` = 拒绝 -- `♾️` = 在有效 exec 策略允许此决定时始终允许 +- `♾️` = 始终允许（当该决定受当前有效执行策略允许时） -审批人可以对该消息添加表情回应，或使用回退斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 +审批者可以对该消息添加反应，也可以使用回退斜杠命令：`/approve allow-once`、`/approve allow-always` 或 `/approve deny`。 -只有已解析出的审批人才能批准或拒绝。渠道投递包含命令文本，因此仅应在受信任房间中启用 `channel` 或 `both`。 +只有已解析的审批者才能批准或拒绝。渠道发送会包含命令文本，因此仅在受信任房间中启用 `channel` 或 `both`。 -Matrix 审批提示会复用共享核心审批规划器。Matrix 特定的原生界面目前仅作为 exec 审批的传输层：房间/私信路由以及消息发送/更新/删除行为。 +Matrix 审批提示复用共享核心审批规划器。Matrix 特定的原生界面仅作为执行审批的传输层：房间/私信路由以及消息发送/更新/删除行为。 按账户覆盖： - `channels.matrix.accounts..execApprovals` -相关文档：[Exec 审批](/zh-CN/tools/exec-approvals) +相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) ## 多账户示例 @@ -871,18 +872,18 @@ Matrix 审批提示会复用共享核心审批规划器。Matrix 特定的原生 } ``` -顶层 `channels.matrix` 值会作为命名账户的默认值，除非某个账户进行了覆盖。 -你可以使用 `groups..account`（或旧版 `rooms..account`）将继承的房间条目限制到某个 Matrix 账户。 -未设置 `account` 的条目会在所有 Matrix 账户间共享，而设置了 `account: "default"` 的条目在默认账户直接配置于顶层 `channels.matrix.*` 时仍然有效。 -部分共享认证默认值本身不会创建单独的隐式默认账户。只有当该默认账户具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；命名账户在稍后由缓存凭证满足认证时，仍可通过 `homeserver` 加 `userId` 保持可发现。 -如果 Matrix 已经恰好有一个命名账户，或者 `defaultAccount` 指向现有命名账户键，那么单账户到多账户的修复/设置提升会保留该账户，而不会创建新的 `accounts.default` 条目。只有 Matrix 认证/引导键会移动到该提升后的账户中；共享投递策略键会保留在顶层。 +顶层 `channels.matrix` 值会作为命名账户的默认值，除非某个账户显式覆盖它们。 +你可以使用 `groups..account`（或旧版 `rooms..account`）将继承的房间条目限定到某一个 Matrix 账户。 +不带 `account` 的条目会在所有 Matrix 账户之间共享，而带有 `account: "default"` 的条目在默认账户直接配置在顶层 `channels.matrix.*` 时仍然有效。 +部分共享认证默认值本身不会创建单独的隐式默认账户。只有当该默认账户具有新的认证信息（`homeserver` 加 `accessToken`，或 `homeserver` 加 `userId` 和 `password`）时，OpenClaw 才会合成顶层 `default` 账户；命名账户仍然可以在缓存凭证稍后满足认证时，通过 `homeserver` 加 `userId` 保持可发现。 +如果 Matrix 已经恰好有一个命名账户，或者 `defaultAccount` 指向一个现有命名账户键，则从单账户到多账户的修复/设置提升会保留该账户，而不是创建新的 `accounts.default` 条目。只有 Matrix 认证/引导键会移动到这个被提升的账户中；共享发送策略键会保留在顶层。 当你希望 OpenClaw 在隐式路由、探测和 CLI 操作中优先使用某个命名 Matrix 账户时，请设置 `defaultAccount`。 -如果你配置了多个命名账户，请设置 `defaultAccount`，或在依赖隐式账户选择的 CLI 命令中传递 `--account `。 -当你希望为某条命令覆盖该隐式选择时，请向 `openclaw matrix verify ...` 和 `openclaw matrix devices ...` 传递 `--account `。 +如果你配置了多个命名账户，请设置 `defaultAccount`，或者为依赖隐式账户选择的 CLI 命令传递 `--account `。 +当你希望对单个命令覆盖该隐式选择时，请将 `--account ` 传给 `openclaw matrix verify ...` 和 `openclaw matrix devices ...`。 ## 私有/LAN homeserver -默认情况下，出于 SSRF 防护考虑，OpenClaw 会阻止私有/内部 Matrix homeserver，除非你为每个账户显式选择启用。 +默认情况下，出于 SSRF 防护考虑，OpenClaw 会阻止连接私有/内部 Matrix homeserver，除非你为每个账户显式选择启用。 如果你的 homeserver 运行在 localhost、LAN/Tailscale IP 或内部主机名上，请为该 Matrix 账户启用 `allowPrivateNetwork`： @@ -908,7 +909,8 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -此选择启用仅允许受信任的私有/内部目标。公共明文 homeserver（例如 `http://matrix.example.org:8008`）仍会被阻止。请尽可能优先使用 `https://`。 +此选择启用仅允许受信任的私有/内部目标。公共明文 homeserver，例如 +`http://matrix.example.org:8008`，仍会被阻止。尽可能优先使用 `https://`。 ## 代理 Matrix 流量 @@ -927,11 +929,11 @@ openclaw matrix account add \ ``` 命名账户可以使用 `channels.matrix.accounts..proxy` 覆盖顶层默认值。 -OpenClaw 会将同一代理设置用于运行时 Matrix 流量和账户状态探测。 +OpenClaw 会对运行时 Matrix 流量和账户状态探测使用相同的代理设置。 ## 目标解析 -在 OpenClaw 任何要求你提供房间或用户目标的位置，Matrix 都接受以下目标形式： +在 OpenClaw 任何要求你输入房间或用户目标的地方，Matrix 都接受以下目标形式： - 用户：`@user:server`、`user:@user:server` 或 `matrix:user:@user:server` - 房间：`!room:server`、`room:!room:server` 或 `matrix:room:!room:server` @@ -940,36 +942,36 @@ OpenClaw 会将同一代理设置用于运行时 Matrix 流量和账户状态探 实时目录查找使用已登录的 Matrix 账户： - 用户查找会查询该 homeserver 上的 Matrix 用户目录。 -- 房间查找会直接接受明确的房间 ID 和别名，然后回退为搜索该账户已加入的房间名称。 -- 已加入房间名称查找是尽力而为的。如果某个房间名称无法解析为 ID 或别名，它将在运行时允许列表解析中被忽略。 +- 房间查找可直接接受显式房间 ID 和别名，然后回退到搜索该账户已加入的房间名称。 +- 已加入房间名称查找为尽力而为。如果房间名称无法解析为 ID 或别名，则运行时允许列表解析会忽略它。 ## 配置参考 - `enabled`：启用或禁用该渠道。 - `name`：账户的可选标签。 -- `defaultAccount`：配置了多个 Matrix 账户时的首选账户 ID。 +- `defaultAccount`：配置多个 Matrix 账户时的首选账户 ID。 - `homeserver`：homeserver URL，例如 `https://matrix.example.org`。 -- `allowPrivateNetwork`：允许此 Matrix 账户连接到私有/内部 homeserver。当 homeserver 解析到 `localhost`、LAN/Tailscale IP 或如 `matrix-synapse` 这样的内部主机时启用此项。 -- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可以使用自己的 `proxy` 覆盖顶层默认值。 +- `allowPrivateNetwork`：允许此 Matrix 账户连接私有/内部 homeserver。当 homeserver 解析为 `localhost`、LAN/Tailscale IP 或内部主机（如 `matrix-synapse`）时启用此项。 +- `proxy`：Matrix 流量的可选 HTTP(S) 代理 URL。命名账户可使用自己的 `proxy` 覆盖顶层默认值。 - `userId`：完整 Matrix 用户 ID，例如 `@bot:example.org`。 -- `accessToken`：基于令牌认证的访问令牌。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 支持明文值和 SecretRef 值，覆盖 env/file/exec 提供商。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 -- `password`：用于密码登录的密码。支持明文值和 SecretRef 值。 +- `accessToken`：基于令牌认证的访问令牌。`channels.matrix.accessToken` 和 `channels.matrix.accounts..accessToken` 在 env/file/exec providers 中都支持明文值和 SecretRef 值。请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 +- `password`：用于基于密码登录的密码。支持明文值和 SecretRef 值。 - `deviceId`：显式 Matrix 设备 ID。 -- `deviceName`：密码登录时的设备显示名称。 -- `avatarUrl`：用于资料同步和 `set-profile` 更新的已存储自身头像 URL。 -- `initialSyncLimit`：启动同步事件上限。 +- `deviceName`：用于密码登录的设备显示名称。 +- `avatarUrl`：用于资料同步和 `set-profile` 更新的已存储自头像 URL。 +- `initialSyncLimit`：启动同步事件限制。 - `encryption`：启用 E2EE。 -- `allowlistOnly`：对私信和房间强制仅允许列表行为。 +- `allowlistOnly`：强制私信和房间仅使用允许列表行为。 - `allowBots`：允许来自其他已配置 OpenClaw Matrix 账户的消息（`true` 或 `"mentions"`）。 - `groupPolicy`：`open`、`allowlist` 或 `disabled`。 - `contextVisibility`：补充房间上下文可见性模式（`all`、`allowlist`、`allowlist_quote`）。 - `groupAllowFrom`：房间流量的用户 ID 允许列表。 - `groupAllowFrom` 条目应为完整 Matrix 用户 ID。未解析的名称会在运行时被忽略。 -- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用。 +- `historyLimit`：作为群组历史上下文包含的最大房间消息数。会回退到 `messages.groupChat.historyLimit`。设为 `0` 可禁用。 - `replyToMode`：`off`、`first` 或 `all`。 - `markdown`：用于出站 Matrix 文本的可选 Markdown 渲染配置。 -- `streaming`：`off`（默认）、`partial`、`quiet`、`true` 或 `false`。`partial` 和 `true` 会使用普通 Matrix 文本消息启用“先预览后完成”的草稿更新。`quiet` 则为自托管推送规则设置使用静默预览通知。 -- `blockStreaming`：`true` 会在草稿预览流式传输启用时，为已完成的助手消息块启用独立进度消息。 +- `streaming`：`off`（默认）、`partial`、`quiet`、`true` 或 `false`。`partial` 和 `true` 会通过普通 Matrix 文本消息启用“先预览再更新”的草稿更新。`quiet` 则为自托管推送规则设置使用非通知预览通知。 +- `blockStreaming`：`true` 会在草稿预览流式传输启用时，为已完成的智能体块启用单独进度消息。 - `threadReplies`：`off`、`inbound` 或 `always`。 - `threadBindings`：线程绑定会话路由和生命周期的按渠道覆盖。 - `startupVerification`：启动时自动自验证请求模式（`if-unverified`、`off`）。 @@ -977,35 +979,35 @@ OpenClaw 会将同一代理设置用于运行时 Matrix 流量和账户状态探 - `textChunkLimit`：出站消息分块大小。 - `chunkMode`：`length` 或 `newline`。 - `responsePrefix`：出站回复的可选消息前缀。 -- `ackReaction`：此渠道/账户的可选确认表情回应覆盖值。 -- `ackReactionScope`：可选确认表情回应作用域覆盖值（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 -- `reactionNotifications`：入站表情回应通知模式（`own`、`off`）。 -- `mediaMaxMb`：Matrix 媒体处理的媒体大小上限（MB）。它适用于出站发送和入站媒体处理。 -- `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认值：`off`。 -- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在邀请处理期间解析为房间 ID；OpenClaw 不信任受邀房间声明的别名状态。 +- `ackReaction`：此渠道/账户的可选确认反应覆盖。 +- `ackReactionScope`：可选确认反应范围覆盖（`group-mentions`、`group-all`、`direct`、`all`、`none`、`off`）。 +- `reactionNotifications`：入站反应通知模式（`own`、`off`）。 +- `mediaMaxMb`：Matrix 媒体处理的媒体大小上限（MB）。适用于出站发送和入站媒体处理。 +- `autoJoin`：邀请自动加入策略（`always`、`allowlist`、`off`）。默认：`off`。 +- `autoJoinAllowlist`：当 `autoJoin` 为 `allowlist` 时允许的房间/别名。别名条目会在处理邀请时解析为房间 ID；OpenClaw 不信任被邀请房间声称的别名状态。 - `dm`：私信策略块（`enabled`、`policy`、`allowFrom`、`sessionScope`、`threadReplies`）。 -- `dm.allowFrom` 条目应为完整 Matrix 用户 ID，除非你已经通过实时目录查找解析过它们。 -- `dm.sessionScope`：`per-user`（默认）或 `per-room`。如果你希望每个 Matrix 私信房间即使面对同一对端也保持独立上下文，请使用 `per-room`。 -- `dm.threadReplies`：仅私信的线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，对私信中的回复位置和会话隔离都生效。 -- `execApprovals`：Matrix 原生 exec 审批投递（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 -- `execApprovals.approvers`：允许审批 exec 请求的 Matrix 用户 ID。当 `dm.allowFrom` 已能标识审批人时，此项可选。 +- `dm.allowFrom` 条目应为完整 Matrix 用户 ID，除非你已通过实时目录查找解析过它们。 +- `dm.sessionScope`：`per-user`（默认）或 `per-room`。当你希望每个 Matrix 私信房间即使对端相同也保持独立上下文时，请使用 `per-room`。 +- `dm.threadReplies`：仅私信的线程策略覆盖（`off`、`inbound`、`always`）。它会覆盖顶层 `threadReplies` 设置，用于私信中的回复位置和会话隔离。 +- `execApprovals`：Matrix 原生执行审批发送（`enabled`、`approvers`、`target`、`agentFilter`、`sessionFilter`）。 +- `execApprovals.approvers`：允许审批执行请求的 Matrix 用户 ID。当 `dm.allowFrom` 已经标识出审批者时，此项为可选。 - `execApprovals.target`：`dm | channel | both`（默认：`dm`）。 -- `accounts`：按账户命名的覆盖项。顶层 `channels.matrix` 值会作为这些条目的默认值。 -- `groups`：按房间的策略映射。建议使用房间 ID 或别名；未解析的房间名称会在运行时被忽略。会话/群组标识在解析后使用稳定的房间 ID，而人类可读标签仍来自房间名称。 -- `groups..account`：在多账户设置中，将某个继承的房间条目限制到特定 Matrix 账户。 -- `groups..allowBots`：已配置机器人发送者的房间级覆盖值（`true` 或 `"mentions"`）。 -- `groups..users`：按房间的发送者允许列表。 -- `groups..tools`：按房间的工具允许/拒绝覆盖项。 -- `groups..autoReply`：房间级提及门控覆盖值。`true` 会禁用该房间的提及要求；`false` 会强制重新启用。 -- `groups..skills`：可选的房间级 Skills 过滤器。 +- `accounts`：命名的按账户覆盖。顶层 `channels.matrix` 值会作为这些条目的默认值。 +- `groups`：按房间划分的策略映射。优先使用房间 ID 或别名；未解析的房间名称会在运行时被忽略。会话/群组标识在解析后使用稳定的房间 ID，而人类可读标签仍来自房间名称。 +- `groups..account`：在多账户设置中，将某个继承的房间条目限定到特定 Matrix 账户。 +- `groups..allowBots`：针对已配置机器人发送者的房间级覆盖（`true` 或 `"mentions"`）。 +- `groups..users`：按房间划分的发送者允许列表。 +- `groups..tools`：按房间划分的工具允许/拒绝覆盖。 +- `groups..autoReply`：房间级提及门控覆盖。`true` 会禁用该房间的提及要求；`false` 会强制重新开启。 +- `groups..skills`：可选的房间级技能过滤器。 - `groups..systemPrompt`：可选的房间级系统提示片段。 - `rooms`：`groups` 的旧别名。 -- `actions`：按操作的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 +- `actions`：按操作划分的工具门控（`messages`、`reactions`、`pins`、`profile`、`memberInfo`、`channelInfo`、`verification`）。 ## 相关内容 -- [渠道概览](/zh-CN/channels) — 所有支持的渠道 -- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程 -- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 -- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 -- [安全](/zh-CN/gateway/security) — 访问模型和加固 +- [Channels Overview](/zh-CN/channels) — 所有支持的渠道 +- [Pairing](/zh-CN/channels/pairing) — 私信认证和配对流程 +- [Groups](/zh-CN/channels/groups) — 群聊行为和提及门控 +- [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由 +- [Security](/zh-CN/gateway/security) — 访问模型和加固 diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index afdcbbc9d..feae688a8 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要发布一个插件配置 schema，或调试插件验证错误 -summary: 插件清单 + JSON Schema 要求（严格配置验证） + - 你需要发布插件配置 schema，或调试插件校验错误 +summary: 插件清单 + JSON Schema 要求（严格配置校验） title: 插件清单 x-i18n: - generated_at: "2026-04-05T23:26:38Z" + generated_at: "2026-04-06T00:20:32Z" model: gpt-5.4 provider: openai - source_hash: 5f7af9bcbdc958448e83d2bc96f0acb37017a10b3848343bae1ed5fd2fe4c082 + source_hash: 89a940d54bd18bf60368addd09aeef47d53ca9b07714397e1c43083e01aac6b6 source_path: plugins/manifest.md workflow: 15 --- @@ -17,43 +17,37 @@ x-i18n: 本页仅适用于**原生 OpenClaw 插件清单**。 -关于兼容的 bundle 布局，请参见 [插件 bundle](/zh-CN/plugins/bundles)。 +关于兼容的 bundle 布局，请参阅 [插件包](/zh-CN/plugins/bundles)。 兼容的 bundle 格式使用不同的清单文件： - Codex bundle：`.codex-plugin/plugin.json` -- Claude bundle：`.claude-plugin/plugin.json` 或不带清单的默认 Claude 组件 - 布局 +- Claude bundle：`.claude-plugin/plugin.json` 或不带清单的默认 Claude 组件布局 - Cursor bundle：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些 bundle 布局，但不会按照此处描述的 -`openclaw.plugin.json` schema 对它们进行验证。 +OpenClaw 也会自动检测这些 bundle 布局，但它们不会按照这里介绍的 `openclaw.plugin.json` schema 进行校验。 -对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时， -读取 bundle 元数据、声明的 skill 根目录、Claude 命令根目录、Claude bundle -的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。 +对于兼容 bundle，当布局符合 OpenClaw 运行时预期时，OpenClaw 当前会读取 bundle 元数据，以及声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值，以及受支持的 hook 包。 -每个原生 OpenClaw 插件**必须**在**插件根目录**中提供一个 -`openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下** -验证配置。缺失或无效的清单会被视为插件错误，并阻止配置验证。 +每个原生 OpenClaw 插件**都必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。 -完整的插件系统指南请参见：[Plugins](/zh-CN/tools/plugin)。 -关于原生能力模型和当前的外部兼容性指导，请参见： +完整的插件系统指南请参阅：[插件](/zh-CN/tools/plugin)。 +关于原生能力模型和当前外部兼容性指南，请参阅： [能力模型](/zh-CN/plugins/architecture#public-capability-model)。 -## 此文件的作用 +## 这个文件的作用 `openclaw.plugin.json` 是 OpenClaw 在加载你的插件代码之前读取的元数据。 -将它用于： +请将它用于： - 插件标识 -- 配置验证 -- 无需启动插件运行时即可提供的认证和新手引导元数据 -- 需要在插件运行时加载前解析的别名和自动启用元数据 -- 需要在运行时加载前自动激活插件的简写模型族归属元数据 +- 配置校验 +- 无需启动插件运行时即可获取的凭证和新手引导元数据 +- 应在插件运行时加载前解析的别名和自动启用元数据 +- 应在运行时加载前自动激活插件的简写模型家族归属元数据 - 用于内置兼容接线和契约覆盖的静态能力归属快照 -- 无需加载运行时即可合并到目录和验证表面的渠道专属配置元数据 +- 无需加载运行时即可合并到目录和校验表面的渠道专用配置元数据 - 配置 UI 提示 不要将它用于： @@ -62,7 +56,7 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会按照此处描述的 - 声明代码入口点 - npm 安装元数据 -这些应放在你的插件代码和 `package.json` 中。 +这些内容应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -128,50 +122,50 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会按照此处描述的 ## 顶层字段参考 -| Field | Required | Type | 含义 | -| ----------------------------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Yes | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | -| `configSchema` | Yes | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | No | `true` | 将内置插件标记为默认启用。省略此项，或设置为任何非 `true` 的值，则插件默认保持禁用。 | -| `legacyPluginIds` | No | `string[]` | 归一化到此规范插件 id 的旧版 id。 | -| `autoEnableWhenConfiguredProviders` | No | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | -| `kind` | No | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件类型。 | -| `channels` | No | `string[]` | 此插件拥有的渠道 id。用于发现和配置验证。 | -| `providers` | No | `string[]` | 此插件拥有的提供商 id。 | -| `modelSupport` | No | `object` | 由清单拥有的简写模型族元数据，用于在运行时之前自动加载插件。 | -| `providerAuthEnvVars` | No | `Record` | OpenClaw 无需加载插件代码即可检查的低成本提供商认证环境变量元数据。 | -| `providerAuthChoices` | No | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的低成本认证选项元数据。 | -| `contracts` | No | `object` | 适用于语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 | -| `channelConfigs` | No | `Record` | 在运行时加载前合并进发现和验证表面的、由清单拥有的渠道配置元数据。 | -| `skills` | No | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | -| `name` | No | `string` | 人类可读的插件名称。 | -| `description` | No | `string` | 在插件表面显示的简短摘要。 | -| `version` | No | `string` | 信息性插件版本。 | -| `uiHints` | No | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | +| Field | Required | Type | 含义 | +| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | +| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | +| `enabledByDefault` | 否 | `true` | 将某个内置插件标记为默认启用。省略它，或将其设为任何非 `true` 的值，都会让该插件默认保持禁用。 | +| `legacyPluginIds` | 否 | `string[]` | 会规范化到此规范插件 id 的旧版 id。 | +| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个供 `plugins.slots.*` 使用的独占插件类型。 | +| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于发现和配置校验。 | +| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 | +| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 | +| `providerAuthEnvVars` | 否 | `Record` | 无需加载插件代码即可由 OpenClaw 检查的轻量提供商凭证环境变量元数据。 | +| `providerAuthChoices` | 否 | `object[]` | 供新手引导选择器、首选提供商解析和简单 CLI flag 接线使用的轻量凭证选项元数据。 | +| `contracts` | 否 | `object` | 用于语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、Web 搜索 和工具归属的静态内置能力快照。 | +| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载前合并到发现和校验表面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | +| `name` | 否 | `string` | 人类可读的插件名称。 | +| `description` | 否 | `string` | 在插件相关表面中显示的简短摘要。 | +| `version` | 否 | `string` | 信息性插件版本。 | +| `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## `providerAuthChoices` 参考 -每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。 +每个 `providerAuthChoices` 条目描述一个新手引导或凭证选择项。 OpenClaw 会在提供商运行时加载前读取它。 | Field | Required | Type | 含义 | | --------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | -| `provider` | Yes | `string` | 此选项所属的提供商 id。 | -| `method` | Yes | `string` | 要分发到的认证方法 id。 | -| `choiceId` | Yes | `string` | 供新手引导和 CLI 流程使用的稳定认证选项 id。 | -| `choiceLabel` | No | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 | -| `choiceHint` | No | `string` | 选择器的简短辅助文本。 | -| `assistantPriority` | No | `number` | 在由助手驱动的交互式选择器中，较低值会排在更前面。 | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏此选项，但仍允许通过手动 CLI 进行选择。 | -| `deprecatedChoiceIds` | No | `string[]` | 应将用户重定向到当前替代选项的旧版选项 id。 | -| `groupId` | No | `string` | 用于分组相关选项的可选组 id。 | -| `groupLabel` | No | `string` | 该组的面向用户标签。 | -| `groupHint` | No | `string` | 该组的简短辅助文本。 | -| `optionKey` | No | `string` | 用于简单单标志认证流程的内部选项键。 | -| `cliFlag` | No | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 | -| `cliOption` | No | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key `。 | -| `cliDescription` | No | `string` | CLI 帮助中使用的描述。 | -| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导表面中。如省略，默认值为 `["text-inference"]`。 | +| `provider` | 是 | `string` | 此选项所属的提供商 id。 | +| `method` | 是 | `string` | 要分派到的凭证方法 id。 | +| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定凭证选项 id。 | +| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | +| `choiceHint` | 否 | `string` | 选择器的简短帮助文本。 | +| `assistantPriority` | 否 | `number` | 在由智能体驱动的交互式选择器中，数值越小排序越靠前。 | +| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，但仍允许在手动 CLI 选择中使用。 | +| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到当前替代选项的旧版 choice id。 | +| `groupId` | 否 | `string` | 用于对相关选项进行分组的可选组 id。 | +| `groupLabel` | 否 | `string` | 该分组的面向用户标签。 | +| `groupHint` | 否 | `string` | 该分组的简短帮助文本。 | +| `optionKey` | 否 | `string` | 用于简单单 flag 凭证流程的内部选项键名。 | +| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 | +| `cliOption` | 否 | `string` | 完整的 CLI 选项形态，例如 `--openrouter-api-key `。 | +| `cliDescription` | 否 | `string` | 用于 CLI 帮助信息中的说明。 | +| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 该选项应出现在哪些新手引导表面中。如果省略，默认值为 `["text-inference"]`。 | ## `uiHints` 参考 @@ -190,20 +184,20 @@ OpenClaw 会在提供商运行时加载前读取它。 } ``` -每个字段提示可包含： +每个字段提示可以包含： | Field | Type | 含义 | | ------------- | ---------- | -------------------------- | | `label` | `string` | 面向用户的字段标签。 | -| `help` | `string` | 简短辅助文本。 | +| `help` | `string` | 简短帮助文本。 | | `tags` | `string[]` | 可选的 UI 标签。 | -| `advanced` | `boolean` | 将该字段标记为高级选项。 | -| `sensitive` | `boolean` | 将该字段标记为秘密或敏感。 | +| `advanced` | `boolean` | 将该字段标记为高级字段。 | +| `sensitive` | `boolean` | 将该字段标记为密钥或敏感。 | | `placeholder` | `string` | 表单输入的占位文本。 | ## `contracts` 参考 -仅在 `contracts` 中放置 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。 +仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。 ```json { @@ -223,21 +217,21 @@ OpenClaw 会在提供商运行时加载前读取它。 每个列表都是可选的： -| Field | Type | 含义 | -| -------------------------------- | ---------- | -------------------------------------------- | -| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 | -| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转写提供商 id。 | -| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 | -| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 | -| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 | -| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 | -| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 | -| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 id。 | -| `tools` | `string[]` | 此插件拥有的智能体工具名称，用于内置契约检查。 | +| Field | Type | 含义 | +| -------------------------------- | ---------- | ---------------------------------------------- | +| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 | +| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转写提供商 id。 | +| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 | +| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 | +| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 | +| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 | +| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 | +| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索 提供商 id。 | +| `tools` | `string[]` | 此插件为内置契约检查拥有的智能体工具名称。 | ## `channelConfigs` 参考 -当渠道插件在运行时加载前需要低成本配置元数据时，请使用 `channelConfigs`。 +当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。 ```json { @@ -264,20 +258,19 @@ OpenClaw 会在提供商运行时加载前读取它。 } ``` -每个渠道条目可包含： +每个渠道条目可以包含： -| Field | Type | 含义 | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------ | -| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 | -| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查表面中的渠道标签。 | -| `description` | `string` | 用于检查和目录表面的简短渠道描述。 | -| `preferOver` | `string[]` | 在选择表面中应优先于其排序的旧版或较低优先级插件 id。 | +| Field | Type | 含义 | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | +| `uiHints` | `Record` | 该渠道配置部分可选的 UI 标签 / 占位符 / 敏感性提示。 | +| `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查表面中的渠道标签。 | +| `description` | `string` | 用于检查和目录表面的简短渠道描述。 | +| `preferOver` | `string[]` | 在选择表面中，此渠道应优先于的旧版或较低优先级插件 id。 | ## `modelSupport` 参考 -当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` -这类简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。 +如果 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的提供商插件，请使用 `modelSupport`。 ```json { @@ -288,69 +281,60 @@ OpenClaw 会在提供商运行时加载前读取它。 } ``` -OpenClaw 采用以下优先级： +OpenClaw 会按以下优先级处理： -- 显式的 `provider/model` 引用使用所属 `providers` 清单元数据 +- 显式 `provider/model` 引用使用所属 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` - 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 -- 如果仍有歧义，则在用户或配置指定提供商之前忽略该歧义 +- 其余歧义会被忽略，直到用户或配置显式指定提供商 字段： -| Field | Type | 含义 | -| --------------- | ---------- | -------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 通过 `startsWith` 与简写模型 id 进行匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除 profile 后缀后，与简写模型 id 进行匹配的正则表达式源码。 | +| Field | Type | 含义 | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 针对简写模型 id 进行匹配的前缀。 | +| `modelPatterns` | `string[]` | 在移除 profile 后缀后，针对简写模型 id 进行匹配的正则表达式源码。 | -旧版顶层能力键已被弃用。请使用 `openclaw doctor --fix` 将 -`speechProviders`、`realtimeTranscriptionProviders`、 -`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 -`imageGenerationProviders`、`videoGenerationProviders`、 -`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通清单加载 -已不再将这些顶层字段视为能力归属。 +旧版顶层能力键已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通清单加载不再将这些顶层字段视为能力归属。 ## 清单与 `package.json` 的区别 这两个文件承担不同的职责： -| File | 用途 | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.plugin.json` | 发现、配置验证、认证选项元数据，以及必须在插件代码运行前就存在的 UI 提示 | -| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 | +| File | 用途 | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.plugin.json` | 发现、配置校验、凭证选项元数据，以及必须在插件代码运行前存在的 UI 提示 | +| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 配置块 | 如果你不确定某段元数据应放在哪里，请使用以下规则： -- 如果 OpenClaw 必须在加载插件代码前知道它，请将其放在 `openclaw.plugin.json` 中 -- 如果它与打包、入口文件或 npm 安装行为有关，请将其放在 `package.json` 中 +- 如果 OpenClaw 必须在加载插件代码之前知道它，就把它放在 `openclaw.plugin.json` 中 +- 如果它与打包、入口文件或 npm 安装行为有关，就把它放在 `package.json` 中 ### 影响发现的 `package.json` 字段 -某些运行时前插件元数据有意放在 `package.json` 的 `openclaw` 配置块下， -而不是 `openclaw.plugin.json` 中。 +某些运行时前的插件元数据有意放在 `package.json` 的 `openclaw` 配置块下，而不是 `openclaw.plugin.json` 中。 重要示例： -| Field | 含义 | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | 声明原生插件入口点。 | -| `openclaw.setupEntry` | 在新手引导和延迟渠道启动期间使用的轻量级仅设置入口点。 | -| `openclaw.channel` | 低成本渠道目录元数据，如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.persistedAuthState` | 轻量级持久认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经有任何已登录状态？”。 | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 用于内置和外部发布插件的安装 / 更新提示。 | -| `openclaw.install.defaultChoice` | 当存在多个安装来源时的首选安装路径。 | -| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个受限的内置插件重新安装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间于完整渠道插件之前加载仅设置的渠道表面。 | +| Field | 含义 | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | 声明原生插件入口点。 | +| `openclaw.setupEntry` | 轻量的仅设置入口点，用于新手引导和延迟渠道启动期间。 | +| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 | +| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅基于环境变量的设置？”。 | +| `openclaw.channel.persistedAuthState` | 轻量持久化凭证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何已登录状态？”。 | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 用于内置插件和外部发布插件的安装 / 更新提示。 | +| `openclaw.install.defaultChoice` | 当存在多个安装来源时的首选安装路径。 | +| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重新安装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间，先加载仅设置渠道表面，再加载完整渠道插件。 | -`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。 -无效值会被拒绝；较新的但有效的值会让插件在旧主机上被跳过。 +`openclaw.install.minHostVersion` 会在安装期间和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会让旧主机跳过该插件。 -`openclaw.install.allowInvalidConfigRecovery` 的设计范围是有意收窄的。 -它不会让任意损坏的配置变得可安装。当前它仅允许安装流程从某些特定的陈旧内置插件升级失败中恢复， -例如缺失的内置插件路径，或同一个内置插件下陈旧的 `channels.` 条目。 -无关的配置错误仍会阻止安装，并引导操作人员使用 `openclaw doctor --fix`。 +`openclaw.install.allowInvalidConfigRecovery` 的范围被有意限制得很窄。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或该内置插件对应的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并引导操作员使用 `openclaw doctor --fix`。 -`openclaw.channel.persistedAuthState` 是供微型检查器模块使用的包元数据： +`openclaw.channel.persistedAuthState` 是一个小型检查器模块的包元数据： ```json { @@ -366,45 +350,56 @@ OpenClaw 采用以下优先级： } ``` -当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行低成本的是 / 否认证探测时，请使用它。 -目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 +当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行轻量的是 / 否凭证探测时，请使用它。目标导出应是一个仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 + +`openclaw.channel.configuredState` 对轻量仅环境变量已配置检查采用相同的结构： + +```json +{ + "openclaw": { + "channel": { + "id": "telegram", + "configuredState": { + "specifier": "./configured-state", + "exportName": "hasTelegramConfiguredState" + } + } + } +} +``` + +当某个渠道可以根据环境变量或其他微小的非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 ## JSON Schema 要求 -- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置也是如此。 +- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。 - 可以接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。 -- Schema 会在配置读取 / 写入时验证，而不是在运行时验证。 +- Schema 会在配置读取 / 写入时校验，而不是在运行时校验。 -## 验证行为 +## 校验行为 -- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 由某个插件清单声明。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` - 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。 -- 如果插件已安装，但其清单或 schema 损坏或缺失，则验证会失败，Doctor 会报告该插件错误。 -- 如果插件配置存在，但插件已**禁用**，则配置会被保留，并且 Doctor + 日志中会显示**警告**。 +- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由某个插件清单声明。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。 +- 如果插件已安装，但其清单或 schema 损坏或缺失，校验会失败，Doctor 会报告该插件错误。 +- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并且 Doctor + 日志中会显示**警告**。 -完整的 `plugins.*` schema 请参见 [配置参考](/zh-CN/gateway/configuration)。 +完整的 `plugins.*` schema 请参阅 [配置参考](/zh-CN/gateway/configuration)。 -## 说明 +## 注意事项 -- **原生 OpenClaw 插件必须提供此清单**，包括本地文件系统加载的插件。 -- 运行时仍会单独加载插件模块；该清单仅用于发现 + 验证。 -- 原生清单使用 JSON5 解析，因此接受注释、尾随逗号和未加引号的键， - 只要最终值仍然是一个对象即可。 -- 清单加载器只会读取文档中记录的清单字段。避免在这里添加自定义顶层键。 -- `providerAuthEnvVars` 是用于认证探测、环境变量标记验证以及其他类似提供商认证表面的低成本元数据路径， - 这些场景不应仅仅为了检查环境变量名称而启动插件运行时。 -- `providerAuthChoices` 是用于认证选项选择器、 - `--auth-choice` 解析、首选提供商映射以及在提供商运行时加载前进行简单新手引导 CLI 标志注册的低成本元数据路径。 - 对于需要提供商代码的运行时向导元数据，请参见 - [提供商运行时 hook](/zh-CN/plugins/architecture#provider-runtime-hooks)。 -- 互斥插件类型通过 `plugins.slots.*` 进行选择。 - - `kind: "memory"` 由 `plugins.slots.memory` 选择。 - - `kind: "context-engine"` 由 `plugins.slots.contextEngine` - 选择（默认：内置 `legacy`）。 +- 对于**原生 OpenClaw 插件**，清单是**必需的**，包括本地文件系统加载。 +- 运行时仍会单独加载插件模块；清单仅用于发现 + 校验。 +- 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。 +- 清单加载器只会读取文档中说明的清单字段。避免在这里添加自定义顶层键。 +- `providerAuthEnvVars` 是用于凭证探测、环境变量标记校验以及类似提供商凭证表面的轻量元数据路径，这些表面不应为了检查环境变量名而启动插件运行时。 +- `providerAuthChoices` 是在提供商运行时加载前，用于凭证选项选择器、`--auth-choice` 解析、首选提供商映射以及简单新手引导 CLI flag 注册的轻量元数据路径。对于需要提供商代码的运行时向导元数据，请参阅 + [提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。 +- 独占插件类型通过 `plugins.slots.*` 进行选择。 + - `kind: "memory"` 通过 `plugins.slots.memory` 选择。 + - `kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择 + （默认值：内置 `legacy`）。 - 当插件不需要它们时，可以省略 `channels`、`providers` 和 `skills`。 -- 如果你的插件依赖原生模块，请记录构建步骤以及任何 - package manager 允许列表要求（例如 pnpm 的 `allow-build-scripts` +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` - `pnpm rebuild `）。 ## 相关内容 diff --git a/docs/zh-CN/providers/models.md b/docs/zh-CN/providers/models.md index 01fd2416a..7039ca87f 100644 --- a/docs/zh-CN/providers/models.md +++ b/docs/zh-CN/providers/models.md @@ -1,26 +1,25 @@ --- read_when: - 你想选择一个模型提供商 - - 你想查看 LLM 认证和模型选择的快速设置示例 + - 你想查看用于 LLM 身份验证和模型选择的快速设置示例 summary: OpenClaw 支持的模型提供商（LLM） title: 模型提供商快速开始 x-i18n: - generated_at: "2026-04-05T18:14:57Z" + generated_at: "2026-04-06T00:19:36Z" model: gpt-5.4 provider: openai - source_hash: bc98c65af5737b2c820f4da3304118c2b449d8f0cd363d73922f81087331e93d + source_hash: 4836c7baa0a5af6b01c1369ebe2fdc6032d50d306dd10e2dbb778c6fce1384c4 source_path: providers/models.md workflow: 15 --- # 模型提供商 -OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证，然后将默认 -模型设置为 `provider/model`。 +OpenClaw 可以使用许多 LLM 提供商。选择一个，完成身份验证，然后将默认模型设置为 `provider/model`。 ## 快速开始（两步） -1. 使用提供商完成认证（通常通过 `openclaw onboard`）。 +1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。 2. 设置默认模型： ```json5 @@ -31,11 +30,13 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证 ## 支持的提供商（入门集合） +- [Alibaba Model Studio](/zh-CN/providers/alibaba) - [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic) - [Amazon Bedrock](/zh-CN/providers/bedrock) - [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international) - [Chutes](/zh-CN/providers/chutes) - [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) +- [fal](/zh-CN/providers/fal) - [Fireworks](/zh-CN/providers/fireworks) - [GLM 模型](/zh-CN/providers/glm) - [MiniMax](/zh-CN/providers/minimax) @@ -46,6 +47,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证 - [OpenRouter](/zh-CN/providers/openrouter) - [Qianfan](/zh-CN/providers/qianfan) - [Qwen](/zh-CN/providers/qwen) +- [Runway](/zh-CN/providers/runway) - [StepFun](/zh-CN/providers/stepfun) - [Synthetic](/zh-CN/providers/synthetic) - [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) @@ -53,10 +55,9 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证 - [xAI](/zh-CN/providers/xai) - [Z.AI](/zh-CN/providers/zai) -## 其他内置变体 +## 其他内置提供商变体 -- `anthropic-vertex` - 当 Vertex 凭证可用时，隐式启用 Google Vertex 上的 Anthropic 支持；无需单独的新手引导认证选项 +- `anthropic-vertex` - 当 Vertex 凭证可用时，隐式支持 Google Vertex 上的 Anthropic；无需单独的新手引导身份验证选项 - `copilot-proxy` - 本地 VS Code Copilot Proxy 桥接；使用 `openclaw onboard --auth-choice copilot-proxy` -关于完整的提供商目录（xAI、Groq、Mistral 等）和高级配置， -请参见 [模型提供商](/zh-CN/concepts/model-providers)。 +要查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 diff --git a/docs/zh-CN/providers/runway.md b/docs/zh-CN/providers/runway.md index 644f228bd..4ae5ab0b6 100644 --- a/docs/zh-CN/providers/runway.md +++ b/docs/zh-CN/providers/runway.md @@ -3,23 +3,23 @@ read_when: - 你想在 OpenClaw 中使用 Runway 视频生成 - 你需要设置 Runway API 密钥/环境变量 - 你想将 Runway 设为默认视频提供商 -summary: 在 OpenClaw 中设置 Runway 视频生成 +summary: OpenClaw 中的 Runway 视频生成设置 title: Runway x-i18n: - generated_at: "2026-04-05T23:52:10Z" + generated_at: "2026-04-06T00:19:34Z" model: gpt-5.4 provider: openai - source_hash: f86c0777841cde5b265bba5d6b3dd8fd05fa433ddd0f678860d8bfaa1b7483c5 + source_hash: 87092da3f1a3cb137b0a3dffe1241a5a3d84eb29fa7c3a6b1df9c2871f1c80b6 source_path: providers/runway.md workflow: 15 --- # Runway -OpenClaw 内置了 `runway` 提供商，用于托管式视频生成。 +OpenClaw 内置了一个 `runway` 提供商，用于托管视频生成。 - 提供商：`runway` -- 认证：`RUNWAYML_API_SECRET`（规范名称；`RUNWAY_API_KEY` 也可用） +- 凭证：`RUNWAYML_API_SECRET`（规范名称；`RUNWAY_API_KEY` 也可用） - API：Runway 基于任务的视频生成 API ## 快速开始 @@ -49,10 +49,12 @@ openclaw onboard --auth-choice runway-api-key 内置的 `runway` 视频生成提供商默认使用 `runway/gen4.5`。 - 模式：文生视频、单图图生视频，以及单视频视频转视频 -- 运行时：异步任务提交 + 通过 `GET /v1/tasks/{id}` 轮询 -- 本地图像/视频引用：支持通过数据 URI 使用 +- 运行时：异步提交任务，并通过 `GET /v1/tasks/{id}` 轮询 +- 智能体会话：`video_generate` 会启动一个后台任务，之后在同一会话中的调用现在会返回活动任务状态，而不是生成重复运行 +- 状态查询：`video_generate action=status` +- 本地图像/视频引用：支持通过数据 URI - 当前视频转视频注意事项：OpenClaw 目前对视频输入要求使用 `runway/gen4_aleph` -- 当前文生视频注意事项：OpenClaw 目前对纯文本运行仅提供 `16:9` 和 `9:16` +- 当前文生视频注意事项：OpenClaw 目前为纯文本运行公开 `16:9` 和 `9:16` 要将 Runway 用作默认视频提供商： diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index 6b8c846f9..fc7aad17c 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -6,24 +6,24 @@ read_when: summary: 使用已配置的提供商（如 Alibaba、OpenAI、Google、Qwen、MiniMax 和 Runway）生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-06T00:04:06Z" + generated_at: "2026-04-06T00:19:56Z" model: gpt-5.4 provider: openai - source_hash: 64e95077eed9cbf28566de38ea31a0fd547e7d7013ed7093cb82a7774656d570 + source_hash: 9917245069c39676a7e33afe4800d9c528300e8489a35a28aa6c0356d65b2282 source_path: tools/video-generation.md workflow: 15 --- # 视频生成 -`video_generate` 工具可让智能体使用你已配置的提供商创建视频。在智能体会话中，OpenClaw 会将视频生成作为后台任务启动，在任务台账中跟踪它，然后在片段准备就绪时再次唤醒智能体，以便智能体将完成的视频发布回原始渠道。 +`video_generate` 工具让智能体能够使用你配置的提供商来创建视频。在智能体会话中，OpenClaw 会将视频生成作为后台任务启动，在任务账本中跟踪它，然后在片段准备就绪后再次唤醒智能体，以便智能体将完成的视频发回原始渠道。 -只有在至少有一个视频生成提供商可用时，此工具才会显示。如果你在智能体工具中看不到 `video_generate`，请配置 `agents.defaults.videoGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个视频生成提供商可用时，此工具才会出现。如果你在智能体工具中看不到 `video_generate`，请配置 `agents.defaults.videoGenerationModel` 或设置提供商 API 密钥。 -在智能体会话中，`video_generate` 会立即返回一个任务 id/run id。实际的提供商任务会在后台继续运行。完成后，OpenClaw 会使用内部完成事件唤醒同一会话，以便智能体发送一条正常的后续消息，并附上生成的视频附件。 +在智能体会话中，`video_generate` 会立即返回一个任务 id/run id。实际的提供商作业会在后台继续运行。完成后，OpenClaw 会使用内部完成事件唤醒同一会话，以便智能体发送常规后续消息以及生成的视频附件。 ## 快速开始 @@ -43,9 +43,9 @@ x-i18n: } ``` -3. 向智能体提问：_“生成一段 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时分冲浪。”_ +3. 向智能体发出请求：_“生成一段 5 秒的电影感视频，内容是一只友善的龙虾在日落时分冲浪。”_ -智能体会自动调用 `video_generate`。无需工具允许列表 —— 当有提供商可用时，它默认启用。 +智能体会自动调用 `video_generate`。无需工具白名单配置——当提供商可用时，它默认启用。 对于没有会话支持的智能体运行的直接同步上下文，该工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。 @@ -64,7 +64,7 @@ x-i18n: | Together | `Wan-AI/Wan2.2-T2V-A14B` | 1 张图片 | `TOGETHER_API_KEY` | | xAI | `grok-imagine-video` | 1 张图片或 1 个视频 | `XAI_API_KEY` | -使用 `action: "list"` 可在运行时查看可用的提供商和模型： +使用 `action: "list"` 在运行时查看可用的提供商和模型： ``` /tool video_generate action=list @@ -72,30 +72,33 @@ x-i18n: ## 工具参数 -| 参数 | 类型 | 说明 | -| ----------------- | -------- | -------------------------------------------------------------------------------------- | -| `prompt` | string | 视频生成提示词（`action: "generate"` 时必填） | -| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | -| `model` | string | 提供商/模型覆盖，例如 `qwen/wan2.6-t2v` | -| `image` | string | 单个参考图片路径或 URL | -| `images` | string[] | 多个参考图片（最多 5 张） | -| `video` | string | 单个参考视频路径或 URL | -| `videos` | string[] | 多个参考视频（最多 4 个） | -| `size` | string | 提供商支持时使用的尺寸提示 | -| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | -| `resolution` | string | 分辨率提示：`480P`、`720P` 或 `1080P` | -| `durationSeconds` | number | 目标时长（秒）。OpenClaw 可能会四舍五入到提供商支持的最近值 | -| `audio` | boolean | 提供商支持时启用生成音频 | -| `watermark` | boolean | 提供商支持时切换水印 | -| `filename` | string | 输出文件名提示 | +| 参数 | 类型 | 描述 | +| ----------------- | -------- | ------------------------------------------------------------------------------------------------- | +| `prompt` | string | 视频生成提示词（`action: "generate"` 时必填） | +| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于查看提供商的 `"list"` | +| `model` | string | 提供商/模型覆盖，例如 `qwen/wan2.6-t2v` | +| `image` | string | 单个参考图片路径或 URL | +| `images` | string[] | 多个参考图片（最多 5 张） | +| `video` | string | 单个参考视频路径或 URL | +| `videos` | string[] | 多个参考视频（最多 4 个） | +| `size` | string | 当提供商支持时的尺寸提示 | +| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | +| `resolution` | string | 分辨率提示：`480P`、`720P` 或 `1080P` | +| `durationSeconds` | number | 目标时长（秒）。OpenClaw 可能会将其四舍五入到最近的提供商支持值 | +| `audio` | boolean | 当提供商支持时启用生成音频 | +| `watermark` | boolean | 在支持时切换提供商水印 | +| `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。不支持的可选覆盖项会尽力忽略，并在工具结果中作为警告返回。像参考输入过多这类硬性能力限制，仍会在提交前直接失败。当某个提供商或模型只支持离散的视频时长集合时，OpenClaw 会将 `durationSeconds` 四舍五入到最近的受支持值，并在工具结果中报告规范化后的时长。 +并非所有提供商都支持所有参数。不受支持的可选覆盖项会在尽力而为的基础上被忽略，并在工具结果中作为警告返回。诸如参考输入过多之类的硬性能力限制，仍会在提交前直接失败。当提供商或模型仅支持离散的视频时长集合时，OpenClaw 会将 `durationSeconds` 四舍五入到最近的支持值，并在工具结果中报告规范化后的时长。 ## 异步行为 -- 由会话支持的智能体运行：`video_generate` 会创建后台任务，立即返回 started/task 响应，并在之后的智能体跟进消息中发布完成的视频。 -- 任务跟踪：使用 `openclaw tasks list` / `openclaw tasks show ` 查看该生成任务的排队中、运行中和终态状态。 +- 有会话支持的智能体运行：`video_generate` 会创建一个后台任务，立即返回 started/task 响应，并在稍后的智能体后续消息中发送完成的视频。 +- 重复预防：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `video_generate` 调用会返回任务状态，而不是启动另一次生成。 +- 状态查询：使用 `action: "status"` 查看当前有会话支持的视频任务，而不启动新任务。 +- 任务跟踪：使用 `openclaw tasks list` / `openclaw tasks show ` 查看生成任务的排队、运行中和终态状态。 - 完成唤醒：OpenClaw 会将内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。 +- 提示词提示：当视频任务已在进行中时，同一会话中的后续用户/手动轮次会收到一个小的运行时提示，这样模型就不会盲目再次调用 `video_generate`。 - 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮返回最终视频结果。 ## 配置 @@ -119,41 +122,41 @@ x-i18n: 生成视频时，OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 **`model` 参数**（如果智能体指定了） +1. 工具调用中的 **`model` 参数**（如果智能体指定了该参数） 2. 配置中的 **`videoGenerationModel.primary`** 3. 按顺序使用 **`videoGenerationModel.fallbacks`** -4. **自动检测** —— 仅使用基于凭证的默认提供商： - - 先使用当前默认提供商 - - 然后按 provider-id 顺序使用其余已注册的视频生成提供商 +4. **自动检测** —— 仅使用基于凭证的提供商默认值： + - 先尝试当前默认提供商 + - 然后按 provider-id 顺序尝试其余已注册的视频生成提供商 -如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。 +如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中将包含每次尝试的详细信息。 ## 提供商说明 -- Alibaba 使用 DashScope / Model Studio 异步视频端点，目前要求参考资源使用远程 `http(s)` URL。 -- Google 使用 Gemini/Veo，支持单个图片或视频参考输入。 +- Alibaba 使用 DashScope / Model Studio 异步视频端点，目前要求参考资源必须为远程 `http(s)` URL。 +- Google 使用 Gemini/Veo，并支持单个图片或视频参考输入。 - MiniMax、Together、BytePlus（国际版）和 fal 目前支持单个图片参考输入。 - OpenAI 使用原生视频端点，目前默认使用 `sora-2`。 -- Qwen 支持图片/视频参考，但上游 DashScope 视频端点目前要求这些参考必须使用远程 `http(s)` URL。 +- Qwen 支持图片/视频参考，但上游 DashScope 视频端点当前要求这些参考必须为远程 `http(s)` URL。 - Runway 使用原生异步任务 API，并通过 `GET /v1/tasks/{id}` 轮询，目前默认使用 `gen4.5`。 -- xAI 使用原生 xAI 视频 API，支持文生视频、图生视频，以及远程视频编辑/扩展流程。 -- fal 对长时间运行的任务使用基于队列的 fal 视频流程，而不是单个阻塞式推理请求。 +- xAI 使用原生 xAI 视频 API，支持文生视频、图生视频以及远程视频编辑/扩展流程。 +- fal 对于长时间运行的作业使用基于队列的 fal 视频流程，而不是单个阻塞式推理请求。 ## Qwen 参考输入 -内置的 Qwen 提供商支持文生视频以及图片/视频参考模式，但上游 DashScope 视频端点目前要求参考输入必须使用 **远程 http(s) URL**。本地文件路径和上传的缓冲区会在前置检查时被直接拒绝，而不是被悄悄忽略。 +内置的 Qwen 提供商支持文生视频以及图片/视频参考模式，但上游 DashScope 视频端点当前要求参考输入必须为 **远程 http(s) URL**。本地文件路径和上传的缓冲区会在前置检查时直接被拒绝，而不是被静默忽略。 ## 相关内容 -- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具 -- [后台任务](/zh-CN/automation/tasks) —— 分离式 `video_generate` 运行的任务跟踪 -- [Alibaba Model Studio](/zh-CN/providers/alibaba) —— 直接设置 Wan 提供商 -- [Google（Gemini）](/zh-CN/providers/google) —— Veo 提供商设置 -- [MiniMax](/zh-CN/providers/minimax) —— Hailuo 提供商设置 -- [OpenAI](/zh-CN/providers/openai) —— Sora 提供商设置 -- [Qwen](/zh-CN/providers/qwen) —— Qwen 专属设置和限制 -- [Runway](/zh-CN/providers/runway) —— Runway 设置及当前模型/输入说明 -- [Together AI](/zh-CN/providers/together) —— Together Wan 提供商设置 -- [xAI](/zh-CN/providers/xai) —— Grok 视频提供商设置 -- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) —— `videoGenerationModel` 配置 -- [模型](/zh-CN/concepts/models) —— 模型配置和故障转移 +- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 +- [后台任务](/zh-CN/automation/tasks) — 分离式 `video_generate` 运行的任务跟踪 +- [Alibaba Model Studio](/zh-CN/providers/alibaba) — 直接 Wan 提供商设置 +- [Google（Gemini）](/zh-CN/providers/google) — Veo 提供商设置 +- [MiniMax](/zh-CN/providers/minimax) — Hailuo 提供商设置 +- [OpenAI](/zh-CN/providers/openai) — Sora 提供商设置 +- [Qwen](/zh-CN/providers/qwen) — Qwen 专属设置和限制 +- [Runway](/zh-CN/providers/runway) — Runway 设置以及当前模型/输入说明 +- [Together AI](/zh-CN/providers/together) — Together Wan 提供商设置 +- [xAI](/zh-CN/providers/xai) — Grok 视频提供商设置 +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `videoGenerationModel` 配置 +- [模型](/zh-CN/concepts/models) — 模型配置和故障转移