diff --git a/docs/zh-CN/cli/infer.md b/docs/zh-CN/cli/infer.md index cf7865e0b..2b10fa31c 100644 --- a/docs/zh-CN/cli/infer.md +++ b/docs/zh-CN/cli/infer.md @@ -2,24 +2,24 @@ read_when: - 添加或修改 `openclaw infer` 命令 - 设计稳定的无头能力自动化 -summary: 面向由提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI +summary: 面向 provider 支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI title: 推理 CLI x-i18n: - generated_at: "2026-04-25T19:10:43Z" + generated_at: "2026-04-25T19:34:26Z" model: gpt-5.4 provider: openai - source_hash: 2e4ee27a124a5969231fb3363e582cf90323f887e9625dc7c8aa3e7640b54224 + source_hash: bd5b98b70fd959cdcdf80131cebf99cb7131b220c5757acb380ce405b85998a1 source_path: cli/infer.md workflow: 15 --- -`openclaw infer` 是提供商支持的推理工作流的规范无头入口。 +`openclaw infer` 是 provider 支持的推理工作流的规范无头入口。 -它有意暴露的是能力家族，而不是原始的 Gateway 网关 RPC 名称，也不是原始的智能体工具 id。 +它有意暴露的是能力家族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。 ## 将 infer 变成一个 Skills -复制并粘贴以下内容给一个智能体： +把这段内容复制并粘贴给一个智能体： ```text Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`. @@ -29,11 +29,11 @@ Focus on model runs, image generation, video generation, audio transcription, TT 一个好的基于 infer 的 Skills 应该： - 将常见用户意图映射到正确的 infer 子命令 -- 为其覆盖的工作流包含一些规范的 infer 示例 +- 包含它所覆盖工作流的一些规范 infer 示例 - 在示例和建议中优先使用 `openclaw infer ...` -- 避免在 Skills 正文中重新记录整个 infer 功能面 +- 避免在 Skills 正文中重新记录整个 infer 入口 -典型的以 infer 为中心的 Skills 覆盖范围： +典型的 infer 聚焦型 Skills 覆盖范围： - `openclaw infer model run` - `openclaw infer image generate` @@ -44,19 +44,19 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## 为什么使用 infer -`openclaw infer` 为 OpenClaw 内由提供商支持的推理任务提供了一个统一的 CLI。 +`openclaw infer` 为 OpenClaw 中由 provider 支持的推理任务提供了一个统一的 CLI。 优势： -- 使用 OpenClaw 中已配置的提供商和模型，而不是为每个后端单独接入一次性封装。 -- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一到一个命令树下。 +- 使用 OpenClaw 中已经配置好的 providers 和模型，而不是为每个后端单独接入一次性封装。 +- 将模型、图像、音频转写、TTS、视频、网页和嵌入工作流统一到同一棵命令树下。 - 为脚本、自动化和智能体驱动工作流使用稳定的 `--json` 输出结构。 - 当任务本质上是“运行推理”时，优先使用 OpenClaw 的第一方入口。 -- 对于大多数 infer 命令，使用常规本地路径而无需依赖 Gateway 网关。 +- 对于大多数 infer 命令，使用常规本地路径而不需要 Gateway 网关。 -对于端到端提供商检查，在底层 -提供商测试通过后，优先使用 `openclaw infer ...`。它会在发出提供商请求之前，覆盖已发布的 CLI、配置加载、 -默认智能体解析、内置插件激活、运行时依赖修复， +对于端到端的 provider 检查，在更底层的 +provider 测试通过后，优先使用 `openclaw infer ...`。它会在发出 provider 请求之前，覆盖已发布的 CLI、配置加载、 +默认智能体解析、内置插件激活、运行时依赖修复 以及共享能力运行时。 ## 命令树 @@ -117,14 +117,14 @@ Focus on model runs, image generation, video generation, audio transcription, TT | 任务 | 命令 | 说明 | | ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | | 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 | -| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时使用 `image edit` | -| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是支持图像的 `` | -| 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `` | +| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时，使用 `image edit` | +| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是图像能力的 `` | +| 转写音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `` | | 合成语音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 面向 Gateway 网关 | -| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持 `--resolution` 等提供商提示参数 | +| 生成视频 | `openclaw infer video generate --prompt "..." --json` | 支持 `--resolution` 等 provider 提示参数 | | 描述视频文件 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必须是 `` | | 搜索网页 | `openclaw infer web search --query "..." --json` | | -| 获取网页内容 | `openclaw infer web fetch --url https://example.com --json` | | +| 抓取网页 | `openclaw infer web fetch --url https://example.com --json` | | | 创建嵌入 | `openclaw infer embedding create --text "..." --json` | | ## 行为 @@ -133,15 +133,15 @@ Focus on model runs, image generation, video generation, audio transcription, TT - 当输出将被其他命令或脚本消费时，使用 `--json`。 - 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。 - 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `` 形式。 -- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/` 会运行一个受限的 Codex app-server 图像理解轮次；`openai-codex/` 使用 OpenAI Codex OAuth 提供商路径。 -- 无状态执行命令默认使用本地。 -- 由 Gateway 网关管理状态的命令默认使用网关。 -- 常规本地路径不要求 Gateway 网关 正在运行。 -- `model run` 是一次性执行。通过该命令中的智能体运行时打开的 MCP 服务器会在回复后被回收，无论是本地执行还是 `--gateway` 执行都一样，因此重复的脚本调用不会让 stdio MCP 子进程持续存活。 +- 对于 `image describe`，显式提供 `--model` 会直接运行该 provider/model。该模型必须在模型目录或 provider 配置中具备图像能力。`codex/` 会运行一个受限的 Codex app-server 图像理解轮次；`openai-codex/` 则使用 OpenAI Codex OAuth provider 路径。 +- 无状态执行命令默认走本地。 +- 由 Gateway 网关管理状态的命令默认走 gateway。 +- 常规本地路径不要求 Gateway 网关正在运行。 +- `model run` 是单次执行。对于本地和 `--gateway` 执行，该命令通过智能体运行时打开的 MCP 服务器都会在回复后退役，因此重复的脚本调用不会持续保留 stdio MCP 子进程。 ## 模型 -使用 `model` 进行由提供商支持的文本推理以及模型/提供商检查。 +对由 provider 支持的文本推理以及模型/provider 检查，使用 `model`。 ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json @@ -152,20 +152,20 @@ openclaw infer model inspect --name gpt-5.5 --json 说明： -- `model run` 会复用智能体运行时，因此提供商/模型覆盖的行为与常规智能体执行一致。 -- 因为 `model run` 面向无头自动化，所以它不会在命令结束后保留按会话划分的内置 MCP 运行时。 -- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商认证状态。 +- `model run` 会复用智能体运行时，因此 provider/模型覆盖的行为与常规智能体执行一致。 +- 因为 `model run` 面向无头自动化，所以命令结束后不会保留按会话维度的内置 MCP 运行时。 +- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的 provider 认证状态。 ## 图像 -使用 `image` 进行生成、编辑和描述。 +对生成、编辑和描述，使用 `image`。 ```bash openclaw infer image generate --prompt "friendly lobster illustration" --json openclaw infer image generate --prompt "cinematic product photo of headphones" --json -openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --openai-background transparent --prompt "simple red circle sticker on a transparent background" --json +openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json -openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --openai-background transparent --prompt "keep the logo, remove the background" --json +openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json openclaw infer image describe --file ./photo.jpg --json openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json @@ -174,15 +174,16 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j 说明： - 从现有输入文件开始时，使用 `image edit`。 -- 对于 `--model openai/gpt-image-1.5`，使用 `--output-format png --openai-background transparent` - 以获得透明背景的 OpenAI PNG 输出。 - 这些 OpenAI 专用标志在 `image generate` 和 - `image edit` 中都可用。 -- 使用 `image providers --json` 来确认哪些内置图像提供商 - 可被发现、已配置、已选中，以及每个提供商暴露了哪些 +- 当使用 + `--model openai/gpt-image-1.5` 时，配合 `--output-format png --background transparent` + 可获得透明背景的 OpenAI PNG 输出； + `--openai-background` 仍可作为 OpenAI 专用别名使用。不声明背景支持的 providers + 会将该提示报告为被忽略的覆盖项。 +- 使用 `image providers --json` 可验证哪些内置图像 providers + 可被发现、已配置、已选中，以及每个 provider 暴露了哪些 生成/编辑能力。 -- 对于图像生成变更，使用 `image generate --model --json` 作为最小范围的在线 - CLI 冒烟检查。示例： +- 将 `image generate --model --json` 用作图像生成变更的 + 最窄范围在线 CLI 冒烟检查。示例： ```bash openclaw infer image providers --json @@ -194,15 +195,15 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j ``` JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 和已写入的 - 输出路径。设置了 `--output` 时，最终扩展名可能会遵循 - 提供商返回的 MIME 类型。 + 输出路径。设置了 `--output` 时，最终扩展名可能会跟随 + provider 返回的 MIME 类型。 -- 对于 `image describe`，`--model` 必须是支持图像的 ``。 +- 对于 `image describe`，`--model` 必须是具备图像能力的 ``。 - 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 ## 音频 -使用 `audio` 进行文件转录。 +对文件转写，使用 `audio`。 ```bash openclaw infer audio transcribe --file ./memo.m4a --json @@ -212,12 +213,12 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso 说明： -- `audio transcribe` 用于文件转录，而不是实时会话管理。 +- `audio transcribe` 用于文件转写，不用于实时会话管理。 - `--model` 必须是 ``。 ## TTS -使用 `tts` 进行语音合成和 TTS 提供商状态管理。 +对语音合成和 TTS provider 状态，使用 `tts`。 ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json @@ -228,12 +229,12 @@ openclaw infer tts status --json 说明： -- `tts status` 默认使用网关，因为它反映的是由 Gateway 网关管理的 TTS 状态。 +- `tts status` 默认走 gateway，因为它反映的是由 Gateway 网关管理的 TTS 状态。 - 使用 `tts providers`、`tts voices` 和 `tts set-provider` 来检查和配置 TTS 行为。 ## 视频 -使用 `video` 进行生成和描述。 +对生成和描述，使用 `video`。 ```bash openclaw infer video generate --prompt "cinematic sunset over the ocean" --json @@ -249,7 +250,7 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js ## 网页 -使用 `web` 进行搜索和抓取工作流。 +对搜索和抓取工作流，使用 `web`。 ```bash openclaw infer web search --query "OpenClaw docs" --json @@ -260,11 +261,11 @@ openclaw infer web providers --json 说明： -- 使用 `web providers` 来检查可用、已配置和已选中的提供商。 +- 使用 `web providers` 来检查可用、已配置和已选中的 providers。 ## 嵌入 -使用 `embedding` 进行向量创建和嵌入提供商检查。 +对向量创建和嵌入 provider 检查，使用 `embedding`。 ```bash openclaw infer embedding create --text "friendly lobster" --json @@ -274,7 +275,7 @@ openclaw infer embedding providers --json ## JSON 输出 -Infer 命令会在共享封装结构下规范化 JSON 输出： +Infer 命令会在共享封装下规范化 JSON 输出： ```json { @@ -299,9 +300,9 @@ Infer 命令会在共享封装结构下规范化 JSON 输出： - `outputs` - `error` -对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化场景， -请使用该数组中的 `path`、`mimeType`、`size` 以及任何媒体专用尺寸字段， -而不是解析面向人的 stdout。 +对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化，请使用 +该数组中的 `path`、`mimeType`、`size` 以及任何媒体特定尺寸信息， +而不是去解析面向人的 stdout。 ## 常见陷阱 @@ -325,7 +326,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso - `openclaw capability ...` 是 `openclaw infer ...` 的别名。 -## 相关内容 +## 相关 -- [CLI reference](/zh-CN/cli) +- [CLI 参考](/zh-CN/cli) - [Models](/zh-CN/concepts/models) diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 5cb6aeee4..a836234bc 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,73 +2,72 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考：涵盖核心 OpenClaw 键名、默认值，以及指向各专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-25T19:10:44Z" + generated_at: "2026-04-25T19:34:27Z" model: gpt-5.4 provider: openai - source_hash: baeb721609668f8eb08598cce9fb6139d6dd8c826b08e360010ff4118283b59a + source_hash: 3f9941fc10dd1929d62354fb604534e0526de8098de2484f8e3a571fd0c65082 source_path: gateway/configuration-reference.md workflow: 15 --- -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若想查看面向任务的概览，请参见 [配置](/zh-CN/gateway/configuration)。 -本文涵盖 OpenClaw 的主要配置面，并在某个子系统拥有自己更深入的参考文档时提供跳转链接。由渠道和插件拥有的命令目录，以及更深层的内存 / QMD 调整项，分别位于它们自己的页面，而不是放在这里。 +本页涵盖主要的 OpenClaw 配置面，并在子系统有各自更深入的参考文档时提供外链。由渠道和插件拥有的命令目录，以及更深入的 memory/QMD 旋钮，位于各自独立页面，而不是本页。 -代码事实来源： +代码事实依据： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 -- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，供深入查看工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面，验证配置文档基线哈希 +- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 +- `config.schema.lookup` 会返回单个按路径限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面，校验配置文档基线哈希 -专用的深入参考： +专门的深入参考文档： -- [内存配置参考](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，用于当前内建 + 内置命令目录 -- 各自拥有的渠道 / 插件页面，用于渠道特定的命令面 +- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [斜杠命令](/zh-CN/tools/slash-commands)，用于查看当前内置 + 捆绑命令目录 +- 各自拥有的渠道/插件页面，用于查看渠道专属命令面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -每个渠道的配置键已移至专门页面——请参阅 -[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`， -包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 +每个渠道的配置键已移至专门页面 —— 请参见 +[配置 — 渠道](/zh-CN/gateway/config-channels) 了解 `channels.*`， +其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他 内置渠道（认证、访问控制、多账号、提及门控）。 ## 智能体默认值、多智能体、会话和消息 -已移至专门页面——请参阅 -[配置 — 智能体](/zh-CN/gateway/config-agents)，内容包括： +已移至专门页面 —— 请参见 +[配置 — 智能体](/zh-CN/gateway/config-agents) 了解： - `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱） -- `multiAgent.*`（多智能体路由和绑定） +- `multiAgent.*`（多智能体路由与绑定） - `session.*`（会话生命周期、压缩、清理） - `messages.*`（消息投递、TTS、Markdown 渲染） - `talk.*`（Talk 模式） - - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认的停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） + - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保留平台默认的静默等待窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`） ## 工具和自定义提供商 工具策略、实验性开关、由提供商支持的工具配置，以及自定义 -提供商 / base-URL 设置已移至专门页面——请参阅 +提供商 / base-URL 设置，已移至专门页面 —— 请参见 [配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。 ## MCP -由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下， -并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、 -`show`、`set` 和 `unset` 命令可管理此配置块，而无需在 -编辑配置时连接到目标服务器。 +由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi 及其他运行时适配器使用。`openclaw mcp list`、 +`show`、`set` 和 `unset` 命令可管理此配置块，而无需在编辑配置期间连接到 +目标服务器。 ```json5 { mcp: { - // 可选。默认值：600000 ms（10 分钟）。设为 0 以禁用空闲驱逐。 + // 可选。默认值：600000 ms（10 分钟）。设为 0 可禁用空闲驱逐。 sessionIdleTtlMs: 600000, servers: { docs: { @@ -87,14 +86,16 @@ x-i18n: } ``` -- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供命名的 stdio 或远程 MCP 服务器定义。 -- `mcp.sessionIdleTtlMs`：用于按会话范围管理的内置 MCP 运行时的空闲 TTL。 - 一次性嵌入式运行会请求在运行结束时清理；此 TTL 是为长期会话和未来调用方提供的兜底机制。 -- `mcp.*` 下的更改会通过释放已缓存的会话 MCP 运行时来热应用。 - 下一次工具发现 / 使用时会依据新配置重新创建它们，因此被移除的 - `mcp.servers` 条目会立即被清理，而不是等待空闲 TTL 到期。 +- `mcp.servers`：供运行时使用的已命名 stdio 或远程 MCP 服务器定义， + 这些运行时会暴露已配置的 MCP 工具。 +- `mcp.sessionIdleTtlMs`：用于会话作用域内置 MCP 运行时的空闲 TTL。 + 一次性嵌入式运行会在运行结束时请求清理；该 TTL 是针对 + 长生命周期会话和未来调用方的兜底机制。 +- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。 + 下一次工具发现/使用时会根据新配置重新创建它们，因此被移除的 + `mcp.servers` 条目会立即回收，而不是等待空闲 TTL 到期。 -运行时行为请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 +有关运行时行为，请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。 ## Skills @@ -122,13 +123,14 @@ x-i18n: } ``` -- `allowBundled`：仅针对内置 Skills 的可选允许列表（受管 / 工作区 Skills 不受影响）。 +- `allowBundled`：仅针对内置 skills 的可选允许列表（不影响托管/工作区 skills）。 - `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。 -- `install.preferBrew`：为 `true` 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器， + 然后才会回退到其他安装器类型。 - `install.nodeManager`：用于 `metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 skill 已内置 / 已安装，也会将其禁用。 -- `entries..apiKey`：为声明主环境变量的 skill 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `entries..enabled: false`：即使 skill 已内置/已安装，也会禁用该 skill。 +- `entries..apiKey`：为声明了主环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -157,48 +159,49 @@ x-i18n: ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 - **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（当插件支持时）。 -- `plugins.entries..env`：插件范围的环境变量映射。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。 +- `plugins.entries..env`：插件作用域的环境变量映射。 - `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的 bundle 提供的钩子目录。 -- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始会话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：为受信任的子智能体覆盖指定可选允许列表，目标使用规范化的 `provider/model`。仅在你明确想允许任意模型时使用 `"*"`。 -- `plugins.entries..config`：由插件定义的配置对象（若可用，则使用原生 OpenClaw 插件 schema 进行验证）。 -- 渠道插件的账号 / 运行时设置位于 `channels.` 下，应由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由中心化的 OpenClaw 选项注册表描述。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。 - - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 - - `baseUrl`：Firecrawl API 基础 URL（默认值：`https://api.firecrawl.dev`）。 +- `plugins.entries..hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从类型化钩子中读取原始会话内容，例如 `llm_input`、`llm_output` 和 `agent_end`。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次覆盖 `provider` 和 `model`。 +- `plugins.entries..subagent.allowedModels`：针对受信任的子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实希望允许任意模型时，才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（在可用时，由原生 OpenClaw 插件 schema 验证）。 +- 渠道插件的账号/运行时设置位于 `channels.` 下，应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 + - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 + - `baseUrl`：Firecrawl API base URL（默认值：`https://api.firecrawl.dev`）。 - `onlyMainContent`：仅提取页面主体内容（默认值：`true`）。 - - `maxAgeMs`：最大缓存时长（毫秒）（默认值：`172800000` / 2 天）。 - - `timeoutSeconds`：抓取请求超时（秒）（默认值：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。 + - `maxAgeMs`：缓存最大保留时长，单位为毫秒（默认值：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时，单位为秒（默认值：`60`）。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：内存 Dreaming 设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：Dreaming 主开关（默认值 `false`）。 - - `frequency`：每次完整 Dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。 +- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。各阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：dreaming 总开关（默认值 `false`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 周期（默认值为 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)： +- 完整的内存配置请参见 [内存配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件还可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将它们作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动的内存插件 id，或设为 `"none"` 以禁用内存插件。 -- `plugins.slots.contextEngine`：选择活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 -- `plugins.installs`：已弃用的兼容性回退字段，用于旧版 - CLI 管理的安装元数据。新的插件安装会改写入受管的 +- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动内存插件 id，或设为 `"none"` 以禁用内存插件。 +- `plugins.slots.contextEngine`：选择活动 context engine 插件 id；默认值为 `"legacy"`，除非你安装并选择了其他 engine。 +- `plugins.installs`：已弃用的兼容性回退项， + 用于旧版 CLI 管理的安装元数据。新的插件安装会改为写入受管理的 `plugins/installs.json` 状态账本。 - 旧版记录包括 `source`、`spec`、`sourcePath`、`installPath`、 `version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、 `shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 + - 请将 `plugins.installs.*` 视为受管理状态；优先使用 CLI 命令，而不是 + 手动编辑。 -请参阅 [插件](/zh-CN/tools/plugin)。 +请参见 [插件](/zh-CN/tools/plugin)。 --- @@ -211,8 +214,8 @@ x-i18n: evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景中选择启用 + // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -249,47 +252,48 @@ x-i18n: ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- `tabCleanup` 会在空闲时间后，或当某个 - 会话超过其上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 - 可禁用对应的单独清理模式。 -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格模式。 -- 仅当你明确信任私有网络浏览器导航时，才将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` 设为启用。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 设备发现检查期间也会受到相同的私有网络阻止。 -- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受支持。 +- `tabCleanup` 会在空闲超时后，或当某个 + 会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 + 可禁用这些单独的清理模式。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格。 +- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间，也会受到相同的私有网络阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 添加显式例外。 -- 远程配置文件仅支持附加模式（禁用启动 / 停止 / 重置）。 +- 远程配置文件为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；当你的提供商直接提供 DevTools WebSocket URL 时，使用 WS(S)。 -- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 - `attachOnly` CDP 可达性以及打开标签页请求。受管的 loopback + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S) + 则适用于你的提供商直接提供 DevTools WebSocket URL 的场景。 +- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程以及 + `attachOnly` CDP 可达性检查和标签页打开请求。托管的 local loopback 配置文件会保留本地 CDP 默认值。 -- 如果某个外部管理的 CDP 服务可通过 loopback 访问，请将该 - 配置文件的 `attachOnly: true` 设为启用；否则 OpenClaw 会将该 loopback 端口视为 - 本地受管浏览器配置文件，并可能报告本地端口占用错误。 -- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到 - 所选主机上，或通过已连接的浏览器节点附加。 -- `existing-session` 配置文件可以设置 `userDataDir`，以指定特定的 - Chromium 内核浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前的 Chrome MCP 路由限制： - 使用基于快照 / ref 的操作而不是 CSS 选择器定位、单文件上传 - 钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，且不支持 +- 如果某个外部管理的 CDP 服务可通过 local loopback 访问，请将该 + 配置文件的 `attachOnly: true` 设为 true；否则 OpenClaw 会把该 loopback 端口视为 + 本地托管浏览器配置文件，并可能报告本地端口归属错误。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在 + 所选主机上附加，或通过已连接的浏览器节点附加。 +- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的 + 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件保留当前 Chrome MCP 路由限制： + 使用快照/ref 驱动的操作，而不是 CSS 选择器定位；单文件上传 + 钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有在远程 CDP 场景下 才需要显式设置 `cdpUrl`。 -- 本地受管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 +- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。 -- 本地受管配置文件会在进程启动后，使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP - 设备发现，并使用 `browser.localCdpReadyTimeoutMs` 检查 - 启动后的 CDP websocket 就绪状态。在较慢的主机上，如果 Chrome 能成功启动但就绪检查与启动过程发生竞争， - 请调高这些值。这两个值都必须是 +- 本地托管配置文件在进程启动后，会使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP + 发现，并使用 `browser.localCdpReadyTimeoutMs` 检查 + 启动后 CDP websocket 就绪状态。在较慢的主机上，如果 Chrome 能成功启动， + 但就绪检查与启动过程竞争，请提高这些值。两个值都必须是 不超过 `120000` ms 的正整数；无效配置值会被拒绝。 -- 自动检测顺序：默认浏览器（若为 Chromium 内核）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 - `browser.executablePath` 和 `browser.profiles..executablePath` 都 支持在 Chromium 启动前将 `~` 和 `~/...` 展开为你的操作系统主目录。 `existing-session` 配置文件上的每配置文件 `userDataDir` 也支持波浪号展开。 -- 控制服务：仅 loopback（端口从 `gateway.port` 派生，默认值为 `18791`）。 -- `extraArgs` 会将额外启动标志追加到本地 Chromium 启动参数中（例如 +- Control 服务：仅限 loopback（端口派生自 `gateway.port`，默认值为 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动追加额外的启动标志（例如 `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -309,7 +313,7 @@ x-i18n: ``` - `seamColor`：原生应用 UI 外框的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖设置。会回退到当前活动智能体身份。 +- `assistant`：Control UI 身份覆盖。回退到当前活动智能体身份。 --- @@ -356,20 +360,20 @@ x-i18n: // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // 可选。默认值为 false。 allowRealIpFallback: false, nodes: { pairing: { - // Optional. Default unset/disabled. + // 可选。默认未设置/禁用。 autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, allowCommands: ["canvas.navigate"], denyCommands: ["system.run"], }, tools: { - // Additional /tools/invoke HTTP denies + // 额外的 /tools/invoke HTTP 拒绝项 deny: ["browser"], - // Remove tools from the default HTTP deny list + // 从默认 HTTP 拒绝列表中移除工具 allow: ["gateway"], }, push: { @@ -389,48 +393,49 @@ x-i18n: - `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可访问。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必须启用。非 loopback bind 要求 Gateway 网关认证。实际中，这意味着共享 token / password，或使用带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设为 `token` 或 `password`。如果两者都已配置但未设置 mode，启动以及服务安装 / 修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示不会提供此选项，这是有意为之。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可用于满足 Control UI / WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们仍遵循 Gateway 网关常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证范围生效（共享密钥和设备 token 会分别跟踪）。被拦截的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径中，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个都作为普通不匹配同时穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你明确希望 localhost 流量也被限流（用于测试环境或严格代理部署），请设为 `false`。 -- 来自浏览器来源的 WS 认证尝试始终会启用限流，并禁用 loopback 豁免（作为防御纵深措施，以防浏览器发起的 localhost 暴力破解）。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback bind 必须启用 Gateway 网关认证。实际做法通常是使用共享 token/password，或配置带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设为 `token` 或 `password`。当两者都已配置且未设置 mode 时，启动以及服务安装/修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 loopback 环境；新手引导提示中不会提供此选项，这是有意为之。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求代理来源为**非 loopback**；同主机 loopback 反向代理不满足 trusted-proxy 认证条件。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可用于满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用这种 Tailscale 头认证；它们仍遵循 Gateway 网关常规的 HTTP 认证模式。这个无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥与设备 token 会分别跟踪）。被拦截的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录前串行化处理。因此，同一客户端的并发错误尝试，可能会在第二个请求时触发限流，而不是两个请求都作为普通不匹配同时穿过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意希望连 localhost 流量也受到限流（例如测试环境或严格代理部署），请设为 `false`。 +- 来自浏览器来源的 WS 认证尝试始终会启用限流，且关闭 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 - 在 loopback 上，这些来自浏览器来源的锁定会按规范化后的 `Origin` - 值彼此隔离，因此来自某个 localhost origin 的重复失败不会自动 - 锁定其他 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为刻意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。 + 值隔离，因此来自某一个 localhost origin 的重复失败，不会自动 + 锁定另一个 origin。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时，这是必需的。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，启用 Host 头 origin 回退，适用于有意依赖 Host 头 origin 策略的部署。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的紧急放行覆盖项， - 允许对受信任私有网络 IP 使用明文 `ws://`；默认情况下明文仍仅限 loopback。 - 没有与之对应的 `openclaw.json` 配置项，而且浏览器私有网络配置，例如 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的 + 紧急放行覆盖项，允许对受信任私有网络 IP 使用明文 `ws://`； + 默认情况下，明文仍仅限 loopback。没有等价的 `openclaw.json` + 配置项，且浏览器私有网络配置，例如 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，也不会影响 Gateway 网关 WebSocket 客户端。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：用于官方 / TestFlight iOS 构建的外部 APNs 中继基础 HTTPS URL；这些构建在将基于中继的注册发布到 Gateway 网关后会使用它。该 URL 必须与编译进 iOS 构建的中继 URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时，单位为毫秒。默认值为 `10000`。 -- 基于中继的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中附带该身份，并将一个按注册范围限定的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述中继配置的临时环境变量覆盖项。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生开关，用于 loopback HTTP 中继 URL。生产中继 URL 应保持为 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道 / 账号在滚动一小时内最多允许的健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：每渠道的健康监控重启退出选项，同时保留全局监控启用状态。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的每账号覆盖项。设置后，其优先级高于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可使用 `gateway.remote.*` 作为回退。 -- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以关闭方式失败（不会用远程回退来掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 -- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败即关闭的行为。 -- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR / IP 允许列表，用于自动批准首次节点设备配对，且该配对未请求任何 scope。未设置时即为禁用。它不会自动批准 operator / browser / Control UI / WebChat 配对，也不会自动批准角色、scope、元数据或公钥升级。 -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许 / 拒绝整形。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外屏蔽的工具名称（扩展默认拒绝列表）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 +- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时，单位为毫秒。默认值为 `10000`。 +- 基于 relay 的注册会委派给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将按注册范围的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖项。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生舱，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监视器的间隔分钟数。设为 `0` 可全局禁用健康监视器重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。应保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监视器重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：渠道级别的健康监视器重启退出选项，同时保留全局监视器启用状态。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的逐账号覆盖项。设置后，其优先级高于渠道级别覆盖项。 +- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以回退使用 `gateway.remote.*`。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未能解析，解析会以关闭方式失败（不会由远程回退进行掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只列出你控制的代理。对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理），loopback 条目仍然有效，但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认为 `false`，以实现失败即关闭的行为。 +- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，且该配对未请求任何 scopes。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准 role、scope、metadata 或公钥升级。 +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许/拒绝塑形。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外屏蔽的工具名（扩展默认拒绝列表）。 +- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 @@ -442,14 +447,14 @@ x-i18n: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 -- 可选的响应加固标头： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 空允许列表会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 +- 可选的响应加固头： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关实例时，请使用唯一端口和状态目录： +在同一主机上运行多个 Gateway 网关实例时，请使用唯一的端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -457,9 +462,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile `（使用 `~/.openclaw-`）。 +便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -请参阅 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 +请参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -477,10 +482,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS / WSS）（默认值：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书 / 密钥对；仅用于本地 / 开发环境。 +- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 +- `autoGenerate`：在未配置显式文件时，自动生成本地自签名证书/密钥对；仅供本地/开发使用。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请限制其权限。 +- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 - `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -497,17 +502,17 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制如何在运行时应用配置编辑。 +- `mode`：控制配置编辑在运行时如何应用。 - `"off"`：忽略实时编辑；更改需要显式重启。 - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：在不重启的情况下在进程内应用更改。 + - `"hot"`：在进程内应用更改，无需重启。 - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 -- `debounceMs`：应用配置更改前的去抖窗口，单位为毫秒（非负整数）。 -- `deferralTimeoutMs`：可选的最长等待时间，单位为毫秒，用于等待正在进行的操作完成，超时后强制重启。省略或设为 `0` 表示无限期等待，并定期记录仍在等待的警告。 +- `debounceMs`：应用配置更改前的防抖窗口，单位为 ms（非负整数）。 +- `deferralTimeoutMs`：可选的最大等待时间，单位为 ms，用于等待正在进行中的操作后再强制重启。省略或设为 `0` 表示无限等待，并定期记录“仍在等待中”的警告。 --- -## Hooks +## 钩子 ```json5 { @@ -543,44 +548,44 @@ openclaw gateway --port 19001 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 拒绝使用查询字符串 hook token。 -验证和安全说明： +验证与安全说明： -- `hooks.enabled=true` 要求提供非空的 `hooks.token`。 +- `hooks.enabled=true` 需要非空的 `hooks.token`。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 - 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认值：`false`）。 + - 只有当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认值：`false`）。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 -- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径中的某个负载字段。 -- 诸如 `{{messages[0].subject}}` 之类的模板会从负载中读取。 -- `transform` 可以指向一个返回 hook 动作的 JS / TS 模块。 - - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 会匹配通用路径中的某个负载字段。 +- 诸如 `{{messages[0].subject}}` 这样的模板会从负载中读取内容。 +- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 - `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或 preset 使用模板化 `sessionKey` 时，它就成为必填项。 -- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。 -- `model` 会为此 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，它就成为必需项。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 +- `model` 会为此次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。 ### Gmail 集成 -- 内置的 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不是使用默认的模板化值。 +- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不要使用模板化默认值。 ```json5 { @@ -604,7 +609,7 @@ openclaw gateway --port 19001 ``` - 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边另行运行一个独立的 `gog gmail watch serve`。 +- 不要与 Gateway 网关同时运行单独的 `gog gmail watch serve`。 --- @@ -620,16 +625,16 @@ openclaw gateway --port 19001 } ``` -- 通过 Gateway 网关端口下的 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI： +- 通过 Gateway 网关端口在 HTTP 下提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback bind：canvas 路由和其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token / password / trusted-proxy）。 -- 节点 WebView 通常不会发送认证标头；节点完成配对并连接后，Gateway 网关会为 canvas / A2UI 访问通告节点范围的能力 URL。 -- 能力 URL 绑定到当前活跃的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 会将 live-reload 客户端注入到所提供的 HTML 中。 +- 仅限本地：保持 `gateway.bind: "loopback"`（默认值）。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- 节点 WebView 通常不会发送认证头；当节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域能力 URL。 +- 能力 URL 绑定到当前活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 会向所提供的 HTML 中注入 live-reload 客户端。 - 当目录为空时，会自动创建起始 `index.html`。 -- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 - 更改需要重启 Gateway 网关。 - 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 @@ -663,7 +668,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。若需跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 +会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -688,10 +693,10 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少该键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 -- 完整优先级请参阅 [环境](/zh-CN/help/environment)。 +- 仅当进程环境中缺少对应键时，才会应用内联环境变量。 +- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。 +- 完整优先级请参见 [环境](/zh-CN/help/environment)。 ### 环境变量替换 @@ -706,9 +711,9 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失 / 为空的变量会在配置加载时抛出错误。 -- 使用 `$${VAR}` 来表示字面量 `${VAR}`。 -- 可与 `$include` 一起使用。 +- 缺失/为空的变量会在配置加载时抛出错误。 +- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 +- 适用于 `$include`。 --- @@ -718,7 +723,7 @@ SecretRef 是增量式的：明文值仍然可用。 ### `SecretRef` -使用一种对象形状： +使用以下对象结构之一： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -730,13 +735,13 @@ SecretRef 是增量式的：明文值仍然可用。 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不能包含以 `/` 分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不能包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） -### 支持的凭证面 +### 支持的凭证表面 -- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 会以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖范围内。 +- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 +- `auth-profiles.json` 中的 refs 也包含在运行时解析和审计覆盖范围内。 ### Secret 提供商配置 @@ -768,14 +773,14 @@ SecretRef 是增量式的：明文值仍然可用。 说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会以关闭方式失败。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。 -- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin / stdout 上的协议负载进行通信。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证已解析目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会应用到已解析目标路径。 -- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传入所需变量。 -- Secret 引用会在激活时解析为内存中的快照，之后请求路径只读取该快照。 -- 激活期间会应用活动面过滤：启用面上的未解析引用会导致启动 / 重载失败，而非活动面会被跳过并给出诊断信息。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 +- 当无法验证 Windows ACL 时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 上的协议负载工作。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 +- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 +- Secret refs 会在激活时解析为内存快照，之后请求路径只读取该快照。 +- 激活期间会应用活动表面过滤：已启用表面上无法解析的 refs 会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。 --- @@ -797,13 +802,13 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 每个智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级别引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`），用于静态凭证模式。 -- OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 每个智能体的 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持值级别 refs（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式的 profiles（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时，会将其清除。 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 -- 请参阅 [OAuth](/zh-CN/concepts/oauth)。 -- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参阅 [Secrets Management](/zh-CN/gateway/secrets)。 +- 请参见 [OAuth](/zh-CN/concepts/oauth)。 +- Secrets 运行时行为，以及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -825,20 +830,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置文件因真实的 - 计费 / 余额不足错误而失败时，使用的基础退避时长（小时）（默认值：`5`）。即使在 `401` / `403` 响应上，明确的计费文本 - 仍可能落入此类，但提供商特定的文本匹配器 - 仍只作用于拥有它们的提供商（例如 OpenRouter - `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 - organization / workspace 支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商划分的计费退避时长覆盖项。 -- `billingMaxHours`：计费退避指数增长的上限时长（小时）（默认值：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟）（默认值：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限时长（分钟）（默认值：`60`）。 +- `billingBackoffHours`：当某个 profile 因真实的 + 计费/余额不足错误而失败时的基础退避时长（小时）（默认值：`5`）。即使在 `401`/`403` 响应下，明确的计费文本 + 仍可能落入这里，但提供商特定的文本匹配器 + 仍然仅限于拥有它们的提供商（例如 OpenRouter 的 + `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 + organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。 +- `billingMaxHours`：计费退避指数增长的上限小时数（默认值：`24`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认值：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认值：`60`）。 - `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认值：`24`）。 -- `overloadedProfileRotations`：对于过载错误，在切换到模型回退前，同一提供商 auth-profile 最多允许的轮换次数（默认值：`1`）。像 `ModelNotReadyException` 这样的提供商忙碌形态会落入此类。 -- `overloadedBackoffMs`：在重试过载提供商 / 配置文件轮换前的固定延迟（默认值：`0`）。 -- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退前，同一提供商 auth-profile 最多允许的轮换次数（默认值：`1`）。该限流桶包括提供商形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `overloadedProfileRotations`：同一提供商 auth-profile 因过载错误进行轮换的最大次数，超过后才切换到模型回退（默认值：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态归入这里。 +- `overloadedBackoffMs`：在重试某个过载的提供商/profile 轮换前的固定延迟（默认值：`0`）。 +- `rateLimitedProfileRotations`：同一提供商 auth-profile 因速率限制错误进行轮换的最大次数，超过后才切换到模型回退（默认值：`1`）。该速率限制桶包括提供商特定文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -858,9 +863,9 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用稳定路径。 +- 设置 `logging.file` 可使用固定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入前的最大日志文件大小（字节）（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- `maxFileBytes`：在抑制写入前，日志文件允许的最大字节数（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -906,21 +911,22 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `enabled`：仪表化输出的总开关（默认值：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 之类的通配符）。 -- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的时长阈值，单位为毫秒。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认值：`false`）。 -- `otel.endpoint`：用于 OTel 导出的收集器 URL。 +- `flags`：启用定向日志输出的标志字符串数组（支持通配符，例如 `"telegram.*"` 或 `"*"`）。 +- `stuckSessionWarnMs`：当会话持续处于处理状态时，发出卡住会话警告的年龄阈值，单位为 ms。 +- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认值：`false`）。 +- `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP / gRPC 元数据标头。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。 - `otel.serviceName`：资源属性的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率，范围为 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷出遥测数据的时间间隔，单位为毫秒。 -- `otel.captureContent`：用于 OTel span 属性中原始内容捕获的显式启用项。默认关闭。布尔值 `true` 会捕获非 system 消息 / 工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 -- `OPENCLAW_OTEL_PRELOADED=1`：用于那些已注册全局 OpenTelemetry SDK 的主机的环境开关。此时 OpenClaw 会跳过由插件拥有的 SDK 启动 / 关闭流程，同时保持诊断监听器处于活动状态。 -- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认值：`false`）。 -- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（默认均为 `true`）。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 +- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 +- `otel.flushIntervalMs`：定期刷新遥测数据的间隔，单位为 ms。 +- `otel.captureContent`：为 OTEL span 属性选择启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 消息/工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：环境变量开关，用于启用最新的实验性 GenAI span provider 属性。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI metrics 使用有界语义属性。 +- `OPENCLAW_OTEL_PRELOADED=1`：环境变量开关，用于那些已经注册全局 OpenTelemetry SDK 的主机。此时 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保留诊断监听器处于活动状态。 +- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认值：`false`）。 +- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。 --- @@ -942,12 +948,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `channel`：用于 npm / git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：在 Gateway 网关启动时检查 npm 更新（默认值：`true`）。 +- `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。 -- `auto.stableDelayHours`：稳定渠道自动应用前的最小时延（小时）（默认值：`6`；最大值：`168`）。 -- `auto.stableJitterHours`：稳定渠道额外的发布扩散窗口（小时）（默认值：`12`；最大值：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查的运行频率（小时）（默认值：`1`；最大值：`24`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。 +- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外小时数（默认值：`12`；最大值：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认值：`1`；最大值：`24`）。 --- @@ -980,22 +986,22 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：全局 ACP 功能门控（默认值：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认值：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须与已注册的 ACP 运行时插件匹配）。 -- `defaultAgent`：当生成过程未指定显式目标时，使用的后备 ACP 目标智能体 id。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示没有额外限制。 +- `enabled`：全局 ACP 功能开关（默认值：`false`）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认值：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。 +- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 +- `defaultAgent`：当派生运行未指定显式目标时，使用的回退 ACP 目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空值表示没有额外限制。 - `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷出窗口，单位为毫秒。 -- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态 / 工具行（默认值：`true`）。 -- `stream.deliveryMode`：`"live"` 增量式流送；`"final_only"` 缓冲直到轮次终止事件。 -- `stream.hiddenBoundarySeparator`：在隐藏工具事件后的可见文本前插入的分隔符（默认值：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次可投影的智能体输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态 / 更新行最大字符数。 -- `stream.tagVisibility`：标签名到布尔可见性覆盖的记录，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL，单位为分钟。 -- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。 +- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位为 ms。 +- `stream.maxChunkChars`：流式块投影在拆分前的最大块大小。 +- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认值：`true`）。 +- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。 +- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前使用的分隔符（默认值：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 +- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 +- `stream.tagVisibility`：一个记录，保存 tag 名称到布尔可见性覆盖值的映射，用于流式事件。 +- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL，单位为分钟。 +- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -1012,10 +1018,10 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣 / 季节性标语。 + - `"random"`（默认）：轮换的有趣/季节性标语。 - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。 -- 若要隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 +- 若要隐藏整个 banner（而不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -1039,13 +1045,13 @@ SecretRef 是增量式的：明文值仍然可用。 ## 身份 -请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的 identity 字段。 +请参见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。 --- ## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可剥离未知键）。 +当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前会导致验证失败；`openclaw doctor --fix` 可剥离未知键）。 @@ -1085,11 +1091,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 清理前，已完成的隔离 cron 运行会话保留多久。也控制已归档已删除 cron 转录的清理。默认值：`24h`；设为 `false` 以禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发裁剪前的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志裁剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不会发送认证标头。 -- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于那些仍带有 `notify: true` 的已存储任务。 +- `sessionRetention`：从 `sessions.json` 中清理前，保留已完成隔离 cron 运行会话的时长。也控制已归档删除的 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前的最大大小。默认值：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。 +- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不发送认证头。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于那些仍有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -1105,11 +1111,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认值：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试使用的退避延迟数组，单位为毫秒（默认值：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。 +- `maxAttempts`：一次性作业在瞬时错误上的最大重试次数（默认值：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试的退避延迟数组，单位为 ms（默认值：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则表示重试所有瞬时类型。 -仅适用于一次性 cron 任务。周期性任务使用独立的失败处理。 +仅适用于一次性 cron 作业。周期性作业使用单独的失败处理机制。 ### `cron.failureAlert` @@ -1127,11 +1133,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：为 cron 任务启用失败告警（默认值：`false`）。 -- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。 -- `cooldownMs`：同一任务重复告警之间的最小间隔，单位为毫秒（非负整数）。 -- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。 -- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。 +- `enabled`：启用 cron 作业失败告警（默认值：`false`）。 +- `after`：在触发告警前允许的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。 +- `accountId`：用于限定告警投递范围的可选账号或渠道 id。 ### `cron.failureDestination` @@ -1148,16 +1154,16 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 所有任务共享的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时默认值为 `"announce"`。 -- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最近一次已知的投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。在 webhook 模式下为必填项。 -- `accountId`：可选的投递账号覆盖项。 -- 每任务 `delivery.failureDestination` 会覆盖这个全局默认值。 -- 当既未设置全局也未设置每任务失败目标时，那些本来就通过 `announce` 投递的任务，在失败时会回退到其主 announce 目标。 -- `delivery.failureDestination` 仅对 `sessionTarget="isolated"` 任务受支持，除非该任务的主 `delivery.mode` 是 `"webhook"`。 +- 所有作业共享的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 +- `channel`：用于 announce 投递的渠道覆盖值。`"last"` 会复用上一次已知的投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：可选的投递账号覆盖值。 +- 每个作业的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当全局和每作业失败目标都未设置时，那些原本已通过 `announce` 投递的作业，在失败时会回退到其主 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 --- @@ -1165,34 +1171,34 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | -| ---------------- | -------------------------------------- | -| `{{Body}}` | 完整的入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史记录 / 发送者包装） | -| `{{BodyStripped}}` | 已去除群组提及的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新会话创建时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（图像 / 音频 / 文档 / …） | -| `{{Transcript}}` | 音频转录文本 | -| `{{Prompt}}` | CLI 条目的已解析媒体提示词 | -| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | -| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | +| 变量 | 说明 | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | 完整入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 新建会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录文本 | +| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示词 | +| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力提供） | +| `{{GroupMembers}}` | 群组成员预览（尽力提供） | +| `{{SenderName}}` | 发送者显示名称（尽力提供） | +| `{{SenderE164}}` | 发送者电话号码（尽力提供） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置包含（`$include`） +## 配置 include（`$include`） -将配置拆分到多个文件中： +将配置拆分为多个文件： ```json5 // ~/.openclaw/openclaw.json @@ -1207,18 +1213,18 @@ SecretRef 是增量式的：明文值仍然可用。 **合并行为：** -- 单文件：替换所在的包含对象。 +- 单个文件：替换其所在的包含对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 include 之后合并（覆盖被包含的值）。 -- 嵌套 include：最多 10 层深。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径 / `../` 形式最终仍解析到该边界内时才允许。 -- 仅更改由单文件 include 支持的某一个顶层 section 的 OpenClaw 自有写入，会透传写入到该被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 根 include、include 数组，以及带有同级覆盖的 include，对 OpenClaw 自有写入而言是只读的；这些写入会以关闭方式失败，而不是将配置展平。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰消息。 +- 同级键：在 includes 之后合并（覆盖已包含的值）。 +- 嵌套 includes：最多支持 10 层深度。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在最终仍解析到该边界内时，才允许使用绝对路径/`../` 形式。 +- 当 OpenClaw 自有写入仅更改由单文件 include 支持的某个顶层分区时，该写入会透传到被包含的文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 +- 根级 include、include 数组，以及带有同级覆盖的 include，对于 OpenClaw 自有写入均为只读；这类写入会以关闭方式失败，而不是将配置展平。 +- 错误：针对缺失文件、解析错误和循环 include 提供清晰消息。 --- -_相关：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ ## 相关 diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index 2ff6b0930..e296d8eef 100644 --- a/docs/zh-CN/logging.md +++ b/docs/zh-CN/logging.md @@ -1,37 +1,37 @@ --- read_when: - - 你需要一个适合初学者的日志概览 + - 你需要一份面向初学者的日志概览 - 你想要配置日志级别或格式 - 你正在进行故障排除，需要快速找到日志 summary: 日志概览：文件日志、控制台输出、CLI 尾随查看，以及 Control UI title: 日志概览 x-i18n: - generated_at: "2026-04-25T18:39:15Z" + generated_at: "2026-04-25T19:34:27Z" model: gpt-5.4 provider: openai - source_hash: 745c14ef9ca008d43a0f4f2d5c051ec6bafbe5249e1a1753448182fff72afd6e + source_hash: 47bd7c3c515248ba2580bd372417e5842f6936bcc92b0fd83301491293d0be2c source_path: logging.md workflow: 15 --- # 日志 -OpenClaw 有两个主要的日志输出面： +OpenClaw 有两个主要的日志界面： - 由 Gateway 网关写入的**文件日志**（JSON 行）。 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。 -Control UI 的 **Logs** 选项卡会尾随读取网关文件日志。本页将说明日志存放在哪里、如何读取日志，以及如何配置日志级别和格式。 +Control UI 的 **Logs** 选项卡会尾随读取 gateway 文件日志。本页说明日志存放在哪里、如何读取，以及如何配置日志级别和格式。 ## 日志存放位置 -默认情况下，Gateway 网关会在以下位置写入滚动日志文件： +默认情况下，Gateway 网关会将滚动日志文件写入： `/tmp/openclaw/openclaw-YYYY-MM-DD.log` -日期使用网关主机的本地时区。 +日期使用 gateway 主机的本地时区。 -你可以在 `~/.openclaw/openclaw.json` 中覆盖该设置： +你可以在 `~/.openclaw/openclaw.json` 中覆盖此设置： ```json { @@ -45,15 +45,15 @@ Control UI 的 **Logs** 选项卡会尾随读取网关文件日志。本页将 ### CLI：实时尾随查看（推荐） -使用 CLI 通过 RPC 尾随查看网关日志文件： +使用 CLI 通过 RPC 尾随读取 gateway 日志文件： ```bash openclaw logs --follow ``` -当前有用的选项： +当前常用选项： -- `--local-time`：按你的本地时区显示时间戳 +- `--local-time`：使用你的本地时区显示时间戳 - `--url ` / `--token ` / `--timeout `：标准 Gateway 网关 RPC 标志 - `--expect-final`：由智能体支持的 RPC 最终响应等待标志（这里通过共享客户端层接受） @@ -67,16 +67,16 @@ openclaw logs --follow 当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量中的凭证；如果目标 Gateway 网关需要认证，请自行包含 `--token`。 -在 JSON 模式下，CLI 会输出带有 `type` 标记的对象： +在 JSON 模式下，CLI 会输出带有 `type` 标签的对象： - `meta`：流元数据（文件、游标、大小） - `log`：已解析的日志条目 - `notice`：截断 / 轮转提示 - `raw`：未解析的原始日志行 -如果本地的 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式的 `--url` 目标不会使用此回退。 +如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式的 `--url` 目标不会使用此回退机制。 -如果 Gateway 网关无法访问，CLI 会输出一条简短提示，建议运行： +如果 Gateway 网关无法访问，CLI 会打印一条简短提示，建议运行： ```bash openclaw doctor @@ -84,12 +84,11 @@ openclaw doctor ### Control UI（网页） -Control UI 的 **Logs** 选项卡会使用 `logs.tail` 尾随读取同一个文件。 -有关如何打开它，请参阅 [/web/control-ui](/zh-CN/web/control-ui)。 +Control UI 的 **Logs** 选项卡会使用 `logs.tail` 尾随读取同一个文件。有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 -### 仅查看渠道日志 +### 仅渠道日志 -如需筛选渠道活动（WhatsApp / Telegram 等），请使用： +要筛选渠道活动（WhatsApp/Telegram 等），请使用： ```bash openclaw channels logs --channel whatsapp @@ -99,15 +98,15 @@ openclaw channels logs --channel whatsapp ### 文件日志（JSONL） -日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以渲染结构化输出（时间、级别、子系统、消息）。 +日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以呈现结构化输出（时间、级别、子系统、消息）。 ### 控制台输出 -控制台日志会**感知 TTY**，并以便于阅读的格式显示： +控制台日志会**感知 TTY**，并以便于阅读的方式格式化： - 子系统前缀（例如 `gateway/channels/whatsapp`） -- 级别着色（info / warn / error） -- 可选的紧凑模式或 JSON 模式 +- 级别着色（info/warn/error） +- 可选的紧凑或 JSON 模式 控制台格式由 `logging.consoleStyle` 控制。 @@ -115,9 +114,9 @@ openclaw channels logs --channel whatsapp `openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志： -- 普通模式：只显示重要结果（错误、解析错误、慢调用） +- 普通模式：仅显示重要结果（错误、解析错误、慢调用） - `--verbose`：显示所有请求 / 响应流量 -- `--ws-log auto|compact|full`：选择详细输出的渲染样式 +- `--ws-log auto|compact|full`：选择详细日志的呈现样式 - `--compact`：`--ws-log compact` 的别名 示例： @@ -130,7 +129,7 @@ openclaw gateway --verbose --ws-log full ## 配置日志 -所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。 +所有日志配置都位于 `~/.openclaw/openclaw.json` 中的 `logging` 下。 ```json { @@ -150,34 +149,34 @@ openclaw gateway --verbose --ws-log full - `logging.level`：**文件日志**（JSONL）级别。 - `logging.consoleLevel`：**控制台**详细程度级别。 -你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level `**（例如 `openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在单次运行中提高详细程度，而无需编辑 `openclaw.json`。你也可以传递全局 CLI 选项 **`--log-level `**（例如，`openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。 -`--verbose` 仅影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 +`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 ### 控制台样式 `logging.consoleStyle`： -- `pretty`：适合人阅读、带颜色、带时间戳。 +- `pretty`：适合人工阅读，带颜色和时间戳。 - `compact`：更紧凑的输出（最适合长时间会话）。 -- `json`：每行一个 JSON（用于日志处理器）。 +- `json`：每行一个 JSON（适用于日志处理器）。 ### 脱敏 -工具摘要可以在输出到控制台之前，对敏感令牌进行脱敏： +工具摘要可以在输出到控制台之前对敏感令牌进行脱敏： - `logging.redactSensitive`：`off` | `tools`（默认：`tools`） -- `logging.redactPatterns`：正则表达式字符串列表，用于覆盖默认集合 +- `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表 -脱敏**只影响控制台输出**，不会修改文件日志。 +脱敏**仅影响控制台输出**，不会修改文件日志。 ## 诊断 + OpenTelemetry -诊断是面向模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**取代日志；它们的存在是为了向指标、追踪和其他导出器提供数据。 +诊断是用于模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了提供给指标、追踪和其他导出器使用。 -诊断事件会在进程内发出，但只有在启用了 diagnostics 和导出器插件后，导出器才会附加。 +诊断事件会在进程内发出，但只有在启用 diagnostics 和导出器插件后，导出器才会附加。 -### OpenTelemetry 与 OTLP 的区别 +### OpenTelemetry 与 OTLP - **OpenTelemetry（OTel）**：用于追踪、指标和日志的数据模型 + SDK。 - **OTLP**：用于将 OTel 数据导出到收集器 / 后端的线协议。 @@ -185,44 +184,43 @@ openclaw gateway --verbose --ws-log full ### 导出的信号 -- **指标**：计数器 + 直方图（token 使用量、消息流、排队）。 -- **追踪**：用于模型使用 + webhook / 消息处理的 span。 -- **日志**：当启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请留意 `logging.level` 和导出器过滤器。 +- **指标**：计数器 + 直方图（令牌用量、消息流、排队）。 +- **追踪**：用于模型使用和 webhook / 消息处理的 span。 +- **日志**：当启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很高；请留意 `logging.level` 和导出器过滤器。 ### 诊断事件目录 -模型使用： +模型使用情况： -- `model.usage`：token、成本、时长、上下文、provider / model / channel、session id。 +- `model.usage`：令牌、成本、耗时、上下文、provider / model / channel、会话 ID。`usage` 是提供商 / 单轮的成本和遥测记账；`context.used` 是当前提示 / 上下文快照，在涉及缓存输入或工具循环调用时，可能低于提供商的 `usage.total`。 消息流： - `webhook.received`：每个渠道的 webhook 入站。 -- `webhook.processed`：webhook 已处理 + 时长。 +- `webhook.processed`：webhook 已处理 + 耗时。 - `webhook.error`：webhook 处理器错误。 -- `message.queued`：消息已加入处理队列。 -- `message.processed`：结果 + 时长 + 可选错误。 -- `message.delivery.started`：出站投递尝试已开始。 -- `message.delivery.completed`：出站投递尝试已完成 + 时长 / 结果数量。 -- `message.delivery.error`：出站投递尝试失败 + 时长 / 有界错误类别。 +- `message.queued`：消息已入队等待处理。 +- `message.processed`：结果 + 耗时 + 可选错误。 +- `message.delivery.started`：出站投递尝试开始。 +- `message.delivery.completed`：出站投递尝试完成 + 耗时 / 结果数量。 +- `message.delivery.error`：出站投递尝试失败 + 耗时 / 有界错误类别。 队列 + 会话： - `queue.lane.enqueue`：命令队列通道入队 + 深度。 - `queue.lane.dequeue`：命令队列通道出队 + 等待时间。 - `session.state`：会话状态转换 + 原因。 -- `session.stuck`：会话卡住警告 + 持续时长。 +- `session.stuck`：会话卡住警告 + 持续时间。 - `run.attempt`：运行重试 / 尝试元数据。 - `diagnostic.heartbeat`：聚合计数器（webhook / 队列 / 会话）。 -Exec： +执行： -- `exec.process.completed`：终端 exec 进程结果、时长、目标、模式、 - 退出码和失败类型。不包含命令文本和工作目录。 +- `exec.process.completed`：终端 exec 进程结果、耗时、目标、模式、退出码和失败类型。不包含命令文本和工作目录。 -### 启用 diagnostics（不启用导出器） +### 启用 diagnostics（无导出器） -如果你希望 diagnostics 事件可供插件或自定义接收端使用，请这样配置： +如果你希望诊断事件可供插件或自定义接收端使用，请使用： ```json { @@ -232,10 +230,9 @@ Exec： } ``` -### diagnostics 标志（定向日志） +### Diagnostics 标志（定向日志） -使用标志启用额外的、定向的调试日志，而不必提高 `logging.level`。 -标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。 +使用标志可以在不提高 `logging.level` 的情况下启用额外的定向调试日志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。 ```json { @@ -254,12 +251,12 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload 说明： - 标志日志会写入标准日志文件（与 `logging.file` 相同）。 -- 输出仍会按照 `logging.redactSensitive` 进行脱敏。 +- 输出仍会根据 `logging.redactSensitive` 进行脱敏。 - 完整指南：[/diagnostics/flags](/zh-CN/diagnostics/flags)。 ### 导出到 OpenTelemetry -diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器 / 后端。 +可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出诊断数据。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器 / 后端。 ```json { @@ -300,120 +297,93 @@ diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适 - 你也可以使用 `openclaw plugins enable diagnostics-otel` 启用该插件。 - `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。 -- 指标包括 token 使用量、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间）。 -- 可以通过 `traces` / `metrics` 切换追踪 / 指标（默认：开启）。启用后，追踪包括模型使用 span，以及 webhook / 消息处理 span。 -- 默认不会导出原始模型 / 工具内容。仅当你的收集器和保留策略已获准用于提示词、响应、工具或系统提示词文本时，才使用 `diagnostics.otel.captureContent`。 +- 指标包括令牌用量、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间），以及 GenAI 令牌用量和模型调用时长直方图。 +- 可以通过 `traces` / `metrics` 切换追踪 / 指标（默认：开启）。启用时，追踪包含模型使用 span 以及 webhook / 消息处理 span。 +- 默认不会导出原始模型 / 工具内容。仅在你的收集器和保留策略已获批准用于提示词、响应、工具或系统提示词文本时，才使用 `diagnostics.otel.captureContent`。 - 当你的收集器需要认证时，请设置 `headers`。 -- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、 - `OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。 +- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。 +- 设置 `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` 以发出最新的实验性 GenAI provider span 属性（`gen_ai.provider.name`），而不是旧版 span 属性（`gen_ai.system`）。GenAI 指标始终使用有界、低基数的语义属性。 - 当另一个预加载项或宿主进程已经注册了全局 OpenTelemetry SDK 时，请设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭自己的 SDK，但仍会连接 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。 ### 已导出指标（名称 + 类型） -模型使用： +模型使用情况： -- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、 - `openclaw.provider`、`openclaw.model`） -- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、 - `openclaw.model`） -- `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、 - `openclaw.provider`、`openclaw.model`） -- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、 - `openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `gen_ai.client.token.usage`（直方图，GenAI 语义约定指标， - 属性：`gen_ai.token.type` = `input` / `output`、`gen_ai.system`、 - `gen_ai.operation.name`、`gen_ai.request.model`） +- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `gen_ai.client.token.usage`（直方图，GenAI semantic-conventions 指标，属性：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`） +- `gen_ai.client.operation.duration`（直方图，单位为秒，GenAI semantic-conventions 指标，属性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`，可选 `error.type`） 消息流： -- `openclaw.webhook.received`（计数器，属性：`openclaw.channel`、 - `openclaw.webhook`） -- `openclaw.webhook.error`（计数器，属性：`openclaw.channel`、 - `openclaw.webhook`） -- `openclaw.webhook.duration_ms`（直方图，属性：`openclaw.channel`、 - `openclaw.webhook`） -- `openclaw.message.queued`（计数器，属性：`openclaw.channel`、 - `openclaw.source`） -- `openclaw.message.processed`（计数器，属性：`openclaw.channel`、 - `openclaw.outcome`） -- `openclaw.message.duration_ms`（直方图，属性：`openclaw.channel`、 - `openclaw.outcome`） -- `openclaw.message.delivery.started`（计数器，属性：`openclaw.channel`、 - `openclaw.delivery.kind`） -- `openclaw.message.delivery.duration_ms`（直方图，属性： - `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、 - `openclaw.errorCategory`） +- `openclaw.webhook.received`（计数器，属性：`openclaw.channel`、`openclaw.webhook`） +- `openclaw.webhook.error`（计数器，属性：`openclaw.channel`、`openclaw.webhook`） +- `openclaw.webhook.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.webhook`） +- `openclaw.message.queued`（计数器，属性：`openclaw.channel`、`openclaw.source`） +- `openclaw.message.processed`（计数器，属性：`openclaw.channel`、`openclaw.outcome`） +- `openclaw.message.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.outcome`） +- `openclaw.message.delivery.started`（计数器，属性：`openclaw.channel`、`openclaw.delivery.kind`） +- `openclaw.message.delivery.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`） 队列 + 会话： - `openclaw.queue.lane.enqueue`（计数器，属性：`openclaw.lane`） - `openclaw.queue.lane.dequeue`（计数器，属性：`openclaw.lane`） -- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 - `openclaw.channel=heartbeat`） +- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 `openclaw.channel=heartbeat`） - `openclaw.queue.wait_ms`（直方图，属性：`openclaw.lane`） - `openclaw.session.state`（计数器，属性：`openclaw.state`、`openclaw.reason`） - `openclaw.session.stuck`（计数器，属性：`openclaw.state`） - `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`） - `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`） -Exec： +执行： -- `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、 - `openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） +- `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） 诊断内部机制（内存 + 工具循环）： - `openclaw.memory.heap_used_bytes`（直方图，属性：`openclaw.memory.kind`） - `openclaw.memory.rss_bytes`（直方图） - `openclaw.memory.pressure`（计数器，属性：`openclaw.memory.level`） -- `openclaw.tool.loop.iterations`（计数器，属性：`openclaw.toolName`、 - `openclaw.outcome`） -- `openclaw.tool.loop.duration_ms`（直方图，属性：`openclaw.toolName`、 - `openclaw.outcome`） +- `openclaw.tool.loop.iterations`（计数器，属性：`openclaw.toolName`、`openclaw.outcome`） +- `openclaw.tool.loop.duration_ms`（直方图，属性：`openclaw.toolName`、`openclaw.outcome`） -### 已导出 span（名称 + 关键属性） +### 已导出的 span（名称 + 关键属性） - `openclaw.model.usage` - `openclaw.channel`、`openclaw.provider`、`openclaw.model` - - `openclaw.tokens.*`（input / output / cache_read / cache_write / total） + - `openclaw.tokens.*`（input/output/cache_read/cache_write/total） + - 默认使用 `gen_ai.system`，或者在启用最新 GenAI semantic conventions 时使用 `gen_ai.provider.name` + - `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*` - `openclaw.run` - - `openclaw.outcome`、`openclaw.channel`、`openclaw.provider`、 - `openclaw.model`、`openclaw.errorCategory` + - `openclaw.outcome`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.errorCategory` - `openclaw.model.call` - - `gen_ai.system`、`gen_ai.request.model`、`gen_ai.operation.name`、 - `openclaw.provider`、`openclaw.model`、`openclaw.api`、 - `openclaw.transport`、`openclaw.provider.request_id_hash`（上游提供商请求 id 的有界 SHA 哈希；不会导出原始 id） + - 默认使用 `gen_ai.system`，或者在启用最新 GenAI semantic conventions 时使用 `gen_ai.provider.name` + - `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`、`openclaw.provider.request_id_hash`（上游提供商请求 ID 的有界、基于 SHA 的哈希；不会导出原始 ID） - `openclaw.tool.execution` - - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、 - `openclaw.tool.params.*` + - `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、`openclaw.tool.params.*` - `openclaw.exec` - - `openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、 - `openclaw.failureKind`、`openclaw.exec.command_length`、 - `openclaw.exec.exit_code`、`openclaw.exec.timed_out` + - `openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`、`openclaw.exec.command_length`、`openclaw.exec.exit_code`、`openclaw.exec.timed_out` - `openclaw.webhook.processed` - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId` - `openclaw.webhook.error` - - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、 - `openclaw.error` + - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、`openclaw.error` - `openclaw.message.processed` - - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、 - `openclaw.messageId`、`openclaw.reason` + - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、`openclaw.messageId`、`openclaw.reason` - `openclaw.message.delivery` - - `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、 - `openclaw.errorCategory`、`openclaw.delivery.result_count` + - `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`、`openclaw.delivery.result_count` - `openclaw.session.stuck` - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`、`openclaw.history.size`、 - `openclaw.context.tokens`、`openclaw.errorCategory`（不包含 prompt、历史、响应或会话键内容） + - `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含 prompt、history、response 或 session-key 内容） - `openclaw.tool.loop` - - `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、 - `openclaw.errorCategory`（不包含循环消息、参数或工具输出） + - `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（不包含循环消息、参数或工具输出） - `openclaw.memory.pressure` - - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、 - `openclaw.memory.rss_bytes` + - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes` -当明确启用内容捕获时，模型 / 工具 span 还可以包含你选择启用的特定内容类别对应的、有界且已脱敏的 `openclaw.content.*` 属性。 +当显式启用内容捕获时，模型 / 工具 span 还可以包含你选择启用的特定内容类别对应的有界、已脱敏 `openclaw.content.*` 属性。 ### 采样 + 刷新 @@ -422,29 +392,26 @@ Exec： ### 协议说明 -- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 - `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。 +- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。 - 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。 -- 如果端点已包含 `/v1/logs`，则会按原样用于日志。 -- `OPENCLAW_OTEL_PRELOADED=1` 会复用外部已注册的 OpenTelemetry SDK - 来处理追踪 / 指标，而不是启动由插件拥有的 NodeSDK。 +- 如果端点已包含 `/v1/logs`，则日志也会按原样使用该端点。 +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` 仅控制 GenAI span provider 属性的形状。读取 `gen_ai.system` 的现有仪表板在迁移完成前可以继续使用默认设置。 +- `OPENCLAW_OTEL_PRELOADED=1` 会复用外部已注册的 OpenTelemetry SDK 来处理追踪 / 指标，而不是启动由插件拥有的 NodeSDK。 - `diagnostics.otel.logs` 会为主日志记录器输出启用 OTLP 日志导出。 ### 日志导出行为 - OTLP 日志使用与写入 `logging.file` 相同的结构化记录。 -- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 - OTLP 日志。 -- 高日志量的安装应优先使用 OTLP 收集器采样 / 过滤。 +- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 OTLP 日志。 +- 高日志量的部署应优先使用 OTLP 收集器采样 / 过滤。 ## 故障排除提示 - **Gateway 网关无法访问？** 先运行 `openclaw doctor`。 -- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在向 - `logging.file` 中的文件路径写入。 -- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace`，然后重试。 +- **日志为空？** 检查 Gateway 网关是否正在运行，并且是否正在向 `logging.file` 中的文件路径写入内容。 +- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。 ## 相关内容 -- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 -- [诊断](/zh-CN/gateway/configuration-reference#diagnostics) — OpenTelemetry 导出和缓存追踪配置 +- [Gateway Logging Internals](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 +- [Diagnostics](/zh-CN/gateway/configuration-reference#diagnostics) — OpenTelemetry 导出和缓存追踪配置 diff --git a/docs/zh-CN/plugins/voice-call.md b/docs/zh-CN/plugins/voice-call.md index 8a1ab592a..ffe48e285 100644 --- a/docs/zh-CN/plugins/voice-call.md +++ b/docs/zh-CN/plugins/voice-call.md @@ -1,29 +1,28 @@ --- read_when: - - 你想从 OpenClaw 发起一个出站语音通话 - - 你正在配置或开发语音通话插件 -summary: 语音通话插件：通过 Twilio/Telnyx/Plivo 进行出站 + 入站通话（插件安装 + 配置 + CLI） -title: 语音通话插件 + - 你想从 OpenClaw 发起一个呼出语音通话 + - 你正在配置或开发 voice-call 插件 +summary: Voice Call 插件：通过 Twilio/Telnyx/Plivo 进行呼出 + 呼入通话（插件安装 + 配置 + CLI） +title: Voice call 插件 x-i18n: - generated_at: "2026-04-25T05:55:57Z" + generated_at: "2026-04-25T19:34:26Z" model: gpt-5.4 provider: openai - source_hash: bb396c6e346590b742c4d0f0e4f9653982da78fc40b9650760ed10d6fcd5710c + source_hash: f6f6cb9346b63751756b8c6744b56486d1856b2d0f3b94082ced42c7435595d6 source_path: plugins/voice-call.md workflow: 15 --- -OpenClaw 的语音通话通过插件实现。支持出站通知以及带入站策略的 -多轮对话。 +通过插件为 OpenClaw 提供语音通话。支持呼出通知，以及带有呼入策略的多轮对话。 当前提供商： - `twilio`（Programmable Voice + Media Streams） - `telnyx`（Call Control v2） - `plivo`（Voice API + XML transfer + GetInput speech） -- `mock`（开发/无网络） +- `mock`（开发环境/无网络） -快速心智模型： +快速理解模型： - 安装插件 - 重启 Gateway 网关 @@ -34,11 +33,11 @@ OpenClaw 的语音通话通过插件实现。支持出站通知以及带入站 Voice Call 插件运行在 **Gateway 网关进程内部**。 -如果你使用远程 Gateway 网关，请在**运行 Gateway 网关的机器**上安装/配置该插件，然后重启 Gateway 网关以加载它。 +如果你使用远程 Gateway 网关，请在**运行 Gateway 网关的机器上**安装/配置该插件，然后重启 Gateway 网关以加载它。 ## 安装 -### 方案 A：从 npm 安装（推荐） +### 选项 A：从 npm 安装（推荐） ```bash openclaw plugins install @openclaw/voice-call @@ -46,7 +45,7 @@ openclaw plugins install @openclaw/voice-call 之后重启 Gateway 网关。 -### 方案 B：从本地文件夹安装（开发，无需复制） +### 选项 B：从本地文件夹安装（开发环境，不复制） ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin @@ -60,6 +59,8 @@ cd "$PLUGIN_SRC" && pnpm install 在 `plugins.entries.voice-call.config` 下设置配置： +如果 `enabled` 为 true，但所选提供商缺少凭证，Gateway 网关启动日志会记录一条 setup-incomplete 警告，列出缺失的键名，并跳过启动运行时。运行 `openclaw voicecall setup` 可以看到相同的就绪详情。命令、RPC 调用和智能体工具在使用时仍会返回确切缺失的提供商配置。 + ```json5 { plugins: { @@ -68,7 +69,7 @@ cd "$PLUGIN_SRC" && pnpm install enabled: true, config: { provider: "twilio", // 或 "telnyx" | "plivo" | "mock" - fromNumber: "+15550001234", // 或 Twilio 的 TWILIO_FROM_NUMBER + fromNumber: "+15550001234", // 或者 Twilio 的 TWILIO_FROM_NUMBER toNumber: "+15550005678", twilio: { @@ -95,13 +96,13 @@ cd "$PLUGIN_SRC" && pnpm install path: "/voice/webhook", }, - // Webhook 安全性（推荐用于隧道/代理） + // Webhook 安全性（建议用于隧道/代理） webhookSecurity: { allowedHosts: ["voice.example.com"], trustedProxyIPs: ["100.64.0.1"], }, - // 公开暴露方式（选择一种） + // 对外公开方式（选择一种） // publicUrl: "https://example.ngrok.app/voice/webhook", // tunnel: { provider: "ngrok" }, // tailscale: { mode: "funnel", path: "/voice/webhook" } @@ -112,7 +113,7 @@ cd "$PLUGIN_SRC" && pnpm install streaming: { enabled: true, - provider: "openai", // 可选；未设置时使用第一个已注册的实时转写提供商 + provider: "openai", // 可选；未设置时使用第一个已注册的实时转录提供商 streamPath: "/voice/stream", providers: { openai: { @@ -152,25 +153,18 @@ cd "$PLUGIN_SRC" && pnpm install openclaw voicecall setup ``` -默认输出在聊天日志和终端会话中都易于阅读。它会检查 -插件是否已启用、提供商和凭证是否存在、webhook -暴露是否已配置，以及是否只启用了一个音频模式。脚本请使用 -`openclaw voicecall setup --json`。 +默认输出便于在聊天日志和终端会话中阅读。它会检查插件是否启用、提供商和凭证是否存在、webhook 暴露是否已配置，以及是否只有一种音频模式处于启用状态。脚本请使用 `openclaw voicecall setup --json`。 -对于 Twilio、Telnyx 和 Plivo，设置必须能解析为公开可访问的 webhook URL。如果 -已配置的 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退地址解析为 -loopback 或私有网络空间，设置会失败，而不是启动一个无法接收真实运营商 webhook 的 -提供商。 +对于 Twilio、Telnyx 和 Plivo，设置必须解析为一个公开可访问的 webhook URL。如果已配置的 `publicUrl`、隧道 URL、Tailscale URL 或 serve 回退地址解析到 loopback 或私有网络地址空间，那么设置会失败，而不是启动一个无法接收真实运营商 webhook 的提供商。 -如需进行一次无意外的冒烟测试，请运行： +若要进行一个尽量不出意外的冒烟测试，请运行： ```bash openclaw voicecall smoke openclaw voicecall smoke --to "+15555550123" ``` -第二个命令仍然是演练模式。添加 `--yes` 以发起一次简短的出站 -通知呼叫： +第二个命令仍然是一次 dry run。添加 `--yes` 可发起一个简短的呼出通知通话： ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -180,57 +174,44 @@ openclaw voicecall smoke --to "+15555550123" --yes - Twilio/Telnyx 需要一个**可公开访问**的 webhook URL。 - Plivo 需要一个**可公开访问**的 webhook URL。 -- `mock` 是本地开发提供商（不发起网络调用）。 -- 如果旧配置仍使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键，请运行 `openclaw doctor --fix` 进行重写。 -- Telnyx 要求设置 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。 +- `mock` 是一个本地开发提供商（不发起网络调用）。 +- 如果旧配置仍在使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键，请运行 `openclaw doctor --fix` 进行重写。 +- Telnyx 需要 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`），除非 `skipSignatureVerification` 为 true。 - `skipSignatureVerification` 仅用于本地测试。 -- 如果你使用 ngrok 免费层，请将 `publicUrl` 设置为精确的 ngrok URL；签名验证始终会强制执行。 -- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，允许带无效签名的 Twilio webhook。仅用于本地开发。 -- Ngrok 免费层 URL 可能会变化或添加中间页行为；如果 `publicUrl` 漂移，Twilio 签名将会失败。生产环境中，优先使用稳定域名或 Tailscale funnel。 -- `realtime.enabled` 会启动完整的语音到语音对话；不要与 `streaming.enabled` 同时启用。 -- 分块流式传输安全默认值： - - `streaming.preStartTimeoutMs` 会关闭那些始终未发送有效 `start` 帧的 socket。 +- 如果你使用 ngrok 免费套餐，请将 `publicUrl` 设置为精确的 ngrok URL；签名验证始终会强制执行。 +- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，允许 Twilio webhook 使用无效签名。仅用于本地开发。 +- Ngrok 免费套餐 URL 可能变化，或添加中间跳转行为；如果 `publicUrl` 漂移，Twilio 签名校验将失败。生产环境建议优先使用稳定域名或 Tailscale funnel。 +- `realtime.enabled` 会启动完整的语音到语音实时对话；不要与 `streaming.enabled` 同时启用。 +- 流式传输安全默认值： + - `streaming.preStartTimeoutMs` 会关闭那些从未发送有效 `start` 帧的 socket。 - `streaming.maxPendingConnections` 限制未认证、启动前 socket 的总数。 - `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证、启动前 socket 数量。 -- `streaming.maxConnections` 限制打开的媒体流 socket 总数（待启动 + 活动）。 -- 运行时回退目前仍接受这些旧的 voice-call 键，但重写路径是 `openclaw doctor --fix`，兼容垫片只是临时的。 +- `streaming.maxConnections` 限制所有已打开媒体流 socket 的总数（待启动 + 活跃）。 +- 运行时回退目前仍接受这些旧的 voice-call 键，但重写路径是 `openclaw doctor --fix`，兼容垫片只是临时方案。 ## 实时语音对话 `realtime` 为实时通话音频选择一个全双工实时语音提供商。 -它与 `streaming` 分开，后者仅将音频转发给实时 -转写提供商。 +它与 `streaming` 分开，后者只会将音频转发给实时转录提供商。 当前运行时行为： -- `realtime.enabled` 支持用于 Twilio Media Streams。 +- `realtime.enabled` 支持 Twilio Media Streams。 - `realtime.enabled` 不能与 `streaming.enabled` 组合使用。 -- `realtime.provider` 是可选的。若未设置，Voice Call 会使用第一个 - 已注册的实时语音提供商。 -- 内置的实时语音提供商包括 Google Gemini Live（`google`）和 - OpenAI（`openai`），由各自的 provider 插件注册。 +- `realtime.provider` 是可选的。未设置时，Voice Call 会使用第一个已注册的实时语音提供商。 +- 内置的实时语音提供商包括 Google Gemini Live（`google`）和 OpenAI（`openai`），由其各自的提供商插件注册。 - 提供商自有的原始配置位于 `realtime.providers.` 下。 -- Voice Call 默认暴露共享的 `openclaw_agent_consult` 实时工具。 - 当来电者请求更深层次的推理、最新信息或普通 OpenClaw 工具时，实时模型可以调用它。 +- Voice Call 默认会公开共享的 `openclaw_agent_consult` 实时工具。当来电者请求更深入的推理、当前信息或普通 OpenClaw 工具时，实时模型可以调用它。 - `realtime.toolPolicy` 控制 consult 运行： - - `safe-read-only`：暴露 consult 工具，并将常规智能体限制为 - `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 - `memory_get`。 - - `owner`：暴露 consult 工具，并让常规智能体使用正常的 - 智能体工具策略。 - - `none`：不暴露 consult 工具。自定义 `realtime.tools` 仍会 - 透传给实时提供商。 -- Consult 会话键会在可用时复用现有语音会话，然后 - 回退到来电方/被叫方电话号码，以便后续 consult 调用在通话期间保持 - 上下文。 -- 如果 `realtime.provider` 指向未注册的提供商，或者根本没有注册任何实时 - 语音提供商，Voice Call 会记录警告并跳过 - 实时媒体，而不是让整个插件失败。 + - `safe-read-only`：公开 consult 工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 + - `owner`：公开 consult 工具，并允许常规智能体使用正常的智能体工具策略。 + - `none`：不公开 consult 工具。自定义 `realtime.tools` 仍会继续传递给实时提供商。 +- Consult 会话键在可用时会复用现有语音会话；否则回退到主叫/被叫电话号码，以便后续 consult 调用在通话期间保持上下文。 +- 如果 `realtime.provider` 指向一个未注册的提供商，或者根本没有注册任何实时语音提供商，Voice Call 会记录警告并跳过实时媒体，而不是让整个插件失败。 Google Gemini Live 实时默认值： -- API 密钥：`realtime.providers.google.apiKey`、`GEMINI_API_KEY` 或 - `GOOGLE_GENERATIVE_AI_API_KEY` +- API 密钥：`realtime.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_GENERATIVE_AI_API_KEY` - 模型：`gemini-2.5-flash-native-audio-preview-12-2025` - 声音：`Kore` @@ -248,7 +229,7 @@ Google Gemini Live 实时默认值： realtime: { enabled: true, provider: "google", - instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.", + instructions: "简短回答。在使用更深层工具之前先调用 openclaw_agent_consult。", toolPolicy: "safe-read-only", providers: { google: { @@ -289,35 +270,31 @@ Google Gemini Live 实时默认值： } ``` -有关提供商特定的实时语音选项，请参见 [Google provider](/zh-CN/providers/google) 和 [OpenAI provider](/zh-CN/providers/openai)。 +参见 [Google provider](/zh-CN/providers/google) 和 [OpenAI provider](/zh-CN/providers/openai) +了解提供商特定的实时语音选项。 -## 实时分块流式转写 +## 流式转录 -`streaming` 为实时通话音频选择一个实时转写提供商。 +`streaming` 为实时通话音频选择一个实时转录提供商。 当前运行时行为： -- `streaming.provider` 是可选的。若未设置，Voice Call 会使用第一个 - 已注册的实时转写提供商。 -- 内置的实时转写提供商包括 Deepgram（`deepgram`）、 - ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI - （`xai`），由各自的 provider 插件注册。 +- `streaming.provider` 是可选的。未设置时，Voice Call 会使用第一个已注册的实时转录提供商。 +- 内置的实时转录提供商包括 Deepgram（`deepgram`）、ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI（`xai`），由其各自的提供商插件注册。 - 提供商自有的原始配置位于 `streaming.providers.` 下。 -- 如果 `streaming.provider` 指向未注册的提供商，或根本没有注册任何实时 - 转写提供商，Voice Call 会记录警告，并 - 跳过媒体流，而不是让整个插件失败。 +- 如果 `streaming.provider` 指向一个未注册的提供商，或者根本没有注册任何实时转录提供商，Voice Call 会记录警告并跳过媒体流式传输，而不是让整个插件失败。 -OpenAI 分块流式转写默认值： +OpenAI 流式转录默认值： - API 密钥：`streaming.providers.openai.apiKey` 或 `OPENAI_API_KEY` - 模型：`gpt-4o-transcribe` - `silenceDurationMs`：`800` - `vadThreshold`：`0.5` -xAI 分块流式转写默认值： +xAI 流式转录默认值： - API 密钥：`streaming.providers.xai.apiKey` 或 `XAI_API_KEY` -- 端点：`wss://api.x.ai/v1/stt` +- endpoint：`wss://api.x.ai/v1/stt` - `encoding`：`mulaw` - `sampleRate`：`8000` - `endpointingMs`：`800` @@ -378,7 +355,7 @@ xAI 分块流式转写默认值： } ``` -旧键仍会被 `openclaw doctor --fix` 自动迁移： +旧版键仍可由 `openclaw doctor --fix` 自动迁移： - `streaming.sttProvider` → `streaming.provider` - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey` @@ -386,16 +363,16 @@ xAI 分块流式转写默认值： - `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs` - `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold` -## 陈旧通话清理器 +## 过期通话回收器 使用 `staleCallReaperSeconds` 结束那些从未收到终态 webhook 的通话 -（例如始终未完成的 notify 模式通话）。默认值为 `0` +（例如，始终未完成的 notify 模式通话）。默认值为 `0` （禁用）。 -推荐范围： +建议范围： - **生产环境：** 对于 notify 风格流程，使用 `120`–`300` 秒。 -- 将此值保持为**高于 `maxDurationSeconds`**，以便正常通话能够 +- 保持该值**高于 `maxDurationSeconds`**，这样正常通话才能 完成。一个不错的起始值是 `maxDurationSeconds + 30–60` 秒。 示例： @@ -417,26 +394,28 @@ xAI 分块流式转写默认值： ## Webhook 安全性 -当 Gateway 网关前面有代理或隧道时，插件会重建 -用于签名验证的公开 URL。这些选项控制哪些转发 -标头会被信任。 +当 Gateway 网关前方有代理或隧道时，插件会重建 +用于签名验证的公开 URL。这些选项控制应信任哪些转发 +请求头。 -`webhookSecurity.allowedHosts` 会将转发标头中的主机加入允许名单。 +`webhookSecurity.allowedHosts` 会对来自转发请求头的主机进行 allowlist。 -`webhookSecurity.trustForwardingHeaders` 会在没有允许名单的情况下信任转发标头。 +`webhookSecurity.trustForwardingHeaders` 会在没有 allowlist 的情况下信任转发请求头。 -仅当请求远程 IP 与列表匹配时，`webhookSecurity.trustedProxyIPs` 才会信任转发标头。 +`webhookSecurity.trustedProxyIPs` 仅在请求的 +远程 IP 与列表匹配时信任转发请求头。 -Twilio 和 Plivo 启用了 webhook 重放保护。被重放的有效 webhook -请求会被确认，但不会执行副作用。 +Twilio 和 Plivo 启用了 webhook 重放保护。被重放但签名有效的 webhook +请求会被确认接收，但会跳过副作用处理。 -Twilio 对话轮次在 `` 回调中包含每轮令牌，因此 -陈旧/重放的语音回调无法满足较新的待处理转录轮次。 +Twilio 对话轮次在 `` 回调中包含每轮唯一的 token，因此 +过期/重放的语音回调不能满足较新的待处理转录轮次。 -如果缺少提供商要求的签名标头，未认证的 webhook 请求会在读取请求体之前被拒绝。 +当提供商要求的签名请求头缺失时，未认证的 webhook 请求 +会在读取请求体之前被拒绝。 -voice-call webhook 使用共享的预认证请求体配置（64 KB / 5 秒）， -并在签名验证前对每个 IP 设置进行中的请求数量上限。 +voice-call webhook 使用共享的预认证请求体配置文件（64 KB / 5 秒）， +并且在签名验证前对每个 IP 的进行中请求数进行限制。 使用稳定公开主机的示例： @@ -457,11 +436,11 @@ voice-call webhook 使用共享的预认证请求体配置（64 KB / 5 秒）， } ``` -## 用于通话的 TTS +## 通话的 TTS -Voice Call 对通话中的 -流式语音使用核心 `messages.tts` 配置。你可以在插件配置下使用 -**相同结构**进行覆盖——它会与 `messages.tts` 进行深度合并。 +Voice Call 会使用核心 `messages.tts` 配置来处理 +通话中的流式语音。你可以在插件配置下使用**相同的结构** +覆盖它——它会与 `messages.tts` 进行深度合并。 ```json5 { @@ -479,13 +458,13 @@ Voice Call 对通话中的 说明： -- 插件配置中的旧版 `tts.` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会由 `openclaw doctor --fix` 修复；已提交的配置应使用 `tts.providers.`。 -- **Microsoft speech 会被语音通话忽略**（电话音频需要 PCM；当前 Microsoft 传输不暴露电话 PCM 输出）。 -- 当启用 Twilio 媒体流时，会使用核心 TTS；否则通话会回退到提供商原生语音。 -- 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML ``。在这种状态下，如果电话 TTS 不可用，播放请求会失败，而不是混用两条播放路径。 -- 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条包含提供商链（`from`、`to`、`attempts`）的警告，便于调试。 -- 当 Twilio 插话或流拆除清除待处理 TTS 队列时，排队中的 - 播放请求会正常结束，而不会让等待播放完成的来电者一直挂起。 +- 插件配置中旧版的 `tts.` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）可由 `openclaw doctor --fix` 修复；已提交的配置应使用 `tts.providers.`。 +- **Microsoft speech 会被语音通话忽略**（电话音频需要 PCM；当前的 Microsoft 传输不公开电话用 PCM 输出）。 +- 启用 Twilio 媒体流时会使用核心 TTS；否则通话会回退到提供商原生语音。 +- 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML ``。如果此状态下电话 TTS 不可用，播放请求会失败，而不是混用两种播放路径。 +- 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条带有提供商链（`from`、`to`、`attempts`）的警告，便于调试。 +- 当 Twilio 的 barge-in 或流关闭清空待处理 TTS 队列时，已排队的 + 播放请求会结束，而不会让等待播放完成的来电者一直挂起。 ### 更多示例 @@ -504,7 +483,7 @@ Voice Call 对通话中的 } ``` -仅为通话覆盖为 ElevenLabs（其他地方保持核心默认值）： +仅对通话覆盖为 ElevenLabs（其他地方保留核心默认值）： ```json5 { @@ -529,7 +508,7 @@ Voice Call 对通话中的 } ``` -仅为通话覆盖 OpenAI 模型（深度合并示例）： +仅覆盖通话的 OpenAI 模型（深度合并示例）： ```json5 { @@ -552,23 +531,23 @@ Voice Call 对通话中的 } ``` -## 入站通话 +## 呼入通话 -入站策略默认是 `disabled`。要启用入站通话，请设置： +呼入策略默认是 `disabled`。若要启用呼入通话，请设置： ```json5 { inboundPolicy: "allowlist", allowFrom: ["+15550001234"], - inboundGreeting: "Hello! How can I help?", + inboundGreeting: "你好！有什么可以帮你？", } ``` -`inboundPolicy: "allowlist"` 是一种低保障的来电显示筛选机制。插件 -会对提供商提供的 `From` 值进行标准化，并将其与 `allowFrom` 进行比较。 -webhook 验证可以认证提供商投递和负载完整性，但 -不能证明 PSTN/VoIP 来电号码的所有权。请将 `allowFrom` 视为 -来电显示过滤，而不是强来电者身份验证。 +`inboundPolicy: "allowlist"` 是一种低保证级别的主叫号码筛选机制。插件 +会将提供商给出的 `From` 值标准化，并与 `allowFrom` 进行比较。 +Webhook 验证可以认证提供商投递和载荷完整性，但 +无法证明 PSTN/VoIP 主叫号码的归属权。请将 `allowFrom` 视为 +主叫号码过滤，而不是强主叫身份认证。 自动响应使用智能体系统。可通过以下项进行调优： @@ -578,44 +557,44 @@ webhook 验证可以认证提供商投递和负载完整性，但 ### 语音输出约定 -对于自动响应，Voice Call 会向系统提示词追加一个严格的语音输出约定： +对于自动响应，Voice Call 会在系统提示词后附加一个严格的语音输出约定： - `{"spoken":"..."}` -随后 Voice Call 会以防御性方式提取语音文本： +随后 Voice Call 会以防御式方式提取语音文本： -- 忽略被标记为推理/错误内容的负载。 -- 解析直接 JSON、带围栏的 JSON 或内联 `"spoken"` 键。 -- 回退到纯文本，并移除可能属于规划/元信息的开头段落。 +- 忽略标记为推理/错误内容的载荷。 +- 解析直接 JSON、带围栏的 JSON，或内联的 `"spoken"` 键。 +- 回退到纯文本，并移除看起来像规划/元信息前导段落的内容。 这样可以让语音播放聚焦于面向来电者的文本，并避免将规划文本泄露到音频中。 ### 对话启动行为 -对于出站 `conversation` 通话，首条消息处理与实时播放状态绑定： +对于呼出的 `conversation` 通话，首条消息处理与实时播放状态绑定： -- 只有在初始问候语正在实际播放时，才会抑制插话队列清理和自动响应。 -- 如果初始播放失败，通话会回到 `listening`，初始消息仍保留在队列中以供重试。 -- Twilio 流式传输的初始播放会在流连接时启动，无需额外延迟。 -- 插话会中止当前播放，并清除那些已排队但尚未开始播放的 Twilio - TTS 条目。被清除的条目会以已跳过状态结束，因此后续响应逻辑 - 可以继续，而不必等待那些永远不会播放的音频。 -- 实时语音对话使用实时流自己的开场轮次。Voice Call 不会为该初始消息发送旧版 `` TwiML 更新，因此出站 `` 会话会保持连接。 +- 只有在初始问候语正在主动播报时，才会抑制 barge-in 队列清空和自动响应。 +- 如果初始播放失败，通话会返回 `listening`，并且初始消息会保留在队列中等待重试。 +- Twilio 流式传输的初始播放会在流连接建立后立即开始，不会额外延迟。 +- Barge-in 会中止当前播放，并清空 Twilio 中已排队但尚未开始播放的 + TTS 条目。被清空的条目会以 skipped 状态结束，因此后续响应逻辑 + 可以继续，而无需等待那些永远不会播放的音频。 +- 实时语音对话使用实时流自身的开场轮次。Voice Call 不会为该初始消息发布旧版 `` TwiML 更新，因此呼出的 `` 会话会保持附着状态。 ### Twilio 流断开宽限期 -当 Twilio 媒体流断开时，Voice Call 会等待 `2000ms`，然后才自动结束通话： +当 Twilio 媒体流断开时，Voice Call 会等待 `2000ms`，然后再自动结束通话： -- 如果流在该时间窗口内重新连接，则会取消自动结束。 -- 如果宽限期后仍未重新注册流，则会结束该通话，以防出现卡住的活动通话。 +- 如果流在这段时间内重新连接，则会取消自动结束。 +- 如果宽限期过后仍未重新注册任何流，则会结束通话，以防活跃通话卡住。 ## CLI ```bash openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw" openclaw voicecall start --to "+15555550123" # call 的别名 -openclaw voicecall continue --call-id --message "Any questions?" -openclaw voicecall speak --call-id --message "One moment" +openclaw voicecall continue --call-id --message "还有什么问题吗？" +openclaw voicecall speak --call-id --message "请稍等" openclaw voicecall dtmf --call-id --digits "ww123456#" openclaw voicecall end --call-id openclaw voicecall status --call-id @@ -625,24 +604,24 @@ openclaw voicecall expose --mode funnel ``` `latency` 会从默认的 voice-call 存储路径读取 `calls.jsonl`。使用 -`--file ` 指向其他日志，并使用 `--last ` 将分析限制 -为最后 N 条记录（默认 200）。输出包括轮次 -延迟和监听等待时间的 p50/p90/p99。 +`--file ` 指向其他日志文件，使用 `--last ` 将分析范围限制为 +最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 +p50/p90/p99。 ## 智能体工具 工具名称：`voice_call` -动作： +操作： -- `initiate_call`（message、to?、mode?） -- `continue_call`（callId、message） -- `speak_to_user`（callId、message） -- `send_dtmf`（callId、digits） +- `initiate_call`（message，to?，mode?） +- `continue_call`（callId，message） +- `speak_to_user`（callId，message） +- `send_dtmf`（callId，digits） - `end_call`（callId） - `get_status`（callId） -此仓库在 `skills/voice-call/SKILL.md` 中附带了匹配的 Skills 文档。 +此仓库附带了对应的 Skills 文档：`skills/voice-call/SKILL.md`。 ## Gateway 网关 RPC @@ -655,6 +634,6 @@ openclaw voicecall expose --mode funnel ## 相关内容 -- [文本转语音](/zh-CN/tools/tts) -- [Talk 模式](/zh-CN/nodes/talk) -- [语音唤醒](/zh-CN/nodes/voicewake) +- [Text-to-speech](/zh-CN/tools/tts) +- [Talk mode](/zh-CN/nodes/talk) +- [Voice wake](/zh-CN/nodes/voicewake) diff --git a/docs/zh-CN/providers/fal.md b/docs/zh-CN/providers/fal.md index 702be18ca..150951d0c 100644 --- a/docs/zh-CN/providers/fal.md +++ b/docs/zh-CN/providers/fal.md @@ -1,31 +1,31 @@ --- read_when: - - 你想在 OpenClaw 中使用 fal 图像生成】【。assistant to=functions.read-commentary 彩神争霸官方下载 there's no need. - - 你需要 `FAL_KEY` 认证流程 - - 你想为 `image_generate` 或 `video_generate` 使用 fal 默认值 -summary: 在 OpenClaw 中设置 fal 图像与视频生成 + - 你想在 OpenClaw 中使用 fal 图像生成功能 + - 你需要使用 `FAL_KEY` 认证流程 + - 你想为 `image_generate` 或 `video_generate` 使用 fal 默认设置 +summary: 在 OpenClaw 中设置 fal 图像和视频生成功能 title: Fal x-i18n: - generated_at: "2026-04-24T03:43:00Z" + generated_at: "2026-04-25T19:34:33Z" model: gpt-5.4 provider: openai - source_hash: d23d2d0d27e5f60f9dacb4a6a7e4c07248cf45ccd80bfabaf6bb99f5f78946b2 + source_hash: 26f28ff7c99dbe386fd2a42f8f85ae8bc34a1510decd302462ab9c8a4a8428ba source_path: providers/fal.md workflow: 15 --- -OpenClaw 附带一个内置 `fal` 提供商，用于托管图像和视频生成。 +OpenClaw 内置了一个 `fal` provider，用于托管式图像和视频生成。 | 属性 | 值 | | -------- | ------------------------------------------------------------- | -| 提供商 | `fal` | -| 认证 | `FAL_KEY`（标准写法；`FAL_API_KEY` 也可作为回退） | -| API | fal 模型端点 | +| 提供商 | `fal` | +| 认证 | `FAL_KEY`（规范用法；`FAL_API_KEY` 也可作为回退方案） | +| API | fal 模型端点 | ## 入门指南 - + ```bash openclaw onboard --auth-choice fal-api-key ``` @@ -47,21 +47,25 @@ OpenClaw 附带一个内置 `fal` 提供商，用于托管图像和视频生成 ## 图像生成 -内置 `fal` 图像生成提供商默认使用 +内置的 `fal` 图像生成提供商默认使用 `fal/fal-ai/flux/dev`。 -| 能力 | 值 | +| 能力 | 值 | | -------------- | -------------------------- | -| 最大图像数 | 每次请求 4 张 | -| 编辑模式 | 已启用，支持 1 张参考图像 | -| 尺寸覆盖 | 支持 | -| 宽高比 | 支持 | -| 分辨率 | 支持 | +| 最大图像数量 | 每次请求 4 张 | +| 编辑模式 | 已启用，1 张参考图像 | +| 尺寸覆盖 | 支持 | +| 宽高比 | 支持 | +| 分辨率 | 支持 | +| 输出格式 | `png` 或 `jpeg` | fal 图像编辑端点**不**支持 `aspectRatio` 覆盖。 +当你想输出 PNG 时，请使用 `outputFormat: "png"`。fal 在 OpenClaw 中未声明显式的透明背景控制，因此 `background: +"transparent"` 会被报告为 fal 模型的已忽略覆盖项。 + 要将 fal 用作默认图像提供商： ```json5 @@ -78,17 +82,17 @@ fal 图像编辑端点**不**支持 `aspectRatio` 覆盖。 ## 视频生成 -内置 `fal` 视频生成提供商默认使用 +内置的 `fal` 视频生成提供商默认使用 `fal/fal-ai/minimax/video-01-live`。 -| 能力 | 值 | +| 能力 | 值 | | ---------- | ------------------------------------------------------------ | -| 模式 | 文本转视频、单图参考 | -| 运行时 | 基于队列的提交/状态/结果流程，适用于长时间运行的任务 | +| 模式 | 文生视频、单图参考 | +| 运行时 | 基于队列的 submit/status/result 流程，用于长时间运行的任务 | - **HeyGen video-agent：** + **HeyGen 视频智能体：** - `fal/fal-ai/heygen/v2/video-agent` @@ -131,7 +135,7 @@ fal 图像编辑端点**不**支持 `aspectRatio` 覆盖。 -使用 `openclaw models list --provider fal` 查看完整的可用 fal +使用 `openclaw models list --provider fal` 可查看完整的可用 fal 模型列表，包括最近新增的条目。 @@ -139,12 +143,12 @@ fal 图像编辑端点**不**支持 `aspectRatio` 覆盖。 - 共享的图像工具参数与提供商选择。 + 共享的图像工具参数和提供商选择。 - 共享的视频工具参数与提供商选择。 + 共享的视频工具参数和提供商选择。 - 包括图像和视频模型选择在内的智能体默认值。 + 智能体默认设置，包括图像和视频模型选择。 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index c1694769c..16a88bd99 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -3,64 +3,73 @@ read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - 你想使用 Codex 订阅认证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅 +summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-25T19:10:45Z" + generated_at: "2026-04-25T19:34:28Z" model: gpt-5.4 provider: openai - source_hash: 640db14eaeec4197a44b8447df545ea34fba18cafede35fd12a3a3f78fff669e + source_hash: ce19da678fa54080277e30d9adebfee8936f05b4ca94aa8d17e2c674eefba970 source_path: providers/openai.md workflow: 15 --- OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列路由。模型前缀决定所使用的路由： -- **API 密钥** —— 通过按使用量计费的方式直接访问 OpenAI Platform（`openai/*` 模型） -- **通过 PI 使用 Codex 订阅** —— 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） -- **Codex app-server harness** —— 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`） +- **API 密钥** — 通过直接访问 OpenAI Platform 并按使用量计费（`openai/*` 模型） +- **通过 Pi 使用 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） +- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`） -OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用基于订阅的 OAuth。 +OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用基于订阅的 OAuth。 -提供商、模型、运行时和渠道是彼此独立的层。如果你把这些标签混淆了，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再修改配置。 +提供商、模型、运行时和渠道是彼此独立的层。如果这些标签 +让你感到混淆，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，然后再 +修改配置。 ## 快速选择 | 目标 | 使用方式 | 说明 | | --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | -| 直接使用 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 | -| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。是订阅配置的最佳首选。 | -| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `embeddedHarness.runtime: "codex"` | 为该模型引用强制启用 Codex app-server harness。 | +| 直接按 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 | +| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 Pi 路由。对于订阅配置，这是最佳的首选方案。 | +| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `embeddedHarness.runtime: "codex"` | 为该模型引用强制使用 Codex app-server harness。 | | 图像生成或编辑 | `openai/gpt-image-2` | 可搭配 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 | | 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 | -GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 / OAuth 路由。对于直接 `OPENAI_API_KEY` 流量，请使用 `openai/gpt-5.5`；对于通过 PI 的 Codex OAuth，请使用 `openai-codex/gpt-5.5`；若要使用原生 Codex app-server harness，请使用 `openai/gpt-5.5` 并设置 `embeddedHarness.runtime: "codex"`。 +GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问和 +订阅 / OAuth 路由使用。对直接 `OPENAI_API_KEY` +流量使用 `openai/gpt-5.5`，对通过 Pi 的 Codex OAuth 使用 `openai-codex/gpt-5.5`，或者 +对原生 Codex app-server harness 使用带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.5`。 -启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置的 Codex app-server 插件。只有在你显式选择原生 Codex harness 并设置 `embeddedHarness.runtime: "codex"`，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。 +启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会 +启用内置的 Codex app-server 插件。只有在你显式选择原生 Codex harness， +即设置 +`embeddedHarness.runtime: "codex"`，或使用旧版 `codex/*` 模型引用时， +OpenClaw 才会启用该插件。 -## OpenClaw 功能支持范围 +## OpenClaw 功能覆盖范围 -| OpenAI 能力 | OpenClaw 对应功能面 | Status | +| OpenAI 能力 | OpenClaw 表面 | Status | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | | 聊天 / Responses | `openai/` 模型提供商 | 是 | | Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/` | 是 | | Codex app-server harness | 带 `embeddedHarness.runtime: codex` 的 `openai/` | 是 | -| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 | +| 服务端 web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 web 搜索且未固定提供商时 | | 图像 | `image_generate` | 是 | | 视频 | `video_generate` | 是 | | 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | | 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | | 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 | -| 向量嵌入 | memory embedding provider | 是 | +| 嵌入 | memory embedding provider | 是 | ## 入门指南 -选择你偏好的认证方式，并按照设置步骤进行操作。 +选择你偏好的认证方式，并按照设置步骤操作。 @@ -68,7 +77,7 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 - 在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。 + 在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。 ```bash @@ -81,7 +90,7 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -90,13 +99,16 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 ### 路由摘要 - | Model ref | Route | Auth | + | 模型引用 | 路由 | 认证 | |-----------|-------|------| | `openai/gpt-5.5` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - `openai/*` 默认是直接 OpenAI API 密钥路由，除非你显式强制使用 Codex app-server harness。对于通过默认 PI runner 的 Codex OAuth，请使用 `openai-codex/*`；若要使用原生 Codex app-server 执行，请使用 `openai/gpt-5.5` 并设置 `embeddedHarness.runtime: "codex"`。 + `openai/*` 是直接 OpenAI API 密钥路由，除非你显式强制 + 使用 Codex app-server harness。对通过 + 默认 Pi 运行器的 Codex OAuth 使用 `openai-codex/*`，或使用带有 + `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.5` 进行原生 Codex app-server 执行。 ### 配置示例 @@ -109,13 +121,13 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 ``` - OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也同样不提供它。 + OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也不会公开它。 - **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。 + **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。 @@ -129,7 +141,7 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 openclaw models auth login --provider openai-codex ``` - 对于无头环境或不适合回调的配置，可添加 `--device-code`，以使用 ChatGPT 的设备码流程登录，而不是使用 localhost 浏览器回调： + 对于无头环境或不适合回调的设置，可添加 `--device-code`，改用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调： ```bash openclaw models auth login --provider openai-codex --device-code @@ -140,7 +152,7 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -149,13 +161,15 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 ### 路由摘要 - | Model ref | Route | Auth | + | 模型引用 | 路由 | 认证 | |-----------|-------|------| - | `openai-codex/gpt-5.5` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 | + | `openai-codex/gpt-5.5` | 通过 Pi 的 ChatGPT/Codex OAuth | Codex 登录 | | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server 认证 | - 在认证 / 配置文件命令中继续使用 `openai-codex` provider id。`openai-codex/*` 模型前缀同样是 Codex OAuth 的显式 PI 路由。它不会选择或自动启用内置的 Codex app-server harness。 + 认证 / 配置文件命令仍然使用 `openai-codex` provider id。 + `openai-codex/*` 模型前缀也是用于 Codex OAuth 的显式 Pi 路由。 + 它不会选择或自动启用内置的 Codex app-server harness。 ### 配置示例 @@ -167,23 +181,27 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理生成的凭证。 ### Status 指示器 - 聊天中的 `/status` 会显示当前会话正在使用的模型运行时。默认的 PI harness 显示为 `Runtime: OpenClaw Pi Default`。当选择内置的 Codex app-server harness 时，`/status` 会显示 `Runtime: OpenAI Codex`。现有会话会保留其已记录的 harness id，因此如果你在修改 `embeddedHarness` 后希望 `/status` 反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。 + 聊天中的 `/status` 会显示当前会话正在使用哪个模型运行时。 + 默认的 Pi harness 显示为 `Runtime: OpenClaw Pi Default`。当 + 选择内置的 Codex app-server harness 时，`/status` 会显示 + `Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你在修改 `embeddedHarness` 后希望 `/status` + 反映新的 Pi/Codex 选择，请使用 `/new` 或 `/reset`。 ### 上下文窗口上限 - OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。 + OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。 对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`： - 原生 `contextWindow`：`1000000` - 默认运行时 `contextTokens` 上限：`272000` - 实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： + 这个较小的默认上限在实践中具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它： ```json5 { @@ -203,23 +221,28 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 ### 目录恢复 - 当上游 Codex 目录中存在 `gpt-5.5` 元数据时，OpenClaw 会使用这些元数据。如果实时 Codex 发现结果在账户已认证的情况下遗漏了 `openai-codex/gpt-5.5` 这一行，OpenClaw 会合成这一 OAuth 模型行，以避免 cron、子智能体和已配置默认模型的运行因 `Unknown model` 而失败。 + OpenClaw 会在上游 Codex 目录元数据存在时使用其中的 `gpt-5.5` 信息。 + 如果实时 Codex 发现结果中缺少 `openai-codex/gpt-5.5` 这一行， + 但账户已完成认证，OpenClaw 会合成该 OAuth 模型行，这样 + cron、子智能体以及已配置的默认模型运行就不会因 + `Unknown model` 而失败。 ## 图像生成 -内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 -它同时支持使用 OpenAI API 密钥进行图像生成，以及通过同一个 `openai/gpt-image-2` 模型引用使用 Codex OAuth 进行图像生成。 +内置的 `openai` 插件通过 `image_generate` 工具注册图像生成。 +它同时支持基于 OpenAI API 密钥的图像生成，以及通过同一个 `openai/gpt-image-2` 模型引用进行的 Codex OAuth 图像 +生成。 | 能力 | OpenAI API 密钥 | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | | 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` | | 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 | -| 传输 | OpenAI Images API | Codex Responses 后端 | +| 传输 | OpenAI Images API | Codex Responses backend | | 每次请求的最大图像数 | 4 | 4 | -| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） | +| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） | | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | | 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全时映射到受支持的尺寸 | @@ -234,28 +257,48 @@ GPT-5.5 同时支持直接通过 OpenAI Platform API 密钥访问，以及订阅 ``` -有关通用工具参数、提供商选择和故障切换行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。若要输出透明背景的 PNG/WebP，请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝 `background: "transparent"`。 +`gpt-image-2` 是 OpenAI 文生图生成和图像 +编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为 +显式模型覆盖使用。对透明背景 +PNG/WebP 输出请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝 +`background: "transparent"`。 -对于透明背景请求，智能体应调用 `image_generate`，并使用 `model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及 `openai.background: "transparent"`。OpenClaw 还会通过将默认的 `openai/gpt-image-2` 透明背景请求重写为 `gpt-image-1.5`，来保护公开的 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义的 OpenAI-compatible 端点则会保留其已配置的 deployment / model 名称。 +对于透明背景请求，智能体应调用 `image_generate`，并设置 +`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及 +`background: "transparent"`；较旧的 `openai.background` 提供商选项 +仍然可用。OpenClaw 还会通过将默认的 `openai/gpt-image-2` 透明背景 +请求重写为 `gpt-image-1.5`，来保护公开的 OpenAI 和 +OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点则会保留 +其已配置的 deployment / model 名称。 -同样的设置也适用于无头 CLI 运行： +相同设置也适用于无头 CLI 运行： ```bash openclaw infer image generate \ --model openai/gpt-image-1.5 \ --output-format png \ - --openai-background transparent \ + --background transparent \ --prompt "A simple red circle sticker on a transparent background" \ --json ``` -从输入文件开始时，对 `openclaw infer image edit` 也使用相同的 `--output-format` 和 `--openai-background` 标志。 +当你从输入文件开始时，也可以将相同的 `--output-format` 和 `--background` 标志与 +`openclaw infer image edit` 一起使用。 +`--openai-background` 仍可作为 OpenAI 专用别名使用。 -对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。当配置了 `openai-codex` OAuth 配置文件后，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会在该请求中静默回退到 API 密钥。如果你想改用直接的 OpenAI Images API 路由，请使用 API 密钥、自定义 base URL 或 Azure 端点显式配置 `models.providers.openai`。 -如果该自定义图像端点位于受信任的 LAN / 私有地址上，还需同时设置 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非显式选择加入，否则 OpenClaw 会持续阻止私有 / 内部的 OpenAI-compatible 图像端点。 +对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。当 +已配置 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth +访问令牌，并通过 Codex Responses backend 发送图像请求。它 +不会先尝试 `OPENAI_API_KEY`，也不会在该请求中静默回退到 API 密钥。 +当你希望改为使用直接 OpenAI Images API +路由时，请使用 API 密钥、 +自定义 base URL 或 Azure 端点显式配置 `models.providers.openai`。 +如果该自定义图像端点位于可信 LAN / 私有地址上，还需要设置 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；如果没有这个显式启用项， +OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。 生成： @@ -266,7 +309,7 @@ openclaw infer image generate \ 生成透明 PNG： ``` -/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png openai='{"background":"transparent"}' +/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent ``` 编辑： @@ -277,15 +320,15 @@ openclaw infer image generate \ ## 视频生成 -内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。 +内置的 `openai` 插件通过 `video_generate` 工具注册视频生成。 | 能力 | 值 | | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | -| 模式 | 文本生成视频、图像生成视频、单视频编辑 | -| 参考输入 | 1 张图像或 1 个视频 | +| 模式 | 文生视频、图生视频、单视频编辑 | +| 参考输入 | 1 张图片或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 | +| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并带有工具警告 | ```json5 { @@ -298,20 +341,20 @@ openclaw infer image generate \ ``` -有关通用工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。 ## GPT-5 提示词贡献 -OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较早的 GPT-4.x 模型则不会。 +OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的覆盖层。较旧的 GPT-4.x 模型则不会。 -内置的原生 Codex harness 会通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保持相同的后续跟进和主动心跳指引。 +内置的原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和 heartbeat 覆盖层，因此即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保留相同的持续跟进和主动 heartbeat 指导。 -GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复与静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指引始终启用。友好的交互风格层是独立且可配置的。 +GPT-5 贡献会为角色持续性、执行安全、工具纪律、输出形态、完成检查和验证添加带标签的行为契约。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层则是单独的，并且可配置。 | 值 | 效果 | | ---------------------- | ------------------------------------------- | -| `"friendly"`（默认） | 启用友好的交互风格层 | +| `"friendly"`（默认） | 启用友好交互风格层 | | `"on"` | `"friendly"` 的别名 | | `"off"` | 仅禁用友好风格层 | @@ -341,26 +384,26 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 -当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 +当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。 -## 语音与语音处理 +## 语音与语音识别 - 内置的 `openai` 插件为 `messages.tts` 功能面注册了语音合成功能。 + 内置的 `openai` 插件为 `messages.tts` 表面注册了语音合成。 - | Setting | Config path | Default | + | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 声音 | `messages.tts.providers.openai.voice` | `coral` | + | 音色 | `messages.tts.providers.openai.voice` | `coral` | | 速度 | `messages.tts.providers.openai.speed` | （未设置） | | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | - | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | + | 格式 | `messages.tts.providers.openai.responseFormat` | 语音消息为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -375,20 +418,23 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API 端点。 + 设置 `OPENAI_TTS_BASE_URL` 可以覆盖 TTS 的 base URL，而不会影响聊天 API 端点。 - 内置的 `openai` 插件通过 OpenClaw 的媒体理解转录功能面注册了批量语音转文本。 + 内置的 `openai` 插件通过 + OpenClaw 的媒体理解转写表面注册了批量语音转文本。 - 默认模型：`gpt-4o-transcribe` - 端点：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，只要入站音频转录使用 `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道音频附件 + - 在 OpenClaw 中，凡是入站音频转写使用 + `tools.media.audio` 的地方都受支持，包括 Discord 语音频道片段和渠道 + 音频附件 - 若要强制使用 OpenAI 进行入站音频转录： + 若要强制对入站音频转写使用 OpenAI： ```json5 { @@ -408,14 +454,15 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 } ``` - 当共享音频媒体配置或每次调用的转录请求提供语言和提示词提示时，这些信息会被转发给 OpenAI。 + 当共享音频媒体配置或按次调用的转写请求中提供了语言和提示词提示时， + 它们会被转发给 OpenAI。 - - 内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。 + + 内置的 `openai` 插件为 Voice Call 插件注册了实时转写。 - | Setting | Config path | Default | + | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | 语言 | `...openai.language` | （未设置） | @@ -425,19 +472,19 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用连接到 `wss://api.openai.com/v1/realtime` 的 WebSocket，并使用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前仍记录短片段，并改用批量 `tools.media.audio` 转录路径。 + 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这一流式提供商用于 Voice Call 的实时转写路径；Discord 语音目前仍是录制短片段并改用批量 `tools.media.audio` 转写路径。 - 内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。 + 内置的 `openai` 插件为 Voice Call 插件注册了实时语音。 - | Setting | Config path | Default | + | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 声音 | `...openai.voice` | `alloy` | - | 温度 | `...openai.temperature` | `0.8` | + | 音色 | `...openai.voice` | `alloy` | + | Temperature | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | @@ -451,13 +498,20 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 ## Azure OpenAI 端点 -内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求格式。 +内置的 `openai` 提供商可以通过覆盖 base URL， +将 Azure OpenAI 资源用于图像生成。在图像生成路径上，OpenClaw +会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 +Azure 的请求格式。 -实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不会受到 `models.providers.openai.baseUrl` 的影响。其 Azure 设置请参阅 [语音与语音处理](#voice-and-speech) 下的 **实时语音** 折叠项。 +实时语音使用单独的配置路径 +（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`）， +不会受 `models.providers.openai.baseUrl` 影响。其 Azure +设置请参见 [语音与语音识别](#voice-and-speech) 下 **实时语音** +折叠面板中的说明。 -在以下情况下使用 Azure OpenAI： +以下情况下请使用 Azure OpenAI： - 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 @@ -465,7 +519,9 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 ### 配置 -对于通过内置 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： +若要通过内置的 `openai` 提供商使用 Azure 进行图像生成，请将 +`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 +Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： ```json5 { @@ -480,27 +536,32 @@ GPT-5 贡献会添加一个带标签的行为契约，用于规范 persona 持 } ``` -OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路由： +OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成 +路由： - `*.openai.azure.com` - `*.services.ai.azure.com` - `*.cognitiveservices.azure.com` -对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会： +对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会： -- 发送 `api-key` 标头，而不是 `Authorization: Bearer` -- 使用基于 deployment 的路径（`/openai/deployments/{deployment}/...`） -- 为每个请求追加 `?api-version=...` +- 发送 `api-key` 请求头，而不是 `Authorization: Bearer` +- 使用以 deployment 为作用域的路径（`/openai/deployments/{deployment}/...`） +- 为每个请求附加 `?api-version=...` -其他 base URL（公开 OpenAI、OpenAI-compatible 代理）则继续使用标准 OpenAI 图像请求格式。 +其他 base URL（公共 OpenAI、OpenAI 兼容代理）则会保留标准 +OpenAI 图像请求格式。 -`openai` 提供商图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 `openai.baseUrl` 视为公开 OpenAI 端点，因此会在 Azure 图像 deployment 上失败。 +`openai` 提供商图像生成路径的 Azure 路由要求 +OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 +`openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure +图像 deployment 上会失败。 ### API 版本 -设置 `AZURE_OPENAI_API_VERSION` 以固定 Azure 图像生成路径所使用的特定 Azure 预览版或正式版版本： +设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本： ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" @@ -510,47 +571,62 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ### 模型名称就是 deployment 名称 -Azure OpenAI 将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公开的 OpenAI 模型 id。 +Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段 +必须是你在 Azure 门户中配置的**Azure deployment 名称**，而不是 +公开的 OpenAI 模型 id。 -如果你创建了一个名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 的 deployment： +如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，并由它提供 `gpt-image-2`： ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` -同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 +同样的 deployment 名称规则也适用于通过 +内置 `openai` 提供商路由的图像生成调用。 ### 区域可用性 -Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。 - -在创建 deployment 之前，请先检查 Microsoft 当前的区域列表，并确认你的区域提供该特定模型。 +Azure 图像生成目前仅在部分区域可用 +（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 +`uaenorth`）。在创建 +deployment 之前，请先检查 Microsoft 当前的区域列表，并确认你的区域提供该特定模型。 ### 参数差异 -Azure OpenAI 与公开 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公开 OpenAI 允许的某些选项（例如 `gpt-image-2` 上的某些 `background` 值），或仅在特定模型版本中提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的特定 deployment 和 API 版本所支持的参数集。 +Azure OpenAI 与公开 OpenAI 并不总是接受相同的图像参数。 +Azure 可能会拒绝公开 OpenAI 允许的选项（例如在 `gpt-image-2` 上的某些 +`background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 +OpenClaw。如果 Azure 请求因验证错误而失败，请在 +Azure 门户中检查你的特定 deployment 和 API 版本所支持的参数集。 -Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 —— 请参阅 [高级配置](#advanced-configuration) 下 **原生路由与 OpenAI-compatible 路由** 折叠项。 +Azure OpenAI 使用原生传输和兼容行为，但不会接收 +OpenClaw 的隐藏归因请求头——请参见 [Advanced configuration](#advanced-configuration) 下 +**Native vs OpenAI-compatible routes** +折叠面板中的说明。 -对于 Azure 上的聊天或 Responses 流量（超出图像生成范围），请使用新手引导流程或专用的 Azure provider 配置 —— 单独设置 `openai.baseUrl` 不会自动采用 Azure 的 API / 认证格式。另有一个独立的 `azure-openai-responses/*` provider；请参阅下方的“服务端压缩”折叠项。 +对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用 +新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl` +不会自动采用 Azure 的 API / 认证格式。另有一个单独的 +`azure-openai-responses/*` 提供商；请参见 +下方的服务端压缩折叠面板。 ## 高级配置 - - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先、SSE 回退（`"auto"`）的方式。 + + 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都会优先使用 WebSocket，并在失败时回退到 SSE（`"auto"`）。 在 `"auto"` 模式下，OpenClaw 会： - - 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试 - - 在发生失败后，将 WebSocket 标记为约 60 秒的降级状态，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次标识标头 - - 在不同传输变体之间统一使用量计数器（`input_tokens` / `prompt_tokens`） + - 在回退到 SSE 之前，重试一次早期 WebSocket 失败 + - 在失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次身份请求头 + - 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| - | `"auto"`（默认） | WebSocket 优先，SSE 回退 | + | `"auto"`（默认） | WebSocket 优先，失败时回退到 SSE | | `"sse"` | 强制仅使用 SSE | | `"websocket"` | 强制仅使用 WebSocket | @@ -578,7 +654,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 - OpenClaw 默认对 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。 + OpenClaw 默认会为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。 ```json5 // 禁用预热 @@ -598,12 +674,12 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 - OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了一个共享的快速模式开关： + OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的快速模式开关： - **聊天 / UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先级处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -618,13 +694,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 ``` - 会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。 + 会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为已配置的默认值。 - - OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型进行设置： + + OpenAI 的 API 通过 `service_tier` 提供优先级处理。你可以在 OpenClaw 中按模型设置它： ```json5 { @@ -647,17 +723,17 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 - 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务端压缩： + 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩： - - 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`） + - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） - 这适用于内置 Pi harness 路径，以及嵌入式运行所使用的 OpenAI provider 钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 + 这适用于内置 Pi harness 路径，以及嵌入式运行所使用的 OpenAI 提供商钩子。原生 Codex app-server harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 - 适用于 Azure OpenAI Responses 这类兼容端点： + 对 Azure OpenAI Responses 之类的兼容端点很有用： ```json5 { @@ -709,7 +785,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 - `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。 + `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 @@ -727,35 +803,35 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 } ``` - 使用 `strict-agentic` 时，OpenClaw 会： - - 当有可用工具操作时，不再将“仅做计划”的轮次视为成功推进 - - 使用“立即行动”的引导重试该轮次 - - 对于较大工作量自动启用 `update_plan` - - 如果模型持续规划却不执行，则显式显示阻塞状态 + 在 `strict-agentic` 下，OpenClaw 会： + - 当工具动作可用时，不再将仅有计划的轮次视为成功进展 + - 使用“立即行动”的引导重试该轮 + - 对实质性工作自动启用 `update_plan` + - 如果模型持续只做计划而不执行，则显式显示阻塞状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较早的模型系列仍保持默认行为。 + 仅限于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。 - - OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用 OpenAI-compatible `/v1` 代理采用不同处理方式： + + OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式与通用 OpenAI 兼容 `/v1` 代理不同： **原生路由**（`openai/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对拒绝 `reasoning.effort: "none"` 的模型或代理，省略已禁用的 reasoning + - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用式 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏归因标头 - - 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏归因请求头 + - 保留 OpenAI 专用请求整形（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示） - **代理 / compatible 路由：** + **代理 / 兼容路由：** - 使用更宽松的兼容行为 - - 从非原生 `openai-completions` 负载中移除 Completions `store` - - 接受针对 OpenAI-compatible Completions 代理的高级 `params.extra_body` / `params.extraBody` 透传 JSON - - 不强制严格工具 schema，也不附加原生专用标头 + - 从非原生 `openai-completions` 负载中剥离 Completions `store` + - 接受用于 OpenAI 兼容 Completions 代理的高级 `params.extra_body` / `params.extraBody` 透传 JSON + - 不强制严格工具 schema 或原生专用请求头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。 @@ -764,15 +840,15 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐 - 选择 provider、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。 - 共享图像工具参数和 provider 选择。 + 共享图像工具参数和提供商选择。 - 共享视频工具参数和 provider 选择。 + 共享视频工具参数和提供商选择。 - + 认证细节和凭证复用规则。 diff --git a/docs/zh-CN/reference/token-use.md b/docs/zh-CN/reference/token-use.md index fa31ef73e..43c942eb2 100644 --- a/docs/zh-CN/reference/token-use.md +++ b/docs/zh-CN/reference/token-use.md @@ -1,144 +1,152 @@ --- read_when: - - 解释 token 使用量、成本或上下文窗口 + - 解释令牌用量、成本或上下文窗口 - 调试上下文增长或压缩行为 -summary: OpenClaw 如何构建提示词上下文并报告 token 使用量与成本 -title: Token 使用量和成本 +summary: OpenClaw 如何构建提示上下文并报告令牌用量 + 成本 +title: 令牌用量和成本 x-i18n: - generated_at: "2026-04-24T03:19:04Z" + generated_at: "2026-04-25T19:34:28Z" model: gpt-5.4 provider: openai - source_hash: 4a95e7592a06bd750c0bfc9303d8cec2a538756e95f35c3001dc960cfebcadbf + source_hash: 828b282103902f55d65ce820c17753c2602169eff068bcea36e629759002f28d source_path: reference/token-use.md workflow: 15 --- -# Token 使用量和成本 +# 令牌用量和成本 -OpenClaw 跟踪的是 **token**，而不是字符。token 因模型而异，但大多数 -OpenAI 风格模型对英文文本平均约为每个 token 4 个字符。 +OpenClaw 跟踪的是 **令牌**，而不是字符。令牌因模型而异，但大多数 OpenAI 风格的模型对英文文本的平均换算约为每个令牌 4 个字符。 -## 系统提示词如何构建 +## 系统提示如何构建 -OpenClaw 会在每次运行时组装自己的系统提示词。它包括： +OpenClaw 会在每次运行时组装自己的系统提示。它包括： - 工具列表 + 简短描述 -- Skills 列表（仅元数据；说明会按需通过 `read` 加载）。 +- Skills 列表（仅元数据；说明按需通过 `read` 加载）。 紧凑的 Skills 块受 `skills.limits.maxSkillsPromptChars` 限制， - 并可在每个智能体上通过 - `agents.list[].skillsLimits.maxSkillsPromptChars` 进行覆盖。 -- 自更新说明 -- 工作区 + bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、新建时的 `BOOTSTRAP.md`，以及存在时的 `MEMORY.md`）。根目录下的小写 `memory.md` 不会被注入；它是 `openclaw doctor --fix` 在与 `MEMORY.md` 配对时使用的旧版修复输入。大文件会被 `agents.defaults.bootstrapMaxChars` 截断（默认值：12000），而 bootstrap 注入总量受 `agents.defaults.bootstrapTotalMaxChars` 限制（默认值：60000）。`memory/*.md` 每日文件不是常规 bootstrap 提示词的一部分；在普通回合中它们仍通过 memory 工具按需使用，但纯 `/new` 和 `/reset` 可以在该首回合前置一个一次性的启动上下文块，其中包含最近的每日 memory。该启动前导由 `agents.defaults.startupContext` 控制。 + 并且可按智能体通过 + `agents.list[].skillsLimits.maxSkillsPromptChars` 覆盖。 +- 自我更新说明 +- 工作区 + 引导文件（新的 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`，以及存在时的 `MEMORY.md`）。根目录的小写 `memory.md` 不会被注入；当与 `MEMORY.md` 配对时，它是 `openclaw doctor --fix` 的旧版修复输入。大文件会被 `agents.defaults.bootstrapMaxChars` 截断（默认值：12000），引导注入总量受 `agents.defaults.bootstrapTotalMaxChars` 限制（默认值：60000）。`memory/*.md` 每日文件不属于常规引导提示的一部分；在普通轮次中，它们仍然通过 memory 工具按需访问，但裸 `/new` 和 `/reset` 可以在首次轮次前附加一个一次性的启动上下文块，其中包含最近的每日记忆。该启动前导由 `agents.defaults.startupContext` 控制。 - 时间（UTC + 用户时区） - 回复标签 + heartbeat 行为 -- 运行时元数据（主机/操作系统/模型/thinking） +- 运行时元数据（主机 / OS / 模型 / 思考） -完整分解请参见 [系统提示词](/zh-CN/concepts/system-prompt)。 +完整细分请参见 [System Prompt](/zh-CN/concepts/system-prompt)。 ## 什么会计入上下文窗口 模型接收到的所有内容都会计入上下文限制： -- 系统提示词（上面列出的所有部分） +- 系统提示（上面列出的所有部分） - 对话历史（用户 + 助手消息） - 工具调用和工具结果 -- 附件/转录（图片、音频、文件） +- 附件 / 转录内容（图像、音频、文件） - 压缩摘要和裁剪产物 - 提供商包装层或安全头（不可见，但仍会计入） -某些运行时较重的表面还有各自的显式上限： +一些运行时较重的表面有各自明确的上限： - `agents.defaults.contextLimits.memoryGetMaxChars` - `agents.defaults.contextLimits.memoryGetDefaultLines` - `agents.defaults.contextLimits.toolResultMaxChars` - `agents.defaults.contextLimits.postCompactionMaxChars` -每个智能体的覆盖项位于 `agents.list[].contextLimits` 下。这些旋钮 -用于有界的运行时摘录和由运行时注入的自有块。它们 -与 bootstrap 限制、启动上下文限制和 Skills 提示词 -限制是分开的。 +按智能体的覆盖项位于 `agents.list[].contextLimits` 下。这些旋钮 +用于受限的运行时摘录和由运行时注入的内容块。它们 +与引导限制、启动上下文限制和 Skills 提示限制是分开的。 -对于图片，OpenClaw 会在调用提供商前，对转录/工具图片负载进行缩放。 -使用 `agents.defaults.imageMaxDimensionPx`（默认值：`1200`）来调整此项： +对于图像，OpenClaw 会在调用提供商之前缩小转录 / 工具图像载荷的尺寸。 +使用 `agents.defaults.imageMaxDimensionPx`（默认值：`1200`）来调整： -- 较低的值通常会减少视觉 token 使用量和负载大小。 -- 较高的值会为 OCR/UI 密集型截图保留更多视觉细节。 +- 较低的值通常会减少视觉令牌用量和载荷大小。 +- 较高的值会保留更多视觉细节，适用于 OCR / UI 密集型截图。 -如需查看实际分解（按注入文件、工具、Skills 和系统提示词大小），请使用 `/context list` 或 `/context detail`。参见 [上下文](/zh-CN/concepts/context)。 +如需实际细分（按每个注入文件、工具、Skills 和系统提示大小），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 -## 如何查看当前 token 使用量 +## 如何查看当前令牌用量 -在聊天中使用这些命令： +在聊天中使用以下命令： -- `/status` → **富含 emoji 的状态卡片**，显示会话模型、上下文使用量、 - 上次响应的输入/输出 token，以及**预估成本**（仅 API 密钥）。 -- `/usage off|tokens|full` → 在每条回复后追加一个**按响应计的使用量页脚**。 - - 按会话持久化（存储为 `responseUsage`）。 - - OAuth 认证**隐藏成本**（仅显示 token）。 -- `/usage cost` → 显示 OpenClaw 会话日志中的本地成本摘要。 +- `/status` → **富含表情符号的状态卡片**，显示会话模型、上下文用量、 + 上次响应的输入 / 输出令牌，以及 **估算成本**（仅 API 密钥）。 +- `/usage off|tokens|full` → 为每条回复附加一个 **按响应统计的用量页脚**。 + - 按会话持久保存（存储为 `responseUsage`）。 + - OAuth 认证 **隐藏成本**（仅显示令牌）。 +- `/usage cost` → 从 OpenClaw 会话日志中显示本地成本摘要。 其他表面： -- **TUI/Web TUI：** 支持 `/status` + `/usage`。 -- **CLI：** `openclaw status --usage` 和 `openclaw channels list` 会显示 - 标准化后的提供商配额窗口（`X% left`，而不是按响应计的成本）。 - 当前支持使用窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、 +- **TUI / Web TUI：** 支持 `/status` + `/usage`。 +- **CLI：** `openclaw status --usage` 和 `openclaw channels list` 显示 + 标准化后的提供商配额窗口（`X% left`，而不是按响应成本）。 + 当前支持用量窗口的提供商：Anthropic、GitHub Copilot、Gemini CLI、 OpenAI Codex、MiniMax、Xiaomi 和 z.ai。 -使用量表面会在显示前标准化常见的提供商原生字段别名。 -对于 OpenAI 家族的 Responses 流量，这包括 `input_tokens` / -`output_tokens` 以及 `prompt_tokens` / `completion_tokens`，因此特定传输的 +用量表面在显示前会标准化常见的提供商原生字段别名。 +对于 OpenAI 系列的 Responses 流量，这包括 `input_tokens` / +`output_tokens` 以及 `prompt_tokens` / `completion_tokens`，因此传输层特定的 字段名不会改变 `/status`、`/usage` 或会话摘要。 -Gemini CLI JSON 使用量也会被标准化：回复文本来自 `response`，并且 -`stats.cached` 会映射为 `cacheRead`；当 CLI 未提供显式 `stats.input` 字段时， +Gemini CLI JSON 用量也会被标准化：回复文本来自 `response`，并且 +`stats.cached` 会映射到 `cacheRead`，当 CLI 省略明确的 `stats.input` 字段时， 会使用 `stats.input_tokens - stats.cached`。 -对于原生 OpenAI 家族 Responses 流量，WebSocket/SSE 使用量别名也会以相同方式标准化，并且当 +对于原生 OpenAI 系列 Responses 流量，WebSocket / SSE 用量别名也会以相同方式标准化，并且当 `total_tokens` 缺失或为 `0` 时，总量会回退为标准化后的输入 + 输出。 当当前会话快照较为稀疏时，`/status` 和 `session_status` 还可以 -从最近的转录使用日志中恢复 token/cache 计数器和当前活动运行时模型标签。现有的非零实时值仍优先于转录回退值，并且当存储总量缺失或更小时，较大的、偏向提示词的 -转录总量可以胜出。 -提供商配额窗口的使用量认证在可用时来自提供商特定 Hook； -否则，OpenClaw 会回退为从认证配置文件、环境变量或配置中匹配 OAuth/API 密钥 -凭证。 -助手转录条目会持久化相同的标准化使用量形状，包括 -当活动模型已配置定价且提供商返回使用量元数据时的 `usage.cost`。这为 `/usage cost` 和基于转录的会话 -状态提供了一个稳定来源，即使实时运行时状态已经消失。 +从最近的转录用量日志中恢复令牌 / 缓存计数器以及活动运行时模型标签。 +现有的非零实时值仍然优先于转录回退值，并且当存储总量缺失或更小时， +更大的、偏向提示的转录总量可以胜出。 +提供商配额窗口的用量认证会在可用时来自提供商特定钩子； +否则 OpenClaw 会回退为从认证配置文件、环境变量或配置中匹配的 OAuth / API 密钥凭证。 +助手转录条目会持久化相同的标准化用量结构，包括 +当活动模型已配置定价且提供商返回用量元数据时的 `usage.cost`。 +这使 `/usage cost` 和基于转录的会话状态即使在实时运行时状态消失后 +仍有稳定的数据来源。 + +OpenClaw 将提供商用量计费与当前上下文 +快照分开保留。提供商 `usage.total` 可能包括缓存输入、输出以及多个 +工具循环模型调用，因此它对成本和遥测很有用，但可能会高估实时 +上下文窗口。上下文显示和诊断使用最新的提示快照 +（`promptTokens`，或者当没有提示快照时使用最后一次模型调用）作为 `context.used`。 ## 成本估算（显示时） 成本根据你的模型定价配置估算： -```text +``` models.providers..models[].cost ``` -这些值是 `input`、`output`、`cacheRead` 和 -`cacheWrite` 的**每 100 万 token 的美元价格**。如果缺少定价，OpenClaw 仅显示 token。OAuth token +这些值表示 `input`、`output`、`cacheRead` 和 +`cacheWrite` 的 **每 100 万令牌的美元价格**。如果缺少定价，OpenClaw 仅显示令牌。OAuth 令牌 永不显示美元成本。 -## 缓存 TTL 和裁剪影响 +## 缓存 TTL 和裁剪的影响 -提供商提示词缓存仅在缓存 TTL 窗口内适用。OpenClaw 可以 -选择性运行**cache-ttl 裁剪**：一旦缓存 TTL -过期，它会裁剪会话，然后重置缓存窗口，以便后续请求可以重用新近缓存的上下文，而不是重新缓存完整历史。这样可以在会话空闲超过 TTL 时降低缓存写入成本。 +提供商提示缓存仅在缓存 TTL 窗口内生效。OpenClaw 可以 +选择运行 **cache-ttl pruning**：当缓存 TTL +过期后，它会裁剪会话，然后重置缓存窗口，以便后续请求能够重用 +刚刚重新缓存的上下文，而不是重新缓存完整历史。这样可以在会话空闲超过 TTL 时 +降低缓存写入成本。 -请在 [Gateway 网关配置](/zh-CN/gateway/configuration) 中进行配置，并在 +请在 [Gateway 网关配置](/zh-CN/gateway/configuration) 中配置它，并在 [会话裁剪](/zh-CN/concepts/session-pruning) 中查看行为细节。 -heartbeat 可以在空闲间隔之间保持缓存**温热**。如果你的模型缓存 TTL -为 `1h`，将 heartbeat 间隔设置为略低于该值（例如 `55m`）可以避免 -重新缓存完整提示词，从而减少缓存写入成本。 +Heartbeat 可以在空闲间隔期间让缓存保持 **热状态**。如果你的模型缓存 TTL +是 `1h`，将 heartbeat 间隔设置得略低一些（例如 `55m`）可以避免 +重新缓存完整提示，从而减少缓存写入成本。 -在多智能体设置中，你可以保留一个共享模型配置，并通过 `agents.list[].params.cacheRetention` 为每个智能体单独调整缓存行为。 +在多智能体设置中，你可以保留一个共享的模型配置，并通过 +`agents.list[].params.cacheRetention` 按智能体调整缓存行为。 -如需完整的逐项参数指南，请参见 [提示词缓存](/zh-CN/reference/prompt-caching)。 +如需完整的逐项参数指南，请参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 对于 Anthropic API 定价，缓存读取比输入 -token 便宜得多，而缓存写入则按更高倍数计费。最新价格和 TTL 倍数请参见 Anthropic 的 -提示词缓存定价： +令牌便宜得多，而缓存写入按更高倍数计费。最新费率和 TTL 倍数 +请参见 Anthropic 的提示缓存定价： [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### 示例：使用 heartbeat 保持 1h 缓存温热 +### 示例：使用 heartbeat 保持 1h 缓存热状态 ```yaml agents: @@ -153,7 +161,7 @@ agents: every: "55m" ``` -### 示例：带按智能体缓存策略的混合流量 +### 示例：混合流量与按智能体划分的缓存策略 ```yaml agents: @@ -163,24 +171,24 @@ agents: models: "anthropic/claude-opus-4-6": params: - cacheRetention: "long" # default baseline for most agents + cacheRetention: "long" # 大多数智能体的默认基线 list: - id: "research" default: true heartbeat: - every: "55m" # keep long cache warm for deep sessions + every: "55m" # 为深度会话保持长缓存热状态 - id: "alerts" params: - cacheRetention: "none" # avoid cache writes for bursty notifications + cacheRetention: "none" # 避免为突发通知写入缓存 ``` `agents.list[].params` 会在所选模型的 `params` 之上合并，因此你可以 -仅覆盖 `cacheRetention`，并保持其他模型默认值不变。 +只覆盖 `cacheRetention`，并保持其他模型默认值不变。 -### 示例：启用 Anthropic 1M 上下文 beta 请求头 +### 示例：启用 Anthropic 1M 上下文 beta 标头 -Anthropic 的 1M 上下文窗口目前仍受 beta 门控。OpenClaw 可以在你于受支持的 Opus -或 Sonnet 模型上启用 `context1m` 时，注入所需的 +Anthropic 的 1M 上下文窗口目前仍受 beta 限制。OpenClaw 可以在你对受支持的 Opus +或 Sonnet 模型启用 `context1m` 时注入所需的 `anthropic-beta` 值。 ```yaml @@ -192,29 +200,29 @@ agents: context1m: true ``` -这会映射到 Anthropic 的 `context-1m-2025-08-07` beta 请求头。 +这会映射到 Anthropic 的 `context-1m-2025-08-07` beta 标头。 这仅在该模型条目上设置了 `context1m: true` 时适用。 -要求：该凭证必须有资格使用长上下文。如果没有， -Anthropic 会对此请求返回提供商侧的速率限制错误。 +要求：凭证必须具备长上下文用量资格。如果不具备， +Anthropic 会针对该请求返回提供商侧限流错误。 -如果你使用 OAuth/订阅 token（`sk-ant-oat-*`）认证 Anthropic， -OpenClaw 会跳过 `context-1m-*` beta 请求头，因为 Anthropic 目前 +如果你使用 OAuth / 订阅令牌（`sk-ant-oat-*`）认证 Anthropic， +OpenClaw 会跳过 `context-1m-*` beta 标头，因为 Anthropic 当前 会以 HTTP 401 拒绝这种组合。 -## 减少 token 压力的技巧 +## 减少令牌压力的提示 - 使用 `/compact` 来总结长会话。 - 在你的工作流中裁剪大型工具输出。 -- 对截图较多的会话，降低 `agents.defaults.imageMaxDimensionPx`。 -- 保持 skill 描述简短（skill 列表会注入到提示词中）。 -- 对冗长的探索性工作，优先使用较小的模型。 +- 对截图密集型会话，降低 `agents.defaults.imageMaxDimensionPx`。 +- 保持 Skills 描述简短（Skills 列表会被注入提示中）。 +- 对冗长的探索性工作，优先选择较小的模型。 -关于精确的 skill 列表开销公式，请参见 [Skills](/zh-CN/tools/skills)。 +有关精确的 Skills 列表开销公式，请参见 [Skills](/zh-CN/tools/skills)。 -## 相关 +## 相关内容 -- [API 使用量和成本](/zh-CN/reference/api-usage-costs) -- [提示词缓存](/zh-CN/reference/prompt-caching) -- [使用量跟踪](/zh-CN/concepts/usage-tracking) +- [API 用量和成本](/zh-CN/reference/api-usage-costs) +- [提示缓存](/zh-CN/reference/prompt-caching) +- [用量跟踪](/zh-CN/concepts/usage-tracking) diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 8d92e7834..d0b795d7d 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -6,24 +6,24 @@ read_when: summary: 使用已配置的提供商（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、LiteLLM、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像 title: 图像生成 x-i18n: - generated_at: "2026-04-25T19:10:44Z" + generated_at: "2026-04-25T19:34:29Z" model: gpt-5.4 provider: openai - source_hash: af0afacd9714dbaacfd3b15560ee3badfd6ecea6d2ecf63a12cc9834d916d3e6 + source_hash: fd7cdb5989dc3d09c87f940e423db669ac95c12a7502b23daa25fc73ba4ff85f source_path: tools/image-generation.md workflow: 15 --- -`image_generate` 工具允许智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体的回复一并发送。 +`image_generate` 工具允许智能体使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。 -只有当至少有一个图像生成提供商可用时，该工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。 +只有在至少有一个图像生成提供商可用时，该工具才会出现。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。 ## 快速开始 1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY` 或 `OPENROUTER_API_KEY`），或使用 OpenAI Codex OAuth 登录。 -2. 可选：设置你偏好的模型： +2. 可选地设置你偏好的模型： ```json5 { @@ -31,7 +31,7 @@ x-i18n: defaults: { imageGenerationModel: { primary: "openai/gpt-image-2", - // image_generate 的可选默认提供商请求超时时间。 + // image_generate 的可选默认提供商请求超时。 timeoutMs: 180_000, }, }, @@ -40,14 +40,15 @@ x-i18n: ``` Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -`openai-codex` OAuth 配置文件时，OpenClaw 会通过同一个 OAuth 配置文件来路由图像请求，而不是先尝试 `OPENAI_API_KEY`。 -显式的自定义 `models.providers.openai` 图像配置，例如 API 密钥或 -自定义 / Azure `baseUrl`，会重新切换为直接使用 OpenAI Images API 路由。 -对于像 LocalAI 这样的 OpenAI 兼容局域网端点，请保留自定义的 -`models.providers.openai.baseUrl`，并显式启用 -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；私有 / 内部图像端点默认仍会被阻止。 +`openai-codex` OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求， +而不是先尝试 `OPENAI_API_KEY`。显式的自定义 `models.providers.openai` 图像配置， +例如 API 密钥或自定义 / Azure base URL，会重新切换回直接使用 OpenAI Images API 的路由。 +对于 LocalAI 这类兼容 OpenAI 的局域网端点，请保留自定义的 +`models.providers.openai.baseUrl`，并通过 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` 显式启用； +私有 / 内部图像端点默认仍会被阻止。 -3. 向智能体提问：_“生成一张友好的机器人吉祥物图像。”_ +3. 向智能体发出请求：_“生成一张友好的机器人吉祥物图像。”_ 智能体会自动调用 `image_generate`。不需要工具允许列表——当提供商可用时，它默认启用。 @@ -62,9 +63,11 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 | LiteLLM 图像生成 | `litellm/gpt-image-2` | `LITELLM_API_KEY` | | Google Gemini 图像生成 | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -同一个 `image_generate` 工具同时处理文生图和参考图像编辑。 -单张参考图像使用 `image`，多张参考图像使用 `images`。 -当提供商支持时，会转发诸如 `quality`、`outputFormat` 以及 OpenAI 专用的 `background` 等输出提示；如果提供商不支持，这些参数会被标记为已忽略。 +同一个 `image_generate` 工具可处理文生图和参考图编辑。 +对单张参考图使用 `image`，对多张参考图使用 `images`。 +在提供商支持时，会转发如 `quality`、`outputFormat` 和 `background` 这类输出提示； +如果提供商不支持，则会报告这些参数被忽略。目前内置的透明背景支持仅限 OpenAI； +如果其他提供商的后端会输出 PNG alpha，它们仍可能保留透明通道。 ## 支持的提供商 @@ -75,7 +78,7 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 | LiteLLM | `gpt-image-2` | 是（最多 5 张输入图像） | `LITELLM_API_KEY` | | Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | | fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` | -| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | +| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth (`minimax-portal`) | | ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | | Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` | | xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` | @@ -89,24 +92,24 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 ## 工具参数 -图像生成提示词。`action: "generate"` 时必填。 +图像生成提示词。对于 `action: "generate"` 为必填。 -使用 `"list"` 在运行时查看可用的提供商和模型。 +使用 `"list"` 可在运行时查看可用的提供商和模型。 -提供商 / 模型覆盖，例如 `openai/gpt-image-2`；透明 OpenAI 背景请使用 +提供商 / 模型覆盖，例如 `openai/gpt-image-2`；透明的 OpenAI 背景请使用 `openai/gpt-image-1.5`。 -编辑模式下的单张参考图像路径或 URL。 +用于编辑模式的单张参考图路径或 URL。 -编辑模式下的多张参考图像（最多 5 张）。 +用于编辑模式的多张参考图（最多 5 张）。 @@ -122,11 +125,16 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -提供商支持时的质量提示。 +当提供商支持时的质量提示。 -提供商支持时的输出格式提示。 +当提供商支持时的输出格式提示。 + + + +当提供商支持时的背景提示。对于支持透明的提供商，请将 `transparent` 与 +`outputFormat: "png"` 或 `"webp"` 一起使用。 @@ -142,12 +150,12 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 -仅 OpenAI 提示：`background`、`moderation`、`outputCompression` 和 `user`。 +仅适用于 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。 -并非所有提供商都支持所有参数。当后备提供商支持与请求值接近的几何选项，而不是完全相同的选项时，OpenClaw 会在提交前重映射到最接近的受支持尺寸、宽高比或分辨率。像 `quality` 或 `outputFormat` 这类不受支持的输出提示，会对未声明支持它们的提供商被丢弃，并在工具结果中报告。 +并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项而不是精确请求的选项时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。对于未声明支持的提供商，不受支持的输出提示（如 `quality` 或 `outputFormat`）会被丢弃，并在工具结果中报告。 -工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 +工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。 ## 配置 @@ -175,44 +183,43 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了 生成图像时，OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 **`model` 参数**（如果智能体指定了它） +1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** 3. 按顺序使用 **`imageGenerationModel.fallbacks`** -4. **自动检测** —— 仅使用有认证支持的提供商默认值： +4. **自动检测**——仅使用有认证支持的提供商默认值： - 当前默认提供商优先 - - 其余已注册的图像生成提供商，按提供商 ID 顺序排列 + - 其余已注册的图像生成提供商按提供商 ID 顺序排列 -如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个已配置的候选项。如果全部失败，错误信息中会包含每次尝试的详细信息。 +如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个已配置候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 注意： - 每次调用的 `model` 覆盖是精确的：OpenClaw 只会尝试该提供商 / 模型， - 不会继续尝试已配置的 primary / fallback 或自动检测到的 + 不会继续尝试已配置的 primary / fallback，也不会尝试自动检测到的 提供商。 -- 自动检测具有认证感知能力。只有当 OpenClaw 实际能够认证该提供商时， +- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够为某个提供商认证时， 该提供商默认值才会进入候选列表。 -- 自动检测默认启用。如果你希望图像生成 - 仅使用显式的 `model`、`primary` 和 `fallbacks` +- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。 -- 为较慢的图像后端设置 `agents.defaults.imageGenerationModel.timeoutMs`。 - 每次调用的 `timeoutMs` 工具参数会覆盖已配置的默认值。 -- 使用 `action: "list"` 查看当前已注册的提供商、 - 它们的默认模型，以及认证环境变量提示。 +- 对于较慢的图像后端，请设置 `agents.defaults.imageGenerationModel.timeoutMs`。 + 每次调用的 `timeoutMs` 工具参数会覆盖配置中的默认值。 +- 使用 `action: "list"` 可查看当前已注册的提供商、它们的 + 默认模型以及认证环境变量提示。 ### 图像编辑 OpenAI、OpenRouter、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL： ``` -"将这张照片生成成水彩风格" + image: "/path/to/photo.jpg" +"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" ``` -OpenAI、OpenRouter、Google 和 xAI 通过 `images` 参数支持最多 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。 +OpenAI、OpenRouter、Google 和 xAI 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。 ### OpenRouter 图像模型 -OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRouter 的聊天补全图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型： +OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRouter 的 chat completions 图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型： ```json5 { @@ -226,29 +233,25 @@ OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRout } ``` -OpenClaw 会将 `prompt`、`count`、参考图像以及兼容 Gemini 的 `aspectRatio` / `resolution` 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 查看你已配置插件所公开的内容。 +OpenClaw 会将 `prompt`、`count`、参考图像以及兼容 Gemini 的 `aspectRatio` / `resolution` 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；请使用 `action: "list"` 查看你配置的插件公开了哪些内容。 ### OpenAI `gpt-image-2` -OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了 -`openai-codex` OAuth 配置文件，OpenClaw 会复用与 Codex 订阅聊天模型相同的 OAuth -配置文件，并通过 Codex Responses 后端发送图像请求。旧版 Codex `baseUrl`，例如 +OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果已配置 +`openai-codex` OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的同一 OAuth +配置文件，并通过 Codex Responses 后端发送图像请求。旧版 Codex base URL，例如 `https://chatgpt.com/backend-api`，会在图像请求中规范化为 -`https://chatgpt.com/backend-api/codex`。它不会 -静默回退到 `OPENAI_API_KEY` 来处理该请求。若要强制使用直接 OpenAI -Images API 路由，请显式配置 `models.providers.openai`，例如 API -密钥、自定义 `baseUrl` 或 Azure 端点。仍然可以显式选择 -`openai/gpt-image-1.5`、 -`openai/gpt-image-1` 和 `openai/gpt-image-1-mini` -模型。透明背景 PNG/WebP 输出请使用 `gpt-image-1.5`； +`https://chatgpt.com/backend-api/codex`。它不会为该请求静默回退到 +`OPENAI_API_KEY`。若要强制直接路由到 OpenAI Images API，请显式配置 +`models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。 +`openai/gpt-image-1.5`、`openai/gpt-image-1` 和 `openai/gpt-image-1-mini` +模型仍可显式选择。透明背景的 PNG/WebP 输出请使用 `gpt-image-1.5`； 当前的 `gpt-image-2` API 会拒绝 `background: "transparent"`。 -`gpt-image-2` 同时支持文生图和参考图像编辑， -都通过同一个 `image_generate` 工具完成。OpenClaw 会将 `prompt`、 -`count`、`size`、`quality`、`outputFormat` 和参考图像转发给 OpenAI。 +`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图和参考图像编辑。OpenClaw 会将 `prompt`、`count`、`size`、`quality`、`outputFormat` 和参考图像转发给 OpenAI。 OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下， -OpenClaw 会将它们映射到受支持的 `size`，否则工具会将它们报告为 -被忽略的覆盖项。 +OpenClaw 会将它们映射为受支持的 `size`，否则工具会将它们报告为 +被忽略的覆盖参数。 OpenAI 专用选项位于 `openai` 对象下： @@ -266,31 +269,33 @@ OpenAI 专用选项位于 `openai` 对象下： ``` `openai.background` 接受 `transparent`、`opaque` 或 `auto`；透明 -输出需要将 `outputFormat` 设为 `png` 或 `webp`，并且使用支持透明度的 OpenAI -图像模型。对于默认的 `gpt-image-2` 透明背景请求，OpenClaw 会将其路由到 `gpt-image-1.5`。 -`openai.outputCompression` 适用于 JPEG/WebP -输出。 +输出要求 `outputFormat` 为 `png` 或 `webp`，并且使用支持透明度的 OpenAI +图像模型。OpenClaw 会将默认的 `gpt-image-2` 透明背景请求路由到 `gpt-image-1.5`。 +`openai.outputCompression` 适用于 JPEG/WebP 输出。 -当你要求智能体生成透明背景的 OpenAI 图像时，预期的 -工具调用如下： +顶层 `background` 提示是提供商无关的，目前在选择 OpenAI 提供商时会映射到 +相同的 OpenAI `background` 请求字段。 +对于未声明支持背景控制的提供商，它会在 `ignoredOverrides` 中返回， +而不是接收这个不受支持的参数。 + +当你请求智能体生成带透明背景的 OpenAI 图像时，预期的 +工具调用是： ```json { "model": "openai/gpt-image-1.5", - "prompt": "一个透明背景上的简单红色圆形贴纸", + "prompt": "A simple red circle sticker on a transparent background", "outputFormat": "png", - "openai": { - "background": "transparent" - } + "background": "transparent" } ``` -显式指定 `openai/gpt-image-1.5` 模型可以让该请求在不同的 +显式使用 `openai/gpt-image-1.5` 模型可让该请求在 工具摘要和 harness 中保持可移植性。如果智能体改为使用默认的 -`openai/gpt-image-2`，并在公开 -OpenAI 或 OpenAI Codex OAuth 路由上设置 `openai.background: "transparent"`，OpenClaw 会将提供商请求重写为 -`gpt-image-1.5`。Azure 和自定义的 OpenAI 兼容端点会保留它们已配置的 -部署 / 模型名称。 +`openai/gpt-image-2`，并在公开的 OpenAI 或 OpenAI Codex OAuth 路由上设置 +`openai.background: "transparent"`，OpenClaw 会将提供商请求重写为 +`gpt-image-1.5`。Azure 和自定义的兼容 OpenAI 端点会保留其 +已配置的 deployment / model 名称。 对于无头 CLI 生成，请使用等效的 `openclaw infer` 标志： @@ -298,59 +303,61 @@ OpenAI 或 OpenAI Codex OAuth 路由上设置 `openai.background: "transparent"` openclaw infer image generate \ --model openai/gpt-image-1.5 \ --output-format png \ - --openai-background transparent \ - --prompt "一个透明背景上的简单红色圆形贴纸" \ + --background transparent \ + --prompt "A simple red circle sticker on a transparent background" \ --json ``` -同样的 `--output-format` 和 `--openai-background` 标志也可用于 -`openclaw infer image edit`。其他内置提供商也可以返回 PNG， -并且如果其后端输出 alpha 通道，可能会保留透明度，但 OpenClaw 目前只为 OpenAI 图像生成公开提供了 -显式的透明背景控制。 +在 `openclaw infer image edit` 上也可以使用相同的 `--output-format` 和 `--background` +标志；`--openai-background` 仍然保留为 +OpenAI 专用别名。当前除 OpenAI 外的其他内置提供商都未声明 +显式背景控制，因此对它们而言，`background: "transparent"` 会被报告为 +已忽略。 生成一张 4K 横向图像： ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="为 OpenClaw 图像生成设计一张简洁的编辑风格海报" size=3840x2160 count=1 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 ``` -生成一张透明 PNG： +生成透明 PNG： ``` -/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="一个透明背景上的简单红色圆形贴纸" outputFormat=png openai='{"background":"transparent"}' +/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent ``` 生成两张方形图像： ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="为一款平静风格的效率应用图标提供两个视觉方向" size=1024x1024 count=2 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2 ``` 编辑一张本地参考图像： ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="保留主体，将背景替换为明亮的摄影棚布景" image=/path/to/reference.png size=1024x1536 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 ``` 使用多张参考图像进行编辑： ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="结合第一张图像中的角色特征与第二张图像中的配色方案" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -如果要将 OpenAI 图像生成路由到 Azure OpenAI 部署，而不是 -`api.openai.com`，请参阅 OpenAI provider 文档中的 [Azure OpenAI 端点](/zh-CN/providers/openai#azure-openai-endpoints)。 +如需将 OpenAI 图像生成路由到 Azure OpenAI deployment， +而不是 `api.openai.com`，请参阅 OpenAI provider 文档中的 +[Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。 -MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用： +MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用： -- `minimax/image-01`，用于 API 密钥配置 -- `minimax-portal/image-01`，用于 OAuth 配置 +- 用于 API 密钥设置的 `minimax/image-01` +- 用于 OAuth 设置的 `minimax-portal/image-01` ## 提供商能力 | 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（工作流定义的输出） | 是（1 张） | 是（最多 4 张） | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | 是（最多 4 张） | | 编辑 / 参考图 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） | | 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 | | 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 | @@ -358,29 +365,29 @@ MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用： ### xAI `grok-imagine-image` -内置的 xAI 提供商在仅提示词请求时使用 `/v1/images/generations`， +内置的 xAI 提供商在纯提示词请求时使用 `/v1/images/generations`， 当存在 `image` 或 `images` 时使用 `/v1/images/edits`。 - 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro` - 数量：最多 4 张 -- 参考图：一个 `image` 或最多五个 `images` +- 参考图：单个 `image` 或最多五个 `images` - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2` - 分辨率：`1K`、`2K` -- 输出：以 OpenClaw 管理的图像附件形式返回 +- 输出：作为 OpenClaw 管理的图像附件返回 -在这些控制项出现在跨提供商共享的 -`image_generate` 契约中之前，OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或 -额外的仅原生支持宽高比控制。 +在这些控制项存在于跨提供商共享的 `image_generate` 合同之前， +OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或 +其他仅限原生接口的宽高比选项。 ## 相关内容 -- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 -- [fal](/zh-CN/providers/fal) — fal 图像与视频提供商设置 +- [Tools 概览](/zh-CN/tools) — 所有可用的智能体工具 +- [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置 -- [Google（Gemini）](/zh-CN/providers/google) — Gemini 图像提供商设置 +- [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置 - [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置 -- [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置 +- [OpenAI](/zh-CN/providers/openai) — OpenAI Images provider 设置 - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置 - [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置 -- [Models](/zh-CN/concepts/models) — 模型配置与故障切换 +- [Models](/zh-CN/concepts/models) — 模型配置和故障切换