diff --git a/docs/zh-CN/automation/hooks.md b/docs/zh-CN/automation/hooks.md index 0c702bd31..eeeac7d69 100644 --- a/docs/zh-CN/automation/hooks.md +++ b/docs/zh-CN/automation/hooks.md @@ -1,24 +1,24 @@ --- read_when: - - 你希望为 `/new`、`/reset`、`/stop` 和智能体生命周期事件提供事件驱动的自动化功能 + - 你想要为 /new、/reset、/stop 和智能体生命周期事件提供事件驱动的自动化功能 - 你想要构建、安装或调试钩子 summary: 钩子：用于命令和生命周期事件的事件驱动自动化 title: 钩子 x-i18n: - generated_at: "2026-04-26T23:09:30Z" + generated_at: "2026-04-27T11:10:42Z" model: gpt-5.4 provider: openai - source_hash: f1f9b1dc0c470502f782758e1542435f1e593750ff69a39f7f966c7d42e29c1e + source_hash: f5e63700c90456dfc26de8545ad4382d6d34bcfd8896966d88e008da5c690255 source_path: automation/hooks.md workflow: 15 --- -钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中被发现，并可通过 `openclaw hooks` 进行检查。只有在你启用钩子，或至少配置了一个钩子条目、hook pack、旧版处理器或额外钩子目录后，Gateway 网关才会加载内部钩子。 +钩子是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中被发现，并可通过 `openclaw hooks` 进行检查。只有在你启用 hooks，或至少配置一个 hook 条目、hook pack、旧版处理程序或额外 hook 目录后，Gateway 网关才会加载内部钩子。 OpenClaw 中有两种钩子： -- **内部钩子**（本页）：当智能体事件触发时在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 -- **Webhooks**：外部 HTTP 端点，让其他系统可以在 OpenClaw 中触发工作。参见 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。 +- **内部钩子**（本页）：当智能体事件触发时，在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 +- **Webhooks**：外部 HTTP 端点，让其他系统在 OpenClaw 中触发工作。请参见 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。 钩子也可以内置在插件中。`openclaw hooks list` 会同时显示独立钩子和由插件管理的钩子。 @@ -46,14 +46,16 @@ openclaw hooks info session-memory | `command:reset` | 发出 `/reset` 命令时 | | `command:stop` | 发出 `/stop` 命令时 | | `command` | 任意命令事件（通用监听器） | -| `session:compact:before` | 压缩开始汇总历史记录之前 | +| `session:compact:before` | 在压缩开始总结历史记录之前 | | `session:compact:after` | 压缩完成之后 | | `session:patch` | 修改会话属性时 | -| `agent:bootstrap` | 注入工作区 bootstrap 文件之前 | -| `gateway:startup` | 渠道启动且钩子加载完成之后 | -| `message:received` | 从任意渠道收到入站消息 | -| `message:transcribed` | 音频转录完成之后 | -| `message:preprocessed` | 所有媒体和链接理解完成之后 | +| `agent:bootstrap` | 在注入工作区引导文件之前 | +| `gateway:startup` | 渠道启动并加载钩子后 | +| `gateway:shutdown` | Gateway 网关开始关闭时 | +| `gateway:pre-restart` | 预期中的 Gateway 网关重启之前 | +| `message:received` | 来自任意渠道的入站消息 | +| `message:transcribed` | 音频转写完成后 | +| `message:preprocessed` | 所有媒体和链接理解完成后 | | `message:sent` | 出站消息已送达 | ## 编写钩子 @@ -65,15 +67,15 @@ openclaw hooks info session-memory ``` my-hook/ ├── HOOK.md # 元数据 + 文档 -└── handler.ts # 处理器实现 +└── handler.ts # 处理程序实现 ``` -### `HOOK.md` 格式 +### HOOK.md 格式 ```markdown --- name: my-hook -description: "这个钩子的简短说明" +description: "此钩子功能的简短描述" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- @@ -87,15 +89,15 @@ metadata: | 字段 | 说明 | | ---------- | ---------------------------------------------------- | -| `emoji` | CLI 中显示的 emoji | +| `emoji` | CLI 中显示的表情符号 | | `events` | 要监听的事件数组 | -| `export` | 要使用的命名导出（默认是 `"default"`） | +| `export` | 要使用的具名导出（默认为 `"default"`） | | `os` | 所需平台（例如 `["darwin", "linux"]`） | | `requires` | 所需的 `bins`、`anyBins`、`env` 或 `config` 路径 | | `always` | 跳过资格检查（布尔值） | | `install` | 安装方式 | -### 处理器实现 +### 处理程序实现 ```typescript const handler = async (event) => { @@ -104,16 +106,16 @@ const handler = async (event) => { } console.log(`[my-hook] New command triggered`); - // 你的逻辑写在这里 + // Your logic here - // 可选：向用户发送消息 + // Optionally send message to user event.messages.push("Hook executed!"); }; export default handler; ``` -每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 push 以发送给用户）以及 `context`（事件特定数据）。智能体和工具插件的钩子上下文还可以包含 `trace`，这是一个只读、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中，以便与 OTEL 进行关联。 +每个事件都包括：`type`、`action`、`sessionKey`、`timestamp`、`messages`（push 后可发送给用户）以及 `context`（事件特定数据）。智能体和工具插件钩子的上下文还可能包含 `trace`，这是只读的、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中以进行 OTEL 关联。 ### 事件上下文重点 @@ -127,45 +129,47 @@ export default handler; **消息事件**（`message:preprocessed`）：`context.bodyForAgent`（最终增强后的正文）、`context.from`、`context.channelId`。 -**Bootstrap 事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。 +**引导事件**（`agent:bootstrap`）：`context.bootstrapFiles`（可变数组）、`context.agentId`。 -**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端可以触发补丁事件。 +**会话补丁事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端才能触发补丁事件。 -**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 还会增加 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。 +**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 额外包含 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。 -`command:stop` 观察的是用户发出 `/stop`；它属于取消/命令生命周期，而不是智能体最终完成的关卡。需要检查自然结束答案并让智能体再进行一轮处理的插件，应改用类型化插件钩子 `before_agent_finalize`。参见 [Plugin hooks](/zh-CN/plugins/hooks)。 +`command:stop` 观察的是用户发出 `/stop` 的动作；它属于取消/命令生命周期，而不是智能体最终完成的关卡。需要检查自然生成的最终回答并要求智能体再执行一轮的插件，应改用类型化插件钩子 `before_agent_finalize`。请参见 [插件钩子](/zh-CN/plugins/hooks)。 + +**Gateway 网关生命周期事件**：`gateway:shutdown` 包含 `reason` 和 `restartExpectedMs`，并在 Gateway 网关开始关闭时触发。`gateway:pre-restart` 包含相同上下文，但仅在关闭属于预期重启的一部分且提供了有限的 `restartExpectedMs` 值时才会触发。关闭期间，每个生命周期钩子的等待都是尽力而为且有时间上限的，因此即使处理程序卡住，关闭流程也会继续。 ## 钩子发现 -钩子会按以下目录进行发现，覆盖优先级依次递增： +钩子会从以下目录中被发现，按覆盖优先级从低到高排序： 1. **内置钩子**：随 OpenClaw 一起发布 2. **插件钩子**：内置在已安装插件中的钩子 -3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录与此具有相同优先级。 -4. **工作区钩子**：`/hooks/`（每个智能体单独使用，默认禁用，需显式启用） +3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录也具有相同优先级。 +4. **工作区钩子**：`/hooks/`（按智能体划分，默认禁用，需显式启用） -工作区钩子可以新增钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。 +工作区钩子可以添加新的钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。 -在配置内部钩子之前，Gateway 网关会在启动时跳过内部钩子发现。你可以通过 `openclaw hooks enable ` 启用一个内置或托管钩子，安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来主动启用。启用某个具名钩子后，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器则会启用更广泛的发现机制。 +在配置内部钩子之前，Gateway 网关会在启动时跳过内部钩子发现。你可以使用 `openclaw hooks enable ` 启用一个内置或托管钩子、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个具名钩子时，Gateway 网关只会加载该钩子的处理程序；而 `hooks.internal.enabled=true`、额外 hook 目录和旧版处理程序则会启用广泛发现。 ### Hook packs -Hook pack 是通过 `package.json` 中的 `openclaw.hooks` 导出钩子的 npm 包。安装方式如下： +Hook pack 是通过 `package.json` 中的 `openclaw.hooks` 导出钩子的 npm 包。安装命令如下： ```bash openclaw plugins install ``` -npm spec 仅支持注册表来源（包名 + 可选精确版本或 dist-tag）。Git/URL/file spec 和 semver 范围都会被拒绝。 +npm 规格仅支持 registry（包名 + 可选的精确版本或 dist-tag）。Git/URL/file 规格和 semver 范围都会被拒绝。 ## 内置钩子 -| 钩子 | 事件 | 功能 | +| 钩子 | 事件 | 功能说明 | | --------------------- | ------------------------------ | ----------------------------------------------------- | | session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的 bootstrap 文件 | +| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的引导文件 | | command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` | -| boot-md | `gateway:startup` | 在网关启动时运行 `BOOT.md` | +| boot-md | `gateway:startup` | 在 Gateway 网关启动时运行 `BOOT.md` | 启用任意内置钩子： @@ -175,13 +179,13 @@ openclaw hooks enable -### `session-memory` 详情 +### session-memory 详情 -提取最近 15 条用户/assistant 消息，通过 LLM 生成描述性文件名 slug，并使用主机本地日期保存到 `/memory/YYYY-MM-DD-slug.md`。要求配置 `workspace.dir`。 +提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，并使用主机本地日期保存到 `/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。 -### `bootstrap-extra-files` 配置 +### bootstrap-extra-files 配置 ```json { @@ -198,26 +202,26 @@ openclaw hooks enable } ``` -路径相对于工作区解析。仅会加载已识别的 bootstrap 基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 +路径相对于工作区解析。只会加载被识别的引导基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 -### `command-logger` 详情 +### command-logger 详情 将每个斜杠命令记录到 `~/.openclaw/logs/commands.log`。 -### `boot-md` 详情 +### boot-md 详情 在 Gateway 网关启动时，从当前活动工作区运行 `BOOT.md`。 ## 插件钩子 -插件可以通过插件 SDK 注册类型化钩子，以实现更深层的集成：拦截工具调用、修改提示词、控制消息流等。 +插件可以通过 插件 SDK 注册类型化钩子，以实现更深层集成：拦截工具调用、修改提示词、控制消息流等。 当你需要 `before_tool_call`、`before_agent_reply`、`before_install` 或其他进程内生命周期钩子时，请使用插件钩子。 -完整的插件钩子参考请参见 [Plugin hooks](/zh-CN/plugins/hooks)。 +完整的插件钩子参考，请参见 [插件钩子](/zh-CN/plugins/hooks)。 ## 配置 @@ -252,7 +256,7 @@ openclaw hooks enable } ``` -额外钩子目录： +额外的钩子目录： ```json { @@ -267,7 +271,7 @@ openclaw hooks enable ``` -旧版 `hooks.internal.handlers` 数组配置格式仍然受支持，以保持向后兼容，但新钩子应使用基于发现的系统。 +为保持向后兼容，旧版的 `hooks.internal.handlers` 数组配置格式仍受支持，但新钩子应使用基于发现的系统。 ## CLI 参考 @@ -289,8 +293,8 @@ openclaw hooks disable ## 最佳实践 -- **保持处理器快速。** 钩子会在命令处理期间运行。对较重的工作请使用 `void processInBackground(event)` 以即发即忘方式处理。 -- **优雅地处理错误。** 用 try/catch 包裹高风险操作；不要抛出异常，以便其他处理器继续运行。 +- **保持处理程序快速。** 钩子会在命令处理期间运行。对于耗时工作，可使用 `void processInBackground(event)` 以 fire-and-forget 方式执行。 +- **优雅地处理错误。** 将有风险的操作包装在 try/catch 中；不要抛出异常，以便其他处理程序能够继续运行。 - **尽早过滤事件。** 如果事件类型/动作无关，请立即返回。 - **使用具体事件键。** 优先使用 `"events": ["command:new"]`，而不是 `"events": ["command"]`，以减少开销。 @@ -313,17 +317,17 @@ openclaw hooks list openclaw hooks info my-hook ``` -检查是否缺少二进制文件（PATH）、环境变量、配置值或操作系统兼容性。 +检查是否缺少二进制文件（PATH）、环境变量、配置值，或是否存在 OS 兼容性问题。 ### 钩子未执行 -1. 确认钩子已启用：`openclaw hooks list` -2. 重启你的网关进程以重新加载钩子。 -3. 检查网关日志：`./scripts/clawlog.sh | grep hook` +1. 验证钩子已启用：`openclaw hooks list` +2. 重启你的 Gateway 网关进程以重新加载钩子。 +3. 检查 Gateway 网关日志：`./scripts/clawlog.sh | grep hook` ## 相关内容 - [CLI 参考：hooks](/zh-CN/cli/hooks) - [Webhooks](/zh-CN/automation/cron-jobs#webhooks) -- [Plugin hooks](/zh-CN/plugins/hooks) — 进程内插件生命周期钩子 +- [插件钩子](/zh-CN/plugins/hooks) — 进程内插件生命周期钩子 - [配置](/zh-CN/gateway/configuration-reference#hooks) diff --git a/docs/zh-CN/gateway/config-tools.md b/docs/zh-CN/gateway/config-tools.md index a8ed30fa7..0d46f661e 100644 --- a/docs/zh-CN/gateway/config-tools.md +++ b/docs/zh-CN/gateway/config-tools.md @@ -1,59 +1,59 @@ --- read_when: - 配置 `tools.*` 策略、允许列表或实验性功能 - - 注册自定义提供商或覆盖 base URL + - 注册自定义 provider 或覆盖 base URL - 设置与 OpenAI 兼容的自托管端点 sidebarTitle: Tools and custom providers -summary: 工具配置（策略、实验性开关、提供商支持的工具）以及自定义提供商 / base-URL 设置 -title: 配置——工具和自定义提供商 +summary: 工具配置（策略、实验性开关、provider 支持的工具）以及自定义 provider/base-URL 设置 +title: 配置——工具和自定义 provider x-i18n: - generated_at: "2026-04-27T09:29:04Z" + generated_at: "2026-04-27T11:10:44Z" model: gpt-5.4 provider: openai - source_hash: 1dd86212954d2f5c11b3cf376a3a18655a657814d267cea38b42ea40a33617a4 + source_hash: 4cb18ee1b2d16309ba2eedb0408f63df58ae7f319dfe8c4cb3bf2a868415463a source_path: gateway/config-tools.md workflow: 15 --- -`tools.*` 配置键和自定义提供商 / base-URL 设置。对于智能体、渠道以及其他顶层配置键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 +`tools.*` 配置键和自定义 provider / base-URL 设置。对于智能体、渠道及其他顶层配置键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 ## 工具 -### 工具配置文件 +### 工具配置档案 -`tools.profile` 会在 `tools.allow` / `tools.deny` 之前设置基础允许列表： +`tools.profile` 在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导会在未设置时，默认将新的本地配置设为 `tools.profile: "coding"`（现有的显式配置文件会被保留）。 +本地新手引导会在未设置时，默认将新的本地配置设为 `tools.profile: "coding"`（已显式设置的配置档案会被保留）。 -| 配置文件 | 包含内容 | +| 配置档案 | 包含内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | 仅 `session_status` | | `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | | `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| `full` | 不限制（与未设置相同） | ### 工具组 -| 组 | 工具 | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| 组 | 工具 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括 provider 插件） | ### `tools.allow` / `tools.deny` -全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭时也会应用。 +全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭时也会生效。 ```json5 { @@ -63,7 +63,7 @@ x-i18n: ### `tools.byProvider` -进一步限制特定提供商或模型可用的工具。顺序：基础配置文件 → 提供商配置文件 → allow / deny。 +进一步限制特定 provider 或模型可用的工具。顺序：基础配置档案 → provider 配置档案 → allow/deny。 ```json5 { @@ -95,9 +95,9 @@ x-i18n: } ``` -- 每个智能体的覆盖项（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。 -- 提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，当 `exec` 目标是 `node` 时则为 `node`）。 +- 每个智能体的覆盖配置（`agents.list[].tools.elevated`）只能进一步收紧限制。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅对单条消息生效。 +- 提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认为 `gateway`，或者当 exec 目标为 `node` 时使用 `node`）。 ### `tools.exec` @@ -121,7 +121,7 @@ x-i18n: ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 以启用检测。设置可以在全局 `tools.loopDetection` 中定义，并在每个智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查**默认关闭**。设置 `enabled: true` 以启用检测。设置可在全局 `tools.loopDetection` 中定义，并可在每个智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -143,7 +143,7 @@ x-i18n: ``` - 为循环分析保留的最大工具调用历史记录。 + 为循环分析保留的最大工具调用历史记录数量。 用于发出警告的重复无进展模式阈值。 @@ -155,17 +155,17 @@ x-i18n: 对任何无进展运行执行硬停止的阈值。 - 对重复的同一工具 / 同一参数调用发出警告。 + 对重复调用相同工具 / 相同参数的情况发出警告。 对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻止。 - 对交替出现的无进展配对模式发出警告 / 阻止。 + 对交替出现的成对无进展模式发出警告 / 阻止。 -如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证将失败。 +如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，则验证失败。 ### `tools.web` @@ -200,7 +200,7 @@ x-i18n: ### `tools.media` -配置入站媒体理解（图像 / 音频 / 视频）： +配置入站媒体理解（图片 / 音频 / 视频）： ```json5 { @@ -208,7 +208,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // 选择启用：将完成的异步音乐 / 视频直接发送到渠道 + directSend: false, // 选择启用：将已完成的异步音乐 / 视频直接发送到渠道 }, audio: { enabled: true, @@ -239,29 +239,29 @@ x-i18n: - **提供商条目**（`type: "provider"` 或省略）： + **Provider 条目**（`type: "provider"` 或省略）： - - `provider`：API 提供商 id（`openai`、`anthropic`、`google` / `gemini`、`groq` 等） + - `provider`：API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 id 覆盖值 - - `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 + - `profile` / `preferredProfile`：`auth-profiles.json` 配置档案选择 **CLI 条目**（`type: "cli"`）： - `command`：要运行的可执行文件 - - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等） + - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等；已弃用的 `{input}` 也可作为 `{{MediaPath}}` 的别名使用） **通用字段：** - - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai` / `anthropic` / `minimax` → image，`google` → image + audio + video，`groq` → audio。 - - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每个条目的覆盖项。 - - 当智能体调用显式 `image` 工具时，`tools.media.image.timeoutSeconds` 和对应图像模型的 `timeoutSeconds` 条目也会生效。 + - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 + - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每个条目的覆盖设置。 + - `tools.media.image.timeoutSeconds` 以及对应图片模型中的 `timeoutSeconds` 条目，在智能体调用显式 `image` 工具时也会生效。 - 失败时会回退到下一个条目。 - 提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 + Provider 身份验证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - - `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` 和 `video_generate` 任务会优先尝试直接投递到渠道。默认值：`false`（旧版的请求者会话唤醒 / 模型投递路径）。 + - `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` 和 `video_generate` 任务会优先尝试直接投递到渠道。默认值：`false`（旧版请求者会话唤醒 / 模型投递路径）。 @@ -281,7 +281,7 @@ x-i18n: ### `tools.sessions` -控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 @@ -300,9 +300,9 @@ x-i18n: - `self`：仅当前会话键。 - `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 - - `agent`：属于当前智能体 id 的任意会话（如果你在同一个智能体 id 下按发送者运行会话，则可能包括其他用户）。 - - `all`：任意会话。跨智能体定向仍然需要 `tools.agentToAgent`。 - - 沙箱限制：当当前会话处于沙箱隔离状态，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 + - `agent`：属于当前智能体 id 的任何会话（如果你在同一个智能体 id 下按发送者运行会话，则可能包含其他用户）。 + - `all`：任何会话。跨智能体定位仍然需要 `tools.agentToAgent`。 + - 沙箱钳制：当当前会话处于沙箱隔离状态，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 @@ -328,12 +328,12 @@ x-i18n: - - 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 - - 文件会被写入子工作区中的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 + - 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 + - 文件会在子工作区中实体化到 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 - - Base64 输入会使用严格的字母表 / 填充检查以及解码前大小保护进行验证。 - - 文件权限为：目录 `0700`，文件 `0600`。 - - 清理由 `cleanup` 策略决定：`delete` 始终会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 + - Base64 输入会通过严格的字母表 / 填充检查以及解码前大小保护进行校验。 + - 目录权限为 `0700`，文件权限为 `0600`。 + - 清理遵循 `cleanup` 策略：`delete` 始终删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 @@ -353,9 +353,9 @@ x-i18n: } ``` -- `planTool`：为非简单的多步骤工作跟踪启用结构化的 `update_plan` 工具。 -- 默认值：`false`，除非为 OpenAI 或 OpenAI Codex GPT-5 系列运行将 `agents.defaults.embeddedPi.executionContract`（或每个智能体的覆盖项）设置为 `"strict-agentic"`。设置为 `true` 可在该范围之外强制启用此工具，设置为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示也会添加使用指导，以便模型仅在实质性工作中使用它，并且最多只保留一个 `in_progress` 步骤。 +- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：`false`，除非针对 OpenAI 或 OpenAI Codex 的 GPT-5 系列运行，将 `agents.defaults.embeddedPi.executionContract`（或每个智能体的覆盖设置）设为 `"strict-agentic"`。设为 `true` 可在该范围之外强制启用此工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 +- 启用后，系统提示词还会添加使用指南，以便模型仅在处理实质性工作时使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -375,21 +375,21 @@ x-i18n: } ``` -- `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可定向的目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示无超时。 +- `model`：生成的子智能体默认使用的模型。如果省略，子智能体会继承调用方的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可定位的目标智能体 id 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 - 每个子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- -## 自定义提供商和 base URL +## 自定义 provider 和 base URL -OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 ```json5 { models: { - mode: "merge", // merge（默认） | replace + mode: "merge", // merge（默认）| replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -414,76 +414,76 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 ``` - - - 对于自定义认证需求，使用 `authHeader: true` + `headers`。 - - 使用 `OPENCLAW_AGENT_DIR`（或遗留环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 - - 对于匹配的提供商 ID，合并优先级如下： + + - 对于自定义身份验证需求，使用 `authHeader: true` + `headers`。 + - 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 + - 对于匹配的 provider ID，合并优先级如下： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在当前配置 / auth-profile 上下文中该提供商不是 SecretRef 托管时优先。 - - SecretRef 托管的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 - - SecretRef 托管的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`）。 - - 空的或缺失的智能体 `apiKey` / `baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow` / `maxTokens` 会在显式配置值与隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 在存在时会保留显式运行时上限；当你希望限制有效上下文而不更改模型原生元数据时可使用它。 + - 非空的智能体 `apiKey` 值仅在当前配置 / 身份配置档案上下文中该 provider 不由 SecretRef 管理时优先。 + - 由 SecretRef 管理的 provider `apiKey` 值会根据源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件 / exec 引用为 `secretref-managed`），而不会持久化已解析的密钥。 + - 由 SecretRef 管理的 provider 头部值会根据源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用为 `secretref-managed`）。 + - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间采用较高者。 + - 匹配模型的 `contextTokens` 在显式运行时上限存在时会保留它；使用它可在不更改模型原生元数据的情况下限制有效上下文。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。 -### 提供商字段详情 +### Provider 字段详情 - - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 - - `models.providers`：以提供商 id 为键的自定义提供商映射。 - - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 + - `models.mode`：provider 目录行为（`merge` 或 `replace`）。 + - `models.providers`：按 provider id 键控的自定义 provider 映射。 + - 安全编辑：对增量更新，使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge`。`config set` 会拒绝破坏性替换，除非你传入 `--replace`。 - + - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 - - `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef / 环境变量替换）。 - - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 - - `models.providers.*.contextWindow`：当模型条目未设置 `contextWindow` 时，该提供商下模型的默认原生上下文窗口。 - - `models.providers.*.contextTokens`：当模型条目未设置 `contextTokens` 时，该提供商下模型的默认有效运行时上下文上限。 - - `models.providers.*.maxTokens`：当模型条目未设置 `maxTokens` 时，该提供商下模型的默认输出 token 上限。 - - `models.providers.*.timeoutSeconds`：可选的每个提供商模型 HTTP 请求超时时间（秒），包括连接、响应头、响应体以及总请求中止处理。 + - `models.providers.*.apiKey`：provider 凭证（优先使用 SecretRef / 环境变量替换）。 + - `models.providers.*.auth`：身份验证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 + - `models.providers.*.contextWindow`：当模型条目未设置 `contextWindow` 时，此 provider 下模型的默认原生上下文窗口。 + - `models.providers.*.contextTokens`：当模型条目未设置 `contextTokens` 时，此 provider 下模型的默认有效运行时上下文上限。 + - `models.providers.*.maxTokens`：当模型条目未设置 `maxTokens` 时，此 provider 下模型的默认输出 token 上限。 + - `models.providers.*.timeoutSeconds`：可选的每个 provider 模型 HTTP 请求超时时间（秒），包括连接、头部、正文及整个请求中止处理。 - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 - - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 + - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 头传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 - - `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 + - `models.providers.*.headers`：用于代理 / 租户路由的额外静态头部。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖设置。 + `models.providers.*.request`：模型 provider HTTP 请求的传输覆盖设置。 - - `request.headers`：额外 headers（与提供商默认值合并）。值支持 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（全部支持 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：当为 `true` 时，若 DNS 解析为私有地址、CGNAT 或类似范围，则允许通过提供商 HTTP 抓取保护机制向 `baseUrl` 发起 HTTPS 请求（适用于受信任的自托管 OpenAI 兼容端点的运维人员选择启用）。WebSocket 使用相同的 `request` 处理 headers / TLS，但不使用该抓取 SSRF 防护门。默认值为 `false`。 + - `request.headers`：额外头部（与 provider 默认值合并）。值支持 SecretRef。 + - `request.auth`：身份验证策略覆盖。模式：`"provider-default"`（使用 provider 内置身份验证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选的 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段，则通过 provider HTTP 抓取保护允许对 `baseUrl` 进行 HTTPS 访问（这是面向受信任自托管 OpenAI 兼容端点的运维人员选择启用项）。WebSocket 使用相同的 `request` 处理头部 / TLS，但不使用该抓取 SSRF 防护门。默认值为 `false`。 - - `models.providers.*.models`：显式的提供商模型目录条目。 - - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。这会覆盖该模型的提供商级 `contextWindow`。 - - `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。这会覆盖提供商级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用；当两者不同，`openclaw models list` 会显示这两个值。 - - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空非原生值（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时将其强制设为 `false`。空的 / 省略的 `baseUrl` 会保留默认 OpenAI 行为。 - - `models.providers.*.models.*.compat.requiresStringContent`：针对仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组压平为普通字符串。 + - `models.providers.*.models`：显式的 provider 模型目录条目。 + - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。它会覆盖该模型的 provider 级 `contextWindow`。 + - `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。它会覆盖 provider 级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它；当两者不同，`openclaw models list` 会同时显示这两个值。 + - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生地址（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的 / 省略的 `baseUrl` 会保留默认 OpenAI 行为。 + - `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前，将纯文本的 `messages[].content` 数组展平为普通字符串。 - - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根路径。 + - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启 / 关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 - - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 id 过滤器。 + - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的 provider-id 过滤器，用于定向发现。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 - - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的后备最大输出 token 数。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 + - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 -### 提供商示例 +### Provider 示例 - 内置的 `cerebras` 提供商插件可通过 `openclaw onboard --auth-choice cerebras-api-key` 进行配置。仅当需要覆盖默认值时才使用显式提供商配置。 + 内置的 `cerebras` provider 插件可通过 `openclaw onboard --auth-choice cerebras-api-key` 进行配置。只有在需要覆盖默认值时，才使用显式 provider 配置。 ```json5 { @@ -533,11 +533,11 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` - 与 Anthropic 兼容的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 + 与 Anthropic 兼容的内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - 请参阅 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为后备。 + 请参阅 [本地模型](/zh-CN/gateway/local-models)。简而言之：在配置较强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 ```json5 @@ -574,7 +574,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` - 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅包含 M2.7。在与 Anthropic 兼容的流式路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认禁用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 + 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅包含 M2.7。在 Anthropic 兼容的流式路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。 @@ -611,9 +611,9 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` - 对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 + 对于中国区端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 - 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式使用兼容性，OpenClaw 会根据端点能力而不只是内置提供商 id 来进行判断。 + 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式传输使用兼容性，而 OpenClaw 会依据端点能力而不仅仅是内置 provider id 来判断这一点。 @@ -628,7 +628,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` - 设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 + 设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -665,7 +665,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 } ``` - Base URL 不应包含 `/v1`（Anthropic 客户端会自动追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 + Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -684,7 +684,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` - - 对于通用端点，请定义带有 base URL 覆盖项的自定义提供商。 + - 对于通用端点，请定义一个带有 base URL 覆盖的自定义 provider。 diff --git a/docs/zh-CN/nodes/audio.md b/docs/zh-CN/nodes/audio.md index 5dd53667e..e204a3b0a 100644 --- a/docs/zh-CN/nodes/audio.md +++ b/docs/zh-CN/nodes/audio.md @@ -1,38 +1,38 @@ --- read_when: - - 更改音频转录或媒体处理方式 -summary: 入站音频/语音消息如何被下载、转录并注入到回复中 -title: 音频与语音消息 + - 更改音频转录或媒体处理 +summary: 入站音频/语音便笺如何被下载、转录并注入到回复中 +title: 音频和语音便笺 x-i18n: - generated_at: "2026-04-27T07:11:46Z" + generated_at: "2026-04-27T11:10:44Z" model: gpt-5.4 provider: openai - source_hash: d2795f306a0095e2355b39cb600698d02076aba5a64ad5ba2a22f7752adbe5db + source_hash: bd987f4e7475b5c4e46fad9cf44385111ad229f12e4554a16b8f0fa91f7e9d8c source_path: nodes/audio.md workflow: 15 --- -# 音频 / 语音消息（2026-01-17） +# 音频 / 语音便笺（2026-01-17） -## 已支持的功能 +## 有效功能 -- **媒体理解（音频）**：如果启用了音频理解（或自动检测到可用能力），OpenClaw 会： +- **媒体理解（音频）**：如果启用了音频理解（或已自动检测到），OpenClaw 会： 1. 定位第一个音频附件（本地路径或 URL），并在需要时下载它。 - 2. 在发送到每个模型条目前先强制执行 `maxBytes` 限制。 + 2. 在发送给每个模型条目前强制执行 `maxBytes` 限制。 3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。 - 4. 如果失败或跳过（大小 / 超时），则尝试下一个条目。 - 5. 成功后，它会用一个 `[Audio]` 块替换 `Body`，并设置 `{{Transcript}}`。 -- **命令解析**：当转录成功时，`CommandBody` / `RawBody` 会被设置为转录文本，因此斜杠命令仍然可以工作。 -- **详细日志**：在 `--verbose` 模式下，我们会记录何时运行转录，以及何时替换消息正文。 + 4. 如果失败或跳过（大小/超时），则尝试下一个条目。 + 5. 成功后，它会用一个 `[Audio]` 区块替换 `Body`，并设置 `{{Transcript}}`。 +- **命令解析**：当转录成功时，`CommandBody`/`RawBody` 会被设置为转录文本，因此斜杠命令仍然可用。 +- **详细日志**：在 `--verbose` 模式下，我们会记录转录何时运行，以及何时替换正文。 ## 自动检测（默认） -如果你**没有配置模型**，并且 `tools.media.audio.enabled` **没有**被设置为 `false`， -OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后停止： +如果你**没有配置模型**，并且 `tools.media.audio.enabled` **未**设置为 `false`， +OpenClaw 会按以下顺序自动检测，并在第一个可用选项处停止： -1. **当前活动的回复模型**，前提是它的提供商支持音频理解。 +1. **当前活动回复模型**，前提是其提供商支持音频理解。 2. **本地 CLI**（如果已安装） - - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder / decoder / joiner / tokens） + - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder/decoder/joiner/tokens） - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型） - `whisper`（Python CLI；会自动下载模型） 3. **Gemini CLI**（`gemini`），使用 `read_many_files` @@ -42,7 +42,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 要禁用自动检测，请设置 `tools.media.audio.enabled: false`。 要自定义，请设置 `tools.media.audio.models`。 -注意：在 macOS / Linux / Windows 上，二进制检测都是尽力而为；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或者设置一个带有完整命令路径的显式 CLI 模型。 +注意：在 macOS/Linux/Windows 上，二进制检测是尽力而为的；请确保 CLI 位于 `PATH` 中（我们会展开 `~`），或设置带有完整命令路径的显式 CLI 模型。 ## 配置示例 @@ -70,7 +70,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 } ``` -### 仅提供商，并带有范围控制 +### 仅提供商，并带作用域限制 ```json5 { @@ -142,7 +142,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 media: { audio: { enabled: true, - echoTranscript: true, // 默认为 false + echoTranscript: true, // 默认是 false echoFormat: '📝 "{transcript}"', // 可选，支持 {transcript} models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }], }, @@ -153,69 +153,70 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 ## 说明与限制 -- 提供商凭证遵循标准模型凭证顺序（凭证配置文件、环境变量、`models.providers.*.apiKey`）。 -- Groq 的设置详情： [Groq](/zh-CN/providers/groq)。 +- 提供商凭证遵循标准模型认证顺序（auth profiles、环境变量、`models.providers.*.apiKey`）。 +- Groq 设置详情： [Groq](/zh-CN/providers/groq)。 - 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。 -- Deepgram 的设置详情： [Deepgram（音频转录）](/zh-CN/providers/deepgram)。 -- Mistral 的设置详情： [Mistral](/zh-CN/providers/mistral)。 +- Deepgram 设置详情： [Deepgram（音频转录）](/zh-CN/providers/deepgram)。 +- Mistral 设置详情： [Mistral](/zh-CN/providers/mistral)。 - 当使用 `provider: "senseaudio"` 时，SenseAudio 会读取 `SENSEAUDIO_API_KEY`。 -- SenseAudio 的设置详情： [SenseAudio](/zh-CN/providers/senseaudio)。 +- SenseAudio 设置详情： [SenseAudio](/zh-CN/providers/senseaudio)。 - 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。 -- 默认大小上限为 20 MB（`tools.media.audio.maxBytes`）。超出大小限制的音频会被该模型跳过，并尝试下一个条目。 -- 小型 / 空音频文件如果小于 1024 字节，会在提供商 / CLI 转录前被跳过。 -- 音频的默认 `maxChars` 为**未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或按条目设置 `maxChars` 可裁剪输出。 -- OpenAI 的自动默认模型是 `gpt-4o-mini-transcribe`；如需更高准确率，请设置 `model: "gpt-4o-transcribe"`。 -- 使用 `tools.media.audio.attachments` 处理多个语音消息（`mode: "all"` + `maxAttachments`）。 -- 转录文本可在模板中通过 `{{Transcript}}` 使用。 -- `tools.media.audio.echoTranscript` 默认关闭；启用后，会在智能体处理前将转录确认消息发送回原始聊天。 +- 默认大小上限为 20 MB（`tools.media.audio.maxBytes`）。超出大小的音频会针对该模型被跳过，并尝试下一个条目。 +- 小型/空音频文件如果小于 1024 字节，会在提供商/CLI 转录前被跳过。 +- 音频的默认 `maxChars` 为**未设置**（完整转录）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 可裁剪输出。 +- OpenAI 的自动默认模型为 `gpt-4o-mini-transcribe`；设置 `model: "gpt-4o-transcribe"` 可获得更高精度。 +- 使用 `tools.media.audio.attachments` 处理多个语音便笺（`mode: "all"` + `maxAttachments`）。 +- 转录文本可通过 `{{Transcript}}` 提供给模板。 +- `tools.media.audio.echoTranscript` 默认关闭；启用后会在智能体处理前，将转录确认消息发送回原始聊天。 - `tools.media.audio.echoFormat` 用于自定义回显文本（占位符：`{transcript}`）。 - CLI 标准输出有上限（5 MB）；请保持 CLI 输出简洁。 +- CLI 的 `args` 应使用 `{{MediaPath}}` 表示本地音频文件路径。旧版 `audio.transcription.command` 配置中的已弃用 `{input}` 占位符仍作为兼容别名被接受，并会迁移为 `{{MediaPath}}`。 ### 代理环境支持 -基于提供商的音频转录支持标准的出站代理环境变量： +基于提供商的音频转录支持标准出站代理环境变量： - `HTTPS_PROXY` - `HTTP_PROXY` - `https_proxy` - `http_proxy` -如果未设置代理环境变量，则使用直接出站连接。如果代理配置格式错误，OpenClaw 会记录一条警告，并回退为直接抓取。 +如果未设置代理环境变量，则使用直接出站连接。如果代理配置格式错误，OpenClaw 会记录警告并回退为直接抓取。 ## 群组中的提及检测 -当为群聊设置 `requireMention: true` 时，OpenClaw 现在会在检查提及之前**先**转录音频。这样即使语音消息中包含提及，也能被正确处理。 +当为群组聊天设置 `requireMention: true` 时，OpenClaw 现在会在检查提及**之前**先转录音频。这样即使语音便笺中包含提及，也可以被处理。 **工作方式：** -1. 如果语音消息没有文本正文，且群组要求提及，OpenClaw 会执行一次“预检”转录。 -2. 系统会检查转录文本中是否存在提及模式（例如 `@BotName`、表情触发器）。 -3. 如果发现提及，消息会继续进入完整的回复流水线。 -4. 转录文本会用于提及检测，从而让语音消息能够通过提及关卡。 +1. 如果一条语音消息没有文本正文，且群组要求提及，OpenClaw 会执行一次“预检”转录。 +2. 系统会检查转录文本中是否包含提及模式（例如 `@BotName`、表情符号触发器）。 +3. 如果发现提及，该消息会继续进入完整回复流水线。 +4. 转录文本会用于提及检测，因此语音便笺也可以通过提及门控。 **回退行为：** -- 如果预检期间转录失败（超时、API 错误等），消息会基于仅文本的提及检测继续处理。 -- 这样可以确保混合消息（文本 + 音频）不会被错误丢弃。 +- 如果预检期间的转录失败（超时、API 错误等），消息会基于仅文本的提及检测进行处理。 +- 这可确保混合消息（文本 + 音频）永远不会被错误丢弃。 -**按 Telegram 群组 / 话题选择退出：** +**按 Telegram 群组/话题选择退出：** -- 设置 `channels.telegram.groups..disableAudioPreflight: true`，即可跳过该群组的预检转录提及检查。 -- 设置 `channels.telegram.groups..topics..disableAudioPreflight`，即可按话题覆盖（`true` 表示跳过，`false` 表示强制启用）。 -- 默认值为 `false`（当提及门控条件匹配时启用预检）。 +- 设置 `channels.telegram.groups..disableAudioPreflight: true` 可跳过该群组的预检转录提及检查。 +- 设置 `channels.telegram.groups..topics..disableAudioPreflight` 可按话题覆盖（`true` 表示跳过，`false` 表示强制启用）。 +- 默认值为 `false`（当满足提及门控条件时启用预检）。 -**示例：** 用户在一个设置了 `requireMention: true` 的 Telegram 群组中发送一条语音消息，说“Hey @Claude, what's the weather?”。该语音消息会先被转录，随后检测到提及，智能体就会进行回复。 +**示例：** 用户在一个设置了 `requireMention: true` 的 Telegram 群组中发送一条语音便笺，内容是 “Hey @Claude, what's the weather?”。该语音便笺会被转录，检测到提及，然后智能体进行回复。 ## 注意事项 -- 范围规则遵循首个匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。 +- 作用域规则采用首个匹配优先。`chatType` 会被标准化为 `direct`、`group` 或 `room`。 - 请确保你的 CLI 以 0 退出并输出纯文本；如果输出 JSON，需要通过 `jq -r .text` 进行处理。 - 对于 `parakeet-mlx`，如果你传入 `--output-dir`，当 `--output-format` 为 `txt`（或省略）时，OpenClaw 会读取 `/.txt`；非 `txt` 输出格式会回退为解析标准输出。 - 请将超时设置保持在合理范围内（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。 -- 预检转录仅处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理中。 +- 预检转录仅处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理。 ## 相关内容 - [媒体理解](/zh-CN/nodes/media-understanding) -- [Talk mode](/zh-CN/nodes/talk) +- [Talk 模式](/zh-CN/nodes/talk) - [语音唤醒](/zh-CN/nodes/voicewake)