diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index 78cfc386a..b63be788f 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: 核心 OpenClaw 键、默认值及专用子系统参考链接的 Gateway 网关配置参考 +summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-23T06:40:45Z" + generated_at: "2026-04-23T16:04:43Z" model: gpt-5.4 provider: openai - source_hash: 75c7e0d88ea6eacb8a2dd41f83033da853130dc2a689950c1a188d7c4ca8f977 + source_hash: babca02b02a019601d617a20ac35bdaa70f299434fc9be8fa3842acf5ebdaf7c source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若想查看面向任务的概览，请参见[配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若想查看面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供相应链接。它**不会**尝试在单个页面中内联所有由渠道/plugin 拥有的命令目录，或所有深层 memory/QMD 调节项。 +本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供跳转链接。它**不会**尝试在单一页面中内联每一个渠道/插件自有命令目录，或每一个深层 memory/QMD 细粒度选项。 -代码事实来源： +代码中的真实依据： -- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/plugin/渠道元数据 -- `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 配置参考](/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)，适用于当前内置 + 内置 plugin 命令目录 -- 各自所属的渠道/plugin 页面，适用于特定渠道的命令面 +- [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 会使用安全默认值。 @@ -43,28 +43,28 @@ x-i18n: 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ----------------------------------------- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；必须由所有者批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） | -| `open` | 允许所有传入私信（要求 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| --------------------- | ---- | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---------------------------------------------- | -| `allowlist`（默认） | 仅允许匹配已配置 allowlist 的群组 | -| `open` | 绕过群组 allowlist（但仍适用提及门控） | -| `disabled` | 屏蔽所有群组/房间消息 | +| 群组策略 | 行为 | +| ----------------------- | ---- | +| `allowlist`（默认） | 仅允许匹配配置的允许列表的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 阻止所有群组/房间消息 | -`channels.defaults.groupPolicy` 会在提供商的 `groupPolicy` 未设置时作为默认值。 +`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 配对码会在 1 小时后过期。待处理的私信配对请求上限为**每个渠道 3 个**。 -如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 +如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（失败时默认关闭），并在启动时给出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。只有当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），才会应用渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未拥有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### 渠道默认值和 heartbeat +### 渠道默认值和心跳 -使用 `channels.defaults` 为各提供商共享群组策略和 heartbeat 行为： +使用 `channels.defaults` 为各提供商设置共享的群组策略和心跳行为： ```json5 { @@ -106,14 +106,14 @@ x-i18n: ``` - `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自 allowlist 发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 -- `channels.defaults.heartbeat.showOk`：在 heartbeat 输出中包含健康的渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在 heartbeat 输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染 heartbeat 输出。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 +- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 +- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联会话时会自动启动。 +WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。在存在已关联会话时会自动启动。 ```json5 { @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 蓝色对勾（在 self-chat 模式下为 false） + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,10 +164,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 出站命令默认使用 `default` 账号（如果存在）；否则使用第一个已配置的账号 ID（排序后）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖该回退默认账号选择。 +- 出站命令默认使用账号 `default`；如果不存在，则使用第一个已配置的账号 ID（按排序顺序）。 +- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配某个已配置账号 ID 时，覆盖该默认账号选择。 - 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 每账号覆盖项：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 按账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress（默认：off；请显式选择启用，以避免预览编辑速率限制） + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ 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` 会发出警告。 +- 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`（可在私聊和群聊中工作）。 -- 重试策略：参见[重试策略](/zh-CN/concepts/retry)。 +- 顶层 `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 @@ -286,7 +286,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial） + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用项 + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,35 +334,35 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 ``` - Token：`channels.discord.token`，默认账号还可回退使用 `DISCORD_BOT_TOKEN`。 -- 直接出站调用如果显式提供 Discord `token`，则该次调用会使用该 token；账号重试/策略设置仍来自活动运行时快照中选定的账号。 -- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 -- 交付目标请使用 `user:`（私信）或 `channel:`（guild 渠道）；裸数字 ID 会被拒绝。 -- Guild slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不带 `#`）。优先使用 guild ID。 -- 默认会忽略由 bot 编写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该 bot 的 bot 消息（仍会过滤 bot 自己的消息）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及 bot 的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使它们未超过 2000 个字符。 +- 直接出站调用如果显式提供了 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` 表示禁用） + - `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` 会将运行时可用性映射为 bot 在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急破玻璃兼容模式）。 -- `channels.discord.execApprovals`：原生 Discord 的 exec 审批交付和审批者授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，exec 审批会被激活。 +- 顶层 `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` 将运行时可用性映射为机器人在线状态（健康 => online，降级 => idle，耗尽 => 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 allowlist。省略时会为所有智能体转发审批请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示的发送位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到原始渠道，`"both"` 同时发送到两处。当 target 包含 `"channel"` 时，按钮仅对已解析的审批者可用。 - - `cleanupAfterResolve`：为 `true` 时，会在批准、拒绝或超时后删除审批私信。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到发起频道，`"both"` 两者都发送。当 target 包含 `"channel"` 时，按钮仅对已解析出的审批者可用。 + - `cleanupAfterResolve`：为 `true` 时，在审批通过、拒绝或超时后删除审批私信。 -**Reaction notification 模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 +**Reaction notification 模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds..users` 中用户在所有消息上的反应）。 ### Google Chat @@ -396,8 +396,8 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 - 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 交付目标请使用 `spaces/` 或 `users/`。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急破玻璃兼容模式）。 +- 对投递目标使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变 email principal 匹配（破窗式兼容模式）。 ### Slack @@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式传输 API + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,38 +464,34 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- **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 完成配置，但当前命令/运行时路径无法解析出对应的密钥值。 +- **Socket 模式**需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式**需要 `botToken` 加上 `signingSecret`（在根级或按账号设置）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- Slack 账号快照会暴露按凭证划分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `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:`。 **Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可以是按线程隔离（默认）或在渠道内共享。`thread.inheritParent` 会将父渠道对话记录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 为每线程独立（默认）或在整个频道共享。`thread.inheritParent` 会将父频道的转录复制到新线程中。 -- Slack 原生流式传输加上 Slack 助手风格的 “is typing...” 线程状态，需要一个回复线程目标。顶层私信默认保持在线程之外，因此它们会使用 `typingReaction` 或常规交付，而不是线程样式预览。 -- `typingReaction` 会在回复运行期间，向传入的 Slack 消息添加一个临时 reaction，并在完成后移除。请使用 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 助手风格的“正在输入...”线程状态需要回复目标是线程。顶层私信默认保持非线程，因此会使用 `typingReaction` 或常规投递，而不是线程式预览。 +- `typingReaction` 会在回复进行期间向传入的 Slack 消息添加一个临时 reaction，并在完成后移除。使用 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"`）。 -| 操作组 | 默认值 | 说明 | -| ----------- | ------ | -------------------- | -| reactions | 启用 | 添加 reaction + 列出 reactions | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 置顶/取消置顶/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ------------ | ------- | ---------------------- | +| reactions | 已启用 | 添加 reaction + 列出 reactions | +| messages | 已启用 | 读取/发送/编辑/删除 | +| pins | 已启用 | 置顶/取消置顶/列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 作为一个 plugin 提供：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -512,10 +508,10 @@ Mattermost 作为一个 plugin 提供：`openclaw plugins install @openclaw/matt "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 显式启用 + native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 面向反向代理/公网部署的可选显式 URL + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -527,20 +523,16 @@ Mattermost 作为一个 plugin 提供：`openclaw plugins install @openclaw/matt 聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 -启用 Mattermost 原生命令时： +当启用 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.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器必须能访问到它。 +- 原生 slash 回调使用 Mattermost 在注册 slash 命令期间返回的按命令分配 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.requireMention`：在频道中回复前要求 `@mention`。 +- `channels.mattermost.groups..requireMention`：按频道覆盖提及门控（`"*"` 表示默认）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 ### Signal @@ -549,7 +541,7 @@ Mattermost 作为一个 plugin 提供：`openclaw plugins install @openclaw/matt channels: { signal: { enabled: true, - account: "+15555550123", // 可选的账号绑定 + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -565,11 +557,11 @@ Mattermost 作为一个 plugin 提供：`openclaw plugins install @openclaw/matt - `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 接入路径（由 plugin 提供支持，配置位于 `channels.bluebubbles` 下）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles` 下）。 ```json5 { @@ -577,21 +569,21 @@ BlueBubbles 是推荐的 iMessage 接入路径（由 plugin 提供支持，配 bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl、password、webhookPath、群组控制以及高级 actions： - // 参见 /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` - 此处涵盖的核心键路径：`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 { @@ -615,15 +607,15 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时，覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账号 ID 时覆盖默认账号选择。 - 需要对 Messages 数据库授予完全磁盘访问权限。 -- 优先使用 `chat_id:` 目标。可使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）可用于通过 SCP 获取附件。 +- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 +- `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)。 @@ -636,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由 plugin 提供支持，配置位于 `channels.matrix` 下。 +Matrix 由插件支持，配置位于 `channels.matrix` 下。 ```json5 { @@ -667,24 +659,24 @@ Matrix 由 plugin 提供支持，配置位于 `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.defaultAccount` 用于在多账号设置中选择首选账号。 +- `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.execApprovals`：Matrix 原生 exec 审批投递与审批者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，exec 审批会启用。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID allowlist。省略时会为所有智能体转发审批请求。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：审批提示的发送位置。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组为会话：`per-user`（默认）按路由对端共享，而 `per-room` 则隔离每个私信房间。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组到会话中：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 +- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 ### Microsoft Teams -Microsoft Teams 由 plugin 提供支持，配置位于 `channels.msteams` 下。 +Microsoft Teams 由插件支持，配置位于 `channels.msteams` 下。 ```json5 { @@ -692,19 +684,19 @@ Microsoft Teams 由 plugin 提供支持，配置位于 `channels.msteams` 下。 msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、团队/渠道策略： - // 参见 /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC -IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 +IRC 由插件支持，配置位于 `channels.irc` 下。 ```json5 { @@ -726,12 +718,12 @@ IRC 由 plugin 提供支持，配置位于 `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 渠道配置（主机/端口/TLS/频道/允许列表/提及门控）见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： +每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -739,11 +731,11 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 telegram: { accounts: { default: { - name: "主 bot", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "告警 bot", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -752,18 +744,18 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 } ``` -- 当省略 `accountId` 时，会使用 `default`（CLI + 路由）。 -- 环境变量 token 只适用于**默认**账号。 -- 基础渠道设置适用于所有账号，除非在各账号中单独覆盖。 -- 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍处于单账号顶层渠道配置，OpenClaw 会先将按账号作用域划分的顶层单账号值提升到该渠道的账号映射中，以确保原始账号继续可用。大多数渠道会将它们移到 `channels..accounts.default`；而 Matrix 则可以改为保留现有的匹配命名/默认目标。 -- 现有仅渠道级的绑定（无 `accountId`）将继续匹配默认账号；按账号作用域的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会修复混合形态，方法是将按账号作用域划分的顶层单账号值移动到为该渠道选定的提升账号中。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有的匹配命名/默认目标。 +- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 +- 环境变量 token 仅适用于**默认**账号。 +- 基础渠道设置适用于所有账号，除非按账号覆盖。 +- 使用 `bindings[].match.accountId` 将每个账号路由到不同智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，而当前仍处于单账号顶层渠道配置，OpenClaw 会先将账号范围的顶层单账号值提升到该渠道的账号映射中，以便原账号继续工作。大多数渠道会将这些值移到 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/默认目标。 +- 现有仅渠道级的绑定（无 `accountId`）会继续匹配默认账号；账号范围绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将账号范围的顶层单账号值移动到为该渠道选定的提升账号中，来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/默认目标。 -### 其他插件渠道 +### 其他渠道插件 -许多 plugin 渠道都配置为 `channels.`，并在各自专属的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参见完整的渠道索引：[渠道](/zh-CN/channels)。 +许多渠道插件配置为 `channels.`，并在其专用渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +查看完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 @@ -771,9 +763,9 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式下会被忽略。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式下会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当可以进行检测时（原生提及或至少存在一个模式）才会强制执行提及门控。 +- 仅在能够检测提及时（原生提及或至少存在一个模式）才会强制执行提及门控。 ```json5 { @@ -786,9 +778,9 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。各渠道可通过 `channels..historyLimit`（或按账号）进行覆盖。设为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 -#### 私信历史记录限制 +#### 私信历史限制 ```json5 { @@ -803,13 +795,13 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 不限制（保留全部）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### self-chat 模式 +#### 自聊模式 -将你自己的号码包含在 `allowFrom` 中以启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码包含在 `allowFrom` 中以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -830,21 +822,21 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 } ``` -### 命令（聊天命令处理） +### Commands（聊天命令处理） ```json5 { commands: { - native: "auto", // 在支持时注册原生命令 - nativeSkills: "auto", // 在支持时注册原生 Skills 命令 - text: true, // 解析聊天消息中的 /commands - bash: false, // 允许 !（别名：/bash） + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // 允许 /config - mcp: false, // 允许 /mcp - plugins: false, // 允许 /plugins - debug: false, // 允许 /debug - restart: true, // 允许 /restart + gateway restart 工具 + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -859,30 +851,30 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 -- 此块配置命令面。当前内置 + 内置 plugin 命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键参考**，不是完整的命令目录。诸如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、memory `/dreaming`、phone-control `/phone` 以及 Talk `/voice` 这类由渠道/plugin 拥有的命令，记录在它们各自的渠道/plugin 页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 此块用于配置命令面。当前内置 + 内置插件的命令目录见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、memory `/dreaming`、手机控制 `/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 bot 菜单项。 -- `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 客户端可用。 +- `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 客户端仍然可用。 - `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 会为 plugin 发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 会按渠道控制配置变更（默认：true）。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用/禁用控制。 +- `channels..configWrites` 按渠道控制配置变更（默认：true）。 - 对于多账号渠道，`channels..accounts..configWrites` 也会控制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认值：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner allowlist。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner id 进行哈希处理。设置 `ownerDisplaySecret` 可控制哈希方式。 -- `allowFrom` 按提供商生效。设置后，它将成为**唯一**的授权来源（渠道 allowlist/配对以及 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 会在未设置 `allowFrom` 时，允许命令绕过访问组策略。 +- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启工具操作。默认值：`true`。 +- `ownerAllowFrom` 是 owner 专属命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在 system prompt 中对 owner ID 做哈希。设置 `ownerDisplaySecret` 可控制哈希方式。 +- `allowFrom` 按提供商设置。一旦设置，它就是**唯一**授权来源（渠道允许列表/配对以及 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 会在未设置 `allowFrom` 时，让命令绕过访问组策略。 - 命令文档映射： - - 内置 + 内置变体目录：[Slash Commands](/zh-CN/tools/slash-commands) - - 渠道专属命令面：[渠道](/zh-CN/channels) + - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) + - 渠道专属命令面：[Channels](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[配对](/zh-CN/channels/pairing) + - 配对命令：[Pairing](/zh-CN/channels/pairing) - LINE 卡片命令：[LINE](/zh-CN/channels/line) - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -904,7 +896,7 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从 workspace 向上遍历并自动检测。 +可选的仓库根目录，会显示在 system prompt 的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。 ```json5 { @@ -914,18 +906,16 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### `agents.defaults.skills` -为未设置 -`agents.list[].skills` -的智能体提供可选的默认 Skills allowlist。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // 继承 github、weather - { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 无 Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } @@ -933,13 +923,12 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 - 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。 - 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示不使用 Skills。 -- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它 - 不会与默认值合并。 +- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建 workspace bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -949,9 +938,9 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入到 system prompt 中。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在 assistant 已完成一次响应之后）会跳过重新注入 workspace bootstrap，从而减小提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续写轮次（在 assistant 已完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小 prompt 大小。Heartbeat 运行和压缩后重试仍会重建上下文。 ```json5 { @@ -961,7 +950,7 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -每个 workspace bootstrap 文件在截断前允许的最大字符数。默认值：`12000`。 +单个工作区 bootstrap 文件在被截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -971,7 +960,7 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapTotalMaxChars` -跨所有 workspace bootstrap 文件注入的最大总字符数。默认值：`60000`。 +跨所有工作区 bootstrap 文件注入的总最大字符数。默认值：`60000`。 ```json5 { @@ -981,11 +970,10 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，对智能体可见的警告文本。 -默认值：`"once"`。 +控制 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：绝不在系统提示中注入警告文本。 -- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。 +- `"off"`：绝不向 system prompt 注入警告文本。 +- `"once"`：对每个唯一的截断签名只注入一次警告（推荐）。 - `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 @@ -996,32 +984,29 @@ IRC 由 plugin 提供支持，配置位于 `channels.irc` 下。 ### 上下文预算归属映射 -OpenClaw 有多个高容量的提示/上下文预算，它们 -被有意按子系统拆分，而不是全部流经一个通用 -旋钮。 +OpenClaw 具有多个高容量 prompt/上下文预算，它们会按子系统有意拆分，而不是全部汇入一个通用开关。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 常规 workspace bootstrap 注入。 + 常规工作区 bootstrap 注入。 - `agents.defaults.startupContext.*`： 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入系统提示中的精简 Skills 列表。 + 注入到 system prompt 中的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： - 有边界的运行时摘录和由运行时拥有的注入块。 + 有界的运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引 memory 搜索片段和注入大小。 + 已索引 memory 搜索片段及注入尺寸控制。 -仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖项： +仅当某个智能体需要不同预算时，再使用对应的按智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` -运行时注入的首轮启动前导内容。 +控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -1042,7 +1027,7 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 #### `agents.defaults.contextLimits` -为有边界的运行时上下文面提供共享默认值。 +为有界运行时上下文面提供共享默认值。 ```json5 { @@ -1059,19 +1044,14 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 } ``` -- `memoryGetMaxChars`：`memory_get` 摘录的默认上限；超过后会添加截断 - 元数据和续接提示。 -- `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认 - 行窗口。 -- `toolResultMaxChars`：用于持久化结果和 - 溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：在压缩后刷新注入期间使用的 - `AGENTS.md` 摘录上限。 +- `memoryGetMaxChars`：默认的 `memory_get` 摘录上限；超出后会附加截断元数据和继续提示。 +- `memoryGetDefaultLines`：省略 `lines` 时默认的 `memory_get` 行窗口。 +- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 +- `postCompactionMaxChars`：压缩后刷新注入期间用于 `AGENTS.md` 摘录的上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 旋钮的按智能体覆盖项。省略的字段会继承 -`agents.defaults.contextLimits`。 +针对共享 `contextLimits` 开关的按智能体覆盖。省略的字段会继承 `agents.defaults.contextLimits`。 ```json5 { @@ -1097,8 +1077,7 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 #### `skills.limits.maxSkillsPromptChars` -注入系统提示中的精简 Skills 列表的全局上限。这 -不会影响按需读取 `SKILL.md` 文件。 +注入到 system prompt 中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -1112,7 +1091,7 @@ OpenClaw 有多个高容量的提示/上下文预算，它们 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示预算的按智能体覆盖项。 +针对 Skills prompt 预算的按智能体覆盖。 ```json5 { @@ -1131,11 +1110,11 @@ Skills 提示预算的按智能体覆盖项。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录/工具图像块中图像最长边允许的最大像素尺寸。 默认值：`1200`。 -较低的值通常会降低 vision token 使用量，并减小以截图为主运行时的请求负载大小。 -较高的值则能保留更多视觉细节。 +较低的值通常会减少 vision token 使用量，以及以截图为主的运行中的请求负载大小。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -1145,7 +1124,7 @@ Skills 提示预算的按智能体覆盖项。 ### `agents.defaults.userTimezone` -系统提示上下文所用的时区（不是消息时间戳）。会回退到主机时区。 +用于 system prompt 上下文的时区（不是消息时间戳）。会回退到主机时区。 ```json5 { @@ -1155,7 +1134,7 @@ Skills 提示预算的按智能体覆盖项。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +system prompt 中的时间格式。默认值：`auto`（OS 偏好）。 ```json5 { @@ -1193,9 +1172,9 @@ Skills 提示预算的按智能体覆盖项。 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 全局默认提供商参数 + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { - runtime: "auto", // auto | pi | 已注册 harness id，例如 codex + runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1212,51 +1191,51 @@ Skills 提示预算的按智能体覆盖项。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 字符串形式只设置主模型。 - - 对象形式设置主模型以及有序故障切换模型。 -- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用作 `image` 工具路径的 vision 模型配置。 - - 当所选/默认模型无法接受图像输入时，也会用作回退路由。 -- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享图像生成能力，以及任何未来会生成图像的工具/plugin 表面。 - - 常见取值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key（例如 `google/*` 对应的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 对应的 `OPENAI_API_KEY`，`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 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/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` 仍可推断出带认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key。 - - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 +- `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，也要配置对应的提供商认证/API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`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 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` 仍可推断基于认证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider/model，也要配置对应的提供商认证/API key。 + - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`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`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续暴露一个过时的、已移除提供商默认值。 -- `models`：供 `/model` 使用的已配置模型目录和 allowlist。每个条目都可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 来添加条目。`config set` 会拒绝会移除现有 allowlist 条目的替换操作，除非你传入 `--replace`。 - - 按提供商作用域的配置/新手引导流程会将选定提供商的模型合并到此映射中，并保留已配置的无关提供商。 -- `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"` 可让已注册的 plugin harness 接管受支持模型，使用 `runtime: "pi"` 可强制使用内置 PI harness，或使用已注册 harness id，如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退 add/remove 命令）会保存规范的对象形式，并在可能时保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍是串行的）。默认值：4。 +- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，再尝试对该精确模型 ID 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式的 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续保留一个已删除提供商的陈旧默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。 + - 提供商范围的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已经配置的无关提供商。 +- `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。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制哪种底层执行器来运行嵌入式智能体轮次。 -大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 -当受信任的 plugin 提供原生 harness 时可以使用它，例如内置的 -Codex app-server harness。 +`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 +大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 +当受信任的插件提供原生 harness 时使用它，例如内置的 +Codex 应用服务器 harness。 ```json5 { @@ -1272,15 +1251,16 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的 plugin harness id。内置 Codex plugin 注册的是 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。当未选择 plugin harness 时，`"pi"` 会保留内置 PI harness 作为兼容回退；`"none"` 则会在缺少或不支持所选 plugin harness 时直接失败，而不是静默使用 PI。所选 plugin harness 的失败始终会直接暴露。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness ID。内置 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。当未选中任何插件 harness 时，`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会让缺失或不受支持的插件 harness 选择直接失败，而不是静默使用 PI。已选中的插件 harness 失败则始终会直接显现。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 -- 对于仅使用 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 这只控制嵌入式聊天 harness。媒体生成、vision、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。 +- 对于仅 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 在第一次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变量变更只影响新的或已重置的会话，不影响现有转录。具有转录历史但未记录固定值的旧会话会被视为固定为 PI。`/status` 会在 `Fast` 旁边显示非 PI 的 harness ID，例如 `codex`。 +- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍然使用各自的 provider/model 设置。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | +| 别名 | 模型 | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1294,12 +1274,12 @@ 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 模型默认启用 `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 { @@ -1329,11 +1309,11 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - CLI 后端以文本为主；工具始终禁用。 - 设置了 `sessionArg` 时支持会话。 -- 如果 `imageArg` 接受文件路径，则支持图像透传。 +- 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换由 OpenClaw 组装的整个系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示实验。 +用固定字符串替换由 OpenClaw 组装的整个 system prompt。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体级别（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控的 prompt 实验。 ```json5 { @@ -1347,7 +1327,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.promptOverlays` -按模型家族应用、与提供商无关的提示覆盖。GPT-5 系列模型 ID 会跨提供商接收共享行为契约；`personality` 仅控制友好交互风格这一层。 +按模型家族应用的、与提供商无关的 prompt overlays。GPT-5 系列模型 ID 会跨提供商接收共享行为契约；`personality` 仅控制友好交互风格层。 ```json5 { @@ -1364,28 +1344,28 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `"friendly"`（默认）和 `"on"` 会启用友好交互风格层。 -- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍然启用。 -- 当此共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 +- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 +- 当该共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` -定期 heartbeat 运行。 +定期 Heartbeat 运行。 ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m 表示禁用 + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 - lightContext: false, // 默认：false；true 仅保留 workspace bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 会在全新会话中运行每次 heartbeat（无对话历史） + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认）| block - target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1396,15 +1376,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `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 时，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。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 +- `includeSystemPromptSection`：为 false 时，会从 system prompt 中省略 Heartbeat 段，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最大秒数。留空则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：为 true 时，Heartbeat 运行会使用轻量 bootstrap 上下文，并且仅保留工作区 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` @@ -1414,14 +1394,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 已注册 compaction provider plugin 的 id（可选） + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 - postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 - model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖 - notifyUser: true, // 在 compaction 开始和完成时向用户发送简短通知（默认：false） + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1434,19 +1414,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（对长历史进行分块摘要）。参见[Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction provider plugin 的 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`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。当主会话应继续使用某个模型，但 compaction 摘要应改用另一个模型时可使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 之前执行一次静默的智能体轮次，以存储持久 memory。若 workspace 为只读则会跳过。 +- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction 提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置的 LLM 摘要。失败时回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：单次 compaction 操作在被 OpenClaw 中止前允许的最大秒数。默认值：`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 开始和完成时向用户发送简短通知（例如“Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默。 +- `memoryFlush`：自动 compaction 之前的静默智能体轮次，用于存储持久 memory。工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在将内容发送到 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存中的上下文裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1454,7 +1434,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟 + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1468,25 +1448,25 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` - + -- `mode: "cache-ttl"` 会启用修剪流程。 -- `ttl` 控制下一次允许再次运行修剪的时间（自上次缓存触达之后）。 -- 修剪会先对过大的工具结果执行软截断，然后在需要时对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用裁剪过程。 +- `ttl` 控制何时允许再次运行裁剪（自上次缓存触碰之后）。 +- 裁剪会先对过大的工具结果进行软裁剪，如仍有需要，再对更旧的工具结果进行硬清除。 -**软截断**会保留开头和结尾，并在中间插入 `...`。 +**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被截断/清除。 -- 比例基于字符数（近似），而不是精确 token 数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过修剪。 +- 图像块永远不会被裁剪/清除。 +- 比例基于字符数（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过裁剪。 -行为细节请参见[会话修剪](/zh-CN/concepts/session-pruning)。 +行为细节参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1498,7 +1478,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs） + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } @@ -1506,11 +1486,11 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参见[流式传输](/zh-CN/concepts/streaming)。 +行为和分块细节参见 [Streaming](/zh-CN/concepts/streaming)。 -### 输入中指示器 +### 输入指示器 ```json5 { @@ -1523,16 +1503,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/提及使用 `instant`，未被提及的群聊使用 `message`。 +- 默认值：对于私聊/提及为 `instant`，对于未提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见[输入中指示器](/zh-CN/concepts/typing-indicators)。 +参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1578,7 +1558,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // 也支持 SecretRef / 内联内容： + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1635,16 +1615,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `ssh`：通用的 SSH 支持远程运行时 - `openshell`：OpenShell 运行时 -当选择 `backend: "openshell"` 时，运行时特定设置会移到 +当选择 `backend: "openshell"` 时，运行时特定设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域 workspace 的远程绝对根路径 +- `workspaceRoot`：用于按作用域工作区的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其物化为临时文件 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 认证优先级：** @@ -1652,29 +1632,29 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从活动 secrets 运行时快照中解析 +- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前从活动 secrets 运行时快照中解析 **SSH 后端行为：** -- 在 create 或 recreate 后对远程 workspace 执行一次初始化 -- 然后保持远程 SSH workspace 为规范版本 +- 在创建或重建后，一次性初始化远程工作区 +- 然后持续将远程 SSH 工作区保持为规范状态 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 -**Workspace 访问：** +**工作区访问：** -- `none`：按作用域在 `~/.openclaw/sandboxes` 下创建沙箱 workspace -- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` -- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` +- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 +- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` +- `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** -- `session`：按会话划分的容器 + workspace -- `agent`：每个智能体一个容器 + workspace（默认） -- `shared`：共享容器和 workspace（无跨会话隔离） +- `session`：每个会话一个容器 + 工作区 +- `agent`：每个智能体一个容器 + 工作区（默认） +- `shared`：共享容器和工作区（无跨会话隔离） -**OpenShell plugin 配置：** +**OpenShell 插件配置：** ```json5 { @@ -1687,10 +1667,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // 可选 - gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选 OpenShell policy id - providers: ["openai"], // 可选 + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1702,29 +1682,29 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在 exec 前从本地播种到远程，在 exec 后同步回本地；本地 workspace 保持为规范版本 -- `remote`：在创建沙箱时只向远程播种一次，然后保持远程 workspace 为规范版本 +- `mirror`：在执行前将本地内容播种到远端，执行后再同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时将本地内容一次性播种到远端，之后保持远端工作区为规范副本 -在 `remote` 模式下，播种步骤之后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步到沙箱中。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但 sandbox 生命周期和可选的镜像同步由 plugin 负责。 +在 `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`（破窗式开关）。 -**传入附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 +**传入附件**会被暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会被合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入系统提示。它不要求在 `openclaw.json` 中启用 `browser.enabled`。 -默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到 system prompt 中。不需要在 `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`。 +- `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=` @@ -1744,16 +1724,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果你的 WebGL/3D 使用场景需要它们，可通过 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些默认项。 - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 可重新启用扩展，如果你的工作流 - 依赖这些扩展。 + 默认启用；如果 WebGL/3D 使用场景需要它们，可通过 + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 + - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 将使用 Chromium 的 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的 默认进程上限。 - - 此外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值属于容器镜像基线；如需更改容器默认值，请使用带有自定义 - entrypoint 的自定义浏览器镜像。 + - 当启用 `noSandbox` 时，另外附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 默认值是容器镜像基线；如需修改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 @@ -1763,7 +1741,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ```bash scripts/sandbox-setup.sh # 主沙箱镜像 -scripts/sandbox-browser-setup.sh # 可选浏览器镜像 +scripts/sandbox-browser-setup.sh # 可选的浏览器镜像 ``` ### `agents.list`（按智能体覆盖） @@ -1778,13 +1756,13 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体的 thinking 级别覆盖 - reasoningDefault: "on", // 按智能体的 reasoning 可见性覆盖 - fastModeDefault: false, // 按智能体的 fast mode 覆盖 + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置后会替换 agents.defaults.skills + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1815,27 +1793,27 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `id`：稳定的智能体 id（必填）。 -- `default`：当设置了多个时，第一个生效（会记录警告）。如果一个都没设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。只覆盖 `primary` 的 cron 任务仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定的模型条目之上。可用于设置智能体特定的覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills allowlist。若省略，当 `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 会话时，请使用带有 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）的 `type: "acp"`。 -- `identity.avatar`：相对于 workspace 的路径、`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`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话快速模式覆盖时应用。 +- `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。 - `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id allowlist（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱模式运行的目标。 +- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式配置选择；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个彼此隔离的智能体。参见[多智能体](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关内运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1854,12 +1832,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `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 }` **确定性的匹配顺序：** @@ -1867,16 +1845,16 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 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 绑定层级顺序。 -### 按智能体访问配置文件 +### 按智能体划分的访问配置 - + ```json5 { @@ -1894,7 +1872,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1969,7 +1947,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节请参见[多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1995,22 +1973,22 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 父线程 token 数高于此值时跳过父线程分叉（0 表示禁用） + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // 时长或 false - maxDiskBytes: "500mb", // 可选硬预算 - highWaterBytes: "400mb", // 可选清理目标 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的不活动自动取消聚焦（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计算的硬性最大存续时间（`0` 表示禁用） + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // 旧版字段（运行时始终使用 "main"） + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -2023,34 +2001,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`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` 后重置。当两者都已配置时，哪个先到期就以哪个为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。 - - 如果父会话 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父会话对话历史。 - - 设为 `0` 可禁用此保护，并始终允许父会话分叉。 +- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都已配置，则以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名使用。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，允许的父会话最大 `totalTokens`（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 + - 设置为 `0` 可禁用此保护，并始终允许父级分叉。 - **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间在智能体对智能体交换期间允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式往返。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 优先生效。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间交换时，允许的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 - - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认为 `pruneAfter`；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 + - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 + - `pruneAfter`：陈旧条目的时效截止（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认继承 `pruneAfter`；设置为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘硬预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大存续时间（`0` 表示禁用；提供商可覆盖） + - `idleHours`：按小时计算的默认无活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：按小时计算的默认硬性最大存续时间（`0` 表示禁用；提供商可覆盖） @@ -2061,7 +2039,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ```json5 { messages: { - responsePrefix: "🦞", // 或 "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2076,7 +2054,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, }, inbound: { - debounceMs: 2000, // 0 表示禁用 + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -2086,38 +2064,38 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -### 响应前缀 +### 回复前缀 按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | -------------------- | --------------------------- | -| `{model}` | 简短模型名称 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 描述 | 示例 | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | 简短模型名称 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | +| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认 reaction -- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 +- 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。 - 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 - 在 Slack 和 Discord 上，未设置时，如果确认 reaction 处于启用状态，则状态 reaction 保持启用。 - 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态 reaction。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除 ack。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reactions。 + 在 Slack 和 Discord 上，未设置时会在 ack reactions 处于激活状态时保持状态 reactions 启用。 + 在 Telegram 上，需要显式将其设为 `true` 才会启用生命周期状态 reactions。 -### 传入防抖 +### 入站防抖 -将同一发送者的快速纯文本消息合并为单个智能体轮次。媒体/附件会立即触发刷新。控制命令会绕过防抖。 +将来自同一发送者的快速纯文本消息批量合并为一次智能体轮次。媒体/附件会立即冲刷。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -2160,18 +2138,18 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 -- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。 -- `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 服务器，并放宽模型/语音校验。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式启用）。 +- API keys 会回退到 `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-compatible TTS 服务器，并放宽对模型/语音的验证。 --- ## Talk -Talk 模式（macOS/iOS/Android）的默认值。 +Talk 模式的默认值（macOS/iOS/Android）。 ```json5 { @@ -2196,12 +2174,12 @@ Talk 模式（macOS/iOS/Android）的默认值。 ``` - 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `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 key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 +- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录文本。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -2209,37 +2187,37 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础 allowlist： +`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： -本地新手引导会在未设置时将新的本地配置默认设为 `tools.profile: "coding"`（现有显式配置文件会被保留）。 +本地新手引导在未设置时，默认将新的本地配置设为 `tools.profile: "coding"`（已显式设置的现有 profile 会保留）。 -| 配置文件 | 包含内容 | +| 配置文件 | 包含内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | +| `minimal` | 仅 `session_status` | | `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | | `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 分组 | 工具 | +| 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括 provider 插件） | +| `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` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 +全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 ```json5 { @@ -2249,7 +2227,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -进一步限制特定提供商或模型可用的工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 +针对特定提供商或模型进一步限制工具。顺序：基础 profile → 提供商 profile → allow/deny。 ```json5 { @@ -2265,7 +2243,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.elevated` -控制沙箱外的提升权限 `exec` 访问： +控制沙箱外的 elevated exec 访问： ```json5 { @@ -2281,9 +2259,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- 每个智能体的覆盖配置（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅对单条消息生效。 -- 提权后的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，或者当 `exec` 目标为 `node` 时使用 `node`）。 +- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令只应用于单条消息。 +- Elevated `exec` 会绕过沙箱隔离，并使用已配置的 escape 路径（默认 `gateway`，或当 exec 目标是 `node` 时使用 `node`）。 ### `tools.exec` @@ -2307,8 +2285,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` -工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。 -设置可在全局 `tools.loopDetection` 中定义，也可在每个智能体的 `agents.list[].tools.loopDetection` 中覆盖。 +工具循环安全检查默认**禁用**。设置 `enabled: true` 以启用检测。 +设置可在全局 `tools.loopDetection` 中定义，并可在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2329,14 +2307,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史记录数。 -- `warningThreshold`：触发警告的重复无进展模式阈值。 +- `historySize`：为循环分析保留的最大工具调用历史。 +- `warningThreshold`：用于发出警告的重复无进展模式阈值。 - `criticalThreshold`：用于阻止严重循环的更高重复阈值。 - `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复调用相同工具且参数相同的情况发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展轮询发出警告或阻止。 -- `detectors.pingPong`：对交替出现且无进展的成对模式发出警告或阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，则验证会失败。 +- `detectors.genericRepeat`：对重复的同一工具/同一参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 +- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2346,14 +2324,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 web: { search: { enabled: true, - apiKey: "brave_api_key", // 或 BRAVE_API_KEY 环境变量 + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略时自动检测 + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2370,7 +2348,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.media` -配置传入媒体理解能力（图片/音频/视频）： +配置传入媒体理解（图像/音频/视频）： ```json5 { @@ -2378,7 +2356,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 选择启用：异步音乐/视频完成后直接发送到渠道 + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2406,28 +2384,28 @@ Talk 模式（macOS/iOS/Android）的默认值。 **提供商条目**（`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"`）： -- `command`：要运行的可执行命令 +- `command`：要运行的可执行文件 - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等） **通用字段：** - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 -- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每个条目的覆盖设置。 +- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** -- `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` +- `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` 和 `video_generate` 任务会优先尝试直接投递到渠道。默认值：`false` - （旧版请求者会话唤醒/模型投递路径）。 + （旧版的请求方会话唤醒/模型投递路径）。 @@ -2446,9 +2424,9 @@ provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m ### `tools.sessions` -控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可定位哪些会话。 -默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。 +默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 ```json5 { @@ -2464,10 +2442,10 @@ provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： - `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` @@ -2478,11 +2456,11 @@ provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m tools: { sessions_spawn: { attachments: { - enabled: false, // 选择启用：设为 true 以允许内联文件附件 - maxTotalBytes: 5242880, // 所有文件合计最多 5 MB + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, - maxFileBytes: 1048576, // 每个文件最多 1 MB - retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 + maxFileBytes: 1048576, // 1 MB per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2491,24 +2469,24 @@ provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： -- 附件仅支持 `runtime: "subagent"`。ACP runtime 会拒绝它们。 -- 文件会以实体形式写入子工作区的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 +- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 +- 文件会被物化到子工作区中的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会通过严格的字母表/填充校验以及解码前大小保护进行验证。 +- Base64 输入会通过严格的字母表/填充检查以及解码前大小保护进行验证。 - 文件权限为：目录 `0700`，文件 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 总是删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 +- 清理由 `cleanup` 策略控制：`delete` 总会移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 +实验性内置工具标志。默认关闭，除非适用严格智能体式 GPT-5 自动启用规则。 ```json5 { tools: { experimental: { - planTool: true, // 启用实验性的 update_plan + planTool: true, // enable experimental update_plan }, }, } @@ -2517,8 +2495,8 @@ provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m 说明： - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每个智能体的覆盖值）被设置为 `"strict-agentic"`，且当前运行使用的是 OpenAI 或 OpenAI Codex 的 GPT-5 系列模型。设为 `true` 可在该范围之外强制启用此工具；设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示也会添加使用指导，以便模型仅在处理重要工作时使用它，并且最多只保留一个 `in_progress` 步骤。 +- 默认值：`false`，除非在 OpenAI 或 OpenAI Codex GPT-5 系列运行中，`agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 `"strict-agentic"`。设置 `true` 可在该范围外强制启用该工具；设置 `false` 则即使在严格智能体式 GPT-5 运行中也保持关闭。 +- 启用后，system prompt 还会添加使用指导，使模型仅在较重工作中使用它，并且最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2538,21 +2516,21 @@ provider 凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `m } ``` -- `model`：派生子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可定向的目标智能体 id 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `model`：生成的子智能体默认模型。若省略，子智能体会继承调用方模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 默认允许的目标智能体 ID 列表（`["*"]` = 任意；默认：仅同一智能体）。 - `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时时间（秒）。`0` 表示无超时。 -- 每个子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- 按子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- -## 自定义 provider 和 base URL +## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 +OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { models: { - mode: "merge", // merge（默认） | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2576,51 +2554,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` 值仅在该 provider 在当前 config/auth-profile 上下文中不是由 SecretRef 管理时优先。 - - 由 SecretRef 管理的 provider `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的 provider 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` 会在存在时保留显式运行时上限；当你想限制有效上下文而不更改模型原生元数据时，可使用它。 + - 对于匹配模型的 `contextWindow`/`maxTokens`，会使用显式配置值与隐式目录值中较高的那个。 + - 对于匹配模型的 `contextTokens`，若显式运行时上限存在，则会保留它；当你希望缩小有效上下文预算、但不更改原生模型元数据时，可使用它。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 + - 标记持久化以源为准：标记来自活动源配置快照（解析前），而不是来自已解析的运行时 secret 值。 -### provider 字段详情 +### 提供商字段详情 -- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 -- `models.providers`：按 provider id 键控的自定义 provider 映射。 - - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。`config set` 会拒绝破坏性替换，除非你传入 `--replace`。 +- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 +- `models.providers`：以提供商 ID 为键的自定义提供商映射。 + - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge`，或使用 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：provider 凭证（优先使用 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.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，在请求中注入 `options.num_ctx`（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 -- `models.providers.*.baseUrl`：上游 API 的 base URL。 +- `models.providers.*.baseUrl`：上游 API base URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 -- `models.providers.*.request`：模型 provider HTTP 请求的传输覆盖配置。 - - `request.headers`：额外 headers（与 provider 默认值合并）。值支持 SecretRef。 - - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都支持可选的 `tls` 子对象。 - - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段，则允许通过 provider HTTP 抓取防护访问 HTTPS `baseUrl`（供受信任的自托管 OpenAI-compatible 端点由运维人员选择启用）。WebSocket 使用同一个 `request` 处理 headers/TLS，但不使用该抓取 SSRF 防护。默认值 `false`。 -- `models.providers.*.models`：显式 provider 模型目录条目。 -- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生值（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串的 OpenAI-compatible 聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 +- `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.tls`：直连的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（全部支持 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段时，允许通过提供商 HTTP 抓取保护访问 HTTPS（这是针对受信任的自托管 OpenAI-compatible 端点的 operator 显式启用项）。WebSocket 会对 headers/TLS 使用相同的 `request`，但不使用该抓取 SSRF 防护。默认值为 `false`。 +- `models.providers.*.models`：显式的提供商模型目录条目。 +- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。 +- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时，使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空的非原生值（主机不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：适用于仅支持字符串内容的 OpenAI-compatible 聊天端点的可选兼容性提示。为 `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.refreshInterval`：发现刷新轮询间隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的默认回退上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的默认回退最大输出 token 数。 +- `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 示例 +### 提供商示例 @@ -2656,7 +2634,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`。 +Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 @@ -2693,8 +2671,8 @@ 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`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 对于通用端点，请定义带有 base URL 覆盖的自定义 provider。 +- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，请定义一个带 base URL 覆盖的自定义提供商。 @@ -2733,11 +2711,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` 传输上声明流式使用兼容性，而 OpenClaw 会根据端点能力 -而不只是内置 provider id 来判断这一点。 +`openai-completions` 传输上声明流式使用兼容性，OpenClaw 会根据端点能力 +而不只是根据内置提供商 ID 本身来决定相关行为。 @@ -2755,7 +2733,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -Anthropic-compatible，内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic-compatible，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 @@ -2838,14 +2816,16 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic-compatible 流式路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 +在 Anthropic-compatible 流式传输路径上，OpenClaw 默认会禁用 MiniMax thinking， +除非你显式自行设置 `thinking`。`/fast on` 或 +`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2866,7 +2846,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串 + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2876,13 +2856,13 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管/工作区 Skills 不受影响）。 -- `load.extraDirs`：额外的共享 Skill 根目录（优先级最低）。 -- `install.preferBrew`：当为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后再回退到其他安装器类型。 -- `install.nodeManager`：用于 `metadata.openclaw.install` - 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使 Skill 已内置/已安装，也会禁用该 Skill。 -- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 +- `allowBundled`：仅针对内置 Skills 的可选允许列表（不影响托管/工作区 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 对象）。 --- @@ -2911,46 +2891,46 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- 设备发现支持原生 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` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks，以及受支持的 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 抓取 provider 设置。 - - `apiKey`：Firecrawl API key（支持 SecretRef）。回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..env`：插件作用域环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，core 会阻止 `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.firecrawl.config.webFetch`：Firecrawl web fetch 提供商设置。 + - `apiKey`：Firecrawl API key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 - `maxAgeMs`：最大缓存时长（毫秒）（默认：`172800000` / 2 天）。 - `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - - `enabled`：启用 X Search provider。 + - `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 配置参考](/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`。 + - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -参见 [插件](/zh-CN/tools/plugin)。 +参见 [Plugins](/zh-CN/tools/plugin)。 --- -## Browser +## 浏览器 ```json5 { @@ -2959,8 +2939,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择启用 - // allowPrivateNetwork: true, // 旧版别名 + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2987,21 +2967,23 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此 browser 导航默认保持严格模式。 -- 仅当你明确信任私有网络 browser 导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间也会受到相同的私有网络拦截限制。 -- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此默认会对浏览器导航保持严格限制。 +- 只有当你明确愿意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。 +- `ssrfPolicy.allowPrivateNetwork` 仍受支持，作为旧版别名。 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 - 远程配置文件为仅附加模式（禁用 start/stop/reset）。 -- `profiles.*.cdpUrl` 支持 `http://`、`https://`、`ws://` 和 `wss://`。 - 当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；当 provider 直接给出 DevTools WebSocket URL 时，使用 WS(S)。 -- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，并且可以附加到所选主机上，或通过已连接的 browser 节点附加。 -- `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的 Chromium-based browser 配置文件，例如 Brave 或 Edge。 -- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用 snapshot/ref 驱动的操作而不是 CSS 选择器定向、单文件上传 hooks、不支持对话框超时覆盖、不支持 `wait --load networkidle`，且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下显式设置 `cdpUrl`。 -- 自动检测顺序：默认 browser（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- 控制服务：仅 loopback（端口从 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口尺寸或调试标志）。 +- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 + 当你希望 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 路由限制：基于快照/引用驱动的操作，而不是 CSS 选择器定位；单文件上传 hooks；不支持对话框超时覆盖；不支持 `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`、窗口大小设置或调试标志）。 --- @@ -3013,14 +2995,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji、短文本、图片 URL 或 data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` - `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 +- `assistant`：Control UI identity 覆盖。会回退到活动智能体 identity。 --- @@ -3035,8 +3017,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3054,9 +3036,9 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL - // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需 - // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3067,12 +3049,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // 可选。默认 false。 + // Optional. Default false. allowRealIpFallback: false, tools: { - // 额外的 /tools/invoke HTTP 拒绝项 + // Additional /tools/invoke HTTP denies deny: ["browser"], - // 从默认 HTTP 拒绝列表中移除工具 + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -3092,42 +3074,42 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `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` 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，启动以及服务安装/修复流程都会失败。 +- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 +- **认证**：默认必须启用。非 loopback bind 需要 Gateway 网关认证。实际中，这意味着使用共享 token/password，或使用设置了 `gateway.auth.mode: "trusted-proxy"` 的 identity-aware 反向代理。新手引导向导默认会生成 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 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `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`。 -- 来自 browser 源的 WS 认证尝试始终会被限流，且不会豁免 loopback（作为针对基于 browser 的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自 browser 源的锁定会按规范化后的 `Origin` - 值分别隔离，因此某个 localhost origin 的重复失败不会自动 - 锁定另一个 origin。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给 identity-aware 反向代理，并信任来自 `gateway.trustedProxies` 的 identity headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求代理源是**非 loopback**；同主机的 loopback 反向代理不满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve identity headers 可用于满足 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 连接的显式 browser-origin 允许列表。当 browser 客户端来自非 loopback origin 时必须设置。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。 +- `controlUi.allowedOrigins`：Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时必须设置。 +- `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`：客户端侧的紧急放行开关，允许通过明文 `ws://` 连接受信任的私有网络 IP；默认仍然只允许 local loopback 使用明文连接。 -- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 -- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的破窗式覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。 +- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关之后，供 Gateway 网关使用的外部 APNs relay 基础 HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 匹配。 - `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会被委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个注册范围的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用该已存储的注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖项。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生开关，允许使用 loopback HTTP relay URL。生产环境的 relay URL 应保持为 HTTPS。 -- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的健康监控最大重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：每个渠道的健康监控重启退出设置，同时保留全局监控开启。 -- `channels..accounts..healthMonitor.enabled`：多账号渠道的每个账号覆盖设置。设置后，其优先级高于渠道级覆盖。 -- 本地 Gateway 网关调用路径仅在 `gateway.auth.*` 未设置时，才可使用 `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` 额外阻止的工具名称（扩展默认拒绝列表）。 -- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。 +- 基于 relay 的注册会委托给特定 Gateway 网关 identity。配对的 iOS 应用会获取 `gateway.identity.get`，将该 identity 包含在 relay 注册中，并将注册作用域的发送授权转发给 Gateway 网关。其他 Gateway 网关无法复用该已存储的注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发使用的逃生开关，允许对 loopback HTTP relay URL 使用 HTTP。生产 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。仅列出你控制的代理。对于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理），loopback 条目仍然有效，但它们**不会**使 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 列表中移除工具名。 @@ -3139,14 +3121,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 + 空 allowlist 会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 可禁用 URL 抓取。 - 可选的响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origins 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + - `gateway.http.securityHeaders.strictTransportSecurity`（仅为你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -通过唯一端口和状态目录，在一台主机上运行多个 Gateway 网关： +在同一主机上使用不同端口和状态目录运行多个 Gateway 网关： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3174,10 +3156,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发环境。 +- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 +- `autoGenerate`：在未配置显式文件时自动生成本地自签名 cert/key 对；仅供本地/开发使用。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请限制访问权限。 +- `keyPath`：TLS 私钥文件的文件系统路径；请限制权限。 - `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -3194,12 +3176,12 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制配置编辑在运行时的应用方式。 +- `mode`：控制在运行时如何应用配置编辑。 - `"off"`：忽略实时编辑；变更需要显式重启。 - - `"restart"`：配置变更时始终重启 Gateway 网关进程。 - - `"hot"`：在不重启的情况下于进程内应用变更。 - - `"hybrid"`（默认）：优先尝试热重载；如有需要则回退为重启。 -- `debounceMs`：应用配置变更前的去抖窗口（毫秒）（非负整数）。 + - `"restart"`：在配置变更时始终重启 Gateway 网关进程。 + - `"hot"`：在进程内应用变更而不重启。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 +- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。 - `deferralTimeoutMs`：在强制重启前等待正在进行中的操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- @@ -3238,46 +3220,46 @@ openclaw gateway --port 19001 ``` 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 -拒绝使用查询字符串中的 hook token。 +查询字符串中的 hook token 会被拒绝。 验证与安全说明： -- `hooks.enabled=true` 要求 `hooks.token` 为非空。 +- `hooks.enabled=true` 需要非空的 `hooks.token`。 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或预设使用了模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 并将 `hooks.allowRequestSessionKey=true`。静态映射键不需要此选择启用。 +- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果某个 mapping 或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要该显式启用项。 **端点：** - `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`。 + - 模板渲染后的 mapping `sessionKey` 值会被视为外部提供，因此也需要 `hooks.allowRequestSessionKey=true`。 -- `match.path`：匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source`：为通用路径匹配负载中的某个字段。 -- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。 -- `transform` 可以指向返回 hook 动作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。 -- `agentId`：路由到指定智能体；未知 id 会回退到默认值。 -- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。 -- `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任一映射或预设使用模板化 `sessionKey` 时，它会成为必需项。 -- `deliver: true`：将最终回复发送到某个渠道；`channel` 默认值为 `last`。 -- `model`：覆盖本次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径的某个负载字段。 +- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取数据。 +- `transform` 可以指向一个返回 hook 操作的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径遍历都会被拒绝）。 +- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 +- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 +- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的 mapping 会话键设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + mapping）的可选前缀允许列表，例如 `["hook:"]`。当任意 mapping 或 preset 使用模板化 `sessionKey` 时，它就变为必填项。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 +- `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 { @@ -3305,14 +3287,14 @@ openclaw gateway --port 19001 --- -## Canvas host +## Canvas 主机 ```json5 { canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` @@ -3321,14 +3303,14 @@ openclaw gateway --port 19001 - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback 绑定：canvas 路由和其他 Gateway 网关 HTTP 接口一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 -- Node WebView 通常不会发送认证 headers；在节点完成配对并连接后，Gateway 网关会广播节点作用域的能力 URL，用于访问 canvas/A2UI。 -- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 -- 会向所提供的 HTML 中注入 live-reload 客户端。 +- 非 loopback bind：canvas 路由需要 Gateway 网关认证（token/password/trusted-proxy），与其他 Gateway 网关 HTTP 面相同。 +- Node WebViews 通常不会发送认证 headers；在某个节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布节点作用域的 capability URL。 +- Capability URL 绑定到当前活跃的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 将 live reload 客户端注入到所提供的 HTML 中。 - 为空时会自动创建起始 `index.html`。 -- 同时也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 也会在 `/__openclaw__/a2ui/` 下提供 A2UI。 - 变更需要重启 Gateway 网关。 -- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 +- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 --- @@ -3346,11 +3328,11 @@ openclaw gateway --port 19001 } ``` -- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。 +- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。 - `full`：包含 `cliPath` + `sshPort`。 -- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 +- 主机名默认为 `openclaw`。使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域网（DNS-SD） +### 广域（DNS-SD） ```json5 { @@ -3360,7 +3342,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要实现跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 分割 DNS。 +在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请将其与 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 配合使用。 设置：`openclaw dns setup --apply`。 @@ -3385,14 +3367,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少该键时，才会应用内联环境变量。 +- 仅当进程环境中缺少某个键时，才会应用内联环境变量。 - `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置中导入缺失的预期键名。 -- 完整优先级请参见 [环境](/zh-CN/help/environment)。 +- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 +- 完整优先级参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： +在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3403,7 +3385,7 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空变量会在加载配置时抛出错误。 +- 缺失/为空的变量会在配置加载时抛出错误。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 - 可与 `$include` 一起使用。 @@ -3411,11 +3393,11 @@ openclaw gateway --port 19001 ## Secrets -SecretRef 为增量功能：明文值仍然可用。 +SecretRef 是增量支持的：明文值仍然可用。 ### `SecretRef` -使用以下对象结构之一： +使用以下对象形状： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3427,21 +3409,21 @@ SecretRef 为增量功能：明文值仍然可用。 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` - `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 凭证范围](/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 provider 配置 +### Secret 提供商配置 ```json5 { secrets: { providers: { - default: { source: "env" }, // 可选的显式 env provider + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3465,17 +3447,17 @@ SecretRef 为增量功能：明文值仍然可用。 说明： -- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- `exec` provider 要求 `command` 为绝对路径，并通过 stdin/stdout 使用协议负载。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍验证解析后的目标路径。 -- 如果配置了 `trustedDirs`，则受信任目录检查会作用于解析后的目标路径。 -- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。 -- Secret 引用会在激活时解析为内存中的快照，之后请求路径只读取该快照。 -- 激活期间会应用活动范围过滤：启用范围内未解析的引用会导致启动/重载失败，而非活动范围会被跳过并附带诊断信息。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- `exec` 提供商要求 `command` 是绝对路径，并通过 stdin/stdout 使用协议负载。 +- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证其解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 +- 默认情况下，`exec` 子进程环境最小化；请使用 `passEnv` 显式传入所需变量。 +- Secret 引用会在激活时解析到内存快照中，之后请求路径只读取该快照。 +- 激活期间会应用活动面过滤：已启用面上的未解析引用会导致启动/重载失败，而未激活的面会被跳过并附带诊断信息。 --- -## Auth 存储 +## 凭证存储 ```json5 { @@ -3493,11 +3475,11 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- 每个智能体的 profile 存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持值级引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式的 profile（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会被清理。 -- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.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)。 @@ -3521,20 +3503,15 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个 profile 因真实 - 账单/余额不足错误而失败时的基础退避时长（小时）（默认：`5`）。即使是 `401`/`403` 响应，显式账单文本 - 也仍可能归入这里，但 provider 特定的文本 - 匹配器仍只作用于拥有它们的 provider（例如 OpenRouter 的 - `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 - organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的每个 provider 账单退避时长覆盖值（小时）。 +- `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`：对于过载错误，在切换到模型回退之前，同一 provider 的 auth-profile 允许的最大轮换次数（默认：`1`）。诸如 `ModelNotReadyException` 之类的 provider 忙碌形态会归入这里。 -- `overloadedBackoffMs`：在重试过载的 provider/profile 轮换前的固定延迟（毫秒）（默认：`0`）。 -- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退之前，同一 provider 的 auth-profile 允许的最大轮换次数（默认：`1`）。该限流桶包括 provider 形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 +- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。 +- `overloadedProfileRotations`：针对 overloaded 错误，在切换到模型回退前，同一提供商的 auth-profile 最多轮换次数（默认：`1`）。例如 `ModelNotReadyException` 这样的 provider-busy 形态就落在此类。 +- `overloadedBackoffMs`：在重试 overloaded 提供商/配置文件轮换前的固定延迟（毫秒）（默认：`0`）。 +- `rateLimitedProfileRotations`：针对 rate-limit 错误，在切换到模型回退前，同一提供商的 auth-profile 最多轮换次数（默认：`1`）。该 rate-limit 类别包括提供商特征文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -3554,8 +3531,8 @@ SecretRef 为增量功能：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用固定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 +- 设置 `logging.file` 可使用稳定路径。 +- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 - `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3593,20 +3570,20 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- `enabled`：仪表输出总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。 -- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的时长阈值（毫秒）。 -- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 -- `otel.endpoint`：用于 OTel 导出的 collector URL。 +- `enabled`：instrumentation 输出的主开关（默认：`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 或 log 导出。 -- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷出 telemetry 的间隔（毫秒）。 -- `cacheTrace.enabled`：记录内嵌运行的缓存跟踪快照（默认：`false`）。 -- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。 +- `otel.serviceName`：资源属性中的服务名。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 +- `otel.sampleRate`：trace 采样率 `0`–`1`。 +- `otel.flushIntervalMs`：周期性遥测刷新间隔（毫秒）。 +- `cacheTrace.enabled`：记录嵌入式运行的缓存追踪快照（默认：`false`）。 +- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（默认全部为 `true`）。 --- @@ -3628,12 +3605,12 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- `channel`：npm/git 安装的发布通道——`"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。 +- `channel`：npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：当 Gateway 网关启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：稳定通道自动应用前的最短延迟（小时）（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：稳定通道额外的发布扩散窗口（小时）（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 通道检查运行的频率（小时）（默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小时延（小时）（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：稳定渠道额外发布扩散窗口（小时）（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认：`1`；最大：`24`）。 --- @@ -3668,20 +3645,20 @@ SecretRef 为增量功能：明文值仍然可用。 - `enabled`：全局 ACP 功能开关（默认：`false`）。 - `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP runtime backend id（必须与已注册的 ACP runtime 插件匹配）。 -- `defaultAgent`：当派生未指定显式目标时，ACP 默认的目标智能体 id。 -- `allowedAgents`：允许用于 ACP runtime 会话的智能体 id 列表；空列表表示不做额外限制。 -- `maxConcurrentSessions`：同时活动的 ACP 会话最大数量。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷出窗口（毫秒）。 -- `stream.maxChunkChars`：在拆分流式块投影前允许的最大块大小。 -- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 表示增量流式输出；`"final_only"` 表示缓冲到轮次终结事件后再输出。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的助手输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。 -- `stream.tagVisibility`：标签名称到布尔可见性覆盖的映射记录，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在符合清理条件前的空闲 TTL（分钟）。 -- `runtime.installCommand`：引导 ACP runtime 环境时运行的可选安装命令。 +- `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 会话 worker 在可被清理前的空闲 TTL（分钟）。 +- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -3697,10 +3674,10 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换显示有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 +- `cli.banner.taglineMode` 控制 banner 标语风格： + - `"random"`（默认）：轮换的有趣/季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍会显示 banner 标题/版本）。 - 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3723,9 +3700,9 @@ SecretRef 为增量功能：明文值仍然可用。 --- -## 身份 +## identity -请参见 [智能体默认值](#agent-defaults) 下的 `agents.list` 身份字段。 +参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的 identity 字段。 --- @@ -3760,22 +3737,22 @@ SecretRef 为增量功能：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用：供已存储的 notify:true 任务使用的回退值 - webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token - sessionRetention: "24h", // 时长字符串或 false + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth + sessionRetention: "24h", // duration string or false runLog: { - maxBytes: "2mb", // 默认 2_000_000 字节 - keepLines: 2000, // 默认 2000 + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 }, }, } ``` -- `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；如果省略，则不会发送认证 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；若省略，则不会发送认证 header。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍然设置了 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3791,11 +3768,11 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `maxAttempts`：一次性作业在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。 - `backoffMs`：每次重试尝试的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会对所有瞬时类型进行重试。 +- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时类型。 -仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。 +仅适用于一次性 cron 作业。循环作业使用单独的失败处理机制。 ### `cron.failureAlert` @@ -3813,11 +3790,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` @@ -3834,16 +3811,16 @@ SecretRef 为增量功能：明文值仍然可用。 } ``` -- 所有任务共用的 cron 失败通知默认目标。 +- 所有作业的默认 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 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。 +参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 --- @@ -3853,32 +3830,32 @@ SecretRef 为增量功能：明文值仍然可用。 | 变量 | 描述 | | ------------------ | ------------------------------------------------- | -| `{{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}}` | provider 提示（whatsapp、telegram、discord 等） | +| `{{Body}}` | 完整传入消息正文 | +| `{{RawBody}}` | 原始正文（无历史/发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 ID | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 创建新会话时为 `"true"` | +| `{{MediaUrl}}` | 传入媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | CLI 条目解析后的媒体 prompt | +| `{{MaxChars}}` | CLI 条目解析后的最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- ## 配置包含（`$include`） -将配置拆分为多个文件： +将配置拆分到多个文件中： ```json5 // ~/.openclaw/openclaw.json @@ -3893,15 +3870,15 @@ SecretRef 为增量功能：明文值仍然可用。 **合并行为：** -- 单文件：替换其所在的包含对象。 +- 单文件：替换所在的包含对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 include 之后合并（覆盖被包含的值）。 -- 嵌套 include：最多支持 10 层。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许使用。 -- 由 OpenClaw 发起、且只更改由单文件 include 支撑的某个顶层 section 的写入操作，会直接写回该被包含文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 更新到 `plugins.json5` 中，并保持 `openclaw.json` 不变。 -- 对于根级 include、include 数组，以及带有同级覆盖的 include，OpenClaw 发起的写入均为只读；这些写入会以关闭方式失败，而不是将配置展平。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰的报错信息。 +- 同级键：在 includes 之后合并（覆盖被包含的值）。 +- 嵌套 includes：最多 10 层。 +- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式解析后仍位于该边界内时才允许。 +- 当 OpenClaw 自有写入只修改由单文件 include 支撑的一个顶层段时，会直接写回该被包含文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 更新到 `plugins.json5` 中，并保持 `openclaw.json` 不变。 +- 根级 includes、include 数组，以及带同级覆盖的 includes 对于 OpenClaw 自有写入是只读的；这类写入会以关闭方式失败，而不是将配置拍平。 +- 错误：对于缺失文件、解析错误和循环 includes，会给出清晰消息。 --- -_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_ diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index 98425fd18..0557a7537 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -1,27 +1,27 @@ --- read_when: - - 你想使用内置的 Codex app-server 测试工具 + - 你想使用内置的 Codex 应用服务器测试工具 - 你需要 Codex 模型引用和配置示例 - - 你想为仅使用 Codex 的部署禁用 Pi 回退 -summary: 通过内置的 Codex app-server 测试工具运行 OpenClaw 嵌入式智能体轮次 + - 你想为仅使用 Codex 的部署禁用 Pi 回退机制 +summary: 通过内置的 Codex 应用服务器测试工具运行 OpenClaw 嵌入式智能体轮次 title: Codex 测试工具 x-i18n: - generated_at: "2026-04-23T15:20:02Z" + generated_at: "2026-04-23T16:04:44Z" model: gpt-5.4 provider: openai - source_hash: 4537cdc043768f19cd097b4542dfb3447bf3342c7c300832e160b795263c2a52 + source_hash: 07e7fb033cd4025e53d65a719bab7bd704335933bf19bfb10648cede42cdee46 source_path: plugins/codex-harness.md workflow: 15 --- # Codex 测试工具 -内置的 `codex` 插件让 OpenClaw 能通过 Codex app-server 运行嵌入式智能体轮次，而不是使用内置的 PI 测试工具。 +内置的 `codex` 插件让 OpenClaw 通过 Codex 应用服务器运行嵌入式智能体轮次，而不是使用内置的 Pi 测试工具。 -当你希望由 Codex 接管底层智能体会话时，可以使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。 -OpenClaw 仍负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 +当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩以及应用服务器执行。 +OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 -原生 Codex 轮次也会遵循共享插件钩子，因此 prompt shim、感知压缩的自动化、工具中间件和生命周期观察器都能与 PI 测试工具保持一致： +原生 Codex 轮次也会遵循共享的插件钩子，因此提示词 shim、感知压缩的自动化、工具中间件和生命周期观察器都会与 Pi 测试工具保持一致： - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -30,34 +30,40 @@ OpenClaw 仍负责聊天渠道、会话文件、模型选择、工具、审批 - `before_message_write` - `agent_end` -内置插件还可以注册一个 Codex app-server 扩展工厂，以添加异步 `tool_result` 中间件。 +内置插件还可以注册一个 Codex 应用服务器扩展工厂，以添加异步 `tool_result` 中间件。 该测试工具默认关闭。只有在启用 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选中它。 -如果你从未配置 `codex/*`，现有的 PI、OpenAI、Anthropic、Gemini、本地和自定义提供商运行都会保持当前行为。 +如果你从未配置 `codex/*`，现有的 Pi、OpenAI、Anthropic、Gemini、本地和自定义提供商运行都会保持当前行为。 ## 选择正确的模型前缀 -OpenClaw 为 OpenAI 访问和 Codex 风格访问提供了不同路径： +OpenClaw 为 OpenAI 访问方式和 Codex 风格的访问方式提供了不同路径： -| 模型引用 | 运行时路径 | 适用场景 | -| -------------------- | ------------------------------------------ | ----------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线的 OpenAI 提供商路径 | 你希望通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | -| `openai-codex/gpt-5.4` | 通过 PI 的 OpenAI Codex OAuth 提供商路径 | 你希望使用 ChatGPT/Codex OAuth，但不使用 Codex app-server 测试工具。 | -| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex 测试工具 | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 | +| 模型引用 | 运行时路径 | 使用场景 | +| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.4` | 通过 OpenClaw/Pi 流程的 OpenAI 提供商 | 你想通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | +| `openai-codex/gpt-5.4` | 通过 Pi 的 OpenAI Codex OAuth 提供商 | 你想使用 ChatGPT/Codex OAuth，但不使用 Codex 应用服务器测试工具。 | +| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex 测试工具 | 你希望嵌入式智能体轮次使用原生 Codex 应用服务器执行。 | -Codex 测试工具只接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保留其常规路径。 +Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保持其正常路径。 + +测试工具选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选测试工具的 id，并在同一会话 id 的后续轮次中继续使用它。若你希望未来的会话使用另一种测试工具，请更改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话于 Pi 和 Codex 之间切换前，请使用 `/new` 或 `/reset` 启动一个新会话。 +这样可以避免同一份转录被重放到两个不兼容的原生会话系统中。 + +在测试工具固定机制引入之前创建的旧会话，一旦已有转录历史，就会被视为固定到 Pi。更改配置后，使用 `/new` 或 `/reset` 可让该对话改为使用 Codex。 + +`/status` 会在 `Fast` 旁边显示生效的非 Pi 测试工具，例如 `Fast · codex`。默认的 Pi 测试工具不会显示。 ## 要求 -- OpenClaw，并且可用内置 `codex` 插件。 -- Codex app-server `0.118.0` 或更高版本。 -- app-server 进程可用的 Codex 身份验证。 +- OpenClaw，且可使用内置的 `codex` 插件。 +- Codex 应用服务器 `0.118.0` 或更高版本。 +- 应用服务器进程可用的 Codex 身份验证。 -该插件会阻止较旧版本或未带版本信息的 app-server 握手。 -这样可确保 OpenClaw 始终使用它已针对其进行测试的协议表面。 +该插件会阻止过旧或未标明版本的应用服务器握手。 +这样可以让 OpenClaw 保持在已验证过的协议范围内运行。 -对于实时测试和 Docker 冒烟测试，身份验证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。 -请使用与你本地 Codex app-server 相同的身份验证材料。 +对于实时测试和 Docker 冒烟测试，身份验证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex 应用服务器相同的认证材料。 ## 最小配置 @@ -84,7 +90,7 @@ Codex 测试工具只接管 `codex/*` 模型引用。现有的 `openai/*`、`ope } ``` -如果你的配置使用 `plugins.allow`，也需要把 `codex` 包含进去： +如果你的配置使用 `plugins.allow`，也要在其中加入 `codex`： ```json5 { @@ -99,12 +105,11 @@ Codex 测试工具只接管 `codex/*` 模型引用。现有的 `openai/*`、`ope } ``` -将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 也会自动启用内置 `codex` 插件。 -显式插件条目在共享配置中仍然很有用，因为它能让部署意图更清晰。 +将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 时，也会自动启用内置的 `codex` 插件。在共享配置中，显式写出插件条目仍然很有用，因为这能清楚表明部署意图。 -## 添加 Codex 而不替换其他模型 +## 添加 Codex，但不替换其他模型 -当你希望 `codex/*` 模型使用 Codex，而其余所有模型使用 PI 时，请保留 `runtime: "auto"`： +如果你希望 `codex/*` 模型使用 Codex，而其他模型仍使用 Pi，请保留 `runtime: "auto"`： ```json5 { @@ -136,16 +141,16 @@ Codex 测试工具只接管 `codex/*` 模型引用。现有的 `openai/*`、`ope } ``` -采用这种形式后： +采用这种配置时： -- `/model codex` 或 `/model codex/gpt-5.4` 会使用 Codex app-server 测试工具。 +- `/model codex` 或 `/model codex/gpt-5.4` 会使用 Codex 应用服务器测试工具。 - `/model gpt` 或 `/model openai/gpt-5.4` 会使用 OpenAI 提供商路径。 - `/model opus` 会使用 Anthropic 提供商路径。 -- 如果选择的是非 Codex 模型，PI 仍然是兼容性测试工具。 +- 如果选择的是非 Codex 模型，Pi 仍然会作为兼容性测试工具。 ## 仅使用 Codex 的部署 -当你需要证明每个嵌入式智能体轮次都使用 Codex 测试工具时，请禁用 PI 回退： +当你需要证明每一次嵌入式智能体轮次都使用 Codex 测试工具时，请禁用 Pi 回退： ```json5 { @@ -169,11 +174,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 都会提前失败。 +禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、应用服务器版本过旧，或应用服务器无法启动，OpenClaw 都会尽早失败。 ## 按智能体使用 Codex -你可以让某个智能体仅使用 Codex，同时让默认智能体保持正常的自动选择： +你可以只让某一个智能体专用 Codex，而默认智能体仍保持正常的自动选择： ```json5 { @@ -204,11 +209,12 @@ openclaw gateway run } ``` -使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的 OpenClaw 会话，而 Codex 测试工具会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定。 +使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex 测试工具会按需为其创建或恢复配套的应用服务器线程。`/reset` 会清除该线程对应的 OpenClaw 会话绑定，并让下一轮再次根据当前配置解析测试工具。 ## 模型发现 -默认情况下，`codex` 插件会向 app-server 查询可用模型。如果发现失败或超时，它会使用内置的回退目录： +默认情况下，Codex 插件会向应用服务器请求可用模型。 +如果发现失败或超时，它会使用内置的回退目录： - `codex/gpt-5.4` - `codex/gpt-5.4-mini` @@ -234,7 +240,7 @@ openclaw gateway run } ``` -如果你希望启动时避免探测 Codex，而是固定使用回退目录，可以禁用发现： +如果你希望启动时避免探测 Codex，并固定使用回退目录，请禁用发现： ```json5 { @@ -253,18 +259,19 @@ openclaw gateway run } ``` -## App-server 连接和策略 +## 应用服务器连接与策略 -默认情况下，插件会使用以下命令在本地启动 Codex： +默认情况下，插件会用以下命令在本地启动 Codex： ```bash codex app-server --listen stdio:// ``` 默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试工具会话： -`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 `sandbox: "danger-full-access"`。这是一种适用于自主心跳的受信任本地操作姿态：Codex 可以使用 shell 和网络工具，而不会停在无人可答复的原生审批提示上。 +`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 +`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会因为无人响应的原生审批提示而中断。 -如果你希望启用由 Codex guardian 审核的审批，请设置 `appServer.mode: +如果要启用由 Codex Guardian 审核的审批，请设置 `appServer.mode: "guardian"`： ```json5 @@ -285,11 +292,11 @@ codex app-server --listen stdio:// } ``` -Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加网络访问等权限时，Codex 会将该审批请求路由给一个 reviewer 子智能体，而不是向人类发出提示。该 reviewer 会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多保护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。 +Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审核子智能体，而不是向人工发出提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。 -`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。 +`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。 -对于已经在运行的 app-server，请使用 WebSocket 传输： +对于已经在运行的应用服务器，请使用 WebSocket 传输： ```json5 { @@ -313,22 +320,22 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 支持的 `appServer` 字段： -| 字段 | 默认值 | 含义 | +| 字段 | 默认值 | 含义 | | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | -| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | -| `url` | 未设置 | WebSocket app-server URL。 | -| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket 请求头。 | -| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程启动、恢复和轮次的原生 Codex 审批策略。 | -| `sandbox` | `"danger-full-access"` | 发送到线程启动和恢复的原生 Codex 沙箱模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审核提示。 | -| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | +| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | +| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | +| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | +| `url` | 未设置 | WebSocket 应用服务器 URL。 | +| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket 标头。 | +| `requestTimeoutMs` | `60000` | 应用服务器控制平面调用的超时时间。 | +| `mode` | `"yolo"` | 用于 YOLO 或 Guardian 审核执行的预设。 | +| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 | +| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 | +| `serviceTier` | 未设置 | 可选的 Codex 应用服务器服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | -较旧的环境变量在匹配配置字段未设置时，仍可作为本地测试的回退方式使用： +当对应配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -337,10 +344,11 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用 -`plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性本地测试中使用 -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复的部署，更推荐使用配置，因为这样可以将插件行为与 Codex 测试工具的其余设置放在同一个经过审查的文件中。 +`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试时使用 +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，推荐使用配置， +因为这样可以将插件行为与 Codex 测试工具设置的其余部分放在同一个经过审查的文件中。 -## 常见配方 +## 常见用法 使用默认 stdio 传输的本地 Codex： @@ -356,7 +364,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -仅使用 Codex 的测试工具验证，并禁用 PI 回退： +仅使用 Codex 的测试工具验证，禁用 Pi 回退： ```json5 { @@ -395,7 +403,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -带显式请求头的远程 app-server： +带显式标头的远程应用服务器： ```json5 { @@ -418,54 +426,69 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有 Codex 线程时，下一个轮次会再次将当前选定的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送到 app-server。 -从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 时，会保留线程绑定，但会要求 Codex 使用新选定的模型继续。 +模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时， +下一轮会再次将当前选定的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送给 +应用服务器。从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 时，会保留线程绑定，但会要求 +Codex 使用新选定的模型继续执行。 ## Codex 命令 -内置插件将 `/codex` 注册为一个已授权的斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道上工作。 +内置插件将 `/codex` 注册为授权斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。 常见形式： -- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和技能。 -- `/codex models` 列出实时 Codex app-server 模型。 +- `/codex status` 显示实时应用服务器连接状态、模型、账户、速率限制、MCP 服务器和 skills。 +- `/codex models` 列出实时 Codex 应用服务器模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 - `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 -- `/codex compact` 请求 Codex app-server 压缩已附加的线程。 +- `/codex compact` 请求 Codex 应用服务器压缩已附加的线程。 - `/codex review` 为已附加的线程启动 Codex 原生审查。 - `/codex account` 显示账户和速率限制状态。 -- `/codex mcp` 列出 Codex app-server MCP 服务器状态。 -- `/codex skills` 列出 Codex app-server Skills。 +- `/codex mcp` 列出 Codex 应用服务器 MCP 服务器状态。 +- `/codex skills` 列出 Codex 应用服务器 Skills。 -`/codex resume` 会写入与测试工具用于常规轮次相同的 sidecar 绑定文件。下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*` 模型传入 app-server，并保持启用扩展历史记录。 +`/codex resume` 会写入与测试工具正常轮次所使用的同一个配套绑定文件。 +在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*` +模型传入应用服务器，并保持启用扩展历史记录。 -该命令表面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，单独的控制方法会报告为 `unsupported by this Codex app-server`。 +该命令功能要求 Codex 应用服务器版本为 `0.118.0` 或更高。如果未来版本或自定义的应用服务器 +未暴露某个 JSON-RPC 方法，各个控制方法会显示为 `unsupported by this Codex app-server`。 -## 工具、媒体和压缩 +## 工具、媒体与压缩 -Codex 测试工具只改变底层嵌入式智能体执行器。 +Codex 测试工具仅改变底层嵌入式智能体执行器。 -OpenClaw 仍然构建工具列表，并从测试工具接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出都会继续通过正常的 OpenClaw 传递路径处理。 +OpenClaw 仍然构建工具列表，并从测试工具接收动态工具结果。文本、图像、视频、音乐、TTS、 +审批和消息工具输出会继续通过正常的 OpenClaw 传递路径处理。 -当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件审批流路由；其他征询和自由格式输入请求仍会以默认拒绝方式处理。 +当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批请求会通过 OpenClaw 的插件审批流程路由；其他请求输入和自由格式输入请求仍会以失败关闭的方式处理。 -当选定模型使用 Codex 测试工具时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或测试工具切换。该镜像包括用户提示、最终助手文本，以及 app-server 发出时的轻量级 Codex 推理或计划记录。当前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。 +当所选模型使用 Codex 测试工具时，原生线程压缩会委托给 Codex 应用服务器。OpenClaw 会保留一份转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或测试工具切换。该镜像包括用户提示、最终助手文本，以及在应用服务器发出时包含轻量级的 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。 -媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用匹配的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 +媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用相应的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 故障排除 -**`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`，设置一个 `codex/*` 模型引用，或者检查 `plugins.allow` 是否排除了 `codex`。 +**`/model` 中未显示 Codex：** 启用 `plugins.entries.codex.enabled`， +设置一个 `codex/*` 模型引用，或检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用的是 PI 而不是 Codex：** 如果没有 Codex 测试工具接管该运行，OpenClaw 可能会使用 PI 作为兼容性后端。测试时可设置 `embeddedHarness.runtime: "codex"` 来强制选择 Codex，或设置 `embeddedHarness.fallback: "none"` 以便在没有匹配插件测试工具时直接失败。一旦选中了 Codex app-server，其失败会直接暴露出来，不需要额外的回退配置。 +**OpenClaw 使用的是 Pi 而不是 Codex：** 如果没有 Codex 测试工具接管该运行， +OpenClaw 可能会使用 Pi 作为兼容性后端。测试时设置 +`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置 +`embeddedHarness.fallback: "none"` 以在没有匹配的插件测试工具时直接失败。 +一旦选中了 Codex 应用服务器，它的失败会直接暴露出来，无需额外的回退配置。 -**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本 `0.118.0` 或更高。 +**应用服务器被拒绝：** 升级 Codex，使应用服务器握手报告版本 +`0.118.0` 或更高。 -**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`，或禁用发现。 +**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` +或禁用发现。 -**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，以及远程 app-server 是否使用相同版本的 Codex app-server 协议。 +**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`， +并确认远程应用服务器使用相同的 Codex 应用服务器协议版本。 -**某个非 Codex 模型使用了 PI：** 这是预期行为。Codex 测试工具只接管 `codex/*` 模型引用。 +**非 Codex 模型使用了 Pi：** 这是预期行为。Codex 测试工具只会接管 +`codex/*` 模型引用。 ## 相关内容 diff --git a/docs/zh-CN/plugins/sdk-agent-harness.md b/docs/zh-CN/plugins/sdk-agent-harness.md index f6a09f399..a61d42039 100644 --- a/docs/zh-CN/plugins/sdk-agent-harness.md +++ b/docs/zh-CN/plugins/sdk-agent-harness.md @@ -1,51 +1,51 @@ --- read_when: - - 你正在更改内嵌智能体运行时或 harness 注册表 - - 你正在从内置插件或受信任插件注册一个智能体 harness + - 你正在更改嵌入式智能体运行时或 Harness 注册表 + - 你正在从内置或受信任的插件注册一个智能体 Harness - 你需要了解 Codex 插件与模型提供商之间的关系 sidebarTitle: Agent Harness -summary: 用于替换底层内嵌智能体执行器的实验性插件 SDK 接口 surface +summary: 用于替换底层嵌入式智能体执行器的插件实验性 SDK 接口面 title: 智能体 Harness 插件 x-i18n: - generated_at: "2026-04-22T23:23:44Z" + generated_at: "2026-04-23T16:04:43Z" model: gpt-5.4 provider: openai - source_hash: efaecca18210af0e9e641bd888c1edb55e08e96299158ff021d6c2dd0218ec25 + source_hash: ec858acedaae8670c730022f8cc700499ac3b95d3d4144584e01051b224fee64 source_path: plugins/sdk-agent-harness.md workflow: 15 --- # 智能体 Harness 插件 -**智能体 harness** 是为一次已准备好的 OpenClaw 智能体轮次提供底层执行的执行器。它不是模型提供商，不是渠道，也不是工具注册表。 +**智能体 harness** 是一个已准备好的 OpenClaw 智能体单次轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 -仅对内置或受信任的原生插件使用此接口。该契约仍属实验性，因为其参数类型刻意映射当前的内嵌运行器。 +仅对内置或受信任的原生插件使用此接口面。该契约仍然是实验性的，因为参数类型有意映射当前的嵌入式运行器。 ## 何时使用 harness -当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层并不是合适抽象时，注册智能体 harness。 +当某个模型家族拥有自己的原生会话运行时，而常规 OpenClaw 提供商传输抽象并不适合时，注册一个智能体 harness。 -示例： +例如： -- 拥有线程和上下文压缩能力的原生 coding-agent 服务器 +- 拥有线程与压缩能力的原生 coding-agent 服务器 - 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程 -- 除了 OpenClaw 会话转录之外，还需要自身 resume id 的模型运行时 +- 除 OpenClaw 会话转录之外，还需要自身 resume id 的模型运行时 -不要仅为了添加一个新的 LLM API 而注册 harness。对于常规的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +不要仅仅为了添加一个新的 LLM API 而注册 harness。对于常规 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 -## 核心仍负责的内容 +## 核心仍然负责的内容 -在选择 harness 之前，OpenClaw 已经解析完成： +在选择 harness 之前，OpenClaw 已经解析了： - 提供商和模型 - 运行时凭证状态 -- 思考等级和上下文预算 +- 思考级别和上下文预算 - OpenClaw 转录 / 会话文件 - 工作区、沙箱和工具策略 - 渠道回复回调和流式传输回调 - 模型回退和实时模型切换策略 -这种划分是有意为之。Harness 负责运行一次已准备好的尝试；它不会选择提供商、替换渠道投递，也不会静默切换模型。 +这种划分是有意设计的。harness 运行的是一个已准备好的尝试；它不会选择提供商、替代渠道投递，或静默切换模型。 ## 注册 harness @@ -85,55 +85,58 @@ export default definePluginEntry({ ## 选择策略 -OpenClaw 会在提供商 / 模型解析完成后选择 harness： +OpenClaw 会在提供商 / 模型解析之后选择一个 harness： -1. `OPENCLAW_AGENT_RUNTIME=` 会强制使用具有该 id 的已注册 harness。 -2. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。 -3. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册的 harness 判断自己是否支持已解析的提供商 / 模型。 -4. 如果没有已注册 harness 匹配，OpenClaw 会使用 PI，除非禁用了 PI 回退。 +1. 现有会话中记录的 harness id 优先生效，因此配置 / 环境变量的变化不会将该转录热切换到另一个运行时。 +2. `OPENCLAW_AGENT_RUNTIME=` 会为尚未固定的会话强制使用具有该 id 的已注册 harness。 +3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。 +4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 harness 是否支持已解析的提供商 / 模型。 +5. 如果没有匹配的已注册 harness，除非禁用了 PI 回退，否则 OpenClaw 会使用 PI。 -插件 harness 失败会显示为运行失败。在 `auto` 模式下，仅当没有已注册的插件 harness 支持已解析的提供商 / 模型时，才会使用 PI 回退。一旦某个插件 harness 已声明接管某次运行，OpenClaw 就不会再通过 PI 重放同一轮次，因为这可能改变凭证 / 运行时语义，或导致副作用重复。 +插件 harness 失败会表现为运行失败。在 `auto` 模式下，仅当没有已注册的插件 harness 支持已解析的提供商 / 模型时，才会使用 PI 回退。一旦某个插件 harness 已接管一次运行，OpenClaw 就不会通过 PI 重放同一轮次，因为这可能改变凭证 / 运行时语义或造成副作用重复。 -内置 Codex 插件将 `codex` 注册为其 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应放在插件或运维配置中，而不是共享运行时选择器中。 +嵌入式运行后，所选 harness id 会与会话 id 一起持久化。在 harness 固定机制之前创建的旧会话，一旦拥有转录历史，就会被视为固定到 PI。要在 PI 与原生插件 harness 之间切换，请使用新的 / 重置后的会话。`/status` 会在 `Fast` 旁显示诸如 `codex` 之类的非默认 harness id；PI 作为默认兼容路径则会被隐藏。 + +内置 Codex 插件将 `codex` 注册为它的 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应属于插件或操作员配置，而不应放在共享运行时选择器中。 ## 提供商与 harness 配对 -大多数 harness 也应该注册一个提供商。提供商会让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 其余部分可见。随后，harness 在 `supports(...)` 中声明该提供商。 +大多数 harness 也应同时注册一个提供商。提供商让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后，harness 在 `supports(...)` 中声明对该提供商的支持。 -内置 Codex 插件遵循此模式： +内置 Codex 插件遵循这种模式： -- provider id: `codex` +- provider id：`codex` - 用户模型引用：`codex/gpt-5.4`、`codex/gpt-5.2`，或 Codex app server 返回的其他模型 -- harness id: `codex` -- auth：合成的提供商可用性，因为 Codex harness 拥有原生 Codex 登录 / 会话 +- harness id：`codex` +- 凭证：合成的提供商可用性，因为 Codex harness 拥有原生 Codex 登录 / 会话 - app-server 请求：OpenClaw 向 Codex 发送裸模型 id，并让 harness 与原生 app-server 协议通信 -Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规的 OpenClaw 提供商路径。当你想使用 Codex 管理的凭证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。 +Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规 OpenClaw 提供商路径。当你需要 Codex 管理的凭证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。 -有关运维设置、模型前缀示例和仅适用于 Codex 的配置，请参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 +有关操作员设置、模型前缀示例和仅限 Codex 的配置，请参阅 [Codex Harness](/zh-CN/plugins/codex-harness)。 -OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未带版本信息的服务器，以确保 OpenClaw 仅运行在它已测试过的协议接口之上。 +OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未带版本信息的服务器，以确保 OpenClaw 只运行在其已测试过的协议接口面之上。 ### Codex app-server 工具结果中间件 -当清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，内置插件还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 挂载 Codex app-server 专用的 `tool_result` 中间件。这是受信任插件的扩展点，适用于那些需要在原生 Codex harness 内部运行、并在工具输出回投到 OpenClaw 转录之前完成的异步工具结果转换。 +当清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，内置插件还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 附加 Codex app-server 专用的 `tool_result` 中间件。这是受信任插件的接口，用于那些需要在原生 Codex harness 内部运行、并在工具输出被投影回 OpenClaw 转录之前执行的异步工具结果转换。 ### 原生 Codex harness 模式 -内置的 `codex` harness 是用于内嵌 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件；如果你的配置使用限制性 allowlist，还需将 `codex` 加入 `plugins.allow`。它与 `openai-codex/*` 不同： +内置的 `codex` harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件；如果你的配置使用了限制性 allowlist，还要将 `codex` 加入 `plugins.allow`。它与 `openai-codex/*` 不同： - `openai-codex/*` 通过常规 OpenClaw 提供商路径使用 ChatGPT / Codex OAuth。 - `codex/*` 使用内置 Codex 提供商，并通过 Codex app-server 路由该轮次。 -在该模式运行时，Codex 负责原生线程 id、resume 行为、上下文压缩以及 app-server 执行。OpenClaw 仍负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管此次运行时，请使用 `embeddedHarness.runtime: "codex"` 并设置 `embeddedHarness.fallback: "none"`。该配置仅是一个选择保护：Codex app-server 失败本来就会直接失败，而不会再通过 PI 重试。 +当此模式运行时，Codex 负责原生线程 id、resume 行为、压缩和 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管运行时，请使用 `embeddedHarness.runtime: "codex"` 配合 `embeddedHarness.fallback: "none"`。该配置仅是一个选择保护：Codex app-server 失败本来就会直接失败，而不会通过 PI 重试。 ## 禁用 PI 回退 -默认情况下，OpenClaw 使用 `agents.defaults.embeddedHarness` 为 `{ runtime: "auto", fallback: "pi" }` 来运行内嵌智能体。在 `auto` 模式下，已注册的插件 harness 可以接管某个提供商 / 模型组合。如果没有匹配项，OpenClaw 会回退到 PI。 +默认情况下，OpenClaw 以 `agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }` 来运行嵌入式智能体。在 `auto` 模式下，已注册的插件 harness 可以接管某个提供商 / 模型组合。如果没有任何匹配，OpenClaw 会回退到 PI。 -当你需要在缺少插件 harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 harness 失败本就会硬失败。这不会阻止显式设置 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 +当你需要在缺少插件 harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 -对于仅使用 Codex 的内嵌运行： +对于仅限 Codex 的嵌入式运行： ```json { @@ -149,7 +152,7 @@ OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会 } ``` -如果你希望任意已注册的插件 harness 都可以接管匹配的模型，但又不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： +如果你希望任何已注册的插件 harness 都能接管匹配的模型，但又绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： ```json { @@ -164,7 +167,7 @@ OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会 } ``` -每个智能体的覆盖配置使用相同结构： +按智能体覆盖使用相同的结构： ```json { @@ -189,7 +192,7 @@ OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会 } ``` -`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的 runtime。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。 +`OPENCLAW_AGENT_RUNTIME` 仍然会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。 ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -197,39 +200,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -在禁用回退后，如果请求的 harness 未注册、不支持已解析的提供商 / 模型，或者在产生轮次副作用前就失败，会话将提早失败。这对于仅使用 Codex 的部署，以及必须证明 Codex app-server 路径确实被使用的实时测试，都是有意设计的行为。 +在禁用回退后，如果请求的 harness 未注册、不支持已解析的提供商 / 模型，或者在产生轮次副作用之前失败，则会话会尽早失败。这对仅限 Codex 的部署以及必须证明 Codex app-server 路径确实在使用中的实时测试而言，是有意设计的行为。 -此设置仅控制内嵌智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。 +此设置只控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。 ## 原生会话与转录镜像 -Harness 可以保留原生 session id、thread id 或守护进程侧的 resume token。请将这种绑定明确地与 OpenClaw 会话关联起来，并持续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。 +harness 可以保留原生会话 id、线程 id 或守护进程侧的 resume token。请将这种绑定明确关联到 OpenClaw 会话，并继续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。 -OpenClaw 转录仍然是以下能力的兼容层： +OpenClaw 转录仍然是以下场景的兼容层： - 渠道可见的会话历史 -- 转录搜索和索引 +- 转录搜索与索引 - 在后续轮次切换回内置 PI harness - 通用的 `/new`、`/reset` 和会话删除行为 -如果你的 harness 存储了 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 在所属 OpenClaw 会话被重置时清除它。 +如果你的 harness 存储了 sidecar 绑定，请实现 `reset(...)`，这样 OpenClaw 才能在所属 OpenClaw 会话被重置时清除它。 -## 工具和媒体结果 +## 工具与媒体结果 -核心会构造 OpenClaw 工具列表，并将其传入已准备好的尝试中。当 harness 执行动态工具调用时，请通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。 +核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试中。当 harness 执行动态工具调用时，请通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。 -这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出与 PI 支持的运行共享同一条投递路径。 +这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出，与由 PI 支持的运行走同一条投递路径。 ## 当前限制 -- 公共导入路径是通用的，但某些 attempt / result 类型别名仍因兼容性而保留 `Pi` 命名。 -- 第三方 harness 安装仍属实验性。在你确实需要原生会话运行时之前，优先使用提供商插件。 -- 支持跨轮次切换 harness。不要在某一轮次中途切换 harness，尤其是在原生工具、审批、助手文本或消息发送已经开始之后。 +- 公共导入路径是通用的，但某些 attempt / result 类型别名仍然保留 `Pi` 名称以保持兼容性。 +- 第三方 harness 安装仍处于实验阶段。在你确实需要原生会话运行时之前，优先使用提供商插件。 +- 支持跨轮次切换 harness。不要在一轮进行过程中、在原生工具、审批、助手文本或消息发送已经开始之后切换 harness。 ## 相关内容 - [SDK 概览](/zh-CN/plugins/sdk-overview) -- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) +- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) - [Codex Harness](/zh-CN/plugins/codex-harness) - [模型提供商](/zh-CN/concepts/model-providers) diff --git a/docs/zh-CN/start/showcase.md b/docs/zh-CN/start/showcase.md index 9f2bda9a8..7028e1b82 100644 --- a/docs/zh-CN/start/showcase.md +++ b/docs/zh-CN/start/showcase.md @@ -1,152 +1,81 @@ --- description: Real-world OpenClaw projects from the community read_when: - - 寻找真实的 OpenClaw 使用示例 - - 更新社区项目精选 + - 在寻找真实的 OpenClaw 使用示例 + - 更新社区项目亮点 summary: 由 OpenClaw 驱动的社区构建项目和集成 title: 展示区 x-i18n: - generated_at: "2026-04-23T06:43:41Z" + generated_at: "2026-04-23T16:04:42Z" model: gpt-5.4 provider: openai - source_hash: 5bf4bd2548709a01ad18331537f804b32c3213139c2234915aa17f7a2638f19f + source_hash: b95dc12399a1a263c268671ffccfc86b069ec908a5bf40adc00663153c281d7d source_path: start/showcase.md workflow: 15 --- # 展示区 -
-

构建于聊天、终端、浏览器和客厅之中

-

- OpenClaw 项目不是玩具演示。人们正在通过他们早已使用的渠道，交付 PR 审查循环、移动应用、家庭自动化、语音系统、开发工具和重度记忆工作流。 -

- -
-
- 聊天原生构建 - Telegram、WhatsApp、Discord、Beeper、网页聊天，以及终端优先工作流。 -
-
- 真实自动化 - 预订、购物、支持、报告和浏览器控制，无需等待 API。 -
-
- 本地 + 物理世界 - 打印机、扫地机器人、摄像头、健康数据、家庭系统和个人知识库。 -
-
-
+OpenClaw 项目不是玩具演示。人们正在通过自己已经在使用的渠道，交付 PR 审查闭环、移动应用、家庭自动化、语音系统、开发工具以及重度记忆工作流——基于 Telegram、WhatsApp、Discord 和终端的聊天原生构建；无需等待 API 的真实自动化，可用于预订、购物和支持；以及与打印机、扫地机器人、摄像头和家庭系统的现实世界集成。 -**想被推荐展示？** 请在 [Discord 的 #self-promotion](https://discord.gg/clawd) 中分享你的项目，或在 [X 上标记 @openclaw](https://x.com/openclaw)。 +**想被收录展示？** 请在 [Discord 的 #self-promotion 频道](https://discord.gg/clawd) 分享你的项目，或在 [X 上标记 @openclaw](https://x.com/openclaw)。 - - ## 视频 -

- 如果你想用最短路径从“这是什么？”走到“好，我懂了”，就从这里开始。 -

+如果你想用最短路径从“这是什么？”到“好，我懂了”，请从这里开始。 -
-
-
-