diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index f33e2fc67..0c0193a1f 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: 核心 OpenClaw 键名、默认值及各子系统专用参考链接的 Gateway 网关配置参考 +summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值以及指向各专用子系统参考文档的链接 title: 配置参考 x-i18n: - generated_at: "2026-04-18T03:32:00Z" + generated_at: "2026-04-19T10:22:55Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若需按任务组织的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。 -本页涵盖 OpenClaw 的主要配置层面，并在某个子系统有自己更深入的参考文档时提供外链。它**不会**尝试在单页中内联每个由渠道/插件拥有的命令目录，或每个深入的内存/QMD 调节项。 +本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有自己更深入的参考文档时提供外链。它**不会**尝试在单页中内联每个渠道 / 插件自有的命令目录，也不会内联所有深层 memory / QMD 调节项。 -代码中的权威来源： +代码事实来源： -- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 返回单个按路径范围限定的 schema 节点，供下钻工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面对配置文档基线哈希进行验证 +- `openclaw config schema` 会打印用于校验和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 +- `config.schema.lookup` 会返回单个按路径范围限定的 schema 节点，供下钻工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema surface 校验配置文档基线哈希 -专用深入参考： +专门的深度参考： -- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 -- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件的命令目录 -- 各渠道/插件所属页面，适用于渠道特定的命令层面 +- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations` 以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置 +- [Slash Commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件的命令目录 +- 各渠道 / 插件所属页面，适用于渠道特定的命令 surface -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -每个渠道在其配置节存在时都会自动启动（除非设置了 `enabled: false`）。 +每个渠道在其配置段存在时都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ---- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对的允许存储中的发送者） | -| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| --------------------- | ------------------------------------------------ | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储） | +| `open` | 允许所有传入私信（需要 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---- | -| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | -| `open` | 绕过群组允许列表（但提及门控仍然适用） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| ----------------------- | ---------------------------------------- | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（仍会应用提及门控） | +| `disabled` | 阻止所有群组 / 房间消息 | `channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退到 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未具有模型覆盖时（例如通过 `/model` 设置），会应用该渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值可接受 `provider/model` 或已配置的模型别名。当某个会话尚未设置模型覆盖时（例如通过 `/model` 设置），就会应用该渠道映射。 ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### 渠道默认值和心跳 +### 渠道默认值与心跳 -使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： +使用 `channels.defaults` 为各提供商设置共享的群组策略和心跳行为： ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。每渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：当某个提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。可选值：`all`（默认，包含所有引用 / 线程 / 历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用 / 回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 -- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 +- `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, // 蓝色已读勾（自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 出站命令默认使用 `default` 账号（如果存在）；否则使用首个已配置的账号 ID（按排序结果）。 -- 可选的 `channels.whatsapp.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖该回退默认账号选择。 -- 旧版单账号 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 出站命令默认使用账号 `default`（如果存在）；否则使用首个已配置的账号 ID（排序后）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖该回退默认账号选择。 +- 旧版单账号 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 - 每账号覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -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 （默认：off；如需避免预览编辑频率限制，请显式启用） actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,12 +226,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 ``` - Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账号还可回退到 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 -- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若该项缺失或无效，`openclaw doctor` 会发出警告。 -- `configWrites: false` 会阻止由 Telegram 发起的配置写入（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)。 +- 可选的 `channels.telegram.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- 在多账号设置（2 个及以上账号 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；当该项缺失或无效时，`openclaw doctor` 会发出警告。 +- `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可为论坛主题配置持久化 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中通用。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（可在私聊和群聊中工作）。 +- 重试策略：参见 [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 （在 Discord 上，progress 会映射为 partial） 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, // 对 `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:`（服务器渠道）作为投递目标；裸数字 ID 会被拒绝。 -- 服务器 slug 为小写，空格会替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用服务器 ID。 -- 默认会忽略由机器人撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则仅接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 -- `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及该机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分较高的消息，即使其未超过 2000 个字符。 +- 对于提供显式 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 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：用于线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：用于按小时设置不活动自动取消聚焦的 Discord 覆盖（`0` 表示禁用） - - `maxAgeHours`：用于按小时设置硬性最大时长的 Discord 覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的显式启用开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中统一说明。 -- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 + - `enabled`：用于线程绑定会话功能的 Discord 覆盖项（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递 / 路由） + - `idleHours`：按小时设置的 Discord 不活动自动取消聚焦覆盖项（`0` 表示禁用） + - `maxAgeHours`：按小时设置的 Discord 硬性最大时长覆盖项（`0` 表示禁用） + - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程的选择性启用开关 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可为渠道和线程配置持久化 ACP 绑定（在 `match.peer.id` 中使用渠道 / 线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中通用。 +- `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。 - `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直通传递给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔 `streaming` 值会自动迁移。 -- `channels.discord.autoPresence` 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - - `approvers`：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人私信，`"channel"` 发送到来源渠道，`"both"` 两处都发送。当 target 包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 - - `cleanupAfterResolve`：当为 `true` 时，在批准、拒绝或超时后删除审批私信。 +- `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` 会重新启用可变名称 / 标签匹配（破窗应急兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生的 exec 审批投递和审批者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，会激活 exec 审批。 + - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时会回退到 `commands.ownerAllowFrom`。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 + - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批者私信，`"channel"` 发送到原始渠道，`"both"` 同时发送到两处。当 target 包含 `"channel"` 时，按钮仅对已解析出的审批者可用。 + - `cleanupAfterResolve`：为 `true` 时，在审批、拒绝或超时后删除审批私信。 -**Reaction notification 模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users`，作用于所有消息）。 +**Reaction notification 模式：** `off`（无）、`own`（bot 自己的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 ### Google Chat @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- 服务账号 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账号 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账号 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 +- 传递目标请使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（破窗应急兼容模式）。 ### Slack @@ -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, // 当 mode=partial 时使用 Slack 原生流式传输 API }, mediaMaxMb: 20, execApprovals: { @@ -464,30 +464,30 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。存在已 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号配置）。 +- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账号的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP mode** 需要 `botToken` 加 `signingSecret`（位于根级或按账号设置）。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- Slack 账号快照会公开每个凭证的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 `signingSecretStatus`。`configured_unavailable` 表示该账号通过 SecretRef 配置，但当前命令/运行时路径无法解析该 secret 值。 +- Slack 账号快照会暴露每个凭证的来源 / 状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账号是通过 SecretRef 配置的，但当前命令 / 运行时路径无法解析该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔 `streaming` 和 `nativeStreaming` 值会自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 可选的 `channels.slack.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 +- 传递目标请使用 `user:`（私信）或 `channel:`（渠道）。 **Reaction notification 模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可以是每线程独立（默认）或在渠道内共享。`thread.inheritParent` 会将父渠道的转录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 为按线程隔离（默认）或在整个渠道内共享。`thread.inheritParent` 会将父渠道转录复制到新线程中。 -- Slack 原生流式传输以及 Slack 助手风格的“正在输入...”线程状态需要回复线程目标。顶层私信默认保持非线程，因此会使用 `typingReaction` 或普通投递，而不是线程风格预览。 -- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加临时反应，并在完成后移除。使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递与审批人授权。schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输以及 Slack 助手风格的“is typing...”线程状态都需要回复线程目标。顶层私信默认保持为非线程，因此会使用 `typingReaction` 或普通投递，而不是线程风格预览。 +- `typingReaction` 会在回复进行时向传入的 Slack 消息添加一个临时 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 | 启用 | 添加反应 + 列出反应 | -| messages | 启用 | 读取/发送/编辑/删除 | -| pins | 启用 | 固定/取消固定/列出 | -| memberInfo | 启用 | 成员信息 | -| emojiList | 启用 | 自定义 emoji 列表 | +| 操作组 | 默认值 | 说明 | +| ----------- | ------- | -------------------- | +| reactions | 启用 | 添加 reaction + 列出 reactions | +| messages | 启用 | 读取 / 发送 / 编辑 / 删除 | +| pins | 启用 | 置顶 / 取消置顶 / 列表 | +| memberInfo | 启用 | 成员信息 | +| emojiList | 启用 | 自定义 emoji 列表 | ### Mattermost @@ -508,10 +508,10 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` "team-channel-id": { requireMention: false }, }, commands: { - native: true, // 显式启用 + native: true, // 选择性启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 面向反向代理/公网部署的可选显式 URL + // 面向反向代理 / 公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,18 +521,18 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` } ``` -聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（回复以触发前缀开头的消息）。 启用 Mattermost 原生命令时： -- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），而不是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且能从 Mattermost 服务器访问。 -- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。请使用主机/域名值，而不是完整 URL。 +- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问该地址。 +- 原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败，或没有任何命令被激活，OpenClaw 会拒绝回调，并返回 `Unauthorized: invalid command token.`。 +- 对于私有 / tailnet / 内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机 / 域名。请使用主机 / 域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在渠道中回复前需要 `@mention`。 -- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 表示默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- `channels.mattermost.requireMention`：要求在渠道中必须先 `@mention` 才会回复。 +- `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（默认值使用 `"*"`）。 +- 可选的 `channels.mattermost.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 ### Signal @@ -557,11 +557,11 @@ Mattermost 作为插件提供：`openclaw plugins install @openclaw/mattermost` - `channels.signal.account`：将渠道启动固定到特定的 Signal 账号身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 可选的 `channels.signal.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles` 下）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `channels.bluebubbles`）。 ```json5 { @@ -577,13 +577,13 @@ BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 `chann ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- 顶层 `bindings[]` 中带有 `type: "acp"` 的条目可以将 BlueBubbles 会话绑定到持久化 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置见 [BlueBubbles](/zh-CN/channels/bluebubbles)。 ### iMessage -OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护进程或端口。 +OpenClaw 会启动 `imsg rpc`（通过 stdio 进行 JSON-RPC）。不需要 daemon 或端口。 ```json5 { @@ -607,17 +607,17 @@ OpenClaw 会生成 `imsg rpc`（基于 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 -- 需要对 Messages 数据库授予 Full Disk Access。 -- 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 +- 需要对 Messages 数据库授予完全磁盘访问权限。 +- 优先使用 `chat_id:` 目标。可使用 `imsg chats --limit 20` 列出聊天。 +- `cliPath` 可以指向 SSH wrapper；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- SCP 使用严格主机密钥检查，因此请确保 relay 主机密钥已存在于 `~/.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)。 - + ```bash #!/usr/bin/env bash @@ -628,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 由扩展支持，配置位于 `channels.matrix` 下。 +Matrix 由扩展支持，配置位于 `channels.matrix`。 ```json5 { @@ -659,24 +659,24 @@ Matrix 由扩展支持，配置位于 `channels.matrix` 下。 ``` - Token 认证使用 `accessToken`；密码认证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与此网络显式启用项是彼此独立的控制项。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。命名账号可通过 `channels.matrix.accounts..proxy` 覆盖。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有 / 内部 homeserver。`proxy` 与这一网络选择性启用项是相互独立的控制项。 - `channels.matrix.defaultAccount` 在多账号设置中选择首选账号。 -- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - - `approvers`：允许审批 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（来源房间）或 `"both"`。 - - 每账号覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组为会话：`per-user`（默认）按路由对端共享，而 `per-room` 则隔离每个私信房间。 -- Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 +- `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并搭配 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 +- `channels.matrix.execApprovals`：Matrix 原生的 exec 审批投递和审批者授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在 auto 模式下，当可从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批者时，会激活 exec 审批。 + - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 + - `agentFilter`：可选的智能体 ID 允许列表。省略时会为所有智能体转发审批。 + - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（原始房间）或 `"both"`。 + - 按账号覆盖：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归并为会话：`per-user`（默认）按路由后的对端共享，而 `per-room` 会隔离每个私信房间。 +- Matrix 状态探测和实时目录查询使用与运行时流量相同的代理策略。 +- 完整的 Matrix 配置、目标规则和设置示例见 [Matrix](/zh-CN/channels/matrix)。 ### Microsoft Teams -Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。 +Microsoft Teams 由扩展支持，配置位于 `channels.msteams`。 ```json5 { @@ -684,7 +684,7 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。 msteams: { enabled: true, configWrites: true, - // appId、appPassword、tenantId、webhook、团队/渠道策略： + // appId、appPassword、tenantId、webhook、团队 / 渠道策略： // 参见 /channels/msteams }, }, @@ -692,11 +692,11 @@ Microsoft Teams 由扩展支持，配置位于 `channels.msteams` 下。 ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 +- 完整的 Teams 配置（凭证、webhook、私信 / 群组策略、按团队 / 按渠道覆盖）见 [Microsoft Teams](/zh-CN/channels/msteams)。 ### IRC -IRC 由扩展支持，配置位于 `channels.irc` 下。 +IRC 由扩展支持，配置位于 `channels.irc`。 ```json5 { @@ -718,12 +718,12 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 会在与某个已配置账号 ID 匹配时覆盖默认账号选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录在 [IRC](/zh-CN/channels/irc) 中。 +- 可选的 `channels.irc.defaultAccount` 会在其与某个已配置账号 ID 匹配时，覆盖默认账号选择。 +- 完整的 IRC 渠道配置（host / port / TLS / channels / allowlists / 提及门控）见 [IRC](/zh-CN/channels/irc)。 ### 多账号（所有渠道） -为每个渠道运行多个账号（每个都有自己的 `accountId`）： +为每个渠道运行多个账号（每个账号都有自己的 `accountId`）： ```json5 { @@ -731,11 +731,11 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 telegram: { accounts: { default: { - name: "Primary bot", + name: "主 bot", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "告警 bot", botToken: "987654:XYZ...", }, }, @@ -744,28 +744,28 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -- 当省略 `accountId` 时使用 `default`（CLI + 路由）。 +- 当省略 `accountId` 时，使用 `default`（CLI + 路由）。 - 环境变量 token 仅适用于 **default** 账号。 -- 基础渠道设置会应用到所有账号，除非按账号进行了覆盖。 +- 基础渠道设置会应用于所有账号，除非按账号单独覆盖。 - 使用 `bindings[].match.accountId` 将每个账号路由到不同的智能体。 -- 如果你在仍使用单账号顶层渠道配置时，通过 `openclaw channels add`（或渠道新手引导）添加非默认账号，OpenClaw 会先将按账号范围的顶层单账号值提升到渠道账号映射中，这样原始账号仍能继续工作。大多数渠道会将其移至 `channels..accounts.default`；Matrix 则可改为保留现有匹配的已命名/默认目标。 -- 现有仅渠道级绑定（无 `accountId`）会继续匹配默认账号；按账号范围的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会修复混合形态，方法是将按账号范围的顶层单账号值移入为该渠道选定的提升后账号中。大多数渠道使用 `accounts.default`；Matrix 则可改为保留现有匹配的已命名/默认目标。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加了一个非默认账号，而当前仍处于单账号顶层渠道配置，OpenClaw 会先将具有账号作用域的顶层单账号值提升到渠道账号映射中，以便原账号继续工作。大多数渠道会将其移动到 `channels..accounts.default`；Matrix 则可以改为保留现有匹配的命名 / 默认目标。 +- 现有仅渠道级的绑定（没有 `accountId`）仍会匹配默认账号；账号级绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将具有账号作用域的顶层单账号值移动到该渠道选定的提升账号中来修复混合形状。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有匹配的命名 / 默认目标。 ### 其他扩展渠道 -许多扩展渠道配置为 `channels.`，并记录在各自专用的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -查看完整渠道索引： [Channels](/zh-CN/channels)。 +许多扩展渠道都配置为 `channels.`，并在其专属渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 -群组消息默认 **需要提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 +群组消息默认**需要提及**（元数据提及或安全 regex 模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 **提及类型：** -- **元数据提及**：平台原生 @ 提及。在 WhatsApp self-chat 模式中会被忽略。 -- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当能够进行检测时（原生提及或至少一个模式），才会执行提及门控。 +- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。 +- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全 regex 模式。无效模式以及不安全的嵌套重复会被忽略。 +- 只有在可以进行检测时（原生提及或至少有一个模式），才会强制执行提及门控。 ```json5 { @@ -778,9 +778,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）进行覆盖。设置为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账号）覆盖。设置为 `0` 可禁用。 -#### 私信历史限制 +#### 私信历史记录限制 ```json5 { @@ -795,13 +795,13 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：每私信覆盖 → 提供商默认值 → 不限（保留全部）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 -#### self-chat 模式 +#### 自聊模式 -在 `allowFrom` 中包含你自己的号码即可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码加入 `allowFrom` 即可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -827,9 +827,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ```json5 { commands: { - native: "auto", // 支持时注册原生命令 - nativeSkills: "auto", // 支持时注册原生 Skills 命令 - text: true, // 在聊天消息中解析 /commands + native: "auto", // 在支持时注册原生命令 + nativeSkills: "auto", // 在支持时注册原生 Skills 命令 + text: true, // 解析聊天消息中的 /commands bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, config: false, // 允许 /config @@ -851,32 +851,32 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 -- 此配置块用于配置命令层面。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 -- 本页是**配置键**参考，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 这类由渠道/插件拥有的命令，记录在其各自的渠道/插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 -- 文本命令必须是带有前导 `/` 的**独立**消息。 -- `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` 会为插件发现、安装以及启用/禁用控制启用 `/plugins`。 -- `channels..configWrites` 控制每个渠道的配置变更（默认：true）。 -- 对于多账号渠道，`channels..accounts..configWrites` 也会控制以该账号为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认：`true`。 -- `ownerAllowFrom` 是 owner 专用命令/工具的显式 owner 允许列表。它与 `allowFrom` 分离。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希行为。 -- `allowFrom` 是按提供商划分的。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对与 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 +- 此配置块用于配置命令 surface。当前内置 + 内置插件命令目录请参见 [Slash Commands](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 以及 Talk `/voice` 这类由渠道 / 插件自有的命令，记录在对应渠道 / 插件页面以及 [Slash Commands](/zh-CN/tools/slash-commands) 中。 +- 文本命令必须是带前导 `/` 的**独立**消息。 +- `native: "auto"` 会为 Discord / Telegram 开启原生命令，对 Slack 保持关闭。 +- `nativeSkills: "auto"` 会为 Discord / Telegram 开启原生 Skills 命令，对 Slack 保持关闭。 +- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前注册的命令。 +- 使用 `channels..commands.nativeSkills` 可按渠道覆盖原生 Skills 注册。 +- `channels.telegram.customCommands` 会添加额外的 Telegram 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 客户端仍然可用。 +- `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 +- `plugins: true` 会启用 `/plugins`，用于插件发现、安装以及启用 / 禁用控制。 +- `channels..configWrites` 控制按渠道进行的配置变更（默认：true）。 +- 对于多账号渠道，`channels..accounts..configWrites` 也会控制面向该账号的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 +- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认值：`true`。 +- `ownerAllowFrom` 是仅限所有者命令 / 工具的显式所有者允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对所有者 ID 进行哈希处理。设置 `ownerDisplaySecret` 可控制哈希方式。 +- `allowFrom` 按提供商生效。设置后，它会成为**唯一**授权来源（渠道 allowlist / pairing 和 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 允许命令在未设置 `allowFrom` 时绕过访问组策略。 - 命令文档映射： - - 内置 + 内置插件目录： [Slash Commands](/zh-CN/tools/slash-commands) - - 渠道特定命令层面： [Channels](/zh-CN/channels) - - QQ Bot 命令： [QQ Bot](/zh-CN/channels/qqbot) - - 配对命令： [Pairing](/zh-CN/channels/pairing) - - LINE 卡片命令： [LINE](/zh-CN/channels/line) - - 内存 Dreaming： [Dreaming](/zh-CN/concepts/dreaming) + - 内置 + 内置插件目录：[Slash Commands](/zh-CN/tools/slash-commands) + - 渠道特定命令 surface：[Channels](/zh-CN/channels) + - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) + - pairing 命令：[Pairing](/zh-CN/channels/pairing) + - LINE card 命令：[LINE](/zh-CN/channels/line) + - memory dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -896,7 +896,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 +系统提示 Runtime 行中显示的可选仓库根路径。若未设置，OpenClaw 会从 workspace 开始向上遍历自动检测。 ```json5 { @@ -906,7 +906,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.skills` -为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 +为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills allowlist。 ```json5 { @@ -921,14 +921,14 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 } ``` -- 省略 `agents.defaults.skills` 表示默认 Skills 不受限制。 +- 省略 `agents.defaults.skills` 表示默认不限制 Skills。 - 省略 `agents.list[].skills` 表示继承默认值。 -- 设置 `agents.list[].skills: []` 表示没有 Skills。 +- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用自动创建 workspace bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -938,9 +938,9 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入到系统提示中。默认值：`"always"`。 +控制何时将 workspace bootstrap 文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全续接回合（在 assistant 完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续写轮次（在 assistant 已完成回复之后）会跳过 workspace bootstrap 的重新注入，从而减少提示大小。heartbeat 运行和压缩后重试仍会重建上下文。 ```json5 { @@ -950,7 +950,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapMaxChars` -每个工作区 bootstrap 文件在截断前的最大字符数。默认值：`12000`。 +单个 workspace bootstrap 文件在被截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -960,7 +960,7 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区 bootstrap 文件合计可注入的最大字符数。默认值：`60000`。 +所有 workspace bootstrap 文件合计可注入的最大字符数。默认值：`60000`。 ```json5 { @@ -970,10 +970,10 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 +控制在 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 -- `"off"`：绝不向系统提示中注入警告文本。 -- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 +- `"off"`：绝不将警告文本注入系统提示。 +- `"once"`：对于每个唯一的截断签名仅注入一次警告（推荐）。 - `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 @@ -984,20 +984,20 @@ IRC 由扩展支持，配置位于 `channels.irc` 下。 ### 上下文预算归属映射 -OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有意按子系统拆分的，而不是全部通过某个通用调节项流动。 +OpenClaw 具有多个高容量提示 / 上下文预算，并且这些预算会按子系统有意拆分，而不是全部流经一个通用调节项。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： - 常规工作区 bootstrap 注入。 + 常规 workspace bootstrap 注入。 - `agents.defaults.startupContext.*`： 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入到系统提示中的紧凑 Skills 列表。 + 注入系统提示中的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： - 有界的运行时摘录和由运行时拥有的注入块。 + 有界的运行时摘录和注入的运行时自有块。 - `memory.qmd.limits.*`： - 已索引的内存搜索片段与注入大小控制。 + 已索引 memory 搜索片段和注入大小控制。 仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖： @@ -1006,7 +1006,7 @@ OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有 #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` 运行中注入的首回合启动前导内容。 +控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -1027,7 +1027,7 @@ OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有 #### `agents.defaults.contextLimits` -有界运行时上下文层面的共享默认值。 +有界运行时上下文 surface 的共享默认值。 ```json5 { @@ -1044,14 +1044,14 @@ OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有 } ``` -- `memoryGetMaxChars`：在添加截断元数据和继续提示之前，`memory_get` 摘录的默认上限。 +- `memoryGetMaxChars`：在添加截断元数据和续写提示之前，`memory_get` 摘录的默认上限。 - `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：用于压缩后刷新注入时的 `AGENTS.md` 摘录上限。 +- `postCompactionMaxChars`：用于压缩后刷新注入时 `AGENTS.md` 摘录的上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 +对共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承 `agents.defaults.contextLimits`。 ```json5 { @@ -1077,7 +1077,7 @@ OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有 #### `skills.limits.maxSkillsPromptChars` -注入到系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 +注入系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -1091,7 +1091,7 @@ OpenClaw 具有多个高容量提示/上下文预算，并且这些预算是有 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示预算的按智能体覆盖。 +针对 Skills 提示预算的按智能体覆盖。 ```json5 { @@ -1110,11 +1110,11 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，transcript / 工具图像块中图像最长边允许的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量以及以截图为主运行时的请求负载大小。 -较高的值会保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量，并减小以截图为主的运行请求负载大小。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -1124,7 +1124,7 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.userTimezone` -系统提示上下文所用时区（不是消息时间戳）。会回退到主机时区。 +系统提示上下文使用的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -1134,7 +1134,7 @@ Skills 提示预算的按智能体覆盖。 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（OS 偏好）。 ```json5 { @@ -1191,48 +1191,48 @@ Skills 提示预算的按智能体覆盖。 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 字符串形式只设置主模型。 - - 对象形式设置主模型以及有序故障切换模型。 -- `imageModel`：接受字符串（`"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-1`（用于 OpenAI Images）。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/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` 工具。 + - 当已选 / 默认模型无法接受图像输入时，也会用作回退路由。 +- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 用于共享的图像生成能力，以及任何未来生成图像的工具 / 插件 surface。 + - 典型值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-1`（OpenAI Images）。 + - 如果你直接选择某个 provider / model，也请同时配置对应的 provider 凭证 / API key（例如 `google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 需要 `OPENAI_API_KEY`，`fal/*` 需要 `FAL_KEY`）。 + - 若省略，`image_generate` 仍可推断出有认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试其余已注册的图像生成 provider。 +- `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` 工具。 + - 若省略，`music_generate` 仍可推断出有认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试其余已注册的音乐生成 provider。 + - 如果你直接选择某个 provider / model，也请同时配置对应的 provider 凭证 / 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 }`）。 + - 若省略，`video_generate` 仍可推断出有认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试其余已注册的视频生成 provider。 + - 如果你直接选择某个 provider / model，也请同时配置对应的 provider 凭证 / API key。 + - 内置的 Qwen 视频生成 provider 最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及 provider 级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 用于 `pdf` 工具的模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 + - 若省略，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` 配置的模型目录和允许列表。每个条目都可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 -- `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。 +- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 +- `verboseDefault`：智能体默认 verbose 级别。可选值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体默认 elevated-output 级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到首个已配置 provider / model，而不是继续暴露一个陈旧的、已移除 provider 默认值。 +- `models`：用于 `/model` 的已配置模型目录和 allowlist。每个条目都可以包含 `alias`（快捷名）和 `params`（provider 特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 +- `params`：应用到所有模型的全局默认 provider 参数。设置路径为 `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` 以及 fallback add / remove 命令）会保存为规范对象形式，并尽量保留现有 fallback 列表。 +- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍然串行）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体回合。 -大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 -当某个受信任插件提供原生 harness 时使用它，例如内置的 +`embeddedHarness` 控制由哪个底层执行器运行嵌入式智能体轮次。 +大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 +当受信任插件提供原生 harness 时使用它，例如内置的 Codex app-server harness。 ```json5 @@ -1249,15 +1249,15 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或某个已注册插件 harness ID。内置 Codex 插件注册的是 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 会在插件 harness 缺失或不支持所选项时直接失败，而不是静默使用 PI。 +- `runtime`：`"auto"`、`"pi"` 或某个已注册插件 harness id。内置 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 则会在插件 harness 选择缺失或不受支持时直接失败，而不是静默使用 PI。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 -- 对于仅 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们自己的提供商/模型设置。 +- 对于仅使用 Codex 的部署，请设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / model 设置。 -**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： +**内置 alias 简写**（仅在该模型存在于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | +| Alias | 模型 | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1268,15 +1268,15 @@ Codex app-server harness。 | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你配置的别名始终优先于默认值。 +你配置的 alias 总是优先于默认值。 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` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 +Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可将其禁用。 +Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -适用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备份。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API provider 失败时，可作为备份。 ```json5 { @@ -1304,13 +1304,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本为主；工具始终禁用。 +- CLI 后端以文本为主；工具始终被禁用。 - 设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图像直通。 +- 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示。可设置在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅空白的值会被忽略。适用于受控的提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先级更高；空值或仅含空白的值会被忽略。适用于受控提示实验。 ```json5 { @@ -1324,7 +1324,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.heartbeat` -定期 Heartbeat 运行。 +周期性 heartbeat 运行。 ```json5 { @@ -1334,13 +1334,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 节 - lightContext: false, // 默认：false；true 仅保留工作区 bootstrap 文件中的 HEARTBEAT.md + includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 + lightContext: false, // 默认：false；true 仅保留 workspace bootstrap 文件中的 HEARTBEAT.md isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认） | block - target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（默认）| block + target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1351,15 +1351,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 上下文，并仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次 heartbeat 都会在一个没有任何先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 采用相同隔离模式。可将每次 heartbeat 的 token 成本从约 100K 降至约 2-5K tokens。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 -- Heartbeat 会运行完整的智能体回合 —— 间隔越短，消耗的 tokens 越多。 +- `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`：direct / 私信投递策略。`allow`（默认）允许 direct-target 投递。`block` 会抑制 direct-target 投递，并输出 `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 越多。 ### `agents.defaults.compaction` @@ -1369,19 +1369,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选） + provider: "my-provider", // 已注册 compaction provider 插件的 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 + identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于 compaction 的可选模型覆盖 - notifyUser: true, // compaction 开始时发送简短通知（默认：false） + notifyUser: true, // 在 compaction 开始时向用户发送简短通知（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "会话即将进行 compaction。现在请存储持久记忆。", + prompt: "将任何持久备注写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，请精确回复静默 token NO_REPLY。", }, }, }, @@ -1389,19 +1389,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（适用于长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方案。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。 +- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册 compaction provider 插件的 id。设置后，将调用该 provider 的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 在中止前允许单次 compaction 操作运行的最长秒数。默认值：`900`。 - `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指导。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：compaction 后要重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置时，或显式设置为该默认配对时，也接受较旧的 `Every Session`/`Safety` 标题作为旧版回退。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持使用一个模型，而 compaction 摘要应改用另一个模型时使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：为 `true` 时，在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：在自动 compaction 之前执行静默的智能体回合，用于存储持久记忆。工作区为只读时会跳过。 +- `postCompactionSections`：compaction 后要重新注入的可选 `AGENTS.md` H2 / H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。若未设置，或显式设置为该默认配对，则旧版 `Every Session` / `Safety` 标题也会作为兼容性回退被接受。 +- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持使用某个模型，而 compaction 摘要应使用另一个模型时，请使用此项；未设置时，compaction 会使用会话的主模型。 +- `notifyUser`：为 `true` 时，会在 compaction 开始时向用户发送简短通知（例如“正在压缩上下文...”）。默认禁用，以保持 compaction 静默进行。 +- `memoryFlush`：在自动 compaction 前执行静默的智能体轮次，用于存储持久记忆。当 workspace 为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存中的上下文里修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1415,7 +1415,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[旧工具结果内容已清除]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1425,23 +1425,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制下次允许再次运行修剪的间隔时间（自上次缓存触碰后计算）。 -- 修剪会先对过大的工具结果进行软裁剪，如有需要，再对较旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用修剪流程。 +- `ttl` 控制多久之后才能再次运行修剪（自上次缓存触碰后计算）。 +- 修剪会先对过大的工具结果执行软截断，然后在需要时对更旧的工具结果执行硬清除。 -**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 +**软截断**会保留开头和结尾，并在中间插入 `...`。 **硬清除**会用占位符替换整个工具结果。 -说明： +注意： -- 图像块永远不会被裁剪/清除。 -- 比例按字符计算（近似），不是精确 token 数。 +- 图像块永远不会被截断 / 清除。 +- 比例按字符计算（近似值），不是精确 token 数。 - 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 -行为详情参见 [Session Pruning](/zh-CN/concepts/session-pruning)。 +行为细节见 [Session Pruning](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -1459,11 +1459,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`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号变体）。Signal / Slack / Discord / Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为与分块详情参见 [Streaming](/zh-CN/concepts/streaming)。 +行为和分块细节见 [Streaming](/zh-CN/concepts/streaming)。 ### 输入中指示器 @@ -1478,7 +1478,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/被提及时为 `instant`，未被提及的群聊为 `message`。 +- 默认值：私聊 / 被提及时为 `instant`，未被提及的群聊中为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1487,7 +1487,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南参见 [Sandboxing](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南见 [Sandboxing](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -1587,19 +1587,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 支持的远程运行时 +- `ssh`：通用 SSH 远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时特定设置会移至 +选择 `backend: "openshell"` 时，运行时特定设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** - `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：供按作用域工作区使用的远程绝对根路径 +- `workspaceRoot`：用于按作用域 workspace 的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRef - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略调节项 **SSH 认证优先级：** @@ -1607,27 +1607,27 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前激活的 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前从当前 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后仅播种一次远程工作区 -- 然后保持远程 SSH 工作区为规范副本 +- 在创建或重新创建后，先为远程 workspace 执行一次初始化 +- 随后保持远程 SSH workspace 为规范副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程更改同步回主机 -- 不支持沙箱浏览器容器 +- 不会自动将远程变更同步回主机 +- 不支持沙箱 browser 容器 -**工作区访问：** +**workspace 访问：** -- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱工作区 -- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` -- `rw`：智能体工作区以读写方式挂载到 `/workspace` +- `none`：在 `~/.openclaw/sandboxes` 下使用按作用域划分的沙箱 workspace +- `ro`：沙箱 workspace 位于 `/workspace`，智能体 workspace 以只读方式挂载到 `/agent` +- `rw`：智能体 workspace 以读写方式挂载到 `/workspace` **作用域：** -- `session`：按会话划分的容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） -- `shared`：共享容器和工作区（无跨会话隔离） +- `session`：每会话一个容器 + workspace +- `agent`：每智能体一个容器 + workspace（默认） +- `shared`：共享容器和 workspace（无跨会话隔离） **OpenShell 插件配置：** @@ -1644,7 +1644,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 remoteAgentWorkspaceDir: "/agent", gateway: "lab", // 可选 gatewayEndpoint: "https://lab.example", // 可选 - policy: "strict", // 可选 OpenShell 策略 id + policy: "strict", // 可选 OpenShell policy id providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, @@ -1657,30 +1657,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在执行前从本地播种到远程，执行后再同步回来；本地工作区保持为规范副本 -- `remote`：在创建沙箱时仅向远程播种一次，随后保持远程工作区为规范副本 +- `mirror`：执行前将本地内容初始化到远程，执行后再同步回本地；本地 workspace 保持为规范副本 +- `remote`：创建沙箱时仅初始化一次远程，随后保持远程 workspace 为规范副本 -在 `remote` 模式下，于 OpenClaw 之外在主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 -传输层通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，于 OpenClaw 之外在主机本地所做的编辑，在初始化步骤之后不会自动同步进沙箱。 +传输层使用 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期和可选的 mirror 同步。 **`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 **容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 会被阻止。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 +默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗应急模式）。 -**传入附件** 会暂存到当前工作区的 `media/inbound/*` 中。 +**传入附件** 会被暂存到活动 workspace 中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 +**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +**沙箱隔离 browser**（`sandbox.browser.enabled`）：在容器中运行的 Chromium + CDP。会将 noVNC URL 注入系统提示。不需要在 `openclaw.json` 中启用 `browser.enabled`。 noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选，用于将容器边缘的 CDP 入口限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机做了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机 browser。 +- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时，才设置为 `bridge`。 +- `cdpSourceRange` 可选地将容器边界的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱隔离 browser 容器中。设置后（包括 `[]`），它会替换 browser 容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1698,23 +1698,21 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有 - `--no-zygote` - `--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` 重新启用扩展。 - - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 则使用 Chromium 的默认进程限制。 - - 此外，在启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。 + - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL / 3D 使用需要它们，可通过设置 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 来禁用这些标志。 + - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 + - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 可使用 Chromium 的默认进程限制。 + - 当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。 + - 这些默认值是容器镜像基线；如需修改容器默认值，请使用带有自定义 entrypoint 的自定义 browser 镜像。 -浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 +Browser 沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 构建镜像： ```bash scripts/sandbox-setup.sh # 主沙箱镜像 -scripts/sandbox-browser-setup.sh # 可选浏览器镜像 +scripts/sandbox-browser-setup.sh # 可选 browser 镜像 ``` ### `agents.list`（按智能体覆盖） @@ -1730,12 +1728,12 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } - thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性 - fastModeDefault: false, // 按智能体覆盖的默认快速模式 + thinkingDefault: "high", // 按智能体覆盖 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖 fast mode embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置时会替换 agents.defaults.skills + params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models params + skills: ["docs-search"], // 设置后会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1766,27 +1764,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 允许列表。若省略，且已设置 `agents.defaults.skills`，则该智能体会继承之；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `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` 会派生默认值：从 `emoji` 推导 `ackReaction`，从 `name`/`emoji` 推导 `mentionPatterns`。 -- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `id`：稳定的智能体 ID（必填）。 +- `default`：如果设置了多个，则以第一个为准（会记录警告）。如果一个都未设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局 fallback）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallback，除非你设置 `fallbacks: []`。 +- `params`：按智能体设置的流式参数，会合并覆盖到 `agents.defaults.models` 中已选模型条目之上。用它来为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills allowlist。如果省略，则在设置了 `agents.defaults.skills` 时继承该值；显式列表会替换默认值而不是合并，`[]` 表示不启用任何 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive`）。当没有按消息或会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当没有按消息或会话的 reasoning 覆盖时生效。 +- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当没有按消息或会话的 fast-mode 覆盖时生效。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体仍保留默认的 PI fallback。 +- `runtime`：可选的按智能体运行时描述符。当智能体默认应使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：workspace 相对路径、`http(s)` URL 或 `data:` URI。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name` / `emoji`。 +- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 ID allowlist（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承防护：如果请求者会话已处于沙箱隔离中，`sessions_spawn` 会拒绝那些会在无沙箱下运行的目标。 +- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择 profile；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个相互隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1805,27 +1803,27 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由用 `route`（缺失时默认是 route），持久 ACP 对话绑定用 `acp`。 -- `match.channel`（必需） +- `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 }` **确定性匹配顺序：** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer/guild/team） -5. `match.accountId: "*"`（渠道范围） +4. `match.accountId`（精确匹配，无 peer / guild / team） +5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每一层中，第一个匹配的 `bindings` 条目获胜。 +在每一层级内，第一个匹配的 `bindings` 条目获胜。 -对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）进行解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + 账号 + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。 -### 按智能体访问配置 +### 按智能体访问配置文件 @@ -1845,7 +1843,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1874,7 +1872,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - + ```json5 { @@ -1920,7 +1918,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级详情参见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 +优先级细节见 [Multi-Agent Sandbox & Tools](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1953,7 +1951,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 maxEntries: 500, rotateBytes: "10mb", resetArchiveRetention: "30d", // 时长或 false - maxDiskBytes: "500mb", // 可选硬预算 + maxDiskBytes: "500mb", // 可选硬上限预算 highWaterBytes: "400mb", // 可选清理目标 }, threadBindings: { @@ -1974,34 +1972,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在某个渠道上下文中，每个发送者获得隔离的会话。 - - `global`：某个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在同一渠道上下文内，每个发送者拥有独立会话。 + - `global`：同一渠道上下文中的所有参与者共享一个会话（仅在你确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `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` 可禁用此保护，并始终允许父级分叉。 -- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式传递。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 进行匹配。首个 deny 生效。 +- **`identityLinks`**：将规范 ID 映射到带 provider 前缀的 peer，用于跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名使用。 +- **`parentForkMaxTokens`**：创建 fork 出来的线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。 + - 如果父会话的 `totalTokens` 超过该值，OpenClaw 会启动一个全新的线程会话，而不是继承父级 transcript 历史。 + - 设为 `0` 可禁用此保护，并始终允许从父级 fork。 +- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主私聊桶。 +- **`agentToAgent.maxPingPongTurns`**：智能体间交换时允许的最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式回复。 +- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，其中旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一条 deny 优先生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会应用清理。 - - `pruneAfter`：陈旧条目的时间截止（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留时长。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的制品/会话。 - - `highWaterBytes`：预算清理后的可选目标值。默认为 `maxDiskBytes` 的 `80%`。 + - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 + - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` transcript 归档的保留期。默认继承 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件 / 会话。 + - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖） + - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用；provider 可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；provider 可覆盖） @@ -2039,36 +2037,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 回复前缀 -按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道 / 账号覆盖：`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}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 -### 确认反应 +### Ack reaction - 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 -- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时若确认反应处于激活状态，则状态反应保持启用。 - 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。 +- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除 ack。 +- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态 reaction。 + 在 Slack 和 Discord 上，未设置时会在 ack reaction 已启用的情况下保持状态 reaction 启用。 + 在 Telegram 上，需显式将其设为 `true` 才会启用生命周期状态 reaction。 ### 入站防抖 -将来自同一发送者的快速纯文本消息批处理为一次智能体回合。媒体/附件会立即冲刷。控制命令会绕过防抖。 +将来自同一发送者的快速、纯文本消息合并为一次智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -2112,17 +2110,17 @@ 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 服务器，并放宽模型/语音验证。 +- `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-compatible TTS 服务器，并放宽模型 / voice 校验。 --- ## Talk -Talk 模式的默认值（macOS/iOS/Android）。 +Talk 模式的默认值（macOS / iOS / Android）。 ```json5 { @@ -2146,13 +2144,13 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 +- 当配置了多个 Talk provider 时，`talk.provider` 必须与 `talk.providers` 中的某个键匹配。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，会被自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 -- `silenceTimeoutMs` 控制用户静默后，Talk 模式等待多久才发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用易读名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送 transcript。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- @@ -2160,37 +2158,37 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置一个基础允许列表： +`tools.profile` 会在 `tools.allow` / `tools.deny` 之前设置基础 allowlist： -本地新手引导会在未设置时，将新的本地配置默认设为 `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` | 无限制（与未设置相同） | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 无限制（与未设置相同） | ### 工具组 -| 组 | 工具 | +| 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | | `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括 provider 插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 +全局工具允许 / 拒绝策略（deny 优先生效）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会应用。 ```json5 { @@ -2200,7 +2198,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.byProvider` -进一步为特定提供商或模型限制工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。 +对特定 provider 或模型进一步限制工具。顺序：基础 profile → provider profile → allow / deny。 ```json5 { @@ -2216,7 +2214,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.elevated` -控制沙箱之外的高权限 exec 访问： +控制沙箱之外的 elevated exec 访问： ```json5 { @@ -2232,9 +2230,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` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`；当 exec 目标是 `node` 时则使用 `node`）。 ### `tools.exec` @@ -2258,8 +2256,8 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.loopDetection` -工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 -设置可在 `tools.loopDetection` 中全局定义，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 以启用检测。 +设置可在全局 `tools.loopDetection` 中定义，并在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2280,14 +2278,14 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `historySize`：为循环分析保留的最大工具调用历史数。 +- `historySize`：用于循环分析时保留的最大工具调用历史数。 - `warningThreshold`：对重复无进展模式发出警告的阈值。 -- `criticalThreshold`：对严重循环进行阻止的更高重复阈值。 -- `globalCircuitBreakerThreshold`：任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复的同工具/同参数调用发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展配对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 +- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：对任何无进展运行触发硬停止的阈值。 +- `detectors.genericRepeat`：对重复的同工具 / 同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻止。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告 / 阻止。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，则校验失败。 ### `tools.web` @@ -2304,7 +2302,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略时自动检测 + provider: "firecrawl", // 可选；省略则自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2321,7 +2319,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.media` -配置入站媒体理解（图像/音频/视频）： +配置入站媒体理解（图像 / 音频 / 视频）： ```json5 { @@ -2329,7 +2327,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // 显式启用：将完成的异步音乐/视频直接发送到渠道 + directSend: false, // 选择性启用：将已完成的异步音乐 / 视频直接发送到渠道 }, audio: { enabled: true, @@ -2355,10 +2353,10 @@ Talk 模式的默认值（macOS/iOS/Android）。 -**提供商条目**（`type: "provider"` 或省略）： +**Provider 条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 id 覆盖 +- `provider`：API provider id（`openai`、`anthropic`、`google` / `gemini`、`groq` 等） +- `model`：模型 ID 覆盖 - `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2368,17 +2366,17 @@ Talk 模式的默认值（macOS/iOS/Android）。 **通用字段：** -- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → image，`google` → image+audio+video，`groq` → audio。 +- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai` / `anthropic` / `minimax` → image，`google` → image + audio + video，`groq` → audio。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -提供商凭证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - `asyncCompletion.directSend`：为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接渠道投递。默认：`false` - （旧版请求方会话唤醒/模型投递路径）。 + 和 `video_generate` 任务会先尝试直接投递到渠道。默认值：`false` + （沿用旧版请求者会话唤醒 / 模型投递路径）。 @@ -2397,9 +2395,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可针对哪些会话。 +控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。 -默认值：`tree`（当前会话 + 由其生成的会话，例如 subagents）。 +默认值：`tree`（当前会话 + 由其派生出的会话，例如子智能体）。 ```json5 { @@ -2415,10 +2413,10 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： - `self`：仅当前会话键。 -- `tree`：当前会话 + 当前会话生成的会话（subagents）。 -- `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` @@ -2429,7 +2427,7 @@ Talk 模式的默认值（macOS/iOS/Android）。 tools: { sessions_spawn: { attachments: { - enabled: false, // 显式启用：设为 true 以允许内联文件附件 + enabled: false, // 选择性启用：设为 true 以允许内联文件附件 maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, maxFileBytes: 1048576, // 每个文件 1 MB @@ -2442,16 +2440,16 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会实体化到子工作区的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 -- 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会通过严格的字母表/填充校验以及解码前大小保护进行验证。 +- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝附件。 +- 文件会被物化到子 workspace 的 `.openclaw/attachments//` 中，并附带一个 `.manifest.json`。 +- 附件内容会自动从 transcript 持久化中脱敏。 +- Base64 输入会通过严格的字母表 / 填充校验以及解码前大小保护进行验证。 - 目录权限为 `0700`，文件权限为 `0600`。 -- 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 +- 清理遵循 `cleanup` 策略：`delete` 总是删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。 +实验性内置工具标志。默认关闭，除非触发严格 agentic GPT-5 自动启用规则。 ```json5 { @@ -2465,9 +2463,9 @@ Talk 模式的默认值（macOS/iOS/Android）。 说明： -- `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）被设置为 OpenAI 或 OpenAI Codex GPT-5 系列运行的 `"strict-agentic"`。设为 `true` 可在该范围之外强制启用此工具，设为 `false` 则即使对 strict-agentic GPT-5 运行也保持关闭。 -- 启用后，系统提示还会添加使用指导，使模型仅在实质性工作中使用它，并始终最多保持一个步骤处于 `in_progress`。 +- `planTool`：为非平凡多步骤工作跟踪启用结构化 `update_plan` 工具。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）对 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设为 `true` 可在该范围之外强制启用该工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 +- 启用后，系统提示还会加入使用说明，以便模型仅在重要工作中使用它，并始终最多只保留一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2487,21 +2485,21 @@ Talk 模式的默认值（macOS/iOS/Android）。 } ``` -- `model`：生成的子智能体默认模型。若省略，子智能体会继承调用方的模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 -- 每个子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 +- `model`：派生子智能体的默认模型。若省略，子智能体会继承调用者的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 可用的默认目标智能体 ID allowlist（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 +- 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- -## 自定义提供商和 base URL +## 自定义 provider 和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义 provider。 ```json5 { models: { - mode: "merge", // merge（默认） | replace + mode: "merge", // merge（默认）| replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2525,50 +2523,50 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 对于自定义认证需求，使用 `authHeader: true` + `headers`。 +- 使用 `authHeader: true` + `headers` 以满足自定义认证需求。 - 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 -- 对匹配提供商 ID 的合并优先级： - - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商未在当前配置/auth-profile 上下文中由 SecretRef 管理时优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`）。 - - 空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间取较高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；用它可限制有效上下文，而无需更改原生模型元数据。 - - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记从当前激活的源配置快照（解析前）写入，而不是从已解析的运行时 secret 值写入。 +- 对于匹配的 provider ID，合并优先级如下： + - 非空的智能体 `models.json` `baseUrl` 值优先生效。 + - 非空的智能体 `apiKey` 值仅在该 provider 在当前配置 / 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` / `baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow` / `maxTokens` 会在显式配置值和隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；使用它可以限制有效上下文，而无需修改模型原生元数据。 + - 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。 + - 标记持久化以源为准：标记写入自活动源配置快照（解析前），而不是来自已解析的运行时 secret 值。 -### 提供商字段详情 +### Provider 字段详情 -- `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 id 作为键的自定义提供商映射。 +- `models.mode`：provider 目录行为（`merge` 或 `replace`）。 +- `models.providers`：按 provider id 键控的自定义 provider 映射。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 +- `models.providers.*.apiKey`：provider 凭证（优先使用 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.*.headers`：用于代理/租户路由的额外静态 headers。 -- `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 兼容端点的 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 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。 +- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 header。 +- `models.providers.*.request`：模型 provider HTTP 请求的传输覆盖。 + - `request.headers`：额外 header（会与 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 fetch 防护访问 HTTPS（这是为受信任的自托管 OpenAI-compatible 端点提供的 operator 选择性启用项）。WebSocket 使用相同的 `request` 来处理 header / TLS，但不使用该 fetch SSRF 防护。默认值为 `false`。 +- `models.providers.*.models`：显式 provider 模型目录条目。 +- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 +- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时，请使用此项。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生值（host 不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的 / 省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：针对仅支持字符串的 OpenAI-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.enabled`：开启 / 关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的提供商 id 过滤器，用于定向发现。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 tokens。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 -### 提供商示例 +### Provider 示例 @@ -2582,8 +2580,8 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ fallbacks: ["cerebras/zai-glm-4.6"], }, models: { - "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, - "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }, + "cerebras/zai-glm-4.7": { alias: "GLM 4.7（Cerebras）" }, + "cerebras/zai-glm-4.6": { alias: "GLM 4.6（Cerebras）" }, }, }, }, @@ -2595,8 +2593,8 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ apiKey: "${CEREBRAS_API_KEY}", api: "openai-completions", models: [ - { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, - { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }, + { id: "zai-glm-4.7", name: "GLM 4.7（Cerebras）" }, + { id: "zai-glm-4.6", name: "GLM 4.6（Cerebras）" }, ], }, }, @@ -2621,7 +2619,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 +设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录请使用 `opencode/...` 引用，Go 目录请使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 @@ -2641,8 +2639,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 覆盖的自定义提供商。 +- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 对于通用端点，请定义一个带 base URL 覆盖的自定义 provider。 @@ -2681,11 +2679,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 会根据端点能力 -而不仅仅是内置提供商 id 来处理这一点。 +`openai-completions` 传输上声明流式传输用法兼容性，OpenClaw 会根据端点能力 +而不只是内置 provider id 本身来决定相关行为。 @@ -2703,11 +2701,11 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -兼容 Anthropic，内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +Anthropic-compatible，内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2742,7 +2740,7 @@ Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7` } ``` -base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2786,16 +2784,15 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic 兼容的流式路径上，OpenClaw 默认会关闭 MiniMax thinking， -除非你显式自行设置 `thinking`。`/fast on` 或 -`params.fastMode: true` 会将 `MiniMax-M2.7` 改写为 +在 Anthropic-compatible 流式传输路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。 +`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留合并的托管模型作为回退。 +参见 [Local Models](/zh-CN/gateway/local-models)。简而言之：在性能较强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2826,13 +2823,13 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。 +- `allowBundled`：仅针对内置 Skills 的可选 allowlist（托管 / workspace Skills 不受影响）。 - `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。 -- `install.nodeManager`：`metadata.openclaw.install` - 规范使用的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 skill 已内置/安装，也会将其禁用。 -- `entries..apiKey`：为声明了主环境变量的 skills 提供便捷配置（明文字符串或 SecretRef 对象）。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个 Skill 已内置 / 已安装，也将其禁用。 +- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -2860,41 +2857,41 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 和 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 -- **配置变更需要重启 gateway。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时可用）。 +- 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 +- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置更改需要重启 Gateway 网关。** +- `allow`：可选 allowlist（仅加载列出的插件）。`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 获取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 和受支持的 bundle 提供 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可在后台子智能体运行中请求按次覆盖 `provider` 和 `model`。 +- `plugins.entries..subagent.allowedModels`：针对受信任子智能体覆盖的可选规范 `provider/model` 目标 allowlist。仅当你确实想允许任意模型时才使用 `"*"`。 +- `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`）。 + - `onlyMainContent`：仅提取页面主内容（默认：`true`）。 + - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 + - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 - `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：内存 Dreaming 设置。阶段与阈值参见 [Dreaming](/zh-CN/concepts/dreaming)。 - - `enabled`：Dreaming 主开关（默认 `false`）。 - - `frequency`：每次完整 Dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - - 阶段策略与阈值属于实现细节（不是面向用户的配置键）。 -- 完整内存配置见 [内存配置参考](/zh-CN/reference/memory-config)： +- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 + - `enabled`：dreaming 主开关（默认 `false`）。 + - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 + - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 +- 完整 memory 配置见 [Memory configuration reference](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。 -- `plugins.slots.memory`：选择活动内存插件 id，或设为 `"none"` 以禁用内存插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择其他引擎。 +- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是当作原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 以禁用 memory 插件。 +- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 + - 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 参见 [Plugins](/zh-CN/tools/plugin)。 @@ -2909,7 +2906,7 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 仅对受信任的私有网络访问显式启用 + // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时选择性启用 // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2937,26 +2934,29 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。 -- 仅当你明确受信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止策略约束。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用，因此 browser 导航默认保持严格模式。 +- 仅当你明确愿意信任私有网络 browser 导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP profile 端点（`profiles.*.cdpUrl`）在可达性 / 发现检查期间也会受到同样的私有网络阻止规则约束。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。 -- 远程配置文件为仅附加模式（start/stop/reset 已禁用）。 +- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。 +- 远程 profile 为仅附加模式（禁用 start / stop / reset）。 - `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 路由限制： - 基于 snapshot/ref 的操作而不是 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`、窗口大小设置或调试标志）。 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； + 当你的提供方直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 +- `existing-session` profile 使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机 + 或已连接的 browser 节点上。 +- `existing-session` profile 可以设置 `userDataDir`，以指向特定的 + Chromium-based browser profile，例如 Brave 或 Edge。 +- `existing-session` profile 保持当前 Chrome MCP 路由限制： + 使用 snapshot / ref 驱动的操作，而不是 CSS selector 定位；单文件上传 + hook；不支持对话框超时覆盖；不支持 `wait --load networkidle`，以及 + `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地托管的 `openclaw` profile 会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 远程 CDP 才需要显式设置 `cdpUrl`。 +- 自动检测顺序：如果默认 browser 是 Chromium-based，则优先使用默认 browser → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 +- `extraArgs` 会在本地 Chromium 启动时追加额外启动标志（例如 + `--disable-gpu`、窗口尺寸或调试标志）。 --- @@ -2974,8 +2974,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 } ``` -- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。 -- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。 +- `seamColor`：原生应用 UI 外观的强调色（Talk Mode 气泡着色等）。 +- `assistant`：Control UI 身份覆盖。未设置时会回退到当前活动智能体身份。 --- @@ -3010,8 +3010,8 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 // 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 回退模式 + // allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必填 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3044,64 +3044,64 @@ base URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方 -- `mode`：`local`（运行 gateway）或 `remote`（连接远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 +- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 - **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 说明**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量会到达 `eth0`，因此 gateway 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以在所有接口上监听。 -- **认证**：默认必须启用。非 loopback bind 需要 gateway 认证。实际中这意味着共享 token/password，或启用了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。若两者都已配置但未设置 mode，启动以及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项，这是有意为之。 -- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 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 和认证范围生效（共享密钥与设备 token 分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在失败写入前串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都以普通不匹配方式穿过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认是 `true`；当你有意也想对 localhost 流量启用限流时（例如测试环境或严格代理部署），请设为 `false`。 -- 来自浏览器源的 WS 认证尝试始终会启用限流，且不会豁免 loopback（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 -- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值隔离，因此来自一个 localhost origin 的重复失败不会自动 +- **Docker 说明**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 gateway 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或使用 `bind: "custom"` 并设置 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必须启用。非 loopback bind 需要 Gateway 网关认证。实际来说，这意味着需要共享 token / password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。如果两者都已配置但未设置 mode，启动和服务安装 / 修复流程会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于受信任的本地 local loopback 设置；新手引导提示中不会提供该选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 header（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不能满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 header 可以满足 Control UI / WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 gateway 的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。这种无 token 流程假定 gateway 主机是受信任的。 +- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 会被分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，同一个 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端并发的错误尝试，可能会在第二个请求时触发限流，而不是两个请求都像普通不匹配那样并行通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你明确希望连 localhost 流量也被限流（例如测试环境或严格代理部署），请设为 `false`。 +- 来自 browser-origin 的 WS 认证尝试始终会启用限流，并关闭 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- 在 loopback 上，这些 browser-origin 锁定会按规范化后的 `Origin` + 值进行隔离，因此一个 localhost origin 的重复失败不会自动 锁定另一个 origin。 - `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。 -- `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`：客户端侧的紧急覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式 browser-origin allowlist。当期望来自非 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`：客户端侧的破窗应急覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许对 loopback 使用明文。 - `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway 认证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 gateway 发布基于 relay 的注册后，供其使用的外部 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.auth.*` 未设置时，本地 gateway 调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未能解析，解析会默认拒绝失败（不会被远程回退掩盖）。 -- `trustedProxies`：终止 TLS 或注入 forwarded-client headers 的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**让 loopback 请求具备 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：为 `true` 时，当 `X-Forwarded-For` 缺失时，gateway 接受 `X-Real-IP`。默认 `false`，以保持默认拒绝行为。 -- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认 deny 列表）。 -- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。 +- `gateway.push.apns.relay.baseUrl`：供官方 / TestFlight iOS 构建在向 gateway 发布基于 relay 的注册之后使用的外部 APNs relay 的基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。 +- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时（毫秒）。默认值为 `10000`。 +- 基于 relay 的注册会委派给特定的 gateway identity。配对后的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该 identity，并向 gateway 转发一个具有注册作用域的发送授权。其他 gateway 无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅限开发环境的逃逸开关，用于 loopback HTTP relay URL。生产环境 relay URL 应保持 HTTPS。 +- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：每个渠道 / 账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保留全局监控启用。 +- `channels..accounts..healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，它优先于渠道级覆盖。 +- 本地 gateway 调用路径仅会在 `gateway.auth.*` 未设置时，才将 `gateway.remote.*` 用作回退。 +- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析成功，则解析会默认拒绝（不会用远程回退掩盖）。 +- `trustedProxies`：终止 TLS 或注入转发客户端 header 的反向代理 IP。只列出你控制的代理。loopback 条目对同主机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**让 loopback 请求具备使用 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，gateway 会接受 `X-Real-IP`。默认 `false`，以保持默认拒绝行为。 +- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。 +- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。 -### OpenAI 兼容端点 +### OpenAI-compatible 端点 -- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false`。 -- 可选响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 空 allowlist 会被视为未设置；如需禁用 URL 获取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false`。 +- 可选的响应加固 header： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在一台主机上运行多个 gateways，并使用唯一端口和状态目录： +在同一主机上运行多个 Gateway 网关，并使用唯一的端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3129,10 +3129,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`：在 gateway 监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：在未配置显式文件时自动生成本地自签名 cert/key 对；仅供本地/开发使用。 +- `enabled`：在 gateway 监听器处启用 TLS 终止（HTTPS / WSS）（默认：`false`）。 +- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书 / 密钥对；仅适用于本地 / 开发环境。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；请限制权限。 +- `keyPath`：TLS 私钥文件的文件系统路径；请限制其权限。 - `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 ### `gateway.reload` @@ -3149,13 +3149,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制在运行时如何应用配置编辑。 - - `"off"`：忽略实时编辑；变更需要显式重启。 +- `mode`：控制运行时如何应用配置编辑。 + - `"off"`：忽略实时编辑；更改需要显式重启。 - `"restart"`：配置变更时始终重启 gateway 进程。 - - `"hot"`：在进程内应用变更而不重启。 - - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 -- `debounceMs`：应用配置变更前的防抖窗口，单位毫秒（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最大时间，单位毫秒（默认：`300000` = 5 分钟）。 + - `"hot"`：在不重启的情况下于进程内应用变更。 + - `"hybrid"`（默认）：先尝试热重载；如有需要再回退到重启。 +- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待正在进行中的操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- @@ -3195,11 +3195,11 @@ openclaw gateway --port 19001 认证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 拒绝使用查询字符串中的 hook token。 -验证和安全说明： +校验和安全说明： -- `hooks.enabled=true` 要求 `hooks.token` 为非空。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 -- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。 +- `hooks.enabled=true` 需要非空的 `hooks.token`。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 +- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 **端点：** @@ -3211,18 +3211,18 @@ openclaw gateway --port 19001 -- `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 会匹配通用路径的某个负载字段。 -- 类似 `{{messages[0].subject}}` 这样的模板会从负载中读取。 -- `transform` 可指向一个返回 hook action 的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。 +- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 匹配通用路径中的某个负载字段。 +- 类似 `{{messages[0].subject}}` 的模板会从负载中读取值。 +- `transform` 可以指向返回 hook action 的 JS / TS 模块。 + - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 之内（绝对路径和路径穿越都会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。 -- `defaultSessionKey`：对未显式提供 `sessionKey` 的 hook 智能体运行，可选的固定会话键。 +- `defaultSessionKey`：对于未显式设置 `sessionKey` 的 hook 智能体运行，使用的可选固定会话键。 - `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。 +- `allowedSessionKeyPrefixes`：对显式 `sessionKey` 值（请求 + 映射）生效的可选前缀 allowlist，例如 `["hook:"]`。 - `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖本次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `model` 会覆盖该次 hook 运行所使用的 LLM（如果设置了模型目录，则该模型必须被允许）。 @@ -3249,8 +3249,8 @@ openclaw gateway --port 19001 } ``` -- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 +- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。如需禁用，请设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1`。 +- 不要在 Gateway 网关旁边再单独运行一个 `gog gmail watch serve`。 --- @@ -3266,18 +3266,18 @@ openclaw gateway --port 19001 } ``` -- 通过 Gateway 网关端口在 HTTP 下提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： +- 在 Gateway 网关端口下通过 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- 仅本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback bind：canvas 路由和其他 Gateway 网关 HTTP 层面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。 -- Node WebViews 通常不会发送认证 headers；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问发布带节点作用域的 capability URL。 -- Capability URL 绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 -- 会将 live-reload 客户端注入到所提供的 HTML 中。 -- 空目录时会自动创建起始 `index.html`。 -- 也会在 `/__openclaw__/a2ui/` 下提供 A2UI。 -- 变更需要重启 gateway。 -- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 +- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 +- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP surface 一样，需要 Gateway 网关认证（token / password / trusted-proxy）。 +- Node WebView 通常不会发送认证 header；在某个节点完成配对并连接后，Gateway 网关会为 canvas / A2UI 访问公布节点作用域 capability URL。 +- Capability URL 绑定到活动节点的 WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 会向提供的 HTML 中注入 live-reload 客户端。 +- 当目录为空时，会自动创建起始 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 更改需要重启 gateway。 +- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -3309,7 +3309,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，可搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 +会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若需跨网络发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。 设置：`openclaw dns setup --apply`。 @@ -3334,14 +3334,14 @@ openclaw gateway --port 19001 } ``` -- 仅当进程环境中缺少该键时，才会应用内联环境变量。 -- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 -- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 +- 内联环境变量仅会在进程环境中缺少该键时才生效。 +- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖已有变量）。 +- `shellEnv`：从你的登录 shell profile 中导入缺失的预期键名。 - 完整优先级参见 [Environment](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： +你可以在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3352,45 +3352,45 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/空变量会在配置加载时抛出错误。 +- 缺失 / 为空的变量会在配置加载时抛出错误。 - 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 -- 可与 `$include` 配合使用。 +- 支持与 `$include` 一起使用。 --- ## Secrets -Secret refs 是增量式的：明文值仍然可用。 +SecretRef 是增量支持的：明文值仍然可用。 ### `SecretRef` -使用如下对象结构： +使用以下对象形状之一： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -验证规则： +校验规则： - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `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` 会被拒绝） -### 支持的凭证层面 +### 支持的凭证 surface -- 规范矩阵： [SecretRef 凭证层面](/zh-CN/reference/secretref-credential-surface) -- `secrets apply` 作用于受支持的 `openclaw.json` 凭证路径。 -- `auth-profiles.json` refs 也被纳入运行时解析和审计覆盖范围。 +- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) +- `secrets apply` 会作用于受支持的 `openclaw.json` 凭证路径。 +- `auth-profiles.json` 的引用也包含在运行时解析和审计覆盖中。 -### Secret 提供商配置 +### Secret providers 配置 ```json5 { secrets: { providers: { - default: { source: "env" }, // 可选的显式 env 提供商 + default: { source: "env" }, // 可选的显式环境变量 provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3414,17 +3414,17 @@ Secret refs 是增量式的：明文值仍然可用。 说明： -- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 -- 如果配置了 `trustedDirs`，受信任目录检查会作用于解析后的目标路径。 -- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。 -- Secret refs 会在激活时解析到内存快照中，之后请求路径只读取该快照。 -- 激活期间会应用活动层面过滤：已启用层面中的未解析 refs 会导致启动/重载失败，而未激活层面会被跳过并输出诊断信息。 +- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。 +- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin / stdout 传输协议负载。 +- 默认会拒绝符号链接 command 路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会校验其解析后的目标路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会作用于解析后的目标路径。 +- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传入所需变量。 +- Secret 引用会在激活时解析为内存中的快照，之后请求路径只会读取该快照。 +- 激活期间会应用活动 surface 过滤：已启用 surface 上未解析的引用会导致启动 / 重载失败，而非活动 surface 则会被跳过并附带诊断信息。 --- -## 认证存储 +## 凭证存储 ```json5 { @@ -3442,13 +3442,13 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- 按智能体的配置文件存储于 `/auth-profiles.json`。 -- `auth-profiles.json` 对静态凭证模式支持值级 refs（`api_key` 用 `keyRef`，`token` 用 `tokenRef`）。 -- OAuth 模式配置文件（`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)。 +- Secrets 运行时行为，以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3470,19 +3470,20 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `billingBackoffHours`：当某个配置文件因真实计费/余额不足错误而失败时的基础回退小时数 - （默认：`5`）。即使在 `401`/`403` 响应下，只要存在显式计费文本 - 也可能归入这里，但提供商特定的文本匹配器仍会限定在拥有该匹配器的提供商内 - （例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 - 组织/工作区支出上限消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商计费回退小时覆盖。 -- `billingMaxHours`：计费回退指数增长的小时上限（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退分钟数（默认：`10`）。 -- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认：`60`）。 -- `failureWindowHours`：用于回退计数器的滚动窗口小时数（默认：`24`）。 -- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退前，同一提供商 auth-profile 允许轮换的最大次数（默认：`1`）。如 `ModelNotReadyException` 这类提供商繁忙形态会归入这里。 -- `overloadedBackoffMs`：在重试 overloaded 提供商/profile 轮换前的固定延迟（默认：`0`）。 -- `rateLimitedProfileRotations`：对于 rate limit 错误，在切换到模型回退前，同一提供商 auth-profile 允许轮换的最大次数（默认：`1`）。该 rate limit 桶包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 这类提供商形态文本。 +- `billingBackoffHours`：当某个配置文件因真实的 + 计费 / 余额不足错误而失败时，采用的基础退避时长（小时）（默认：`5`）。即使在 `401` / `403` 响应上，显式的计费相关文本 + 也可能落入此路径，但 provider 特定的文本 + 匹配器仍然只作用于拥有它们的 provider（例如 OpenRouter 的 + `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或 + 组织 / workspace 支出上限消息则仍然会进入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按 provider 覆盖的计费退避小时数。 +- `billingMaxHours`：计费退避指数增长的上限小时数（默认：`24`）。 +- `authPermanentBackoffMinutes`：对高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。 +- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认：`60`）。 +- `failureWindowHours`：用于退避计数的滚动时间窗口（小时）（默认：`24`）。 +- `overloadedProfileRotations`：在切换到模型 fallback 之前，同一 provider 因过载错误所允许的最大 auth profile 轮换次数（默认：`1`）。类似 `ModelNotReadyException` 的 provider 忙碌形态会归入此项。 +- `overloadedBackoffMs`：在重试过载 provider / profile 轮换前的固定延迟（毫秒）（默认：`0`）。 +- `rateLimitedProfileRotations`：在切换到模型 fallback 之前，同一 provider 因速率限制错误所允许的最大 auth profile 轮换次数（默认：`1`）。该 rate-limit 类别包含 provider 风格文本，如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -3502,9 +3503,9 @@ Secret refs 是增量式的：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 可使用稳定路径。 -- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。 -- `maxFileBytes`：在抑制写入前允许的最大日志文件大小，单位字节（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- 设置 `logging.file` 可使用固定路径。 +- `consoleLevel` 在使用 `--verbose` 时会提升为 `debug`。 +- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3541,17 +3542,17 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `enabled`：检测输出的总开关（默认：`true`）。 -- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。 -- `stuckSessionWarnMs`：当会话仍处于 processing 状态时，发出卡住会话警告的年龄阈值，单位毫秒。 -- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。 -- `otel.endpoint`：OTel 导出的收集器 URL。 +- `enabled`：仪表输出的主开关（默认：`true`）。 +- `flags`：用于启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。 +- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的年龄阈值（毫秒）。 +- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 +- `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 +- `otel.headers`：随 OTel 导出请求一起发送的额外 HTTP / gRPC 元数据 header。 - `otel.serviceName`：资源属性中的服务名。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 -- `otel.sampleRate`：`0`–`1` 的 trace 采样率。 -- `otel.flushIntervalMs`：定期刷新遥测数据的间隔，单位毫秒。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 +- `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`）。 @@ -3576,12 +3577,12 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `channel`：npm/git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `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`）。 --- @@ -3614,21 +3615,21 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `enabled`：全局 ACP 功能门控（默认：`false`）。 -- `dispatch.enabled`：ACP 会话回合分发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 -- `backend`：默认 ACP 运行时后端 id（必须匹配某个已注册的 ACP 运行时插件）。 -- `defaultAgent`：当生成操作未指定显式目标时，ACP 目标智能体 id 的回退值。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示无额外限制。 -- `maxConcurrentSessions`：最多并发活动 ACP 会话数。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位毫秒。 -- `stream.maxChunkChars`：流式块投影在拆分前允许的最大分块大小。 -- `stream.repeatSuppression`：按回合抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到回合终止事件后再输出。 -- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 回合投影的 assistant 输出最大字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。 -- `stream.tagVisibility`：为流式事件记录标签名到布尔可见性覆盖的映射。 -- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL，单位分钟。 +- `enabled`：全局 ACP 功能开关（默认：`false`）。 +- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可保留 ACP 命令可用，但阻止执行。 +- `backend`：默认 ACP 运行时后端 id（必须与某个已注册 ACP 运行时插件匹配）。 +- `defaultAgent`：当 spawn 未指定显式目标时，作为后备使用的 ACP 目标智能体 id。 +- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id allowlist；为空表示不增加额外限制。 +- `maxConcurrentSessions`：并发活动 ACP 会话的最大数量。 +- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 +- `stream.maxChunkChars`：在拆分流式块投影之前允许的最大块大小。 +- `stream.repeatSuppression`：抑制每轮中重复的状态 / 工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 增量流式传输；`"final_only"` 会缓冲到轮次终结事件后再输出。 +- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前使用的分隔符（默认：`"paragraph"`）。 +- `stream.maxOutputChars`：每个 ACP 轮次投影的 assistant 输出最大字符数。 +- `stream.maxSessionUpdateChars`：投影 ACP 状态 / 更新行的最大字符数。 +- `stream.tagVisibility`：用于流式事件的标签名到布尔可见性覆盖的记录。 +- `runtime.ttlMinutes`：ACP 会话工作进程在符合清理条件前的空闲 TTL（分钟）。 - `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 --- @@ -3645,11 +3646,11 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣/季节性标语。 - - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 -- 如需隐藏整个 banner（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 +- `cli.banner.taglineMode` 控制 banner 标语风格： + - `"random"`（默认）：轮换的有趣 / 季节性标语。 + - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。 +- 若要隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3673,13 +3674,13 @@ Secret refs 是增量式的：明文值仍然可用。 ## 身份 -参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的身份字段。 +请参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的身份字段。 --- ## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可清除未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前会导致校验失败；`openclaw doctor --fix` 可清除未知键）。 @@ -3708,8 +3709,8 @@ Secret refs 是增量式的：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 已弃用的回退，仅用于已存储的 notify:true 作业 - webhookToken: "replace-with-dedicated-token", // 可选的出站 webhook bearer token 认证 + webhook: "https://example.invalid/legacy", // 已弃用：供已存储的 notify:true 作业使用的回退 + webhookToken: "replace-with-dedicated-token", // 可选：用于出站 webhook 认证的 bearer token sessionRetention: "24h", // 时长字符串或 false runLog: { maxBytes: "2mb", // 默认 2_000_000 字节 @@ -3719,11 +3720,11 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `sessionRetention`：从 `sessions.json` 中清理前，保留已完成隔离 cron 运行会话的时长。也控制已归档、已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：触发清理前，每个运行日志文件（`cron/runs/.jsonl`）的最大大小。默认：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。 +- `sessionRetention`：在从 `sessions.json` 清理前，保留已完成隔离 cron 运行会话的时长。也控制已归档删除的 cron transcript 的清理。默认值：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在触发清理前允许的最大大小。默认值：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。 - `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送认证 header。 -- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 +- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍保留 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3739,11 +3740,11 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试的回退延迟数组，单位毫秒（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时类型。 +- `maxAttempts`：一次性作业在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。若省略，则会对所有瞬时错误类型进行重试。 -仅适用于一次性 cron 作业。周期性作业使用单独的失败处理。 +仅适用于一次性 cron 作业。周期性作业使用单独的失败处理方式。 ### `cron.failureAlert` @@ -3761,11 +3762,11 @@ Secret refs 是增量式的：明文值仍然可用。 } ``` -- `enabled`：为 cron 作业启用失败告警（默认：`false`）。 -- `after`：触发告警前所需的连续失败次数（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 -- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则 POST 到已配置的 webhook。 -- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。 +- `enabled`：启用 cron 作业失败告警（默认：`false`）。 +- `after`：在触发告警前允许的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最短间隔（毫秒）（非负整数）。 +- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。 +- `accountId`：用于限定告警投递范围的可选账号或渠道 id。 ### `cron.failureDestination` @@ -3783,48 +3784,48 @@ Secret refs 是增量式的：明文值仍然可用。 ``` - 所有作业共享的 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"`。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。 +- `channel`：用于 announce 投递的渠道覆盖。`"last"` 会复用上次已知的投递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：用于投递的可选账号覆盖。 +- 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 +- 当全局和按作业的失败目标都未设置时，已经通过 `announce` 投递的作业会在失败时回退到其主 announce 目标。 +- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。 +参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [background tasks](/zh-CN/automation/tasks) 进行跟踪。 --- ## 媒体模型模板变量 -在 `tools.media.models[].args` 中展开的模板占位符： +在 `tools.media.models[].args` 中扩展的模板占位符： -| 变量 | 说明 | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | 完整入站消息正文 | -| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 id | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 创建了新会话时为 `"true"` | -| `{{MediaUrl}}` | 入站媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | CLI 条目的已解析媒体提示 | -| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | -| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | +| 变量 | 说明 | +| ------------------ | ------------------------------------- | +| `{{Body}}` | 完整入站消息正文 | +| `{{RawBody}}` | 原始正文（无历史记录 / 发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 新建会话时为 `"true"` | +| `{{MediaUrl}}` | 入站媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image / audio / document / …） | +| `{{Transcript}}` | 音频 transcript | +| `{{Prompt}}` | 为 CLI 条目解析出的媒体提示 | +| `{{MaxChars}}` | 为 CLI 条目解析出的最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| `{{Provider}}` | provider 提示（whatsapp、telegram、discord 等） | --- -## 配置 include（`$include`） +## 配置包含（`$include`） 将配置拆分为多个文件： @@ -3841,13 +3842,13 @@ Secret refs 是增量式的：明文值仍然可用。 **合并行为：** -- 单文件：替换其所在的对象。 +- 单个文件：替换所在的包含对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：在 include 之后合并（覆盖 include 的值）。 -- 嵌套 include：最多支持 10 层深度。 -- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式仅在最终仍解析到该边界内时才允许。 -- 错误：对缺失文件、解析错误和循环 include 提供清晰错误信息。 +- 同级键：会在 includes 之后合并（覆盖包含进来的值）。 +- 嵌套 includes：最多支持 10 层。 +- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。只有在最终仍解析到该边界之内时，才允许使用绝对路径 / `../` 形式。 +- 错误：对于缺失文件、解析错误和循环包含，会给出清晰提示。 --- -_相关： [Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/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/help/faq.md b/docs/zh-CN/help/faq.md index 89e154d14..b5888c64b 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - 回答常见的设置、安装、新手引导或运行时支持问题 - - 在深入调试之前对用户报告的问题进行初步排查 -summary: 关于 OpenClaw 设置、配置和使用的常见问题 + - 在进行更深入的调试之前，对用户报告的问题进行初步分诊 +summary: 有关 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-19T06:50:03Z" + generated_at: "2026-04-19T10:22:57Z" model: gpt-5.4 provider: openai - source_hash: f569fb0412797314a11c41a1bbfa14f5892d2d368544fa67800823a6457000e6 + source_hash: de5a3b612607fc86c883466ff803b82466415644b7211d1c176f87e07641bb97 source_path: help/faq.md workflow: 15 --- # 常见问题 -针对真实环境中的设置提供快速解答和更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。有关运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。有关完整配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +针对真实世界部署场景的快速解答，以及更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整的配置参考，请参阅 [配置](/zh-CN/gateway/configuration)。 ## 如果出了问题，先看最初的六十秒 @@ -25,7 +25,7 @@ x-i18n: openclaw status ``` - 快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 + 快速本地摘要：操作系统 + 更新、Gateway 网关 / 服务可达性、智能体 / 会话、提供商配置 + 运行时问题（当 Gateway 网关 可达时）。 2. **可直接粘贴的报告（可安全分享）** @@ -33,7 +33,7 @@ x-i18n: openclaw status --all ``` - 只读诊断，包含日志尾部（令牌已脱敏）。 + 只读诊断，包含日志尾部（令牌已打码）。 3. **守护进程 + 端口状态** @@ -49,22 +49,22 @@ x-i18n: openclaw status --deep ``` - 运行实时 Gateway 网关健康探测，包括在支持时的渠道探测 - （需要可达的 Gateway 网关）。参见 [Health](/zh-CN/gateway/health)。 + 运行实时 Gateway 网关 健康探测，在支持时也包括渠道探测 + （需要 Gateway 网关 可达）。请参阅 [Health](/zh-CN/gateway/health)。 -5. **查看最新日志尾部** +5. **跟踪最新日志** ```bash openclaw logs --follow ``` - 如果 RPC 不可用，则退回到： + 如果 RPC 不可用，则改用： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 文件日志与服务日志是分开的；请参阅 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 + 文件日志与服务日志是分开的；请参阅 [日志](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 6. **运行 Doctor（修复）** @@ -72,47 +72,48 @@ x-i18n: openclaw doctor ``` - 修复/迁移配置与状态 + 运行健康检查。参见 [Doctor](/zh-CN/gateway/doctor)。 + 修复 / 迁移配置 / 状态，并运行健康检查。请参阅 [Doctor](/zh-CN/gateway/doctor)。 -7. **Gateway 网关快照** +7. **Gateway 网关 快照** ```bash openclaw health --json openclaw health --verbose # 出错时显示目标 URL + 配置路径 ``` - 向正在运行的 Gateway 网关请求完整快照（仅限 WS）。参见 [Health](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关 请求完整快照（仅限 WS）。请参阅 [Health](/zh-CN/gateway/health)。 ## 快速开始和首次运行设置 - - 使用一个可以**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问有效得多， - 因为大多数“我卡住了”的情况都是**本地配置或环境问题**，远程协助者无法直接检查。 + + 使用一个可以**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问要有效得多， + 因为大多数“我卡住了”的情况都是**本地配置或环境问题**， + 远程协助者无法直接检查。 - **Claude Code**： [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**： [https://openai.com/codex/](https://openai.com/codex/) - 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置 - （PATH、服务、权限、认证文件）。通过可修改的（git）安装方式， - 把**完整源代码检出**提供给它们： + 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器级别的 + 设置问题（PATH、服务、权限、认证文件）。通过可修改的（git）安装方式， + 将**完整源码检出**提供给它们： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这会**从 git 检出安装** OpenClaw，这样智能体就可以读取代码 + 文档， - 并针对你当前运行的确切版本进行推理。你之后随时都可以重新运行安装器， - 不带 `--install-method git` 参数来切换回稳定版。 + 这会**从 git 检出**安装 OpenClaw，因此智能体可以读取代码 + 文档， + 并针对你当前运行的确切版本进行分析。之后你随时都可以通过重新运行安装器并去掉 + `--install-method git` 切回稳定版。 - 提示：让智能体先**规划并监督**修复过程（分步骤），然后只执行 - 必要的命令。这样可以让改动更小，也更容易审计。 + 提示：让智能体**规划并监督**修复过程（一步一步），然后只执行 + 必要的命令。这样能让改动保持小而且更容易审计。 如果你发现了真实的 bug 或修复，请提交 GitHub issue 或发送 PR： [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - 请先运行这些命令（在寻求帮助时分享输出）： + 先从这些命令开始（在寻求帮助时分享输出）： ```bash openclaw status @@ -122,30 +123,30 @@ x-i18n: 它们的作用： - - `openclaw status`：快速查看 Gateway 网关/智能体健康状态 + 基本配置。 + - `openclaw status`：Gateway 网关 / 智能体健康状况 + 基本配置的快速快照。 - `openclaw models status`：检查提供商认证 + 模型可用性。 - - `openclaw doctor`：验证并修复常见的配置/状态问题。 + - `openclaw doctor`：验证并修复常见的配置 / 状态问题。 其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、 `openclaw gateway status`、`openclaw health --verbose`。 - 快速调试循环： [如果出了问题，先看最初的六十秒](#如果出了问题先看最初的六十秒)。 - 安装文档： [Install](/zh-CN/install)、[安装器标志](/zh-CN/install/installer)、[Updating](/zh-CN/install/updating)。 + 快速调试循环：[如果出了问题，先看最初的六十秒](#如果出了问题先看最初的六十秒)。 + 安装文档：[安装](/zh-CN/install)、[安装器标志](/zh-CN/install/installer)、[更新](/zh-CN/install/updating)。 - + 常见的 Heartbeat 跳过原因： - - `quiet-hours`：不在已配置的活跃时间窗口内 - - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白/仅标题的脚手架内容 + - `quiet-hours`：不在已配置的 active-hours 时间窗口内 + - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白 / 仅标题的脚手架内容 - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但还没有任何任务间隔到期 - `alerts-disabled`：所有 Heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） - 在任务模式下，只有在真正的 Heartbeat 运行 - 完成后，才会推进到期时间戳。被跳过的运行不会把任务标记为已完成。 + 在任务模式下，只有在真实的 Heartbeat 运行完成之后， + 到期时间戳才会推进。被跳过的运行不会将任务标记为已完成。 - 文档： [Heartbeat](/zh-CN/gateway/heartbeat)、[自动化与任务](/zh-CN/automation)。 + 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[自动化与任务](/zh-CN/automation)。 @@ -157,9 +158,9 @@ x-i18n: openclaw onboard --install-daemon ``` - 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 + 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口上运行 Gateway 网关。 - 从源码开始（贡献者/开发者）： + 从源码开始（贡献者 / 开发者）： ```bash git clone https://github.com/openclaw/openclaw.git @@ -170,32 +171,32 @@ x-i18n: openclaw onboard ``` - 如果你还没有全局安装，请通过 `pnpm openclaw onboard` 运行它。 + 如果你还没有全局安装，可以通过 `pnpm openclaw onboard` 运行它。 - 向导会在新手引导完成后立即用一个干净的（非令牌化）仪表板 URL 打开你的浏览器，并且也会在摘要中打印该链接。请保持该标签页打开；如果它没有自动启动，请在同一台机器上复制/粘贴打印出的 URL。 + 向导会在新手引导结束后立刻用一个干净的（不带令牌的）仪表板 URL 打开你的浏览器，并且也会在摘要中打印该链接。保持这个标签页打开；如果没有自动启动，就在同一台机器上复制 / 粘贴打印出来的 URL。 - + **Localhost（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - - 如果它要求共享密钥认证，请将已配置的令牌或密码粘贴到 Control UI 设置中。 + - 如果它要求 shared-secret 认证，请把已配置的令牌或密码粘贴到 Control UI 设置中。 - 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果尚未配置共享密钥，请使用 `openclaw doctor --generate-gateway-token` 生成一个令牌。 + - 如果还没有配置 shared secret，可通过 `openclaw doctor --generate-gateway-token` 生成一个令牌。 - **不在 localhost 上：** + **不在 localhost：** - - **Tailscale Serve**（推荐）：保持 bind loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头会满足 Control UI/WebSocket 认证要求（无需粘贴共享密钥，前提是你信任 Gateway 网关主机）；HTTP API 仍然需要共享密钥认证，除非你明确使用 private-ingress `none` 或 trusted-proxy HTTP 认证。 - 来自同一客户端的并发 Serve 错误认证尝试，会在失败认证限制器记录前被串行化，因此第二次错误重试可能已经显示 `retry later`。 - - **Tailnet bind**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的共享密钥。 - - **支持身份感知的反向代理**：将 Gateway 网关保留在非 loopback 的 trusted proxy 后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开该代理 URL。 - - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。通过隧道时仍然适用共享密钥认证；如果出现提示，请粘贴已配置的令牌或密码。 + - **Tailscale Serve**（推荐）：保持 bind loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份头就能满足 Control UI / WebSocket 认证（无需粘贴 shared secret，前提是你信任 Gateway 网关 主机）；HTTP API 仍然需要 shared-secret 认证，除非你特意使用 private-ingress `none` 或 trusted-proxy HTTP 认证。 + 来自同一客户端的并发错误 Serve 认证尝试，会在 failed-auth limiter 记录之前先被串行化，因此第二次错误重试可能已经显示 `retry later`。 + - **Tailnet bind**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的 shared secret。 + - **具备身份感知能力的反向代理**：将 Gateway 网关 保持在非 loopback 的 trusted proxy 后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 + - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。shared-secret 认证在隧道上仍然适用；如果有提示，请粘贴已配置的令牌或密码。 - 有关 bind 模式和认证详情，请参阅 [Dashboard](/web/dashboard) 和 [Web surfaces](/web)。 + 有关 bind 模式和认证细节，请参阅 [仪表板](/web/dashboard) 和 [Web 界面](/web)。 @@ -205,55 +206,55 @@ x-i18n: - `approvals.exec`：将审批提示转发到聊天目标 - `channels..execApprovals`：让该渠道作为 exec 审批的原生审批客户端 - 主机 exec 策略仍然是真正的审批门槛。聊天配置只控制审批 - 提示出现在哪里，以及人们如何进行响应。 + 主机的 exec 策略仍然是真正的审批关卡。聊天配置只控制审批 + 提示出现在哪里，以及人们如何作答。 - 在大多数设置中，你**不**需要同时启用两者： + 在大多数部署中，你**不**需要两者都配置： - - 如果聊天本身已经支持命令和回复，那么同一聊天中的 `/approve` 会通过共享路径工作。 - - 如果受支持的原生渠道可以安全推断审批人，当 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用“私信优先”的原生审批。 - - 当提供原生审批卡片/按钮时，该原生 UI 是主要路径；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，智能体才应包含手动 `/approve` 命令。 - - 仅当提示还必须转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 - - 仅当你明确希望将审批提示回发到原始房间/话题中时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 - - 插件审批则是另一套逻辑：它们默认使用同一聊天中的 `/approve`、可选的 `approvals.plugin` 转发，并且只有部分原生渠道还会在其基础上保留原生插件审批处理。 + - 如果聊天已经支持命令和回复，同一聊天中的 `/approve` 会通过共享路径生效。 + - 如果受支持的原生渠道可以安全推断审批者，当 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用私信优先的原生审批。 + - 当有原生审批卡片 / 按钮可用时，该原生 UI 是主要路径；只有当工具结果表明聊天审批不可用，或者手动审批是唯一可行路径时，智能体才应包含手动 `/approve` 命令。 + - 只有当提示也必须被转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 + - 只有当你明确希望将审批提示发回原始房间 / 主题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 + - 插件审批则是另一套机制：默认使用同一聊天中的 `/approve`，可选 `approvals.plugin` 转发，而且只有部分原生渠道会在此基础上保留原生插件审批处理。 - 简短来说：转发用于路由，原生客户端配置用于更丰富的渠道特定 UX。 - 参见 [Exec Approvals](/zh-CN/tools/exec-approvals)。 + 简短来说：转发用于路由，原生客户端配置用于更丰富的渠道专属 UX。 + 请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 - 需要 Node **>= 22**。推荐使用 `pnpm`。**不推荐**为 Gateway 网关使用 Bun。 + 需要 Node **>= 22**。推荐使用 `pnpm`。不推荐将 Bun 用于 Gateway 网关。 - 可以。Gateway 网关非常轻量——文档列出了个人使用所需的配置大约为 **512MB-1GB RAM**、**1 个核心** 和 **500MB** + 可以。Gateway 网关 很轻量——文档列出个人使用只需 **512MB-1GB RAM**、**1 个核心** 和大约 **500MB** 磁盘空间，并说明 **Raspberry Pi 4 可以运行它**。 - 如果你想有更多余量（日志、媒体、其他服务），**推荐 2GB**，但这 + 如果你想要更多余量（日志、媒体、其他服务），建议 **2GB**，但这 不是硬性最低要求。 - 提示：小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑/手机上配对 **nodes**，用于 - 本地屏幕/摄像头/canvas 或命令执行。参见 [Nodes](/zh-CN/nodes)。 + 提示：小型 Pi / VPS 可以托管 Gateway 网关，而你可以在笔记本电脑 / 手机上配对 **节点**， + 用于本地屏幕 / 摄像头 / canvas 或命令执行。请参阅 [Nodes](/zh-CN/nodes)。 - 简短来说：可以运行，但要预期会有一些粗糙之处。 + 简短来说：可以运行，但要预期会有一些棘手边缘情况。 - 使用 **64 位** 操作系统，并保持 Node >= 22。 - - 优先选择**可修改的（git）安装**，这样你可以查看日志并快速更新。 - - 一开始不要启用渠道/Skills，然后逐个添加。 - - 如果你遇到奇怪的二进制问题，通常是 **ARM 兼容性**问题。 + - 优先使用**可修改的（git）安装方式**，这样你可以查看日志并快速更新。 + - 先不要启用渠道 / Skills，然后逐个添加。 + - 如果你遇到奇怪的二进制问题，通常是 **ARM 兼容性** 问题。 - 文档： [Linux](/zh-CN/platforms/linux)、[Install](/zh-CN/install)。 + 文档：[Linux](/zh-CN/platforms/linux)、[安装](/zh-CN/install)。 - - 该界面依赖 Gateway 网关可达且已认证。TUI 还会在首次 hatch 时自动发送 - “Wake up, my friend!”。如果你看到这一行却**没有回复**， - 且 token 一直为 0，说明智能体根本没有运行。 + + 这个界面依赖于 Gateway 网关 可达且已完成认证。TUI 也会在首次 hatch 时自动发送 + “Wake up, my friend!”。如果你看到这行文字却**没有回复**， + 且令牌仍然是 0，那么智能体根本没有运行。 1. 重启 Gateway 网关： @@ -269,83 +270,83 @@ x-i18n: openclaw logs --follow ``` - 3. 如果仍然卡住，请运行： + 3. 如果仍然卡住，运行： ```bash openclaw doctor ``` - 如果 Gateway 网关是远程的，请确认隧道/Tailscale 连接已建立，并且 UI - 指向的是正确的 Gateway 网关。参见 [Remote access](/zh-CN/gateway/remote)。 + 如果 Gateway 网关 是远程的，请确保隧道 / Tailscale 连接已建立，并且 UI + 指向的是正确的 Gateway 网关。请参阅 [远程访问](/zh-CN/gateway/remote)。 - - 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor 即可。这样 - 可以让你的机器人“完全保持不变”（记忆、会话历史、认证和渠道 + + 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这样 + 就能让你的机器人“完全保持原样”（memory、会话历史、认证以及渠道 状态），前提是你复制了**这两个**位置： 1. 在新机器上安装 OpenClaw。 2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 - 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。 + 4. 运行 `openclaw doctor` 并重启 Gateway 网关 服务。 - 这会保留配置、认证配置文件、WhatsApp 凭证、会话和记忆。如果你处于 - 远程模式，请记住会话存储和工作区归 Gateway 网关主机所有。 + 这会保留配置、认证配置文件、WhatsApp 凭据、会话和 memory。如果你处于 + 远程模式，请记住会话存储和工作区归 Gateway 网关 主机所有。 - **重要：**如果你只是把工作区提交/推送到 GitHub，你备份的 - 是**记忆 + 引导文件**，但**不是**会话历史或认证。它们位于 + **重要：** 如果你只是把工作区提交 / 推送到 GitHub，你备份的将是 + **memory + bootstrap 文件**，但**不包括**会话历史或认证。那些内容位于 `~/.openclaw/` 下（例如 `~/.openclaw/agents//sessions/`）。 - 相关内容： [Migrating](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 + 相关内容：[迁移](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 [智能体工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 [远程模式](/zh-CN/gateway/remote)。 - + 查看 GitHub 更新日志： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 最新条目位于顶部。如果顶部部分标记为 **Unreleased**，那么下一个带日期的 + 最新条目位于顶部。如果顶部部分标记为 **Unreleased**，则下一个带日期的 部分就是最新发布的版本。条目按 **Highlights**、**Changes** 和 - **Fixes** 分组（必要时还会有文档/其他部分）。 + **Fixes** 分组（需要时还会有 docs / 其他部分）。 - 某些 Comcast/Xfinity 连接会因 Xfinity - Advanced Security 而错误地屏蔽 `docs.openclaw.ai`。请禁用它或将 `docs.openclaw.ai` 加入允许列表，然后重试。 - 也请通过这里的入口帮助我们解除屏蔽： [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 + 某些 Comcast / Xfinity 连接会因为 Xfinity + Advanced Security 而错误地屏蔽 `docs.openclaw.ai`。请将其禁用，或把 `docs.openclaw.ai` 加入允许列表，然后重试。 + 也请通过这里反馈，帮助我们解除拦截： [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 - 如果你仍然无法访问该站点，文档也镜像在 GitHub 上： + 如果你仍然无法访问该站点，文档在 GitHub 上有镜像： [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - **Stable** 和 **beta** 是 **npm dist-tags**，而不是独立的代码线： + **Stable** 和 **beta** 是 **npm dist-tags**，不是独立的代码线： - `latest` = stable - `beta` = 用于测试的早期构建 - 通常，稳定版会先发布到 **beta**，然后通过一个显式的 - 晋升步骤把同一个版本移动到 `latest`。维护者在需要时也可以 - 直接发布到 `latest`。这就是为什么 beta 和 stable 在晋升后可能会 + 通常，稳定版本会先发布到 **beta**，然后通过一个明确的 + 提升步骤把同一个版本移动到 `latest`。维护者在需要时也可以 + 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升之后可以 指向**同一个版本**。 查看变更内容： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 有关安装单行命令以及 beta 与 dev 的区别，请参见下方的折叠项。 + 关于安装单行命令以及 beta 和 dev 的区别，请参阅下面的折叠项。 - **Beta** 是 npm dist-tag `beta`（在晋升后可能与 `latest` 相同）。 - **Dev** 是 `main` 的移动头部（git）；发布时使用 npm dist-tag `dev`。 + **Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 相同）。 + **Dev** 是 `main` 的滚动最新版本（git）；发布时使用 npm dist-tag `dev`。 - 单行命令（macOS/Linux）： + 单行命令（macOS / Linux）： ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta @@ -358,11 +359,11 @@ x-i18n: Windows 安装器（PowerShell）： [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - 更多细节： [开发渠道](/zh-CN/install/development-channels) 和 [安装器标志](/zh-CN/install/installer)。 + 更多细节：[开发渠道](/zh-CN/install/development-channels) 和 [安装器标志](/zh-CN/install/installer)。 - + 有两种方式： 1. **Dev 渠道（git 检出）：** @@ -371,9 +372,9 @@ x-i18n: openclaw update --channel dev ``` - 这会切换到 `main` 分支并从源码更新。 + 这会切换到 `main` 分支，并从源码更新。 - 2. **可修改安装（通过安装站点）：** + 2. **可修改安装（从安装站点）：** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -381,7 +382,7 @@ x-i18n: 这样你会得到一个可本地编辑的仓库，然后可以通过 git 更新。 - 如果你更喜欢手动进行一次干净的克隆，请使用： + 如果你更喜欢手动使用一个干净的克隆，请使用： ```bash git clone https://github.com/openclaw/openclaw.git @@ -390,8 +391,8 @@ x-i18n: pnpm build ``` - 文档： [Update](/cli/update)、[开发渠道](/zh-CN/install/development-channels)、 - [Install](/zh-CN/install)。 + 文档：[更新](/cli/update)、[开发渠道](/zh-CN/install/development-channels)、 + [安装](/zh-CN/install)。 @@ -399,21 +400,21 @@ x-i18n: 大致参考： - **安装：** 2-5 分钟 - - **新手引导：** 5-15 分钟，取决于你配置了多少渠道/模型 + - **新手引导：** 5-15 分钟，取决于你配置了多少渠道 / 模型 - 如果卡住了，请参阅 [安装器卡住了](#quick-start-and-first-run-setup) - 和 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 + 如果卡住，请使用 [安装器卡住了](#quick-start-and-first-run-setup) + 以及 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 - 重新运行安装器，并开启**详细输出**： + 使用**详细输出**重新运行安装器： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - 使用详细输出安装 beta： + 带详细输出的 beta 安装： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -434,44 +435,44 @@ x-i18n: Set-PSDebug -Trace 0 ``` - 更多选项： [安装器标志](/zh-CN/install/installer)。 + 更多选项：[安装器标志](/zh-CN/install/installer)。 两个常见的 Windows 问题： - **1）npm 错误 spawn git / git not found** + **1) npm 错误 spawn git / git not found** - - 安装 **Git for Windows**，并确保 `git` 已加入你的 PATH。 + - 安装 **Git for Windows**，并确保 `git` 在你的 PATH 中。 - 关闭并重新打开 PowerShell，然后重新运行安装器。 - **2）安装后 openclaw is not recognized** + **2) 安装后提示 openclaw is not recognized** - - 你的 npm 全局 bin 目录没有加入 PATH。 + - 你的 npm 全局 bin 文件夹不在 PATH 中。 - 检查路径： ```powershell npm config get prefix ``` - - 将该目录添加到你的用户 PATH 中（Windows 上不需要 `\bin` 后缀；在大多数系统中它是 `%AppData%\npm`）。 + - 将该目录添加到你的用户 PATH 中（Windows 上不需要 `\bin` 后缀；在大多数系统上它是 `%AppData%\npm`）。 - 更新 PATH 后，关闭并重新打开 PowerShell。 - 如果你想获得最顺畅的 Windows 设置体验，请使用 **WSL2** 而不是原生 Windows。 - 文档： [Windows](/zh-CN/platforms/windows)。 + 如果你想要最顺畅的 Windows 设置体验，请使用 **WSL2**，而不是原生 Windows。 + 文档：[Windows](/zh-CN/platforms/windows)。 - + 这通常是原生 Windows shell 中控制台代码页不匹配导致的。 症状： - - `system.run`/`exec` 输出中的中文显示为乱码 - - 相同命令在另一个终端配置中显示正常 + - `system.run` / `exec` 输出中的中文显示为乱码 + - 同一个命令在另一个终端配置中看起来正常 - 在 PowerShell 中的快速解决方法： + PowerShell 中的快速解决方法： ```powershell chcp 65001 @@ -480,72 +481,72 @@ x-i18n: $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - 然后重启 Gateway 网关并重试你的命令： + 然后重启 Gateway 网关 并重试你的命令： ```powershell openclaw gateway restart ``` - 如果你在最新版本 OpenClaw 上仍然可以复现这个问题，请在这里跟踪/报告： + 如果你在最新版本的 OpenClaw 上仍然能复现这个问题，请在这里跟踪 / 报告： - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - 使用**可修改的（git）安装**，这样你本地就有完整的源码和文档，然后 - 在_那个目录中_向你的机器人（或 Claude/Codex）提问，这样它就可以读取仓库并准确回答。 + + 使用**可修改的（git）安装方式**，这样你就能在本地拥有完整的源码和文档，然后在 + _该文件夹中_ 向你的机器人（或 Claude / Codex）提问，这样它就能读取仓库并给出准确回答。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 更多细节： [Install](/zh-CN/install) 和 [安装器标志](/zh-CN/install/installer)。 + 更多细节：[安装](/zh-CN/install) 和 [安装器标志](/zh-CN/install/installer)。 简短回答：按照 Linux 指南操作，然后运行新手引导。 - - Linux 快速路径 + 服务安装： [Linux](/zh-CN/platforms/linux)。 - - 完整演练： [入门指南](/zh-CN/start/getting-started)。 - - 安装 + 更新： [安装与更新](/zh-CN/install/updating)。 + - Linux 快速路径 + 服务安装：[Linux](/zh-CN/platforms/linux)。 + - 完整演练：[入门指南](/zh-CN/start/getting-started)。 + - 安装器 + 更新：[安装与更新](/zh-CN/install/updating)。 - 任何 Linux VPS 都可以使用。在服务器上安装，然后通过 SSH/Tailscale 访问 Gateway 网关。 + 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH / Tailscale 访问 Gateway 网关。 - 指南： [exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。 - 远程访问： [Gateway remote](/zh-CN/gateway/remote)。 + 指南：[exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。 + 远程访问：[Gateway 网关 远程访问](/zh-CN/gateway/remote)。 - - 我们维护了一个**托管中心**，汇总了常见提供商。选择一个并按照指南操作： + + 我们维护了一个**托管中心**，涵盖常见提供商。选择一个并按照指南操作： - [VPS 托管](/zh-CN/vps)（所有提供商集中在一处） - [Fly.io](/zh-CN/install/fly) - [Hetzner](/zh-CN/install/hetzner) - [exe.dev](/zh-CN/install/exe-dev) - 它在云端的工作方式是：**Gateway 网关运行在服务器上**，而你通过 Control UI（或 Tailscale/SSH） - 从你的笔记本电脑/手机访问它。你的状态 + 工作区 - 都保存在服务器上，因此应将主机视为事实来源并做好备份。 + 它在云端的工作方式是：**Gateway 网关 运行在服务器上**，而你通过 + Control UI（或 Tailscale / SSH）从笔记本电脑 / 手机访问它。你的状态 + 工作区 + 都保存在服务器上，因此请把主机视为真实来源并做好备份。 - 你可以将 **nodes**（Mac/iOS/Android/无头）与这个云端 Gateway 网关配对，以访问 - 本地屏幕/摄像头/canvas，或在你的笔记本电脑上运行命令，同时保持 - Gateway 网关在云端。 + 你可以将**节点**（Mac / iOS / Android / 无头设备）配对到该云端 Gateway 网关，以便访问 + 本地屏幕 / 摄像头 / canvas，或在你的笔记本电脑上运行命令，同时保持 + Gateway 网关 在云端。 - 中心： [Platforms](/zh-CN/platforms)。远程访问： [Gateway remote](/zh-CN/gateway/remote)。 - Nodes： [Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 + 中心页：[平台](/zh-CN/platforms)。远程访问：[Gateway 网关 远程访问](/zh-CN/gateway/remote)。 + 节点：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 - + 简短回答：**可以，但不推荐**。更新流程可能会重启 - Gateway 网关（这会断开当前活动会话），可能需要干净的 git 检出，并且 - 可能会要求确认。更安全的做法是：由操作员在 shell 中执行更新。 + Gateway 网关（这会断开当前会话），可能需要一个干净的 git 检出，并且 + 可能会要求确认。更安全的做法是：由操作员在 shell 中运行更新。 使用 CLI： @@ -557,53 +558,53 @@ x-i18n: openclaw update --no-restart ``` - 如果你必须从智能体自动化执行： + 如果你必须通过智能体自动化： ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - 文档： [Update](/cli/update)、[Updating](/zh-CN/install/updating)。 + 文档：[更新](/cli/update)、[更新中](/zh-CN/install/updating)。 `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成： - - **模型/认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） - - **工作区**位置 + 引导文件 - - **Gateway 网关设置**（bind/port/auth/tailscale） + - **模型 / 认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） + - **工作区**位置 + bootstrap 文件 + - **Gateway 网关 设置**（bind / port / auth / tailscale） - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及像 QQ Bot 这样的内置渠道插件） - - **守护进程安装**（macOS 上是 LaunchAgent；Linux/WSL2 上是 systemd user unit） + - **守护进程安装**（macOS 上为 LaunchAgent；Linux / WSL2 上为 systemd 用户单元） - **健康检查** 和 **Skills** 选择 如果你配置的模型未知或缺少认证，它还会发出警告。 - - 不需要。你可以使用 **API 密钥**（Anthropic/OpenAI/其他）运行 OpenClaw，或者使用 - **仅本地模型**，这样你的数据会保留在你的设备上。订阅（Claude - Pro/Max 或 OpenAI Codex）只是对这些提供商进行认证的可选方式。 + + 不需要。你可以使用 **API 密钥**（Anthropic / OpenAI / 其他） + 运行 OpenClaw，也可以使用**纯本地模型**，这样你的数据就保留在你的设备上。订阅（Claude + Pro / Max 或 OpenAI Codex）只是为这些提供商进行认证的可选方式。 - 对于 OpenClaw 中的 Anthropic，实际划分是： + 对于 OpenClaw 中的 Anthropic，实际上的区分是： - - **Anthropic API key**：常规 Anthropic API 计费 - - **Claude CLI / OpenClaw 中的 Claude 订阅认证**：Anthropic 工作人员 - 告诉我们，这种用法再次被允许，除非 Anthropic 发布新的 - 政策，否则 OpenClaw 会将 `claude -p` - 的使用视为该集成已获许可 + - **Anthropic API 密钥**：普通 Anthropic API 计费 + - **OpenClaw 中的 Claude CLI / Claude 订阅认证**：Anthropic 员工 + 告诉我们这种用法再次被允许，OpenClaw 正将 `claude -p` + 的使用视为该集成的受认可用法，除非 Anthropic 发布新的 + 政策 - 对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是更 - 可预测的设置方式。OpenAI Codex OAuth 已明确支持 - 用于 OpenClaw 这类外部工具。 + 对于长期运行的 Gateway 网关 主机，Anthropic API 密钥仍然是更 + 可预测的设置方式。OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部 + 工具。 - OpenClaw 还支持其他托管式订阅选项，包括 + OpenClaw 还支持其他托管的订阅式选项，包括 **Qwen Cloud Coding Plan**、**MiniMax Coding Plan** 和 **Z.AI / GLM Coding Plan**。 - 文档： [Anthropic](/zh-CN/providers/anthropic)、[OpenAI](/zh-CN/providers/openai)、 + 文档：[Anthropic](/zh-CN/providers/anthropic)、[OpenAI](/zh-CN/providers/openai)、 [Qwen Cloud](/zh-CN/providers/qwen)、 [MiniMax](/zh-CN/providers/minimax)、[GLM Models](/zh-CN/providers/glm)、 [本地模型](/zh-CN/gateway/local-models)、[模型](/zh-CN/concepts/models)。 @@ -613,86 +614,86 @@ x-i18n: 可以。 - Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 - 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为该集成已获许可的 - 用法。如果你希望获得最可预测的服务器端设置，请改用 Anthropic API 密钥。 + Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 + 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为该集成中受认可的 + 用法。如果你想要最可预测的服务端部署方式，请改用 Anthropic API 密钥。 支持。 - Anthropic 工作人员告诉我们，这种用法再次被允许，因此 OpenClaw 将 - Claude CLI 复用和 `claude -p` 的使用视为该集成已获许可的 - 用法，除非 Anthropic 发布新的政策。 + Anthropic 员工告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 + Claude CLI 复用和 `claude -p` 的使用视为该集成中受认可的 + 用法。 - Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径可用，但 OpenClaw 现在在可用时更偏好 Claude CLI 复用和 `claude -p`。 + Anthropic setup-token 仍然作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 对于生产环境或多用户工作负载，Anthropic API 密钥认证仍然是 - 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他订阅式托管 + 更安全、更可预测的选择。如果你想了解 OpenClaw 中其他托管的订阅式 选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model - Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM + Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 以及 [GLM Models](/zh-CN/providers/glm)。 -这表示你当前窗口内的 **Anthropic 配额/速率限制** 已耗尽。如果你 -使用 **Claude CLI**，请等待窗口重置或升级你的套餐。如果你 -使用 **Anthropic API key**，请检查 Anthropic Console -中的使用情况/计费，并在需要时提高限制。 +这意味着你当前时间窗口内的 **Anthropic 配额 / 速率限制** 已经耗尽。如果你 +使用 **Claude CLI**，请等待时间窗口重置或升级你的套餐。如果你 +使用的是 **Anthropic API 密钥**，请检查 Anthropic Console +中的使用量 / 计费情况，并在需要时提高限制。 - 如果消息明确是： - `Extra usage is required for long context requests`，说明该请求正尝试使用 - Anthropic 的 1M 上下文 beta（`context1m: true`）。这仅在你的 - 凭证符合长上下文计费条件时才有效（API 密钥计费，或 + 如果消息具体是： + `Extra usage is required for long context requests`，这表示请求正在尝试使用 + Anthropic 的 1M 上下文 beta（`context1m: true`）。这只有在你的 + 凭据符合长上下文计费资格时才有效（API 密钥计费，或 启用了 Extra Usage 的 OpenClaw Claude 登录路径）。 - 提示：设置一个**后备模型**，这样在某个提供商触发速率限制时，OpenClaw 仍可继续回复。 - 参见 [Models](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 + 提示：设置一个**回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍然可以继续回复。 + 请参阅 [模型](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 - 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。存在 AWS 环境标记时，OpenClaw 可以自动发现支持流式传输/文本的 Bedrock 目录，并将其合并为隐式 `amazon-bedrock` 提供商；否则你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled`，或添加手动提供商条目。参见 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你更喜欢托管式密钥流程，在 Bedrock 前面加一个兼容 OpenAI 的代理仍然是有效选项。 + 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。当存在 AWS 环境变量标记时，OpenClaw 可以自动发现 Bedrock 的流式传输 / 文本模型目录，并将其作为隐式 `amazon-bedrock` 提供商合并；否则，你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled` 或添加手动提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是一个可行选项。 - OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.4`。参见 [模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 + OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适用时将默认模型设置为 `openai-codex/gpt-5.4`。请参阅 [模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 - OpenClaw 将这两条路径分开处理： + OpenClaw 将这两种路径分开处理： - - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth + - `openai-codex/gpt-5.4` = ChatGPT / Codex OAuth - `openai/gpt-5.4` = 直接 OpenAI Platform API - 在 OpenClaw 中，ChatGPT/Codex 登录连接到的是 `openai-codex/*` 路径， + 在 OpenClaw 中，ChatGPT / Codex 登录连接的是 `openai-codex/*` 路径， 而不是直接的 `openai/*` 路径。如果你想在 OpenClaw 中使用直接 API 路径，请设置 `OPENAI_API_KEY`（或等效的 OpenAI 提供商配置）。 - 如果你想在 OpenClaw 中使用 ChatGPT/Codex 登录，请使用 `openai-codex/*`。 + 如果你想在 OpenClaw 中使用 ChatGPT / Codex 登录，请使用 `openai-codex/*`。 - + `openai-codex/*` 使用 Codex OAuth 路径，其可用配额窗口由 - OpenAI 管理，并取决于套餐。实际中，这些限制可能与 - ChatGPT 网站/应用的体验不同，即使二者绑定的是同一个账户。 + OpenAI 管理，并取决于你的套餐。实际上，即使两者绑定的是同一个账户， + 这些限制也可能与 ChatGPT 网站 / 应用中的体验不同。 OpenClaw 可以在 - `openclaw models status` 中显示当前可见的提供商使用量/配额窗口，但它不会凭空创建或规范化 ChatGPT 网页版的 - 权益，使其变成直接 API 访问。如果你想使用直接 OpenAI Platform - 计费/限额路径，请通过 API 密钥使用 `openai/*`。 + `openclaw models status` 中显示当前可见的提供商使用量 / 配额窗口，但它不会虚构或规范化 ChatGPT 网页版 + 权益来变成直接 API 访问。如果你想使用直接的 OpenAI Platform + 计费 / 限额路径，请使用带 API 密钥的 `openai/*`。 支持。OpenClaw 完全支持 **OpenAI Code（Codex）订阅 OAuth**。 - OpenAI 明确允许在 OpenClaw 这样的外部工具/工作流中 - 使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。 + OpenAI 明确允许在 OpenClaw 这样的外部工具 / 工作流中 + 使用订阅 OAuth。新手引导也可以为你运行 OAuth 流程。 - 参见 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 + 请参阅 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 @@ -701,105 +702,106 @@ x-i18n: 步骤： - 1. 在本地安装 Gemini CLI，确保 `gemini` 已在 `PATH` 中 + 1. 在本地安装 Gemini CLI，使 `gemini` 位于 `PATH` 中 - Homebrew：`brew install gemini-cli` - npm：`npm install -g @google/gemini-cli` 2. 启用插件：`openclaw plugins enable google` 3. 登录：`openclaw models auth login --provider google-gemini-cli --set-default` 4. 登录后的默认模型：`google-gemini-cli/gemini-3-flash-preview` - 5. 如果请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` + 5. 如果请求失败，请在 Gateway 网关 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` - 这会将 OAuth token 存储在 Gateway 网关主机上的认证配置文件中。详情请参阅： [模型提供商](/zh-CN/concepts/model-providers)。 + 这会将 OAuth 令牌存储在 Gateway 网关 主机上的认证配置文件中。详情请参阅：[模型提供商](/zh-CN/concepts/model-providers)。 - 通常不适合。OpenClaw 需要大上下文 + 强安全性；小卡会截断并泄漏。如果你确实要用，请在本地运行你能运行的**最大**模型构建（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加 prompt injection 风险——参见 [Security](/zh-CN/gateway/security)。 + 通常不适合。OpenClaw 需要大上下文 + 强安全性；小模型会截断并泄露内容。如果你必须使用，请在本地运行你能承载的**最大**模型构建（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小 / 量化后的模型会增加 prompt injection 风险——请参阅 [安全](/zh-CN/gateway/security)。 - 选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些选项一起列出，这样在遵守所选区域提供商限制的同时，仍可保留后备能力。 + 选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic / OpenAI 与这些选项一同列出，这样在遵守你所选区域提供商限制的同时，回退方案仍可用。 - 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人 - 会买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的设备也可以。 + 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 可通过 WSL2 运行）。Mac mini 是可选的——有些人 + 会买一台作为始终在线的主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的机器也可以。 - 只有在使用**仅限 macOS 的工具**时，你才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器运行在任意 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS node。 + 你只在**需要仅限 macOS 的工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器运行在任意 Mac 上，而 Gateway 网关 可以运行在 Linux 或其他地方。如果你还想使用其他仅限 macOS 的工具，可以在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。 - 文档： [BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、[Mac 远程模式](/zh-CN/platforms/mac/remote)。 + 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、[Mac 远程模式](/zh-CN/platforms/mac/remote)。 - - 你需要**某台已登录 Messages 的 macOS 设备**。它**不**一定非得是 Mac mini—— - 任意 Mac 都可以。对于 iMessage，**请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 + + 你需要**某台已登录 Messages 的 macOS 设备**。它**不必**是 Mac mini—— + 任何 Mac 都可以。对于 iMessage，**请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关 可以运行在 Linux 或其他地方。 - 常见设置： + 常见部署方式： - - 在 Linux/VPS 上运行 Gateway 网关，并在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 - - 如果你想要最简单的单机设置，也可以把所有内容都运行在 Mac 上。 + - 在 Linux / VPS 上运行 Gateway 网关，并在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 + - 如果你想要最简单的单机部署，也可以把所有内容都运行在这台 Mac 上。 - 文档： [BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 + 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 [Mac 远程模式](/zh-CN/platforms/mac/remote)。 - + 可以。**Mac mini 可以运行 Gateway 网关**，而你的 MacBook Pro 可以作为 - **node**（配套设备）连接。Nodes 不运行 Gateway 网关——它们提供额外 - 的能力，例如该设备上的 screen/camera/canvas 和 `system.run`。 + **节点**（配套设备）连接。节点不运行 Gateway 网关——它们提供额外的 + 能力，例如该设备上的屏幕 / 摄像头 / canvas 和 `system.run`。 常见模式： - - Gateway 网关运行在 Mac mini 上（常开）。 - - MacBook Pro 运行 macOS 应用或 node host，并与 Gateway 网关配对。 + - Gateway 网关 运行在 Mac mini 上（始终在线）。 + - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关 配对。 - 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。 - 文档： [Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 + 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 - **不推荐**使用 Bun。我们观察到一些运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 + **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 对于稳定的 Gateway 网关，请使用 **Node**。 - 如果你仍想试验 Bun，请在非生产 Gateway 网关上进行， - 并且不要使用 WhatsApp/Telegram。 + 如果你仍然想尝试 Bun，请在非生产环境的 Gateway 网关 上使用， + 并且不要启用 WhatsApp / Telegram。 - `channels.telegram.allowFrom` 填的是**真人发送者的 Telegram 用户 ID**（数字），不是机器人用户名。 + `channels.telegram.allowFrom` 是**真人发送者的 Telegram 用户 ID**（数字）。 + 它不是机器人用户名。 - 新手引导接受 `@username` 输入并将其解析为数字 ID，但 OpenClaw 授权只使用数字 ID。 + 新手引导接受 `@username` 输入，并会将其解析为数字 ID，但 OpenClaw 的授权只使用数字 ID。 - 更安全的方式（无需第三方机器人）： + 更安全的方式（不使用第三方机器人）： - - 给你的机器人发私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。 + - 向你的机器人发送私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。 官方 Bot API： - - 给你的机器人发私信，然后调用 `https://api.telegram.org/bot/getUpdates` 并读取 `message.from.id`。 + - 向你的机器人发送私信，然后调用 `https://api.telegram.org/bot/getUpdates` 并读取 `message.from.id`。 - 第三方方式（隐私性较差）： + 第三方方式（隐私性较低）： - - 给 `@userinfobot` 或 `@getidsbot` 发私信。 + - 向 `@userinfobot` 或 `@getidsbot` 发送私信。 - 参见 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 + 请参阅 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 - 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账号**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账号是全局的。参见 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 + 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会拥有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账号**，而且私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）在每个 WhatsApp 账号范围内是全局的。请参阅 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 - - 可以。使用多智能体路由：为每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peers）绑定到各个智能体。示例配置见 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [模型](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 + + 可以。使用多智能体路由：为每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peer）绑定到各自的智能体。示例配置见 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [模型](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。 - - 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： + + 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置如下： ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -808,24 +810,24 @@ x-i18n: brew install ``` - 如果你通过 systemd 运行 OpenClaw，请确保服务 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew prefix），以便 `brew` 安装的工具能在非登录 shell 中被解析。 - 较新的构建还会在 Linux systemd 服务中预先添加常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在已设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 + 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样在非登录 shell 中也能解析 `brew` 安装的工具。 + 最近的构建也会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在已设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 - - - **可修改的（git）安装：** 完整源代码检出，可编辑，最适合贡献者。 - 你需要在本地运行构建，也可以修补代码/文档。 - - **npm install：** 全局 CLI 安装，不包含仓库，最适合“直接运行”。 + + - **可修改的（git）安装：** 完整源码检出、可编辑，最适合贡献者。 + 你可以在本地运行构建并修改代码 / 文档。 + - **npm install：** 全局 CLI 安装，没有仓库，最适合“只想直接运行”。 更新来自 npm dist-tags。 - 文档： [入门指南](/zh-CN/start/getting-started)、[Updating](/zh-CN/install/updating)。 + 文档：[入门指南](/zh-CN/start/getting-started)、[更新中](/zh-CN/install/updating)。 - - 可以。安装另一种形式后，再运行 Doctor，让 Gateway 网关服务指向新的入口点。 - 这**不会删除你的数据**——它只会更改 OpenClaw 代码的安装方式。你的状态 + + 可以。安装另一种形式后，运行 Doctor，让 Gateway 网关 服务指向新的入口点。 + 这**不会删除你的数据**——它只会更改 OpenClaw 的代码安装方式。你的状态 （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都会保持不变。 从 npm 切换到 git： @@ -847,152 +849,153 @@ x-i18n: openclaw gateway restart ``` - Doctor 会检测 Gateway 网关服务入口点不匹配的问题，并提供将服务配置重写为与当前安装一致的选项（在自动化中使用 `--repair`）。 + Doctor 会检测 Gateway 网关 服务入口点不匹配，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 `--repair`）。 - 备份建议：参见 [备份策略](#where-things-live-on-disk)。 + 备份提示：请参阅 [备份策略](#where-things-live-on-disk)。 - - 简短回答：**如果你想要 24/7 可靠性，请使用 VPS**。如果你想要 - 最低的使用门槛，并且可以接受休眠/重启，那么就在本地运行。 + + 简短回答：**如果你想要 24/7 的可靠性，就使用 VPS**。如果你想要 + 最低的使用门槛，并且可以接受休眠 / 重启，那就在本地运行。 **笔记本电脑（本地 Gateway 网关）** - - **优点：** 无服务器成本，可直接访问本地文件，有可见的浏览器窗口。 - - **缺点：** 休眠/网络中断 = 连接断开，操作系统更新/重启会中断，必须保持唤醒。 + - **优点：** 没有服务器成本，可直接访问本地文件，有可见的浏览器窗口。 + - **缺点：** 休眠 / 网络中断 = 断开连接，操作系统更新 / 重启会中断，必须保持唤醒。 **VPS / 云端** - - **优点：** 常开、网络稳定、不会受笔记本休眠影响、更容易持续运行。 - - **缺点：** 通常为无头运行（使用截图），只能远程访问文件，更新时必须通过 SSH。 + - **优点：** 始终在线，网络稳定，没有笔记本休眠问题，更容易长期保持运行。 + - **缺点：** 通常是无头运行（使用截图），只能远程访问文件，更新时必须通过 SSH。 - **OpenClaw 特定说明：** WhatsApp/Telegram/Slack/Mattermost/Discord 在 VPS 上都能正常工作。唯一真正的取舍是**无头浏览器**与可见窗口之间的差异。参见 [Browser](/zh-CN/tools/browser)。 + **OpenClaw 专属说明：** WhatsApp / Telegram / Slack / Mattermost / Discord 在 VPS 上都能正常工作。真正的权衡只有**无头浏览器**与可见窗口的区别。请参阅 [Browser](/zh-CN/tools/browser)。 - **推荐默认方案：** 如果你以前遇到过 Gateway 网关断连，请用 VPS。本地运行非常适合你正在积极使用 Mac，且希望访问本地文件或使用带可见浏览器的 UI 自动化时。 + **推荐默认方案：** 如果你之前遇到过 Gateway 网关 断连，就用 VPS。本地运行非常适合你正在积极使用 Mac，并且希望访问本地文件或通过可见浏览器执行 UI 自动化的时候。 - 不是必须，但**出于可靠性和隔离性考虑，推荐这样做**。 + 不是必须，但为了**可靠性和隔离性**，我们建议这样做。 - - **专用主机（VPS/Mac mini/Pi）：** 常开、较少受休眠/重启影响、权限更干净、更容易持续运行。 - - **共享笔记本/台式机：** 对测试和主动使用来说完全没问题，但当机器休眠或更新时要预期会暂停。 + - **专用主机（VPS / Mac mini / Pi）：** 始终在线，更少受到休眠 / 重启打断，权限更干净，更容易持续运行。 + - **共享笔记本 / 台式机：** 完全适合测试和主动使用，但机器休眠或更新时会出现暂停。 - 如果你想兼顾两者，可以将 Gateway 网关放在专用主机上，并把你的笔记本电脑作为 **node** 配对，以提供本地 screen/camera/exec 工具。参见 [Nodes](/zh-CN/nodes)。 - 有关安全指导，请阅读 [Security](/zh-CN/gateway/security)。 + 如果你想兼顾两者的优点，可以把 Gateway 网关 放在专用主机上，再将你的笔记本电脑作为**节点**配对，以提供本地屏幕 / 摄像头 / exec 工具。请参阅 [Nodes](/zh-CN/nodes)。 + 如需安全指南，请阅读 [安全](/zh-CN/gateway/security)。 - - OpenClaw 很轻量。对于基础 Gateway 网关 + 一个聊天渠道： + + OpenClaw 很轻量。对于基础的 Gateway 网关 + 一个聊天渠道： - - **绝对最低配置：** 1 vCPU、1GB RAM、约 500MB 磁盘。 - - **推荐配置：** 1-2 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。Node 工具和浏览器自动化可能比较吃资源。 + - **绝对最低要求：** 1 个 vCPU、1GB RAM、约 500MB 磁盘空间。 + - **推荐配置：** 1-2 个 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较吃资源。 - 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。 + 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian / Ubuntu）。Linux 安装路径在这些系统上测试最充分。 - 文档： [Linux](/zh-CN/platforms/linux)、[VPS 托管](/zh-CN/vps)。 + 文档：[Linux](/zh-CN/platforms/linux)、[VPS 托管](/zh-CN/vps)。 - - 可以。把 VM 当作 VPS 对待即可：它需要始终在线、可访问，并且为 - Gateway 网关和你启用的所有渠道提供足够的 RAM。 + + 可以。将虚拟机视为 VPS 即可：它需要始终在线、可访问，并且有足够的 + RAM 来运行 Gateway 网关 和你启用的任何渠道。 - 基准建议： + 基线建议： - - **绝对最低配置：** 1 vCPU、1GB RAM。 - - **推荐配置：** 如果你运行多个渠道、浏览器自动化或媒体工具，建议使用 2GB RAM 或更多。 - - **操作系统：** Ubuntu LTS 或其他现代 Debian/Ubuntu。 + - **绝对最低要求：** 1 个 vCPU、1GB RAM。 + - **推荐配置：** 如果你要运行多个渠道、浏览器自动化或媒体工具，建议使用 2GB RAM 或更多。 + - **操作系统：** Ubuntu LTS 或其他现代 Debian / Ubuntu。 - 如果你使用 Windows，**WSL2 是最简单的 VM 风格设置**，并且拥有最佳的工具 - 兼容性。参见 [Windows](/zh-CN/platforms/windows)、[VPS 托管](/zh-CN/vps)。 - 如果你在 VM 中运行 macOS，请参见 [macOS VM](/zh-CN/install/macos-vm)。 + 如果你使用的是 Windows，**WSL2 是最容易的虚拟机式部署方式**，并且具有最佳的工具 + 兼容性。请参阅 [Windows](/zh-CN/platforms/windows)、[VPS 托管](/zh-CN/vps)。 + 如果你在虚拟机中运行 macOS，请参阅 [macOS VM](/zh-CN/install/macos-vm)。 -## OpenClaw 是什么？ +## 什么是 OpenClaw？ - - OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息渠道中回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；助手本身才是产品。 + + OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息渠道中回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还支持语音 + 实时 Canvas。**Gateway 网关** 是始终在线的控制平面；这个助手才是产品本身。 - OpenClaw 不只是“Claude 的一个包装壳”。它是一个**本地优先的控制平面**，让你能够在**自己的硬件**上运行一个强大的 - 助手，通过你已经在使用的聊天应用访问它，并拥有 - 有状态的会话、记忆和工具——而无需把你的工作流控制权交给托管式 + OpenClaw 并不只是“Claude 的一个封装”。它是一个**本地优先的控制平面**，让你能够在**自己的硬件上** + 运行一个功能强大的助手，并通过你已经在使用的聊天应用访问它，同时具备 + 有状态会话、memory 和工具——无需把你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：** Gateway 网关可运行在任何你想要的地方（Mac、Linux、VPS），并将 + - **你的设备，你的数据：** 在任何你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将 工作区 + 会话历史保留在本地。 - - **真实渠道，而不是 Web 沙箱：** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， - 以及受支持平台上的移动端语音和 Canvas。 - - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + - **真实渠道，而不是 Web 沙箱：** WhatsApp / Telegram / Slack / Discord / Signal / iMessage 等， + 以及受支持平台上的移动语音和 Canvas。 + - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体进行路由 和故障切换。 - - **仅本地选项：** 运行本地模型，这样如果你愿意，**所有数据都可以留在你的设备上**。 + - **纯本地选项：** 运行本地模型，这样**所有数据都可以保留在你的设备上**，如果你愿意的话。 - **多智能体路由：** 按渠道、账户或任务拆分不同智能体，每个都有自己的 工作区和默认设置。 - - **开源且可修改：** 可检查、扩展并自托管，无需受制于供应商锁定。 + - **开源且可修改：** 可检查、可扩展、可自托管，不受供应商锁定。 - 文档： [Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 - [记忆](/zh-CN/concepts/memory)。 + 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 + [Memory](/zh-CN/concepts/memory)。 - - 很适合入门的项目包括： + + 很适合作为第一个项目的事情： - - 搭建网站（WordPress、Shopify，或简单的静态站点）。 - - 制作移动应用原型（大纲、界面、API 计划）。 + - 构建一个网站（WordPress、Shopify，或一个简单的静态站点）。 + - 制作一个移动应用原型（大纲、界面、API 方案）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail 并自动生成摘要或后续跟进。 + - 连接 Gmail，并自动生成摘要或后续跟进。 - 它可以处理大型任务，但在你将任务拆分为多个阶段， - 并使用子智能体进行并行工作时效果最好。 + 它可以处理大型任务，但最适合的方式是把任务拆分成多个阶段， + 并使用子智能体来并行处理。 - - 日常中最有价值的用法通常包括： + + 日常中最常见的收获通常包括： - - **个人简报：** 汇总收件箱、日历和你关心的新闻。 - - **研究与起草：** 快速研究、总结，以及邮件或文档的初稿。 - - **提醒和跟进：** 由 cron 或 Heartbeat 驱动的提醒和检查清单。 - - **浏览器自动化：** 填表、收集数据、重复执行 Web 任务。 - - **跨设备协作：** 从手机发送任务，让 Gateway 网关在服务器上运行，然后在聊天中把结果返回给你。 + - **个人简报：** 汇总你关心的收件箱、日历和新闻。 + - **研究与起草：** 快速研究、摘要，以及电子邮件或文档的初稿。 + - **提醒和跟进：** 由 cron 或 Heartbeat 驱动的提醒和清单。 + - **浏览器自动化：** 填表、采集数据，以及重复性的网页任务。 + - **跨设备协作：** 从手机发送任务，让 Gateway 网关 在服务器上执行，然后在聊天中返回结果。 - - 对于**研究、筛选和起草**来说可以。它可以扫描网站、构建候选名单、 - 总结潜在客户，并撰写外联或广告文案草稿。 + + 可以用于**研究、资格筛选和起草**。它可以扫描网站、建立候选名单、 + 总结潜在客户信息，并撰写外联文案或广告文案草稿。 对于**外联或广告投放**，请始终保留人工参与。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审阅所有内容。最安全的模式是让 - OpenClaw 起草，由你审批。 + 平台政策，并在发送前审核所有内容。最安全的模式是让 + OpenClaw 起草，再由你审批。 - 文档： [Security](/zh-CN/gateway/security)。 + 文档：[安全](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协同层，而不是 IDE 替代品。若要在仓库中获得最快的直接编码循环，请使用 - Claude Code 或 Codex。如果你需要持久记忆、跨设备访问和工具编排，请使用 OpenClaw。 + + OpenClaw 是一个**个人助手**和协作协调层，不是 IDE 替代品。对于仓库中的最快直接编码循环， + 请使用 Claude Code 或 Codex。使用 OpenClaw 则是在你 + 需要持久 memory、跨设备访问和工具编排的时候。 优势： - - **跨会话的持久记忆 + 工作区** + - **跨会话的持久 memory + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - - **始终在线的 Gateway 网关**（可运行在 VPS 上，随时随地交互） - - 用于本地浏览器/screen/camera/exec 的 **Nodes** + - **始终在线的 Gateway 网关**（运行在 VPS 上，可随时随地交互） + - 用于本地浏览器 / 屏幕 / 摄像头 / exec 的 **节点** - 展示： [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + 展示页：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1000,45 +1003,45 @@ x-i18n: ## Skills 和自动化 - - 使用托管覆盖，而不是编辑仓库副本。把你的更改放到 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 里的 `skills.load.extraDirs` 添加一个文件夹）。优先级顺序为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍然会优先于内置 Skills，而无需改动 git。如果你需要全局安装该 skill，但只希望某些智能体可见，请将共享副本放在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的修改才应该放在仓库里并以 PR 的形式提交。 + + 使用托管覆盖，而不是直接编辑仓库中的副本。将你的更改放到 `~/.openclaw/skills//SKILL.md`（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级顺序是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍然会在不触碰 git 的前提下优先于内置 Skills。如果你需要全局安装这个 skill，但只让部分智能体可见，请将共享副本保存在 `~/.openclaw/skills` 中，并使用 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的修改才应放在仓库中并通过 PR 提交。 - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级顺序为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一次会话中将其视为 `/skills`。如果该 skill 只应对某些智能体可见，可再配合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果这个 skill 只应对某些智能体可见，请配合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 - 当前支持的模式有： + 目前支持的模式有： - - **Cron jobs**：隔离的任务可以为每个任务设置 `model` 覆盖。 - - **子智能体**：将任务路由到具有不同默认模型的独立智能体。 - - **按需切换**：随时使用 `/model` 切换当前会话模型。 + - **Cron 作业：** 隔离作业可以为每个作业设置 `model` 覆盖。 + - **子智能体：** 将任务路由到具有不同默认模型的独立智能体。 + - **按需切换：** 使用 `/model` 可随时切换当前会话的模型。 - 参见 [Cron jobs](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 - - 对于长时间运行或并行任务，请使用**子智能体**。子智能体在独立会话中运行， - 返回摘要，并让你的主聊天保持响应。 + + 对于长时间运行或并行任务，请使用**子智能体**。子智能体在自己的会话中运行， + 返回摘要，并保持你的主聊天保持响应。 让你的机器人“为这个任务生成一个子智能体”，或使用 `/subagents`。 - 使用聊天中的 `/status` 查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 + 在聊天中使用 `/status` 可以查看 Gateway 网关 当前正在做什么（以及它是否繁忙）。 - token 提示：长任务和子智能体都会消耗 token。如果你在意成本，请通过 `agents.defaults.subagents.model` 为子智能体设置一个 + 令牌提示：长任务和子智能体都会消耗令牌。如果你在意成本，请通过 `agents.defaults.subagents.model` 为子智能体设置一个 更便宜的模型。 - 文档： [Sub-agents](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息会一直停留在绑定的会话上。 + + 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息就会持续留在已绑定的会话上。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 生成（可选再加上 `mode: "session"` 以实现持久后续跟进）。 + - 使用 `sessions_spawn` 并设置 `thread: true` 启动（可选再加 `mode: "session"` 以支持持久后续跟进）。 - 或者手动使用 `/focus ` 进行绑定。 - 使用 `/agents` 检查绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 @@ -1050,19 +1053,19 @@ x-i18n: - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - 在生成时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 - 文档： [Sub-agents](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[配置参考](/zh-CN/gateway/configuration-reference)、[斜杠命令](/zh-CN/tools/slash-commands)。 - - 先检查解析后的请求方路由： + + 先检查已解析的请求者路由： - - 完成模式的子智能体投递会优先使用任何已绑定的线程或会话路由。 - - 如果完成来源只携带渠道，OpenClaw 会回退到请求方会话中保存的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍可能成功。 - - 如果既没有绑定路由，也没有可用的已保存路由，直接投递可能失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 - - 无效或过期的目标仍可能强制回退到队列投递，或导致最终投递失败。 - - 如果子智能体最后一条可见的 assistant 回复是精确的静默 token `NO_REPLY` / `no_reply`，或正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制通知，而不是发送更早的过时进度。 - - 如果子智能体在仅执行工具调用后超时，通知可能会将其折叠为一个简短的部分进度摘要，而不是重放原始工具输出。 + - 完成模式的子智能体在存在已绑定线程或会话路由时，会优先投递到那里。 + - 如果完成来源只带有渠道，OpenClaw 会回退到请求者会话中存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍然可能成功。 + - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 + - 无效或过期的目标仍可能导致回退到队列，或者最终投递失败。 + - 如果子任务最后一条可见的助手回复恰好是静默令牌 `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制通知，而不是发布先前已过时的进度。 + - 如果子任务在只进行了工具调用后超时，通知可能会将其折叠为简短的部分进度摘要，而不是重放原始工具输出。 调试： @@ -1070,19 +1073,19 @@ x-i18n: openclaw tasks show ``` - 文档： [Sub-agents](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)、[Session Tools](/zh-CN/concepts/session-tool)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)、[会话工具](/zh-CN/concepts/session-tool)。 - Cron 在 Gateway 网关进程内部运行。如果 Gateway 网关没有持续运行， - 已计划的任务就不会执行。 + Cron 在 Gateway 网关 进程内部运行。如果 Gateway 网关 没有持续运行， + 定时作业就不会执行。 检查清单： - - 确认已启用 cron（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关是否 24/7 持续运行（没有休眠/重启）。 - - 验证任务的时区设置（`--tz` 与主机时区）。 + - 确认 cron 已启用（`cron.enabled`），且未设置 `OPENCLAW_SKIP_CRON`。 + - 检查 Gateway 网关 是否在 24/7 持续运行（没有休眠 / 重启）。 + - 验证作业的时区设置（`--tz` 与主机时区）。 调试： @@ -1091,22 +1094,22 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - 文档： [Cron jobs](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)。 + 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)。 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示预期不会有外部消息。 - - 缺少或无效的通知目标（`channel` / `to`）意味着运行器跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）表示运行器尝试投递了，但凭证阻止了它。 - - 静默的隔离结果（仅有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队回退投递。 + - `--no-deliver` / `delivery.mode: "none"` 表示不应有任何外部消息。 + - 缺少或无效的通知目标（`channel` / `to`）表示运行器跳过了对外投递。 + - 渠道认证失败（`unauthorized`、`Forbidden`）表示运行器尝试了投递，但凭据阻止了它。 + - 静默的隔离结果（只有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制回退到排队投递。 - 对于隔离的 cron 任务，运行器负责最终投递。智能体应当 - 返回一段纯文本摘要，由运行器负责发送。`--no-deliver` 会让 - 该结果仅保留在内部；它并不是让智能体改为通过 - message 工具直接发送。 + 对于隔离的 cron 作业，运行器负责最终投递。系统期望 + 智能体返回一个纯文本摘要，供运行器发送。`--no-deliver` 会将 + 该结果保留在内部；它并不会改为让智能体直接通过 + message 工具发送。 调试： @@ -1115,24 +1118,24 @@ x-i18n: openclaw tasks show ``` - 文档： [Cron jobs](/zh-CN/automation/cron-jobs)、[后台任务](/zh-CN/automation/tasks)。 + 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[后台任务](/zh-CN/automation/tasks)。 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 会在当前运行抛出 `LiveSessionModelSwitchError` 时， - 持久化一次运行时模型切换并重试。重试会保留切换后的 - 提供商/模型；如果该切换还携带了新的认证配置文件覆盖，cron - 也会先持久化它再重试。 + 隔离的 cron 在当前运行抛出 `LiveSessionModelSwitchError` 时， + 可以持久化运行时模型切换并重试。重试会保留已切换的 + provider / model；如果切换还携带了新的认证配置覆盖，cron + 也会在重试前将其持久化。 - 相关的选择规则： + 相关选择规则： - - 适用时，Gmail hook 模型覆盖优先级最高。 - - 然后是每个任务的 `model`。 - - 然后是任何已保存的 cron 会话模型覆盖。 - - 最后才是普通的智能体/默认模型选择。 + - 如果适用，Gmail hook 模型覆盖优先级最高。 + - 然后是每个作业的 `model`。 + - 然后是任何已存储的 cron 会话模型覆盖。 + - 最后才是常规的智能体 / 默认模型选择。 重试循环是有上限的。在初始尝试加上 2 次切换重试之后， cron 会中止，而不是无限循环。 @@ -1144,12 +1147,12 @@ x-i18n: openclaw tasks show ``` - 文档： [Cron jobs](/zh-CN/automation/cron-jobs)、[cron CLI](/cli/cron)。 + 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[cron CLI](/cli/cron)。 - 使用原生 `openclaw skills` 命令，或将 Skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。 + 使用原生 `openclaw skills` 命令，或将 Skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 ```bash @@ -1163,39 +1166,40 @@ x-i18n: openclaw skills check ``` - 原生 `openclaw skills install` 会写入当前活动工作区的 `skills/` - 目录。只有当你想发布或 - 同步你自己的 Skills 时，才需要额外安装 `clawhub` CLI。对于跨智能体共享安装，请将 skill 放在 - `~/.openclaw/skills` 下，并使用 `agents.defaults.skills` 或 - `agents.list[].skills` 来缩小可见该 skill 的智能体范围。 + 原生 `openclaw skills install` 会写入当前工作区的 `skills/` + 目录。只有当你想发布或同步你自己的 Skills 时，才需要单独安装 `clawhub` CLI。 + 对于跨智能体共享安装，请将 skill 放在 + `~/.openclaw/skills` 下；如果你想限制哪些智能体可以看到它， + 请使用 `agents.defaults.skills` 或 + `agents.list[].skills`。 - 可以。使用 Gateway 网关调度器： + 可以。使用 Gateway 网关 调度器： - - **Cron jobs**：用于已计划或周期性任务（重启后仍保留）。 + - **Cron 作业**：用于定时或重复任务（重启后仍会保留）。 - **Heartbeat**：用于“主会话”的定期检查。 - - **隔离任务**：用于会发布摘要或投递到聊天中的自主智能体。 + - **隔离作业**：用于会发布摘要或投递到聊天中的自治智能体。 - 文档： [Cron jobs](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)、 + 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件控制，且只有当它们在 **Gateway 网关主机** 上符合条件时，才会出现在 system prompt 中。在 Linux 上，`darwin` 专属 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）除非你覆盖了这些限制，否则不会加载。 + + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件控制，而且只有当它们在 **Gateway 网关 主机**上符合条件时，Skills 才会出现在系统提示中。在 Linux 上，`darwin` 专属的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制条件。 你有三种受支持的模式： **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关主机是 macOS，这些 Skills 会正常加载。 + 在 macOS 二进制文件存在的位置运行 Gateway 网关，然后通过[远程模式](#gateway-ports-already-running-and-remote-mode)或通过 Tailscale 从 Linux 连接。由于 Gateway 网关 主机是 macOS，这些 Skills 会正常加载。 - **选项 B - 使用 macOS node（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS node（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当所需二进制文件存在于 node 上时，OpenClaw 可以将这些仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 + **选项 B - 使用 macOS 节点（无需 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - 将 Gateway 网关保留在 Linux 上，但让所需 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持其符合条件。 + 将 Gateway 网关 保持运行在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持其符合条件。 1. 为该二进制文件创建一个 SSH 包装器（示例：Apple Notes 的 `memo`）： @@ -1205,7 +1209,7 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. 将该包装器放入 Linux 主机上的 `PATH` 中（例如 `~/bin/memo`）。 + 2. 将该包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 3. 覆盖 skill 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： ```markdown @@ -1216,24 +1220,24 @@ x-i18n: --- ``` - 4. 启动新会话，以刷新 Skills 快照。 + 4. 启动一个新会话，以便刷新 Skills 快照。 目前没有内置。 - 可选方案： + 可选方式： - - **自定义 skill / 插件：** 最适合可靠的 API 访问（Notion/HeyGen 都提供 API）。 - - **浏览器自动化：** 无需编写代码即可工作，但速度较慢，也更脆弱。 + - **自定义 skill / 插件：** 最适合可靠的 API 访问（Notion / HeyGen 都有 API）。 + - **浏览器自动化：** 无需写代码即可使用，但速度较慢，也更脆弱。 - 如果你希望按客户保留上下文（代理机构工作流），一个简单模式是： + 如果你想为每个客户保留上下文（代理机构工作流），一种简单模式是： - - 每个客户对应一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - - 让智能体在会话开始时获取该页面。 + - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 + - 在会话开始时让智能体获取该页面。 - 如果你希望获得原生集成，请提交功能请求，或构建一个 + 如果你想要原生集成，请提交功能请求，或构建一个 面向这些 API 的 skill。 安装 Skills： @@ -1243,130 +1247,130 @@ x-i18n: openclaw skills update --all ``` - 原生安装会落在当前活动工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果共享安装只应对部分智能体可见，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 Skills 需要通过 Homebrew 安装二进制文件；在 Linux 上，这意味着 Linuxbrew（参见上面的 Homebrew Linux 常见问题条目）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会落到当前工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果共享安装只应对某些智能体可见，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。有些 Skills 期望通过 Homebrew 安装二进制文件；在 Linux 上，这意味着 Linuxbrew（参见上面的 Homebrew Linux 常见问题条目）。请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 进行连接： + 使用内置的 `user` 浏览器配置文件，它通过 Chrome DevTools MCP 进行连接： ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 如果你想使用自定义名称，请创建一个显式的 MCP 配置文件： + 如果你想自定义名称，请创建一个显式的 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 该路径仅限主机本地。如果 Gateway 网关运行在其他地方，请在浏览器所在机器上运行 node host，或改用远程 CDP。 + 这一路径可以使用本地主机浏览器，也可以使用已连接的浏览器节点。如果 Gateway 网关 运行在其他地方，请在浏览器所在机器上运行一个节点主机，或改用远程 CDP。 - `existing-session` / `user` 的当前限制： + `existing-session` / `user` 当前的限制： - - 操作基于 ref 驱动，而不是基于 CSS 选择器驱动 - - 上传需要 `ref` / `inputRef`，并且当前一次只支持一个文件 - - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要受管浏览器或原始 CDP 配置文件 + - 操作是基于 ref 驱动的，而不是基于 CSS 选择器驱动的 + - 上传需要 `ref` / `inputRef`，而且目前一次只支持一个文件 + - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置文件 -## 沙箱隔离和记忆 +## 沙箱隔离和 memory - - 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。有关 Docker 专用设置（Docker 中的完整 Gateway 网关或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 + + 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（Docker 中的完整 Gateway 网关 或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 - 默认镜像以安全优先方式运行，并且使用 `node` 用户，因此它不 - 包含系统包、Homebrew 或内置浏览器。若要获得更完整的设置： + 默认镜像以安全优先为目标，并以 `node` 用户身份运行，因此它不 + 包含系统包、Homebrew 或内置浏览器。若想获得更完整的部署： - - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，这样缓存可以保留。 - - 通过 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖预先写入镜像。 - - 使用内置 CLI 安装 Playwright 浏览器： + - 持久化 `/home/node`，使用 `OPENCLAW_HOME_VOLUME` 让缓存得以保留。 + - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 + - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径已持久化。 + - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径是持久化的。 - 文档： [Docker](/zh-CN/install/docker)、[Browser](/zh-CN/tools/browser)。 + 文档：[Docker](/zh-CN/install/docker)、[Browser](/zh-CN/tools/browser)。 - - 可以——前提是你的私有流量是**私信**，而公共流量是**群组**。 + + 可以——前提是你的私密流量是**私信**，而公开流量是**群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在 Docker 中运行，而主私信会话仍然留在主机上。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组 / 渠道会话（非主键）会在 Docker 中运行，而主私信会话仍然在主机上运行。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 - 设置演练 + 示例配置： [群组：个人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置：[群组：私密私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) - 关键配置参考： [Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) + 关键配置参考：[Gateway 网关 配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) - - 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局和每个智能体的 binds 会合并；当 `scope: "shared"` 时，每个智能体的 binds 会被忽略。对任何敏感内容都请使用 `:ro`，并记住 binds 会绕过沙箱文件系统边界。 + + 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局和按智能体的绑定会合并；当 `scope: "shared"` 时，按智能体绑定会被忽略。对任何敏感内容都使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会同时根据规范化路径和通过最深已存在祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，通过父级符号链接逃逸的情况仍会以失败关闭方式被阻止，并且在符号链接解析之后，允许根目录检查仍然适用。 + OpenClaw 会同时根据规范化路径以及通过最深层已存在祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，通过符号链接父目录进行逃逸的情况仍会以默认拒绝方式失败；而且在符号链接解析之后，允许根目录检查仍然会继续生效。 - 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [沙箱隔离 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 - - OpenClaw 的记忆就是智能体工作区中的 Markdown 文件： + + OpenClaw 的 memory 就是智能体工作区中的 Markdown 文件： - - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中整理过的长期笔记（仅主/私密会话） + - `memory/YYYY-MM-DD.md` 中的每日日志 + - `MEMORY.md` 中整理过的长期笔记（仅主 / 私密会话） - OpenClaw 还会运行一个**静默的预压缩记忆刷新**，以提醒模型 - 在自动压缩前写入持久笔记。只有当工作区 - 可写时，这个过程才会运行（只读沙箱会跳过它）。参见 [记忆](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一个**静默的预压缩 memory flush**，提醒模型 + 在自动压缩前写入持久笔记。这只会在工作区 + 可写时运行（只读沙箱会跳过）。请参阅 [Memory](/zh-CN/concepts/memory)。 - - 让机器人**把这个事实写入记忆**。长期笔记应放在 `MEMORY.md` 中， - 短期上下文则放入 `memory/YYYY-MM-DD.md`。 + + 让机器人**把这个事实写入 memory**。长期笔记应写入 `MEMORY.md`， + 短期上下文则写入 `memory/YYYY-MM-DD.md`。 - 这仍然是我们正在持续改进的领域。提醒模型存储记忆会有帮助； - 它会知道该怎么做。如果它还是一直忘记，请确认 Gateway 网关每次运行时 - 使用的是同一个工作区。 + 这仍然是我们正在改进的领域。提醒模型存储记忆会有帮助； + 它会知道该怎么做。如果它还是总忘记，请确认 Gateway 网关 每次运行时都在使用同一个 + 工作区。 - 文档： [记忆](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 + 文档：[Memory](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 - - 记忆文件存储在磁盘上，除非你删除它们，否则会一直保留。限制来自你的 - 存储空间，而不是模型。**会话上下文** 仍然受模型 - 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 - 需要记忆搜索——它只会把相关部分重新拉回上下文。 + + memory 文件保存在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 + 存储空间，而不是模型。**会话上下文**仍然受模型 + 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么会有 + memory 搜索——它只会将相关部分重新拉回上下文。 - 文档： [记忆](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 + 文档：[Memory](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 - - 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天/补全， - 并且**不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）** 对语义记忆搜索没有帮助。OpenAI embeddings + + 只有在你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天 / 补全， + **不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）** 并不能帮助启用语义 memory 搜索。OpenAI embeddings 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在能够解析 API 密钥时自动选择提供商 - （认证配置文件、`models.providers.*.apiKey` 或环境变量）。 - 如果可以解析 OpenAI 密钥，它会优先使用 OpenAI；否则，如果可以解析 Gemini 密钥，则优先 Gemini； - 然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥，记忆 - 搜索会保持禁用，直到你完成配置。如果你已配置并存在本地模型路径，OpenClaw + 如果你没有显式设置提供商，OpenClaw 会在它 + 能解析到 API 密钥时自动选择一个提供商（认证配置文件、`models.providers.*.apiKey` 或环境变量）。 + 如果能解析到 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析到 Gemini 密钥， + 则选择 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥， + memory 搜索会保持禁用状态，直到你完成配置。如果你已配置且存在本地模型路径，OpenClaw 会优先选择 `local`。当你显式设置 `memorySearch.provider = "ollama"` 时，也支持 Ollama。 - 如果你更希望保持本地运行，请设置 `memorySearch.provider = "local"`（可选再设置 + 如果你想完全本地运行，请设置 `memorySearch.provider = "local"`（可选再设置 `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 - `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或本地** - embedding 模型——有关设置细节，请参见 [记忆](/zh-CN/concepts/memory)。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embeddings + 模型——设置细节请参阅 [Memory](/zh-CN/concepts/memory)。 @@ -1374,52 +1378,52 @@ x-i18n: ## 磁盘上的文件位置 - - 不会——**OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 + + 不会——**OpenClaw 的状态是本地的**，但**外部服务仍然能看到你发送给它们的内容**。 - - **默认本地：** 会话、记忆文件、配置和工作区都保存在 Gateway 网关主机上 + - **默认保存在本地：** 会话、memory 文件、配置和工作区都位于 Gateway 网关 主机上 （`~/.openclaw` + 你的工作区目录）。 - - **因需要而远程：** 你发送给模型提供商（Anthropic/OpenAI 等）的消息会发送到 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在它们 - 的服务器上。 - - **你可以控制范围：** 使用本地模型可以让提示词保留在你的机器上，但渠道 - 流量仍会经过相应渠道的服务器。 + - **因需求而远程：** 你发送给模型提供商（Anthropic / OpenAI / 等）的消息会发送到 + 它们的 API，而聊天平台（WhatsApp / Telegram / Slack / 等）会将消息数据存储在它们的 + 服务器上。 + - **由你控制数据范围：** 使用本地模型可以让提示保留在你的机器上，但渠道 + 流量仍然会经过该渠道的服务器。 - 相关内容： [智能体工作区](/zh-CN/concepts/agent-workspace)、[记忆](/zh-CN/concepts/memory)。 + 相关内容：[智能体工作区](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 - + 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： - | Path | 用途 | + | Path | 用途 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证配置文件中） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`） | - | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件支持 secret 负载 | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清理） | - | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + 会话） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | + | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时会复制到认证配置文件中） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API 密钥，以及可选的 `keyRef` / `tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件后备 secret 负载 | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目会被清理） | + | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | + | `$OPENCLAW_STATE_DIR/agents/` | 按智能体划分的状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（按智能体） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是独立的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 + 你的**工作区**（AGENTS.md、memory 文件、Skills 等）是独立的，通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 - 这些文件位于**智能体工作区**，而不是 `~/.openclaw`。 + 这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 - - **工作区（每个智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 - `MEMORY.md`（如果没有 `MEMORY.md`，则使用旧版回退 `memory.md`）、 - `memory/YYYY-MM-DD.md`、可选的 `HEARTBEAT.md`。 - - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、认证配置文件、会话、日志， + - **工作区（每个智能体）：** `AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + `MEMORY.md`（若不存在 `MEMORY.md`，则回退到旧版 `memory.md`）， + `memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 + - **状态目录（`~/.openclaw`）：** 配置、渠道 / 提供商状态、认证配置文件、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 - 默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： + 默认工作区为 `~/.openclaw/workspace`，可通过以下方式配置： ```json5 { @@ -1427,42 +1431,42 @@ x-i18n: } ``` - 如果机器人在重启后“忘记”了内容，请确认 Gateway 网关每次启动时都使用同一个 - 工作区（并记住：远程模式使用的是**Gateway 网关主机的** - 工作区，而不是你本地笔记本电脑上的工作区）。 + 如果机器人在重启后“遗忘”了内容，请确认 Gateway 网关 每次启动时都在使用同一个 + 工作区（并记住：远程模式使用的是**Gateway 网关 主机** + 的工作区，而不是你的本地笔记本电脑）。 - 提示：如果你想保留某种持久行为或偏好，请让机器人**把它写入 + 提示：如果你希望某种行为或偏好长期保留，请让机器人**将其写入 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 - 参见 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [记忆](/zh-CN/concepts/memory)。 + 请参阅 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 - 将你的**智能体工作区**放入一个**私有** git 仓库，并将其备份到某个 - 私有位置（例如 GitHub 私有仓库）。这样可以保存记忆 + AGENTS/SOUL/USER - 文件，并让你日后恢复这个助手的“思维”。 + 将你的**智能体工作区**放在一个**私有** git 仓库中，并备份到某个 + 私有位置（例如 GitHub 私有仓库）。这样可以保存 memory + AGENTS / SOUL / USER + 文件，并让你之后能够恢复助手的“思维”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、token 或加密的 secret 负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭据、会话、令牌或加密 secret 负载）。 如果你需要完整恢复，请分别备份工作区和状态目录 （参见上面的迁移问题）。 - 文档： [智能体工作区](/zh-CN/concepts/agent-workspace)。 + 文档：[智能体工作区](/zh-CN/concepts/agent-workspace)。 - 请参阅专门指南： [Uninstall](/zh-CN/install/uninstall)。 + 请参阅专门指南：[卸载](/zh-CN/install/uninstall)。 - 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性沙箱。 - 相对路径会在工作区内解析，但绝对路径仍可访问主机上的其他 + 可以。工作区是**默认 cwd** 和 memory 锚点，而不是硬性沙箱。 + 相对路径会在工作区内解析，但绝对路径可以访问主机上的其他 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体设置沙箱。如果你 希望某个仓库成为默认工作目录，请将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源代码；除非你有意让智能体在其中工作，否则应保持 - 工作区独立。 + `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你明确希望智能体在其中工作，否则请将 + 工作区与其分开。 示例（将仓库作为默认 cwd）： @@ -1479,29 +1483,29 @@ x-i18n: - 会话状态归**Gateway 网关主机**所有。如果你处于远程模式，你需要关注的会话存储位于远程机器上，而不是你本地笔记本电脑上。参见 [会话管理](/zh-CN/concepts/session)。 + 会话状态归**Gateway 网关 主机**所有。如果你处于远程模式，你关心的会话存储位于远程机器上，而不是你的本地笔记本电脑。请参阅 [会话管理](/zh-CN/concepts/session)。 ## 配置基础 - + OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` $OPENCLAW_CONFIG_PATH ``` - 如果该文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 + 如果文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 - - 非 loopback bind **需要有效的 Gateway 网关认证路径**。实际中这意味着： + + 非 loopback bind **需要有效的 gateway 认证路径**。实际来说，这意味着： - - 共享密钥认证：token 或 password - - 在已正确配置的非 loopback 身份感知反向代理之后使用 `gateway.auth.mode: "trusted-proxy"` + - shared-secret 认证：令牌或密码 + - 位于正确配置的非 loopback 身份感知反向代理之后的 `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -1517,24 +1521,24 @@ x-i18n: 说明： - - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关认证。 + - `gateway.remote.token` / `.password` 本身**不会**启用本地 gateway 认证。 - 只有在 `gateway.auth.*` 未设置时，本地调用路径才会将 `gateway.remote.*` 用作回退。 - - 对于 password 认证，请改为设置 `gateway.auth.mode: "password"` 加上 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析将以失败关闭方式结束（不会被远程回退掩盖）。 - - 共享密钥的 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（保存在应用/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这类携带身份的模式则改用请求标头。避免将共享密钥放入 URL 中。 - - 在 `gateway.auth.mode: "trusted-proxy"` 下，同主机的 loopback 反向代理仍然**不**满足 trusted-proxy 认证要求。trusted proxy 必须是已配置的非 loopback 来源。 + - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 + - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会以默认拒绝方式失败（不会用远程回退来掩盖）。 + - shared-secret 的 Control UI 部署通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在 app / UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的带身份模式则改用请求头。避免将 shared secret 放在 URL 中。 + - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机上的 loopback 反向代理**仍然不能**满足 trusted-proxy 认证。trusted proxy 必须是一个已配置的非 loopback 来源。 - - OpenClaw 默认强制启用 Gateway 网关认证，包括 loopback。在常规默认路径下，这意味着 token 认证：如果没有显式配置认证路径，Gateway 网关启动时会解析为 token 模式并自动生成一个 token，保存到 `gateway.auth.token` 中，因此**本地 WS 客户端必须进行认证**。这样可以阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认会强制执行 gateway 认证，包括 loopback。在正常默认路径下，这意味着令牌认证：如果没有显式配置认证路径，gateway 启动时会解析为令牌模式并自动生成一个令牌，保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须认证**。这样可以阻止其他本地进程调用 Gateway 网关。 - 如果你更喜欢其他认证路径，可以显式选择 password 模式（或者，对于非 loopback 的身份感知反向代理，可选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 随时都可以为你生成 token：`openclaw doctor --generate-gateway-token`。 + 如果你更喜欢其他认证路径，可以显式选择密码模式（或者，对于非 loopback 的身份感知反向代理，可选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成令牌：`openclaw doctor --generate-gateway-token`。 - - Gateway 网关会监视配置并支持热重载： + + Gateway 网关 会监视配置并支持热重载： - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更则重启 - 也支持 `hot`、`restart`、`off` @@ -1554,23 +1558,23 @@ x-i18n: } ``` - - `off`：隐藏标语文本，但保留横幅标题/版本行。 + - `off`：隐藏标语文本，但保留横幅标题 / 版本行。 - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换有趣/季节性标语（默认行为）。 - - 如果你想完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `random`：轮换有趣 / 季节性标语（默认行为）。 + - 如果你希望完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - - `web_fetch` 无需 API 密钥即可工作。`web_search` 取决于你选择的 + + `web_fetch` 无需 API 密钥即可使用。`web_search` 取决于你选择的 提供商： - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商，需要按其常规方式配置 API 密钥。 - - Ollama Web 搜索无需密钥，但它会使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商需要正常配置对应的 API 密钥。 + - Ollama Web 搜索 无需密钥，但它使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 - DuckDuckGo 无需密钥，但它是一个基于 HTML 的非官方集成。 - - SearXNG 无需密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - SearXNG 无需密钥 / 可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐：** 运行 `openclaw configure --section web` 并选择一个提供商。 + **推荐方式：** 运行 `openclaw configure --section web` 并选择一个提供商。 环境变量替代方案： - Brave：`BRAVE_API_KEY` @@ -1613,59 +1617,59 @@ x-i18n: } ``` - 提供商特定的 web search 配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 出于兼容性考虑，旧版 `tools.web.search.*` 提供商路径目前仍可临时加载，但新配置不应继续使用它们。 - Firecrawl 的 web fetch 回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + 提供商专属的 web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 + 出于兼容性考虑，旧版 `tools.web.search.*` 提供商路径目前仍可加载，但不应再用于新配置。 + Firecrawl 的 web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 说明： - - 如果你使用 allowlist，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 + - 如果你使用允许列表，请添加 `web_search` / `web_fetch` / `x_search` 或 `group:web`。 - `web_fetch` 默认启用（除非显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会根据可用凭证自动检测第一个可用的 fetch 回退提供商。目前内置提供商是 Firecrawl。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭据中自动检测第一个已就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 - 文档： [Web 工具](/zh-CN/tools/web)。 + 文档：[Web 工具](/zh-CN/tools/web)。 - + `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 都会被移除。 - 恢复方式： + 恢复方法： - - 从备份恢复（git 或复制出来的 `~/.openclaw/openclaw.json`）。 - - 如果你没有备份，请重新运行 `openclaw doctor` 并重新配置渠道/模型。 - - 如果这不是你预期的行为，请提交 bug，并附上你最后已知的配置或任何备份。 - - 本地编码智能体通常可以根据日志或历史记录重建出可用配置。 + - 从备份恢复（git 或复制过的 `~/.openclaw/openclaw.json`）。 + - 如果没有备份，请重新运行 `openclaw doctor` 并重新配置渠道 / 模型。 + - 如果这是意料之外的行为，请提交 bug，并附上你最近可用的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史记录重建一个可工作的配置。 - 预防方式： + 避免方法： - - 小改动请使用 `openclaw config set`。 - - 交互式编辑请使用 `openclaw configure`。 - - 当你不确定精确路径或字段结构时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点及其直接子项摘要，方便逐层钻取。 - - 对于部分 RPC 编辑，请使用 `config.patch`；仅在需要整体替换配置时使用 `config.apply`。 - - 如果你在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + - 对于小改动，请使用 `openclaw config set`。 + - 对于交互式编辑，请使用 `openclaw configure`。 + - 当你不确定准确路径或字段结构时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及其直接子项摘要，便于逐步深入。 + - 对于部分 RPC 编辑，请使用 `config.patch`；只在需要完整替换配置时才使用 `config.apply`。 + - 如果你在智能体运行中使用仅限 owner 的 `gateway` 工具，它仍然会拒绝对 `tools.exec.ask` / `tools.exec.security` 的写入（包括会被规范化到同一受保护 exec 路径的旧版 `tools.bash.*` 别名）。 - 文档： [Config](/cli/config)、[Configure](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[配置](/cli/config)、[配置向导](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 - - 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上 **nodes** 和 **agents**： + + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - - **Gateway 网关（中央）：** 持有渠道（Signal/WhatsApp）、路由和会话。 - - **Nodes（设备）：** Mac/iOS/Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **Agents（workers）：** 用于专门角色的独立“大脑”/工作区（例如 “Hetzner 运维”、“个人数据”）。 - - **子智能体：** 当你需要并行处理时，从主智能体生成后台工作。 - - **TUI：** 连接到 Gateway 网关，并切换智能体/会话。 + - **Gateway 网关（中央）：** 负责渠道（Signal / WhatsApp）、路由和会话。 + - **节点（设备）：** Mac / iOS / Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 + - **智能体（工作节点）：** 针对特定角色的独立“大脑” / 工作区（例如 “Hetzner 运维”、“个人数据”）。 + - **子智能体：** 当你想并行处理时，从主智能体生成后台工作。 + - **TUI：** 连接到 Gateway 网关，并切换智能体 / 会话。 - 文档： [Nodes](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[TUI](/web/tui)。 + 文档：[Nodes](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/web/tui)。 - 可以。这是一个配置项： + 可以。这是一个配置选项： ```json5 { @@ -1678,137 +1682,138 @@ x-i18n: } ``` - 默认值为 `false`（有头模式）。无头模式在某些网站上更容易触发反机器人检查。参见 [Browser](/zh-CN/tools/browser)。 + 默认值是 `false`（有头模式）。在某些网站上，无头模式更容易触发反机器人检查。请参阅 [Browser](/zh-CN/tools/browser)。 - 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化场景（表单、点击、抓取、登录）。主要区别是： + 无头模式使用**同一个 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别在于： - - 没有可见的浏览器窗口（如果你需要可视化，请使用截图）。 + - 没有可见的浏览器窗口（如果需要视觉内容，请使用截图）。 - 某些网站在无头模式下对自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 经常会阻止无头会话。 + 例如，X / Twitter 经常会阻止无头会话。 - 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任意基于 Chromium 的浏览器），然后重启 Gateway 网关。 - 完整配置示例请参见 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 + 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。 + 完整配置示例请参阅 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 -## 远程 Gateway 网关和 nodes +## 远程 Gateway 网关 和节点 - - Telegram 消息由 **Gateway 网关** 处理。Gateway 网关运行智能体， - 然后仅在需要 node 工具时，才会通过 **Gateway WebSocket** 调用 nodes： + + Telegram 消息由 **Gateway 网关** 处理。Gateway 网关 运行智能体， + 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： - Telegram → Gateway 网关 → 智能体 → `node.*` → Node → Gateway 网关 → Telegram + Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram - Nodes 不会看到入站提供商流量；它们只会接收 node RPC 调用。 + 节点不会看到入站提供商流量；它们只会接收节点 RPC 调用。 - - 简短回答：**将你的电脑配对为一个 node**。Gateway 网关运行在别处，但它可以 - 通过 Gateway WebSocket 在你的本地机器上调用 `node.*` 工具（screen、camera、system）。 + + 简短回答：**把你的电脑配对为一个节点**。Gateway 网关 运行在别处，但它可以 + 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、系统）。 - 典型设置： + 典型部署： - 1. 在始终在线的主机（VPS/家用服务器）上运行 Gateway 网关。 - 2. 将 Gateway 网关主机和你的电脑加入同一个 tailnet。 + 1. 在始终在线的主机（VPS / 家庭服务器）上运行 Gateway 网关。 + 2. 将 Gateway 网关 主机和你的电脑加入同一个 tailnet。 3. 确保 Gateway WS 可访问（tailnet bind 或 SSH 隧道）。 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） - 连接，这样它就可以注册为一个 node。 - 5. 在 Gateway 网关上批准该 node： + 连接，这样它就可以注册为一个节点。 + 5. 在 Gateway 网关 上批准该节点： ```bash openclaw devices list openclaw devices approve ``` - 不需要单独的 TCP bridge；nodes 通过 Gateway WebSocket 连接。 + 不需要额外的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对 macOS node 允许在该机器上执行 `system.run`。仅 - 配对你信任的设备，并查阅 [Security](/zh-CN/gateway/security)。 + 安全提醒：配对 macOS 节点意味着允许在该机器上执行 `system.run`。只 + 配对你信任的设备，并查看 [安全](/zh-CN/gateway/security)。 - 文档： [Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 + 文档：[Nodes](/zh-CN/nodes)、[Gateway 网关 协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[安全](/zh-CN/gateway/security)。 先检查基础项： - - Gateway 网关正在运行：`openclaw gateway status` - - Gateway 网关健康状态：`openclaw status` + - Gateway 网关 正在运行：`openclaw gateway status` + - Gateway 网关 健康状态：`openclaw status` - 渠道健康状态：`openclaw channels status` 然后验证认证和路由： - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 - 如果你通过 SSH 隧道连接，请确认本地隧道已建立并指向正确端口。 - - 确认你的 allowlist（私信或群组）包含你的账户。 + - 确认你的允许列表（私信或群组）包含你的账号。 - 文档： [Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 + 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 - - 可以。虽然没有内置的“bot-to-bot”桥接，但你可以通过几种 - 可靠方式来实现： + + 可以。虽然没有内置的“bot 对 bot”桥接，但你可以通过几种 + 可靠方式把它们连接起来： - **最简单：** 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让 Bot A 给 Bot B 发送消息，然后由 Bot B 像平常一样回复。 + **最简单：** 使用两个机器人都能访问的普通聊天渠道（Telegram / Slack / WhatsApp）。 + 让机器人 A 向机器人 B 发送消息，然后让机器人 B 像平常一样回复。 - **CLI bridge（通用）：** 运行一个脚本，通过 - `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，并将目标指向另一个机器人 - 正在监听的聊天。如果其中一个机器人位于远程 VPS 上，请让你的 CLI 通过 SSH/Tailscale 指向那个远程 Gateway 网关 + **CLI bridge（通用）：** 运行一个脚本，使用 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，并指定另一个机器人 + 正在监听的聊天。如果其中一个机器人在远程 VPS 上，请让你的 CLI + 通过 SSH / Tailscale 指向那个远程 Gateway 网关 （参见 [远程访问](/zh-CN/gateway/remote)）。 - 示例模式（在能访问目标 Gateway 网关的机器上运行）： + 示例模式（在可以访问目标 Gateway 网关 的机器上运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：添加一个保护措施，避免两个机器人无限循环（仅在被提及时响应、渠道 - allowlist，或“不要回复机器人消息”的规则）。 + 提示：添加一个防护规则，避免两个机器人无限循环回复（例如仅在被提及时回复、渠道 + 允许列表，或“不要回复机器人消息”的规则）。 - 文档： [远程访问](/zh-CN/gateway/remote)、[Agent CLI](/cli/agent)、[Agent send](/zh-CN/tools/agent-send)。 + 文档：[远程访问](/zh-CN/gateway/remote)、[智能体 CLI](/cli/agent)、[智能体发送](/zh-CN/tools/agent-send)。 - - 不需要。一个 Gateway 网关可以托管多个智能体，每个都有自己的工作区、默认模型 - 和路由。这是标准设置，比起 - 每个智能体跑一个 VPS 更便宜也更简单。 + + 不需要。一个 Gateway 网关 就可以托管多个智能体，每个智能体都拥有自己的工作区、默认模型 + 和路由。这是标准部署方式，而且比为每个智能体单独运行 + 一个 VPS 更便宜也更简单。 - 只有在你需要硬隔离（安全边界）或确实存在你不想共享的 - 差异很大的配置时，才需要使用独立 VPS。否则，请保留一个 Gateway 网关， - 并使用多个智能体或子智能体。 + 只有当你需要硬隔离（安全边界）或非常 + 不同且不想共享的配置时，才需要使用独立 VPS。否则，保留一个 Gateway 网关， + 并使用多个智能体或子智能体即可。 - - 有——node 是从远程 Gateway 网关访问你笔记本电脑的一级方案，而且它们 - 提供的不仅仅是 shell 访问。Gateway 网关运行在 macOS/Linux 上（Windows 通过 WSL2），并且 - 很轻量（小型 VPS 或 Raspberry Pi 级别设备就足够；4 GB RAM 绰绰有余），因此常见 - 设置是一个始终在线的主机，加上你的笔记本电脑作为 node。 + + 有——节点是从远程 Gateway 网关 访问你笔记本电脑的一级方案，而且它们 + 提供的不仅仅是 shell 访问。Gateway 网关 运行在 macOS / Linux 上（Windows 可通过 WSL2 运行），而且 + 非常轻量（小型 VPS 或 Raspberry Pi 级别的机器就足够；4 GB RAM 已很充裕），因此一种常见的 + 部署方式是一个始终在线的主机，再加上你的笔记本电脑作为节点。 - - **不需要入站 SSH。** Nodes 会主动连接到 Gateway WebSocket，并使用设备配对。 - - **更安全的执行控制。** `system.run` 在该笔记本电脑上受 node allowlist/审批控制。 - - **更多设备工具。** 除了 `system.run` 之外，nodes 还暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。** 将 Gateway 网关放在 VPS 上，但通过笔记本电脑上的 node host 在本地运行 Chrome，或通过 Chrome MCP 连接主机上的本地 Chrome。 + - **无需入站 SSH。** 节点主动连接到 Gateway WebSocket，并使用设备配对。 + - **更安全的执行控制。** `system.run` 受该笔记本电脑上的节点允许列表 / 审批控制。 + - **更多设备工具。** 节点除 `system.run` 外，还暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。** 将 Gateway 网关 保持在 VPS 上，但通过笔记本电脑上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接主机上的本地 Chrome。 SSH 适合临时 shell 访问，但对于持续性的智能体工作流和 - 设备自动化来说，nodes 更简单。 + 设备自动化，节点更简单。 - 文档： [Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[Browser](/zh-CN/tools/browser)。 + 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[Browser](/zh-CN/tools/browser)。 - - 不会。除非你有意运行隔离的 profile（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机上都只应运行**一个 Gateway 网关**。Nodes 是连接到 Gateway 网关的外设 - （iOS/Android nodes，或菜单栏应用中的 macOS “node mode”）。有关无头 node - host 和 CLI 控制，请参阅 [Node host CLI](/cli/node)。 + + 不会。每台主机通常只应运行**一个 Gateway 网关**，除非你有意运行隔离的配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)）。节点是连接到 + Gateway 网关 的外设（iOS / Android 节点，或菜单栏应用中的 macOS“节点模式”）。对于无头节点 + 主机和 CLI 控制，请参阅 [节点主机 CLI](/cli/node)。 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 @@ -1817,11 +1822,11 @@ x-i18n: 有。 - - `config.schema.lookup`：在写入前检查某个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子项摘要 - - `config.get`：获取当前快照 + hash - - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；尽可能热重载，并在需要时重启 - - `config.apply`：验证并替换完整配置；尽可能热重载，并在需要时重启 - - 仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 + - `config.schema.lookup`：在写入前检查一个配置子树，包括其浅层 schema 节点、匹配到的 UI 提示和直接子项摘要 + - `config.get`：获取当前快照 + 哈希 + - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；在可能时热重载，需要时重启 + - `config.apply`：验证并替换完整配置；在可能时热重载，需要时重启 + - 仅限 owner 的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会被规范化到相同的受保护 exec 路径 @@ -1850,7 +1855,7 @@ x-i18n: 2. **在你的 Mac 上安装并登录** - 使用 Tailscale 应用并登录到同一个 tailnet。 3. **启用 MagicDNS（推荐）** - - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 会有一个稳定名称。 + - 在 Tailscale 管理控制台中启用 MagicDNS，让 VPS 拥有稳定名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1861,51 +1866,51 @@ x-i18n: openclaw gateway --tailscale serve ``` - 这样会让 Gateway 网关继续绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 + 这会让 Gateway 网关 保持绑定在 loopback 上，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 - - Serve 会暴露**Gateway 网关 Control UI + WS**。Nodes 通过同一个 Gateway WS 端点连接。 + + Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 - 推荐设置： + 推荐部署： - 1. **确保 VPS 和 Mac 位于同一个 tailnet 上**。 - 2. **在 Remote 模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 - 应用会隧道化 Gateway 网关端口，并以 node 身份连接。 - 3. **在 Gateway 网关上批准该 node**： + 1. **确保 VPS 和 Mac 位于同一个 tailnet 中**。 + 2. **在远程模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 + 该应用会为 Gateway 端口建立隧道，并以节点身份连接。 + 3. **在 Gateway 网关 上批准该节点**： ```bash openclaw devices list openclaw devices approve ``` - 文档： [Gateway protocol](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 + 文档：[Gateway 网关 协议](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 - - 如果你只需要在第二台笔记本电脑上使用**本地工具**（screen/camera/exec），请将它添加为 - **node**。这样可以保留单个 Gateway 网关，并避免重复配置。本地 node 工具 - 目前仅支持 macOS，但我们计划扩展到其他操作系统。 + + 如果你只需要在第二台笔记本电脑上使用**本地工具**（屏幕 / 摄像头 / exec），那就把它添加为 + 一个**节点**。这样可以保留单个 Gateway 网关，并避免重复配置。本地节点工具 + 目前仅支持 macOS，但我们计划将其扩展到其他操作系统。 只有在你需要**硬隔离**或两个完全独立的机器人时，才需要安装第二个 Gateway 网关。 - 文档： [Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 + 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 -## 环境变量和 .env 加载 +## 环境变量和 `.env` 加载 - OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： + OpenClaw 会从父进程（shell、launchd / systemd、CI 等）读取环境变量，另外还会加载： - 当前工作目录中的 `.env` - - 来自 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）的全局回退 `.env` + - `~/.openclaw/.env` 中的全局回退 `.env`（也就是 `$OPENCLAW_STATE_DIR/.env`） - 这两个 `.env` 文件都不会覆盖已有的环境变量。 + 两个 `.env` 文件都不会覆盖现有环境变量。 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： @@ -1918,15 +1923,15 @@ x-i18n: } ``` - 有关完整优先级和来源，请参阅 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源请参阅 [/environment](/zh-CN/help/environment)。 - + 两个常见修复方法： - 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也能读取到。 - 2. 启用 shell 导入（可选的便利功能）： + 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，它们也会被读取。 + 2. 启用 shell 导入（可选的便捷功能）： ```json5 { @@ -1939,36 +1944,36 @@ x-i18n: } ``` - 这会运行你的登录 shell，并且只导入缺失的预期键（绝不覆盖）。对应环境变量： + 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不会覆盖）。对应环境变量： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - `openclaw models status` 报告的是**是否启用了 shell 环境导入**。“Shell env: off” - **不**表示你的环境变量缺失——它只表示 OpenClaw 不会自动加载 + `openclaw models status` 报告的是**shell 环境导入**是否已启用。“Shell env: off” + **并不**表示你的环境变量缺失——它只是表示 OpenClaw 不会自动加载 你的登录 shell。 - 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell - 环境。可通过以下方式修复： + 如果 Gateway 网关 作为服务运行（launchd / systemd），它不会继承你的 shell + 环境。可以通过以下任一方式修复： - 1. 将 token 放入 `~/.openclaw/.env`： + 1. 将令牌放入 `~/.openclaw/.env`： ``` COPILOT_GITHUB_TOKEN=... ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将其加入你的配置 `env` 块中（仅在缺失时应用）。 + 3. 或将它添加到你的配置 `env` 块中（仅在缺失时应用）。 - 然后重启 Gateway 网关并重新检查： + 然后重启 Gateway 网关 并重新检查： ```bash openclaw models status ``` - Copilot token 会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 - 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 + Copilot 令牌会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + 请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1977,14 +1982,14 @@ x-i18n: - 发送单独一条 `/new` 或 `/reset` 消息。参见 [会话管理](/zh-CN/concepts/session)。 + 发送 `/new` 或 `/reset` 作为单独消息。请参阅 [会话管理](/zh-CN/concepts/session)。 - 会话可在 `session.idleMinutes` 后过期，但这项功能**默认禁用**（默认值为 **0**）。 - 将其设置为正值即可启用空闲过期。启用后，空闲期后的**下一条** + 会话可以在 `session.idleMinutes` 之后过期，但这**默认是禁用的**（默认值为 **0**）。 + 将其设置为正值即可启用空闲过期。启用后，在空闲期结束后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除转录记录——它只是开始一个新会话。 + 这不会删除转录内容——它只是开始一个新会话。 ```json5 { @@ -1996,21 +2001,21 @@ x-i18n: - - 有，可以通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 - 智能体，以及多个拥有各自工作区和模型的 worker 智能体。 + + 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 + 智能体，以及多个具有各自工作区和模型的工作智能体。 - 不过，更适合将它视为一个**有趣的实验**。它会消耗大量 token，而且通常 - 不如使用一个机器人配合多个独立会话高效。我们更典型的设想是： - 你与一个机器人对话，并使用不同会话处理并行工作。这个 + 不过，这更适合作为一种**有趣的实验**来看待。它会消耗大量令牌，而且通常 + 不如使用一个机器人配合多个独立会话高效。我们设想的典型模式是 + 你只与一个机器人对话，并用不同会话来进行并行工作。这个 机器人也可以在需要时生成子智能体。 - 文档： [多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/cli/agents)。 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[智能体 CLI](/cli/agents)。 - - 会话上下文受模型窗口限制。长聊天、大量工具输出或太多 + + 会话上下文受模型窗口限制。长聊天、大量工具输出或许多 文件都可能触发压缩或截断。 有帮助的做法： @@ -2018,19 +2023,19 @@ x-i18n: - 让机器人总结当前状态并写入文件。 - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 - 将重要上下文保存在工作区中，并让机器人重新读取。 - - 对长时间运行或并行任务使用子智能体，这样主聊天会更小。 - - 如果这种情况经常发生，请选择上下文窗口更大的模型。 + - 对长任务或并行工作使用子智能体，这样主聊天会保持更小。 + - 如果这种情况经常发生，选择具有更大上下文窗口的模型。 - + 使用 reset 命令： ```bash openclaw reset ``` - 非交互式完整重置： + 非交互式完全重置： ```bash openclaw reset --scope full --yes --non-interactive @@ -2044,9 +2049,9 @@ x-i18n: 说明： - - 如果新手引导检测到现有配置，也会提供 **Reset**。参见 [设置向导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了 profile（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅开发模式；会清除开发配置 + 凭证 + 会话 + 工作区）。 + - 如果新手引导检测到已有配置，也会提供**重置**选项。请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请分别重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发环境重置：`openclaw gateway --dev --reset`（仅限开发环境；会清除开发配置 + 凭据 + 会话 + 工作区）。 @@ -2059,35 +2064,35 @@ x-i18n: /compact ``` - 或使用 `/compact ` 来指导总结内容。 + 或使用 `/compact ` 来指导摘要方式。 - - **重置**（为相同聊天键生成新的会话 ID）： + - **重置**（为相同聊天键创建新的会话 ID）： ``` /new /reset ``` - 如果这种情况持续发生： + 如果问题持续发生： - - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧的工具输出。 - - 使用上下文窗口更大的模型。 + - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧工具输出。 + - 使用具有更大上下文窗口的模型。 - 文档： [压缩](/zh-CN/concepts/compaction)、[会话修剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 + 文档：[压缩](/zh-CN/concepts/compaction)、[会话修剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - 这是一个提供商验证错误：模型发出了一个缺少必需 - `input` 的 `tool_use` 块。通常意味着会话历史已过时或已损坏（常见于长线程 - 或工具/schema 变更之后）。 + 这是一个提供商验证错误：模型输出了一个缺少必需 + `input` 的 `tool_use` 块。通常意味着会话历史已过期或损坏（常见于长线程 + 或工具 / schema 变更之后）。 - 修复方法：发送单独的 `/new` 消息以开始一个新会话。 + 修复方法：使用 `/new`（单独一条消息）开始一个新会话。 - - Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。可进行调整或禁用： + + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。你可以调整或禁用它们： ```json5 { @@ -2102,18 +2107,18 @@ x-i18n: ``` 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 markdown - 标题，例如 `# Heading`），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 - 如果该文件不存在，heartbeat 仍会运行，由模型决定做什么。 + 标题，例如 `# Heading`），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 + 如果文件不存在，Heartbeat 仍会运行，并由模型决定该做什么。 - 每个智能体的覆盖设置使用 `agents.list[].heartbeat`。文档： [Heartbeat](/zh-CN/gateway/heartbeat)。 + 按智能体覆盖使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群组里，OpenClaw 就能看到它。 - 默认情况下，群组回复会被阻止，直到你允许发送者（`groupPolicy: "allowlist"`）。 + + 不需要。OpenClaw 运行在**你自己的账号**上，因此只要你在群组里，OpenClaw 就能看到它。 + 默认情况下，在你允许发送者之前，群组回复会被阻止（`groupPolicy: "allowlist"`）。 - 如果你只希望**你自己**能够触发群组回复： + 如果你希望只有**你自己**能触发群组回复： ```json5 { @@ -2129,7 +2134,7 @@ x-i18n: - 方式 1（最快）：查看日志尾部，然后在群组中发送一条测试消息： + 方式 1（最快）：跟踪日志，然后在群组中发送一条测试消息： ```bash openclaw logs --follow --json @@ -2138,61 +2143,61 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 方式 2（如果已经配置/加入 allowlist）：从配置中列出群组： + 方式 2（如果已经配置 / 加入允许列表）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp ``` - 文档： [WhatsApp](/zh-CN/channels/whatsapp)、[Directory](/cli/directory)、[Logs](/cli/logs)。 + 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Directory](/cli/directory)、[日志](/cli/logs)。 - + 两个常见原因： - - 提及门控已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups` 但没有包含 `"*"`，并且该群组不在 allowlist 中。 + - 提及门控已开启（默认）。你必须 `@提及` 机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组不在允许列表中。 - 参见 [Groups](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 + 请参阅 [群组](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 - - 直接聊天默认会折叠到主会话。群组/渠道拥有各自独立的会话键，而 Telegram 话题 / Discord 线程则是独立会话。参见 [Groups](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 + + 直接聊天默认会折叠到主会话。群组 / 渠道有各自独立的会话键，而 Telegram 话题 / Discord 线程则是独立会话。请参阅 [群组](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至上百个）都没问题，但请注意： + 没有硬性限制。几十个（甚至几百个）都没问题，但要注意： - - **磁盘增长：** 会话 + 转录记录保存在 `~/.openclaw/agents//sessions/` 下。 - - **token 成本：** 智能体越多，意味着并发模型使用越多。 - - **运维开销：** 每个智能体都有各自的认证配置文件、工作区和渠道路由。 + - **磁盘增长：** 会话 + 转录内容位于 `~/.openclaw/agents//sessions/` 下。 + - **令牌成本：** 更多智能体意味着更多并发模型使用。 + - **运维开销：** 按智能体划分的认证配置文件、工作区和渠道路由。 提示： - - 为每个智能体保留一个**活动**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长过快，请修剪旧会话（删除 JSONL 或存储条目）。 - - 使用 `openclaw doctor` 发现零散工作区和 profile 不匹配问题。 + - 为每个智能体保留一个**活跃**工作区（`agents.defaults.workspace`）。 + - 如果磁盘增长，修剪旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 检查游离工作区和配置文件不匹配问题。 可以。使用**多智能体路由**来运行多个隔离的智能体，并按 - 渠道/账户/peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 + 渠道 / 账户 / peer 路由入站消息。Slack 作为渠道受支持，并且可以绑定到特定智能体。 - 浏览器访问能力很强，但并不等于“能做人类能做的任何事”——反机器人机制、CAPTCHA 和 MFA - 仍然可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问能力很强，但并不等于“能做任何人类能做的事”——反机器人机制、CAPTCHA 和 MFA + 仍然可能阻止自动化。若想获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 - 最佳实践设置： + 最佳实践部署： - - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 - - 每个角色一个智能体（绑定）。 + - 始终在线的 Gateway 网关 主机（VPS / Mac mini）。 + - 每个角色一个智能体（bindings）。 - 将 Slack 渠道绑定到这些智能体。 - - 需要时通过 Chrome MCP 或 node 使用本地浏览器。 + - 需要时通过 Chrome MCP 或节点使用本地浏览器。 - 文档： [多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 [Browser](/zh-CN/tools/browser)、[Nodes](/zh-CN/nodes)。 @@ -2208,32 +2213,32 @@ x-i18n: agents.defaults.model.primary ``` - 模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略了 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置 provider，最后才退回到已配置默认 provider 这一已弃用的兼容路径。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会退回到第一个已配置的 provider/model，而不是继续暴露一个过时且已移除 provider 的默认值。不过你仍然应该**显式**设置 `provider/model`。 + 模型以 `provider/model` 的形式引用（示例：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才会退回到已配置的默认提供商这一已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是暴露一个陈旧的、已移除提供商默认值。不过，你仍然应该**显式**设置 `provider/model`。 - **推荐默认值：** 使用你提供商栈中可用的最新一代最强模型。 - **对于启用了工具或会接收不受信任输入的智能体：** 优先考虑模型能力，而不是成本。 - **对于日常/低风险聊天：** 使用更便宜的后备模型，并按智能体角色进行路由。 + **推荐默认值：** 使用你提供商栈中可用的最强最新一代模型。 + **对于启用了工具或处理不可信输入的智能体：** 优先考虑模型强度，而不是成本。 + **对于常规 / 低风险聊天：** 使用更便宜的回退模型，并按智能体角色进行路由。 - MiniMax 有单独文档： [MiniMax](/zh-CN/providers/minimax) 和 + MiniMax 有单独文档：[MiniMax](/zh-CN/providers/minimax) 和 [本地模型](/zh-CN/gateway/local-models)。 - 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于日常 - 聊天或摘要，则使用更便宜的模型。你可以按智能体路由模型，并使用子智能体 - 并行处理长任务（每个子智能体都会消耗 token）。参见 [模型](/zh-CN/concepts/models) 和 - [Sub-agents](/zh-CN/tools/subagents)。 + 经验法则：对于高风险工作，使用**你负担得起的最佳模型**；对于日常 + 聊天或摘要，则使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 + 并行处理长任务（每个子智能体都会消耗令牌）。请参阅 [模型](/zh-CN/concepts/models) 和 + [子智能体](/zh-CN/tools/subagents)。 - 强烈警告：较弱/过度量化的模型更容易受到 prompt - injection 和不安全行为的影响。参见 [Security](/zh-CN/gateway/security)。 + 强烈警告：较弱 / 过度量化的模型更容易受到 prompt + injection 和不安全行为影响。请参阅 [安全](/zh-CN/gateway/security)。 - 更多背景： [模型](/zh-CN/concepts/models)。 + 更多背景：[模型](/zh-CN/concepts/models)。 - 使用**模型命令**，或仅编辑**模型**相关字段。避免整体替换配置。 + 使用**模型命令**，或只编辑**模型**字段。避免完整替换配置。 安全选项： @@ -2242,12 +2247,12 @@ x-i18n: - `openclaw configure --section model`（交互式） - 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model` - 除非你确实打算替换整个配置，否则不要对部分对象使用 `config.apply`。 - 对于 RPC 编辑，先使用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 负载会提供规范化路径、浅层 schema 文档/约束以及直接子项摘要， + 除非你确实打算替换整个配置，否则不要用部分对象调用 `config.apply`。 + 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 负载会给出规范化路径、浅层 schema 文档 / 约束，以及直接子项摘要， 以便进行部分更新。 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 - 文档： [模型](/zh-CN/concepts/models)、[Configure](/cli/configure)、[Config](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[模型](/zh-CN/concepts/models)、[配置向导](/cli/configure)、[配置](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 @@ -2269,22 +2274,22 @@ x-i18n: - 若要手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` 安全说明：较小或高度量化的模型更容易受到 prompt - injection 的影响。对于任何可以使用工具的机器人，我们都强烈推荐**大型模型**。 - 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具 allowlist。 + injection 影响。对于任何可使用工具的机器人，我们强烈建议使用**大模型**。 + 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具允许列表。 - 文档： [Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、 - [模型提供商](/zh-CN/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 + 文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、 + [模型提供商](/zh-CN/concepts/model-providers)、[安全](/zh-CN/gateway/security)、 [沙箱隔离](/zh-CN/gateway/sandboxing)。 - - 这些部署可能不同，并且会随时间变化；没有固定的提供商推荐。 - - 在每个 Gateway 网关上使用 `openclaw models status` 检查当前运行时设置。 - - 对于安全敏感/启用工具的智能体，请使用可用的最新一代最强模型。 + - 这些部署可能彼此不同，并且会随时间变化；没有固定的提供商推荐。 + - 请在每个 gateway 上使用 `openclaw models status` 检查当前运行时设置。 + - 对于安全敏感 / 启用了工具的智能体，请使用当前可用的最强最新一代模型。 - + 将 `/model` 命令作为单独消息发送： ``` @@ -2297,56 +2302,56 @@ x-i18n: /model gemini-flash-lite ``` - 这些是内置别名。自定义别名可以通过 `agents.defaults.models` 添加。 + 这些是内置别名。自定义别名可通过 `agents.defaults.models` 添加。 你可以通过 `/model`、`/model list` 或 `/model status` 列出可用模型。 - `/model`（以及 `/model list`）会显示一个紧凑的数字选择器。按编号选择： + `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择： ``` /model 3 ``` - 你也可以为该 provider 强制指定某个认证配置文件（按会话）： + 你还可以为提供商强制指定某个认证配置文件（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示当前激活的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个认证配置文件。 - 如果可用，它还会显示已配置的 provider 端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示当前处于活动状态的智能体、正在使用的 `auth-profiles.json` 文件，以及接下来将尝试哪个认证配置文件。 + 如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 - **如何取消通过 @profile 设置的固定 profile？** + **如何取消通过 @profile 设置的固定配置文件？** - 重新运行 `/model`，**不要**带 `@profile` 后缀： + 重新运行 `/model`，**不要**带上 `@profile` 后缀： ``` /model anthropic/claude-opus-4-6 ``` - 如果你想回到默认值，请从 `/model` 中选择它（或发送 `/model `）。 + 如果你想回到默认值，可以从 `/model` 中选择它（或发送 `/model `）。 使用 `/model status` 确认当前激活的是哪个认证配置文件。 - 可以。将一个设置为默认值，并按需切换： + 可以。将其中一个设为默认值，并按需切换： - **快速切换（按会话）：** 日常任务使用 `/model gpt-5.4`，编码时使用 `/model openai-codex/gpt-5.4` 搭配 Codex OAuth。 - - **默认值 + 切换：** 将 `agents.defaults.model.primary` 设为 `openai/gpt-5.4`，然后在编码时切换到 `openai-codex/gpt-5.4`（或反过来）。 + - **默认值 + 切换：** 将 `agents.defaults.model.primary` 设为 `openai/gpt-5.4`，编码时切换到 `openai-codex/gpt-5.4`（反过来也可以）。 - **子智能体：** 将编码任务路由到使用不同默认模型的子智能体。 - 参见 [模型](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 请参阅 [模型](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 - - 可以使用会话切换，也可以使用配置默认值： + + 你可以使用会话级开关或配置默认值： - - **按会话：** 当会话正在使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 + - **按会话：** 当会话使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 - **按模型默认值：** 将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 - - **Codex OAuth 同样适用：** 如果你也使用 `openai-codex/gpt-5.4`，请在那里设置同样的标志。 + - **Codex OAuth 同样适用：** 如果你也使用 `openai-codex/gpt-5.4`，请在那里设置相同标志。 示例： @@ -2371,39 +2376,40 @@ x-i18n: } ``` - 对于 OpenAI，fast mode 会映射到受支持原生 Responses 请求中的 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 + 对于 OpenAI，快速模式会映射为受支持原生 Responses 请求中的 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 - 参见 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 + 请参阅 [思考与快速模式](/zh-CN/tools/thinking) 和 [OpenAI 快速模式](/zh-CN/providers/openai#openai-fast-mode)。 - + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何 - 会话覆盖的**allowlist**。选择不在该列表中的模型会返回： + 会话覆盖的**允许列表**。选择不在该列表中的模型会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - 这个错误会**替代**正常回复返回。修复方式：将该模型加入 - `agents.defaults.models`，移除 allowlist，或从 `/model list` 中选择一个模型。 + 该错误会**取代**正常回复返回。修复方法：将模型添加到 + `agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。 - 这表示**provider 未配置**（未找到 MiniMax provider 配置或认证 - 配置文件），因此无法解析该模型。 + 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或 + 认证配置文件），因此无法解析该模型。 - 修复检查清单： + 修复清单： - 1. 升级到当前 OpenClaw 版本（或直接运行源码 `main`），然后重启 Gateway 网关。 - 2. 确保已配置 MiniMax（通过向导或 JSON），或者环境变量/认证配置文件中存在 MiniMax 认证， - 以便注入匹配的 provider + 1. 升级到当前版本的 OpenClaw（或直接从源码 `main` 运行），然后重启 gateway。 + 2. 确保已配置 MiniMax（通过向导或 JSON），或者 MiniMax 认证 + 存在于环境变量 / 认证配置文件中，以便注入匹配的提供商 （`minimax` 使用 `MINIMAX_API_KEY`，`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax OAuth）。 - 3. 使用与你的认证路径精确匹配的模型 id（区分大小写）： - 对 API key 设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， - 对 OAuth 设置使用 `minimax-portal/MiniMax-M2.7` / + 3. 为你的认证路径使用精确的模型 id（区分大小写）： + API 密钥 + 配置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， + OAuth 配置使用 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 4. 运行： @@ -2411,15 +2417,15 @@ x-i18n: openclaw models list ``` - 然后从列表中选择（或在聊天中使用 `/model list`）。 + 并从列表中选择（或在聊天中使用 `/model list`）。 - 参见 [MiniMax](/zh-CN/providers/minimax) 和 [模型](/zh-CN/concepts/models)。 + 请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [模型](/zh-CN/concepts/models)。 - - 可以。将**MiniMax 设为默认值**，并在需要时**按会话**切换模型。 - 后备机制用于处理**错误**，而不是“困难任务”，因此请使用 `/model` 或单独的智能体。 + + 可以。将 **MiniMax 设为默认值**，并在需要时**按会话**切换模型。 + 回退机制适用于**错误**，而不是“难任务”，所以请使用 `/model` 或单独的智能体。 **选项 A：按会话切换** @@ -2444,18 +2450,18 @@ x-i18n: /model gpt ``` - **选项 B：分离智能体** + **选项 B：单独的智能体** - 智能体 A 默认：MiniMax - 智能体 B 默认：OpenAI - 按智能体路由，或使用 `/agent` 切换 - 文档： [模型](/zh-CN/concepts/models)、[多智能体路由](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 + 文档：[模型](/zh-CN/concepts/models)、[多智能体路由](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 - 是。OpenClaw 内置了一些默认简写（仅当模型存在于 `agents.defaults.models` 中时才会生效）： + 是的。OpenClaw 内置了一些默认简写（仅在模型存在于 `agents.defaults.models` 中时才会生效）： - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2470,7 +2476,7 @@ x-i18n: - + 别名来自 `agents.defaults.models..alias`。示例： ```json5 @@ -2488,12 +2494,12 @@ x-i18n: } ``` - 然后 `/model sonnet`（或在支持时使用 `/`）就会解析为该模型 ID。 + 然后 `/model sonnet`（或在支持时使用 `/`）就会解析到对应的模型 ID。 - OpenRouter（按 token 计费；模型很多）： + OpenRouter（按令牌计费；模型很多）： ```json5 { @@ -2521,11 +2527,12 @@ x-i18n: } ``` - 如果你引用了某个 provider/model，但缺少所需的 provider 密钥，就会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 + 如果你引用了某个 provider / model，但缺少所需的提供商密钥，你会看到运行时认证错误（例如 `No API key found for provider "zai"`）。 - **添加新智能体后，提示找不到 provider 的 API key** + **添加新智能体后提示 No API key found for provider** - 这通常意味着**新智能体**的认证存储是空的。认证是按智能体隔离的，并存储在： + 这通常意味着**新智能体**的认证存储是空的。认证是按智能体区分的， + 存储在： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2534,9 +2541,9 @@ x-i18n: 修复方式： - 运行 `openclaw agents add `，并在向导中配置认证。 - - 或将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 + - 或者把主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 - **不要**在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。 + **不要**在多个智能体之间复用 `agentDir`；这会导致认证 / 会话冲突。 @@ -2545,106 +2552,106 @@ x-i18n: - 故障切换分两个阶段进行： + 故障切换分为两个阶段： - 1. 同一 provider 内的**认证配置文件轮换**。 - 2. **模型后备**到 `agents.defaults.model.fallbacks` 中的下一个模型。 + 1. **同一提供商内的认证配置文件轮换**。 + 2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。 - 对失败的配置文件会应用冷却时间（指数退避），因此即使某个 provider 触发速率限制或暂时失败，OpenClaw 仍可继续响应。 + 对失败的配置文件会应用冷却时间（指数退避），因此即使某个提供商被速率限制或暂时失败，OpenClaw 仍能继续响应。 - 速率限制桶包含的不仅仅是普通的 `429` 响应。OpenClaw + 速率限制桶不仅包含普通的 `429` 响应。OpenClaw 还会将诸如 `Too many concurrent requests`、 `ThrottlingException`、`concurrency limit reached`、 - `workers_ai ... quota limit exceeded`、`resource exhausted`，以及周期性 - 使用窗口限制（`weekly/monthly limit reached`）等消息也视为值得进行故障切换的 + `workers_ai ... quota limit exceeded`、`resource exhausted` 和周期性的 + 使用窗口限制（`weekly/monthly limit reached`）视为值得故障切换的 速率限制。 有些看起来像计费问题的响应并不是 `402`，而有些 HTTP `402` - 响应也仍会留在那个瞬态桶中。如果 provider 在 `401` 或 `403` 上返回 - 明确的计费文本，OpenClaw 仍可以将其保留在 - 计费路径中，但 provider 特定的文本匹配器会限制在属于它们的 - provider 范围内（例如 OpenRouter 的 `Key limit exceeded`）。如果一个 `402` - 消息看起来更像可重试的使用窗口限制，或者是 - 组织/工作区支出限制（`daily limit reached, resets tomorrow`、 + 响应也会留在那个瞬时错误桶里。如果某个提供商在 `401` 或 `403` + 上返回明确的计费文本，OpenClaw 仍然可以把它归入 + 计费通道，但提供商专属的文本匹配器仍然只作用于 + 拥有它们的提供商（例如 OpenRouter 的 `Key limit exceeded`）。如果某条 `402` + 消息看起来更像是可重试的使用窗口或 + 组织 / 工作区花费限制（`daily limit reached, resets tomorrow`、 `organization spending limit exceeded`），OpenClaw 会将其视为 `rate_limit`，而不是长期计费禁用。 - 上下文溢出错误则不同：像 + 上下文溢出错误则不同：诸如 `request_too_large`、`input exceeds the maximum number of tokens`、 `input token count exceeds the maximum number of input tokens`、 - `input is too long for the model`，或 `ollama error: context length - exceeded` 这样的特征，会停留在压缩/重试路径上，而不会推进到模型 - 后备。 + `input is too long for the model` 或 `ollama error: context length + exceeded` 这类特征会保留在压缩 / 重试路径上，而不是推进模型 + 回退。 - 通用服务器错误文本的判定范围刻意比“任何包含 - unknown/error 的内容”更窄。OpenClaw 确实会将 provider 范围内的瞬态形式 - 视为值得故障切换的超时/过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 + 通用服务器错误文本的范围刻意比“任何带 unknown / error 的内容” + 更窄。OpenClaw 确实会在提供商上下文匹配时，将提供商专属的瞬时错误形态 + 视为值得故障切换的超时 / 过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 `Provider returned error`、停止原因错误如 `Unhandled stop reason: - error`、带有瞬态服务器文本的 JSON `api_error` 负载 + error`、带有瞬时服务器文本的 JSON `api_error` 负载 （`internal server error`、`unknown error, 520`、`upstream error`、`backend - error`），以及 provider 忙碌错误，如 `ModelNotReadyException`，前提是 provider 上下文匹配。 - 像 `LLM request failed with an unknown - error.` 这样的通用内部回退文本则会保持保守，不会单独触发模型后备。 + error`），以及提供商繁忙错误如 `ModelNotReadyException`。 + 而像 `LLM request failed with an unknown + error.` 这样的通用内部回退文本则保持保守，不会仅凭自身触发模型回退。 - 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但在预期的认证存储中找不到对应凭证。 + 这意味着系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭据。 - **修复检查清单：** + **修复清单：** - - **确认 auth profiles 的存放位置**（新路径与旧路径） + - **确认认证配置文件存放位置**（新版路径与旧版路径） - 当前：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - - **确认 Gateway 网关已加载你的环境变量** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。请将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 + - **确认 Gateway 网关 已加载你的环境变量** + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd / launchd 运行 Gateway 网关，它可能不会继承该变量。请把它放到 `~/.openclaw/.env` 中，或启用 `env.shellEnv`。 - **确保你编辑的是正确的智能体** - - 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。 - - **做一个基本的模型/认证状态检查** - - 使用 `openclaw models status` 查看已配置模型，以及 provider 是否已认证。 + - 多智能体部署意味着可能存在多个 `auth-profiles.json` 文件。 + - **检查模型 / 认证状态** + - 使用 `openclaw models status` 查看已配置的模型以及提供商是否已认证。 - **针对 “No credentials found for profile anthropic” 的修复检查清单** + **“No credentials found for profile anthropic” 的修复清单** - 这表示本次运行被固定到一个 Anthropic 认证配置文件，但 Gateway 网关 + 这意味着当前运行被固定到某个 Anthropic 认证配置文件，但 Gateway 网关 无法在其认证存储中找到它。 - **使用 Claude CLI** - - 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 + - 在 Gateway 网关 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - **如果你想改用 API 密钥** - - 在**Gateway 网关主机**上的 `~/.openclaw/.env` 中加入 `ANTHROPIC_API_KEY`。 + - 在**Gateway 网关 主机**上的 `~/.openclaw/.env` 中设置 `ANTHROPIC_API_KEY`。 - 清除任何强制使用缺失配置文件的固定顺序： ```bash openclaw models auth order clear --provider anthropic ``` - - **确认你是在 Gateway 网关主机上运行命令** - - 在远程模式下，auth profiles 位于 Gateway 网关机器上，而不是你的笔记本电脑上。 + - **确认你是在 Gateway 网关 主机上运行命令** + - 在远程模式下，认证配置文件位于 gateway 机器上，而不是你的笔记本电脑上。 - - 如果你的模型配置中把 Google Gemini 设为后备（或者你切换到了 Gemini 简写），OpenClaw 会在模型后备时尝试它。如果你没有配置 Google 凭证，就会看到 `No API key found for provider "google"`。 + + 如果你的模型配置中把 Google Gemini 设为了回退项（或者你切换到了 Gemini 简写），OpenClaw 就会在模型回退时尝试它。如果你没有配置 Google 凭据，就会看到 `No API key found for provider "google"`。 - 修复方法：要么提供 Google 认证，要么从 `agents.defaults.model.fallbacks` / 别名中移除或避免使用 Google 模型，这样后备就不会路由到那里。 + 修复方法：要么提供 Google 认证，要么从 `agents.defaults.model.fallbacks` / 别名中移除 / 避免 Google 模型，这样回退就不会路由到那里。 **LLM request rejected: thinking signature required（Google Antigravity）** 原因：会话历史中包含**没有签名的 thinking 块**（通常来自 - 中止/部分流）。Google Antigravity 要求 thinking 块必须带签名。 + 中断 / 部分流式传输）。Google Antigravity 要求 thinking 块必须带签名。 - 修复方法：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking 块。如果问题仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 + 修复方法：OpenClaw 现在会为 Google Antigravity Claude 去除无签名的 thinking 块。如果仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 ## 认证配置文件：它们是什么，以及如何管理 -相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账户模式） +相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账户模式） - - auth profile 是与某个 provider 绑定的具名凭证记录（OAuth 或 API 密钥）。Profiles 位于： + + 认证配置文件是与某个提供商关联的命名凭据记录（OAuth 或 API 密钥）。配置文件保存在： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2652,8 +2659,8 @@ x-i18n: - - OpenClaw 使用带 provider 前缀的 ID，例如： + + OpenClaw 使用带提供商前缀的 ID，例如： - `anthropic:default`（没有 email 身份时很常见） - `anthropic:` 用于 OAuth 身份 @@ -2661,64 +2668,64 @@ x-i18n: - - 可以。配置支持 profiles 的可选元数据，以及按 provider 排序（`auth.order.`）。这**不会**存储 secrets；它只是将 ID 映射到 provider/mode，并设置轮换顺序。 + + 可以。配置支持可选的配置文件元数据，以及按提供商划分的顺序（`auth.order.`）。这**不会**存储 secret；它只会把 ID 映射到 provider / mode，并设置轮换顺序。 - 如果某个 profile 处于短期**冷却**状态（速率限制/超时/认证失败）或更长期的**禁用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 + 如果某个配置文件处于短暂的**冷却**状态（速率限制 / 超时 / 认证失败）或较长的**禁用**状态（计费 / 额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 - 速率限制冷却可以按模型划分。某个 profile 若在一个模型上处于冷却中， - 仍可能在同一 provider 的兄弟模型上可用， - 但计费/禁用窗口仍会阻止整个 profile。 + 速率限制冷却可以是模型级别的。某个配置文件在一个模型上处于冷却状态时， + 在同一提供商下的兄弟模型上仍可能可用， + 而计费 / 禁用窗口仍会阻止整个配置文件。 - 你还可以通过 CLI 设置**每个智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： + 你还可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： ```bash - # 默认针对已配置的默认智能体（省略 --agent） + # 默认为已配置的默认智能体（省略 --agent） openclaw models auth order get --provider anthropic - # 将轮换锁定到单个 profile（只尝试这一项） + # 将轮换固定为单个配置文件（只尝试这个） openclaw models auth order set --provider anthropic anthropic:default - # 或设置显式顺序（provider 内部后备） + # 或设置显式顺序（提供商内回退） openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # 清除覆盖（回退到配置 auth.order / round-robin） + # 清除覆盖（回退到 config auth.order / round-robin） openclaw models auth order clear --provider anthropic ``` - 若要指定某个智能体： + 要指定某个智能体： ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - 若要验证实际会尝试什么，请使用： + 要验证实际会尝试什么，请使用： ```bash openclaw models status --probe ``` - 如果某个已存储 profile 被显式顺序排除，probe 会 - 将该 profile 报告为 `excluded_by_auth_order`，而不是静默尝试它。 + 如果显式顺序中省略了某个已存储配置文件，probe 会为该配置文件报告 + `excluded_by_auth_order`，而不是悄悄尝试它。 - + OpenClaw 两者都支持： - - **OAuth** 通常可以利用订阅访问权限（在适用时）。 - - **API keys** 使用按 token 计费。 + - **OAuth** 通常会利用订阅访问权限（在适用时）。 + - **API 密钥** 使用按令牌计费。 - 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。 + 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。 -## Gateway 网关：端口、“already running” 和远程模式 +## Gateway 网关：端口、“already running”和远程模式 - - `gateway.port` 控制 WebSocket + HTTP（Control UI、hooks 等）共用的单一复用端口。 + + `gateway.port` 控制单一复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 优先级： @@ -2728,39 +2735,39 @@ x-i18n: - - 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。而 RPC probe 则是 CLI 实际连接到 Gateway 网关 WebSocket 并调用 `status`。 + + 因为 “running” 是 **supervisor** 的视角（launchd / systemd / schtasks）。而 RPC probe 则是 CLI 实际连接到 gateway WebSocket 并调用 `status` 的结果。 - 请使用 `openclaw gateway status`，并重点查看这些行： + 使用 `openclaw gateway status`，并重点查看以下几行： - `Probe target:`（探测实际使用的 URL） - - `Listening:`（端口上实际绑定了什么） - - `Last gateway error:`（当进程还活着但端口没有监听时，最常见的根因） + - `Listening:`（端口上实际绑定的内容） + - `Last gateway error:`（当进程还活着但端口没有监听时，常见的根因） - - 你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 你编辑的是一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 - 修复： + 修复方法： ```bash openclaw gateway install --force ``` - 请在你希望服务使用的相同 `--profile` / 环境下运行它。 + 从你希望服务使用的同一个 `--profile` / 环境中运行这条命令。 - OpenClaw 会在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，就会抛出 `GatewayLockError`，表示另一个实例已经在监听。 + OpenClaw 会在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示已有另一个实例正在监听。 修复方法：停止另一个实例、释放端口，或使用 `openclaw gateway --port ` 运行。 - - 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL，也可以选择附带共享密钥远程凭证： + + 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL，可选附带 shared-secret 远程凭据： ```json5 { @@ -2777,55 +2784,55 @@ x-i18n: 说明： - - 只有当 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（除非你传入覆盖标志）。 + - 只有在 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（或者你传入覆盖标志）。 - macOS 应用会监视配置文件，并在这些值变更时实时切换模式。 - - `gateway.remote.token` / `.password` 只是客户端侧的远程凭证；它们本身不会启用本地 Gateway 网关认证。 + - `gateway.remote.token` / `.password` 只是客户端侧的远程凭据；它们本身不会启用本地 gateway 认证。 - 你的 Gateway 网关认证路径与 UI 使用的认证方法不匹配。 + 你的 gateway 认证路径与 UI 使用的认证方法不匹配。 事实（来自代码）： - - Control UI 会将 token 保存在 `sessionStorage` 中，并且绑定到当前浏览器标签页会话和选定的 Gateway 网关 URL，因此在同一标签页中刷新后仍可正常工作，而不需要恢复长期的 `localStorage` token 持久化。 - - 当出现 `AUTH_TOKEN_MISMATCH` 时，如果 Gateway 网关返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`），受信任客户端可以使用缓存的设备 token 尝试一次有界重试。 - - 现在，这种缓存 token 重试会复用随设备 token 一起保存的已缓存批准 scopes。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的 scope 集，而不会继承缓存 scopes。 - - 除了该重试路径外，connect 认证优先级依次为：显式共享 token/password，然后是显式 `deviceToken`，再然后是已存储的设备 token，最后是 bootstrap token。 - - Bootstrap token 的 scope 检查带有角色前缀。内置的 bootstrap operator allowlist 只满足 operator 请求；node 或其他非 operator 角色仍然需要其自身角色前缀下的 scopes。 + - Control UI 会将令牌保存在当前浏览器标签页会话和所选 gateway URL 对应的 `sessionStorage` 中，因此同一标签页刷新后仍然可以继续工作，而无需恢复长期的 `localStorage` 令牌持久化。 + - 在 `AUTH_TOKEN_MISMATCH` 时，当 gateway 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以使用缓存的设备令牌执行一次有界重试。 + - 该缓存令牌重试现在会复用与设备令牌一同存储的已批准作用域。显式 `deviceToken` / 显式 `scopes` 调用者仍会保留自己请求的作用域集合，而不是继承缓存作用域。 + - 在该重试路径之外，连接认证优先级依次为：显式 shared token / password，然后是显式 `deviceToken`，然后是已存储的设备令牌，最后是 bootstrap 令牌。 + - Bootstrap 令牌作用域检查采用角色前缀。内置的 bootstrap operator 允许列表只满足 operator 请求；节点或其他非 operator 角色仍然需要其自身角色前缀下的作用域。 修复方法： - - 最快方法：`openclaw dashboard`（会打印并复制仪表板 URL，并尝试打开；如为无头环境则显示 SSH 提示）。 - - 如果你还没有 token：`openclaw doctor --generate-gateway-token`。 - - 如果是远程，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 - - 共享密钥模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后将匹配的密钥粘贴到 Control UI 设置中。 - - Tailscale Serve 模式：确认已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback/tailnet URL。 - - trusted-proxy 模式：确认你是通过已配置的非 loopback 身份感知代理访问的，而不是通过同主机 loopback 代理或原始 Gateway 网关 URL。 - - 如果在一次重试后仍然不匹配，请轮换/重新批准已配对的设备 token： + - 最快方式：`openclaw dashboard`（打印并复制仪表板 URL，尝试打开；若为无头环境则显示 SSH 提示）。 + - 如果你还没有令牌：`openclaw doctor --generate-gateway-token`。 + - 如果是远程环境，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 + - Shared-secret 模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后把对应 secret 粘贴到 Control UI 设置中。 + - Tailscale Serve 模式：确保已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份头的原始 loopback / tailnet URL。 + - Trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理访问，而不是通过同主机 loopback 代理或原始 gateway URL。 + - 如果一次重试后仍然不匹配，请轮换 / 重新批准已配对设备令牌： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该 rotate 调用提示被拒绝，请检查两点： - - 已配对设备会话只能轮换它们**自己的**设备，除非它们还拥有 `operator.admin` - - 显式 `--scope` 值不能超过调用方当前的 operator scopes - - 还是卡住？运行 `openclaw status --all` 并按照 [故障排除](/zh-CN/gateway/troubleshooting) 进行处理。认证详情请参见 [Dashboard](/web/dashboard)。 + - 如果该轮换命令提示被拒绝，请检查两点： + - 已配对设备会话只能轮换它们**自己的**设备，除非它们还具有 `operator.admin` + - 显式 `--scope` 值不能超过调用者当前的 operator 作用域 + - 还是卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 操作。认证细节请参阅 [仪表板](/web/dashboard)。 - - `tailnet` bind 会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器不在 Tailscale 上（或者接口已关闭），就没有可绑定的地址。 + + `tailnet` bind 会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器没有接入 Tailscale（或接口已关闭），就没有可绑定的地址。 修复方法： - - 在该主机上启动 Tailscale（使其拥有一个 100.x 地址），或者 + - 在该主机上启动 Tailscale（使其获得一个 100.x 地址），或者 - 切换到 `gateway.bind: "loopback"` / `"lan"`。 - 说明：`tailnet` 是显式指定的。`auto` 会优先选择 loopback；如果你想要只在 tailnet 上绑定，请使用 `gateway.bind: "tailnet"`。 + 注意：`tailnet` 是显式值。`auto` 会优先选择 loopback；如果你想只绑定到 tailnet，请使用 `gateway.bind: "tailnet"`。 - - 通常不可以——一个 Gateway 网关就能运行多个消息渠道和智能体。只有在你需要冗余（例如救援机器人）或硬隔离时，才使用多个 Gateway 网关。 + + 通常不可以——一个 Gateway 网关 就能运行多个消息渠道和智能体。只有当你需要冗余（例如救援机器人）或硬隔离时，才使用多个 Gateway 网关。 可以，但你必须隔离以下内容： @@ -2837,38 +2844,38 @@ x-i18n: 快速设置（推荐）： - 每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 - - 在每个 profile 配置中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 - - 安装按 profile 区分的服务：`openclaw --profile gateway install`。 + - 在每个配置文件中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 + - 安装按配置文件区分的服务：`openclaw --profile gateway install`。 - Profiles 还会为服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 - 完整指南： [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 + 配置文件还会为服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + 完整指南：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 - Gateway 网关是一个 **WebSocket server**，并且它要求第一条消息 - 必须是 `connect` 帧。如果收到其他内容，它就会关闭连接， - 并返回 **code 1008**（策略违规）。 + Gateway 网关 是一个 **WebSocket 服务器**，它要求收到的第一条消息 + 必须是 `connect` frame。如果收到其他内容，它会以 + **code 1008**（策略违规）关闭连接。 常见原因： - 你在浏览器中打开了 **HTTP** URL（`http://...`），而不是使用 WS 客户端。 - 你使用了错误的端口或路径。 - - 某个代理或隧道剥离了认证标头，或发送了非 Gateway 网关请求。 + - 代理或隧道剥离了认证头，或发送了非 Gateway 网关 请求。 快速修复： 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则使用 `wss://...`）。 2. 不要在普通浏览器标签页中打开 WS 端口。 - 3. 如果启用了认证，请在 `connect` 帧中包含 token/password。 + 3. 如果启用了认证，请在 `connect` frame 中包含 token / password。 - 如果你使用的是 CLI 或 TUI，URL 应类似于： + 如果你使用的是 CLI 或 TUI，URL 应该类似： ``` openclaw tui --url ws://:18789 --token ``` - 协议详情： [Gateway protocol](/zh-CN/gateway/protocol)。 + 协议细节：[Gateway 网关 协议](/zh-CN/gateway/protocol)。 @@ -2883,17 +2890,17 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - 你可以通过 `logging.file` 设置一个稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 + 你可以通过 `logging.file` 设置稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 - 查看日志尾部的最快方式： + 最快查看日志尾部的方法： ```bash openclaw logs --follow ``` - 服务/supervisor 日志（当 Gateway 网关通过 launchd/systemd 运行时）： + 服务 / supervisor 日志（当 gateway 通过 launchd / systemd 运行时）： - - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；profiles 使用 `~/.openclaw-/logs/...`） + - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；配置文件使用 `~/.openclaw-/logs/...`） - Linux：`journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows：`schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` @@ -2901,22 +2908,22 @@ x-i18n: - - 使用 Gateway 网关辅助命令： + + 使用 gateway 辅助命令： ```bash openclaw gateway status openclaw gateway restart ``` - 如果你是手动运行 Gateway 网关，`openclaw gateway --force` 可以重新夺回端口。参见 [Gateway 网关](/zh-CN/gateway)。 + 如果你是手动运行 gateway，`openclaw gateway --force` 可以重新夺回端口。请参阅 [Gateway 网关](/zh-CN/gateway)。 - - Windows 上有**两种安装模式**： + + Windows 有**两种安装模式**： - **1）WSL2（推荐）：** Gateway 网关运行在 Linux 内部。 + **1) WSL2（推荐）：** Gateway 网关 在 Linux 内部运行。 打开 PowerShell，进入 WSL，然后重启： @@ -2926,13 +2933,13 @@ x-i18n: openclaw gateway restart ``` - 如果你从未安装过服务，请以前台方式启动它： + 如果你从未安装服务，就在前台启动它： ```bash openclaw gateway run ``` - **2）原生 Windows（不推荐）：** Gateway 网关直接运行在 Windows 中。 + **2) 原生 Windows（不推荐）：** Gateway 网关 直接在 Windows 中运行。 打开 PowerShell 并运行： @@ -2941,17 +2948,17 @@ x-i18n: openclaw gateway restart ``` - 如果你是手动运行（无服务），请使用： + 如果你是手动运行它（没有服务），请使用： ```powershell openclaw gateway run ``` - 文档： [Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关服务运行手册](/zh-CN/gateway)。 + 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关 服务运行手册](/zh-CN/gateway)。 - + 先做一次快速健康检查： ```bash @@ -2963,24 +2970,24 @@ x-i18n: 常见原因： - - 模型认证未在**Gateway 网关主机**上加载（检查 `models status`）。 - - 渠道配对/allowlist 阻止了回复（检查渠道配置 + 日志）。 - - WebChat/Dashboard 已打开，但没有使用正确的 token。 + - **Gateway 网关 主机**上没有加载模型认证（检查 `models status`）。 + - 渠道配对 / 允许列表阻止了回复（检查渠道配置 + 日志）。 + - WebChat / 仪表板打开时没有使用正确的令牌。 - 如果你是远程环境，请确认隧道/Tailscale 连接已建立，并且 - Gateway 网关 WebSocket 可访问。 + 如果你处于远程环境，请确认隧道 / Tailscale 连接已建立，并且 + Gateway WebSocket 可达。 - 文档： [渠道](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 + 文档：[渠道](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 - 这通常意味着 UI 丢失了 WebSocket 连接。请检查： + 这通常表示 UI 丢失了 WebSocket 连接。请检查： - 1. Gateway 网关是否正在运行？`openclaw gateway status` - 2. Gateway 网关是否健康？`openclaw status` - 3. UI 是否有正确的 token？`openclaw dashboard` - 4. 如果是远程环境，隧道/Tailscale 链路是否正常？ + 1. Gateway 网关 是否正在运行？`openclaw gateway status` + 2. Gateway 网关 是否健康？`openclaw status` + 3. UI 是否使用了正确的令牌？`openclaw dashboard` + 4. 如果是远程环境，隧道 / Tailscale 链路是否已建立？ 然后查看日志尾部： @@ -2988,31 +2995,31 @@ x-i18n: openclaw logs --follow ``` - 文档： [Dashboard](/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 + 文档：[仪表板](/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 - - 先看日志和渠道状态： + + 先查看日志和渠道状态： ```bash openclaw channels status openclaw channels logs --channel telegram ``` - 然后匹配错误： + 然后根据错误类型处理： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单项太多。OpenClaw 已经会裁剪到 Telegram 限制并用更少命令重试，但某些菜单项仍需要被移除。请减少插件/skill/自定义命令，或者如果你不需要菜单，禁用 `channels.telegram.commands.native`。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或在代理后面，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 解析正常。 + - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少的命令重试，但某些菜单项仍需要去掉。请减少插件 / skill / 自定义命令，或者如果你不需要菜单，就禁用 `channels.telegram.commands.native`。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或使用代理，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 正常工作。 - 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 + 如果 Gateway 网关 是远程的，请确保你查看的是 Gateway 网关 主机上的日志。 - 文档： [Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 + 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 - - 先确认 Gateway 网关可访问，并且智能体能够运行： + + 先确认 Gateway 网关 可达，并且智能体可以运行： ```bash openclaw status @@ -3020,53 +3027,53 @@ x-i18n: openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你期望在某个聊天 + 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在聊天 渠道中收到回复，请确保已启用投递（`/deliver on`）。 - 文档： [TUI](/web/tui)、[Slash commands](/zh-CN/tools/slash-commands)。 + 文档：[TUI](/web/tui)、[斜杠命令](/zh-CN/tools/slash-commands)。 - - 如果你已安装服务： + + 如果你安装了服务： ```bash openclaw gateway stop openclaw gateway start ``` - 这会停止/启动**受监督的服务**（macOS 上为 launchd，Linux 上为 systemd）。 - 当 Gateway 网关作为后台守护进程运行时，请使用这种方式。 + 这会停止 / 启动**受监管服务**（macOS 上为 launchd，Linux 上为 systemd）。 + 当 Gateway 网关 作为守护进程在后台运行时，请使用这种方式。 - 如果你是在前台运行，请用 Ctrl-C 停止，然后执行： + 如果你是在前台运行，请按 Ctrl-C 停止，然后： ```bash openclaw gateway run ``` - 文档： [Gateway 网关服务运行手册](/zh-CN/gateway)。 + 文档：[Gateway 网关 服务运行手册](/zh-CN/gateway)。 - - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - - `openclaw gateway`：在当前终端会话中**以前台方式**运行 Gateway 网关。 + - `openclaw gateway restart`：重启**后台服务**（launchd / systemd）。 + - `openclaw gateway`：在当前终端会话中**前台**运行 gateway。 - 如果你已经安装了服务，请使用 gateway 命令。只有当 - 你想进行一次性前台运行时，才使用 `openclaw gateway`。 + 如果你安装了服务，请使用 gateway 命令。当你 + 想进行一次性的前台运行时，请使用 `openclaw gateway`。 - 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台信息。然后检查日志文件，查看渠道认证、模型路由和 RPC 错误。 + 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 ## 媒体和附件 - - 智能体发出的附件必须包含一行 `MEDIA:`（单独占一行）。参见 [OpenClaw assistant 设置](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 + + 来自智能体的出站附件必须包含一行 `MEDIA:`（单独成行）。请参阅 [OpenClaw 助手设置](/zh-CN/start/openclaw) 和 [智能体发送](/zh-CN/tools/agent-send)。 CLI 发送： @@ -3076,12 +3083,12 @@ x-i18n: 还请检查： - - 目标渠道支持发送媒体，并且没有被 allowlist 阻止。 - - 文件没有超过提供商的大小限制（图片会被缩放到最长边 2048px）。 - - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 以及通过沙箱验证的文件中。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已经能够读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 以及 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 + - 目标渠道支持出站媒体，并且未被允许列表阻止。 + - 文件在提供商的大小限制内（图片会被调整到最大 2048px）。 + - `tools.fs.workspaceOnly=true` 会让本地路径发送仅限于工作区、temp / media-store 和经过沙箱校验的文件。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 - 参见 [Images](/zh-CN/nodes/images)。 + 请参阅 [图片](/zh-CN/nodes/images)。 @@ -3090,72 +3097,72 @@ x-i18n: - 应将入站私信视为不受信任输入。默认设置旨在降低风险： + 请将入站私信视为不受信任的输入。默认设置旨在降低风险： - - 支持私信的渠道默认行为是**配对**： + - 支持私信的渠道在默认情况下使用**配对**行为： - 未知发送者会收到一个配对码；机器人不会处理他们的消息。 - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - 待处理请求每个渠道最多 **3 个**；如果没有收到代码，请检查 `openclaw pairing list --channel [--account ]`。 - - 若要公开开放私信，需要显式选择加入（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 + - 公开开放私信需要显式选择加入（`dmPolicy: "open"` 和允许列表 `"*"`）。 - 运行 `openclaw doctor` 可以发现有风险的私信策略。 + 运行 `openclaw doctor` 以识别有风险的私信策略。 - - 不是。prompt injection 针对的是**不受信任的内容**，而不仅仅是谁能给机器人发私信。 - 如果你的助手会读取外部内容（web search/fetch、浏览器页面、邮件、 + + 不是。prompt injection 关乎的是**不受信任的内容**，而不仅仅是谁能给机器人发私信。 + 如果你的助手会读取外部内容（web 搜索 / 抓取、浏览器页面、电子邮件、 文档、附件、粘贴的日志），这些内容就可能包含试图 - 劫持模型的指令。即使**只有你自己是发送者**，这种情况也会发生。 + 劫持模型的指令。即使**你是唯一的发送者**，这也可能发生。 - 当启用工具时，风险最大：模型可能会被诱导去 - 泄露上下文，或代表你调用工具。可通过以下方式缩小影响范围： + 最大的风险出现在启用工具时：模型可能会被诱导去 + 泄露上下文或代表你调用工具。降低影响范围的方法包括： - - 使用只读或禁用工具的“reader”智能体来总结不受信任内容 + - 使用只读或禁用工具的“阅读器”智能体来总结不受信任的内容 - 对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 也将解码后的文件/文本文档视为不受信任：OpenResponses + - 同样将解码后的文件 / 文档文本视为不受信任：OpenResponses `input_file` 和媒体附件提取都会将提取出的文本包装在 明确的外部内容边界标记中，而不是直接传递原始文件文本 - - 使用沙箱隔离和严格的工具 allowlist + - 使用沙箱隔离和严格的工具允许列表 - 详情： [Security](/zh-CN/gateway/security)。 + 详情请参阅 [安全](/zh-CN/gateway/security)。 - - 对于大多数设置来说，应该有。使用独立账号和电话号码隔离机器人 - 可以在发生问题时缩小影响范围。这也让你更容易轮换 - 凭证或撤销访问权限，而不会影响你的个人账户。 + + 对于大多数部署来说，是的。用单独的账户和电话号码来隔离机器人 + 能在出问题时缩小影响范围。这也让你更容易轮换 + 凭据或撤销访问，而不影响你的个人账户。 - 从小范围开始。只授予它实际需要的工具和账户访问权限，必要时 + 从小处开始。只授予你实际需要的工具和账户访问权限，必要时 再逐步扩大。 - 文档： [Security](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 + 文档：[安全](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 我们**不**建议让它完全自主处理你的个人消息。最安全的模式是： - - 将私信保持在**配对模式**，或使用严格的 allowlist。 - - 如果你想让它代你发消息，请使用**单独的号码或账户**。 + - 将私信保持为**配对模式**或严格的允许列表。 + - 如果你希望它代表你发消息，请使用**单独的号码或账户**。 - 让它起草，然后在发送前**进行审批**。 - 如果你想尝试，请在专用账户上进行，并保持隔离。参见 - [Security](/zh-CN/gateway/security)。 + 如果你想尝试，请在专用账户上进行，并保持隔离。请参阅 + [安全](/zh-CN/gateway/security)。 - - 可以，**前提是**该智能体仅用于聊天，且输入是可信的。更小规格的模型 - 更容易被指令劫持，因此请避免将它们用于启用工具的智能体， - 或用于读取不受信任内容的场景。如果你必须使用更小的模型，请锁紧 - 工具权限并在沙箱中运行。参见 [Security](/zh-CN/gateway/security)。 + + 可以，**前提是**该智能体只用于聊天，且输入是可信的。更小档位的模型 + 更容易受到指令劫持，因此不要将它们用于启用了工具的智能体 + 或读取不受信任内容的场景。如果你必须使用更小的模型，请收紧 + 工具权限，并在沙箱中运行。请参阅 [安全](/zh-CN/gateway/security)。 - 配对码只会在未知发送者给机器人发消息，并且 - `dmPolicy: "pairing"` 已启用时发送。单独发送 `/start` 不会生成代码。 + 只有在未知发送者给机器人发送消息，且 + `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独的 `/start` 不会生成代码。 检查待处理请求： @@ -3163,12 +3170,12 @@ x-i18n: openclaw pairing list telegram ``` - 如果你想立即获得访问权限，请将你的 sender id 加入 allowlist，或为该账户设置 `dmPolicy: "open"`。 + 如果你想立即获得访问权限，请将你的发送者 id 加入允许列表，或为该账户设置 `dmPolicy: "open"`。 - - 不会。WhatsApp 私信默认策略是**配对**。未知发送者只会收到一个配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 + + 不会。WhatsApp 私信的默认策略是**配对**。未知发送者只会收到一个配对码，而且他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你明确触发的发送。 使用以下命令批准配对： @@ -3182,18 +3189,19 @@ x-i18n: openclaw pairing list whatsapp ``` - 向导中的电话号码提示：它用于设置你的**allowlist/owner**，以便允许你自己的私信。它不会用于自动发送。如果你是在自己的 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 + 向导中的电话号码提示用于设置你的**允许列表 / 所有者**，以便允许你自己的私信。它不会用于自动发送。如果你运行在自己的 WhatsApp 号码上，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、终止任务，以及“它停不下来” +## 聊天命令、中止任务和“它停不下来” - 大多数内部消息或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 + 大多数内部消息或工具消息只有在该会话启用了 **verbose**、**trace** 或 **reasoning** 时 + 才会出现。 - 在你看到这些内容的聊天中执行以下命令： + 在你看到这些消息的聊天中修复： ``` /verbose off @@ -3202,15 +3210,15 @@ x-i18n: ``` 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose - 设为 **inherit**。同时确认你没有使用在配置中将 `verboseDefault` 设为 - `on` 的机器人 profile。 + 设为 **inherit**。同时确认你没有在配置中使用将 `verboseDefault` 设为 + `on` 的机器人配置文件。 - 文档： [Thinking and verbose](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 + 文档：[思考和 verbose](/zh-CN/tools/thinking)、[安全](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 - - 将以下任意内容**作为单独消息发送**（不要加斜杠）： + + 发送以下任一内容，且**必须作为单独消息发送**（不要带斜杠）： ``` stop @@ -3234,23 +3242,23 @@ x-i18n: interrupt ``` - 这些都是终止触发词（不是 slash commands）。 + 这些都是中止触发词（不是斜杠命令）。 - 对于后台进程（来自 exec 工具），你可以让智能体执行： + 对于后台进程（来自 exec 工具），你可以让智能体运行： ``` process action:kill sessionId:XXX ``` - Slash commands 概览：参见 [Slash commands](/zh-CN/tools/slash-commands)。 + 斜杠命令概览：请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。 - 大多数命令都必须以**单独消息**形式发送，并且以 `/` 开头，但少数快捷方式（如 `/status`）也支持 allowlist 发送者内联使用。 + 大多数命令都必须作为一个**以 `/` 开头的单独消息**发送，但少数快捷方式（如 `/status`）对允许列表中的发送者也支持内联使用。 - OpenClaw 默认会阻止**跨提供商**消息发送。如果某个工具调用绑定到了 - Telegram，它就不会向 Discord 发送消息，除非你显式允许。 + OpenClaw 默认会阻止**跨提供商**消息发送。如果某个工具调用绑定 + 到 Telegram，它就不会发送到 Discord，除非你显式允许。 为该智能体启用跨提供商消息发送： @@ -3267,20 +3275,20 @@ x-i18n: } ``` - 编辑配置后，重启 Gateway 网关。 + 编辑配置后，重启 gateway。 - - 队列模式决定了新消息如何与正在进行中的运行交互。使用 `/queue` 更改模式： + + 队列模式控制新消息如何与正在进行中的运行交互。使用 `/queue` 更改模式： - `steer` - 新消息会重定向当前任务 - - `followup` - 一次处理一条消息 - - `collect` - 批量收集消息并只回复一次（默认） - - `steer-backlog` - 先立即重定向，再处理积压 - - `interrupt` - 终止当前运行并重新开始 + - `followup` - 消息逐条运行 + - `collect` - 批量收集消息并统一回复（默认） + - `steer-backlog` - 先重定向当前任务，再处理积压消息 + - `interrupt` - 中止当前运行并重新开始 - 你还可以添加诸如 `debounce:2s cap:25 drop:summarize` 的选项用于 followup 模式。 + 你还可以为 followup 模式添加选项，例如 `debounce:2s cap:25 drop:summarize`。 @@ -3288,11 +3296,11 @@ x-i18n: ## 杂项 - - 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在 auth profiles 中存储 Anthropic API key）会启用认证，但实际默认模型仍然是你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，说明 Gateway 网关无法在当前运行智能体所对应的 `auth-profiles.json` 中找到 Anthropic 凭证。 + + 在 OpenClaw 中，凭据和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在认证配置文件中存储 Anthropic API 密钥）会启用认证，但实际的默认模型仍然是你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这意味着 Gateway 网关 无法在当前运行的智能体所使用的预期 `auth-profiles.json` 中找到 Anthropic 凭据。 --- -还是卡住了？请到 [Discord](https://discord.com/invite/clawd) 提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 +如果还是卡住了？请到 [Discord](https://discord.com/invite/clawd) 提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 4392fd57a..ce56628ee 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -1,41 +1,41 @@ --- read_when: - 添加由智能体控制的浏览器自动化 - - 调试为什么 openclaw 会干扰你自己的 Chrome + - 调试为什么 openclaw 正在干扰你自己的 Chrome - 在 macOS 应用中实现浏览器设置 + 生命周期管理 -summary: 集成式浏览器控制服务 + 操作命令 +summary: 集成的浏览器控制服务 + 操作命令 title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-19T09:45:16Z" + generated_at: "2026-04-19T10:22:57Z" model: gpt-5.4 provider: openai - source_hash: dac051a4e963545af045f97e2222777595c1a0865170dcc15407932f21703fd0 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- # 浏览器（由 openclaw 管理） -OpenClaw 可以运行一个**专用的 Chrome/Brave/Edge/Chromium 配置文件**，由智能体控制。 -它与你的个人浏览器相互隔离，并通过 Gateway 网关 内部一个小型本地控制服务进行管理 +OpenClaw 可以运行一个**专用的 Chrome / Brave / Edge / Chromium 配置文件**，由智能体控制。 +它与你的个人浏览器隔离，并通过 Gateway 网关 内部的一个小型本地控制服务进行管理 （仅限 loopback）。 -面向初学者的理解方式： +初学者视角： -- 把它看作一个**独立的、仅供智能体使用的浏览器**。 +- 可以把它看作是一个**独立的、仅供智能体使用的浏览器**。 - `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 - 智能体可以在一个安全通道中**打开标签页、读取页面、点击和输入**。 - 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实已登录的 Chrome 会话。 -## 你将获得什么 +## 你会获得什么 - 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 -- 可预测的标签页控制（列出/打开/聚焦/关闭）。 -- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。 -- 可选的多配置文件支持（`openclaw`、`work`、`remote`，等等）。 +- 确定性的标签页控制（列出 / 打开 / 聚焦 / 关闭）。 +- 智能体操作（点击 / 输入 / 拖动 / 选择）、快照、截图、PDF。 +- 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。 -这个浏览器**不是**你日常使用的主力浏览器。它是一个安全、隔离的界面， -用于智能体自动化和验证。 +这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的界面，用于 +智能体自动化与验证。 ## 快速开始 @@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -如果你看到“浏览器已禁用”，请在配置中启用它（见下文），然后重启 +如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。 -如果 `openclaw browser` 命令完全不存在，或者智能体提示浏览器工具 -不可用，请跳转到[缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 +如果 `openclaw browser` 完全不存在，或者智能体提示浏览器工具不可用， +请跳转到[缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 ## 插件控制 默认的 `browser` 工具现在是一个默认启用的内置插件。 -这意味着你可以在不移除 OpenClaw 其余插件系统的情况下禁用或替换它： +这意味着你可以禁用或替换它，而无需移除 OpenClaw 的其余插件系统： ```json5 { @@ -69,28 +69,28 @@ Gateway 网关。 } ``` -在安装另一个提供相同 `browser` 工具名称的插件之前，请先禁用这个内置插件。 -默认浏览器体验需要同时满足以下条件： +在安装另一个提供相同 `browser` 工具名称的插件之前，请先禁用内置插件。 +默认浏览器体验需要同时满足以下两点： - `plugins.entries.browser.enabled` 未被禁用 - `browser.enabled=true` -如果你只关闭了插件，那么内置浏览器 CLI（`openclaw browser`）、 -Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览器控制 -服务都会一起消失。你的 `browser.*` 配置会保持不变，以便替换插件复用。 +如果你只关闭插件，那么内置浏览器 CLI（`openclaw browser`）、 +Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览器控制服务都会一起消失。 +你的 `browser.*` 配置会保持不变，供替代插件复用。 -内置浏览器插件现在也负责浏览器运行时实现。 -核心部分仅保留共享的插件 SDK 辅助工具，以及用于兼容旧内部导入路径的重新导出。 -实际上，移除或替换浏览器插件包会移除整套浏览器功能，而不是留下第二套 -由核心拥有的运行时。 +内置浏览器插件现在也拥有浏览器运行时实现。 +核心仅保留共享的插件 SDK 辅助工具，以及为旧的内部导入路径提供兼容性重新导出。 +在实际效果上，移除或替换浏览器插件包会移除整套浏览器功能， +而不是留下第二套由核心拥有的运行时实现。 -浏览器配置变更仍然需要重启 Gateway 网关，以便内置插件根据新设置重新注册 -其浏览器服务。 +浏览器配置更改仍然需要重启 Gateway 网关，这样内置插件才能用新设置重新注册其浏览器服务。 ## 缺少浏览器命令或工具 -如果 `openclaw browser` 在升级后突然变成未知命令，或者智能体报告浏览器工具缺失， -最常见的原因是一个过于严格的 `plugins.allow` 列表，其中没有包含 `browser`。 +如果 `openclaw browser` 在升级后突然变成未知命令，或者 +智能体报告浏览器工具缺失，最常见的原因是 +限制性的 `plugins.allow` 列表中没有包含 `browser`。 错误配置示例： @@ -102,7 +102,7 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 } ``` -通过将 `browser` 添加到插件白名单来修复： +可通过将 `browser` 添加到插件允许列表来修复： ```json5 { @@ -114,10 +114,10 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 重要说明： -- 当设置了 `plugins.allow` 时，仅有 `browser.enabled=true` 本身是不够的。 +- 当设置了 `plugins.allow` 时，仅有 `browser.enabled=true` 本身并不够。 - 当设置了 `plugins.allow` 时，仅有 `plugins.entries.browser.enabled=true` 本身也不够。 - `tools.alsoAllow: ["browser"]` **不会**加载内置浏览器插件。它只会在插件已加载后调整工具策略。 -- 如果你不需要严格的插件白名单，删除 `plugins.allow` 也可以恢复默认的内置浏览器行为。 +- 如果你不需要限制性的插件允许列表，删除 `plugins.allow` 也可以恢复默认的内置浏览器行为。 典型症状： @@ -134,11 +134,10 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有已登录会话很重要，并且用户就在电脑前可点击/批准任何附加提示时， - 优先使用 `profile="user"`。 +- 当现有登录会话很重要，并且用户就在电脑前可以点击 / 批准任何附加提示时，优先使用 `profile="user"`。 - 当你想指定某种浏览器模式时，`profile` 是显式覆盖项。 -如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 +如果你想默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 ## 配置 @@ -147,16 +146,16 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 ```json5 { browser: { - enabled: true, // 默认值：true + enabled: true, // default: true 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"], }, - // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖项 - remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时时间（毫秒） - remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时时间（毫秒） + // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override + remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -185,31 +184,32 @@ Gateway 网关 方法（`browser.request`）、智能体工具以及默认浏览 说明： -- 浏览器控制服务会绑定到一个基于 `gateway.port` - 派生出的 loopback 端口（默认是 `18791`，即 gateway + 2）。 +- 浏览器控制服务会绑定到一个基于 `gateway.port` 推导出的 loopback 端口 + （默认：`18791`，即 Gateway 网关 端口 + 2）。 - 如果你覆盖了 Gateway 网关 端口（`gateway.port` 或 `OPENCLAW_GATEWAY_PORT`）， - 派生的浏览器端口也会随之变化，以保持在同一个“族”中。 -- 如果未设置，`cdpUrl` 默认使用受管理的本地 CDP 端口。 + 派生出的浏览器端口也会一并偏移，以保持属于同一个“端口家族”。 +- 未设置时，`cdpUrl` 默认为受管理的本地 CDP 端口。 - `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP 可达性检查。 - `remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 可达性检查。 -- 浏览器导航/打开标签页在导航前会经过 SSRF 防护，并在导航后对最终的 `http(s)` URL 进行尽力的再次检查。 -- 在严格 SSRF 模式下，远程 CDP 端点发现/探测（`cdpUrl`，包括 `/json/version` 查询）也会被检查。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认禁用。只有在你明确信任私有网络浏览器访问时，才将其设为 `true`。 -- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为兼容性旧版别名受到支持。 -- `attachOnly: true` 的意思是“绝不启动本地浏览器；仅在它已运行时进行附加”。 -- `color` 和每个配置文件的 `color` 会为浏览器 UI 着色，这样你就能看到当前哪个配置文件处于活动状态。 -- 默认配置文件是 `openclaw`（由 OpenClaw 管理的独立浏览器）。使用 `defaultProfile: "user"` 可切换为已登录的用户浏览器。 -- 自动检测顺序：如果系统默认浏览器是基于 Chromium，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序。 -- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl` —— 只有远程 CDP 才需要设置这些值。 -- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。对于这个驱动， +- 浏览器导航 / 打开标签页会在导航前受到 SSRF 防护，并在导航后对最终的 `http(s)` URL 进行尽力复检。 +- 在严格 SSRF 模式下，远程 CDP 端点发现 / 探测（`cdpUrl`，包括 `/json/version` 查找）也会被检查。 +- 默认禁用 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`。只有在你有意信任私有网络浏览器访问时，才将其设为 `true`。 +- `browser.ssrfPolicy.allowPrivateNetwork` 仍作为兼容性的旧别名受到支持。 +- `attachOnly: true` 表示“绝不启动本地浏览器；仅在浏览器已运行时附加。” +- `color` 及各配置文件的 `color` 会为浏览器 UI 着色，便于你识别当前活跃的是哪个配置文件。 +- 默认配置文件是 `openclaw`（由 OpenClaw 管理的独立浏览器）。使用 `defaultProfile: "user"` 可选择默认进入已登录用户浏览器。 +- 自动检测顺序：如果系统默认浏览器是 Chromium 内核，则优先使用它；否则依次为 Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort` / `cdpUrl` —— 仅在远程 CDP 场景下设置这些值。 +- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。对于该驱动， 不要设置 `cdpUrl`。 -- 当某个 existing-session 配置文件需要附加到一个非默认的 Chromium 用户配置文件时， - 例如 Brave 或 Edge，请设置 `browser.profiles..userDataDir`。 +- 当 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（例如 Brave 或 Edge）时， + 请设置 `browser.profiles..userDataDir`。 ## 使用 Brave（或其他基于 Chromium 的浏览器） -如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等）， -OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖自动检测： +如果你的**系统默认**浏览器是基于 Chromium 的（Chrome / Brave / Edge 等）， +OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖 +自动检测： CLI 示例： @@ -243,49 +243,49 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## 本地控制与远程控制 - **本地控制（默认）：** Gateway 网关 启动 loopback 控制服务，并可启动本地浏览器。 -- **远程控制（节点主机）：** 在拥有浏览器的那台机器上运行一个节点主机；Gateway 网关 会将浏览器操作代理到它。 -- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以附加到 - 一个远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 +- **远程控制（节点主机）：** 在拥有浏览器的机器上运行一个节点主机；Gateway 网关 会将浏览器操作代理到该节点主机。 +- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以 + 附加到远程的 Chromium 内核浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 -停止行为会根据配置文件模式而有所不同： +停止行为会因配置文件模式而不同： - 本地受管理配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程 -- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前活动的 - 控制会话，并释放 Playwright/CDP 模拟覆盖项（视口、 - 配色方案、区域设置、时区、离线模式及类似状态），即使 +- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前活跃的 + 控制会话，并释放 Playwright / CDP 仿真覆盖项（视口、 + 配色方案、区域设置、时区、离线模式以及类似状态），即使 OpenClaw 并未启动任何浏览器进程 远程 CDP URL 可以包含认证信息： -- 查询令牌（例如 `https://provider.example?token=`） +- 查询参数 token（例如 `https://provider.example?token=`） - HTTP Basic 认证（例如 `https://user:pass@provider.example`） OpenClaw 在调用 `/json/*` 端点以及连接 -CDP WebSocket 时都会保留这些认证信息。对于令牌，优先使用环境变量或密钥管理器， +CDP WebSocket 时都会保留认证信息。对于 token，优先使用环境变量或密钥管理器， 而不是将它们提交到配置文件中。 ## 节点浏览器代理（默认零配置） -如果你在拥有浏览器的那台机器上运行一个**节点主机**，OpenClaw 可以 -在无需任何额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。 +如果你在拥有浏览器的机器上运行了一个**节点主机**，OpenClaw 可以 +自动将浏览器工具调用路由到该节点，而无需任何额外的浏览器配置。 这是远程 Gateway 网关 的默认路径。 说明： -- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。 -- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可获得旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有白名单中的配置文件可以作为目标，并且代理界面上的持久化配置文件创建/删除路由会被阻止。 -- 如果你不想启用它，可以禁用： +- 节点主机会通过一个**代理命令**公开其本地浏览器控制服务器。 +- 配置文件来自节点自己的 `browser.profiles` 配置（与本地相同）。 +- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空即可使用旧版 / 默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建 / 删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可以被访问，并且持久化配置文件的创建 / 删除路由会在代理层被阻止。 +- 如果你不想启用它，可以关闭： - 在节点上：`nodeHost.browserProxy.enabled=false` - - 在 gateway 上：`gateway.nodes.browser.mode="off"` + - 在 Gateway 网关 上：`gateway.nodes.browser.mode="off"` ## Browserless（托管远程 CDP） -[Browserless](https://browserless.io) 是一项托管式 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 -CDP 连接 URL。OpenClaw 可以使用其中任意一种形式，但对于远程浏览器配置文件， -最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。 +[Browserless](https://browserless.io) 是一个托管式 Chromium 服务， +通过 HTTPS 和 WebSocket 提供 CDP 连接 URL。OpenClaw 可以使用这两种形式，但 +对于远程浏览器配置文件，最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。 示例： @@ -308,43 +308,43 @@ CDP 连接 URL。OpenClaw 可以使用其中任意一种形式，但对于远程 说明： -- 请将 `` 替换为你真实的 Browserless 令牌。 -- 请选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 +- 将 `` 替换为你真实的 Browserless token。 +- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 - 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将它转换为 `wss://` 以建立直接 CDP 连接，或者保留 HTTPS URL，让 OpenClaw - 自动发现 `/json/version`。 + 去发现 `/json/version`。 ## 直接 WebSocket CDP 提供商 -某些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是 +一些托管浏览器服务提供的是**直接 WebSocket** 端点，而不是 标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： - **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。 - OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后 - 建立连接。不提供 WebSocket 回退。 + OpenClaw 会调用 `/json/version` 来发现 WebSocket 调试器 URL，然后进行 + 连接。不会回退到 WebSocket。 - **直接 WebSocket 端点** — `ws://host[:port]/devtools//` 或 - `wss://...`，路径为 `/devtools/browser|page|worker|shared_worker|service_worker/`。 - OpenClaw 会通过 WebSocket 握手直接连接，并完全跳过 + `wss://...`，并带有 `/devtools/browser|page|worker|shared_worker|service_worker/` + 路径。OpenClaw 会通过 WebSocket 握手直接连接，并完全跳过 `/json/version`。 -- **裸 WebSocket 根地址** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 +- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、 - [Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP - `/json/version` 发现（将协议规范化为 `http`/`https`）； - 如果发现过程返回了 `webSocketDebuggerUrl`，则使用它；否则 OpenClaw - 会回退到在裸根地址上直接进行 WebSocket 握手。这同时覆盖了 - Chrome 风格的远程调试端口和仅支持 WebSocket 的提供商。 + [Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试通过 HTTP + `/json/version` 进行发现（将协议标准化为 `http` / `https`）； + 如果发现结果返回了 `webSocketDebuggerUrl`，则使用它，否则 OpenClaw + 会回退为在裸根路径上直接执行 WebSocket 握手。这同时覆盖了 + Chrome 风格的远程调试端口和仅提供 WebSocket 的服务商。 -不带 `/devtools/...` 路径的普通 `ws://host:port` / `wss://host:port`， -如果指向本地 Chrome 实例，也可通过“先发现、后回退”的方式获得支持—— -Chrome 只接受在 `/json/version` 返回的特定浏览器级 -或目标级路径上进行 WebSocket 升级，因此仅使用裸根地址握手 -会失败。 +对于没有 `/devtools/...` 路径、直接指向本地 Chrome 实例的普通 +`ws://host:port` / `wss://host:port`， +也可通过“先发现、后回退”的方式得到支持——Chrome 仅接受针对 `/json/version` +返回的特定每浏览器或每目标路径的 WebSocket 升级， +因此单独对裸根路径进行握手会失败。 ### Browserbase [Browserbase](https://www.browserbase.com) 是一个云平台，用于运行 -无头浏览器，并内置 CAPTCHA 求解、隐身模式和住宅代理。 +无头浏览器，内置 CAPTCHA 求解、隐身模式和住宅代理。 ```json5 { @@ -365,78 +365,77 @@ Chrome 只接受在 `/json/version` 返回的特定浏览器级 说明： -- [注册](https://www.browserbase.com/sign-up) 并从 [概览仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。 -- 请将 `` 替换为你真实的 Browserbase API key。 +- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 控制台](https://www.browserbase.com/overview) + 复制你的 **API Key**。 +- 将 `` 替换为你真实的 Browserbase API key。 - Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此 不需要手动创建会话。 -- 免费套餐允许一个并发会话以及每月一个浏览器小时。 - 付费套餐限制请参见 [pricing](https://www.browserbase.com/pricing)。 -- 完整的 API 参考、SDK 指南和集成示例，请参见 [Browserbase docs](https://docs.browserbase.com)。 +- 免费套餐每月允许一个并发会话和一个浏览器小时。 + 付费套餐限制请参见 [定价](https://www.browserbase.com/pricing)。 +- 完整的 API 参考、SDK 指南和集成示例，请参见 [Browserbase 文档](https://docs.browserbase.com)。 ## 安全性 关键概念： -- 浏览器控制仅限 loopback；访问通过 Gateway 网关 的认证或节点配对来完成。 -- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证： - gateway token Bearer 认证、`x-openclaw-password`，或使用 - 已配置 gateway 密码的 HTTP Basic 认证。 +- 浏览器控制仅限 loopback；访问通过 Gateway 网关 的认证或节点配对来实现。 +- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**： + Gateway 网关 token Bearer 认证、`x-openclaw-password`，或使用 + 已配置 Gateway 网关 密码的 HTTP Basic 认证。 - Tailscale Serve 身份头以及 `gateway.auth.mode: "trusted-proxy"` - **不能**用于认证这个独立的 loopback 浏览器 API。 -- 如果启用了浏览器控制，但没有配置共享密钥认证，OpenClaw + **不会**为这个独立的 loopback 浏览器 API 提供认证。 +- 如果启用了浏览器控制但未配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。 -- 如果 `gateway.auth.mode` 已经是 - `password`、`none` 或 `trusted-proxy`，OpenClaw **不会**自动生成该 token。 -- 请将 Gateway 网关 和所有节点主机保持在私有网络（Tailscale）中；避免公开暴露。 -- 将远程 CDP URL/token 视为密钥；优先使用环境变量或密钥管理器。 +- 当 `gateway.auth.mode` 已经是 + `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。 +- 请将 Gateway 网关 和任何节点主机保留在私有网络中（Tailscale）；避免公开暴露。 +- 将远程 CDP URL / token 视为密钥；优先使用环境变量或密钥管理器。 远程 CDP 提示： -- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短期有效 token。 -- 避免将长期有效 token 直接嵌入配置文件。 +- 尽可能优先使用加密端点（HTTPS 或 WSS）以及短时效 token。 +- 避免将长期有效的 token 直接写入配置文件。 ## 配置文件（多浏览器） -OpenClaw 支持多个具名配置文件（路由配置）。配置文件可以是： +OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： -- **由 openclaw 管理**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口 -- **远程**：一个显式的 CDP URL（运行在其他位置的基于 Chromium 的浏览器） -- **现有会话**：通过 Chrome DevTools MCP 自动连接你现有的 Chrome 配置文件 +- **由 openclaw 管理**：一个专用的 Chromium 内核浏览器实例，拥有自己的用户数据目录和 CDP 端口 +- **远程**：一个显式的 CDP URL（运行在其他地方的 Chromium 内核浏览器） +- **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件 默认值： - 如果缺失，会自动创建 `openclaw` 配置文件。 - `user` 配置文件是内置的，用于 Chrome MCP 现有会话附加。 -- 除了 `user` 之外，existing-session 配置文件都需要显式启用；使用 `--driver existing-session` 创建它们。 -- 本地 CDP 端口默认从 **18800–18899** 范围分配。 -- 删除配置文件会将其本地数据目录移动到废纸篓。 +- 除 `user` 外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建它们。 +- 本地 CDP 端口默认从 **18800–18899** 分配。 +- 删除配置文件时，其本地数据目录会被移到废纸篓。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 -## 通过 Chrome DevTools MCP 使用现有会话 +## 通过 Chrome DevTools MCP 连接现有会话 -OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的 -基于 Chromium 的浏览器配置文件。这会复用该浏览器配置文件中 -已打开的标签页和登录状态。 +OpenClaw 也可以通过官方的 Chrome DevTools MCP 服务器，附加到一个正在运行的 Chromium 内核浏览器配置文件。 +这会复用该浏览器配置文件中已经打开的标签页和登录状态。 官方背景与设置参考： -- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers：将 Chrome DevTools MCP 与你的浏览器会话一起使用](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) 内置配置文件： - `user` -可选：如果你想使用不同的名称、颜色或浏览器数据目录， -可以创建自己的自定义 existing-session 配置文件。 +可选：如果你想要不同的名称、颜色或浏览器数据目录，也可以创建你自己的自定义 existing-session 配置文件。 默认行为： -- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，其目标是 +- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是 默认的本地 Google Chrome 配置文件。 -对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`： +对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`： ```json5 { @@ -453,13 +452,13 @@ OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运 } ``` -然后在对应浏览器中： +然后在对应的浏览器中： 1. 打开该浏览器用于远程调试的 inspect 页面。 2. 启用远程调试。 3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 -常见 inspect 页面： +常见的 inspect 页面： - Chrome：`chrome://inspect/#remote-debugging` - Brave：`brave://inspect/#remote-debugging` @@ -479,38 +478,38 @@ openclaw browser --browser-profile user snapshot --format ai - `status` 显示 `driver: existing-session` - `status` 显示 `transport: chrome-mcp` - `status` 显示 `running: true` -- `tabs` 会列出你已经打开的浏览器标签页 -- `snapshot` 会返回所选实时标签页中的 refs +- `tabs` 列出你已打开的浏览器标签页 +- `snapshot` 返回所选实时标签页中的 refs -如果附加失败，请检查： +如果附加不起作用，请检查： -- 目标的基于 Chromium 的浏览器版本为 `144+` -- 已在该浏览器的 inspect 页面中启用远程调试 -- 浏览器已显示附加同意提示，且你已接受 +- 目标 Chromium 内核浏览器版本是否为 `144+` +- 是否已在该浏览器的 inspect 页面中启用远程调试 +- 浏览器是否显示了附加授权提示，并且你已接受 - `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查 - 对于默认自动连接配置文件，本地是否安装了 Chrome，但它无法 - 替你在浏览器端启用远程调试 + 默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你 + 启用浏览器端的远程调试 -智能体使用： +智能体用法： -- 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 -- 如果你使用的是自定义 existing-session 配置文件，请传入该明确的配置文件名。 -- 只有当用户就在电脑前、可以批准附加提示时，才选择这种模式。 +- 当你需要用户的已登录浏览器状态时，使用 `profile="user"`。 +- 如果你使用自定义 existing-session 配置文件，请传入该显式配置文件名。 +- 仅当用户就在电脑前、可以批准附加提示时，才选择这种模式。 - Gateway 网关 或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` 说明： -- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以 - 在你的已登录浏览器会话中执行操作。 -- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加到一个 +- 这条路径比隔离的 `openclaw` 配置文件风险更高，因为它可以 + 在你已登录的浏览器会话中执行操作。 +- 对于该驱动，OpenClaw 不会启动浏览器；它只会附加到 现有会话。 - OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果 - 设置了 `userDataDir`，OpenClaw 会将其传递下去，以显式定位该 + 设置了 `userDataDir`，OpenClaw 会将其透传，以定位到该显式的 Chromium 用户数据目录。 -- existing-session 截图支持页面截图以及基于快照的 `--ref` 元素 - 截图，但不支持 CSS `--element` 选择器。 -- existing-session 页面截图无需 Playwright，即可通过 Chrome MCP 工作。 - 基于 ref 的元素截图（`--ref`）也可用，但 `--full-page` +- existing-session 截图支持页面捕获和基于快照的 `--ref` 元素 + 捕获，但不支持 CSS `--element` 选择器。 +- existing-session 页面截图无需 Playwright，直接通过 Chrome MCP 即可工作。 + 基于 ref 的元素截图（`--ref`）在那里同样可用，但 `--full-page` 不能与 `--ref` 或 `--element` 组合使用。 - 与受管理浏览器路径相比，existing-session 操作仍然更受限制： - `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 @@ -518,27 +517,28 @@ openclaw browser --browser-profile user snapshot --format ai - `click` 仅支持左键（不支持按钮覆盖或修饰键） - `type` 不支持 `slowly=true`；请改用 `fill` 或 `press` - `press` 不支持 `delayMs` - - `hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持 - 每次调用的超时覆盖 - - `select` 目前仅支持单个值 -- existing-session 的 `wait --url` 与其他浏览器驱动一样，支持精确匹配、子串匹配和 glob 模式。 - 但 `wait --load networkidle` 目前尚不支持。 -- existing-session 上传 hook 需要 `ref` 或 `inputRef`，一次只支持一个文件， - 并且不支持 CSS `element` 定位。 + - `hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不 + 支持按调用设置超时覆盖 + - `select` 当前仅支持单个值 +- 与其他浏览器驱动一样，existing-session `wait --url` 支持精确匹配、子串匹配和 glob 模式。 + 但暂不支持 `wait --load networkidle`。 +- existing-session 上传 hook 要求使用 `ref` 或 `inputRef`，一次只支持一个文件， + 且不支持 CSS `element` 定位。 - existing-session 对话框 hook 不支持超时覆盖。 - 某些功能仍然需要受管理浏览器路径，包括批量操作、PDF 导出、下载拦截和 `responsebody`。 -- existing-session 是主机本地的。如果 Chrome 位于另一台机器或 - 不同的网络命名空间中，请改用远程 CDP 或节点主机。 +- existing-session 可以附加到所选主机，或通过已连接的 + 浏览器节点附加。如果 Chrome 位于其他地方且没有连接浏览器节点，请改用 + 远程 CDP 或节点主机。 ## 隔离保证 - **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 - **专用端口**：避免使用 `9222`，以防与开发工作流冲突。 -- **可预测的标签页控制**：通过 `targetId` 定位标签页，而不是“最后一个标签页”。 +- **确定性的标签页控制**：通过 `targetId` 定位标签页，而不是“最后一个标签页”。 ## 浏览器选择 -在本地启动时，OpenClaw 会选择第一个可用项： +在本地启动时，OpenClaw 会选择第一个可用的浏览器： 1. Chrome 2. Brave @@ -546,7 +546,7 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -你可以通过 `browser.executablePath` 进行覆盖。 +你可以使用 `browser.executablePath` 进行覆盖。 平台说明： @@ -556,11 +556,11 @@ openclaw browser --browser-profile user snapshot --format ai ## 控制 API（可选） -仅用于本地集成时，Gateway 网关 会暴露一个小型 loopback HTTP API： +仅用于本地集成时，Gateway 网关 会公开一个小型的 loopback HTTP API： -- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop` +- 状态 / 启动 / 停止：`GET /`、`POST /start`、`POST /stop` - 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId` -- 快照/截图：`GET /snapshot`、`POST /screenshot` +- 快照 / 截图：`GET /snapshot`、`POST /screenshot` - 操作：`POST /navigate`、`POST /act` - Hooks：`POST /hooks/file-chooser`、`POST /hooks/dialog` - 下载：`POST /download`、`POST /wait/download` @@ -573,7 +573,7 @@ openclaw browser --browser-profile user snapshot --format ai 所有端点都接受 `?profile=`。 -如果配置了共享密钥 gateway 认证，浏览器 HTTP 路由也需要认证： +如果配置了共享密钥 Gateway 网关 认证，浏览器 HTTP 路由也会要求认证： - `Authorization: Bearer ` - `x-openclaw-password: ` 或使用该密码的 HTTP Basic 认证 @@ -582,12 +582,12 @@ openclaw browser --browser-profile user snapshot --format ai - 这个独立的 loopback 浏览器 API **不会**使用 trusted-proxy 或 Tailscale Serve 身份头。 -- 如果 `gateway.auth.mode` 为 `none` 或 `trusted-proxy`，这些 loopback 浏览器 - 路由不会继承这些带有身份信息的模式；请保持它们仅限 loopback。 +- 如果 `gateway.auth.mode` 是 `none` 或 `trusted-proxy`，这些 loopback 浏览器 + 路由不会继承这些携带身份的模式；请保持它们仅限 loopback。 ### `/act` 错误契约 -`POST /act` 对路由级校验和 +`POST /act` 对路由级验证和 策略失败使用结构化错误响应： ```json @@ -596,26 +596,26 @@ openclaw browser --browser-profile user snapshot --format ai 当前 `code` 值： -- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind` 或其值无法识别。 -- `ACT_INVALID_REQUEST`（HTTP 400）：操作负载在规范化或校验时失败。 -- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不支持的操作类型中使用了 `selector`。 +- `ACT_KIND_REQUIRED`（HTTP 400）：缺少 `kind`，或其值无法识别。 +- `ACT_INVALID_REQUEST`（HTTP 400）：操作载荷未能通过规范化或验证。 +- `ACT_SELECTOR_UNSUPPORTED`（HTTP 400）：在不受支持的操作类型中使用了 `selector`。 - `ACT_EVALUATE_DISABLED`（HTTP 403）：配置中禁用了 `evaluate`（或 `wait --fn`）。 - `ACT_TARGET_ID_MISMATCH`（HTTP 403）：顶层或批量的 `targetId` 与请求目标冲突。 -- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：该操作不支持 existing-session 配置文件。 +- `ACT_EXISTING_SESSION_UNSUPPORTED`（HTTP 501）：existing-session 配置文件不支持该操作。 -其他运行时失败仍可能返回不带 -`code` 字段的 `{ "error": "" }`。 +其他运行时失败仍可能返回 `{ "error": "" }`，而不包含 +`code` 字段。 ### Playwright 要求 -某些功能（navigate/act/AI snapshot/role snapshot、元素截图、 +某些功能（`navigate` / `act` / AI 快照 / role 快照、元素截图、 PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回 -清晰的 501 错误。 +明确的 501 错误。 -在没有 Playwright 的情况下，以下功能仍然可用： +在没有 Playwright 的情况下仍可使用的功能： - ARIA 快照 -- 当每个标签页的 CDP WebSocket 可用时，受管理 `openclaw` 浏览器的页面截图 +- 当可用每标签页 CDP WebSocket 时，受管理 `openclaw` 浏览器的页面截图 - `existing-session` / Chrome MCP 配置文件的页面截图 - 来自快照输出的 `existing-session` 基于 ref 的截图（`--ref`） @@ -631,42 +631,43 @@ PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回 not supported for element screenshots`。 如果你看到 `Playwright is not available in this gateway build`，请安装完整的 -Playwright 包（不是 `playwright-core`）并重启 gateway，或者重新安装 -带浏览器支持的 OpenClaw。 +Playwright 包（不是 `playwright-core`）并重启 Gateway 网关，或者重新安装 +带有浏览器支持的 OpenClaw。 #### Docker Playwright 安装 -如果你的 Gateway 网关 运行在 Docker 中，请避免使用 `npx playwright`（会有 npm 覆盖冲突）。 -请改用内置 CLI： +如果你的 Gateway 网关 运行在 Docker 中，请避免使用 `npx playwright` +（会与 npm override 冲突）。 +请改用内置的 CLI： ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -要持久化浏览器下载，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如， +要持久保存浏览器下载内容，请设置 `PLAYWRIGHT_BROWSERS_PATH`（例如 `/home/node/.cache/ms-playwright`），并确保通过 -`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。参见 [Docker](/zh-CN/install/docker)。 +`OPENCLAW_HOME_VOLUME` 或 bind mount 持久化 `/home/node`。请参见 [Docker](/zh-CN/install/docker)。 ## 工作原理（内部） 高层流程： - 一个小型**控制服务器**接收 HTTP 请求。 -- 它通过 **CDP** 连接到基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）。 -- 对于高级操作（点击/输入/快照/PDF），它会在 +- 它通过 **CDP** 连接到基于 Chromium 的浏览器（Chrome / Brave / Edge / Chromium）。 +- 对于高级操作（点击 / 输入 / 快照 / PDF），它会在 CDP 之上使用 **Playwright**。 - 当缺少 Playwright 时，只有不依赖 Playwright 的操作可用。 -这种设计为智能体提供了一个稳定、可预测的接口，同时允许 -你切换本地/远程浏览器和不同配置文件。 +这种设计让智能体始终面对一个稳定、确定性的接口，同时允许 +你切换本地 / 远程浏览器和配置文件。 ## CLI 快速参考 -所有命令都接受 `--browser-profile `，用于指定目标配置文件。 -所有命令也都接受 `--json`，用于机器可读输出（稳定负载）。 +所有命令都接受 `--browser-profile ` 来指定目标配置文件。 +所有命令也都接受 `--json` 以输出机器可读格式（稳定载荷）。 -基础操作： +基础命令： - `openclaw browser status` - `openclaw browser start` @@ -680,7 +681,7 @@ docker compose run --rm openclaw-cli \ - `openclaw browser focus abcd1234` - `openclaw browser close abcd1234` -检查： +检查命令： - `openclaw browser screenshot` - `openclaw browser screenshot --full-page` @@ -697,16 +698,15 @@ docker compose run --rm openclaw-cli \ 生命周期说明： -- 对于仅附加和远程 CDP 配置文件，`openclaw browser stop` 仍然是 - 测试完成后的正确清理命令。它会关闭当前活动的控制会话，并清除临时模拟覆盖项， - 而不是终止底层 +- 对于仅附加和远程 CDP 配置文件，在测试后仍然应该使用 + `openclaw browser stop` 进行清理。它会关闭当前活跃的控制会话，并清除临时仿真覆盖项，而不是终止底层 浏览器。 - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` - `openclaw browser responsebody "**/api" --max-chars 5000` -操作： +操作命令： - `openclaw browser navigate https://example.com` - `openclaw browser resize 1280 720` @@ -730,7 +730,7 @@ docker compose run --rm openclaw-cli \ - `openclaw browser trace start` - `openclaw browser trace stop` -状态： +状态命令： - `openclaw browser cookies` - `openclaw browser cookies set session abc123 --url "https://example.com"` @@ -751,59 +751,59 @@ docker compose run --rm openclaw-cli \ 说明： -- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器/对话框的点击或按键之前先运行它们。 -- 下载和 trace 输出路径被限制在 OpenClaw 临时根目录中： - - traces：`/tmp/openclaw`（回退为：`${os.tmpdir()}/openclaw`） - - downloads：`/tmp/openclaw/downloads`（回退为：`${os.tmpdir()}/openclaw/downloads`） -- 上传路径被限制在 OpenClaw 临时 uploads 根目录中： - - uploads：`/tmp/openclaw/uploads`（回退为：`${os.tmpdir()}/openclaw/uploads`） -- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。 +- `upload` 和 `dialog` 是**预置**调用；请在触发文件选择器 / 对话框的点击 / 按键之前先运行它们。 +- 下载和 trace 输出路径仅限于 OpenClaw 临时根目录： + - traces：`/tmp/openclaw`（回退：`${os.tmpdir()}/openclaw`） + - downloads：`/tmp/openclaw/downloads`（回退：`${os.tmpdir()}/openclaw/downloads`） +- 上传路径仅限于 OpenClaw 临时上传根目录： + - uploads：`/tmp/openclaw/uploads`（回退：`${os.tmpdir()}/openclaw/uploads`） +- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入框。 - `snapshot`： - - `--format ai`（安装 Playwright 时的默认值）：返回带数字 refs 的 AI 快照（`aria-ref=""`）。 - - `--format aria`：返回无障碍树（没有 refs；仅用于检查）。 + - `--format ai`（安装 Playwright 时的默认值）：返回带有数字 refs（`aria-ref=""`）的 AI 快照。 + - `--format aria`：返回无障碍树（无 refs；仅用于检查）。 - `--efficient`（或 `--mode efficient`）：紧凑 role 快照预设（interactive + compact + depth + 更低的 maxChars）。 - - 配置默认值（仅工具/CLI）：设置 `browser.snapshotDefaults.mode: "efficient"`，即可在调用方未传入 mode 时使用高效快照（参见 [Gateway configuration](/zh-CN/gateway/configuration-reference#browser)）。 - - Role 快照选项（`--interactive`、`--compact`、`--depth`、`--selector`）会强制使用带 refs（如 `ref=e12`）的基于 role 的快照。 - - `--frame "