diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 74c13ebdf..f9db755dd 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,34 +2,34 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值以及指向专用子系统参考文档的链接 +summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-23T23:21:48Z" + generated_at: "2026-04-24T02:20:28Z" model: gpt-5.4 provider: openai - source_hash: 8d5bcafbb701c326c027059de03c647eb9b2cf2bb1a543bc91c42b5deafa4378 + source_hash: 7014d49347f3fbcf941693c5c8776f65c9b6ac02582af94349fbd11d14233761 source_path: gateway/configuration-reference.md workflow: 15 --- -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -本页介绍 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供相应链接。它**不会**尝试在单个页面中内联每个由渠道/插件拥有的命令目录，或每个深层 memory/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 表面验证配置文档基线哈希 专用深度参考： -- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [Slash Commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件命令目录 -- 渠道特定命令面的所属渠道/插件页面 +- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash Commands](/zh-CN/tools/slash-commands)，查看当前内置 + 内置插件命令目录 +- 各自所属的渠道/插件页面，用于查看特定渠道的命令表面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 --- @@ -41,28 +41,28 @@ x-i18n: 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ------------------------------------------------ | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | --------------------------------------------------------------- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许列表存储） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---------------------------------------- | -| `allowlist`（默认） | 仅允许与配置的允许列表匹配的群组 | -| `open` | 绕过群组允许列表（仍然适用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ------------------------------------------------------ | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（但仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | `channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（失败关闭），并在启动时发出警告。 +配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未具有模型覆盖时（例如通过 `/model` 设置），才会应用此渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未设置模型覆盖时（例如通过 `/model` 设置），将应用该渠道映射。 ```json5 { @@ -85,7 +85,7 @@ x-i18n: ### 渠道默认值和心跳 -使用 `channels.defaults` 可为各个提供商设置共享的群组策略和心跳行为： +使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： ```json5 { @@ -103,7 +103,7 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时的后备群组策略。 +- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的后备群组策略。 - `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 - `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 @@ -111,7 +111,7 @@ x-i18n: ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联的会话时会自动启动。 ```json5 { @@ -162,9 +162,9 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 出站命令默认使用账号 `default`；如果不存在，则使用第一个已配置的账号 ID（按排序顺序）。 -- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配某个已配置账号 ID 时，覆盖该后备默认账号选择。 -- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 出站命令默认使用账号 `default`（若存在）；否则使用第一个已配置的账号 ID（按排序顺序）。 +- 可选的 `channels.whatsapp.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖该后备默认账号选择。 +- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -223,12 +223,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退使用 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当该值缺失或无效时，`openclaw doctor` 会发出警告。 -- `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中类型为 `type: "acp"` 的条目用于为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（可在私聊和群聊中工作）。 +- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 +- `configWrites: false` 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、`/config set|unset`）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为论坛主题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范格式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。 - 重试策略：参见 [Retry policy](/zh-CN/concepts/retry)。 ### Discord @@ -331,36 +331,36 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- Token：`channels.discord.token`，默认账号还可回退使用 `DISCORD_BOT_TOKEN`。 -- 提供显式 Discord `token` 的直接出站调用会使用该 token 执行调用；账号重试/策略设置仍然来自活动运行时快照中所选账号。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 使用 `user:`（私信）或 `channel:`（服务器频道）作为投递目标；不带前缀的纯数字 ID 会被拒绝。 -- 服务器 slug 为小写，空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。 -- 默认会忽略由机器人编写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及机器人的机器人消息（机器人自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃提及其他用户或角色、但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 个字符。 +- Token：`channels.discord.token`，默认账号还可回退到 `DISCORD_BOT_TOKEN`。 +- 对于直接出站调用，如果显式提供了 Discord `token`，该调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中所选账号。 +- 可选的 `channels.discord.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 对投递目标，使用 `user:`（私信）或 `channel:`（服务器频道）；不带前缀的纯数字 ID 会被拒绝。 +- 服务器 slug 使用小写，并将空格替换为 `-`；频道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。 +- 默认会忽略机器人自己发送的消息。`allowBots: true` 会启用这类消息；使用 `allowBots: "mentions"` 则仅接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- `channels.discord.guilds..ignoreOtherMentions`（以及频道级覆盖）会丢弃那些提及其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使消息长度未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：用于线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：用于不活动自动取消聚焦的 Discord 覆盖，单位为小时（`0` 表示禁用） - - `maxAgeHours`：用于硬性最大存续时间的 Discord 覆盖，单位为小时（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程启用的选择加入开关 -- 顶层 `bindings[]` 中类型为 `type: "acp"` 的条目用于为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 + - `enabled`：Discord 对线程绑定会话功能的覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） + - `idleHours`：Discord 对按小时计算的无活动自动取消聚焦的覆盖（`0` 表示禁用） + - `maxAgeHours`：Discord 对按小时计算的硬性最大时长的覆盖（`0` 表示禁用） + - `spawnSubagentSessions`：用于 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为频道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义与 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 共享。 - `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 - `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复发生解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 -- `channels.discord.autoPresence` 会将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（破玻璃兼容模式）。 -- `channels.discord.execApprovals`：原生 Discord exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。 +- `channels.discord.autoPresence` 将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到发起频道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析的审批人使用。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 + - `sessionFilter`：可选的会话键模式（子串或正则）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起频道，`"both"` 同时发送到两处。当 target 包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 -**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（所有消息中来自 `guilds..users` 的用户）。 +**反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中用户在所有消息上的反应）。 ### Google Chat @@ -391,11 +391,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（破玻璃兼容模式）。 +- 对投递目标，使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 ### Slack @@ -462,38 +462,34 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 - **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 - 字符串或 SecretRef 对象。 -- Slack 账号快照会公开按凭证划分的来源/状态字段，例如 - `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 - `signingSecretStatus`。`configured_unavailable` 表示该账号是通过 SecretRef - 配置的，但当前命令/运行时路径无法解析该 secret 值。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- Slack 账号快照会暴露按凭据划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析出该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 可选的 `channels.slack.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会自动迁移。 +- 对投递目标，使用 `user:`（私信）或 `channel:`。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或在频道内共享。`thread.inheritParent` 会将父频道转录复制到新线程。 +**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或在整个频道内共享。`thread.inheritParent` 会将父频道对话记录复制到新线程。 -- Slack 原生流式传输以及 Slack 助手风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持非线程，因此会使用 `typingReaction` 或常规投递，而不是线程样式预览。 -- `typingReaction` 会在回复运行期间为传入的 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：原生 Slack exec 审批投递和审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输加上 Slack 助手风格的 “is typing...” 线程状态需要一个回复线程目标。顶级私信默认保持非线程形式，因此它们会使用 `typingReaction` 或普通投递，而不是线程样式预览。 +- `typingReaction` 会在回复运行期间给传入的 Slack 消息临时添加一个反应，并在完成后移除。请使用 Slack 表情短代码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批投递和审批人授权。schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ---------- | ------- | -------------------- | -| reactions | 启用 | 反应 + 列出反应 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------- | ---------------------- | +| reactions | 已启用 | 添加反应 + 列出反应 | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 固定/取消固定/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义表情列表 | ### Mattermost -Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -523,21 +519,18 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是一个路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可访问。 -- 原生斜杠命令回调会使用 Mattermost 在斜杠命令注册期间返回的按命令划分 token 进行认证。如果注册失败或未激活任何命令，OpenClaw 会拒绝回调，并返回 - `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内网回调主机，Mattermost 可能要求 - `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 +- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的按命令划分 token 进行认证。如果注册失败或没有命令被激活，OpenClaw 会以 `Unauthorized: invalid command token.` 拒绝回调。 +- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。使用主机/域名值，不要使用完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 - `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。 -- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- `channels.mattermost.groups..requireMention`：按频道设置的提及门控覆盖（`"*"` 表示默认值）。 +- 可选的 `channels.mattermost.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 ### Signal @@ -562,7 +555,7 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` - `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 ### BlueBubbles @@ -582,13 +575,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 顶层 `bindings[]` 中类型为 `type: "acp"` 的条目可将 BlueBubbles 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 +- 可选的 `channels.bluebubbles.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 ### iMessage -OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。 ```json5 { @@ -612,15 +605,15 @@ OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 -- 需要对 Messages 数据库授予完整磁盘访问权限。 +- 需要对 Messages 数据库授予完全磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 -- `attachmentRoots` 和 `remoteAttachmentRoots` 用于限制传入附件路径（默认值：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以进行 SCP 附件获取。 +- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 +- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中类型为 `type: "acp"` 的条目可将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 @@ -664,20 +657,20 @@ Matrix 由插件支持，配置位于 `channels.matrix` 下。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 和此网络选择加入是彼此独立的控制项。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以通过 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许使用私有/内部 homeserver。`proxy` 和这个网络显式启用项是相互独立的控制项。 - `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并搭配 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：原生 Matrix exec 审批投递和审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，会激活 exec 审批。 +- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递和审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时会转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 + - `sessionFilter`：可选的会话键模式（子串或正则）。 - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 - `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归并为会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 +- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 ### Microsoft Teams @@ -697,7 +690,7 @@ Microsoft Teams 由插件支持，配置位于 `channels.msteams` 下。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭据、webhook、私信/群组策略、按团队/按频道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC @@ -723,12 +716,12 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 可在其与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -在每个渠道中运行多个账号（每个都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -749,28 +742,28 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -- 省略 `accountId` 时会使用 `default`（CLI + 路由）。 +- 省略 `accountId` 时使用 `default`（CLI + 路由）。 - 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用于所有账号，除非在账号级别覆盖。 -- 使用 `bindings[].match.accountId` 可将每个账号路由到不同的智能体。 -- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账号，OpenClaw 会先将按账号划分的顶层单账号值提升到渠道账号映射中，以便原始账号继续工作。多数渠道会将这些值移至 `channels..accounts.default`；而 Matrix 则可以改为保留现有匹配的命名/default 目标。 -- 现有仅按渠道生效的绑定（无 `accountId`）将继续匹配默认账号；按账号划分的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将按账号划分的顶层单账号值移入该渠道选定的提升后账号，来修复混合形态。多数渠道使用 `accounts.default`；而 Matrix 则可以改为保留现有匹配的命名/default 目标。 +- 基础渠道设置会应用于所有账号，除非被按账号设置覆盖。 +- 使用 `bindings[].match.accountId` 可将每个账号路由到不同智能体。 +- 如果你在仍为单账号顶层渠道配置的情况下，通过 `openclaw channels add`（或渠道新手引导）添加了一个非默认账号，OpenClaw 会先将具备账号作用域的顶层单账号值提升到该渠道的账号映射中，这样原始账号仍能继续工作。大多数渠道会将其移动到 `channels..accounts.default`；而 Matrix 则可以保留现有匹配的命名/default 目标。 +- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；账号级绑定仍是可选的。 +- `openclaw doctor --fix` 也会通过将具备账号作用域的顶层单账号值移动到该渠道所选的提升后账号中来修复混合形状。大多数渠道使用 `accounts.default`；而 Matrix 则可以保留现有匹配的命名/default 目标。 -### 其他插件渠道 +### 其他渠道插件 -许多插件渠道都配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参阅完整渠道索引：[Channels](/zh-CN/channels)。 +许多渠道插件都配置为 `channels.`，并在各自专用的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +查看完整渠道索引： [Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：原生平台 @ 提及。在 WhatsApp 自聊模式下会被忽略。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat mode 下会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当能够检测到提及时才会强制执行提及门控（原生提及或至少一个模式）。 +- 只有在能够检测时才会强制执行提及门控（原生提及或至少一个模式）。 ```json5 { @@ -783,7 +776,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。各渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号配置）覆盖。设置为 `0` 可禁用。 #### 私信历史限制 @@ -800,13 +793,13 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（保留全部）。 +解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### 自聊模式 +#### self-chat mode -将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码包含在 `allowFrom` 中即可启用 self-chat mode（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -827,7 +820,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -### Commands（聊天命令处理） +### 命令（聊天命令处理） ```json5 { @@ -856,32 +849,32 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 -- 此配置块用于配置命令面。当前内置 + 内置插件命令目录，请参阅 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键参考**，不是完整的命令目录。诸如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 等由渠道/插件拥有的命令，记录在各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 此配置块用于配置命令表面。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。由渠道/插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice`，记录在其各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 - 文本命令必须是带前导 `/` 的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而对 Slack 保持关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，而对 Slack 保持关闭。 -- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 -- 使用 `channels..commands.nativeSkills` 可按渠道覆盖原生 Skills 注册。 -- `channels.telegram.customCommands` 可添加额外的 Telegram 机器人菜单项。 +- `native: "auto"` 会为 Discord/Telegram 打开原生命令，对 Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，对 Slack 保持关闭。 +- 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除之前已注册的命令。 +- 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 - `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已启用，且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化 `/config set|unset` 写入还需要 `operator.admin`；只读的 `/config show` 对普通写作用域的 operator 客户端仍然可用。 +- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写作用域的 operator 客户端仍然可用。 - `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 会启用 `/plugins`，用于插件发现、安装和启用/禁用控制。 -- `channels..configWrites` 控制每个渠道是否允许配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会控制针对该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用/禁用控制。 +- `channels..configWrites` 控制每个渠道上的配置变更权限（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 - `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在 system prompt 中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希行为。 -- `allowFrom` 按提供商配置。设置后，它会成为**唯一**的授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 会在未设置 `allowFrom` 时，让命令绕过访问组策略。 +- `ownerAllowFrom` 是所有者专用命令/工具的显式所有者允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对所有者 ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希方式。 +- `allowFrom` 是按提供商配置的。设置后，它会成为**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 会在 `allowFrom` 未设置时允许命令绕过 access-group 策略。 - 命令文档映射： - - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令面：[Channels](/zh-CN/channels) - - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[Pairing](/zh-CN/channels/pairing) - - LINE 卡片命令：[LINE](/zh-CN/channels/line) - - memory Dreaming：[Dreaming](/zh-CN/concepts/dreaming) + - 内置 + 内置插件目录： [Slash Commands](/zh-CN/tools/slash-commands) + - 渠道专用命令表面： [Channels](/zh-CN/channels) + - QQ Bot 命令： [QQ Bot](/zh-CN/channels/qqbot) + - 配对命令： [Pairing](/zh-CN/channels/pairing) + - LINE 卡片命令： [LINE](/zh-CN/channels/line) + - memory dreaming： [Dreaming](/zh-CN/concepts/dreaming) @@ -901,7 +894,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在 system prompt 的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从 workspace 向上遍历并自动检测。 ```json5 { @@ -911,8 +904,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.skills` -未设置 -`agents.list[].skills` 的智能体可使用的可选默认 Skills 允许列表。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 ```json5 { @@ -927,15 +919,14 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 } ``` -- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。 -- 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示没有 Skills。 -- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它 - 不会与默认值合并。 +- 省略 `agents.defaults.skills` 时，默认 Skills 不受限制。 +- 省略 `agents.list[].skills` 时，会继承默认值。 +- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建 workspace bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -945,9 +936,9 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入 system prompt。默认值：`"always"`。 +控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续写轮次（在 assistant 响应完成后）会跳过工作区 bootstrap 的重新注入，从而减少 prompt 大小。心跳运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续接轮次（在 assistant 完成响应之后）会跳过重新注入 workspace bootstrap，从而减小提示大小。心跳运行和压缩后重试仍会重建上下文。 ```json5 { @@ -957,7 +948,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -单个工作区 bootstrap 文件在截断前允许的最大字符数。默认值：`12000`。 +每个 workspace bootstrap 文件在被截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -967,7 +958,7 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件总共注入的最大字符数。默认值：`60000`。 +所有 workspace bootstrap 文件合计注入的最大总字符数。默认值：`60000`。 ```json5 { @@ -977,12 +968,11 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，对智能体可见的警告文本。 -默认值：`"once"`。 +控制在 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：绝不将警告文本注入 system prompt。 +- `"off"`：绝不将警告文本注入系统提示。 - `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时注入警告。 +- `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 { @@ -992,33 +982,29 @@ IRC 由插件支持，配置位于 `channels.irc` 下。 ### 上下文预算归属映射 -OpenClaw 具有多个高容量 prompt/上下文预算，并且它们会 -按子系统刻意拆分，而不是全部流经一个通用 -调节项。 +OpenClaw 有多个高容量提示/上下文预算，并且这些预算会按子系统有意拆分，而不是全部流经一个通用调节项。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 常规工作区 bootstrap 注入。 + 常规 workspace bootstrap 注入。 - `agents.defaults.startupContext.*`： 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入 system prompt 的紧凑 Skills 列表。 + 注入到系统提示中的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： 有界的运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引的 memory 搜索片段和注入大小控制。 + 已索引 memory 搜索片段和注入大小控制。 -仅当某个智能体需要不同 -预算时，才使用对应的按智能体覆盖： +仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` -运行时注入的首轮启动前导内容。 +控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -1039,7 +1025,7 @@ OpenClaw 具有多个高容量 prompt/上下文预算，并且它们会 #### `agents.defaults.contextLimits` -有界运行时上下文面的共享默认值。 +为有界运行时上下文表面提供共享默认值。 ```json5 { @@ -1056,16 +1042,14 @@ OpenClaw 具有多个高容量 prompt/上下文预算，并且它们会 } ``` -- `memoryGetMaxChars`：默认 `memory_get` 摘录上限，超过后才会附加截断 - 元数据和续写提示。 -- `memoryGetDefaultLines`：省略 `lines` 时默认的 `memory_get` 行窗口。 +- `memoryGetMaxChars`：在添加截断元数据和续接提示前，`memory_get` 摘录的默认上限。 +- `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 默认使用的行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 - `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。 #### `agents.list[].contextLimits` -用于共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承 -自 `agents.defaults.contextLimits`。 +对共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 ```json5 { @@ -1091,8 +1075,7 @@ OpenClaw 具有多个高容量 prompt/上下文预算，并且它们会 #### `skills.limits.maxSkillsPromptChars` -注入 system prompt 的紧凑 Skills 列表的全局上限。此项 -不会影响按需读取 `SKILL.md` 文件。 +注入到系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -1106,7 +1089,7 @@ OpenClaw 具有多个高容量 prompt/上下文预算，并且它们会 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills prompt 预算的按智能体覆盖。 +针对 Skills 提示预算的按智能体覆盖。 ```json5 { @@ -1125,11 +1108,11 @@ Skills prompt 预算的按智能体覆盖。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，transcript/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量以及以截图为主运行时的请求负载大小。 -较高的值则可保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量和以截图为主的运行中的请求负载大小。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -1139,7 +1122,7 @@ Skills prompt 预算的按智能体覆盖。 ### `agents.defaults.userTimezone` -用于 system prompt 上下文的时区（不是消息时间戳）。会回退到主机时区。 +系统提示上下文所用的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -1149,7 +1132,7 @@ Skills prompt 预算的按智能体覆盖。 ### `agents.defaults.timeFormat` -system prompt 中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -1206,50 +1189,51 @@ system prompt 中的时间格式。默认值：`auto`（操作系统偏好）。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 字符串形式只设置主模型。 - - 对象形式会设置主模型以及按顺序排列的故障切换模型。 -- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 由 `image` 工具路径用作其视觉模型配置。 - - 当所选/默认模型无法接受图像输入时，也用作回退路由。 -- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 由共享图像生成能力以及未来任何生成图像的工具/插件面使用。 - - 典型值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal），或 `openai/gpt-image-2`（用于 OpenAI Images）。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证（例如 `google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 对应 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 对应 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个由认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 由共享音乐生成能力和内置 `music_generate` 工具使用。 - - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出一个由认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API 密钥。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 由共享视频生成能力和内置 `video_generate` 工具使用。 - - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出一个由认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API 密钥。 +- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 字符串形式仅设置主模型。 + - 对象形式会设置主模型以及按顺序排列的故障转移模型。 +- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由 `image` 工具路径作为其视觉模型配置使用。 + - 当已选/默认模型无法接受图像输入时，也会用作回退路由。 +- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享图像生成功能以及任何未来会生成图像的工具/插件表面使用。 + - 常见取值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证（例如 `google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 对应 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 对应 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出一个有认证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享音乐生成功能和内置 `music_generate` 工具使用。 + - 常见取值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 + - 如果省略，`music_generate` 仍可推断出一个有认证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key。 +- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 由共享视频生成功能和内置 `video_generate` 工具使用。 + - 常见取值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 + - 如果省略，`video_generate` 仍可推断出一个有认证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 +- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，`pdf` 工具使用的默认 PDF 大小限制。 + - 如果省略，PDF 工具会先回退到 `imageModel`，然后回退到已解析的会话/默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认提升输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4` 表示 API 密钥访问，或 `openai-codex/gpt-5.5` 表示 Codex OAuth）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式的 `provider/model`）。如果该提供商不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个已移除提供商的过时默认值。 -- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。 - - 按提供商划分的 configure/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的其他无关提供商。 -- `params`：应用到所有模型的全局默认提供商参数。设置于 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 认领受支持模型，使用 `runtime: "pi"` 可强制使用内置 Pi harness，或使用已注册 harness ID，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 Pi 回退。 -- 修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/删除命令）会保存规范对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍串行）。默认值：4。 +- `elevatedDefault`：智能体的默认 elevated 输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 API key 访问使用 `openai/gpt-5.4`，Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续使用过时的已移除提供商默认值。 +- `models`：用于 `/model` 的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。 + - 提供商作用域的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的其他无关提供商。 + - 对于直接使用 OpenAI Responses 的模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI server-side compaction](/zh-CN/providers/openai#server-side-compaction-responses-api)。 +- `params`：应用到所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）再按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 可让已注册插件 harness 接管受支持的模型，使用 `runtime: "pi"` 可强制使用内置 Pi harness，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 Pi 回退。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和故障转移 add/remove 命令）会保存规范的对象形式，并尽可能保留现有的故障转移列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍是串行）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 -大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 -当受信任的插件提供原生 harness 时可使用它，例如内置的 +`embeddedHarness` 控制由哪个底层执行器运行嵌入式智能体轮次。 +大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 +当受信任插件提供原生 harness 时可使用它，例如内置的 Codex app-server harness。 ```json5 @@ -1266,20 +1250,20 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册插件 harness ID。内置 Codex 插件注册了 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会在未选择任何插件 harness 时保留内置 Pi harness 作为兼容性回退。`"none"` 会让缺失或不受支持的插件 harness 选择直接失败，而不是静默使用 Pi。已选择的插件 harness 若失败，则始终会直接暴露。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件注册的 id 是 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会在未选中任何插件 harness 时保留内置 Pi harness 作为兼容性回退。`"none"` 会让缺失或不受支持的插件 harness 选择直接失败，而不是静默使用 Pi。所选插件 harness 的失败始终会直接暴露。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 Pi 回退。 -- 对于仅 Codex 的部署，请设置 `model: "openai/gpt-5.5"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 在第一次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变量的更改只影响新会话或已重置会话，不影响现有 transcript。带有 transcript 历史但没有记录固定值的旧会话会被视为固定到 Pi。`/status` 会在 `Fast` 旁显示非 Pi 的 harness ID，例如 `codex`。 -- 此项仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider/model 设置。 +- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 在第一次嵌入式运行后，harness 选择会按会话 id 固定。配置/环境变量变更会影响新的或已重置的会话，不会影响现有转录。具有转录历史但未记录固定值的旧会话会被视为固定为 Pi。`/status` 会在 `Fast` 旁显示非 Pi 的 harness id，例如 `codex`。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 -**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： +**内置别名简写**（仅在模型存在于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | +| Alias | 模型 | | ------------------- | -------------------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` 或已配置的 Codex OAuth GPT-5.5 | +| `gpt` | `openai/gpt-5.4` 或已配置的 Codex OAuth GPT-5.5 | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | @@ -1288,13 +1272,13 @@ Codex app-server harness。 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 +Z.AI GLM-4.x 模型会自动启用 thinking mode，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。 +用于仅文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备份。 ```json5 { @@ -1322,13 +1306,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本优先；工具始终禁用。 +- CLI 后端以文本为主；工具始终禁用。 - 设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的 system prompt。可设置在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控 prompt 实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体级别（`agents.list[].systemPromptOverride`）设置。按智能体设置的值优先；空值或仅含空白字符的值会被忽略。适用于受控的提示实验。 ```json5 { @@ -1342,7 +1326,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.promptOverlays` -按模型家族应用的、与提供商无关的 prompt 覆盖层。GPT-5 家族模型 ID 会在各提供商间获得共享行为契约；`personality` 仅控制友好交互风格这一层。 +按模型家族应用的、与提供商无关的提示覆盖。GPT-5 系列模型 id 会在不同提供商间共享同一行为契约；`personality` 仅控制友好交互风格层。 ```json5 { @@ -1359,12 +1343,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `"friendly"`（默认）和 `"on"` 会启用友好交互风格层。 -- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 +- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 - 当这个共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` -周期性心跳运行。 +定期心跳运行。 ```json5 { @@ -1391,15 +1375,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：为 false 时，会省略 system prompt 中的 Heartbeat 段，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：在中止前，单次心跳智能体轮次允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会省略系统提示中的 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：heartbeat 智能体轮次在被中止前允许的最长秒数。留空时使用 `agents.defaults.timeoutSeconds`。 - `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：为 true 时，心跳运行会使用轻量 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在一个全新的会话中运行，不带任何先前对话历史。隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降低到约 2-5K token。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。 -- 心跳会运行完整的智能体轮次 —— 间隔越短，消耗的 token 越多。 +- `lightContext`：为 true 时，heartbeat 运行会使用轻量 bootstrap 上下文，并且只保留 workspace bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次 heartbeat 都会在一个全新的会话中运行，不带任何先前的对话历史。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2-5K token。 +- 按智能体配置：设置 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 +- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。 ### `agents.defaults.compaction` @@ -1429,19 +1413,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（适用于长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 +- `mode`：`default` 或 `safeguard`（用于长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方式。设置提供商会强制启用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后重新注入的可选 AGENTS.md H2/H3 段名称。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型，而 compaction 摘要应在另一个模型上运行时使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如“正在压缩上下文...”和“上下文压缩完成”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 之前执行的静默智能体轮次，用于存储持久 memory。工作区为只读时会跳过。 +- `postCompactionSections`：compaction 后可选的 AGENTS.md H2/H3 节名称重注入列表。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重注入。未设置时，或显式设置为这对默认值时，旧版 `Every Session`/`Safety` 标题也会作为兼容旧版的回退被接受。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型，而 compaction 摘要应使用另一个模型时可使用该项；未设置时，compaction 会使用会话的主模型。 +- `notifyUser`：当为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：在自动 compaction 前执行静默智能体轮次，以存储持久 memory。workspace 为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存中的上下文里修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1465,23 +1449,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制多久之后才能再次运行修剪（自上次缓存触达后计算）。 -- 修剪会先对过大的工具结果执行软修剪，如仍有需要，再对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用修剪流程。 +- `ttl` 控制下次允许再次修剪的时间间隔（自上次缓存触碰后计算）。 +- 修剪会先对过大的工具结果执行软修剪，如有需要再对较旧的工具结果执行硬清除。 **软修剪**会保留开头和结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +说明： - 图像块永远不会被修剪/清除。 -- 比例基于字符数（近似），不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 各比例基于字符数（近似值），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过修剪。 -行为详情请参阅 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为详情参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1499,11 +1483,11 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 - `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参阅 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 ### 输入中指示器 @@ -1518,7 +1502,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：对私聊/提及使用 `instant`，对未提及的群聊使用 `message`。 +- 默认值：私聊/提及时为 `instant`，未提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1527,7 +1511,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参阅 [Sandboxing](/zh-CN/gateway/sandboxing)。 +用于嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1627,7 +1611,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 支持的远程运行时 +- `ssh`：通用的 SSH 支持远程运行时 - `openshell`：OpenShell 运行时 选择 `backend: "openshell"` 时，运行时特定设置会移动到 @@ -1637,9 +1621,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按范围工作区的绝对远程根目录 +- `workspaceRoot`：用于按作用域 workspace 的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时实体化为临时文件的内联内容或 SecretRef +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 会在运行时将其实体化为临时文件的内联内容或 SecretRef - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略调节项 **SSH 认证优先级：** @@ -1647,27 +1631,27 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从活动 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重新创建后，只对远程工作区执行一次初始化 -- 随后将远程 SSH 工作区保持为规范副本 +- 在创建或重建后对远程 workspace 执行一次初始化植入 +- 然后保持远程 SSH workspace 为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 -**工作区访问：** +**workspace 访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下的按范围沙箱工作区 -- `ro`：沙箱工作区挂载到 `/workspace`，智能体工作区以只读方式挂载到 `/agent` -- `rw`：智能体工作区以读写方式挂载到 `/workspace` +- `none`：在 `~/.openclaw/sandboxes` 下使用按作用域划分的沙箱 workspace +- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` +- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` -**范围：** +**作用域：** -- `session`：每个会话一个容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） -- `shared`：共享容器和工作区（无跨会话隔离） +- `session`：每个会话一个容器 + workspace +- `agent`：每个智能体一个容器 + workspace（默认） +- `shared`：共享容器和 workspace（无跨会话隔离） **OpenShell 插件配置：** @@ -1697,29 +1681,29 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在 exec 之前将远程端与本地同步，在 exec 之后再同步回本地；本地工作区保持为规范副本 -- `remote`：在创建沙箱时只向远程端初始化一次，之后保持远程工作区为规范副本 +- `mirror`：在执行前将远程端与本地同步种子化，执行后再同步回本地；本地 workspace 保持为规范副本 +- `remote`：在创建沙箱时仅对远程端执行一次种子化，然后保持远程 workspace 为规范副本 -在 `remote` 模式下，初始化之后，在 OpenClaw 外部于主机本地所做的编辑不会自动同步进沙箱。 -传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。 +在 `remote` 模式下，种子化步骤完成后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步进沙箱。 +传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 被阻止。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破玻璃模式）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请将其设置为 `"bridge"`（或自定义 bridge 网络）。 +`"host"` 会被阻止。默认情况下，`"container:"` 也会被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行模式）。 -**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**传入附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入 system prompt。无需在 `openclaw.json` 中启用 `browser.enabled`。 -默认使用 VNC 认证来提供 noVNC 观察者访问，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入系统提示。无需在 `openclaw.json` 中启用 `browser.enabled`。 +默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选择在容器边界处将 CDP 入口限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅会将额外主机目录挂载到沙箱隔离浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 +- `network` 默认值为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确希望获得全局 bridge 连接时才设置为 `bridge`。 +- `cdpSourceRange` 可选地在容器边界将 CDP 入口限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 - 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -1740,14 +1724,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL/3D 使用场景需要，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 将其禁用。 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 - 如果你的工作流依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设置为 `0` 则使用 Chromium 的 - 默认进程限制。 - - 并且在启用 `noSandbox` 时还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值属于容器镜像基线；若要更改容器默认值，请使用带有自定义 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 将使用 Chromium 的 + 默认进程上限。 + - 另外，在启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 entrypoint 的自定义浏览器镜像。 @@ -1810,27 +1794,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`：稳定的智能体 ID（必填）。 -- `default`：设置多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 可禁用全局 fallbacks）。仅覆盖 `primary` 的 cron 任务仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。 -- `params`：按智能体划分的流式参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用于为特定智能体覆盖如 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，当设置了 `agents.defaults.skills` 时，智能体会继承该值；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，它会覆盖此智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。当未设置按消息或按会话的 fast-mode 覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某一个智能体仅使用 Codex，而其他智能体保留默认的 Pi 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 +- `id`：稳定的智能体 id（必填）。 +- `default`：当设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖二者（`[]` 会禁用全局故障转移）。仅覆盖 `primary` 的 cron 作业仍会继承默认故障转移，除非你设置 `fallbacks: []`。 +- `params`：按智能体设置的流参数，会合并覆盖到 `agents.defaults.models` 中所选模型条目之上。用于为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。若省略，则该智能体会在已设置的情况下继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。在未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。在未设置按消息或按会话 reasoning 覆盖时生效。 +- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。在未设置按消息或按会话 fast-mode 覆盖时生效。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体仍保留默认的 Pi 回退。 +- `runtime`：可选的按智能体 runtime 描述符。当某个智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：相对于 workspace 的路径、`http(s)` URL 或 `data:` URI。 - `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：`sessions_spawn` 可用的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝将目标运行在无沙箱模式下。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 - `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1849,12 +1833,12 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：`route` 表示常规路由（缺失时默认值为 route），`acp` 表示持久 ACP 会话绑定。 +- `type`（可选）：普通路由使用 `route`（缺失时默认视为 route），持久 ACP 会话绑定使用 `acp` - `match.channel`（必填） - `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） - `match.guildId` / `match.teamId`（可选；渠道特定） -- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1862,14 +1846,14 @@ scripts/sandbox-browser-setup.sh # optional browser image 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（渠道级） +5. `match.accountId: "*"`（全渠道） 6. 默认智能体 -在同一层级内，第一个匹配的 `bindings` 条目获胜。 +在每一层中，首个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 -### 按智能体划分的访问配置 +### 按智能体访问配置文件 @@ -1889,7 +1873,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1964,7 +1948,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -优先级详情请参阅 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [Multi-Agent 沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -2018,34 +2002,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：每个发送者在渠道上下文内拥有独立会话。 - - `global`：渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在渠道上下文中，每个发送者都会获得独立会话。 + - `global`：渠道上下文中的所有参与者共享一个会话（仅当你确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 ID 跨渠道隔离。 + - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，以实现跨渠道会话共享。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都配置，则先到期者生效。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 - **`parentForkMaxTokens`**：创建分叉线程会话时，允许的父会话 `totalTokens` 最大值（默认 `100000`）。 - - 如果父会话的 `totalTokens` 超过此值，OpenClaw 会启动一个全新的线程会话，而不是继承父 transcript 历史。 - - 设置为 `0` 可禁用此保护，并始终允许父会话分叉。 -- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间在 agent-to-agent 交换期间允许的最大往返回复轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式交互。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。第一个 deny 优先生效。 + - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。 + - 设置为 `0` 可禁用此保护，并始终允许父级分叉。 +- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间在智能体对智能体交互期间允许的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链接。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：陈旧条目的年龄截止时间（默认 `30d`）。 + - `pruneAfter`：陈旧条目的时间截断点（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` transcript 归档的保留时间。默认继承 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录硬磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认值为 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认不活动自动取消聚焦时长，单位小时（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认硬性最大存续时间，单位小时（`0` 表示禁用；提供商可覆盖） + - `idleHours`：默认的按小时计算的无活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认的按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖） @@ -2089,30 +2073,30 @@ scripts/sandbox-browser-setup.sh # optional browser image **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | -------------- | --------------------------- | -| `{model}` | 短模型名 | `claude-opus-4-6` | +| Variable | 说明 | 示例 | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | 短模型名称 | `claude-opus-4-6` | | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | +| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认取活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，会在回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时若确认反应处于激活状态，则保持状态反应启用。 - 在 Telegram 上，需要显式将其设置为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时如果确认反应处于启用状态，则会保持状态反应启用。 + 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 -### 传入去抖动 +### 入站去抖 -将来自同一发送者的快速纯文本消息批处理为一个智能体轮次。媒体/附件会立即冲刷。控制命令会绕过去抖动。 +将来自同一发送者的快速纯文本消息批处理为一次智能体轮次。媒体/附件会立即冲刷。控制命令会绕过去抖处理。 ### TTS（文本转语音） @@ -2155,18 +2139,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示实际生效状态。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。 - `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式选择加入）。 -- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置、然后 `OPENAI_TTS_BASE_URL`、最后 `https://api.openai.com/v1`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认值为 `false`（需显式启用）。 +- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置、然后 `OPENAI_TTS_BASE_URL`、最后是 `https://api.openai.com/v1`。 - 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。 --- ## Talk -Talk 模式（macOS/iOS/Android）的默认值。 +Talk mode 的默认值（macOS/iOS/Android）。 ```json5 { @@ -2190,13 +2174,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会被自动迁移到 `talk.providers.`。 -- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 +- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅在未配置 Talk API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退。 +- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久再发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `silenceTimeoutMs` 控制 Talk mode 在用户静默后等待多久再发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -2204,37 +2188,37 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（已有的显式 profile 会被保留）。 +本地新手引导会在未设置时，默认将新本地配置设为 `tools.profile: "coding"`（已有显式配置文件会被保留）。 -| 配置文件 | 包含内容 | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| 配置文件 | 包含内容 | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 不限制（与未设置相同） | ### 工具组 -| 组 | 工具 | -| ------------------ | --------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| 组 | 工具 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group: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 插件） | +| `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 沙箱已关闭，也会应用。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭也会应用。 ```json5 { @@ -2244,7 +2228,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -进一步限制特定 provider 或模型可用的工具。顺序：基础 profile → provider profile → allow/deny。 +进一步限制特定提供商或模型可用的工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 ```json5 { @@ -2260,7 +2244,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.elevated` -控制沙箱外部的提升 exec 访问： +控制沙箱外的 elevated exec 访问： ```json5 { @@ -2277,8 +2261,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令只对单条消息生效。 -- 提升后的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，当 exec 目标是 `node` 时则为 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认 `gateway`，如果 exec 目标是 `node` 则使用 `node`）。 ### `tools.exec` @@ -2302,8 +2286,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` -工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 -设置可以在全局 `tools.loopDetection` 中定义，也可以在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查**默认禁用**。设置 `enabled: true` 可激活检测。 +设置可在 `tools.loopDetection` 中全局定义，并可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 ```json5 { @@ -2324,13 +2308,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史数。 -- `warningThreshold`：触发警告的重复无进展模式阈值。 +- `historySize`：用于循环分析而保留的最大工具调用历史。 +- `warningThreshold`：用于发出警告的重复无进展模式阈值。 - `criticalThreshold`：用于阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：针对任意无进展运行的硬停止阈值。 +- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 - `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展轮询发出警告/阻止。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 - 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2365,7 +2349,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.media` -配置传入媒体理解（图像/音频/视频）： +配置入站媒体理解（图像/音频/视频）： ```json5 { @@ -2399,10 +2383,10 @@ Talk 模式（macOS/iOS/Android）的默认值。 -**Provider 条目**（`type: "provider"` 或省略）： +**提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 ID 覆盖 +- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `model`：模型 id 覆盖 - `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2421,8 +2405,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 **异步完成字段：** - `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会先尝试直接投递到渠道。默认值：`false` - （旧版请求方会话唤醒/模型投递路径）。 + 和 `video_generate` 任务会优先尝试直接投递到渠道。默认值：`false` + （旧版的请求方会话唤醒/模型投递路径）。 @@ -2441,9 +2425,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 +控制哪些会话可被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 -默认值：`tree`（当前会话 + 由它派生的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 ```json5 { @@ -2459,10 +2443,10 @@ Talk 模式（macOS/iOS/Android）的默认值。 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 由当前会话派生的会话（子智能体）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在同一个智能体 ID 下运行按发送者划分的会话，则可能包含其他用户）。 -- `all`：任意会话。跨智能体定位仍然需要 `tools.agentToAgent`。 -- 沙箱限制：当当前会话处于沙箱隔离中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一智能体 id 下运行按发送者分组的会话，也可能包含其他用户）。 +- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 +- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2486,18 +2470,18 @@ Talk 模式（macOS/iOS/Android）的默认值。 说明： -- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 -- 文件会实体化到子工作区中的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 -- 附件内容会自动从 transcript 持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充检查以及解码前大小保护进行验证。 +- 仅 `runtime: "subagent"` 支持附件。ACP runtime 会拒绝它们。 +- 文件会被实体化到子 workspace 的 `.openclaw/attachments//` 中，并带有 `.manifest.json`。 +- 附件内容会自动从转录持久化中脱敏。 +- Base64 输入会进行严格的字母表/填充校验，并带有解码前大小保护。 - 目录权限为 `0700`，文件权限为 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留它们。 +- 清理由 `cleanup` 策略决定：`delete` 始终会移除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才会保留附件。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用了 strict-agentic GPT-5 自动启用规则。 +实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 ```json5 { @@ -2512,8 +2496,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 说明： - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 `"strict-agentic"`，且当前运行是 OpenAI 或 OpenAI Codex 的 GPT-5 家族模型。设置为 `true` 可在该范围之外强制启用该工具，设置为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，system prompt 还会添加使用指导，以便模型仅在重要工作中使用它，并且最多只保留一个 `in_progress` 步骤。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围之外强制启用该工具，设置为 `false` 则即使对 strict-agentic GPT-5 运行也保持关闭。 +- 启用后，系统提示还会添加使用指引，使模型仅在重要工作中使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2533,16 +2517,16 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `model`：派生子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 使用的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 -- 按子智能体划分的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`：生成的子智能体的默认模型。若省略，子智能体会继承调用方的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 +- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { @@ -2571,51 +2555,51 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 对于自定义认证需求，请使用 `authHeader: true` + `headers`。 -- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用其旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 -- 对于匹配的 provider ID，合并优先级如下： +- 对于自定义认证需求，可使用 `authHeader: true` + `headers`。 +- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 对于匹配的提供商 ID，合并优先级如下： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商在当前 config/auth-profile 上下文中不是由 SecretRef 管理时优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会根据来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的提供商 header 值会根据来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 + - 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不是由 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 + - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值和隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；当你希望限制实际上下文而不更改模型原生元数据时，请使用它。 - - 当你希望让配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 - - 标记持久化以来源为准：标记从活动来源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 + - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；当你希望限制实际上下文而不改变模型原生元数据时，可使用它。 + - 当你希望让配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 + - 标记持久化以源为权威：标记来自活动源配置快照（解析前），而不是来自已解析的运行时 secret 值。 -### Provider 字段详情 +### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：以 provider ID 为键的自定义提供商映射。 - - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 +- `models.providers`：以提供商 id 为键的自定义提供商映射。 + - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge`，或使用 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：提供商凭据（优先使用 SecretRef/环境变量替换）。 - `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。 -- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭据。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 +- `models.providers.*.headers`：用于代理/租户路由的额外静态 header。 - `models.providers.*.request`：模型提供商 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.headers`：额外 header（与提供商默认值合并）。值接受 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 或类似地址范围时，允许通过 provider HTTP 获取保护对 `baseUrl` 执行 HTTPS 访问（适用于受信任、自托管、兼容 OpenAI 端点的 operator 选择加入）。WebSocket 会对 headers/TLS 使用相同的 `request`，但不会使用该获取 SSRF 防护。默认值 `false`。 + - `request.allowPrivateNetwork`：当为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似范围时，允许通过提供商 HTTP 获取保护访问 HTTPS（这是对受信任的自托管 OpenAI 兼容端点的 operator 显式启用项）。WebSocket 使用相同的 `request` 来处理 headers/TLS，但不使用该获取 SSRF 防护门。默认值为 `false`。 - `models.providers.*.models`：显式提供商模型目录条目。 -- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望实际上下文预算小于模型原生 `contextWindow` 时，请使用它。 -- `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 自动发现设置根路径。 +- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望实际上下文预算小于模型原生 `contextWindow` 时，可使用它。 +- `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.enabled`：开启/关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 id 过滤器。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的后备上下文窗口。 - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的后备最大输出 token 数。 -### Provider 示例 +### 提供商示例 @@ -2685,11 +2669,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 +设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 如需使用通用端点，请定义一个带有 base URL 覆盖的自定义提供商。 +- 对于通用端点，请定义一个带 base URL 覆盖的自定义提供商。 @@ -2728,11 +2712,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -中国区端点：`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` 传输上声明流式 usage 兼容性，OpenClaw 会根据端点能力 -而不仅仅是内置 provider ID 来决定该行为。 +`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会依据端点能力 +而不仅仅是内置提供商 id 来决定这一点。 @@ -2750,11 +2734,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -兼容 Anthropic，内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2789,7 +2773,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2833,15 +2817,16 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `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` 重写为 +在 Anthropic 兼容流式路径上，除非你显式设置 `thinking`，否则 OpenClaw +默认会禁用 MiniMax thinking。`/fast on` 或 +`params.fastMode: true` 会将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。 -请参阅 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能充足的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2872,13 +2857,12 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管/工作区 Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skills 根目录（最低优先级）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` - 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管/workspace Skills 不受影响）。 +- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 - `entries..enabled: false`：即使某个 Skill 已内置/已安装，也会禁用它。 -- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供便捷 API key 字段（明文字符串或 SecretRef 对象）。 --- @@ -2907,42 +2891,42 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 -- **配置更改需要重启 Gateway 网关。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 -- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（当插件支持时）。 +- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 +- **配置变更需要重启 Gateway 网关。** +- `allow`：可选允许列表（只加载列出的插件）。`deny` 优先。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时可用）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的可选规范 `provider/model` 目标允许列表。仅当你确实希望允许任意模型时才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 进行验证）。 +- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，core 会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook，以及受支持 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标的可选允许列表。仅当你有意允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 - `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。 - - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 + - `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`）。 + - `onlyMainContent`：仅提取页面主要内容（默认：`true`）。 + - `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`：memory 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 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)： +- 完整的 memory 配置见 [Memory configuration reference](/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`：选择活动 memory 插件 ID，或使用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认值是 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为清洗后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。 + - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -请参阅 [Plugins](/zh-CN/tools/plugin)。 +参见 [Plugins](/zh-CN/tools/plugin)。 --- @@ -2985,27 +2969,26 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 - `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用，因此浏览器导航默认保持严格模式。 - 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止规则约束。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 -- 远程配置文件为仅附加模式（禁用 start/stop/reset）。 +- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外设置。 +- 远程配置文件是仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； - 当提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可在 - 选定主机上或通过已连接浏览器节点进行附加。 + 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)； + 当提供商直接给你 DevTools WebSocket URL 时，使用 WS(S)。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机上，或通过已连接的浏览器节点附加。 - `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的 - Chromium 系浏览器配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作而非 CSS 选择器定位、单文件上传 - hooks、无对话框超时覆盖、无 `wait --load networkidle`，以及无 - `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有 - 远程 CDP 时才需显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- Control 服务：仅限 loopback（端口从 `gateway.port` 推导，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动附加额外启动参数（例如 - `--disable-gpu`、窗口尺寸或调试标志）。 + 基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件仍受当前 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动操作，而不是 CSS 选择器定向；单文件上传 + hook；不支持对话框超时覆盖；不支持 `wait --load networkidle`， + 也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在 + 远程 CDP 情况下才显式设置 `cdpUrl`。 +- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如 + `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -3023,8 +3006,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡色调等）。 -- `assistant`：Control UI 身份覆盖。未设置时回退到活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI identity 覆盖。会回退到活动智能体 identity。 --- @@ -3093,49 +3076,49 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `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`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 说明**：默认的 `loopback` 绑定会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此无法访问 Gateway 网关。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并搭配 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **认证**：默认必须启用。非 loopback 绑定需要 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` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。 -- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享 secret 和设备 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 绑定）或 `funnel`（公开，需要认证）。 -- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当浏览器客户端预期来自非 loopback origin 时，这是必需的。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host header origin 策略的部署启用 Host header origin 回退。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind mode 值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`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 绑定需要 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` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证条件。 +- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve identity header 可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用这种 Tailscale header 认证；它们仍遵循 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-header origin 策略的部署启用 Host-header origin 回退。 - `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧破玻璃覆盖，允许对受信任的私有网络 IP 使用明文 `ws://`；默认情况下，明文仍仅限 loopback。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的 base HTTPS URL，官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册信息后会使用它。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 -- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个按注册划分的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储注册。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急放行覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许对 loopback 使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭据字段。它们本身不会配置 gateway 认证。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 gateway 后，所使用的外部 APNs relay 的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会委派给特定的 gateway identity。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该 identity，并将一个以注册为作用域的发送授权转发给 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.*` 作为回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 明确通过 SecretRef 配置但未解析，则解析会失败关闭（不会由远程回退掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端 headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。 -- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关会接受 `X-Real-IP`。默认值 `false`，以保持失败关闭行为。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认 deny 列表）。 -- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。 +- `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.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析将以默认拒绝方式失败（不会有远程回退进行掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**使 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，gateway 会接受 `X-Real-IP`。默认值为 `false`，以保持默认拒绝行为。 +- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。 +- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。 -### OpenAI-compatible 端点 +### OpenAI 兼容端点 - Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 @@ -3143,14 +3126,14 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空的 allowlist 会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 空的允许列表会被视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 -- 可选的响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） +- 可选响应加固 header： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一台主机上使用唯一端口和状态目录运行多个 Gateway 网关： +在一台主机上运行多个 gateway，并为每个实例使用唯一端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3178,10 +3161,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` @@ -3198,17 +3181,17 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制如何在运行时应用配置编辑。 - - `"off"`：忽略实时编辑；更改需要显式重启。 - - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：在进程内应用更改而不重启。 +- `mode`：控制配置编辑在运行时如何应用。 + - `"off"`：忽略实时编辑；变更需要显式重启。 + - `"restart"`：配置变更时始终重启 gateway 进程。 + - `"hot"`：进程内应用变更，无需重启。 - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 -- `debounceMs`：应用配置更改前的去抖窗口（毫秒）（非负整数）。 -- `deferralTimeoutMs`：在强制重启前，等待进行中操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 +- `debounceMs`：应用配置变更前的去抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- -## Hooks +## Hook ```json5 { @@ -3242,46 +3225,46 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -拒绝使用查询字符串中的 hook token。 +会拒绝查询字符串中的 hook token。 -验证和安全说明： +验证与安全说明： - `hooks.enabled=true` 需要非空的 `hooks.token`。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 -- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 +- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或预设使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该选择加入。 +- 如果某个映射或 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`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 + - 只有当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此也要求 `hooks.allowRequestSessionKey=true`。 + - 经模板渲染的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 - `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 会匹配通用路径中的某个负载字段。 -- `{{messages[0].subject}}` 之类的模板会从负载中读取。 -- `transform` 可指向一个返回 hook 动作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。 +- `match.source` 会匹配通用路径的某个负载字段。 +- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。 +- `transform` 可以指向返回 hook 动作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 -- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：对未显式提供 `sessionKey` 的 hook 智能体运行，使用的可选固定会话键。 +- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。 +- `defaultSessionKey`：对未显式设置 `sessionKey` 的 hook 智能体运行，使用可选的固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或预设使用模板化 `sessionKey` 时，它就成为必填项。 +- `allowedSessionKeyPrefixes`：对显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，它会变为必需项。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。 -- `model` 会覆盖本次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会为此次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须在允许范围内）。 ### Gmail 集成 -- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。 +- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 +- 如果你保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不是使用模板化默认值。 ```json5 { @@ -3304,12 +3287,12 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。如需禁用，请设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1`。 -- 不要在 Gateway 网关旁边再单独运行一个 `gog gmail watch serve`。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 +- 不要在 Gateway 网关之外单独运行另一个 `gog gmail watch serve`。 --- -## Canvas host +## Canvas 主机 ```json5 { @@ -3321,18 +3304,18 @@ 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 绑定：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 -- Node WebViews 通常不会发送认证 headers；在节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告按节点划分的 capability URL。 -- capability URL 绑定到当前活动的节点 WS 会话，并会很快过期。不使用基于 IP 的回退。 -- 会向提供的 HTML 中注入 live-reload 客户端。 -- 当目录为空时，会自动创建初始 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 下提供 A2UI。 -- 更改需要重启 Gateway 网关。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 +- 非 loopback 绑定：canvas 路由和其他 Gateway 网关 HTTP 表面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 +- Node WebView 通常不会发送认证 header；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问发布节点作用域 capability URL。 +- Capability URL 绑定到当前活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 +- 会向所提供的 HTML 中注入实时重载客户端。 +- 为空时会自动创建起始 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 变更需要重启 gateway。 +- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。 --- @@ -3354,7 +3337,7 @@ openclaw gateway --port 19001 - `full`：包含 `cliPath` + `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域网（DNS-SD） +### 广域（DNS-SD） ```json5 { @@ -3364,7 +3347,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`。 @@ -3389,14 +3372,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少该键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- 仅当进程环境中缺少某个键时，才会应用内联环境变量。 +- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 -- 完整优先级请参阅 [Environment](/zh-CN/help/environment)。 +- 完整优先级参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -在任何配置字符串中都可以通过 `${VAR_NAME}` 引用环境变量： +可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3407,19 +3390,19 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空变量会在配置加载时抛出错误。 +- 缺失/为空的变量会在加载配置时抛出错误。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 -- 可与 `$include` 一起使用。 +- 适用于 `$include`。 --- ## Secrets -SecretRef 是增量式的：明文值仍然可用。 +SecretRef 是增量特性：明文值仍然可用。 ### `SecretRef` -使用以下对象形态： +使用如下对象形状： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3429,17 +3412,17 @@ SecretRef 是增量式的：明文值仍然可用。 - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/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 Credential Surface](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 会定位到受支持的 `openclaw.json` 凭据路径。 +- `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围中。 -### Secret providers 配置 +### Secret 提供商配置 ```json5 { @@ -3469,14 +3452,14 @@ SecretRef 是增量式的：明文值仍然可用。 说明： -- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- 当无法验证 Windows ACL 时，file 和 exec provider 路径会以失败关闭方式处理。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。 -- `exec` provider 要求绝对 `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` 显式传入所需变量。 +- SecretRef 会在激活时被解析到内存快照中，之后请求路径只读取该快照。 +- 激活期间会应用活动表面过滤：启用表面上的未解析引用会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。 --- @@ -3498,13 +3481,13 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- 按智能体划分的 profiles 存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭证模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式的 profiles（`auth.profiles..mode = "oauth"`）不支持以 SecretRef 为后备的 auth-profile 凭证。 -- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会将其清理。 +- 按智能体配置文件存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 支持静态凭据模式的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- OAuth 模式配置文件（`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)。 +- Secrets 运行时行为以及 `audit/configure/apply` 工具： [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3526,20 +3509,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个 profile 因真实的 - 计费/余额不足错误而失败时使用的基础退避时间（小时）（默认：`5`）。即使在 `401`/`403` 响应下，显式的计费文本 - 也仍可能落入此路径，但提供商特定的文本 - 匹配器仍仅作用于拥有它们的提供商（例如 OpenRouter 的 - `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 - 组织/工作区支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商覆盖计费退避小时数。 -- `billingMaxHours`：计费退避指数增长的上限小时数（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟）（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认：`60`）。 +- `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`）。 - `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。 -- `overloadedProfileRotations`：对于过载错误，在切换到模型回退前，允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的 provider 忙碌形态会落入此路径。 -- `overloadedBackoffMs`：在重试过载的 provider/profile 轮换前的固定延迟（毫秒）（默认：`0`）。 -- `rateLimitedProfileRotations`：对于速率限制错误，在切换到模型回退前，允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。该 rate-limit 桶包括提供商形态的文本，例如 `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`。 --- @@ -3559,8 +3542,8 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用稳定路径。 -- 传入 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 +- 设置 `logging.file` 可使用固定路径。 +- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 - `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3598,20 +3581,20 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `enabled`：插桩输出的总开关（默认：`true`）。 -- `flags`：启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。 -- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的年龄阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 -- `otel.endpoint`：OTel 导出的 collector URL。 +- `enabled`：用于控制仪表输出的总开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持诸如 `"telegram.*"` 或 `"*"` 的通配符）。 +- `stuckSessionWarnMs`：当会话保持在处理中状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。 +- `otel.endpoint`：用于 OTel 导出的采集器 URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 -- `otel.serviceName`：资源属性中的服务名。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据请求头。 +- `otel.serviceName`：资源属性的服务名称。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 - `otel.sampleRate`：trace 采样率 `0`–`1`。 -- `otel.flushIntervalMs`：周期性遥测冲刷间隔（毫秒）。 +- `otel.flushIntervalMs`：定期刷新遥测数据的间隔时间（毫秒）。 - `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。 - `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含的内容（默认均为 `true`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（默认均为：`true`）。 --- @@ -3633,12 +3616,12 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `channel`：npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `channel`：用于 npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 - `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最短延迟（小时）（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口（小时）（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：稳定渠道额外的发布分散窗口小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道执行检查的频率（小时）（默认：`1`；最大：`24`）。 --- @@ -3672,21 +3655,21 @@ SecretRef 是增量式的：明文值仍然可用。 ``` - `enabled`：全局 ACP 功能开关（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设置为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。 -- `defaultAgent`：当生成操作未指定显式目标时，后备使用的 ACP 目标智能体 ID。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 列表；为空表示无额外限制。 +- `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 轮次投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 -- `stream.tagVisibility`：标签名称到布尔可见性覆盖的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在符合清理条件前的空闲 TTL（分钟）。 -- `runtime.installCommand`：引导 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 运行时环境时执行的可选安装命令。 --- @@ -3702,11 +3685,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换显示有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍会显示 banner 标题/版本）。 -- 若要隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 +- `cli.banner.taglineMode` 用于控制横幅标语样式： + - `"random"`（默认）：轮换显示有趣/季节性的标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍显示横幅标题/版本）。 +- 如需隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3730,13 +3713,13 @@ SecretRef 是增量式的：明文值仍然可用。 ## 身份 -请参阅 [Agent defaults](#agent-defaults) 下 `agents.list` 的身份字段。 +请参见 [智能体默认值](#agent-defaults) 中的 `agents.list` 身份字段。 --- -## Bridge protocol（旧版节点，历史参考） +## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。 +当前构建版本已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置模式的一部分（在移除之前，校验会失败；`openclaw doctor --fix` 可移除未知键）。 @@ -3776,11 +3759,11 @@ SecretRef 是增量式的：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 中清理之前，保留已完成隔离 cron 运行会话的时长。也控制已归档且被删除的 cron transcript 的清理。默认值：`24h`；设置为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在修剪前的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不发送认证 header。 -- `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` @@ -3796,11 +3779,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`：每次重试尝试的回退延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 项）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会对所有暂时性类型进行重试。 -仅适用于一次性 cron 任务。周期性任务使用单独的失败处理逻辑。 +仅适用于单次 cron 任务。周期性任务使用独立的失败处理方式。 ### `cron.failureAlert` @@ -3818,11 +3801,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` @@ -3841,14 +3824,14 @@ 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"`。 +- `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 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 +请参见 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会被记录为[后台任务](/zh-CN/automation/tasks)。 --- @@ -3856,32 +3839,32 @@ SecretRef 是增量式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | -| ------------------ | ------------------------------------- | -| `{{Body}}` | 完整传入消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 ID | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 传入媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | 为 CLI 条目解析后的媒体 prompt | -| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| Variable | 描述 | +| ------------------ | ------------------------------------------------- | +| `{{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`） 将配置拆分到多个文件中： @@ -3898,15 +3881,15 @@ SecretRef 是增量式的：明文值仍然可用。 **合并行为：** -- 单个文件：替换其所在的包含对象。 +- 单个文件：替换其所在的对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 includes 之后合并（覆盖 include 的值）。 -- 嵌套 includes：最多支持 10 层深度。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式仅在最终仍解析到该边界内时才允许。 -- 当 OpenClaw 自有写入仅更改由单文件 include 支持的一个顶层段时，会直写该被 include 的文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 根级 include、include 数组以及带同级覆盖的 include 对 OpenClaw 自有写入是只读的；这些写入会以失败关闭方式处理，而不是将配置展平。 -- 错误：对于缺失文件、解析错误和循环 include，会提供清晰的错误消息。 +- 同级键：在包含项之后合并（覆盖被包含的值）。 +- 嵌套包含：最多支持 10 层。 +- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许使用。 +- 当 OpenClaw 自有写入仅更改由单文件 include 支持的一个顶层 section 时，会直写到该被包含文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。 +- 对于根级 include、include 数组以及带有同级覆盖的 include，OpenClaw 自有写入为只读；这些写入会以关闭失败的方式处理，而不是将配置拍平。 +- 错误：对缺失文件、解析错误和循环包含提供清晰的消息。 --- -_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/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/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 670383f55..5b666a408 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,23 +1,23 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审查 bundled-plugin 子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组说明各导入位于何处 + - 审查 bundled-plugin 子路径和辅助接口 surface +summary: 插件 SDK 子路径目录：按领域分组说明各导入路径的位置 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-24T01:32:01Z" + generated_at: "2026-04-24T02:20:28Z" model: gpt-5.4 provider: openai - source_hash: 79f44344d9a584380347d0ed0c00cff6652556e5352d2c6143cf6fec092b809e + source_hash: 592cd599c9026eb584773cb7991dd75796f58cd62cd3a85d32e5b106440f7c3e source_path: plugins/sdk-subpaths.md workflow: 15 --- - plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。 - 本页按用途对常用子路径进行归类整理。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 其中也会出现为 bundled-plugin 预留的辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 + plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精细子路径公开。 + 本页按用途分组，汇总常用的子路径。完整的 200+ 子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`； + 其中也包含保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 - 关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 @@ -32,54 +32,54 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/channel-core` | `defineChannelPluginEntry`、`defineSetupPluginEntry`、`createChatChannelPlugin`、`createChannelPluginBase` | | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | | `plugin-sdk/setup` | 共享的设置向导辅助工具、allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | + | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具、默认账户回退辅助工具 | + | `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具，以及默认账户回退辅助工具 | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 精简的账户列表/账户操作辅助工具 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认值回退辅助工具 | + | `plugin-sdk/account-helpers` | 精细的账户列表/账户操作辅助工具 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带 bundled-contract 回退 | - | `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，并带有 bundled-contract 回退 | + | `plugin-sdk/command-gating` | 精细的命令授权门控辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/收尾辅助工具 | - | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建器辅助工具 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/完成辅助工具 | + | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助工具 | | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助工具 | | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助工具 | | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 | - | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | + | `plugin-sdk/poll-runtime` | 精细的投票规范化辅助工具 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 | | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | | `plugin-sdk/channel-status` | 共享的渠道状态快照/摘要辅助工具 | - | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 | + | `plugin-sdk/channel-config-primitives` | 精细的渠道配置 schema 基元 | | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 | | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 共享的群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享的直接私信认证/守卫辅助工具 | + | `plugin-sdk/direct-dm` | 共享的私信认证/保护辅助工具 | | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 面向兼容性的 barrel，包含入站去抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具 | - | `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时接口的精简提及策略辅助工具 | - | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | - | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 | + | `plugin-sdk/channel-inbound` | 为入站去抖动、提及匹配、提及策略辅助工具和 envelope 辅助工具提供兼容性 barrel | + | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精细提及策略辅助工具 | + | `plugin-sdk/channel-location` | 渠道位置上下文与格式化辅助工具 | + | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing/ack 失败的渠道日志辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | | `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 | | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈/reaction 连接能力 | - | `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 | + | `plugin-sdk/channel-feedback` | 反馈/reaction 接线 | + | `plugin-sdk/channel-secret-runtime` | 精细的 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和 secret target 类型 | @@ -87,25 +87,25 @@ x-i18n: | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | API 密钥 onboarding/配置文件写入辅助工具，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助工具，例如 `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助工具 | | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | - | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及 `normalizeNativeXaiModelId` 等 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助工具，包括音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具，包括音频转录 multipart form 辅助工具 | + | `plugin-sdk/provider-web-fetch-contract` | 精细的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 面向无需插件启用连接能力的提供商的精简 web-search 配置/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter | + | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精细 web-search 配置/凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 精细的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及带作用域的凭证 setter/getter | | `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 等 xAI 兼容性辅助工具 | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似能力 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 | | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | @@ -116,25 +116,26 @@ x-i18n: | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助工具 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter/gateway 接口已经足够，优先使用它们 | + | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助工具；如果更精细的 adapter/gateway 接口已足够，优先使用它们 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 | + | `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的精细渠道契约测试辅助工具 | | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 | - | `plugin-sdk/command-detection` | 共享的命令检测辅助工具 | - | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令主体规范化和命令接口辅助工具 | + | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | + | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令主体规范化和命令 surface 辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret 接口的精简 secret-contract 收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret surface 的精细 secret-contract 收集辅助工具 | + | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract/配置解析的精细 `coerceSecretRef` 和 SecretRef 类型辅助工具 | | `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助工具 | | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时接口的精简 pinned-dispatcher 辅助工具 | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 防护的 fetch 和 SSRF 策略辅助工具 | + | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时接口的精细 pinned-dispatcher 辅助工具 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 | | `plugin-sdk/secret-input` | secret 输入解析辅助工具 | | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 | | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 | @@ -143,9 +144,9 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助工具 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 | + | `plugin-sdk/runtime` | 范围广泛的运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 精细的运行时环境、日志器、超时、重试和退避辅助工具 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | 共享的插件命令/hook/http/交互式辅助工具 | | `plugin-sdk/hook-runtime` | 共享的 webhook/内部 hook 管道辅助工具 | @@ -154,58 +155,58 @@ x-i18n: | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | | `plugin-sdk/config-runtime` | 配置加载/写入辅助工具，以及插件配置查找辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化，以及重复/冲突检查，即使 bundled Telegram 契约接口不可用也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不包含宽泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/profile 辅助工具、原生路由/运行时辅助工具 | | `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/收尾辅助工具 | - | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | 精细的回复分发/完成辅助工具 | + | `plugin-sdk/reply-history` | 共享的短时间窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助工具 | + | `plugin-sdk/reply-chunking` | 精细的文本/Markdown 分块辅助工具 | | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 | | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 | | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享的渠道/账户状态摘要辅助工具、运行时状态默认值以及问题元数据辅助工具 | + | `plugin-sdk/status-helpers` | 共享的渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助工具 | | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 | | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带超时的命令运行器，输出已规范化的 stdout/stderr 结果 | + | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 | | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | - | `plugin-sdk/tool-send` | 从工具参数中提取标准发送目标字段 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | | `plugin-sdk/temp-path` | 共享的临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | + | `plugin-sdk/logging-core` | 子系统日志器和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 磁盘后备去重缓存辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时 config-schema 原语 | + | `plugin-sdk/agent-config-primitives` | 精细的智能体运行时 config-schema 基元 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | - | `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助原语 | + | `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助基元 | | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 | - | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 | - | `plugin-sdk/agent-harness` | 面向受信任插件的实验性接口，用于低层智能体 harness：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具，以及尝试结果实用工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint 检测辅助工具 | + | `plugin-sdk/native-command-registry` | 原生命令注册表构建/序列化辅助工具 | + | `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层智能体 harness 接口：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具以及 attempt 结果实用工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 | | `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助工具 | - | `plugin-sdk/runtime-fetch` | 不引入代理/受保护 fetch 导入、支持 dispatcher 感知的运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 不依赖广泛 media 运行时接口的有界响应体读取器 | - | `plugin-sdk/session-binding-runtime` | 不含已配置绑定路由或配对存储的当前会话绑定状态 | - | `plugin-sdk/session-store-runtime` | 不引入广泛配置写入/维护导入的会话存储读取辅助工具 | - | `plugin-sdk/context-visibility-runtime` | 不引入广泛配置/安全导入的上下文可见性解析和补充上下文过滤 | - | `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志导入的精简原始记录/字符串强制转换与规范化辅助工具 | + | `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不引入 proxy/guarded-fetch 导入 | + | `plugin-sdk/response-limit-runtime` | 不包含宽泛媒体运行时接口的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 不包含宽泛配置写入/维护导入的会话存储读取辅助工具 | + | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛配置/安全导入 | + | `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志导入的精细原始记录/字符串强制转换与规范化辅助工具 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | + | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 | | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | - | `plugin-sdk/directory-runtime` | 由配置支持的目录查询/去重 | + | `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | @@ -213,31 +214,31 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/media-runtime` | 共享的媒体获取/转换/存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障转移辅助工具、候选项选择和缺失模型提示 | + | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助工具、候选项选择和缺失模型提示消息 | | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享的文本/Markdown/日志辅助工具，例如对智能体可见文本的剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 | + | `plugin-sdk/text-runtime` | 共享的文本/Markdown/日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 | | `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive 和规范化辅助工具 | | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障转移、认证和注册表辅助工具 | + | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障切换、认证和注册表辅助工具 | | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 | | `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 | | `plugin-sdk/web-media` | 共享的远程/本地媒体加载辅助工具 | - | `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` | + | `plugin-sdk/zod` | 为 plugin SDK 使用者重新导出的 `zod` | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 | + | `plugin-sdk/memory-core` | bunded memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 | | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 | @@ -251,24 +252,24 @@ x-i18n: | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向厂商中立的别名，对应 memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-host-events` | 面向厂商中立的别名，对应 memory host 事件日志辅助工具 | - | `plugin-sdk/memory-host-files` | 面向厂商中立的别名，对应 memory host 文件/运行时辅助工具 | - | `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向厂商中立的别名，对应 memory host 状态辅助工具 | + | `plugin-sdk/memory-host-core` | 面向不同供应商的 memory host 核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 面向不同供应商的 memory host 事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 面向不同供应商的 memory host 文件/运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的 active memory 运行时门面 | + | `plugin-sdk/memory-host-status` | 面向不同供应商的 memory host 状态辅助工具别名 | | `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 | - | 系列 | 当前子路径 | 预期用途 | + | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled 浏览器插件支持辅助工具（`browser-support` 仍然是兼容性 barrel） | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix 辅助/运行时接口 | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助/运行时接口 | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC 辅助接口 | - | 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性/辅助接口 | - | 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性/辅助接口 | + | 认证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 131895f08..110f278fe 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -3,48 +3,47 @@ read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - 你想使用 Codex 订阅认证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 -summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI +summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅 title: OpenAI x-i18n: - generated_at: "2026-04-23T23:39:57Z" + generated_at: "2026-04-24T02:20:29Z" model: gpt-5.4 provider: openai - source_hash: f3445cab47caa324314c115fb968f13c2910954b685b68a17ab9228e3184fa14 + source_hash: f9bb65b29be2b69a85663b17a68560c557ffb5303ac7afa2b27548a27397af46 source_path: providers/openai.md workflow: 15 --- -OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入路径。模型前缀决定所用路径： +OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列路由。模型前缀决定所使用的路由： -- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） +- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型） - **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） -- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`） +- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，并配合 `agents.defaults.embeddedHarness.runtime: "codex"`） -OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 +OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用基于订阅的 OAuth。 -GPT-5.5 当前可通过订阅 / OAuth 路径在 OpenClaw 中使用： -通过 PI runner 使用 `openai-codex/gpt-5.5`，或通过 -Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直接 API 密钥访问 -会在 OpenAI 为公共 API 启用 GPT-5.5 后得到支持；在此之前，请在 -`OPENAI_API_KEY` 配置中使用已启用 API 的模型，例如 `openai/gpt-5.4`。 +GPT-5.5 目前在 OpenClaw 中可通过订阅 / OAuth 路由使用： +`openai-codex/gpt-5.5` 配合 PI runner，或 `openai/gpt-5.5` 配合 +Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即可支持通过 API 密钥直接访问 `openai/gpt-5.5`； +在此之前，对于 `OPENAI_API_KEY` 配置，请使用支持 API 的模型，例如 `openai/gpt-5.4`。 ## OpenClaw 功能覆盖范围 -| OpenAI 能力 | OpenClaw 表面 | 状态 | +| OpenAI 能力 | OpenClaw 界面 | 状态 | | ------------------------- | ------------------------------------------------------ | ------------------------------------------------------ | | 聊天 / Responses | `openai/` 模型提供商 | 是 | -| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/` | 是 | -| Codex app-server harness | 带 `embeddedHarness.runtime: codex` 的 `openai/` | 是 | -| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定 provider 时 | -| 图片 | `image_generate` | 是 | +| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/` | 是 | +| Codex app-server harness | 使用 `embeddedHarness.runtime: codex` 的 `openai/` | 是 | +| 服务端网页搜索 | 原生 OpenAI Responses 工具 | 是，在启用网页搜索且未固定提供商时 | +| 图像 | `image_generate` | 是 | | 视频 | `video_generate` | 是 | | 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | -| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | -| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 | -| Embeddings | memory embedding provider | 是 | +| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 | +| 实时语音 | 语音通话 `realtime.provider: "openai"` | 是 | +| Embeddings | memory embedding 提供商 | 是 | ## 入门指南 @@ -52,7 +51,7 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直 - **最适合：** 直接 API 访问和按使用量计费。 + **最适合：** 直接访问 API 和按量计费。 @@ -69,25 +68,25 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直 openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### 路径摘要 + ### 路由摘要 - | 模型引用 | 路径 | 认证 | + | 模型引用 | 路由 | 认证 | |-----------|-------|------| | `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | OpenAI 在 API 上启用 GPT-5.5 后的未来直接 API 路径 | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | 一旦 OpenAI 在 API 上启用 GPT-5.5 后的未来直接 API 路由 | `OPENAI_API_KEY` | - `openai/*` 是直接 OpenAI API 密钥路径，除非你显式强制使用 - Codex app-server harness。GPT-5.5 本身当前仅支持订阅 / OAuth； - 如需通过默认 PI runner 使用 Codex OAuth，请使用 `openai-codex/*`。 + `openai/*` 默认是直接 OpenAI API 密钥路由，除非你显式强制使用 + Codex app-server harness。GPT-5.5 本身目前仅支持订阅 / OAuth； + 对于通过默认 PI runner 使用的 Codex OAuth，请使用 `openai-codex/*`。 ### 配置示例 @@ -120,7 +119,7 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直 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 @@ -131,23 +130,23 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直 openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-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 路径。 + 认证 / 配置文件命令请继续使用 `openai-codex` 提供商 id。 + `openai-codex/*` 模型前缀也是用于 Codex OAuth 的显式 PI 路由。 ### 配置示例 @@ -159,28 +158,29 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直 ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。 ### 状态指示器 - 聊天中的 `/status` 会显示当前 - 会话所使用的 embedded harness。默认的 PI harness 显示为 `Runner: pi (embedded)`，且 - 不会额外添加单独标记。选中内置的 Codex app-server harness 时， - `/status` 会在 `Fast` 旁追加非 PI harness id，例如 - `Fast · codex`。已有会话会保留其记录的 harness id，因此如果你在更改 `embeddedHarness` 后希望 `/status` - 反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。 + 聊天中的 `/status` 会显示当前会话正在使用哪个嵌入式 harness。 + 默认的 PI harness 显示为 `Runner: pi (embedded)`，且不会 + 额外添加单独标记。选择内置的 Codex app-server harness 时， + `/status` 会在 `Fast` 后附加非 PI harness id，例如 + `Fast · 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 { @@ -201,21 +201,20 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直 -## 图片生成 +## 图像生成 -内置的 `openai` 插件通过 `image_generate` 工具注册图片生成功能。 -它同时支持 OpenAI API 密钥图片生成，以及通过同一个 `openai/gpt-image-2` 模型引用进行的 -Codex OAuth 图片生成。 +内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 +它支持使用同一个 `openai/gpt-image-2` 模型引用，同时进行基于 OpenAI API 密钥的图像生成和基于 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 后端 | -| 每次请求的最大图片数 | 4 | 4 | -| 编辑模式 | 已启用（最多 5 张参考图片） | 已启用（最多 5 张参考图片） | +| 每次请求最大图像数 | 4 | 4 | +| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） | | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 | -| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全可行时映射为受支持的尺寸 | +| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 | ```json5 { @@ -228,32 +227,32 @@ Codex OAuth 图片生成。 ``` -有关共享工具参数、provider 选择和故障切换行为，请参见 [图片生成](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文生图与图片编辑的默认模型。 -`gpt-image-1` 仍可作为显式模型覆盖来使用，但新的 -OpenAI 图片工作流应使用 `openai/gpt-image-2`。 +`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。 +`gpt-image-1` 仍可作为显式模型覆盖继续使用，但新的 +OpenAI 图像工作流应使用 `openai/gpt-image-2`。 -对于 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`。 -如果该自定义图片端点位于受信任的局域网 / 私有地址上，还要设置 -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有这个显式启用项， -OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图片端点。 +对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。 +当配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth +访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。 +当你希望改为使用直接 OpenAI Images API 路由时，请显式配置 +`models.providers.openai`，提供 API 密钥、自定义 base URL 或 Azure 端点。 +如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需设置 +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非提供此显式启用项， +否则 OpenClaw 会继续阻止私有 / 内部的兼容 OpenAI 图像端点。 生成： ``` -/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精致的发布海报" size=3840x2160 count=1 ``` 编辑： ``` -/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 +/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536 ``` ## 视频生成 @@ -264,9 +263,9 @@ OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图片端点。 | ---------------- | --------------------------------------------------------------------------------- | | 默认模型 | `openai/sora-2` | | 模式 | 文生视频、图生视频、单视频编辑 | -| 参考输入 | 1 张图片或 1 个视频 | +| 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 | +| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 | ```json5 { @@ -279,16 +278,16 @@ OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图片端点。 ``` -有关共享工具参数、provider 选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 ## GPT-5 提示词贡献 -OpenClaw 会为跨 provider 的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`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.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收同样的叠加层。较旧的 GPT-4.x 模型则不会。 -内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 覆盖层，因此，即使 Codex 接管了 harness 提示词的其余部分，通过 `embeddedHarness.runtime: "codex"` 强制使用的 `openai/gpt-5.x` 会话，仍会保留相同的后续执行与主动 heartbeat 指导。 +内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此，即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保持相同的后续执行和主动心跳指引。 -GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona 持续性、执行安全性、工具纪律、输出结构、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导对匹配的模型始终启用。友好的交互风格层则是独立且可配置的。 +GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona 持续性、执行安全性、工具纪律、输出形状、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指引始终会为匹配的模型启用。友好的交互风格层是独立的，并且可配置。 | 值 | 效果 | | ---------------------- | ------------------------------------------- | @@ -318,30 +317,30 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona -运行时对值大小写不敏感，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 +这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 -当未设置共享的 `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` 界面注册了语音合成功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `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 { @@ -363,16 +362,16 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona 内置的 `openai` 插件通过 - OpenClaw 的媒体理解转写表面注册了批量语音转文本功能。 + OpenClaw 的媒体理解转录界面注册了批量语音转文本功能。 - 默认模型：`gpt-4o-transcribe` - 端点：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，只要入站音频转写使用 - `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道 + - 在 OpenClaw 中，凡是入站音频转录使用 + `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道 音频附件 - 要为入站音频转写强制使用 OpenAI： + 要强制将 OpenAI 用于入站音频转录： ```json5 { @@ -392,12 +391,13 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona } ``` - 当共享音频媒体配置或每次调用的转写请求提供了语言和提示信息时，这些信息会转发给 OpenAI。 + 当由共享音频媒体配置或按次转录请求提供语言和提示词提示时， + 这些信息会转发给 OpenAI。 - - 内置的 `openai` 插件为 Voice Call 插件注册了实时转写功能。 + + 内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| @@ -409,7 +409,7 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这一流式 provider 用于 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` 转录路径。 @@ -420,7 +420,7 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 语音 | `...openai.voice` | `alloy` | + | 音色 | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | @@ -435,27 +435,27 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona ## Azure OpenAI 端点 -内置的 `openai` provider 可通过覆盖 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) 下 **实时语音** -折叠面板。 +不会受到 `models.providers.openai.baseUrl` 的影响。其 Azure +设置请参阅 [语音与语音处理](#voice-and-speech) 下的 **实时语音** +折叠项。 在以下情况下使用 Azure OpenAI： - 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 -- 你希望将流量保留在现有 Azure 租户内部 +- 你希望将流量保留在现有的 Azure 租户内 ### 配置 -对于通过内置 `openai` provider 进行的 Azure 图片生成，请将 -`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 -Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： +对于通过内置 `openai` 提供商进行的 Azure 图像生成，请将 +`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` +设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： ```json5 { @@ -470,32 +470,32 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： } ``` -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-key` 请求头，而不是 `Authorization: Bearer` +- 使用基于 deployment 的路径（`/openai/deployments/{deployment}/...`） - 为每个请求追加 `?api-version=...` -其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的 -OpenAI 图片请求格式。 +其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的 +OpenAI 图像请求格式。 -`openai` provider 的 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 预览版或 GA 版本： +设置 `AZURE_OPENAI_API_VERSION`，可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本： ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" @@ -505,56 +505,52 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ### 模型名称就是 deployment 名称 -Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` provider 路由的 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`、提供 `gpt-image-2` 的 deployment： ``` -/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 +/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1 ``` -同样的 deployment 名称规则也适用于通过内置 `openai` provider 路由的图片生成调用。 +同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 ### 区域可用性 -Azure 图片生成当前仅在部分区域可用 +Azure 图像生成目前仅在部分区域可用 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 -`uaenorth`）。在创建 deployment 之前，请先检查 Microsoft 当前的 -区域列表，并确认你的区域提供了相应的特定模型。 +`uaenorth`）。创建 deployment 之前，请先查看微软当前的区域列表，并确认你的区域提供相应的具体模型。 ### 参数差异 -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 兼容路径** -折叠面板。 +OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-configuration) 下的 +**原生与兼容 OpenAI 的路由** +折叠项。 -如果你要在 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"`）。 + OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认采用 WebSocket 优先、SSE 回退（`"auto"`）的方式。 在 `"auto"` 模式下，OpenClaw 会： - - 在回退到 SSE 之前，重试一次早期 WebSocket 失败 - - 失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次标识头 - - 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`） + - 在回退到 SSE 之前，对一次早期 WebSocket 失败重试一次 + - 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次身份请求头 + - 在不同传输变体之间统一使用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| @@ -586,7 +582,7 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio - OpenClaw 默认对 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。 + OpenClaw 默认会为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。 ```json5 // 禁用预热 @@ -605,13 +601,13 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio - - OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的 Fast 模式切换： + + OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了一个共享的快速模式开关： - **聊天 / UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将 Fast 模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -626,13 +622,13 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio ``` - 会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，会话会恢复为配置中的默认值。 + 会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。 - OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置它： + OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它： ```json5 { @@ -649,21 +645,23 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。 + `serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。 - 对于直接 OpenAI Responses 模型（位于 `api.openai.com` 的 `openai/*`），OpenClaw 会自动启用服务端压缩： + 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩： - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（如不可用则为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） + + 这适用于内置的 Pi harness 路径，以及嵌入式运行所使用的 OpenAI 提供商钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。 - 对 Azure OpenAI Responses 这类兼容端点很有用： + 对于 Azure OpenAI Responses 之类的兼容端点很有用： ```json5 { @@ -715,13 +713,13 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio - `responsesServerCompaction` 只控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 + `responsesServerCompaction` 只控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 - - 对于运行在 `openai/*` 上的 GPT-5 系列，OpenClaw 可以使用更严格的嵌入式执行契约： + + 对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约： ```json5 { @@ -735,31 +733,31 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio 使用 `strict-agentic` 时，OpenClaw 会： - 当工具操作可用时，不再将仅规划的轮次视为成功进展 - - 通过“立即行动”的引导重试该轮 - - 为实质性工作自动启用 `update_plan` - - 如果模型持续规划而不行动，则显示明确的阻塞状态 + - 使用立即执行的引导重试该轮次 + - 对于较大工作自动启用 `update_plan` + - 如果模型持续规划而不执行，则显示明确的阻塞状态 - 仅作用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧模型系列会保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。 - - OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式，与通用 OpenAI 兼容 `/v1` 代理不同： + + OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式，与通用兼容 OpenAI 的 `/v1` 代理不同： - **原生路径**（`openai/*`、Azure OpenAI）： + **原生路由**（`openai/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用推理设置 + - 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning - 默认将工具 schema 设为严格模式 - - 仅在已验证的原生主机上附加隐藏归因头 - - 保留 OpenAI 专属的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏归因请求头 + - 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示） - **代理 / 兼容路径：** + **代理 / 兼容路由：** - 使用更宽松的兼容行为 - - 不强制严格工具 schema，也不附加原生专用头 + - 不强制严格工具 schema 或原生专用请求头 - Azure OpenAI 使用原生传输与兼容行为，但不会接收隐藏归因头。 + Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。 @@ -768,15 +766,15 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio - 选择 provider、模型引用和故障切换行为。 + 选择提供商、模型引用和故障切换行为。 - - 共享图片工具参数与 provider 选择。 + + 共享图像工具参数和提供商选择。 - 共享视频工具参数与 provider 选择。 + 共享视频工具参数和提供商选择。 - 认证细节与凭证复用规则。 + 认证细节和凭证复用规则。