diff --git a/docs/zh-CN/automation/tasks.md b/docs/zh-CN/automation/tasks.md index 4498ed282..5f3b28574 100644 --- a/docs/zh-CN/automation/tasks.md +++ b/docs/zh-CN/automation/tasks.md @@ -1,44 +1,44 @@ --- read_when: - - 查看正在进行或最近完成的后台工作 - - 调试分离式智能体运行的交付失败 - - 了解后台运行如何与会话、cron 和 Heartbeat 相关 + - 检查正在进行或最近完成的后台工作 + - 调试分离式智能体运行的送达失败 + - 了解后台运行与会话、cron 和 Heartbeat 的关系 sidebarTitle: Background tasks -summary: 用于 ACP 运行、子智能体、隔离的 cron 任务和 CLI 操作的后台任务跟踪 +summary: 用于 ACP 运行、子智能体、隔离 cron 作业和 CLI 操作的后台任务跟踪 title: 后台任务 x-i18n: - generated_at: "2026-05-01T02:52:40Z" + generated_at: "2026-05-05T00:47:32Z" model: gpt-5.5 provider: openai - source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4 + source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991 source_path: automation/tasks.md workflow: 16 --- -正在查找调度？请参阅[自动化和任务](/zh-CN/automation)以选择合适的机制。此页面是后台工作的活动账本，而不是调度器。 +在寻找调度功能？请参阅[自动化和任务](/zh-CN/automation)，以选择正确的机制。此页面是后台工作的活动账本，不是调度器。 -后台任务用于跟踪在**主对话会话之外**运行的工作：ACP 运行、子智能体生成、隔离的 cron 作业执行，以及由 CLI 发起的操作。 +后台任务用于跟踪在**你的主对话会话之外**运行的工作：ACP 运行、子智能体派生、隔离 cron 作业执行，以及 CLI 发起的操作。 -任务**不会**取代会话、cron 作业或 Heartbeat —— 它们是记录发生了哪些分离工作的**活动账本**，包括发生时间以及是否成功。 +任务**不会**取代会话、cron 作业或 Heartbeat — 它们是记录已分离工作发生了什么、何时发生以及是否成功的**活动账本**。 -并非每次智能体运行都会创建任务。Heartbeat 回合和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成以及 CLI 智能体命令都会创建任务。 +并非每次智能体运行都会创建任务。Heartbeat 轮次和普通交互式聊天不会创建任务。所有 cron 执行、ACP 派生、子智能体派生和 CLI 智能体命令都会创建任务。 ## TL;DR -- 任务是**记录**，不是调度器 —— cron 和 Heartbeat 决定工作_何时_运行，任务跟踪_发生了什么_。 -- ACP、子智能体、所有 cron 作业以及 CLI 操作都会创建任务。Heartbeat 回合不会。 -- 每个任务都会经历 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。 -- 当 cron 运行时仍然拥有该作业时，cron 任务会保持活动状态；如果内存中的运行时状态已消失，任务维护会先检查持久化的 cron 运行历史，然后再将任务标记为 lost。 -- 完成是推送驱动的：分离的工作可以直接通知，或在完成时唤醒请求者会话/Heartbeat，因此状态轮询循环通常不是合适的形式。 -- 隔离的 cron 运行和子智能体完成会尽力为其子会话清理已跟踪的浏览器标签页/进程，然后再进行最终清理记账。 -- 在后代子智能体工作仍在清空时，隔离的 cron 投递会抑制过期的中间父级回复；如果最终后代输出在投递前到达，则优先使用该输出。 +- 任务是**记录**，不是调度器 — cron 和 Heartbeat 决定工作_何时_运行，任务跟踪_发生了什么_。 +- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。Heartbeat 轮次不会。 +- 每个任务都会经过 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。 +- 只要 cron 运行时仍拥有该作业，cron 任务就会保持活动；如果内存中的运行时状态已消失，任务维护会先检查持久化的 cron 运行历史，然后才将任务标记为 lost。 +- 完成是推送驱动的：分离的工作可以在完成时直接通知，或唤醒请求方会话/Heartbeat，因此状态轮询循环通常不是正确的形态。 +- 隔离 cron 运行和子智能体完成会尽力为其子会话清理被跟踪的浏览器标签页/进程，然后再进行最终清理记账。 +- 当后代子智能体工作仍在收尾时，隔离 cron 投递会抑制过时的临时父级回复；如果最终后代输出在投递前到达，它会优先使用该输出。 - 完成通知会直接投递到某个渠道，或排队等待下一次 Heartbeat。 -- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 会暴露问题。 -- 终止记录会保留 7 天，然后自动清理。 +- `openclaw tasks list` 会显示所有任务；`openclaw tasks audit` 会暴露问题。 +- 终态记录会保留 7 天，然后自动清理。 ## 快速开始 @@ -81,7 +81,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -94,26 +94,26 @@ x-i18n: ## 什么会创建任务 | 来源 | 运行时类型 | 创建任务记录的时机 | 默认通知策略 | -| ---------------------- | ---------- | -------------------------------------------------------- | ------------ | -| ACP 后台运行 | `acp` | 生成子 ACP 会话 | `done_only` | -| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 生成子智能体 | `done_only` | -| Cron 作业（所有类型） | `cron` | 每次 cron 执行（主会话和隔离模式） | `silent` | -| CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` | -| 智能体媒体作业 | `cli` | 基于会话的 `music_generate`/`video_generate` 运行 | `silent` | +| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | +| ACP 后台运行 | `acp` | 派生子 ACP 会话 | `done_only` | +| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 派生子智能体 | `done_only` | +| Cron 作业（所有类型） | `cron` | 每次 cron 执行（主会话和隔离执行） | `silent` | +| CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` | +| 智能体媒体作业 | `cli` | 会话支持的 `music_generate`/`video_generate` 运行 | `silent` | - 默认情况下，主会话 cron 任务使用 `silent` 通知策略 —— 它们会创建记录用于跟踪，但不会生成通知。隔离的 cron 任务也默认为 `silent`，但由于它们在自己的会话中运行，因此更显眼。 + 主会话 cron 任务默认使用 `silent` 通知策略 — 它们会创建用于跟踪的记录，但不会生成通知。隔离 cron 任务也默认使用 `silent`，但由于它们在自己的会话中运行，因此更加可见。 - 基于会话的 `music_generate` 和 `video_generate` 运行也使用 `silent` 通知策略。它们仍然会创建任务记录，但完成结果会作为内部唤醒交回给原始智能体会话，让智能体自行编写后续消息并附加完成的媒体。如果你启用 `tools.media.asyncCompletion.directSend`，异步 `video_generate` 完成可以先尝试直接渠道投递；异步 `music_generate` 完成仍留在请求者会话唤醒路径上。 + 会话支持的 `music_generate` 和 `video_generate` 运行也使用 `silent` 通知策略。它们仍会创建任务记录，但完成结果会作为内部唤醒交还给原始智能体会话，以便智能体自行写入后续消息并附加完成的媒体。群组/渠道完成遵循正常的可见回复策略，因此当源投递需要时，智能体会使用消息工具。 - - 当基于会话的 `video_generate` 任务仍处于活动状态时，该工具也会充当保护栏：同一会话中重复的 `video_generate` 调用会返回活动任务状态，而不是启动第二个并发生成。当你希望从智能体侧显式查询进度/状态时，请使用 `action: "status"`。 + + 当会话支持的 `video_generate` 任务仍处于活动状态时，该工具还会充当防护：同一会话中重复的 `video_generate` 调用会返回活动任务状态，而不是启动第二个并发生成。当你希望从智能体侧显式查询进度/状态时，请使用 `action: "status"`。 - - Heartbeat 回合 —— 主会话；请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) - - 普通交互式聊天回合 + - Heartbeat 轮次 — 主会话；请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) + - 普通交互式聊天轮次 - 直接 `/command` 响应 @@ -136,47 +136,47 @@ stateDiagram-v2 | Status | 含义 | | ----------- | -------------------------------------------------------------------------- | | `queued` | 已创建，正在等待智能体启动 | -| `running` | 智能体回合正在主动执行 | +| `running` | 智能体轮次正在主动执行 | | `succeeded` | 已成功完成 | -| `failed` | 已完成，但出现错误 | +| `failed` | 已完成但出现错误 | | `timed_out` | 超过了配置的超时时间 | -| `cancelled` | 操作者通过 `openclaw tasks cancel` 停止 | -| `lost` | 运行时在 5 分钟宽限期后失去了权威后备状态 | +| `cancelled` | 操作员通过 `openclaw tasks cancel` 停止 | +| `lost` | 运行时在 5 分钟宽限期后丢失了权威后备状态 | -转换会自动发生 —— 当关联的智能体运行结束时，任务状态会更新为匹配状态。 +转换会自动发生 — 当关联的智能体运行结束时，任务状态会更新为匹配的状态。 -对于活动任务记录，智能体运行完成结果具有权威性。成功的分离运行会最终确定为 `succeeded`，普通运行错误会最终确定为 `failed`，超时或中止结果会最终确定为 `timed_out`。如果操作者已经取消该任务，或者运行时已经记录了更强的终止状态，例如 `failed`、`timed_out` 或 `lost`，后续的成功信号不会将该终止状态降级。 +智能体运行完成是活动任务记录的权威依据。成功的分离运行会最终变为 `succeeded`，普通运行错误会最终变为 `failed`，超时或中止结果会最终变为 `timed_out`。如果操作员已经取消该任务，或运行时已经记录了更强的终态，例如 `failed`、`timed_out` 或 `lost`，后续的成功信号不会将该终态降级。 `lost` 具有运行时感知能力： - ACP 任务：后备 ACP 子会话元数据已消失。 - 子智能体任务：后备子会话已从目标智能体存储中消失。 -- Cron 任务：cron 运行时不再将该作业跟踪为活动状态，并且持久化 cron 运行历史也未显示该次运行的终止结果。离线 CLI 审计不会将其自身空的进程内 cron 运行时状态视为权威。 -- CLI 任务：隔离的子会话任务使用子会话；基于聊天的 CLI 任务改用实时运行上下文，因此残留的渠道/群组/直接会话行不会让它们保持活动状态。由 Gateway 网关支持的 `openclaw agent` 运行也会从其运行结果最终确定，因此已完成的运行不会一直处于活动状态直到清扫器将其标记为 `lost`。 +- Cron 任务：cron 运行时不再将该作业跟踪为活动状态，并且持久化的 cron 运行历史没有显示该次运行的终态结果。离线 CLI 审计不会将其自身空的进程内 cron 运行时状态视为权威依据。 +- CLI 任务：隔离子会话任务使用子会话；聊天支持的 CLI 任务改用实时运行上下文，因此残留的渠道/群组/直接会话行不会让它们保持活动。Gateway 网关支持的 `openclaw agent` 运行也会从其运行结果最终完成，因此已完成的运行不会一直处于活动状态，直到清扫器将其标记为 `lost`。 ## 投递和通知 -当任务达到终止状态时，OpenClaw 会通知你。共有两条投递路径： +当任务达到终态时，OpenClaw 会通知你。有两条投递路径： -**直接投递** —— 如果任务有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留绑定的线程/话题路由，并且可以在放弃直接投递前，从请求者会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 `to` / 账号。 +**直接投递** — 如果任务有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留绑定线程/主题路由，并且可以先从请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）填补缺失的 `to` / 账户，然后再放弃直接投递。 -**会话排队投递** —— 如果直接投递失败或未设置来源，更新会作为系统事件排入请求者的会话，并在下一次 Heartbeat 中显示。 +**会话排队投递** — 如果直接投递失败或未设置来源，更新会作为系统事件排队到请求方的会话中，并在下一次 Heartbeat 时显示。 -任务完成会触发立即 Heartbeat 唤醒，因此你可以快速看到结果 —— 不必等待下一次计划的 Heartbeat tick。 +任务完成会触发立即 Heartbeat 唤醒，因此你可以很快看到结果 — 你不必等到下一次计划的 Heartbeat tick。 -这意味着常规工作流是基于推送的：启动一次分离工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或显式审计时，才轮询任务状态。 +这意味着通常的工作流是基于推送的：启动一次分离工作，然后让运行时在完成时唤醒或通知你。只有在需要调试、干预或显式审计时，才轮询任务状态。 ### 通知策略 -控制你对每个任务收到的信息量： +控制每个任务的通知频率： -| 策略 | 投递内容 | -| --------------------- | ------------------------------------------------------------------------ | -| `done_only`（默认） | 仅终止状态（succeeded、failed 等）—— **这是默认值** | -| `state_changes` | 每次状态转换和进度更新 | -| `silent` | 完全不投递 | +| 策略 | 投递内容 | +| --------------------- | ----------------------------------------------------------------------- | +| `done_only`（默认） | 仅终态（succeeded、failed 等）— **这是默认值** | +| `state_changes` | 每次状态转换和进度更新 | +| `silent` | 完全不投递 | 在任务运行时更改策略： @@ -192,7 +192,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - 输出列：任务 ID、种类、状态、投递、运行 ID、子会话、摘要。 + 输出列：任务 ID、类型、Status、投递、运行 ID、子会话、摘要。 @@ -200,7 +200,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - 查找令牌接受任务 ID、运行 ID 或会话键。显示完整记录，包括计时、投递状态、错误和终止摘要。 + 查找令牌接受任务 ID、运行 ID 或会话键。显示完整记录，包括计时、投递状态、错误和终态摘要。 @@ -208,7 +208,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - 对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消会记录到任务注册表中（没有单独的子运行时句柄）。状态会转换为 `cancelled`，并在适用时发送投递通知。 + 对于 ACP 和子智能体任务，这会终止子会话。对于 CLI 跟踪的任务，取消会记录在任务注册表中（没有单独的子运行时句柄）。Status 会转换为 `cancelled`，并在适用时发送投递通知。 @@ -221,59 +221,59 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - 暴露操作问题。检测到问题时，发现项也会显示在 `openclaw status` 中。 + 暴露操作问题。检测到问题时，发现结果也会出现在 `openclaw status` 中。 - | 发现项 | 严重性 | 触发条件 | - | ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | - | `stale_queued` | 警告 | 排队超过 10 分钟 | - | `stale_running` | 错误 | 运行超过 30 分钟 | - | `lost` | 警告/错误 | 运行时支持的任务所有权消失；保留的丢失任务在 `cleanupAfter` 之前为警告，之后变为错误 | - | `delivery_failed` | 警告 | 投递失败且通知策略不是 `silent` | - | `missing_cleanup` | 警告 | 终端任务没有清理时间戳 | - | `inconsistent_timestamps` | 警告 | 时间线违规（例如结束早于开始） | + | 发现项 | 严重性 | 触发条件 | + | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | + | `stale_queued` | 警告 | 排队超过 10 分钟 | + | `stale_running` | 错误 | 运行超过 30 分钟 | + | `lost` | 警告/错误 | 运行时支持的任务所有权已消失；保留的丢失任务在 `cleanupAfter` 前为警告，之后变为错误 | + | `delivery_failed` | 警告 | 投递失败且通知策略不是 `silent` | + | `missing_cleanup` | 警告 | 终止任务没有清理时间戳 | + | `inconsistent_timestamps` | 警告 | 时间线违规（例如结束时间早于开始时间） | - + ```bash openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` - 使用它来预览或应用任务和 Task Flow 状态的协调、清理标记和修剪。 + 使用它来预览或应用任务和 Task Flow 状态的调和、清理标记和修剪。 - 协调会感知运行时： + 调和会感知运行时： - ACP/subagent 任务会检查其背后的子会话。 - - 如果 subagent 任务的子会话有重启恢复墓碑，则会被标记为丢失，而不是被视为可恢复的背后会话。 - - Cron 任务会检查 cron 运行时是否仍拥有该作业，然后先从持久化的 cron 运行日志/作业状态中恢复终端状态，最后才回退到 `lost`。只有 Gateway 网关进程对内存中的 cron 活动作业集合具有权威性；离线 CLI 审计使用持久历史，但不会仅因为该本地 Set 为空就将 cron 任务标记为丢失。 - - 聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。 + - 子会话带有重启恢复墓碑的 Subagent 任务会被标记为丢失，而不是被视为可恢复的支持会话。 + - Cron 任务会检查 cron 运行时是否仍拥有该作业，然后先从持久化的 cron 运行日志/作业状态恢复终止状态，之后才回退为 `lost`。只有 Gateway 网关进程才是内存中 cron 活动作业集的权威来源；离线 CLI 审计会使用持久化历史记录，但不会仅因为该本地 Set 为空就将 cron 任务标记为丢失。 + - 由聊天支持的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。 完成清理也会感知运行时： - - subagent 完成时会尽力关闭子会话跟踪的浏览器标签页/进程，然后继续公告清理。 - - 隔离 cron 完成时会尽力关闭 cron 会话跟踪的浏览器标签页/进程，然后运行才会完全拆除。 - - 隔离 cron 投递会在需要时等待后代 subagent 的后续处理，并抑制过期的父确认文本，而不是公告它。 - - subagent 完成投递优先使用最新可见的 assistant 文本；如果为空，则回退到经过清理的最新工具/toolResult 文本，并且仅超时的工具调用运行可以折叠为简短的部分进度摘要。终端失败运行会公告失败状态，而不会重放捕获的回复文本。 + - Subagent 完成时会尽力关闭为子会话跟踪的浏览器标签页/进程，然后继续公告清理。 + - 隔离的 cron 完成时会尽力关闭为 cron 会话跟踪的浏览器标签页/进程，然后运行才会完全拆除。 + - 隔离的 cron 投递会在需要时等待后代 subagent 跟进，并抑制过期的父级确认文本，而不是公告它。 + - Subagent 完成投递优先使用最新可见的助手文本；如果为空，则回退到经过净化的最新工具/toolResult 文本，并且仅超时的工具调用运行可以折叠为简短的部分进度摘要。终止失败的运行会公告失败状态，而不会重放捕获的回复文本。 - 清理失败不会掩盖真实的任务结果。 - + ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` - 当你关注的是编排用 Task Flow，而不是某个单独的后台任务记录时，请使用这些命令。 + 当你关心的是编排中的 Task Flow，而不是某一条单独的后台任务记录时，使用这些命令。 -## 聊天任务板（`/tasks`） +## 聊天任务看板（`/tasks`） -在任何聊天会话中使用 `/tasks`，查看链接到该会话的后台任务。该面板会显示活动任务和最近完成的任务，包括运行时、状态、计时以及进度或错误详情。 +在任意聊天会话中使用 `/tasks` 查看链接到该会话的后台任务。看板会显示活动任务和最近完成的任务，包括运行时、状态、时间以及进度或错误详情。 -当当前会话没有可见的关联任务时，`/tasks` 会回退到智能体本地任务计数，因此你仍能获得概览，而不会泄露其他会话的详情。 +当当前会话没有可见的已链接任务时，`/tasks` 会回退到智能体本地任务计数，因此你仍能获得概览，而不会泄露其他会话的详情。 如需完整的操作员账本，请使用 CLI：`openclaw tasks list`。 @@ -287,38 +287,38 @@ Tasks: 3 queued · 2 running · 1 issues 摘要会报告： -- **活动** — `queued` + `running` 的计数 -- **失败** — `failed` + `timed_out` + `lost` 的计数 -- **按运行时** — 按 `acp`、`subagent`、`cron`、`cli` 细分 +- **active** — `queued` + `running` 的计数 +- **failures** — `failed` + `timed_out` + `lost` 的计数 +- **byRuntime** — 按 `acp`、`subagent`、`cron`、`cli` 划分的明细 -`/status` 和 `session_status` 工具都使用感知清理的任务快照：优先显示活动任务，隐藏过期的已完成行，并且只有在没有剩余活动工作时才显示近期失败。这会让状态卡片聚焦于当前重要的内容。 +`/status` 和 `session_status` 工具都会使用感知清理的任务快照：优先显示活动任务，隐藏过期的已完成行，并且只有在没有活动工作剩余时才显示最近失败。这样可以让状态卡片聚焦于当前真正重要的内容。 ## 存储和维护 ### 任务存放位置 -任务记录会持久化到 SQLite： +任务记录会持久化到 SQLite，位置为： ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` 注册表会在 Gateway 网关启动时加载到内存，并将写入同步到 SQLite，以便在重启之间保持持久性。 -Gateway 网关使用 SQLite 默认的自动检查点阈值，以及周期性和关机时的 `TRUNCATE` 检查点，来限制 SQLite 预写日志大小。 +Gateway 网关通过使用 SQLite 默认的自动检查点阈值，以及定期和关闭时的 `TRUNCATE` 检查点，来限制 SQLite 预写日志的大小。 ### 自动维护 -清扫器每 **60 秒**运行一次，处理四件事： +清扫器每 **60 秒**运行一次，并处理四件事： - - 检查活动任务是否仍然有权威的运行时支持。ACP/subagent 任务使用子会话状态，cron 任务使用活动作业所有权，聊天支持的 CLI 任务使用所属运行上下文。如果该支持状态消失超过 5 分钟，任务会被标记为 `lost`。 + + 检查活动任务是否仍具有权威运行时支持。ACP/subagent 任务使用子会话状态，cron 任务使用活动作业所有权，由聊天支持的 CLI 任务使用所属的运行上下文。如果该支持状态消失超过 5 分钟，任务会被标记为 `lost`。 - 关闭终端状态或孤立的父级拥有的一次性 ACP 会话；对于过期的终端状态或孤立的持久 ACP 会话，仅在没有剩余活动对话绑定时关闭。 + 关闭已终止或孤立的、由父级拥有的一次性 ACP 会话；对于过期的已终止或孤立的持久 ACP 会话，仅在没有活动会话绑定保留时才关闭。 - 为终端任务设置 `cleanupAfter` 时间戳（endedAt + 7 天）。在保留期间，丢失任务仍会作为警告显示在审计中；当 `cleanupAfter` 过期或清理元数据缺失时，它们会变为错误。 + 在终止任务上设置 `cleanupAfter` 时间戳（endedAt + 7 天）。在保留期间，丢失任务仍会在审计中显示为警告；在 `cleanupAfter` 过期后，或清理元数据缺失时，它们会显示为错误。 删除超过其 `cleanupAfter` 日期的记录。 @@ -326,42 +326,42 @@ Gateway 网关使用 SQLite 默认的自动检查点阈值，以及周期性和 -**保留期：**终端任务记录会保留 **7 天**，然后自动修剪。不需要配置。 +**保留期：**终止任务记录会保留 **7 天**，然后自动修剪。无需配置。 -## 任务与其他系统的关系 +## 任务如何关联其他系统 - [Task Flow](/zh-CN/automation/taskflow) 是后台任务之上的流编排层。单个流可以在其生命周期内使用托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks 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 作业**定义**位于 `~/.openclaw/cron/jobs.json`；运行时执行状态位于旁边的 `~/.openclaw/cron/jobs-state.json`。**每次** cron 执行都会创建一条任务记录，包括主会话和隔离会话。主会话 cron 任务默认使用 `silent` 通知策略，因此会进行跟踪但不会生成通知。 + cron 作业**定义**位于 `~/.openclaw/cron/jobs.json`；运行时执行状态位于旁边的 `~/.openclaw/cron/jobs-state.json`。**每次** cron 执行都会创建一条任务记录，包括主会话和隔离会话。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪但不会生成通知。 - 请参见 [Cron 作业](/zh-CN/automation/cron-jobs)。 + 参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。 Heartbeat 运行是主会话轮次，它们不会创建任务记录。当任务完成时，它可以触发 Heartbeat 唤醒，让你及时看到结果。 - 请参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 + 参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 - 任务可以引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（启动者）。会话是对话上下文；任务是在其之上的活动跟踪。 + 任务可以引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（发起者）。会话是对话上下文；任务是在其之上的活动跟踪。 - 任务的 `runId` 会链接到执行工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态，你不需要手动管理生命周期。 + 任务的 `runId` 会链接到执行工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态，你无需手动管理生命周期。 ## 相关 -- [自动化与任务](/zh-CN/automation) — 所有自动化机制一览 +- [自动化和任务](/zh-CN/automation) — 所有自动化机制概览 - [CLI：任务](/zh-CN/cli/tasks) — CLI 命令参考 -- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性主会话轮次 +- [Heartbeat](/zh-CN/gateway/heartbeat) — 定期主会话轮次 - [定时任务](/zh-CN/automation/cron-jobs) — 调度后台工作 -- [Task Flow](/zh-CN/automation/taskflow) — 任务之上的流编排 +- [Task Flow](/zh-CN/automation/taskflow) — 任务之上的流程编排 diff --git a/docs/zh-CN/gateway/config-tools.md b/docs/zh-CN/gateway/config-tools.md index 16530f44c..e7b1e3440 100644 --- a/docs/zh-CN/gateway/config-tools.md +++ b/docs/zh-CN/gateway/config-tools.md @@ -4,56 +4,56 @@ read_when: - 注册自定义提供商或覆盖基础 URL - 设置 OpenAI 兼容的自托管端点 sidebarTitle: Tools and custom providers -summary: 工具配置（策略、实验性开关、由提供商支持的工具）和自定义提供商/基础 URL 设置 +summary: 工具配置（策略、实验性开关、提供商支持的工具）以及自定义提供商/基础 URL 设置 title: 配置 — 工具和自定义提供商 x-i18n: - generated_at: "2026-05-03T17:26:32Z" + generated_at: "2026-05-05T00:47:36Z" model: gpt-5.5 provider: openai - source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da + source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883 source_path: gateway/config-tools.md workflow: 16 --- -`tools.*` 配置键以及自定义提供商 / 基础 URL 设置。对于智能体、渠道和其他顶层配置键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 +`tools.*` 配置键和自定义提供商 / 基础 URL 设置。对于智能体、渠道和其他顶层配置键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 ## 工具 -### 工具配置档 +### 工具配置文件 -`tools.profile` 会先设置基础允许列表，然后再应用 `tools.allow`/`tools.deny`： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导会在未设置时将新的本地配置默认为 `tools.profile: "coding"`（会保留已有的显式配置档）。 +本地新手引导会在未设置时将新的本地配置默认设为 `tools.profile: "coding"`（会保留现有的显式配置文件）。 -| 配置档 | 包含内容 | +| 配置文件 | 包含内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| `minimal` | 仅 `session_status` | +| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | +| 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | +| `group:runtime` | `exec`, `process`, `code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 +全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { @@ -61,7 +61,7 @@ x-i18n: } ``` -`write` 和 `apply_patch` 是独立的工具 ID。`allow: ["write"]` 也会为兼容模型启用 `apply_patch`，但 `deny: ["write"]` 不会拒绝 `apply_patch`。若要阻止所有文件变更，请拒绝 `group:fs`，或显式列出每个会变更文件的工具： +`write` 和 `apply_patch` 是独立的工具 ID。`allow: ["write"]` 也会为兼容模型启用 `apply_patch`，但 `deny: ["write"]` 不会拒绝 `apply_patch`。要阻止所有文件变更，请拒绝 `group:fs`，或显式列出每个会变更文件的工具： ```json5 { @@ -71,7 +71,7 @@ x-i18n: ### `tools.byProvider` -进一步限制特定提供商或模型可用的工具。顺序：基础配置档 → 提供商配置档 → 允许/拒绝。 +进一步限制特定提供商或模型可用的工具。顺序：基础配置文件 → 提供商配置文件 → 允许 / 拒绝。 ```json5 { @@ -104,8 +104,8 @@ x-i18n: ``` - 每个智能体的覆盖项（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 按会话存储状态；内联指令只应用于单条消息。 -- 提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认为 `gateway`，或在 exec 目标为 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令只应用于单条消息。 +- 提升权限 `exec` 会绕过沙箱隔离，并使用配置的转义路径（默认是 `gateway`，或在 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -129,7 +129,7 @@ x-i18n: ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。设置可以在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。设置可以在 `tools.loopDetection` 中全局定义，并可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -151,25 +151,25 @@ x-i18n: ``` - 为循环分析保留的最大工具调用历史。 + 为循环分析保留的最大工具调用历史记录。 - 重复无进展模式的警告阈值。 + 用于警告的重复无进展模式阈值。 - 用于阻止关键循环的更高重复阈值。 + 用于阻止严重循环的更高重复阈值。 - 任何无进展运行的硬停止阈值。 + 任意无进展运行的硬停止阈值。 - 对重复的相同工具/相同参数调用发出警告。 + 对重复的相同工具 / 相同参数调用发出警告。 - 对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 + 对已知轮询工具（`process.poll`、`command_status` 等）发出警告 / 阻止。 - 对交替出现的无进展成对模式发出警告/阻止。 + 对交替出现的无进展成对模式发出警告 / 阻止。 @@ -216,7 +216,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async video directly to the channel + directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, @@ -262,14 +262,14 @@ x-i18n: - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → 图像，`google` → 图像+音频+视频，`groq` → 音频。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：逐条目覆盖。 - - 当智能体调用显式的 `image` 工具时，`tools.media.image.timeoutSeconds` 和匹配的图像模型 `timeoutSeconds` 条目也会生效。 + - 当智能体调用显式 `image` 工具时，`tools.media.image.timeoutSeconds` 和匹配的图像模型 `timeoutSeconds` 条目也会生效。 - 失败会回退到下一个条目。 - 提供商身份验证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 + 提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - - `asyncCompletion.directSend`：当为 `true` 时，支持直接完成投递的已完成异步媒体任务会先尝试直接渠道投递。默认值：`false`（请求方会话唤醒/模型投递路径）。目前这适用于异步 `video_generate`；即使启用此项，异步 `music_generate` 完成仍通过请求方会话中介。 + - `asyncCompletion.directSend`：已弃用的兼容性标志。已完成的异步媒体任务仍由请求者会话介导，这样智能体会接收结果，决定如何告知用户，并在源投递需要时使用消息工具。 @@ -289,7 +289,7 @@ x-i18n: ### `tools.sessions` -控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 +控制哪些会话可作为会话工具（`sessions_list`、`sessions_history`、`sessions_send`）的目标。 默认值：`tree`（当前会话 + 由它生成的会话，例如子智能体）。 @@ -305,12 +305,12 @@ x-i18n: ``` - + - `self`：仅当前会话键。 - - `tree`：当前会话 + 当前会话生成的会话（子智能体）。 - - `agent`：属于当前智能体 ID 的任何会话（如果你在同一智能体 ID 下按发送者运行会话，可能包括其他用户）。 + - `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 + - `agent`：属于当前智能体 ID 的任何会话（如果你在同一智能体 ID 下运行按发送者划分的会话，可能包括其他用户）。 - `all`：任何会话。跨智能体定向仍需要 `tools.agentToAgent`。 - - 沙箱限制：当当前会话是沙箱隔离的，并且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 + - 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 @@ -336,12 +336,12 @@ x-i18n: ``` - + - 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 - - 文件会物化到子工作区的 `.openclaw/attachments//`，并带有 `.manifest.json`。 - - 附件内容会自动从转录持久化中删改。 + - 文件会物化到子工作区的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 + - 附件内容会自动从转录持久化中脱敏。 - Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行验证。 - - 文件权限为：目录 `0700`，文件 `0600`。 + - 目录权限为 `0700`，文件权限为 `0600`。 - 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 @@ -351,7 +351,7 @@ x-i18n: ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用严格智能体 GPT-5 自动启用规则。 +实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 ```json5 { @@ -364,8 +364,8 @@ x-i18n: ``` - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或单个智能体覆盖项）针对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围之外强制开启该工具，或设置为 `false` 可即使在严格智能体 GPT-5 运行中也保持关闭。 -- 启用后，系统提示也会添加使用指导，让模型只在实质性工作中使用它，并最多保持一个步骤为 `in_progress`。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每个智能体的覆盖项）为 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围之外强制启用该工具，或设置为 `false`，即使是 strict-agentic GPT-5 运行也保持关闭。 +- 启用后，系统提示词还会添加使用指导，使模型仅将其用于实质性工作，并最多保持一个步骤为 `in_progress`。 ### `agents.defaults.subagents` @@ -385,10 +385,10 @@ x-i18n: } ``` -- `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示不超时。 -- 单个子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`：派生子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认值：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 +- 按子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- @@ -424,19 +424,19 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ ``` - - - 对自定义认证需求使用 `authHeader: true` + `headers`。 - - 使用 `OPENCLAW_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`，一个旧版环境变量别名）覆盖智能体配置根目录。 + + - 对于自定义认证需求，使用 `authHeader: true` + `headers`。 + - 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用 `PI_CODING_AGENT_DIR`，这是旧版环境变量别名）。 - 匹配提供商 ID 的合并优先级： - - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在当前配置/认证配置文件上下文中该提供商未由 SecretRef 管理时优先。 - - SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/执行引用为 `secretref-managed`），而不是持久化已解析的密钥。 - - SecretRef 管理的提供商标头值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/执行引用为 `secretref-managed`）。 - - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置值和隐式目录值中的较高者。 - - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；用它来限制有效上下文，而不改变原生模型元数据。 + - 非空的智能体 `models.json` 中 `baseUrl` 值优先。 + - 非空的智能体 `apiKey` 值仅在当前配置/认证配置文件上下文中该提供商不由 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/执行引用使用 `secretref-managed`），而不是持久化解析后的密钥。 + - 由 SecretRef 管理的提供商标头值会从来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/执行引用使用 `secretref-managed`）。 + - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 会使用显式配置值和隐式目录值中的较高者。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；使用它可以在不更改原生模型元数据的情况下限制有效上下文。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以来源为准：标记会从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。 + - 标记持久化以来源为准：标记从活动来源配置快照（解析前）写入，而不是从解析后的运行时密钥值写入。 @@ -444,64 +444,64 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ ### 提供商字段详情 - + - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 - - `models.providers`：按提供商 ID 键控的自定义提供商映射。 - - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 + - `models.providers`：以提供商 ID 为键的自定义提供商映射。 + - 安全编辑：对于增量更新，使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge`。`config set` 会拒绝破坏性替换，除非你传入 `--replace`。 - - - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。对于自托管的 `/v1/chat/completions` 后端，例如 MLX、vLLM、SGLang 和大多数 OpenAI 兼容本地服务器，请使用 `openai-completions`。带有 `baseUrl` 但没有 `api` 的自定义提供商默认使用 `openai-completions`；仅当后端支持 `/v1/responses` 时才设置 `openai-responses`。 + + - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。对于 MLX、vLLM、SGLang 以及大多数 OpenAI 兼容本地服务器等自托管 `/v1/chat/completions` 后端，使用 `openai-completions`。带有 `baseUrl` 但没有 `api` 的自定义提供商默认使用 `openai-completions`；仅在后端支持 `/v1/responses` 时设置 `openai-responses`。 - `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 - `models.providers.*.contextWindow`：当模型条目未设置 `contextWindow` 时，此提供商下模型的默认原生上下文窗口。 - `models.providers.*.contextTokens`：当模型条目未设置 `contextTokens` 时，此提供商下模型的默认有效运行时上下文上限。 - - `models.providers.*.maxTokens`：当模型条目未设置 `maxTokens` 时，此提供商下模型的默认输出 token 上限。 - - `models.providers.*.timeoutSeconds`：可选的每提供商模型 HTTP 请求超时时间（秒），包括连接、标头、正文和总请求中止处理。 - - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求注入 `options.num_ctx`（默认：`true`）。 - - `models.providers.*.authHeader`：需要时强制通过 `Authorization` 标头传输凭证。 + - `models.providers.*.maxTokens`：当模型条目未设置 `maxTokens` 时，此提供商下模型的默认输出令牌上限。 + - `models.providers.*.timeoutSeconds`：可选的每提供商模型 HTTP 请求超时秒数，包括连接、标头、正文以及总请求中止处理。 + - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认值：`true`）。 + - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 标头传输凭证。 - `models.providers.*.baseUrl`：上游 API 基础 URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态标头。 - + `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖项。 - `request.headers`：额外标头（与提供商默认值合并）。值接受 SecretRef。 - - `request.auth`：认证策略覆盖项。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（带 `token`）、`"header"`（带 `headerName`、`value`、可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖项。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（带 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖项。字段：`ca`、`cert`、`key`、`passphrase`（全部接受 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 解析到私有、CGNAT 或类似范围，允许通过提供商 HTTP fetch 保护访问 `baseUrl` 的 HTTPS（操作员对可信自托管 OpenAI 兼容端点的选择加入）。local loopback 模型提供商流 URL，例如 `localhost`、`127.0.0.1` 和 `[::1]` 会自动允许，除非此项明确设置为 `false`；LAN、tailnet 和私有 DNS 主机仍需选择加入。WebSocket 使用相同的 `request` 来处理标头/TLS，但不使用该 fetch SSRF 门控。默认值为 `false`。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`、可选 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都接受 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 解析到私有、CGNAT 或类似地址范围，则通过提供商 HTTP 获取防护允许 HTTPS 访问 `baseUrl`（操作者为受信任的自托管 OpenAI 兼容端点选择启用）。除非此项显式设置为 `false`，否则 `localhost`、`127.0.0.1` 和 `[::1]` 等回环模型提供商流 URL 会自动允许；局域网、Tailscale 网络和私有 DNS 主机仍需选择启用。WebSocket 对标头/TLS 使用相同的 `request`，但不使用该获取 SSRF 防护。默认值为 `false`。 - + - `models.providers.*.models`：显式提供商模型目录条目。 - - `models.providers.*.models.*.input`：模型输入模态。纯文本模型使用 `["text"]`，原生图像/视觉模型使用 `["text", "image"]`。只有当所选模型标记为支持图像时，图像附件才会注入智能体轮次。 + - `models.providers.*.models.*.input`：模型输入模态。对纯文本模型使用 `["text"]`，对原生图像/视觉模型使用 `["text", "image"]`。只有在所选模型标记为支持图像时，图像附件才会注入智能体轮次。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。这会覆盖该模型的提供商级 `contextWindow`。 - - `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。这会覆盖提供商级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它；`openclaw models list` 会在两个值不同时显示两者。 - - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且非空的非原生 `baseUrl`（主机不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空/省略的 `baseUrl` 保持默认 OpenAI 行为。 - - `models.providers.*.models.*.compat.requiresStringContent`：用于仅字符串 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组展平为普通字符串。 + - `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。这会覆盖提供商级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它；当两者不同时，`openclaw models list` 会显示两个值。 + - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且带有非空、非原生 `baseUrl`（主机不是 `api.openai.com`）的情况，OpenClaw 在运行时会将其强制为 `false`。空值/省略的 `baseUrl` 会保留默认 OpenAI 行为。 + - `models.providers.*.models.*.compat.requiresStringContent`：用于仅接受字符串的 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组扁平化为普通字符串。 - + - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 ID 过滤器。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现模型的回退上下文窗口。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型的回退最大输出 token 数。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的后备最大输出令牌数。 -交互式自定义提供商新手引导会为常见视觉模型 ID 推断图像输入，例如 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V，并对已知纯文本系列跳过额外问题。未知模型 ID 仍会提示确认图像支持。非交互式新手引导使用相同推断；传入 `--custom-image-input` 可强制使用支持图像的元数据，或传入 `--custom-text-input` 可强制使用纯文本元数据。 +交互式自定义提供商新手引导会为 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V 等常见视觉模型 ID 推断图像输入，并对已知纯文本系列跳过额外问题。未知模型 ID 仍会提示是否支持图像。非交互式新手引导使用相同推断；传入 `--custom-image-input` 以强制使用支持图像的元数据，或传入 `--custom-text-input` 以强制使用纯文本元数据。 ### 提供商示例 - - 内置的 `cerebras` 提供商插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置此项。仅在覆盖默认值时才使用显式提供商配置。 + + 内置的 `cerebras` 提供商插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置此项。仅在覆盖默认值时使用显式提供商配置。 ```json5 { @@ -535,7 +535,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 对于 Cerebras 使用 `cerebras/zai-glm-4.7`；对于 Z.AI 直连使用 `zai/glm-4.7`。 + 对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 @@ -551,11 +551,11 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 + Anthropic 兼容的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - 参见[本地模型](/zh-CN/gateway/local-models)。简而言之：在性能足够的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为后备。 + 参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能充足的硬件上通过 LM Studio Responses API 运行大型本地模型；保留已合并的托管模型作为回退。 ```json5 @@ -592,7 +592,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅包含 M2.7。在兼容 Anthropic 的流式路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax 思考。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 + 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认只包含 M2.7。在 Anthropic 兼容的流式传输路径上，OpenClaw 默认禁用 MiniMax thinking，除非你显式自行设置 `thinking`。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 @@ -631,7 +631,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ 对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 - 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式用量兼容性，而 OpenClaw 会根据端点能力启用该行为，而不是只依赖内置提供商 ID。 + 原生 Moonshot 端点会在共享的 `openai-completions` 传输协议上声明流式 usage 兼容性，OpenClaw 会基于端点能力启用该能力，而不是仅依赖内置提供商 ID。 @@ -646,7 +646,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 + 设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，或对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -698,7 +698,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` - 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 + 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` @@ -713,5 +713,5 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ - [配置 — 智能体](/zh-CN/gateway/config-agents) - [配置 — 渠道](/zh-CN/gateway/config-channels) -- [配置参考](/zh-CN/gateway/configuration-reference) — 其他顶级键 +- [配置参考](/zh-CN/gateway/configuration-reference) — 其他顶层键 - [工具和插件](/zh-CN/tools) diff --git a/docs/zh-CN/tools/media-overview.md b/docs/zh-CN/tools/media-overview.md index 5ea49191c..e07850581 100644 --- a/docs/zh-CN/tools/media-overview.md +++ b/docs/zh-CN/tools/media-overview.md @@ -1,42 +1,42 @@ --- read_when: - - 查找 OpenClaw 的媒体能力概览 + - 想了解 OpenClaw 的媒体能力概览 - 决定要配置哪个媒体提供商 - - 了解异步媒体生成的工作方式 + - 了解异步媒体生成的工作原理 sidebarTitle: Media overview -summary: 图像、视频、音乐、语音和媒体理解能力一览 +summary: 图像、视频、音乐、语音和媒体理解能力概览 title: 媒体概览 x-i18n: - generated_at: "2026-04-28T12:05:48Z" + generated_at: "2026-05-05T00:47:29Z" model: gpt-5.5 provider: openai - source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508 + source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059 source_path: tools/media-overview.md workflow: 16 --- -OpenClaw 生成图像、视频和音乐，理解传入媒体（图像、音频、视频），并使用文本转语音大声说出回复。所有媒体能力都由工具驱动：智能体会根据对话决定何时使用它们，并且每个工具只有在至少配置了一个后端提供商时才会出现。 +OpenClaw 生成图像、视频和音乐，理解传入媒体（图像、音频、视频），并通过文本转语音朗读回复。所有媒体能力都由工具驱动：智能体会根据对话决定何时使用它们，并且每个工具只有在至少配置了一个后端提供商时才会出现。 ## 能力 - 通过 `image_generate` 根据文本提示词或参考图像创建和编辑图像。同步执行——随回复内联完成。 + 通过 `image_generate` 使用文本提示词或参考图像创建和编辑图像。同步执行——随回复内联完成。 - 通过 `video_generate` 执行文生视频、图生视频和视频转视频。异步执行——在后台运行，并在结果就绪后发布。 + 通过 `video_generate` 实现文本转视频、图像转视频和视频转视频。异步执行——在后台运行，并在就绪后发布结果。 通过 `music_generate` 生成音乐或音轨。在共享提供商上异步执行；ComfyUI 工作流路径同步运行。 - 通过 `tts` 工具和 `messages.tts` 配置，将发出的回复转换为语音音频。同步执行。 + 通过 `tts` 工具加 `messages.tts` 配置，将外发回复转换为语音音频。同步执行。 - 使用支持视觉的模型提供商和专用媒体理解插件，总结传入的图像、音频和视频。 + 使用具备视觉能力的模型提供商和专用媒体理解插件汇总传入图像、音频和视频。 - 通过批量 STT 或 Voice Call 流式 STT 提供商转录传入的语音消息。 + 通过批处理 STT 或 Voice Call 流式 STT 提供商转录传入语音消息。 @@ -68,7 +68,7 @@ OpenClaw 生成图像、视频和音乐，理解传入媒体（图像、音频 | Xiaomi MiMo | ✓ | | | ✓ | | | ✓ | -媒体理解会使用你的提供商配置中注册的任何支持视觉或支持音频的模型。上面的矩阵列出了具有专用媒体理解支持的提供商；大多数多模态 LLM 提供商（Anthropic、Google、OpenAI 等）在配置为活动回复模型时，也可以理解传入媒体。 +媒体理解会使用在你的提供商配置中注册的任何具备视觉能力或音频能力的模型。上面的矩阵列出了具备专用媒体理解支持的提供商；大多数多模态 LLM 提供商（Anthropic、Google、OpenAI 等）在配置为活动回复模型时，也可以理解传入媒体。 ## 异步与同步 @@ -78,35 +78,35 @@ OpenClaw 生成图像、视频和音乐，理解传入媒体（图像、音频 | 图像 | 同步 | 提供商响应会在数秒内返回；随回复内联完成。 | | 文本转语音 | 同步 | 提供商响应会在数秒内返回；附加到回复音频。 | | 视频 | 异步 | 提供商处理需要 30 秒到数分钟。 | -| 音乐（共享） | 异步 | 与视频具有相同的提供商处理特征。 | -| 音乐（ComfyUI） | 同步 | 本地工作流会针对已配置的 ComfyUI 服务器内联运行。 | +| 音乐（共享） | 异步 | 与视频相同的提供商处理特征。 | +| 音乐（ComfyUI） | 同步 | 本地工作流针对已配置的 ComfyUI 服务器内联运行。 | -对于异步工具，OpenClaw 会将请求提交给提供商，立即返回任务 ID，并在任务账本中跟踪作业。智能体会在作业运行期间继续响应其他消息。当提供商完成后，OpenClaw 会唤醒智能体，使其可以将完成的媒体发布回原始渠道。 +对于异步工具，OpenClaw 会向提供商提交请求，立即返回任务 ID，并在任务账本中跟踪该作业。智能体会在作业运行期间继续回复其他消息。当提供商完成后，OpenClaw 会用生成的媒体路径唤醒智能体，使其可以告知用户，并在源交付策略要求时通过消息工具转发结果。 ## 语音转文本和 Voice Call -Deepgram、DeepInfra、ElevenLabs、Mistral、OpenAI、SenseAudio 和 xAI 在配置后都可以通过批量 `tools.media.audio` 路径转录传入音频。对语音便笺执行预检以进行提及门控或命令解析的渠道插件，会在传入上下文中标记已转录的附件，因此共享媒体理解流程会复用该转录，而不会为同一段音频发起第二次 STT 调用。 +配置后，Deepgram、DeepInfra、ElevenLabs、Mistral、OpenAI、SenseAudio 和 xAI 都可以通过批处理 `tools.media.audio` 路径转录传入音频。对语音备注进行预检以做提及门控或命令解析的渠道插件，会在传入上下文中标记已转录的附件，因此共享媒体理解流程会复用该转录文本，而不是为同一段音频发起第二次 STT 调用。 -Deepgram、ElevenLabs、Mistral、OpenAI 和 xAI 还会注册 Voice Call 流式 STT 提供商，因此实时电话音频可以转发给所选供应商，而无需等待完整录音完成。 +Deepgram、ElevenLabs、Mistral、OpenAI 和 xAI 也会注册 Voice Call 流式 STT 提供商，因此实时电话音频可以转发给选定厂商，而无需等待录音完成。 -## 提供商映射（供应商如何拆分到不同表面） +## 提供商映射（厂商如何分布在各个功能面） - 图像、视频、音乐、批量 TTS、后端实时语音和媒体理解表面。 + 图像、视频、音乐、批处理 TTS、后端实时语音和媒体理解功能面。 - 图像、视频、批量 TTS、批量 STT、Voice Call 流式 STT、后端实时语音和记忆嵌入表面。 + 图像、视频、批处理 TTS、批处理 STT、Voice Call 流式 STT、后端实时语音和记忆嵌入功能面。 - 聊天/模型路由、图像生成/编辑、文本转视频、批量 TTS、批量 STT、图像媒体理解和记忆嵌入表面。在 OpenClaw 为这些类别提供专用提供商契约之前，DeepInfra 原生的重排序/分类/目标检测模型不会注册。 + 聊天/模型路由、图像生成/编辑、文本转视频、批处理 TTS、批处理 STT、图像媒体理解和记忆嵌入功能面。在 OpenClaw 为这些类别提供专用提供商合约之前，DeepInfra 原生的重排、分类和对象检测模型不会注册。 - 图像、视频、搜索、代码执行、批量 TTS、批量 STT 和 Voice Call 流式 STT。xAI Realtime 语音是一项上游能力，但在共享实时语音契约能够表示它之前，不会在 OpenClaw 中注册。 + 图像、视频、搜索、代码执行、批处理 TTS、批处理 STT 和 Voice Call 流式 STT。xAI Realtime voice 是上游能力，但在共享实时语音合约能够表示它之前，不会在 OpenClaw 中注册。 -## 相关 +## 相关内容 - [图像生成](/zh-CN/tools/image-generation) - [视频生成](/zh-CN/tools/video-generation) diff --git a/docs/zh-CN/tools/music-generation.md b/docs/zh-CN/tools/music-generation.md index 8373bddf1..c836e8da9 100644 --- a/docs/zh-CN/tools/music-generation.md +++ b/docs/zh-CN/tools/music-generation.md @@ -4,23 +4,23 @@ read_when: - 配置音乐生成提供商和模型 - 了解 music_generate 工具参数 sidebarTitle: Music generation -summary: 通过 music_generate 在 Google Lyria、MiniMax 和 ComfyUI 工作流中生成音乐 +summary: 通过 `music_generate` 在 Google Lyria、MiniMax 和 ComfyUI 工作流中生成音乐 title: 音乐生成 x-i18n: - generated_at: "2026-05-02T08:00:30Z" + generated_at: "2026-05-05T00:47:29Z" model: gpt-5.5 provider: openai - source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26 + source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650 source_path: tools/music-generation.md workflow: 16 --- -`music_generate` 工具允许智能体通过配置了提供商的共享音乐生成能力创建音乐或音频，目前支持 Google、MiniMax，以及通过工作流配置的 ComfyUI。 +`music_generate` 工具让智能体能够通过配置的提供商使用共享音乐生成能力来创建音乐或音频，目前支持 Google、MiniMax，以及通过工作流配置的 ComfyUI。 -对于由会话支持的智能体运行，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备好后再次唤醒智能体，让智能体可以把完成的音频发回原始渠道。 +对于基于会话的智能体运行，OpenClaw 会将音乐生成作为后台任务启动，在任务台账中跟踪它，然后在曲目准备好后再次唤醒智能体，让智能体通知用户并附上完成的音频。在仅使用消息工具进行可见投递的群组/频道聊天中，智能体会通过消息工具转发结果。 -只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你在智能体的工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API key。 +只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你没有在智能体的工具中看到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API key。 ## 快速开始 @@ -28,9 +28,8 @@ x-i18n: - - 为至少一个提供商设置 API key，例如 - `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。 + + 为至少一个提供商设置 API key，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。 ```json5 @@ -46,26 +45,23 @@ x-i18n: ``` - _“生成一首关于夜晚驾车穿过霓虹城市的欢快合成流行音轨。”_ + _"Generate an upbeat synthpop track about a night drive through a + neon city."_ - 智能体会自动调用 `music_generate`。无需配置工具 - allow-list。 + 智能体会自动调用 `music_generate`。无需将该工具加入允许列表。 - 对于没有由会话支持的智能体运行的直接同步上下文， - 内置工具仍会回退到内联生成，并在工具结果中返回 - 最终媒体路径。 + 对于没有基于会话的智能体运行的直接同步上下文，内置工具仍会回退到内联生成，并在工具结果中返回最终媒体路径。 - 使用工作流 JSON 和提示词/输出节点配置 - `plugins.entries.comfy.config.music`。 + 使用工作流 JSON 以及提示/输出节点配置 `plugins.entries.comfy.config.music`。 - - 对于 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。 + + 对于 Comfy Cloud，设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。 ```text @@ -76,7 +72,7 @@ x-i18n: -示例提示词： +示例提示： ```text Generate a cinematic piano track with soft strings and no vocals. @@ -88,21 +84,21 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## 支持的提供商 -| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | 认证 | +| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | 凭证 | | -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | 最多 1 张图像 | 工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | -| Google | `lyria-3-clip-preview` | 最多 10 张图像 | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.6` | 无 | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` 或 MiniMax OAuth | +| ComfyUI | `workflow` | 最多 1 张图片 | 工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `music-2.6` | 无 | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` 或 MiniMax OAuth | ### 能力矩阵 -`music_generate`、合约测试和共享 live sweep 使用的显式模式合约： +`music_generate`、契约测试和共享 live sweep 使用的显式模式契约： | 提供商 | `generate` | `edit` | 编辑限制 | 共享 live lanes | | -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- | -| ComfyUI | ✓ | ✓ | 1 张图像 | 不在共享 sweep 中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 | -| Google | ✓ | ✓ | 10 张图像 | `generate`, `edit` | -| MiniMax | ✓ | — | 无 | `generate` | +| ComfyUI | ✓ | ✓ | 1 张图片 | 不在共享 sweep 中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 | +| Google | ✓ | ✓ | 10 张图片 | `generate`, `edit` | +| MiniMax | ✓ | — | 无 | `generate` | 使用 `action: "list"` 在运行时检查可用的共享提供商和模型： @@ -110,7 +106,7 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. /tool music_generate action=list ``` -使用 `action: "status"` 检查当前由会话支持的音乐任务： +使用 `action: "status"` 检查当前基于会话的音乐任务： ```text /tool music_generate action=status @@ -125,14 +121,13 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## 工具参数 - 音乐生成提示词。`action: "generate"` 必填。 + 音乐生成提示。`action: "generate"` 需要此参数。 `"status"` 返回当前会话任务；`"list"` 检查提供商。 - 提供商/模型覆盖（例如 `google/lyria-3-pro-preview`, - `comfy/workflow`）。 + 提供商/模型覆盖（例如 `google/lyria-3-pro-preview`、`comfy/workflow`）。 当提供商支持显式歌词输入时使用的可选歌词。 @@ -141,10 +136,10 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. 当提供商支持时，请求仅器乐输出。 - 单个参考图像路径或 URL。 + 单个参考图片路径或 URL。 - 多个参考图像（在支持的提供商上最多 10 张）。 + 多个参考图片（在支持的提供商上最多 10 张）。 当提供商支持时，用秒表示的目标时长提示。 @@ -153,22 +148,22 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. 当提供商支持时使用的输出格式提示。 输出文件名提示。 -可选的提供商请求超时，单位为毫秒。低于 10000ms 的值会提升到 10000ms，并在工具结果中报告。 +可选的提供商请求超时时间，单位为毫秒。低于 10000ms 的值会提升到 10000ms，并在工具结果中报告。 -并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证输入数量等硬性限制。当提供商支持时长但最大值短于请求值时，OpenClaw 会夹取到最接近的受支持时长。对于真正不受支持的可选提示，当所选提供商或模型无法满足时，会被忽略并附带警告。工具结果会报告已应用的设置；`details.normalization` 会捕获任何从请求值到应用值的映射。 +并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证输入数量等硬性限制。当提供商支持时长但最大值短于请求值时，OpenClaw 会将其限制为最接近的受支持时长。对于真正不支持的可选提示，如果所选提供商或模型无法满足，系统会在发出警告后忽略。工具结果会报告已应用的设置；`details.normalization` 会记录任何从请求值到应用值的映射。 ## 异步行为 -由会话支持的音乐生成会作为后台任务运行： +基于会话的音乐生成会作为后台任务运行： -- **后台任务：** `music_generate` 会创建后台任务，立即返回已启动/任务响应，并稍后在后续智能体消息中发布完成的音轨。 -- **重复防护：** 当任务处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是启动另一次生成。使用 `action: "status"` 显式检查。 -- **状态查询：** `openclaw tasks list` 或 `openclaw tasks show ` 会检查 queued、running 和终止状态。 -- **完成唤醒：** OpenClaw 会将内部完成事件注入回同一会话，让模型可以自行编写面向用户的后续消息。 -- **提示词提示：** 当同一会话中已有音乐任务在进行时，后续用户/手动轮次会获得一条小型运行时提示，避免模型盲目再次调用 `music_generate`。 -- **无会话回退：** 没有真实智能体会话的直接/本地上下文会内联运行，并在同一轮中返回最终音频结果。 +- **后台任务：** `music_generate` 会创建后台任务，立即返回已启动/任务响应，并稍后在后续智能体消息中发布完成的曲目。 +- **防止重复：** 当任务处于 `queued` 或 `running` 状态时，同一会话中的后续 `music_generate` 调用会返回任务状态，而不是启动另一次生成。使用 `action: "status"` 可显式检查。 +- **状态查询：** `openclaw tasks list` 或 `openclaw tasks show ` 可检查排队中、运行中和终止状态。 +- **完成唤醒：** OpenClaw 会将内部完成事件注入回同一会话，让模型可以自行写出面向用户的后续消息。 +- **提示提示：** 同一会话中后续的用户/手动轮次会在音乐任务已经进行中时获得一个小的运行时提示，避免模型盲目再次调用 `music_generate`。 +- **无会话回退：** 没有真实智能体会话的直接/本地上下文会以内联方式运行，并在同一轮返回最终音频结果。 ### 任务生命周期 @@ -176,7 +171,7 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. | ----------- | ---------------------------------------------------------------------------------------------- | | `queued` | 任务已创建，正在等待提供商接受。 | | `running` | 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。 | -| `succeeded` | 音轨已准备好；智能体会被唤醒并将其发布到对话中。 | +| `succeeded` | 曲目已准备好；智能体会被唤醒并将其发布到对话中。 | | `failed` | 提供商错误或超时；智能体会带着错误详情被唤醒。 | 从 CLI 检查状态： @@ -208,47 +203,44 @@ openclaw tasks cancel OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 `model` 参数（如果智能体指定了一个）。 +1. 工具调用中的 `model` 参数（如果智能体指定了）。 2. 配置中的 `musicGenerationModel.primary`。 3. 按顺序使用 `musicGenerationModel.fallbacks`。 -4. 仅使用带认证的提供商默认值进行自动检测： - - 当前默认提供商优先； - - 其余已注册的音乐生成提供商按 provider-id 顺序。 +4. 仅使用基于凭证的提供商默认值进行自动检测： + - 先使用当前默认提供商； + - 其余已注册的音乐生成提供商按提供商 ID 顺序使用。 如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误会包含每次尝试的详情。 -将 `agents.defaults.mediaGenerationAutoProviderFallback: false` 设为仅使用显式的 `model`、`primary` 和 `fallbacks` 条目。 +设置 `agents.defaults.mediaGenerationAutoProviderFallback: false` 可仅使用显式的 `model`、`primary` 和 `fallbacks` 条目。 ## 提供商说明 - 由工作流驱动，并依赖为提示词/输出字段配置的图和节点映射。内置的 `comfy` 插件会通过音乐生成提供商注册表接入共享的 `music_generate` 工具。 + 由工作流驱动，依赖为提示/输出字段配置的图和节点映射。内置 `comfy` 插件通过音乐生成提供商注册表接入共享 `music_generate` 工具。 - - 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本，以及可选参考图像。 + + 使用 Lyria 3 批量生成。当前内置流程支持提示、可选歌词文本和可选参考图片。 - 使用批量 `music_generation` 端点。支持提示词、可选歌词、器乐模式、时长控制，以及通过 `minimax` API key 认证或 `minimax-portal` OAuth 进行 mp3 输出。 + 使用批量 `music_generation` 端点。支持提示、可选歌词、器乐模式、时长引导，以及通过 `minimax` API key 凭证或 `minimax-portal` OAuth 输出 mp3。 ## 选择合适路径 -- **共享提供商支持**：当你需要模型选择、提供商故障转移，以及内置异步任务/状态流程时使用。 -- **插件路径（ComfyUI）**：当你需要自定义工作流图，或需要不属于共享内置音乐能力的提供商时使用。 +- **共享提供商支持** 适用于需要模型选择、提供商故障转移，以及内置异步任务/状态流程的场景。 +- **插件路径（ComfyUI）** 适用于需要自定义工作流图，或需要未纳入共享内置音乐能力的提供商的场景。 -如果你正在调试 ComfyUI 特定行为，请参阅 -[ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商 -行为，请从 [Google（Gemini）](/zh-CN/providers/google) 或 -[MiniMax](/zh-CN/providers/minimax) 开始。 +如果你正在调试 ComfyUI 特定行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请从 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。 ## 提供商能力模式 -共享音乐生成合约支持显式模式声明： +共享音乐生成契约支持显式模式声明： -- `generate` 用于仅提示词生成。 -- `edit` 用于请求包含一个或多个参考图像的情况。 +- `generate` 用于仅基于提示的生成。 +- 当请求包含一个或多个参考图片时使用 `edit`。 新的提供商实现应优先使用显式模式块： @@ -268,13 +260,11 @@ capabilities: { } ``` -旧版扁平字段，例如 `maxInputImages`、`supportsLyrics` 和 -`supportsFormat`，**不足以** 声明编辑支持。提供商应显式声明 -`generate` 和 `edit`，以便 live tests、合约测试和共享的 `music_generate` 工具可以确定性地验证模式支持。 +`maxInputImages`、`supportsLyrics` 和 `supportsFormat` 等旧版扁平字段**不足以**声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便 live 测试、契约测试和共享 `music_generate` 工具能够确定性地验证模式支持。 -## Live tests +## Live 测试 -共享内置提供商的选择加入式 live 覆盖： +共享内置提供商的选择性启用 live 覆盖： ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts @@ -286,23 +276,23 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv pnpm test:live:media music ``` -这个 live 文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用 live/env API key，而不是已存储的认证配置文件，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。当前覆盖： +这个 live 文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用 live/env API key 而不是已存储的凭证配置文件，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。当前覆盖范围： - `google`：`generate` 加 `edit` - `minimax`：仅 `generate` - `comfy`：单独的 Comfy live 覆盖，不属于共享提供商 sweep -内置 ComfyUI 音乐路径的选择加入式 live 覆盖： +内置 ComfyUI 音乐路径的选择性启用 live 覆盖： ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -Comfy live 文件还会涵盖已配置相关部分时的 comfy 图像和视频工作流。 +当这些部分已配置时，Comfy live 文件还会覆盖 Comfy 图像和视频工作流。 -## 相关 +## 相关内容 -- [后台任务](/zh-CN/automation/tasks) — 用于跟踪分离的 `music_generate` 运行任务 +- [后台任务](/zh-CN/automation/tasks) — 用于跟踪分离式 `music_generate` 运行的任务 - [ComfyUI](/zh-CN/providers/comfy) - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — `musicGenerationModel` 配置 - [Google (Gemini)](/zh-CN/providers/google) diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index 20658b6b4..08b566c86 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -4,36 +4,36 @@ read_when: - 配置视频生成提供商和模型 - 理解 video_generate 工具参数 sidebarTitle: Video generation -summary: 通过 video_generate 基于文本、图像或视频引用生成视频，支持 16 个提供商后端 +summary: 通过 video_generate 基于文本、图片或视频引用，在 16 个提供商后端生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-28T12:07:04Z" + generated_at: "2026-05-05T00:47:32Z" model: gpt-5.5 provider: openai - source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf + source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83 source_path: tools/video-generation.md workflow: 16 --- -OpenClaw 智能体可以从文本提示、参考图像或现有视频生成视频。支持十六种 provider 后端，每种后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用 API 密钥自动选择合适的 provider。 +OpenClaw 智能体可以根据文本提示词、参考图像或现有视频生成视频。支持十六个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用 API key 自动选择合适的提供商。 -只有当至少一个视频生成 provider 可用时，`video_generate` 工具才会出现。如果你在智能体工具中看不到它，请设置 provider API 密钥或配置 `agents.defaults.videoGenerationModel`。 +只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你在智能体工具中看不到它，请设置提供商 API key 或配置 `agents.defaults.videoGenerationModel`。 OpenClaw 将视频生成视为三种运行时模式： -- `generate` — 没有参考媒体的文本生成视频请求。 +- `generate` — 不带参考媒体的文生视频请求。 - `imageToVideo` — 请求包含一个或多个参考图像。 - `videoToVideo` — 请求包含一个或多个参考视频。 -Provider 可以支持这些模式的任意子集。该工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。 +提供商可以支持这些模式的任意子集。该工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。 ## 快速开始 - - 为任意受支持的 provider 设置 API 密钥： + + 为任一受支持的提供商设置 API key： ```bash export GEMINI_API_KEY="your-key" @@ -46,9 +46,9 @@ Provider 可以支持这些模式的任意子集。该工具会在提交前验 ``` - > 生成一个 5 秒的电影感视频，内容是一只友好的龙虾在日落时冲浪。 + > 生成一段 5 秒的电影感视频，内容是一只友好的龙虾在日落时冲浪。 - 智能体会自动调用 `video_generate`。不需要工具允许列表。 + 智能体会自动调用 `video_generate`。不需要将工具加入允许列表。 @@ -57,25 +57,25 @@ Provider 可以支持这些模式的任意子集。该工具会在提交前验 视频生成是异步的。当智能体在会话中调用 `video_generate` 时： -1. OpenClaw 将请求提交给 provider，并立即返回任务 ID。 -2. Provider 在后台处理作业（通常为 30 秒到 5 分钟，取决于 provider 和分辨率）。 -3. 视频准备好后，OpenClaw 会用内部完成事件唤醒同一会话。 -4. 智能体将完成的视频发回原始对话。 +1. OpenClaw 将请求提交给提供商，并立即返回任务 ID。 +2. 提供商在后台处理作业（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 +3. 视频准备好后，OpenClaw 会用内部完成事件唤醒同一个会话。 +4. 智能体会通知用户并附上生成完成的视频。在使用仅消息工具可见投递的群聊/渠道聊天中，智能体会通过消息工具转发结果，而不是由 OpenClaw 直接发布。 -当作业正在进行时，同一会话中的重复 `video_generate` 调用会返回当前任务状态，而不是启动另一次生成。使用 `openclaw tasks list` 或 `openclaw tasks show ` 从 CLI 检查进度。 +当某个作业正在进行时，同一会话中的重复 `video_generate` 调用会返回当前任务状态，而不是启动另一次生成。使用 `openclaw tasks list` 或 `openclaw tasks show ` 从 CLI 检查进度。 在没有会话支持的智能体运行之外（例如直接工具调用），该工具会回退到内联生成，并在同一轮中返回最终媒体路径。 -当 provider 返回字节时，生成的视频文件会保存在 OpenClaw 管理的媒体存储下。默认的生成视频保存上限遵循视频媒体限制，`agents.defaults.mediaMaxMb` 会为更大的渲染提高该限制。当 provider 还返回托管输出 URL 时，如果本地持久化因文件过大而拒绝，OpenClaw 可以交付该 URL，而不是让任务失败。 +当提供商返回字节时，生成的视频文件会保存在 OpenClaw 管理的媒体存储下。默认的生成视频保存上限遵循视频媒体限制，`agents.defaults.mediaMaxMb` 可提高该上限以支持更大的渲染结果。当提供商还返回托管输出 URL 时，如果本地持久化因文件过大而拒绝保存，OpenClaw 可以投递该 URL，而不是让任务失败。 ### 任务生命周期 | 状态 | 含义 | | ----------- | ------------------------------------------------------------------------------------------------ | -| `queued` | 任务已创建，正在等待 provider 接受。 | -| `running` | Provider 正在处理（通常为 30 秒到 5 分钟，取决于 provider 和分辨率）。 | -| `succeeded` | 视频已准备好；智能体会被唤醒并将其发布到对话中。 | -| `failed` | Provider 错误或超时；智能体会被唤醒并提供错误详情。 | +| `queued` | 任务已创建，正在等待提供商接受。 | +| `running` | 提供商正在处理（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 | +| `succeeded` | 视频已准备好；智能体会被唤醒并将其发布到对话中。 | +| `failed` | 提供商错误或超时；智能体会被唤醒并携带错误详情。 | 从 CLI 检查状态： @@ -85,60 +85,60 @@ openclaw tasks show openclaw tasks cancel ``` -如果当前会话已有视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可在不触发新生成的情况下显式检查。 +如果当前会话已经有一个视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可在不触发新生成的情况下显式检查。 -## 支持的 provider +## 受支持的提供商 -| Provider | 默认模型 | 文本 | 图像参考 | 视频参考 | 认证 | +| 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | 凭证 | | --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- | | Alibaba | `wan2.6-t2v` | ✓ | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` | -| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | 最多 2 张图像（仅 I2V 模型；第一帧 + 最后一帧） | — | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | 最多 2 张图像（通过角色指定第一帧 + 最后一帧） | — | `BYTEPLUS_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | 最多 2 张图像（仅 I2V 模型；首帧 + 尾帧） | — | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | 最多 2 张图像（通过角色指定首帧 + 尾帧） | — | `BYTEPLUS_API_KEY` | | BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | 最多 9 张参考图像 | 最多 3 个视频 | `BYTEPLUS_API_KEY` | | ComfyUI | `workflow` | ✓ | 1 张图像 | — | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | | DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 张图像；使用 Seedance reference-to-video 时最多 9 张 | 使用 Seedance reference-to-video 时最多 3 个视频 | `FAL_KEY` | +| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 张图像；使用 Seedance 参考转视频时最多 9 张 | 使用 Seedance 参考转视频时最多 3 个视频 | `FAL_KEY` | | Google | `veo-3.1-fast-generate-preview` | ✓ | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` | | MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 张图像 | — | `MINIMAX_API_KEY` 或 MiniMax OAuth | | OpenAI | `sora-2` | ✓ | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` | -| OpenRouter | `google/veo-3.1-fast` | ✓ | 最多 4 张图像（第一帧/最后一帧或参考图像） | — | `OPENROUTER_API_KEY` | +| OpenRouter | `google/veo-3.1-fast` | ✓ | 最多 4 张图像（首帧/尾帧或参考图像） | — | `OPENROUTER_API_KEY` | | Qwen | `wan2.6-t2v` | ✓ | 是（远程 URL） | 是（远程 URL） | `QWEN_API_KEY` | | Runway | `gen4.5` | ✓ | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` | | Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 张图像 | — | `TOGETHER_API_KEY` | | Vydra | `veo3` | ✓ | 1 张图像（`kling`） | — | `VYDRA_API_KEY` | | xAI | `grok-imagine-video` | ✓ | 1 张首帧图像或最多 7 个 `reference_image` | 1 个视频 | `XAI_API_KEY` | -一些 provider 接受额外或替代的 API 密钥环境变量。详情请参阅各个 [provider 页面](#related)。 +一些提供商接受额外或替代的 API key 环境变量。详情请参阅各个[提供商页面](#related)。 -运行 `video_generate action=list` 可在运行时检查可用 provider、模型和运行时模式。 +运行 `video_generate action=list` 可在运行时查看可用的提供商、模型和运行时模式。 ### 能力矩阵 `video_generate`、契约测试和共享实时扫描使用的显式模式契约： -| Provider | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时通道 | +| 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 目前的共享实时通道 | | ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 需要远程 `http(s)` 视频 URL | +| Alibaba | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此提供商需要远程 `http(s)` 视频 URL | | BytePlus | ✓ | ✓ | — | `generate`、`imageToVideo` | -| ComfyUI | ✓ | ✓ | — | 不在共享扫描中；工作流特定覆盖由 Comfy 测试维护 | -| DeepInfra | ✓ | — | — | `generate`；内置契约中的原生 DeepInfra 视频 schema 是文本生成视频 | -| fal | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；仅在使用 Seedance reference-to-video 时支持 `videoToVideo` | -| Google | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过共享 `videoToVideo`，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 | +| ComfyUI | ✓ | ✓ | — | 不在共享扫描中；工作流特定覆盖位于 Comfy 测试中 | +| DeepInfra | ✓ | — | — | `generate`；内置契约中的原生 DeepInfra 视频 schema 是文生视频 | +| fal | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；仅在使用 Seedance 参考转视频时支持 `videoToVideo` | +| Google | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过共享 `videoToVideo`，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 | | MiniMax | ✓ | ✓ | — | `generate`、`imageToVideo` | -| OpenAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过共享 `videoToVideo`，因为此组织/输入路径当前需要 provider 侧 inpaint/remix 访问权限 | +| OpenAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过共享 `videoToVideo`，因为此组织/输入路径目前需要提供商侧 inpaint/remix 访问权限 | | OpenRouter | ✓ | ✓ | — | `generate`、`imageToVideo` | -| Qwen | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 需要远程 `http(s)` 视频 URL | +| Qwen | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此提供商需要远程 `http(s)` 视频 URL | | Runway | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时运行 `videoToVideo` | | Together | ✓ | ✓ | — | `generate`、`imageToVideo` | -| Vydra | ✓ | ✓ | — | `generate`；跳过共享 `imageToVideo`，因为内置 `veo3` 仅支持文本，且内置 `kling` 需要远程图像 URL | -| xAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 当前需要远程 MP4 URL | +| Vydra | ✓ | ✓ | — | `generate`；跳过共享 `imageToVideo`，因为内置 `veo3` 仅支持文本，且内置 `kling` 需要远程图像 URL | +| xAI | ✓ | ✓ | ✓ | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此提供商目前需要远程 MP4 URL | ## 工具参数 -### 必需 +### 必填 - 要生成的视频的文本描述。`action: "generate"` 必需。 + 要生成的视频的文本描述。`action: "generate"` 需要此项。 ### 内容输入 @@ -146,55 +146,55 @@ openclaw tasks cancel 单个参考图像（路径或 URL）。 多个参考图像（最多 9 个）。 -可选的按位置角色提示，与合并后的图像列表并行。 +可选的逐位置角色提示，与合并后的图像列表并行。 规范值：`first_frame`、`last_frame`、`reference_image`。 单个参考视频（路径或 URL）。 多个参考视频（最多 4 个）。 -可选的按位置角色提示，与合并后的视频列表并行。 +可选的逐位置角色提示，与合并后的视频列表并行。 规范值：`reference_video`。 -单个参考音频（路径或 URL）。当提供商支持音频输入时，用于背景音乐或语音 +单个参考音频（路径或 URL）。当提供商支持音频输入时，用作背景音乐或语音 参考。 多个参考音频（最多 3 个）。 -可选的按位置角色提示，与合并后的音频列表并行。 +可选的逐位置角色提示，与合并后的音频列表并行。 规范值：`reference_audio`。 -角色提示会按原样转发给提供商。规范值来自 -`VideoGenerationAssetRole` 联合类型，但提供商可能接受额外的 -角色字符串。`*Roles` 数组的条目数不得超过对应的 -参考列表；差一错误会以明确错误失败。 -使用空字符串可让某个槽位保持未设置。对于 xAI，将每个图像角色都设为 -`reference_image`，以使用它的 `reference_images` 生成模式；对于单图像图生视频， +角色提示会原样转发给提供商。规范值来自 +`VideoGenerationAssetRole` 联合类型，但提供商可能接受其他 +角色字符串。`*Roles` 数组的条目数不得多于 +对应参考列表；差一错误会失败并显示清晰错误。 +使用空字符串可让某个槽位保持未设置。对于 xAI，将每个图像角色都设置为 +`reference_image` 可使用它的 `reference_images` 生成模式；对于单图像 image-to-video， 省略角色或使用 `first_frame`。 -### 样式控制 +### 样式控制项 - `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，或 `adaptive`。 + `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` 或 `adaptive`。 -`480P`、`720P`、`768P`，或 `1080P`。 +`480P`、`720P`、`768P` 或 `1080P`。 - 目标时长，单位为秒（四舍五入到最接近的提供商支持值）。 + 目标时长（秒，四舍五入到最近的提供商支持值）。 -当提供商支持时使用的尺寸提示。 +提供商支持时使用的大小提示。 - 在支持时为输出启用生成的音频。不同于 `audioRef*`（输入）。 + 在支持时启用输出中的生成音频。不同于 `audioRef*`（输入）。 在支持时切换提供商水印。 -`adaptive` 是提供商特定的哨兵值：它会按原样转发给 +`adaptive` 是一个提供商特定的哨兵值：它会原样转发给 在能力中声明 `adaptive` 的提供商（例如 BytePlus -Seedance 使用它根据输入图像 -尺寸自动检测比例）。未声明它的提供商会通过 -工具结果中的 `details.ignoredOverrides` 显示该值，因此被丢弃的设置可见。 +Seedance 使用它根据输入图像尺寸自动检测比例）。 +未声明它的提供商会在工具结果的 +`details.ignoredOverrides` 中暴露该值，以便清楚显示被丢弃。 ### 高级 @@ -203,84 +203,84 @@ Seedance 使用它根据输入图像 提供商/模型覆盖（例如 `runway/gen4.5`）。 输出文件名提示。 -可选的提供商请求超时，单位为毫秒。 +可选的提供商请求超时时间（毫秒）。 - 作为 JSON 对象的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。 - 声明了类型化 schema 的提供商会验证键和类型；未知 - 键或不匹配会在回退期间跳过该候选。未 - 声明 schema 的提供商会按原样接收这些选项。运行 `video_generate action=list` - 可查看每个提供商接受的内容。 + 以 JSON 对象表示的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。 + 声明了类型化架构的提供商会验证键名和类型；未知 + 键名或不匹配会在回退期间跳过该候选项。未 + 声明架构的提供商会原样接收这些选项。运行 `video_generate action=list` + 查看每个提供商接受的内容。 并非所有提供商都支持所有参数。OpenClaw 会将时长规范化为 最接近的提供商支持值，并在回退提供商暴露不同 -控制面时，重新映射已翻译的几何提示， -例如从尺寸到宽高比。真正不受支持的覆盖会以尽力而为 +控制面时，重新映射已转换的几何提示， +例如从大小到宽高比。真正不支持的覆盖项会按尽力而为 方式忽略，并在工具结果中报告为警告。硬性能力限制 （例如参考输入过多）会在提交前失败。工具结果 会报告已应用的设置；`details.normalization` 会记录任何 -从请求到应用的转换。 +从请求值到应用值的转换。 -参考输入会选择运行时模式： +参考输入决定运行时模式： -- 没有参考媒体 → `generate` +- 无参考媒体 → `generate` - 任意图像参考 → `imageToVideo` - 任意视频参考 → `videoToVideo` -- 参考音频输入**不会**改变解析出的模式；它们会应用在 - 图像/视频参考选择出的任何模式之上，并且只适用于 - 声明了 `maxInputAudios` 的提供商。 +- 参考音频输入**不会**改变解析出的模式；它们会叠加到 + 图像/视频参考所选择的任何模式之上，并且仅适用于 + 声明 `maxInputAudios` 的提供商。 -混合图像和视频参考不是稳定的共享能力面。 +混合图像和视频参考并不是稳定的共享能力面。 建议每个请求只使用一种参考类型。 #### 回退和类型化选项 -某些能力检查会在回退层而非 -工具边界应用，因此超出主提供商限制的请求 +某些能力检查会应用在回退层，而不是 +工具边界，因此超过主提供商限制的请求 仍可在有能力的回退上运行： -- 当请求包含音频参考时，会跳过未声明 `maxInputAudios`（或为 `0`）的 - 活跃候选；然后尝试下一个候选。 -- 活跃候选的 `maxDurationSeconds` 低于请求的 `durationSeconds`， +- 当请求包含音频参考时，会跳过未声明 `maxInputAudios`（或为 `0`）的活动候选项； + 然后尝试下一个候选项。 +- 活动候选项的 `maxDurationSeconds` 低于请求的 `durationSeconds` 且未声明 `supportedDurationSeconds` 列表 → 跳过。 -- 请求包含 `providerOptions`，且活跃候选显式 - 声明了类型化 `providerOptions` schema → 如果提供的键 - 不在 schema 中，或值类型不匹配，则跳过。未 - 声明 schema 的提供商会按原样接收选项（向后兼容 - 透传）。提供商可以通过 - 声明空 schema（`capabilities.providerOptions: {}`）选择不接受所有提供商选项， - 这会导致与类型不匹配相同的跳过。 +- 请求包含 `providerOptions`，且活动候选项显式 + 声明了类型化 `providerOptions` 架构 → 如果提供的键名 + 不在架构中或值类型不匹配，则跳过。未 + 声明架构的提供商会原样接收选项（向后兼容的 + 透传）。提供商可以通过声明空架构 + (`capabilities.providerOptions: {}`) 选择不接受任何提供商选项， + 这会导致与类型不匹配相同的跳过行为。 -请求中的第一个跳过原因会以 `warn` 记录，使操作员看到 -他们的主提供商何时被跳过；后续跳过会以 `debug` 记录， -以保持较长回退链安静。如果每个候选都被跳过， -聚合错误会包含每个候选的跳过原因。 +请求中的第一个跳过原因会以 `warn` 级别记录，以便运维人员看到 +其主提供商何时被跳过；后续跳过会以 `debug` 级别记录，以 +让较长回退链保持安静。如果每个候选项都被跳过， +聚合错误会包含每个候选项的跳过原因。 ## 操作 -| 操作 | 作用 | -| ---------- | -------------------------------------------------------------------------------------------------------- | -| `generate` | 默认。根据给定提示词和可选参考输入创建视频。 | -| `status` | 在不启动另一次生成的情况下，检查当前会话中正在进行的视频任务状态。 | -| `list` | 显示可用的提供商、模型及其能力。 | +| 操作 | 作用 | +| ---------- | ------------------------------------------------------------------------------------------------------ | +| `generate` | 默认。根据给定提示词和可选参考输入创建视频。 | +| `status` | 检查当前会话正在进行的视频任务状态，而不启动另一个生成。 | +| `list` | 显示可用提供商、模型及其能力。 | ## 模型选择 OpenClaw 按以下顺序解析模型： -1. **`model` 工具参数** — 如果智能体在调用中指定了它。 +1. **`model` 工具参数** — 如果智能体在调用中指定了一个。 2. 配置中的 **`videoGenerationModel.primary`**。 3. 按顺序使用 **`videoGenerationModel.fallbacks`**。 -4. **自动检测** — 具有有效凭证的提供商，从 - 当前默认提供商开始，然后是按字母 - 顺序排列的其余提供商。 +4. **自动检测** — 拥有有效凭证的提供商，从 + 当前默认提供商开始，然后按字母顺序使用其余 + 提供商。 -如果某个提供商失败，会自动尝试下一个候选。如果所有 -候选都失败，错误会包含每次尝试的详情。 +如果提供商失败，会自动尝试下一个候选项。如果所有 +候选项都失败，错误会包含每次尝试的详细信息。 -将 `agents.defaults.mediaGenerationAutoProviderFallback: false` 设为 false，可仅使用 +设置 `agents.defaults.mediaGenerationAutoProviderFallback: false` 可仅使用 显式的 `model`、`primary` 和 `fallbacks` 条目。 ```json5 @@ -304,15 +304,15 @@ OpenClaw 按以下顺序解析模型： 视频必须是远程 `http(s)` URL。 - 提供商 id：`byteplus`。 + 提供商 ID：`byteplus`。 模型：`seedance-1-0-pro-250528`（默认）、 `seedance-1-0-pro-t2v-250528`、`seedance-1-0-pro-fast-251015`、 `seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。 T2V 模型（`*-t2v-*`）不接受图像输入；I2V 模型和 - 通用 `*-pro-*` 模型支持单个参考图像（首 - 帧）。按位置传入图像，或设置 `role: "first_frame"`。 + 通用 `*-pro-*` 模型支持单个参考图像（第一帧）。 + 按位置传入图像，或设置 `role: "first_frame"`。 当提供图像时，T2V 模型 ID 会自动切换到对应的 I2V 变体。 @@ -322,45 +322,45 @@ OpenClaw 按以下顺序解析模型： 需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) - 插件。提供商 id：`byteplus-seedance15`。模型： + 插件。提供商 ID：`byteplus-seedance15`。模型： `seedance-1-5-pro-251215`。 - 使用统一的 `content[]` API。最多支持 2 个输入图像 + 使用统一的 `content[]` API。最多支持 2 张输入图像 （`first_frame` + `last_frame`）。所有输入都必须是远程 `https://` - URL。在每个图像上设置 `role: "first_frame"` / `"last_frame"`，或 + URL。在每张图像上设置 `role: "first_frame"` / `"last_frame"`，或 按位置传入图像。 `aspectRatio: "adaptive"` 会根据输入图像自动检测比例。 - `audio: true` 映射到 `generate_audio`。会转发 `providerOptions.seed` - （数字）。 + `audio: true` 映射到 `generate_audio`。`providerOptions.seed` + （数字）会被转发。 需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) - 插件。提供商 id：`byteplus-seedance2`。模型： + 插件。提供商 ID：`byteplus-seedance2`。模型： `dreamina-seedance-2-0-260128`、 `dreamina-seedance-2-0-fast-260128`。 - 使用统一的 `content[]` API。最多支持 9 个参考图像、 + 使用统一的 `content[]` API。最多支持 9 张参考图像、 3 个参考视频和 3 个参考音频。所有输入都必须是远程 - `https://` URL。在每个资源上设置 `role` — 支持的值： + `https://` URL。在每个素材上设置 `role` — 支持的值： `"first_frame"`、`"last_frame"`、`"reference_image"`、 `"reference_video"`、`"reference_audio"`。 `aspectRatio: "adaptive"` 会根据输入图像自动检测比例。 - `audio: true` 映射到 `generate_audio`。会转发 `providerOptions.seed` - （数字）。 + `audio: true` 映射到 `generate_audio`。`providerOptions.seed` + （数字）会被转发。 - 工作流驱动的本地或云端执行。通过配置的图支持文生视频和 - 图生视频。 + 工作流驱动的本地或云端执行。通过已配置的图支持 text-to-video 和 + image-to-video。 对长时间运行的作业使用基于队列的流程。大多数 fal 视频模型 - 接受单个图像参考。Seedance 2.0 参考到视频 - 模型最多接受 9 个图像、3 个视频和 3 个音频参考， - 且参考文件总数最多为 12 个。 + 接受单个图像参考。Seedance 2.0 reference-to-video + 模型最多接受 9 张图像、3 个视频和 3 个音频参考， + 总参考文件数最多为 12 个。 支持一个图像或一个视频参考。 @@ -369,43 +369,44 @@ OpenClaw 按以下顺序解析模型： 仅支持单个图像参考。 - 仅转发 `size` 覆盖。其他样式覆盖 - （`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并附带 - 警告。 + 仅转发 `size` 覆盖项。其他样式覆盖项 + （`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并 + 发出警告。 使用 OpenRouter 的异步 `/videos` API。OpenClaw 会提交 - 作业，轮询 `polling_url`，并下载 `unsigned_urls` 或 + 作业、轮询 `polling_url`，并下载 `unsigned_urls` 或 文档化的作业内容端点。内置的 `google/veo-3.1-fast` 默认值 - 声明支持 4/6/8 秒时长、`720P`/`1080P` 分辨率，以及 + 标示支持 4/6/8 秒时长、`720P`/`1080P` 分辨率，以及 `16:9`/`9:16` 宽高比。 - 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 + 使用与 Alibaba 相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会预先被拒绝。 - 通过 data URI 支持本地文件。视频到视频需要 - `runway/gen4_aleph`。纯文本运行暴露 `16:9` 和 `9:16` 宽高比。 + 通过 data URI 支持本地文件。Video-to-video 需要 + `runway/gen4_aleph`。纯文本运行暴露 `16:9` 和 `9:16` 宽高 + 比。 仅支持单个图像参考。 - 直接使用 `https://www.vydra.ai/api/v1`，以避免丢失认证的 - 重定向。`veo3` 内置为仅文生视频；`kling` 需要 + 直接使用 `https://www.vydra.ai/api/v1` 以避免会丢失凭证的 + 重定向。`veo3` 内置为仅 text-to-video；`kling` 需要 远程图像 URL。 - 支持文生视频、单个首帧图生视频、通过 xAI `reference_images` 提供最多 7 个 - `reference_image` 输入，以及远程 + 支持 text-to-video、单个首帧 image-to-video、通过 xAI + `reference_images` 最多 7 个 `reference_image` 输入，以及远程 视频编辑/扩展流程。 ## 提供商能力模式 -共享的视频生成契约支持特定模式的能力，而不只是扁平的汇总限制。新的提供商实现应优先使用显式模式块： +共享的视频生成契约支持按模式划分的能力，而不只是扁平的聚合限制。新的提供商实现应优先使用显式模式块： ```typescript capabilities: { @@ -430,42 +431,42 @@ capabilities: { } ``` -`maxInputImages` 和 `maxInputVideos` 等扁平汇总字段**不足以**声明对转换模式的支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，以便实时测试、契约测试和共享的 `video_generate` 工具能够以确定性方式验证模式支持。 +诸如 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段**不足以**声明转换模式支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，以便实时测试、契约测试和共享的 `video_generate` 工具能够确定性地验证模式支持。 -当某个提供商中的一个模型比其他模型支持更广泛的参考输入时，请使用 `maxInputImagesByModel`、`maxInputVideosByModel` 或 `maxInputAudiosByModel`，而不是提高整个模式的限制。 +当一个提供商中的某个模型比其他模型支持更宽泛的参考输入时，请使用 `maxInputImagesByModel`、`maxInputVideosByModel` 或 `maxInputAudiosByModel`，而不是提高整个模式的限制。 ## 实时测试 -为共享的内置提供商启用可选实时覆盖： +为共享的内置提供商选择启用实时覆盖： ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts ``` -仓库封装命令： +仓库包装器： ```bash pnpm test:live:media video ``` -这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API key，而不是已存储的认证配置文件，并默认运行适合发布的冒烟测试： +此实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API key，而不是已存储的认证配置文件，并默认运行发布安全的冒烟测试： -- 扫描中每个非 FAL 提供商都会运行 `generate`。 -- 一秒龙虾提示词。 +- 对扫描中的每个非 FAL 提供商运行 `generate`。 +- 一秒钟龙虾提示词。 - 每个提供商的操作上限来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`（默认 `180000`）。 -FAL 需要显式启用，因为提供商侧队列延迟可能主导发布时间： +FAL 是选择启用项，因为提供商端队列延迟可能主导发布时间： ```bash pnpm test:live:media video --video-providers fal ``` -设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，还会运行共享扫描可以用本地媒体安全执行的已声明转换模式： +设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，还会运行共享扫描可使用本地媒体安全执行的已声明转换模式： - 当 `capabilities.imageToVideo.enabled` 时运行 `imageToVideo`。 -- 当 `capabilities.videoToVideo.enabled` 且提供商/模型接受共享扫描中的缓冲区支持本地视频输入时运行 `videoToVideo`。 +- 当 `capabilities.videoToVideo.enabled` 且该提供商/模型在共享扫描中接受由缓冲区支持的本地视频输入时运行 `videoToVideo`。 -目前，只有当你选择 `runway/gen4_aleph` 时，共享的 `videoToVideo` 实时测试通道才会覆盖 `runway`。 +目前，共享的 `videoToVideo` 实时通道仅在你选择 `runway/gen4_aleph` 时覆盖 `runway`。 ## 配置 @@ -484,7 +485,7 @@ pnpm test:live:media video --video-providers fal } ``` -或通过 CLI 设置： +或通过 CLI： ```bash openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"