chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
bc1b00e064
commit
b9bc11a3a2
@ -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. **工作区钩子**：`<workspace>/hooks/`（每个智能体单独使用，默认禁用，需显式启用）
|
||||
3. **托管钩子**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录也具有相同优先级。
|
||||
4. **工作区钩子**：`<workspace>/hooks/`（按智能体划分，默认禁用，需显式启用）
|
||||
|
||||
工作区钩子可以新增钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。
|
||||
工作区钩子可以添加新的钩子名称，但不能覆盖同名的内置钩子、托管钩子或插件提供的钩子。
|
||||
|
||||
在配置内部钩子之前，Gateway 网关会在启动时跳过内部钩子发现。你可以通过 `openclaw hooks enable <name>` 启用一个内置或托管钩子，安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来主动启用。启用某个具名钩子后，Gateway 网关只会加载该钩子的处理器；而 `hooks.internal.enabled=true`、额外钩子目录和旧版处理器则会启用更广泛的发现机制。
|
||||
在配置内部钩子之前，Gateway 网关会在启动时跳过内部钩子发现。你可以使用 `openclaw hooks enable <name>` 启用一个内置或托管钩子、安装一个 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 <path-or-spec>
|
||||
```
|
||||
|
||||
npm spec 仅支持注册表来源（包名 + 可选精确版本或 dist-tag）。Git/URL/file spec 和 semver 范围都会被拒绝。
|
||||
npm 规格仅支持 registry（包名 + 可选的精确版本或 dist-tag）。Git/URL/file 规格和 semver 范围都会被拒绝。
|
||||
|
||||
## 内置钩子
|
||||
|
||||
| 钩子 | 事件 | 功能 |
|
||||
| 钩子 | 事件 | 功能说明 |
|
||||
| --------------------- | ------------------------------ | ----------------------------------------------------- |
|
||||
| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `<workspace>/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 <hook-name>
|
||||
|
||||
<a id="session-memory"></a>
|
||||
|
||||
### `session-memory` 详情
|
||||
### session-memory 详情
|
||||
|
||||
提取最近 15 条用户/assistant 消息，通过 LLM 生成描述性文件名 slug，并使用主机本地日期保存到 `<workspace>/memory/YYYY-MM-DD-slug.md`。要求配置 `workspace.dir`。
|
||||
提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，并使用主机本地日期保存到 `<workspace>/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。
|
||||
|
||||
<a id="bootstrap-extra-files"></a>
|
||||
|
||||
### `bootstrap-extra-files` 配置
|
||||
### bootstrap-extra-files 配置
|
||||
|
||||
```json
|
||||
{
|
||||
@ -198,26 +202,26 @@ openclaw hooks enable <hook-name>
|
||||
}
|
||||
```
|
||||
|
||||
路径相对于工作区解析。仅会加载已识别的 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`）。
|
||||
|
||||
<a id="command-logger"></a>
|
||||
|
||||
### `command-logger` 详情
|
||||
### command-logger 详情
|
||||
|
||||
将每个斜杠命令记录到 `~/.openclaw/logs/commands.log`。
|
||||
|
||||
<a id="boot-md"></a>
|
||||
|
||||
### `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 <hook-name>
|
||||
}
|
||||
```
|
||||
|
||||
额外钩子目录：
|
||||
额外的钩子目录：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -267,7 +271,7 @@ openclaw hooks enable <hook-name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
旧版 `hooks.internal.handlers` 数组配置格式仍然受支持，以保持向后兼容，但新钩子应使用基于发现的系统。
|
||||
为保持向后兼容，旧版的 `hooks.internal.handlers` 数组配置格式仍受支持，但新钩子应使用基于发现的系统。
|
||||
</Note>
|
||||
|
||||
## CLI 参考
|
||||
@ -289,8 +293,8 @@ openclaw hooks disable <hook-name>
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **保持处理器快速。** 钩子会在命令处理期间运行。对较重的工作请使用 `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)
|
||||
|
||||
@ -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` 之前设置基础允许列表：
|
||||
|
||||
<Note>
|
||||
本地新手引导会在未设置时，默认将新的本地配置设为 `tools.profile: "coding"`（现有的显式配置文件会被保留）。
|
||||
本地新手引导会在未设置时，默认将新的本地配置设为 `tools.profile: "coding"`（已显式设置的配置档案会被保留）。
|
||||
</Note>
|
||||
|
||||
| 配置文件 | 包含内容 |
|
||||
| 配置档案 | 包含内容 |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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:
|
||||
```
|
||||
|
||||
<ParamField path="historySize" type="number">
|
||||
为循环分析保留的最大工具调用历史记录。
|
||||
为循环分析保留的最大工具调用历史记录数量。
|
||||
</ParamField>
|
||||
<ParamField path="warningThreshold" type="number">
|
||||
用于发出警告的重复无进展模式阈值。
|
||||
@ -155,17 +155,17 @@ x-i18n:
|
||||
对任何无进展运行执行硬停止的阈值。
|
||||
</ParamField>
|
||||
<ParamField path="detectors.genericRepeat" type="boolean">
|
||||
对重复的同一工具 / 同一参数调用发出警告。
|
||||
对重复调用相同工具 / 相同参数的情况发出警告。
|
||||
</ParamField>
|
||||
<ParamField path="detectors.knownPollNoProgress" type="boolean">
|
||||
对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻止。
|
||||
</ParamField>
|
||||
<ParamField path="detectors.pingPong" type="boolean">
|
||||
对交替出现的无进展配对模式发出警告 / 阻止。
|
||||
对交替出现的成对无进展模式发出警告 / 阻止。
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证将失败。
|
||||
如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，则验证失败。
|
||||
</Warning>
|
||||
|
||||
### `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:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="媒体模型条目字段">
|
||||
**提供商条目**（`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`（旧版请求者会话唤醒 / 模型投递路径）。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -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:
|
||||
<Accordion title="可见性范围">
|
||||
- `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`。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -328,12 +328,12 @@ x-i18n:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="附件说明">
|
||||
- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。
|
||||
- 文件会被写入子工作区中的 `.openclaw/attachments/<uuid>/`，并附带一个 `.manifest.json`。
|
||||
- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。
|
||||
- 文件会在子工作区中实体化到 `.openclaw/attachments/<uuid>/`，并附带一个 `.manifest.json`。
|
||||
- 附件内容会自动从转录持久化中脱敏。
|
||||
- Base64 输入会使用严格的字母表 / 填充检查以及解码前大小保护进行验证。
|
||||
- 文件权限为：目录 `0700`，文件 `0600`。
|
||||
- 清理由 `cleanup` 策略决定：`delete` 始终会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。
|
||||
- Base64 输入会通过严格的字母表 / 填充检查以及解码前大小保护进行校验。
|
||||
- 目录权限为 `0700`，文件权限为 `0600`。
|
||||
- 清理遵循 `cleanup` 策略：`delete` 始终删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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/<agentId>/agent/models.json` 添加自定义提供商。
|
||||
OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents/<agentId>/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` 或
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="认证和合并优先级">
|
||||
- 对于自定义认证需求，使用 `authHeader: true` + `headers`。
|
||||
- 使用 `OPENCLAW_AGENT_DIR`（或遗留环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。
|
||||
- 对于匹配的提供商 ID，合并优先级如下：
|
||||
<Accordion title="身份验证和合并优先级">
|
||||
- 对于自定义身份验证需求，使用 `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"`。
|
||||
- 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 提供商字段详情
|
||||
### Provider 字段详情
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="顶层目录">
|
||||
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
|
||||
- `models.providers`：以提供商 id 为键的自定义提供商映射。
|
||||
- 安全编辑：使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。
|
||||
- `models.mode`：provider 目录行为（`merge` 或 `replace`）。
|
||||
- `models.providers`：按 provider id 键控的自定义 provider 映射。
|
||||
- 安全编辑：对增量更新，使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge`。`config set` 会拒绝破坏性替换，除非你传入 `--replace`。
|
||||
</Accordion>
|
||||
<Accordion title="提供商连接和认证">
|
||||
<Accordion title="Provider 连接和身份验证">
|
||||
- `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`：用于代理 / 租户路由的额外静态头部。
|
||||
</Accordion>
|
||||
<Accordion title="请求传输覆盖">
|
||||
`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`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="模型目录条目">
|
||||
- `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` 数组展平为普通字符串。
|
||||
</Accordion>
|
||||
<Accordion title="Amazon Bedrock 发现">
|
||||
- `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 数。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 提供商示例
|
||||
### Provider 示例
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Cerebras（GLM 4.7 / GPT OSS）">
|
||||
内置的 `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`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="本地模型（LM Studio）">
|
||||
请参阅 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为后备。
|
||||
请参阅 [本地模型](/zh-CN/gateway/local-models)。简而言之：在配置较强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax M2.7（直连）">
|
||||
```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`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot AI（Kimi）">
|
||||
@ -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 来判断这一点。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode">
|
||||
@ -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`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Synthetic（Anthropic 兼容）">
|
||||
@ -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`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Z.AI（GLM-4.7）">
|
||||
@ -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。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -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.<chatId>.disableAudioPreflight: true`，即可跳过该群组的预检转录提及检查。
|
||||
- 设置 `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight`，即可按话题覆盖（`true` 表示跳过，`false` 表示强制启用）。
|
||||
- 默认值为 `false`（当提及门控条件匹配时启用预检）。
|
||||
- 设置 `channels.telegram.groups.<chatId>.disableAudioPreflight: true` 可跳过该群组的预检转录提及检查。
|
||||
- 设置 `channels.telegram.groups.<chatId>.topics.<threadId>.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 会读取 `<output-dir>/<media-basename>.txt`；非 `txt` 输出格式会回退为解析标准输出。
|
||||
- 请将超时设置保持在合理范围内（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。
|
||||
- 预检转录仅处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理中。
|
||||
- 预检转录仅处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [媒体理解](/zh-CN/nodes/media-understanding)
|
||||
- [Talk mode](/zh-CN/nodes/talk)
|
||||
- [Talk 模式](/zh-CN/nodes/talk)
|
||||
- [语音唤醒](/zh-CN/nodes/voicewake)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user