diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index 766a4b34d..e61709e9a 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -1,57 +1,59 @@ --- read_when: - - 你想使用内置的 Codex app-server harness + - 你想使用内置的 Codex app-server 测试框架 - 你需要 Codex 模型引用和配置示例 - - 你想为仅使用 Codex 的部署禁用 Pi 回退 -summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次 -title: Codex Harness + - 你想为仅使用 Codex 的部署禁用 PI 回退 +summary: 通过内置的 Codex app-server 测试框架运行 OpenClaw 嵌入式智能体回合 +title: Codex 测试框架 x-i18n: - generated_at: "2026-04-23T00:29:12Z" + generated_at: "2026-04-23T02:13:11Z" model: gpt-5.4 provider: openai - source_hash: 5f96680bcaff3d6d50e9673a0131210cfce8a7f976c66573a864d67008de27c1 + source_hash: dc2acc3dc906d12e12a837a25a52ec0e72d44325786106771045d456e6327040 source_path: plugins/codex-harness.md workflow: 15 --- -# Codex Harness +# Codex 测试框架 -内置的 `codex` 插件让 OpenClaw 能够通过 Codex app-server，而不是内置的 Pi harness，来运行嵌入式智能体轮次。 +内置的 `codex` 插件让 OpenClaw 通过 Codex app-server，而不是内置的 PI 测试框架，来运行嵌入式智能体回合。 -当你希望由 Codex 接管底层智能体会话时，可以使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。 +当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。 OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 -原生 Codex 轮次同样遵循共享的 `before_prompt_build`、`before_compaction` 和 `after_compaction` 插件钩子，因此提示词 shim 和具备压缩感知能力的自动化可以与 Pi harness 保持一致。 -原生 Codex 轮次同样遵循共享的 `before_prompt_build`、`before_compaction`、`after_compaction`、`llm_input`、`llm_output` 和 `agent_end` 插件钩子，因此提示词 shim、具备压缩感知能力的自动化以及生命周期观察器都可以与 Pi harness 保持一致。 +原生 Codex 回合同样遵循共享的 `before_prompt_build`、`before_compaction` 和 `after_compaction` 插件钩子，因此提示词垫片和具备压缩感知能力的自动化可以与 PI 测试框架保持一致。 +原生 Codex 回合同样遵循共享的 `before_prompt_build`、`before_compaction`、`after_compaction`、`llm_input`、`llm_output` 和 `agent_end` 插件钩子，因此提示词垫片、具备压缩感知能力的自动化，以及生命周期观察器都可以与 PI 测试框架保持一致。 -该 harness 默认关闭。只有在启用 `codex` 插件且解析后的模型为 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选用它。 -如果你从未配置 `codex/*`，现有的 Pi、OpenAI、Anthropic、Gemini、本地和自定义提供商运行方式都会保持当前行为。 +该测试框架默认关闭。只有在启用 `codex` 插件且解析后的模型为 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选用它。 +如果你从未配置 `codex/*`，现有的 PI、OpenAI、Anthropic、Gemini、本地和自定义提供商运行将保持当前行为。 ## 选择正确的模型前缀 -OpenClaw 为 OpenAI 和 Codex 形态的访问提供了不同路径： +OpenClaw 为 OpenAI 访问和 Codex 形态访问提供了不同的路由： | 模型引用 | 运行时路径 | 适用场景 | | ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw/Pi 管线的 OpenAI 提供商路径 | 你希望使用 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | -| `openai-codex/gpt-5.4` | 通过 Pi 的 OpenAI Codex OAuth 提供商路径 | 你希望使用 ChatGPT/Codex OAuth，而不使用 Codex app-server harness。 | -| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex harness | 你希望在嵌入式智能体轮次中使用原生 Codex app-server 执行。 | +| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线的 OpenAI 提供商 | 你希望使用 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | +| `openai-codex/gpt-5.4` | 通过 PI 的 OpenAI Codex OAuth 提供商 | 你希望使用 ChatGPT/Codex OAuth，而不使用 Codex app-server 测试框架。 | +| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex 测试框架 | 你希望为嵌入式智能体回合使用原生 Codex app-server 执行。 | -Codex harness 只会接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保留其正常路径。 +Codex 测试框架只接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用将继续使用其正常路径。 ## 要求 -- OpenClaw，且内置的 `codex` 插件可用。 +- OpenClaw，并且可用内置的 `codex` 插件。 - Codex app-server `0.118.0` 或更高版本。 - app-server 进程可用的 Codex 凭证。 -该插件会阻止旧版本或未带版本号的 app-server 握手。这样可以确保 OpenClaw 运行在它已针对其进行测试的协议表面之上。 +该插件会阻止较旧或未带版本信息的 app-server 握手。 +这样可以确保 OpenClaw 运行在其已针对的协议表面上。 -对于实时和 Docker 冒烟测试，凭证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的凭证材料。 +对于 live 和 Docker 冒烟测试，凭证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 +`~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的凭证材料。 ## 最小配置 -使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` harness： +使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` 测试框架： ```json5 { @@ -74,7 +76,7 @@ Codex harness 只会接管 `codex/*` 模型引用。现有的 `openai/*`、`open } ``` -如果你的配置使用 `plugins.allow`，也要将 `codex` 包含在其中： +如果你的配置使用 `plugins.allow`，也请把 `codex` 包含进去： ```json5 { @@ -89,11 +91,11 @@ Codex harness 只会接管 `codex/*` 模型引用。现有的 `openai/*`、`open } ``` -将 `agents.defaults.model` 或某个智能体模型设置为 `codex/`，也会自动启用内置的 `codex` 插件。显式写出插件条目在共享配置中仍然很有用，因为它能清楚表明部署意图。 +将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 也会自动启用内置的 `codex` 插件。显式的插件条目在共享配置中仍然有用，因为它能明确表明部署意图。 -## 添加 Codex 而不替换其他模型 +## 在不替换其他模型的情况下添加 Codex -当你希望 `codex/*` 模型使用 Codex，而其他所有模型仍使用 Pi 时，请保留 `runtime: "auto"`： +如果你希望 `codex/*` 模型使用 Codex，而其他所有模型继续使用 PI，请保持 `runtime: "auto"`： ```json5 { @@ -127,14 +129,14 @@ Codex harness 只会接管 `codex/*` 模型引用。现有的 `openai/*`、`open 采用这种形式时： -- `/model codex` 或 `/model codex/gpt-5.4` 使用 Codex app-server harness。 +- `/model codex` 或 `/model codex/gpt-5.4` 使用 Codex app-server 测试框架。 - `/model gpt` 或 `/model openai/gpt-5.4` 使用 OpenAI 提供商路径。 - `/model opus` 使用 Anthropic 提供商路径。 -- 如果选择了非 Codex 模型，Pi 仍然是兼容性 harness。 +- 如果选择的是非 Codex 模型，PI 仍然是兼容性测试框架。 ## 仅使用 Codex 的部署 -当你需要证明每一次嵌入式智能体轮次都使用 Codex harness 时，请禁用 Pi 回退： +当你需要证明每个嵌入式智能体回合都使用 Codex 测试框架时，请禁用 PI 回退： ```json5 { @@ -158,11 +160,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 都会提前失败。 +禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 会尽早失败。 ## 按智能体使用 Codex -你可以让某一个智能体仅使用 Codex，而默认智能体仍保留正常的自动选择： +你可以让某一个智能体仅使用 Codex，同时默认智能体继续保留普通的自动选择： ```json5 { @@ -193,11 +195,11 @@ openclaw gateway run } ``` -使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定。 +使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的 OpenClaw 会话，而 Codex 测试框架会根据需要创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定。 ## 模型发现 -默认情况下，`codex` 插件会向 app-server 查询可用模型。如果发现失败或超时，它会使用内置的回退目录： +默认情况下，`codex` 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的回退目录： - `codex/gpt-5.4` - `codex/gpt-5.4-mini` @@ -223,7 +225,7 @@ openclaw gateway run } ``` -如果你希望启动时避免探测 Codex，而是固定使用回退目录，可以禁用发现： +当你希望启动时避免探测 Codex，并固定使用回退目录时，请禁用发现： ```json5 { @@ -242,19 +244,19 @@ openclaw gateway run } ``` -## app-server 连接与策略 +## App-server 连接和策略 -默认情况下，插件会通过以下命令在本地启动 Codex： +默认情况下，该插件会通过以下方式在本地启动 Codex： ```bash codex app-server --listen stdio:// ``` -默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话： -`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 -`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人可响应的原生审批提示上。 +默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试框架会话： +`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 +`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生审批提示上。 -如果你想启用由 Codex Guardian 审核的审批，请设置 `appServer.mode: +若要选择启用由 Codex Guardian 审核的审批，请设置 `appServer.mode: "guardian"`： ```json5 @@ -297,13 +299,13 @@ Guardian 模式会展开为： } ``` -Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区之外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审核子智能体，而不是向人工发出提示。审核器会收集上下文并应用 Codex 的风险框架，然后批准或拒绝该具体请求。当你希望比 YOLO 模式提供更多护栏，同时仍需要无人值守的智能体和心跳继续推进时，Guardian 非常有用。 +Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区之外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审核子智能体，而不是向人工发出提示。审核器会收集上下文并应用 Codex 的风险框架，然后批准或拒绝该具体请求。若你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体和心跳持续推进，Guardian 会很有用。 -当 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` 时，Docker 实时 harness 包含一个 Guardian 探针。它会以 Guardian 模式启动 Codex harness，验证一个无害的提权 shell 命令会被批准，并验证向不受信任的外部目标上传伪造密钥会被拒绝，从而让智能体回过头来请求显式批准。 +当 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` 时，Docker live 测试框架会包含一个 Guardian 探针。它会以 Guardian 模式启动 Codex 测试框架，验证一个良性的提权 shell 命令会被批准，并验证向不受信任的外部目标上传伪造密钥会被拒绝，从而让智能体回过头来请求显式批准。 -各个单独的策略字段仍然会优先于 `mode`，因此高级部署可以将该预设与显式选择混合使用。 +各个单独的策略字段仍然优先于 `mode`，因此高级部署可以将该预设与显式选择混合使用。 -对于已在运行的 app-server，请使用 WebSocket 传输： +对于已经在运行的 app-server，请使用 WebSocket 传输： ```json5 { @@ -329,20 +331,20 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 | 字段 | 默认值 | 含义 | | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | -| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | -| `url` | 未设置 | WebSocket app-server URL。 | -| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket headers。 | -| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | 用于 YOLO 或 Guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次中的原生 Codex 审批策略。 | -| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复中的原生 Codex 沙箱模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 | -| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | +| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | +| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | +| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | +| `url` | 未设置 | WebSocket app-server URL。 | +| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket 标头。 | +| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | +| `mode` | `"yolo"` | 用于 YOLO 或 Guardian 审核执行的预设。 | +| `approvalPolicy` | `"never"` | 发送给线程启动 / 恢复 / 回合的原生 Codex 审批策略。 | +| `sandbox` | `"danger-full-access"` | 发送给线程启动 / 恢复的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 | +| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | -当匹配的配置字段未设置时，较旧的环境变量仍可作为本地测试的回退： +当匹配的配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -352,10 +354,10 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用 `plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性的本地测试中使用 -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复的部署，优先使用配置， -因为这样可以将插件行为与 Codex harness 设置的其余部分保存在同一个经过审查的文件中。 +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置， +因为它会将插件行为与 Codex 测试框架其余设置一起保存在同一个经过审查的文件中。 -## 常见配方 +## 常用方案 使用默认 stdio 传输的本地 Codex： @@ -371,7 +373,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -仅使用 Codex 的 harness 验证，并禁用 Pi 回退： +仅使用 Codex 的测试框架验证，并禁用 PI 回退： ```json5 { @@ -410,7 +412,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -带显式 headers 的远程 app-server： +带显式标头的远程 app-server： ```json5 { @@ -433,79 +435,83 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时， -下一轮会再次将当前选定的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送给 +模型切换仍由 OpenClaw 控制。当某个 OpenClaw 会话附加到现有的 Codex 线程时， +下一回合会再次将当前选中的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送给 app-server。从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 会保留线程绑定，但会要求 -Codex 使用新选定的模型继续运行。 +Codex 使用新选择的模型继续。 ## Codex 命令 -内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用命令，可在任何支持 -OpenClaw 文本命令的渠道上使用。 +内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用的，并且可在任何支持 +OpenClaw 文本命令的渠道上工作。 常见形式： -- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 skills。 -- `/codex models` 列出实时 Codex app-server 模型。 +- `/codex status` 显示实时的 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。 +- `/codex models` 列出实时的 Codex app-server 模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 -- `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 +- `/codex resume ` 将当前 OpenClaw 会话附加到现有的 Codex 线程。 - `/codex compact` 请求 Codex app-server 压缩已附加的线程。 -- `/codex review` 为已附加线程启动 Codex 原生审查。 +- `/codex review` 为已附加的线程启动 Codex 原生审查。 - `/codex account` 显示账户和速率限制状态。 - `/codex mcp` 列出 Codex app-server MCP 服务器状态。 - `/codex skills` 列出 Codex app-server Skills。 -`/codex resume` 会写入与 harness 正常轮次所使用的同一个 sidecar 绑定文件。在下一条消息中， -OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*` 模型传入 app-server， -并保持启用扩展历史记录。 +`/codex resume` 会写入与测试框架正常回合使用的同一个 sidecar 绑定文件。 +在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw `codex/*` +模型传入 app-server，并保持启用扩展历史记录。 -该命令界面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 -app-server 未暴露某个 JSON-RPC 方法，则各个控制方法会显示为 +该命令表面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 +app-server 未暴露某个 JSON-RPC 方法，各个单独的控制方法会报告为 `unsupported by this Codex app-server`。 ## 工具、媒体和压缩 -Codex harness 只会更改底层的嵌入式智能体执行器。 +Codex 测试框架只会改变底层的嵌入式智能体执行器。 -OpenClaw 仍然构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、 -TTS、审批以及消息工具输出，都会继续通过正常的 OpenClaw 传递路径。 +OpenClaw 仍然会构建工具列表，并从测试框架接收动态工具结果。文本、图像、视频、 +音乐、TTS、审批以及消息工具输出，都会继续通过 OpenClaw 的常规传递路径处理。 -当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。 -OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及未来的模型或 -harness 切换。该镜像包括用户提示、最终助手文本，以及 app-server 发出时的轻量级 -Codex 推理或计划记录。当前，OpenClaw 只记录原生压缩开始和完成信号。它尚未公开 -人类可读的压缩摘要，也尚未提供 Codex 在压缩后保留了哪些条目的可审计列表。 +当 Codex 将 `_meta.codex_approval_kind` 标记为 +`"mcp_tool_call"` 时，Codex MCP 工具审批征求会通过 OpenClaw 的插件审批流程路由； +其他征求和自由形式输入请求仍然会默认拒绝。 -媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用匹配的 -提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、 -`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 +当所选模型使用 Codex 测试框架时，原生线程压缩会委托给 Codex app-server。 +OpenClaw 会保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的 +模型或测试框架切换。该镜像包括用户提示、最终助手文本，以及当 app-server 发出时的轻量级 +Codex 推理或计划记录。目前，OpenClaw 仅记录原生压缩开始和完成信号。它尚未公开 +人类可读的压缩摘要，也尚未公开 Codex 在压缩后保留了哪些条目的可审计列表。 + +媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用相应的提供商 / 模型设置， +例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 +`messages.tts`。 ## 故障排除 **`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`， -设置 `codex/*` 模型引用，或检查 `plugins.allow` 是否排除了 `codex`。 +设置一个 `codex/*` 模型引用，或者检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用的是 Pi 而不是 Codex：** 如果没有 Codex harness 接管此次运行， -OpenClaw 可能会使用 Pi 作为兼容性后端。测试时请设置 -`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置 -`embeddedHarness.fallback: "none"` 以在没有匹配的插件 harness 时直接失败。一旦选择了 -Codex app-server，其失败会直接暴露出来，而不需要额外的回退配置。 +**OpenClaw 使用的是 PI 而不是 Codex：** 如果没有任何 Codex 测试框架接管此次运行， +OpenClaw 可能会使用 PI 作为兼容性后端。测试时请设置 +`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或者设置 +`embeddedHarness.fallback: "none"`，在没有匹配的插件测试框架时直接失败。一旦选中 +Codex app-server，其故障会直接暴露，而无需额外的回退配置。 -**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告的版本为 -`0.118.0` 或更高。 +**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本为 `0.118.0` +或更高。 -**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` +**模型发现很慢：** 调低 `plugins.entries.codex.config.discovery.timeoutMs` 或禁用发现。 **WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`， -以及远程 app-server 是否使用相同版本的 Codex app-server 协议。 +并确认远程 app-server 使用相同版本的 Codex app-server 协议。 -**非 Codex 模型使用了 Pi：** 这是预期行为。Codex harness 只会接管 +**非 Codex 模型使用了 PI：** 这是预期行为。Codex 测试框架只接管 `codex/*` 模型引用。 ## 相关内容 -- [智能体 Harness 插件](/zh-CN/plugins/sdk-agent-harness) +- [智能体测试框架插件](/zh-CN/plugins/sdk-agent-harness) - [模型提供商](/zh-CN/concepts/model-providers) - [配置参考](/zh-CN/gateway/configuration-reference) - [测试](/zh-CN/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/zh-CN/providers/deepgram.md b/docs/zh-CN/providers/deepgram.md index d7f85f2b7..6b59c6149 100644 --- a/docs/zh-CN/providers/deepgram.md +++ b/docs/zh-CN/providers/deepgram.md @@ -1,23 +1,24 @@ --- read_when: - - 你想要将 Deepgram 语音转文本用于音频附件 + - 你想要为音频附件使用 Deepgram 语音转文本功能 + - 你想要为 Voice Call 使用 Deepgram 流式转录功能 - 你需要一个快速的 Deepgram 配置示例 -summary: 用于入站语音便笺的 Deepgram 转录 +summary: 用于接收入站语音便笺的 Deepgram 转录 title: Deepgram x-i18n: - generated_at: "2026-04-12T10:26:13Z" + generated_at: "2026-04-23T02:13:13Z" model: gpt-5.4 provider: openai - source_hash: 091523d6669e3d258f07c035ec756bd587299b6c7025520659232b1b2c1e21a5 + source_hash: ddc55436ebae295db9bd979765fbccab3ba7f25a6f5354a4e7964d151faffa22 source_path: providers/deepgram.md workflow: 15 --- # Deepgram（音频转录） -Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tools.media.audio` 进行**入站音频/语音便笺转录**。 +Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tools.media.audio` 进行入站音频/语音便笺转录，以及通过 `plugins.entries.voice-call.config.streaming` 为 Voice Call 提供流式 STT。 -启用后，OpenClaw 会将音频文件上传到 Deepgram，并将转录文本注入回复流水线中（`{{Transcript}}` + `[Audio]` 区块）。这**不是流式传输**；它使用预录音转录端点。 +对于批量转录，OpenClaw 会将完整的音频文件上传到 Deepgram，并将转录文本注入回复流水线（`{{Transcript}}` + `[Audio]` 块）。对于 Voice Call 流式转录，OpenClaw 会通过 Deepgram 的 WebSocket `listen` 端点转发实时 G.711 u-law 帧，并在 Deepgram 返回结果时输出部分或最终转录文本。 | 详情 | 值 | | ------------- | ---------------------------------------------------------- | @@ -52,13 +53,13 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool ``` - 通过任意已连接的渠道发送一条音频消息。OpenClaw 会通过 Deepgram 对其进行转录，并将转录文本注入回复流水线中。 + 通过任何已连接的渠道发送一条音频消息。OpenClaw 会通过 Deepgram 对其进行转录，并将转录文本注入回复流水线。 ## 配置选项 -| 选项 | 路径 | 说明 | +| 选项 | 路径 | 描述 | | ----------------- | ------------------------------------------------------------ | ------------------------------------- | | `model` | `tools.media.audio.models[].model` | Deepgram 模型 ID（默认：`nova-3`） | | `language` | `tools.media.audio.models[].language` | 语言提示（可选） | @@ -104,24 +105,63 @@ Deepgram 是一个语音转文本 API。在 OpenClaw 中，它用于通过 `tool +## Voice Call 流式 STT + +内置的 `deepgram` 插件还为 Voice Call 插件注册了一个实时转录提供商。 + +| 设置 | 配置路径 | 默认值 | +| --------------- | ----------------------------------------------------------------------- | -------------------------------- | +| API 密钥 | `plugins.entries.voice-call.config.streaming.providers.deepgram.apiKey` | 回退到 `DEEPGRAM_API_KEY` | +| 模型 | `...deepgram.model` | `nova-3` | +| 语言 | `...deepgram.language` | （未设置） | +| 编码 | `...deepgram.encoding` | `mulaw` | +| 采样率 | `...deepgram.sampleRate` | `8000` | +| 端点检测 | `...deepgram.endpointingMs` | `800` | +| 中间结果 | `...deepgram.interimResults` | `true` | + +```json5 +{ + plugins: { + entries: { + "voice-call": { + config: { + streaming: { + enabled: true, + provider: "deepgram", + providers: { + deepgram: { + apiKey: "${DEEPGRAM_API_KEY}", + model: "nova-3", + endpointingMs: 800, + language: "en-US", + }, + }, + }, + }, + }, + }, + }, +} +``` + + +Voice Call 接收的是 8 kHz G.711 u-law 电话音频。Deepgram 流式提供商默认使用 `encoding: "mulaw"` 和 `sampleRate: 8000`，因此可以直接转发 Twilio 媒体帧。 + + ## 说明 - - 身份验证遵循标准的提供商认证顺序。`DEEPGRAM_API_KEY` 是最简单的方式。 + + 认证遵循标准的提供商认证顺序。`DEEPGRAM_API_KEY` 是最简单的方式。 使用代理时，可通过 `tools.media.audio.baseUrl` 和 `tools.media.audio.headers` 覆盖端点或请求头。 - 输出遵循与其他提供商相同的音频规则（大小上限、超时、转录文本注入）。 + 输出遵循与其他提供商相同的音频规则（大小限制、超时、转录文本注入）。 - -Deepgram 转录**仅支持预录音**（不是实时分块流式传输）。OpenClaw 会上传完整的音频文件，并在将其注入对话之前等待完整的转录结果。 - - ## 相关内容 @@ -129,7 +169,7 @@ Deepgram 转录**仅支持预录音**（不是实时分块流式传输）。Open 音频、图像和视频处理流水线概览。 - 完整的配置参考，包括媒体工具设置。 + 包含媒体工具设置在内的完整配置参考。 常见问题和调试步骤。 diff --git a/docs/zh-CN/providers/elevenlabs.md b/docs/zh-CN/providers/elevenlabs.md new file mode 100644 index 000000000..02abc79ba --- /dev/null +++ b/docs/zh-CN/providers/elevenlabs.md @@ -0,0 +1,112 @@ +--- +read_when: + - 你想在 OpenClaw 中使用 ElevenLabs 文本转语音 + - 你想在音频附件中使用 ElevenLabs Scribe 语音转文本 + - 你想在 Voice Call 中使用 ElevenLabs 实时转录 +summary: 使用 ElevenLabs 语音、Scribe STT 和 OpenClaw 实现实时转录 +title: ElevenLabs +x-i18n: + generated_at: "2026-04-23T02:13:13Z" + model: gpt-5.4 + provider: openai + source_hash: 62768d0b8a951548be2a5b293a766432f6345087ed145afc942134513dd9618c + source_path: providers/elevenlabs.md + workflow: 15 +--- + +# ElevenLabs + +OpenClaw 使用 ElevenLabs 提供文本转语音、基于 Scribe v2 的批量语音转文本，以及基于 Scribe v2 Realtime 的 Voice Call 流式 STT。 + +| 能力 | OpenClaw 界面 | 默认值 | +| ------------------------ | --------------------------------------------- | ------------------------ | +| 文本转语音 | `messages.tts` / `talk` | `eleven_multilingual_v2` | +| 批量语音转文本 | `tools.media.audio` | `scribe_v2` | +| 流式语音转文本 | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` | + +## 身份验证 + +在环境中设置 `ELEVENLABS_API_KEY`。为兼容现有的 ElevenLabs 工具链，也接受 `XI_API_KEY`。 + +```bash +export ELEVENLABS_API_KEY="..." +``` + +## 文本转语音 + +```json5 +{ + messages: { + tts: { + providers: { + elevenlabs: { + apiKey: "${ELEVENLABS_API_KEY}", + voiceId: "pMsXgVXv3BLzUgSXRplE", + modelId: "eleven_multilingual_v2", + }, + }, + }, + }, +} +``` + +## 语音转文本 + +对入站音频附件和较短的录制语音片段使用 Scribe v2： + +```json5 +{ + tools: { + media: { + audio: { + enabled: true, + models: [{ provider: "elevenlabs", model: "scribe_v2" }], + }, + }, + }, +} +``` + +OpenClaw 会将多部分音频发送到 ElevenLabs 的 `/v1/speech-to-text`，并使用 `model_id: "scribe_v2"`。如果存在语言提示，则会映射到 `language_code`。 + +## Voice Call 流式 STT + +内置的 `elevenlabs` 插件会为 Voice Call 流式转录注册 Scribe v2 Realtime。 + +| 设置 | 配置路径 | 默认值 | +| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | +| API 密钥 | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | 回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` | +| 模型 | `...elevenlabs.modelId` | `scribe_v2_realtime` | +| 音频格式 | `...elevenlabs.audioFormat` | `ulaw_8000` | +| 采样率 | `...elevenlabs.sampleRate` | `8000` | +| 提交策略 | `...elevenlabs.commitStrategy` | `vad` | +| 语言 | `...elevenlabs.languageCode` | （未设置） | + +```json5 +{ + plugins: { + entries: { + "voice-call": { + config: { + streaming: { + enabled: true, + provider: "elevenlabs", + providers: { + elevenlabs: { + apiKey: "${ELEVENLABS_API_KEY}", + audioFormat: "ulaw_8000", + commitStrategy: "vad", + languageCode: "en", + }, + }, + }, + }, + }, + }, + }, +} +``` + + +Voice Call 接收来自 Twilio 的 8 kHz G.711 u-law 媒体。ElevenLabs 实时提供商默认使用 `ulaw_8000`，因此可以在不转码的情况下直接转发电话音频帧。 + diff --git a/docs/zh-CN/providers/index.md b/docs/zh-CN/providers/index.md index b2c045a3a..33ae6b63e 100644 --- a/docs/zh-CN/providers/index.md +++ b/docs/zh-CN/providers/index.md @@ -5,23 +5,23 @@ read_when: summary: OpenClaw 支持的模型提供商（LLM） title: 提供商目录 x-i18n: - generated_at: "2026-04-23T00:08:07Z" + generated_at: "2026-04-23T02:13:10Z" model: gpt-5.4 provider: openai - source_hash: d61873f18fcaef7353620f687afc2043087c62edca62f24568c67339a9c65086 + source_hash: bcef929e6757f18aad19b810426c49bdb273a9c65781bb3a21cc50d6d17014b5 source_path: providers/index.md workflow: 15 --- # 模型提供商 -OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证，然后将默认模型设置为 `provider/model`。 +OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。 -在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参阅 [Channels](/zh-CN/channels)。 +在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参见 [渠道](/zh-CN/channels)。 ## 快速开始 -1. 使用提供商完成认证（通常通过 `openclaw onboard`）。 +1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。 2. 设置默认模型： ```json5 @@ -32,7 +32,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证 ## 提供商文档 -- [Alibaba Model Studio](/zh-CN/providers/alibaba) +- [阿里巴巴 Model Studio](/zh-CN/providers/alibaba) - [Amazon Bedrock](/zh-CN/providers/bedrock) - [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic) - [Arcee AI（Trinity 模型）](/zh-CN/providers/arcee) @@ -69,7 +69,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证 - [StepFun](/zh-CN/providers/stepfun) - [Synthetic](/zh-CN/providers/synthetic) - [Together AI](/zh-CN/providers/together) -- [Venice（Venice AI，注重隐私）](/zh-CN/providers/venice) +- [Venice（Venice AI，以隐私为中心）](/zh-CN/providers/venice) - [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) - [vLLM（本地模型）](/zh-CN/providers/vllm) - [Volcengine（Doubao）](/zh-CN/providers/volcengine) @@ -81,17 +81,21 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成认证 ## 共享概览页面 - [其他内置变体](/zh-CN/providers/models#additional-bundled-provider-variants) - Anthropic Vertex、Copilot Proxy 和 Gemini CLI OAuth -- [图像生成](/zh-CN/tools/image-generation) - 共享 `image_generate` 工具、提供商选择和故障切换 -- [音乐生成](/zh-CN/tools/music-generation) - 共享 `music_generate` 工具、提供商选择和故障切换 -- [视频生成](/zh-CN/tools/video-generation) - 共享 `video_generate` 工具、提供商选择和故障切换 +- [图像生成](/zh-CN/tools/image-generation) - 共享的 `image_generate` 工具、提供商选择和故障切换 +- [音乐生成](/zh-CN/tools/music-generation) - 共享的 `music_generate` 工具、提供商选择和故障切换 +- [视频生成](/zh-CN/tools/video-generation) - 共享的 `video_generate` 工具、提供商选择和故障切换 ## 转录提供商 - [Deepgram（音频转录）](/zh-CN/providers/deepgram) +- [ElevenLabs](/zh-CN/providers/elevenlabs#speech-to-text) +- [Mistral](/zh-CN/providers/mistral#audio-transcription-voxtral) +- [OpenAI](/zh-CN/providers/openai#speech-to-text) - [xAI](/zh-CN/providers/xai#speech-to-text) ## 社区工具 -- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 面向 Claude 订阅凭证的社区代理（使用前请先核实 Anthropic 的政策/条款） +- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 的政策/条款） -如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 +如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置， +请参见 [模型提供商](/zh-CN/concepts/model-providers)。 diff --git a/docs/zh-CN/providers/mistral.md b/docs/zh-CN/providers/mistral.md index 4b5bc8b4b..fbb99a0a2 100644 --- a/docs/zh-CN/providers/mistral.md +++ b/docs/zh-CN/providers/mistral.md @@ -1,22 +1,23 @@ --- read_when: - 你想在 OpenClaw 中使用 Mistral 模型 + - 你想为 Voice Call 使用 Voxtral 实时转录功能 - 你需要 Mistral API 密钥新手引导和模型参考信息 -summary: 使用 Mistral 模型和 Voxtral 转录，并结合 OpenClaw 使用 +summary: 使用 Mistral 模型和 Voxtral 转录功能与 OpenClaw 配合使用 title: Mistral x-i18n: - generated_at: "2026-04-21T06:04:37Z" + generated_at: "2026-04-23T02:13:15Z" model: gpt-5.4 provider: openai - source_hash: e87d04e3d45c04280c90821b1addd87dd612191249836747fba27cde48b9890f + source_hash: 8aec3c47fee12588b28ea2b652b89f0ff136399d25ca47174d7cb6e7b5d5d97f source_path: providers/mistral.md workflow: 15 --- # Mistral -OpenClaw 支持 Mistral，用于文本/图像模型路由（`mistral/...`）以及通过媒体理解中的 Voxtral 进行音频转录。 -Mistral 还可用于记忆嵌入（`memorySearch.provider = "mistral"`）。 +OpenClaw 支持 Mistral，用于文本/图像模型路由（`mistral/...`）以及在媒体理解中通过 Voxtral 进行音频转录。 +Mistral 也可用于记忆嵌入（`memorySearch.provider = "mistral"`）。 - 提供商：`mistral` - 凭证：`MISTRAL_API_KEY` @@ -48,7 +49,7 @@ Mistral 还可用于记忆嵌入（`memorySearch.provider = "mistral"`）。 } ``` - + ```bash openclaw models list --provider mistral ``` @@ -57,21 +58,21 @@ Mistral 还可用于记忆嵌入（`memorySearch.provider = "mistral"`）。 ## 内置 LLM 目录 -OpenClaw 当前附带以下内置 Mistral 目录： +OpenClaw 当前内置了以下 Mistral 目录： | 模型引用 | 输入 | 上下文 | 最大输出 | 说明 | | -------------------------------- | ----------- | ------- | ---------- | ---------------------------------------------------------------- | -| `mistral/mistral-large-latest` | 文本、图像 | 262,144 | 16,384 | 默认模型 | -| `mistral/mistral-medium-2508` | 文本、图像 | 262,144 | 8,192 | Mistral Medium 3.1 | -| `mistral/mistral-small-latest` | 文本、图像 | 128,000 | 16,384 | Mistral Small 4；可通过 API `reasoning_effort` 调整推理强度 | -| `mistral/pixtral-large-latest` | 文本、图像 | 128,000 | 32,768 | Pixtral | -| `mistral/codestral-latest` | 文本 | 256,000 | 4,096 | 编码 | -| `mistral/devstral-medium-latest` | 文本 | 262,144 | 32,768 | Devstral 2 | -| `mistral/magistral-small` | 文本 | 128,000 | 40,000 | 启用推理 | +| `mistral/mistral-large-latest` | text, image | 262,144 | 16,384 | 默认模型 | +| `mistral/mistral-medium-2508` | text, image | 262,144 | 8,192 | Mistral Medium 3.1 | +| `mistral/mistral-small-latest` | text, image | 128,000 | 16,384 | Mistral Small 4；可通过 API `reasoning_effort` 调整推理强度 | +| `mistral/pixtral-large-latest` | text, image | 128,000 | 32,768 | Pixtral | +| `mistral/codestral-latest` | text | 256,000 | 4,096 | 编码 | +| `mistral/devstral-medium-latest` | text | 262,144 | 32,768 | Devstral 2 | +| `mistral/magistral-small` | text | 128,000 | 40,000 | 启用推理 | ## 音频转录（Voxtral） -通过媒体理解流水线使用 Voxtral 进行音频转录。 +通过媒体理解流水线使用 Voxtral 进行批量音频转录。 ```json5 { @@ -90,11 +91,50 @@ OpenClaw 当前附带以下内置 Mistral 目录： 媒体转录路径使用 `/v1/audio/transcriptions`。Mistral 的默认音频模型是 `voxtral-mini-latest`。 +## Voice Call 流式 STT + +内置的 `mistral` 插件会将 Voxtral Realtime 注册为 Voice Call 流式 STT 提供商。 + +| 设置 | 配置路径 | 默认值 | +| ------------ | ---------------------------------------------------------------------- | --------------------------------------- | +| API 密钥 | `plugins.entries.voice-call.config.streaming.providers.mistral.apiKey` | 回退到 `MISTRAL_API_KEY` | +| 模型 | `...mistral.model` | `voxtral-mini-transcribe-realtime-2602` | +| 编码 | `...mistral.encoding` | `pcm_mulaw` | +| 采样率 | `...mistral.sampleRate` | `8000` | +| 目标延迟 | `...mistral.targetStreamingDelayMs` | `800` | + +```json5 +{ + plugins: { + entries: { + "voice-call": { + config: { + streaming: { + enabled: true, + provider: "mistral", + providers: { + mistral: { + apiKey: "${MISTRAL_API_KEY}", + targetStreamingDelayMs: 800, + }, + }, + }, + }, + }, + }, + }, +} +``` + + +OpenClaw 默认将 Mistral 实时 STT 设置为 `pcm_mulaw` 和 8 kHz，这样 Voice Call 就能直接转发 Twilio 媒体帧。仅当你的上游流已经是原始 PCM 时，才使用 `encoding: "pcm_s16le"` 和匹配的 `sampleRate`。 + + ## 高级配置 - `mistral/mistral-small-latest` 映射到 Mistral Small 4，并通过 Chat Completions API 上的 `reasoning_effort` 支持[可调推理](https://docs.mistral.ai/capabilities/reasoning/adjustable)（`none` 会尽量减少输出中的额外思考内容；`high` 会在最终答案之前展示完整的思考轨迹）。 + `mistral/mistral-small-latest` 映射到 Mistral Small 4，并通过 `reasoning_effort` 支持在 Chat Completions API 上进行[可调推理](https://docs.mistral.ai/capabilities/reasoning/adjustable)（`none` 会尽量减少输出中的额外思考；`high` 会在最终答案前展示完整的思考轨迹）。 OpenClaw 会将会话 **thinking** 级别映射到 Mistral 的 API： @@ -104,7 +144,7 @@ OpenClaw 当前附带以下内置 Mistral 目录： | **low** / **medium** / **high** / **xhigh** / **adaptive** / **max** | `high` | - 其他内置 Mistral 目录模型不使用此参数。当你想要 Mistral 原生的推理优先行为时，请继续使用 `magistral-*` 模型。 + 其他内置 Mistral 目录模型不会使用这个参数。当你想要使用 Mistral 原生的推理优先行为时，请继续使用 `magistral-*` 模型。 @@ -124,7 +164,7 @@ OpenClaw 当前附带以下内置 Mistral 目录： - Mistral 凭证使用 `MISTRAL_API_KEY`。 - 提供商基础 URL 默认为 `https://api.mistral.ai/v1`。 - 新手引导默认模型为 `mistral/mistral-large-latest`。 - - Z.AI 使用 Bearer 认证和你的 API 密钥。 + - Z.AI 使用你的 API 密钥进行 Bearer 认证。 diff --git a/docs/zh-CN/tools/media-overview.md b/docs/zh-CN/tools/media-overview.md index e3febe3bd..e8d233589 100644 --- a/docs/zh-CN/tools/media-overview.md +++ b/docs/zh-CN/tools/media-overview.md @@ -1,72 +1,72 @@ --- read_when: - - 寻找媒体能力概览 - - 决定要配置哪个媒体提供商 + - 想了解媒体能力的概览吗 + - 正在决定要配置哪个媒体提供商 - 了解异步媒体生成的工作方式 summary: 用于媒体生成、理解和语音能力的统一落地页 title: 媒体概览 x-i18n: - generated_at: "2026-04-23T01:23:57Z" + generated_at: "2026-04-23T02:13:10Z" model: gpt-5.4 provider: openai - source_hash: bdc240c0ac4cc066e337f69e04b27828e9eb34648515688bc97e398299d7c18e + source_hash: 999ed1c58a6d80c4bd6deef6e2dbf55b253c0dee3eb974ed212ca2fa91ec445e source_path: tools/media-overview.md workflow: 15 --- # 媒体生成与理解 -OpenClaw 可以生成图像、视频和音乐，理解传入的媒体内容（图像、音频、视频），并通过文本转语音将回复朗读出来。所有媒体能力都由工具驱动：智能体会根据对话决定何时使用它们，并且只有在至少配置了一个后端提供商时，对应工具才会出现。 +OpenClaw 可以生成图像、视频和音乐，理解传入的媒体（图像、音频、视频），并通过文本转语音将回复朗读出来。所有媒体能力都由工具驱动：智能体会根据对话自行决定何时使用它们，而每个工具只有在至少配置了一个对应的底层提供商时才会出现。 -## 能力概览 +## 能力一览 | 能力 | 工具 | 提供商 | 作用 | | -------------------- | ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| 图像生成 | `image_generate` | ComfyUI、fal、Google、MiniMax、OpenAI、Vydra、xAI | 根据文本提示或参考内容创建或编辑图像 | +| 图像生成 | `image_generate` | ComfyUI、fal、Google、MiniMax、OpenAI、Vydra、xAI | 根据文本提示词或参考内容创建或编辑图像 | | 视频生成 | `video_generate` | Alibaba、BytePlus、ComfyUI、fal、Google、MiniMax、OpenAI、Qwen、Runway、Together、Vydra、xAI | 根据文本、图像或现有视频创建视频 | -| 音乐生成 | `music_generate` | ComfyUI、Google、MiniMax | 根据文本提示创建音乐或音频轨道 | +| 音乐生成 | `music_generate` | ComfyUI、Google、MiniMax | 根据文本提示词创建音乐或音频轨道 | | 文本转语音（TTS） | `tts` | ElevenLabs、Microsoft、MiniMax、OpenAI、xAI | 将发出的回复转换为语音音频 | -| 媒体理解 | （自动） | 任何支持视觉/音频的模型提供商，以及 CLI 回退方式 | 总结传入的图像、音频和视频 | +| 媒体理解 | （自动） | 任何支持视觉/音频的模型提供商，以及 CLI 回退方案 | 总结传入的图像、音频和视频 | ## 提供商能力矩阵 -下表展示了各提供商在整个平台中支持的媒体能力。 +此表显示平台中各提供商支持哪些媒体能力。 | 提供商 | 图像 | 视频 | 音乐 | TTS | STT / 转录 | 媒体理解 | | ---------- | ----- | ----- | ----- | --- | ------------------- | ------------------- | -| Alibaba | | 是 | | | | | -| BytePlus | | 是 | | | | | -| ComfyUI | 是 | 是 | 是 | | | | -| Deepgram | | | | | 是 | | -| ElevenLabs | | | | 是 | | | -| fal | 是 | 是 | | | | | -| Google | 是 | 是 | 是 | | | 是 | -| Microsoft | | | | 是 | | | -| MiniMax | 是 | 是 | 是 | 是 | | | -| OpenAI | 是 | 是 | | 是 | 是 | 是 | -| Qwen | | 是 | | | | | -| Runway | | 是 | | | | | -| Together | | 是 | | | | | -| Vydra | 是 | 是 | | | | | -| xAI | 是 | 是 | | 是 | 是 | 是 | +| Alibaba | | 是 | | | | | +| BytePlus | | 是 | | | | | +| ComfyUI | 是 | 是 | 是 | | | | +| Deepgram | | | | | 是 | | +| ElevenLabs | | | | 是 | 是 | | +| fal | 是 | 是 | | | | | +| Google | 是 | 是 | 是 | | | 是 | +| Microsoft | | | | 是 | | | +| MiniMax | 是 | 是 | 是 | 是 | | | +| Mistral | | | | | 是 | | +| OpenAI | 是 | 是 | | 是 | 是 | 是 | +| Qwen | | 是 | | | | | +| Runway | | 是 | | | | | +| Together | | 是 | | | | | +| Vydra | 是 | 是 | | | | | +| xAI | 是 | 是 | | 是 | 是 | 是 | -媒体理解会使用你在提供商配置中注册的任何支持视觉或音频的模型。上表重点标出了具有专门媒体理解支持的提供商；大多数带有多模态模型的 LLM 提供商（Anthropic、Google、OpenAI 等）在被配置为当前回复模型时，也可以理解传入的媒体内容。 +媒体理解会使用你在提供商配置中注册的任何支持视觉或音频的模型。上表重点标出了具有专门媒体理解支持的提供商；大多数带有多模态模型的 LLM 提供商（Anthropic、Google、OpenAI 等）在被配置为当前活动回复模型时，也可以理解传入媒体。 ## 异步生成的工作方式 -视频和音乐生成会作为后台任务运行，因为提供商处理通常需要 30 秒到数分钟。当智能体调用 `video_generate` 或 `music_generate` 时，OpenClaw 会将请求提交给提供商，立即返回任务 ID，并在任务台账中跟踪该任务。任务运行期间，智能体会继续响应其他消息。当提供商处理完成后，OpenClaw 会唤醒智能体，以便它将完成的媒体内容回发到原始渠道。图像生成和 TTS 是同步的，会随回复内联完成。 +视频和音乐生成会作为后台任务运行，因为提供商处理通常需要 30 秒到几分钟不等。当智能体调用 `video_generate` 或 `music_generate` 时，OpenClaw 会将请求提交给提供商，立即返回任务 ID，并在任务账本中跟踪该任务。任务运行期间，智能体会继续响应其他消息。当提供商完成处理后，OpenClaw 会唤醒智能体，以便它将生成完成的媒体发布回原始渠道。图像生成和 TTS 是同步的，会在回复过程中内联完成。 -OpenAI 映射到 OpenClaw 的图像、视频、批量 TTS、批量 STT、Voice Call -流式 STT、实时语音和记忆嵌入能力。xAI 当前映射到 OpenClaw 的图像、视频、搜索、代码执行、批量 TTS、批量 STT， -以及 Voice Call 流式 STT 能力。xAI Realtime voice 是上游能力， -但在共享实时语音契约能够表示它之前，它不会在 OpenClaw 中注册。 +配置后，Deepgram、ElevenLabs、Mistral、OpenAI 和 xAI 都可以通过批处理 `tools.media.audio` 路径转录传入音频。Deepgram、ElevenLabs、Mistral、OpenAI 和 xAI 也会注册语音通话流式 STT 提供商，因此实时电话音频可以直接转发到所选供应商，而无需等待录音完成。 + +OpenAI 映射到 OpenClaw 的图像、视频、批处理 TTS、批处理 STT、语音通话流式 STT、实时语音和记忆嵌入能力。xAI 当前映射到 OpenClaw 的图像、视频、搜索、代码执行、批处理 TTS、批处理 STT 和语音通话流式 STT 能力。xAI Realtime voice 是上游能力，但在共享实时语音契约可以表示它之前，OpenClaw 不会注册它。 ## 快速链接 -- [Image Generation](/zh-CN/tools/image-generation) -- 生成和编辑图像 -- [Video Generation](/zh-CN/tools/video-generation) -- 文本转视频、图像转视频和视频转视频 -- [Music Generation](/zh-CN/tools/music-generation) -- 创建音乐和音频轨道 -- [Text-to-Speech](/zh-CN/tools/tts) -- 将回复转换为语音音频 -- [Media Understanding](/zh-CN/nodes/media-understanding) -- 理解传入的图像、音频和视频 +- [图像生成](/zh-CN/tools/image-generation) -- 生成和编辑图像 +- [视频生成](/zh-CN/tools/video-generation) -- 文本生成视频、图像生成视频，以及视频生成视频 +- [音乐生成](/zh-CN/tools/music-generation) -- 创建音乐和音频轨道 +- [文本转语音](/zh-CN/tools/tts) -- 将回复转换为语音音频 +- [媒体理解](/zh-CN/nodes/media-understanding) -- 理解传入的图像、音频和视频