chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
97b8315251
commit
fbfd38d1f5
@ -6,15 +6,15 @@ sidebarTitle: Doctor
|
||||
summary: Doctor 命令：健康检查、配置迁移和修复步骤
|
||||
title: Doctor
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T22:54:31Z"
|
||||
generated_at: "2026-05-05T00:56:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 86d862ccc56c0d979c2a957272b2e2f5c5fc7bb1ae8142748630ede0003891de
|
||||
source_hash: f8386e5d733ab599c78b96ad04135c8168cacdc55e864676aac26cd095a72685
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过期的配置/状态、检查健康状况，并提供可执行的修复步骤。
|
||||
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。
|
||||
|
||||
## 快速开始
|
||||
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
不提示，直接接受默认值（适用时包括重启/服务/沙箱修复步骤）。
|
||||
不提示并接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
不提示，应用推荐的修复（在安全的情况下执行修复 + 重启）。
|
||||
不提示并应用推荐的修复（在安全时执行修复 + 重启）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
同时应用更激进的修复（会覆盖自定义 supervisor 配置）。
|
||||
同时应用激进修复（会覆盖自定义 supervisor 配置）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
不显示提示运行，并且只应用安全迁移（配置规范化 + 磁盘上的状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。
|
||||
不提示运行，并且只应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。检测到旧版状态迁移时会自动运行。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,7 +62,7 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
扫描系统服务，查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
|
||||
扫描系统服务中的额外 Gateway 网关安装（launchd/systemd/schtasks）。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -73,66 +73,66 @@ openclaw doctor
|
||||
cat ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
## 它会做什么（摘要）
|
||||
## 它的作用（摘要）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="健康、UI 和更新">
|
||||
- 对 git 安装执行可选的预检更新（仅交互模式）。
|
||||
<Accordion title="健康状况、UI 和更新">
|
||||
- git 安装的可选预检更新（仅交互模式）。
|
||||
- UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
|
||||
- 健康检查 + 重启提示。
|
||||
- Skills 状态摘要（可用/缺失/阻塞）和插件状态。
|
||||
- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="配置和迁移">
|
||||
- 针对旧版值的配置规范化。
|
||||
- 将旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.<provider>`。
|
||||
- 旧版值的配置规范化。
|
||||
- 将 Talk 配置从旧版扁平 `talk.*` 字段迁移到 `talk.provider` + `talk.providers.<provider>`。
|
||||
- 针对旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
|
||||
- OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。
|
||||
- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
|
||||
- OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。
|
||||
- 当 `plugins.allow` 是限制性的，但工具策略仍要求通配符或插件自有工具时，发出插件/工具允许列表警告。
|
||||
- 旧版磁盘状态迁移（会话/agent 目录/WhatsApp 凭证）。
|
||||
- 旧版插件清单契约键迁移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。
|
||||
- 旧版 cron 存储迁移（`jobId`, `schedule.cron`, 顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 兜底任务）。
|
||||
- 旧版 agent 运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。
|
||||
- 启用插件时清理过期插件配置；当 `plugins.enabled=false` 时，过期插件引用会被视为惰性隔离配置并保留。
|
||||
- OpenAI Codex OAuth profile 的 OAuth TLS 前置条件检查。
|
||||
- 当 `plugins.allow` 具有限制性但工具策略仍请求通配符或插件自有工具时，发出插件/工具 allowlist 警告。
|
||||
- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
|
||||
- 旧版插件清单合约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
|
||||
- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook fallback 任务）。
|
||||
- 旧版智能体运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。
|
||||
- 插件启用时清理过时的插件配置；当 `plugins.enabled=false` 时，过时的插件引用会被视为惰性 containment 配置并保留。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="状态和完整性">
|
||||
- 会话锁文件检查和过期锁清理。
|
||||
- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支会话 transcript。
|
||||
- 检测卡住的 subagent 重启恢复 tombstone，并通过 `--fix` 支持清除过期的 aborted recovery 标志，避免启动时继续将子进程视为 restart-aborted。
|
||||
- 会话锁文件检查和过时锁清理。
|
||||
- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话 transcript。
|
||||
- 卡住的 subagent 重启恢复墓碑检测，支持通过 `--fix` 清除过时的 aborted recovery 标志，避免启动持续将子进程视为 restart-aborted。
|
||||
- 状态完整性和权限检查（会话、transcript、状态目录）。
|
||||
- 本地运行时检查配置文件权限（chmod 600）。
|
||||
- 模型认证健康状况：检查 OAuth 到期时间，可以刷新即将到期的 token，并报告 auth-profile 的冷却/禁用状态。
|
||||
- 检测额外工作区目录（`~/openclaw`）。
|
||||
- 本地运行时的配置文件权限检查（chmod 600）。
|
||||
- 模型认证健康状况：检查 OAuth 过期状态，可以刷新即将过期的 token，并报告 auth-profile 冷却/禁用状态。
|
||||
- 额外工作区目录检测（`~/openclaw`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway 网关、服务和 supervisor">
|
||||
- 启用沙箱隔离时修复沙箱镜像。
|
||||
- 启用沙箱隔离时的沙箱镜像修复。
|
||||
- 旧版服务迁移和额外 Gateway 网关检测。
|
||||
- Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。
|
||||
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
|
||||
- 渠道状态警告（从正在运行的 Gateway 网关探测）。
|
||||
- 带可选修复的 supervisor 配置审计（launchd/systemd/schtasks）。
|
||||
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd label）。
|
||||
- 渠道状态警告（从运行中的 Gateway 网关探测）。
|
||||
- Supervisor 配置审计（launchd/systemd/schtasks）以及可选修复。
|
||||
- 清理 Gateway 网关服务的嵌入式代理环境，这些服务在安装或更新期间捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。
|
||||
- Gateway 网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。
|
||||
- Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。
|
||||
- Gateway 网关端口冲突诊断（默认 `18789`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="认证、安全和配对">
|
||||
- 针对开放私信策略的安全警告。
|
||||
- 本地 token 模式的 Gateway 网关认证检查（当不存在 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。
|
||||
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过期的本地设备 token 缓存漂移，以及配对记录认证漂移）。
|
||||
- 开放私信策略的安全警告。
|
||||
- local token 模式的 Gateway 网关认证检查（当不存在 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。
|
||||
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过时的本地 device-token 缓存漂移，以及 paired-record 认证漂移）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="工作区和 shell">
|
||||
- Linux 上的 systemd linger 检查。
|
||||
- 工作区 bootstrap 文件大小检查（针对上下文文件的截断/接近限制警告）。
|
||||
- 默认 agent 的 Skills 就绪状态检查；报告允许但缺少 bin、环境变量、配置或 OS 要求的技能，并且 `--fix` 可以在 `skills.entries` 中禁用不可用技能。
|
||||
- Shell 补全状态检查和自动安装/升级。
|
||||
- 记忆搜索 embedding 提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制）。
|
||||
- 源码安装检查（pnpm workspace 不匹配、缺少 UI assets、缺少 tsx 二进制）。
|
||||
- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。
|
||||
- 默认智能体的 Skills 就绪检查；报告缺少 bin、环境变量、配置或操作系统要求的已允许 Skills，且 `--fix` 可以在 `skills.entries` 中禁用不可用 Skills。
|
||||
- Shell completion 状态检查和自动安装/升级。
|
||||
- 记忆搜索 embedding 提供商就绪检查（本地模型、远程 API key 或 QMD binary）。
|
||||
- 源码安装检查（pnpm 工作区不匹配、缺少 UI asset、缺少 tsx binary）。
|
||||
- 写入更新后的配置 + 向导元数据。
|
||||
|
||||
</Accordion>
|
||||
@ -140,40 +140,45 @@ cat ~/.openclaw/openclaw.json
|
||||
|
||||
## Dreams UI 回填和重置
|
||||
|
||||
Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **回填**、**重置** 和 **清除 Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。
|
||||
Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **回填**、**重置** 和 **清除 Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不**属于 `openclaw doctor` CLI 修复/迁移。
|
||||
|
||||
它们会做什么：
|
||||
|
||||
- **回填** 会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM 日记步骤，并将可逆的回填条目写入 `DREAMS.md`。
|
||||
- **重置** 只会从 `DREAMS.md` 中移除这些带标记的回填日记条目。
|
||||
- **清除 Grounded** 只会移除来自历史重放、且尚未积累 live recall 或每日支持的暂存 grounded-only 短期条目。
|
||||
- **回填** 会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary pass，并将可逆的回填条目写入 `DREAMS.md`。
|
||||
- **重置** 只会从 `DREAMS.md` 中移除这些带标记的回填 diary 条目。
|
||||
- **清除 Grounded** 只会移除来自历史 replay、且尚未积累 live recall 或 daily support 的 staged grounded-only short-term 条目。
|
||||
|
||||
它们本身**不会**做什么：
|
||||
|
||||
- 它们不会编辑 `MEMORY.md`
|
||||
- 它们不会运行完整的 doctor 迁移
|
||||
- 除非你先显式运行暂存 CLI 路径，否则它们不会自动将 grounded 候选项暂存到 live 短期提升存储中
|
||||
- 它们不会自动将 grounded candidates 暂存到 live short-term promotion store，除非你先显式运行 staged CLI 路径
|
||||
|
||||
如果你希望 grounded 历史重放影响正常的深度提升通道，请改用 CLI 流程：
|
||||
如果你想让 grounded 历史 replay 影响正常的深度提升通道，请改用 CLI 流程：
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
这会将 grounded durable 候选项暂存到短期 dreaming 存储，同时保持 `DREAMS.md` 作为审阅界面。
|
||||
这会将 grounded durable candidates 暂存到 short-term dreaming store，同时保留 `DREAMS.md` 作为 review surface。
|
||||
|
||||
## 详细行为和原理
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. 可选更新（git 安装）">
|
||||
如果这是一个 git checkout，并且 doctor 正在交互式运行，它会在运行 doctor 前提供更新（fetch/rebase/build）选项。
|
||||
如果这是 git checkout 且 doctor 正在交互式运行，它会在运行 doctor 前提供更新（fetch/rebase/build）选项。
|
||||
</Accordion>
|
||||
<Accordion title="1. 配置规范化">
|
||||
如果配置包含旧版值形状（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。
|
||||
如果配置包含旧版值形态（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
|
||||
|
||||
这包括旧版 Talk 扁平字段。当前公共 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形状重写到提供商映射中。
|
||||
这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形态重写到 provider map 中。
|
||||
|
||||
当 `plugins.allow` 非空且工具策略使用通配符或插件自有工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配实际加载的插件中的工具；它不会绕过独占插件允许列表。Doctor 会为迁移后的旧版允许列表配置写入 `plugins.bundledDiscovery: "compat"`，以保留现有的内置提供商行为，然后指向更严格的 `"allowlist"` 设置。
|
||||
当 `plugins.allow` 非空且工具策略使用
|
||||
通配符或插件自有工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配
|
||||
来自实际加载插件的工具；它不会绕过独占的插件
|
||||
allowlist。Doctor 会为迁移后的
|
||||
旧版 allowlist 配置写入 `plugins.bundledDiscovery: "compat"`，以保留现有内置提供商行为，并且
|
||||
随后指向更严格的 `"allowlist"` 设置。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. 旧版配置键迁移">
|
||||
@ -185,7 +190,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- 显示它应用的迁移。
|
||||
- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
|
||||
|
||||
Gateway 网关在启动时如果检测到旧版配置格式，也会自动运行 doctor 迁移，因此过期配置无需手动干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。
|
||||
当 Gateway 网关在启动时检测到旧版配置格式，它也会自动运行 doctor 迁移，因此过时的配置无需人工干预即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。
|
||||
|
||||
当前迁移：
|
||||
|
||||
@ -201,83 +206,89 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- 旧版 `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
- `routing.transcribeAudio` → `tools.media.audio.models`
|
||||
- `messages.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `messages.tts.providers.<provider>`
|
||||
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
|
||||
- `messages.tts.provider: "edge"` 和 `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` 和 `messages.tts.providers.microsoft`
|
||||
- `channels.discord.voice.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.voice.tts.providers.<provider>`
|
||||
- `channels.discord.accounts.<id>.voice.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
|
||||
- `plugins.entries.voice-call.config.tts.<provider>`（`openai`/`elevenlabs`/`microsoft`/`edge`）→ `plugins.entries.voice-call.config.tts.providers.<provider>`
|
||||
- `channels.discord.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.<provider>`
|
||||
- `channels.discord.accounts.<id>.voice.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts.<id>.voice.tts.providers.<provider>`
|
||||
- `plugins.entries.voice-call.config.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.<provider>`
|
||||
- `plugins.entries.voice-call.config.tts.provider: "edge"` 和 `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` 和 `providers.microsoft`
|
||||
- `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
|
||||
- `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- 对于带有命名 `accounts` 但仍残留单账号顶层渠道值的渠道，将这些账号作用域的值移动到为该渠道选择的提升账号中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
|
||||
- 对于带有命名 `accounts` 但仍残留单账号顶层渠道值的渠道，将这些账号作用域的值移动到为该渠道选定并提升的账号中（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*`（工具/提升权限/执行/沙箱/subagents）
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- 移除 `agents.defaults.llm`；对速度较慢的提供商/模型超时，使用 `models.providers.<id>.timeoutSeconds`
|
||||
- 移除 `agents.defaults.llm`；对较慢的提供商/模型超时使用 `models.providers.<id>.timeoutSeconds`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- 移除 `browser.relayBindHost`（旧版插件中继设置）
|
||||
- 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设为未来或未知枚举值的提供商，而不是封闭失败）
|
||||
- 移除 `browser.relayBindHost`（旧版扩展中继设置）
|
||||
- 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设置为未来或未知枚举值的提供商，而不是以关闭失败结束）
|
||||
|
||||
Doctor 警告还包括多账号渠道的账号默认值指导：
|
||||
|
||||
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有配置 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告后备路由可能选择意外账号。
|
||||
- 如果 `channels.<channel>.defaultAccount` 被设为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。
|
||||
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有配置 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告后备路由可能选中意外的账号。
|
||||
- 如果 `channels.<channel>.defaultAccount` 设置为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. OpenCode 提供商覆盖">
|
||||
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本归零。Doctor 会警告，以便你移除该覆盖并恢复逐模型 API 路由 + 成本。
|
||||
<Accordion title="2b. OpenCode provider overrides">
|
||||
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，以便你移除该覆盖并恢复按模型的 API 路由和成本。
|
||||
</Accordion>
|
||||
<Accordion title="2c. 浏览器迁移和 Chrome MCP 就绪状态">
|
||||
如果你的浏览器配置仍指向已移除的 Chrome 插件路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型：
|
||||
<Accordion title="2c. Browser migration and Chrome MCP readiness">
|
||||
如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型：
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` 会变为 `"existing-session"`
|
||||
- `browser.profiles.*.driver: "extension"` 变为 `"existing-session"`
|
||||
- `browser.relayBindHost` 会被移除
|
||||
|
||||
当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审计主机本地 Chrome MCP 路径：
|
||||
当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 也会审计主机本地 Chrome MCP 路径：
|
||||
|
||||
- 检查同一主机上是否已安装 Google Chrome，以用于默认自动连接配置文件
|
||||
- 检查同一主机上是否为默认自动连接配置文件安装了 Google Chrome
|
||||
- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
|
||||
- 提醒你在浏览器检查页面中启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
|
||||
- 提醒你在浏览器检查页面启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
|
||||
|
||||
Doctor 无法替你启用 Chrome 侧设置。主机本地 Chrome MCP 仍需要：
|
||||
Doctor 不能替你启用 Chrome 侧设置。主机本地 Chrome MCP 仍然需要：
|
||||
|
||||
- Gateway 网关/节点主机上有 Chromium 系浏览器 144+
|
||||
- Gateway 网关/节点主机上有基于 Chromium 的浏览器 144+
|
||||
- 浏览器在本地运行
|
||||
- 该浏览器中已启用远程调试
|
||||
- 该浏览器已启用远程调试
|
||||
- 在浏览器中批准首次附加同意提示
|
||||
|
||||
这里的就绪状态只涉及本地附加前提条件。Existing-session 会保留当前的 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。
|
||||
这里的就绪状态只涉及本地附加前置条件。Existing-session 保留当前的 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。
|
||||
|
||||
此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。那些流程会继续使用原始 CDP。
|
||||
此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。它们会继续使用原始 CDP。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. OAuth TLS 前提条件">
|
||||
当配置了 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈是否能验证证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印特定平台的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。
|
||||
<Accordion title="2d. OAuth TLS prerequisites">
|
||||
配置 OpenAI Codex OAuth 配置文件后，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否校验证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印平台特定的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。
|
||||
</Accordion>
|
||||
<Accordion title="2e. Codex OAuth 提供商覆盖">
|
||||
如果你之前在 `models.providers.openai-codex` 下添加过旧版 OpenAI 传输设置，它们可能会遮蔽新版发布自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 并存时会发出警告，以便你移除或改写陈旧的传输覆盖，并恢复内置路由/后备行为。自定义代理和仅标头覆盖仍受支持，并且不会触发此警告。
|
||||
<Accordion title="2e. Codex OAuth provider overrides">
|
||||
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版自动使用的内置 Codex OAuth provider 路径。当 Doctor 看到这些旧传输设置与 Codex OAuth 同时存在时，会发出警告，以便你移除或重写过期的传输覆盖，并恢复内置路由/后备行为。自定义代理和仅标头覆盖仍受支持，且不会触发此警告。
|
||||
</Accordion>
|
||||
<Accordion title="2f. Codex 插件路由警告">
|
||||
当启用内置 Codex 插件时，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI runner 解析。当你希望通过 PI 使用 Codex OAuth/订阅凭证时，这种组合是有效的，但它很容易与原生 Codex 应用服务器 harness 混淆。Doctor 会发出警告，并指向显式应用服务器形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
|
||||
<Accordion title="2f. Codex plugin route warnings">
|
||||
启用内置 Codex 插件后，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI 运行器解析。当你想通过 PI 使用 Codex OAuth/订阅凭证时，这种组合是有效的，但它很容易与原生 Codex 应用服务器 harness 混淆。Doctor 会警告并指向显式的应用服务器形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
|
||||
|
||||
Doctor 不会自动修复这一点，因为两条路由都有效：
|
||||
Doctor 不会自动修复此问题，因为两条路由都有效：
|
||||
|
||||
- `openai-codex/*` + PI 表示“通过正常 OpenClaw runner 使用 Codex OAuth/订阅凭证。”
|
||||
- `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex 应用服务器运行嵌入式回合。”
|
||||
- `openai-codex/*` + PI 表示“通过普通 OpenClaw 运行器使用 Codex OAuth/订阅凭证。”
|
||||
- `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex 应用服务器运行嵌入式轮次。”
|
||||
- `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话。”
|
||||
- `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。”
|
||||
|
||||
如果出现该警告，请选择你原本想要的路由并手动编辑配置。当 PI Codex OAuth 是有意配置时，请保持该警告原样。
|
||||
如果出现该警告，请选择你原本打算使用的路由，并手动编辑配置。当 PI Codex OAuth 是有意配置时，请保持该警告原样。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. 旧版状态迁移（磁盘布局）">
|
||||
<Accordion title="2g. Session route cleanup">
|
||||
当你将已配置的默认/后备模型或运行时从 Codex 等插件拥有的路由迁移走后，Doctor 还会扫描活动会话存储中是否有过期的自动创建路由状态。
|
||||
|
||||
`openclaw doctor --fix` 可以清除自动创建的过期状态，例如 `modelOverrideSource: "auto"` 模型固定、运行时模型元数据、固定的 harness ID、CLI 会话绑定，以及当其所属路由不再配置时的自动凭证配置文件覆盖。显式用户或旧版会话模型选择会报告给你手动审查并保持不变；当不再打算使用该路由时，请用 `/model ...`、`/new` 切换，或重置该会话。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Legacy state migrations (disk layout)">
|
||||
Doctor 可以将较旧的磁盘布局迁移到当前结构：
|
||||
|
||||
- 会话存储 + 转录：
|
||||
- 会话存储 + 转录记录：
|
||||
- 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Agent 目录：
|
||||
- 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
|
||||
@ -285,133 +296,133 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
|
||||
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账号 ID：`default`）
|
||||
|
||||
这些迁移是尽力而为且幂等的；当 Doctor 将任何旧版文件夹作为备份留下时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + Agent 目录，使历史记录/凭证/模型落入逐 Agent 路径，而无需手动运行 Doctor。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在按结构相等比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。
|
||||
这些迁移是尽力而为且幂等的；当 Doctor 将任何旧版文件夹作为备份保留时，会发出警告。Gateway 网关/CLI 也会在启动时自动迁移旧版会话 + Agent 目录，因此历史记录/凭证/模型会落在按 agent 划分的路径中，而无需手动运行 Doctor。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在按结构相等性比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. 旧版插件清单迁移">
|
||||
Doctor 会扫描所有已安装插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提供将它们移动到 `contracts` 对象并就地重写清单文件的选项。此迁移是幂等的；如果 `contracts` 键已经有相同值，则会移除旧版键而不重复数据。
|
||||
<Accordion title="3a. Legacy plugin manifest migrations">
|
||||
Doctor 会扫描所有已安装的插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提出将它们移动到 `contracts` 对象中，并就地重写清单文件。此迁移是幂等的；如果 `contracts` 键已经有相同的值，旧键会被移除，而不会复制数据。
|
||||
</Accordion>
|
||||
<Accordion title="3b. 旧版 cron 存储迁移">
|
||||
Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或覆盖时的 `cron.store`），查找调度器为了兼容性仍接受的旧作业形态。
|
||||
<Accordion title="3b. Legacy cron store migrations">
|
||||
Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或在覆盖时使用 `cron.store`），查找调度器为了兼容性仍接受的旧作业形态。
|
||||
|
||||
当前 cron 清理包括：
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload`
|
||||
- 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
|
||||
- payload `provider` 递送别名 → 显式 `delivery.channel`
|
||||
- 简单旧版 `notify: true` webhook 后备作业 → 显式 `delivery.mode="webhook"`，并设置 `delivery.to=cron.webhook`
|
||||
- 顶层载荷字段（`message`、`model`、`thinking`、...）→ `payload`
|
||||
- 顶层投递字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
|
||||
- 载荷 `provider` 投递别名 → 显式 `delivery.channel`
|
||||
- 简单旧版 `notify: true` webhook 后备作业 → 显式 `delivery.mode="webhook"`，并带有 `delivery.to=cron.webhook`
|
||||
|
||||
Doctor 只会在不改变行为的情况下自动迁移 `notify: true` 作业。如果某个作业将旧版 notify 后备与现有非 webhook 递送模式组合使用，Doctor 会警告并将该作业留给手动审核。
|
||||
Doctor 只有在不改变行为的情况下，才会自动迁移 `notify: true` 作业。如果某个作业将旧版通知后备与现有非 webhook 投递模式组合在一起，Doctor 会警告并将该作业留给手动审查。
|
||||
|
||||
在 Linux 上，当用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 也会发出警告。当前 OpenClaw 不维护该主机本地脚本，并且当 cron 无法访问 systemd 用户总线时，它可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除陈旧的 crontab 条目；当前健康检查请使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
|
||||
在 Linux 上，当用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 也会发出警告。当前 OpenClaw 不再维护这个主机本地脚本；当 cron 无法访问 systemd 用户总线时，它可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除过时的 crontab 条目；使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status` 执行当前健康检查。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. 会话锁清理">
|
||||
Doctor 会扫描每个智能体会话目录，查找陈旧的写入锁文件，即会话异常退出后留下的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁年龄，以及它是否被视为陈旧（PID 已死或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除陈旧锁文件；否则会打印一条说明，并指示你使用 `--fix` 重新运行。
|
||||
Doctor 会扫描每个智能体会话目录，查找过时的写入锁文件，即会话异常退出后遗留的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍存活、锁龄，以及它是否被视为过时（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除过时的锁文件；否则会打印提示，并指示你使用 `--fix` 重新运行。
|
||||
</Accordion>
|
||||
<Accordion title="3d. 会话转录分支修复">
|
||||
Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词转录重写缺陷创建的重复分支形态：一个被遗弃的用户轮次，包含 OpenClaw 内部运行时上下文，以及一个包含相同可见用户提示词的活跃兄弟分支。在 `--fix` / `--repair` 模式下，Doctor 会在原文件旁备份每个受影响文件，并将转录重写到活跃分支，这样 Gateway 网关历史记录和记忆读取器就不再看到重复轮次。
|
||||
Doctor 会扫描智能体会话 JSONL 文件，查找 2026.4.24 提示词转录重写缺陷创建的重复分支形态：一个包含 OpenClaw 内部运行时上下文的废弃用户轮次，以及一个包含相同可见用户提示词的活跃同级分支。在 `--fix` / `--repair` 模式下，Doctor 会在原文件旁备份每个受影响文件，并将转录重写到活跃分支，使 Gateway 网关历史记录和记忆读取器不再看到重复轮次。
|
||||
</Accordion>
|
||||
<Accordion title="4. 状态完整性检查（会话持久化、路由和安全）">
|
||||
状态目录是运行层面的脑干。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。
|
||||
状态目录是运行时的核心枢纽。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。
|
||||
|
||||
Doctor 检查：
|
||||
Doctor 会检查：
|
||||
|
||||
- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复缺失的数据。
|
||||
- **状态目录权限**：验证可写性；提供修复权限的选项（并在检测到所有者/组不匹配时发出 `chown` 提示）。
|
||||
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致更慢的 I/O 以及锁/同步竞争。
|
||||
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。
|
||||
- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
|
||||
- **状态目录权限**：验证可写性；提供修复权限的选项（当检测到所有者/组不匹配时，会输出 `chown` 提示）。
|
||||
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致较慢的 I/O 以及锁/同步竞争。
|
||||
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入下可能更慢且更易磨损。
|
||||
- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史记录并避免 `ENOENT` 崩溃所必需的。
|
||||
- **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。
|
||||
- **主会话“1 行 JSONL”**：当主转录只有一行时标记（历史记录没有累积）。
|
||||
- **多个状态目录**：当多个 home 目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在安装之间分裂）。
|
||||
- **多个状态目录**：当多个主目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在安装之间分裂）。
|
||||
- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态位于那里）。
|
||||
- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 可被组/所有人读取，则发出警告，并提供收紧到 `600` 的选项。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. 模型凭证健康状况（OAuth 过期）">
|
||||
Doctor 会检查凭证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已陈旧，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。
|
||||
<Accordion title="5. 模型凭证健康（OAuth 过期）">
|
||||
Doctor 会检查凭证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件过时，它会建议使用 Anthropic API key 或 Anthropic setup-token 路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。
|
||||
|
||||
当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），Doctor 会报告需要重新认证，并打印要运行的确切 `openclaw models auth login --provider ...` 命令。
|
||||
|
||||
Doctor 还会报告由于以下原因暂时不可用的凭证配置文件：
|
||||
Doctor 还会报告因以下原因暂时不可用的凭证配置文件：
|
||||
|
||||
- 短暂冷却（速率限制/超时/凭证失败）
|
||||
- 较长禁用（账单/额度失败）
|
||||
- 短暂冷却（速率限制/超时/认证失败）
|
||||
- 较长时间禁用（账单/额度失败）
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. 钩子模型验证">
|
||||
如果设置了 `hooks.gmail.model`，Doctor 会根据目录和允许列表验证模型引用，并在它无法解析或被禁止时发出警告。
|
||||
</Accordion>
|
||||
<Accordion title="7. 沙箱镜像修复">
|
||||
启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。
|
||||
启用沙箱隔离时，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧版名称的选项。
|
||||
</Accordion>
|
||||
<Accordion title="7b. 插件安装清理">
|
||||
Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这包括陈旧的生成依赖根、旧安装阶段目录、早期内置插件依赖修复代码留下的包本地残留，以及可能遮蔽当前内置清单的孤立或已恢复的托管 npm 版内置 `@openclaw/*` 插件。
|
||||
Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这包括过时的生成依赖根目录、旧安装阶段目录、早期内置插件依赖修复代码留下的包本地残留，以及可能遮蔽当前内置清单的孤立或已恢复的托管 npm 内置 `@openclaw/*` 插件副本。
|
||||
|
||||
当配置引用了可下载插件，但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。对于 2026.5.2 内置插件外部化，Doctor 会自动安装现有配置已经使用的可下载插件，然后依赖 `meta.lastTouchedVersion` 让该发布处理只运行一次。Gateway 网关启动和配置重载不会运行包管理器；插件安装仍然是显式的 Doctor/安装/更新工作。
|
||||
当配置引用了可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。对于 2026.5.2 的内置插件外部化，Doctor 会自动安装现有配置已使用的可下载插件，然后依靠 `meta.lastTouchedVersion` 确保该发布迁移只运行一次。Gateway 网关启动和配置重载不会运行包管理器；插件安装仍然是显式的 Doctor/安装/更新工作。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Gateway 网关服务迁移和清理提示">
|
||||
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等对象，不会被标记为“额外”。
|
||||
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的 Gateway 网关类服务并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。
|
||||
|
||||
在 Linux 上，如果用户级 Gateway 网关服务缺失但系统级 OpenClaw Gateway 网关服务存在，Doctor 不会自动安装第二个用户级服务。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复项，或在系统监督器拥有 Gateway 网关生命周期时设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
|
||||
在 Linux 上，如果用户级 Gateway 网关服务缺失，但系统级 OpenClaw Gateway 网关服务存在，Doctor 不会自动安装第二个用户级服务。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复项；如果系统监督进程拥有 Gateway 网关生命周期，则设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. 启动 Matrix 迁移">
|
||||
当 Matrix 渠道账号有待处理或可操作的旧版状态迁移时，Doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
|
||||
当 Matrix 渠道账号有待处理或可执行的旧版状态迁移时，Doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
|
||||
</Accordion>
|
||||
<Accordion title="8c. 设备配对和凭证漂移">
|
||||
Doctor 现在会将设备配对状态作为正常健康检查的一部分进行检查。
|
||||
Doctor 现在会在常规健康检查中检查设备配对状态。
|
||||
|
||||
它报告的内容：
|
||||
它会报告：
|
||||
|
||||
- 待处理的首次配对请求
|
||||
- 已配对设备的待处理角色升级
|
||||
- 已配对设备的待处理范围升级
|
||||
- 公钥不匹配修复，其中设备 ID 仍然匹配，但设备身份不再匹配已批准记录
|
||||
- 已配对记录缺少已批准角色的活跃令牌
|
||||
- 范围漂移到已批准配对基线之外的已配对令牌
|
||||
- 当前机器上的本地缓存设备令牌条目早于 Gateway 网关侧令牌轮换，或携带陈旧的范围元数据
|
||||
- 已配对设备的待处理作用域升级
|
||||
- 设备 ID 仍匹配但设备身份不再匹配已批准记录的公钥不匹配修复
|
||||
- 缺少已批准角色的活跃令牌的配对记录
|
||||
- 作用域漂移到已批准配对基线之外的配对令牌
|
||||
- 当前机器上的本地缓存设备令牌条目，这些条目早于 Gateway 网关侧令牌轮换，或携带过时的作用域元数据
|
||||
|
||||
Doctor 不会自动批准配对请求或自动轮换设备令牌。它会改为打印确切的后续步骤：
|
||||
Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为打印确切的后续步骤：
|
||||
|
||||
- 使用 `openclaw devices list` 检查待处理请求
|
||||
- 使用 `openclaw devices approve <requestId>` 批准确切请求
|
||||
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新令牌
|
||||
- 使用 `openclaw devices remove <deviceId>` 移除并重新批准陈旧记录
|
||||
- 使用 `openclaw devices remove <deviceId>` 移除并重新批准过时记录
|
||||
|
||||
这弥合了常见的“已配对但仍收到需要配对”漏洞：Doctor 现在会区分首次配对、待处理角色/范围升级，以及陈旧令牌/设备身份漂移。
|
||||
这补上了常见的“已配对但仍提示需要配对”漏洞：Doctor 现在会区分首次配对、待处理角色/作用域升级，以及过时令牌/设备身份漂移。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. 安全警告">
|
||||
当提供商对私信开放但没有允许列表，或策略以危险方式配置时，Doctor 会发出警告。
|
||||
当提供商在没有允许列表的情况下向私信开放，或策略以危险方式配置时，Doctor 会发出警告。
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger（Linux）">
|
||||
如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，使 Gateway 网关在注销后保持存活。
|
||||
如果作为 systemd 用户服务运行，Doctor 会确保已启用 linger，使 Gateway 网关在登出后保持运行。
|
||||
</Accordion>
|
||||
<Accordion title="11. 工作区状态（Skills、插件和旧版目录）">
|
||||
Doctor 会打印默认智能体的工作区状态摘要：
|
||||
Doctor 会为默认智能体打印工作区状态摘要：
|
||||
|
||||
- **Skills 状态**：统计符合条件、缺少要求和被允许列表阻止的 Skills。
|
||||
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
|
||||
- **插件状态**：统计已启用/已禁用/出错的插件；列出所有错误的插件 ID；报告内置插件能力。
|
||||
- **插件状态**：统计已启用/已禁用/出错的插件；列出任何错误的插件 ID；报告内置插件能力。
|
||||
- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
|
||||
- **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。
|
||||
- **插件诊断**：展示插件注册表在加载时输出的任何警告或错误。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. 引导文件大小">
|
||||
Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印调优 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
|
||||
Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会按文件报告原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印用于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
|
||||
</Accordion>
|
||||
<Accordion title="11d. 陈旧渠道插件清理">
|
||||
当 `openclaw doctor --fix` 移除缺失的渠道插件时，它还会移除引用该插件的悬空渠道范围配置：`channels.<id>` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖项。这可以防止渠道运行时已经不存在但配置仍要求 Gateway 网关绑定到它的 Gateway 网关启动循环。
|
||||
<Accordion title="11d. 过时渠道插件清理">
|
||||
当 `openclaw doctor --fix` 移除缺失的渠道插件时，它也会移除引用该插件的悬空渠道作用域配置：`channels.<id>` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖。这可以防止渠道运行时已消失但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。
|
||||
</Accordion>
|
||||
<Accordion title="11c. Shell 补全">
|
||||
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：
|
||||
|
||||
- 如果 shell 配置文件使用慢速动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。
|
||||
- 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。
|
||||
- 如果补全已在配置文件中配置但缓存文件缺失，Doctor 会自动重新生成缓存。
|
||||
- 如果完全没有配置补全，Doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。
|
||||
|
||||
@ -419,77 +430,77 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Gateway 网关凭证检查（本地令牌）">
|
||||
Doctor 会检查本地 Gateway 网关令牌凭证就绪状态。
|
||||
Doctor 会检查本地 Gateway 网关令牌认证就绪状态。
|
||||
|
||||
- 如果令牌模式需要令牌但不存在令牌源，Doctor 会提供生成令牌的选项。
|
||||
- 如果令牌模式需要令牌但不存在令牌来源，Doctor 会提供生成一个令牌的选项。
|
||||
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。
|
||||
- `openclaw doctor --generate-gateway-token` 只有在没有配置令牌 SecretRef 时才会强制生成。
|
||||
- `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. 感知只读 SecretRef 的修复">
|
||||
某些修复流程需要检查已配置凭证，同时不削弱运行时快速失败行为。
|
||||
某些修复流程需要检查已配置的凭证，同时不削弱运行时快速失败行为。
|
||||
|
||||
- `openclaw doctor --fix` 现在会使用与状态类命令相同的只读 SecretRef 摘要模型，用于定向配置修复。
|
||||
- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭证。
|
||||
- 如果 Telegram 机器人令牌通过 SecretRef 配置但在当前命令路径中不可用，Doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
|
||||
- `openclaw doctor --fix` 现在对定向配置修复使用与 Status 系列命令相同的只读 SecretRef 摘要模型。
|
||||
- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的 bot 凭证。
|
||||
- 如果 Telegram bot 令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Gateway 网关健康检查 + 重启">
|
||||
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
|
||||
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提示重启。
|
||||
</Accordion>
|
||||
<Accordion title="13b. 记忆搜索就绪状态">
|
||||
Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体就绪。行为取决于已配置的后端和提供商：
|
||||
Doctor 会检查已配置的记忆搜索嵌入提供商是否已为默认智能体准备就绪。行为取决于已配置的后端和提供商：
|
||||
|
||||
- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指南，包括 npm 包和手动二进制路径选项。
|
||||
- **显式本地提供商**：检查是否存在本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。
|
||||
- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。
|
||||
- **显式本地提供商**：检查本地模型文件，或可识别的远程/可下载模型 URL。如果缺失，会建议切换到远程提供商。
|
||||
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境或认证存储中是否存在 API key。如果缺失，会打印可操作的修复提示。
|
||||
- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。
|
||||
- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序逐一尝试每个远程提供商。
|
||||
|
||||
当存在缓存的 Gateway 网关探测结果时（检查时 Gateway 网关健康），Doctor 会将其结果与 CLI 可见的配置交叉比对，并标注任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果你需要实时提供商检查，请使用深度记忆状态命令。
|
||||
当缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关处于健康状态），Doctor 会将其结果与 CLI 可见配置交叉参照，并指出任何差异。Doctor 不会在默认路径上启动新的嵌入 ping；如果你想进行实时提供商检查，请使用深度记忆 Status 命令。
|
||||
|
||||
使用 `openclaw memory status --deep` 在运行时验证嵌入就绪状态。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. 渠道状态警告">
|
||||
如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告警告及建议修复方式。
|
||||
<Accordion title="14. 渠道 Status 警告">
|
||||
如果 Gateway 网关健康，Doctor 会运行渠道 Status 探测，并报告警告及建议的修复方法。
|
||||
</Accordion>
|
||||
<Accordion title="15. Supervisor 配置审计 + 修复">
|
||||
Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或默认值已过期（例如 systemd network-online 依赖项和重启延迟）。发现不匹配时，它会建议更新，并可以将服务文件/任务重写为当前默认值。
|
||||
<Accordion title="15. 监督器配置审计 + 修复">
|
||||
Doctor 会检查已安装的监督器配置（launchd/systemd/schtasks）是否缺少默认值或默认值过旧（例如 systemd network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。
|
||||
|
||||
备注：
|
||||
注意：
|
||||
|
||||
- `openclaw doctor` 会在重写 supervisor 配置前提示。
|
||||
- `openclaw doctor --yes` 接受默认修复提示。
|
||||
- `openclaw doctor --repair` 无需提示即可应用建议修复。
|
||||
- `openclaw doctor --repair --force` 会覆盖自定义 supervisor 配置。
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/bootstrap、supervisor 配置重写，以及旧版服务清理，因为该生命周期由外部 supervisor 拥有。
|
||||
- 在 Linux 上，当匹配的 systemd Gateway 网关 unit 处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略处于非活动状态的非旧版额外 Gateway 网关类似 unit，因此配套服务文件不会产生清理噪声。
|
||||
- 如果令牌认证需要令牌，且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会将已解析的明文令牌值持久化到 supervisor 服务环境元数据中。
|
||||
- Doctor 会检测较旧的 LaunchAgent、systemd 或 Windows Scheduled Task 安装中内联嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时源加载，而不是从 supervisor 定义加载。
|
||||
- Doctor 会检测服务命令是否在 `gateway.port` 变更后仍固定旧的 `--port`，并将服务元数据重写为当前端口。
|
||||
- 如果令牌认证需要令牌，且已配置的令牌 SecretRef 未解析，Doctor 会阻止安装/修复路径，并提供可操作的指导。
|
||||
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，Doctor 会阻止安装/修复，直到显式设置 mode。
|
||||
- 对于 Linux user-systemd unit，Doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
|
||||
- 当配置最后由较新版本写入时，Doctor 服务修复会拒绝使用较旧的 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
|
||||
- `openclaw doctor` 会在重写监督器配置前提示。
|
||||
- `openclaw doctor --yes` 会接受默认修复提示。
|
||||
- `openclaw doctor --repair` 会在不提示的情况下应用建议修复。
|
||||
- `openclaw doctor --repair --force` 会覆盖自定义监督器配置。
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状态并运行非服务修复，但会跳过服务安装/启动/重启/引导、监督器配置重写和旧版服务清理，因为该生命周期由外部监督器负责。
|
||||
- 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外 Gateway 网关类单元，因此配套服务文件不会产生清理噪音。
|
||||
- 如果令牌认证需要令牌，且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会将解析后的明文令牌值持久化到监督器服务环境元数据中。
|
||||
- Doctor 会检测旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装以内联方式嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从监督器定义加载。
|
||||
- Doctor 会检测服务命令是否在 `gateway.port` 更改后仍固定旧的 `--port`，并将服务元数据重写为当前端口。
|
||||
- 如果令牌认证需要令牌，且已配置的令牌 SecretRef 未解析，Doctor 会阻止安装/修复路径，并提供可操作的指引。
|
||||
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，Doctor 会阻止安装/修复，直到显式设置模式。
|
||||
- 对于 Linux 用户 systemd 单元，Doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
|
||||
- 当配置最后由较新版本写入时，Doctor 服务修复会拒绝用较旧的 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
|
||||
- 你始终可以通过 `openclaw gateway install --force` 强制完整重写。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Gateway 网关运行时 + 端口诊断">
|
||||
Doctor 会检查服务运行时（PID、最后退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
|
||||
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
|
||||
</Accordion>
|
||||
<Accordion title="17. Gateway 网关运行时最佳实践">
|
||||
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能在升级后失效，因为服务不会加载你的 shell init。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提供迁移选项。
|
||||
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，且版本管理器路径可能在升级后失效，因为服务不会加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提示迁移到该安装。
|
||||
|
||||
新安装或修复的 macOS LaunchAgent 使用规范的系统 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是复制交互式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程的解析位置。Linux 服务仍保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的 user-bin 目录，但猜测出的版本管理器备用目录只有在这些目录实际存在于磁盘上时，才会写入服务 PATH。
|
||||
新安装或修复的 macOS LaunchAgent 使用规范的系统 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是复制交互式 shell PATH，因此 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程的解析位置。Linux 服务仍会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户 bin 目录，但推测的版本管理器回退目录只有在这些目录实际存在于磁盘上时才会写入服务 PATH。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. 配置写入 + 向导元数据">
|
||||
Doctor 会持久化所有配置变更，并为向导元数据打标以记录本次 Doctor 运行。
|
||||
Doctor 会持久化任何配置更改，并标记向导元数据以记录 Doctor 运行。
|
||||
</Accordion>
|
||||
<Accordion title="19. 工作区提示（备份 + 记忆系统）">
|
||||
Doctor 会在缺少工作区记忆系统时建议添加，并在工作区尚未纳入 git 管理时打印备份提示。
|
||||
当缺少工作区记忆系统时，Doctor 会建议添加；如果工作区尚未纳入 git，它还会打印备份提示。
|
||||
|
||||
有关工作区结构和 git 备份（推荐使用私有 GitHub 或 GitLab）的完整指南，请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。
|
||||
参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，了解工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -4,50 +4,49 @@ read_when:
|
||||
- 调试模型故障转移 / “所有模型均失败”
|
||||
- 了解身份验证配置文件及其管理方式
|
||||
sidebarTitle: Models FAQ
|
||||
summary: 常见问题：模型默认值、选择、别名、切换、故障转移和认证配置文件
|
||||
title: 常见问题：模型和凭证
|
||||
summary: 常见问题：模型默认值、选择、别名、切换、故障转移和身份验证配置文件
|
||||
title: 常见问题：模型和认证
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T22:20:01Z"
|
||||
generated_at: "2026-05-05T00:56:07Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bf06266926cecc06d8799cb17f42d96cdaa09ad83c20e8d4dcc3bcccbd840abc
|
||||
source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54
|
||||
source_path: help/faq-models.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Models 和身份验证配置文件问答。关于设置、会话、Gateway 网关、渠道和
|
||||
Model 和身份验证配置档案问答。有关设置、会话、Gateway 网关、渠道和
|
||||
故障排除，请参阅主 [常见问题](/zh-CN/help/faq)。
|
||||
|
||||
## Models：默认值、选择、别名、切换
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title='什么是“默认模型”？'>
|
||||
OpenClaw 的默认模型就是你设置为以下内容的模型：
|
||||
OpenClaw 的默认模型就是你设置为以下值的模型：
|
||||
|
||||
```
|
||||
agents.defaults.model.primary
|
||||
```
|
||||
|
||||
模型以 `provider/model` 引用（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试该精确模型 ID 的唯一已配置提供商匹配，之后才会回退到已配置的默认提供商，这是已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是显示一个已移除提供商的过期默认值。你仍然应该**显式**设置 `provider/model`。
|
||||
模型以 `provider/model` 形式引用（示例：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后为该精确模型 ID 尝试唯一的已配置提供商匹配，最后才会作为已弃用的兼容路径回退到已配置的默认提供商。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是显示过时的已移除提供商默认值。你仍然应该**显式**设置 `provider/model`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="你推荐什么模型？">
|
||||
**推荐默认值：** 使用你的提供商栈中可用的最强最新一代模型。
|
||||
**对于启用工具或不受信任输入的智能体：** 优先考虑模型能力，而不是成本。
|
||||
**对于日常/低风险聊天：** 使用更便宜的回退模型，并按智能体角色路由。
|
||||
**推荐默认值：**使用你的提供商栈中可用的最强最新一代模型。
|
||||
**对于启用工具或处理不可信输入的智能体：**优先考虑模型能力而非成本。
|
||||
**对于日常/低风险聊天：**使用更便宜的回退模型，并按智能体角色路由。
|
||||
|
||||
MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和
|
||||
[本地模型](/zh-CN/gateway/local-models)。
|
||||
|
||||
经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于日常聊天或摘要，使用更便宜的
|
||||
模型。你可以按智能体路由模型，并使用子智能体来
|
||||
并行处理长任务（每个子智能体都会消耗 token）。参见 [Models](/zh-CN/concepts/models) 和
|
||||
经验法则：高风险工作使用**你负担得起的最佳模型**，日常聊天或摘要使用更便宜的
|
||||
模型。你可以按智能体路由模型，并使用子智能体来并行处理长任务（每个子智能体都会消耗 token）。请参阅 [Models](/zh-CN/concepts/models) 和
|
||||
[子智能体](/zh-CN/tools/subagents)。
|
||||
|
||||
强烈警告：较弱/过度量化的模型更容易受到提示注入和不安全行为的影响。参见 [安全](/zh-CN/gateway/security)。
|
||||
强烈警告：较弱/过度量化的模型更容易受到提示注入和不安全行为影响。请参阅 [安全](/zh-CN/gateway/security)。
|
||||
|
||||
更多上下文：[Models](/zh-CN/concepts/models)。
|
||||
更多背景：[Models](/zh-CN/concepts/models)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -61,34 +60,34 @@ x-i18n:
|
||||
- `openclaw configure --section model`（交互式）
|
||||
- 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model`
|
||||
|
||||
避免用部分对象调用 `config.apply`，除非你打算替换整个配置。
|
||||
对于 RPC 编辑，先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。查找载荷会给出规范化路径、浅层 schema 文档/约束，以及直接子项摘要。
|
||||
用于部分更新。
|
||||
避免对局部对象使用 `config.apply`，除非你确实想替换整个配置。
|
||||
对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。查询载荷会提供规范化路径、浅层 schema 文档/约束以及直接子项摘要。
|
||||
用于局部更新。
|
||||
如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。
|
||||
|
||||
文档：[Models](/zh-CN/concepts/models)、[配置](/zh-CN/cli/configure)、[配置](/zh-CN/cli/config)、[Doctor](/zh-CN/gateway/doctor)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="我可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？">
|
||||
可以。Ollama 是使用本地模型最简单的路径。
|
||||
<Accordion title="我能使用自托管模型（llama.cpp、vLLM、Ollama）吗？">
|
||||
可以。Ollama 是使用本地模型的最简单路径。
|
||||
|
||||
最快设置：
|
||||
|
||||
1. 从 `https://ollama.com/download` 安装 Ollama
|
||||
2. 拉取一个本地模型，例如 `ollama pull gemma4`
|
||||
3. 如果你也想使用云模型，运行 `ollama signin`
|
||||
2. 拉取本地模型，例如 `ollama pull gemma4`
|
||||
3. 如果你也想使用云端模型，请运行 `ollama signin`
|
||||
4. 运行 `openclaw onboard` 并选择 `Ollama`
|
||||
5. 选择 `Local` 或 `Cloud + Local`
|
||||
|
||||
说明：
|
||||
注意：
|
||||
|
||||
- `Cloud + Local` 会提供云模型以及你的本地 Ollama 模型
|
||||
- `kimi-k2.5:cloud` 等云模型不需要本地拉取
|
||||
- `Cloud + Local` 会提供云端模型以及你的本地 Ollama 模型
|
||||
- `kimi-k2.5:cloud` 等云端模型不需要本地拉取
|
||||
- 如需手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/<model>`
|
||||
|
||||
安全说明：较小或重度量化的模型更容易受到提示注入影响。对于任何可以使用工具的 bot，我们强烈建议使用**大模型**。
|
||||
如果你仍想使用小模型，请启用沙箱隔离和严格的工具允许列表。
|
||||
安全注意事项：较小或大量量化的模型更容易受到提示注入影响。对于任何可以使用工具的 bot，我们强烈建议使用**大模型**。
|
||||
如果你仍想使用小模型，请启用沙箱隔离和严格的工具 allowlist。
|
||||
|
||||
文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、
|
||||
[模型提供商](/zh-CN/concepts/model-providers)、[安全](/zh-CN/gateway/security)、
|
||||
@ -103,8 +102,8 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="如何即时切换模型（无需重启）？">
|
||||
将 `/model` 命令作为独立消息使用：
|
||||
<Accordion title="如何即时切换模型（不重启）？">
|
||||
将 `/model` 命令作为独立消息发送：
|
||||
|
||||
```
|
||||
/model sonnet
|
||||
@ -118,25 +117,25 @@ x-i18n:
|
||||
|
||||
这些是内置别名。可以通过 `agents.defaults.models` 添加自定义别名。
|
||||
|
||||
你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。
|
||||
你可以用 `/model`、`/model list` 或 `/model status` 列出可用模型。
|
||||
|
||||
`/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择：
|
||||
`/model`（以及 `/model list`）会显示紧凑的编号选择器。按编号选择：
|
||||
|
||||
```
|
||||
/model 3
|
||||
```
|
||||
|
||||
你也可以为提供商强制指定特定身份验证配置文件（按会话）：
|
||||
你也可以为该提供商强制指定特定身份验证配置档案（按会话）：
|
||||
|
||||
```
|
||||
/model opus@anthropic:default
|
||||
/model opus@anthropic:work
|
||||
```
|
||||
|
||||
提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个身份验证配置文件。
|
||||
它还会在可用时显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
|
||||
提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个身份验证配置档案。
|
||||
可用时，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
|
||||
|
||||
**如何取消固定我用 @profile 设置的配置文件？**
|
||||
**如何取消固定我用 @profile 设置的配置档案？**
|
||||
|
||||
重新运行 `/model`，但**不要**带 `@profile` 后缀：
|
||||
|
||||
@ -145,27 +144,27 @@ x-i18n:
|
||||
```
|
||||
|
||||
如果你想回到默认值，请从 `/model` 中选择它（或发送 `/model <default provider/model>`）。
|
||||
使用 `/model status` 确认当前活动的身份验证配置文件。
|
||||
使用 `/model status` 确认哪个身份验证配置档案处于活动状态。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="我可以将 GPT 5.5 用于日常任务，将 Codex 5.5 用于编码吗？">
|
||||
<Accordion title="我可以日常任务用 GPT 5.5，编码用 Codex 5.5 吗？">
|
||||
可以。将模型选择和运行时选择分开处理：
|
||||
|
||||
- **原生 Codex 编码智能体：** 将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`，并将 `agents.defaults.agentRuntime.id` 设置为 `"codex"`。当你想使用 ChatGPT/Codex 订阅身份验证时，请用 `openclaw models auth login --provider openai-codex` 登录。
|
||||
- **通过 PI 直接执行 OpenAI API 任务：** 使用 `/model openai/gpt-5.5`，不使用 Codex 运行时覆盖，并配置 `OPENAI_API_KEY`。
|
||||
- **通过 PI 使用 Codex OAuth：** 仅当你有意使用带 Codex OAuth 的普通 PI 运行器时，才使用 `/model openai-codex/gpt-5.5`。
|
||||
- **子智能体：** 将编码任务路由到一个仅 Codex 的智能体，该智能体有自己的模型和 `agentRuntime` 默认值。
|
||||
- **原生 Codex 编码智能体：**将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`，并将 `agents.defaults.agentRuntime.id` 设置为 `"codex"`。当你想使用 ChatGPT/Codex 订阅身份验证时，请用 `openclaw models auth login --provider openai-codex` 登录。
|
||||
- **通过 PI 直接执行 OpenAI API 任务：**使用 `/model openai/gpt-5.5`，不要覆盖 Codex 运行时，并配置 `OPENAI_API_KEY`。
|
||||
- **通过 PI 使用 Codex OAuth：**仅在你有意使用带 Codex OAuth 的普通 PI runner 时，使用 `/model openai-codex/gpt-5.5`。
|
||||
- **子智能体：**将编码任务路由到仅使用 Codex 的智能体，并为其设置自己的模型和 `agentRuntime` 默认值。
|
||||
|
||||
参见 [Models](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。
|
||||
请参阅 [Models](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="如何为 GPT 5.5 配置快速模式？">
|
||||
使用会话开关或配置默认值：
|
||||
|
||||
- **按会话：** 当会话正在使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时，发送 `/fast on`。
|
||||
- **按模型默认值：** 将 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 或 `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` 设置为 `true`。
|
||||
- **按会话：**当会话使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时发送 `/fast on`。
|
||||
- **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 或 `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` 设置为 `true`。
|
||||
|
||||
示例：
|
||||
|
||||
@ -185,42 +184,42 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射到 `service_tier = "priority"`。会话 `/fast` 覆盖优先于配置默认值。
|
||||
对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话 `/fast` 覆盖会优先于配置默认值。
|
||||
|
||||
参见 [思考和快速模式](/zh-CN/tools/thinking) 以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。
|
||||
请参阅 [思考和快速模式](/zh-CN/tools/thinking) 以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='为什么我会看到“Model ... is not allowed”，然后没有回复？'>
|
||||
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何
|
||||
会话覆盖的**允许列表**。选择不在该列表中的模型会返回：
|
||||
如果设置了 `agents.defaults.models`，它会成为 `/model` 和任何
|
||||
会话覆盖的 **allowlist**。选择不在该列表中的模型会返回：
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
|
||||
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
|
||||
```
|
||||
|
||||
该错误会**代替**正常回复返回。修复方法：将模型添加到
|
||||
`agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。
|
||||
如果命令还包含 `--runtime codex`，请先添加模型，然后重试同一个
|
||||
该错误会**代替**正常回复返回。修复：将模型添加到
|
||||
`agents.defaults.models`，移除 allowlist，或从 `/model list` 中选择一个模型。
|
||||
如果命令还包含 `--runtime codex`，请先添加模型，然后重试相同的
|
||||
`/model provider/model --runtime codex` 命令。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='为什么我会看到“Unknown model: minimax/MiniMax-M2.7”？'>
|
||||
这意味着**提供商未配置**（没有找到 MiniMax 提供商配置或身份验证
|
||||
配置文件），因此无法解析该模型。
|
||||
这表示**提供商未配置**（未找到 MiniMax 提供商配置或身份验证
|
||||
配置档案），因此无法解析该模型。
|
||||
|
||||
修复清单：
|
||||
|
||||
1. 升级到当前 OpenClaw 版本（或从源代码 `main` 运行），然后重启 Gateway 网关。
|
||||
1. 升级到当前 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。
|
||||
2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax 身份验证
|
||||
存在于环境/身份验证配置文件中，以便可以注入匹配的提供商
|
||||
（`MINIMAX_API_KEY` 用于 `minimax`，`MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax
|
||||
存在于环境变量/身份验证配置档案中，以便可以注入匹配的提供商
|
||||
（`MINIMAX_API_KEY` 用于 `minimax`，`MINIMAX_OAUTH_TOKEN` 或存储的 MiniMax
|
||||
OAuth 用于 `minimax-portal`）。
|
||||
3. 对你的身份验证路径使用精确模型 ID（区分大小写）：
|
||||
`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` 用于 API key
|
||||
设置，或者 `minimax-portal/MiniMax-M2.7` /
|
||||
`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` 用于 API-key
|
||||
设置，或 `minimax-portal/MiniMax-M2.7` /
|
||||
`minimax-portal/MiniMax-M2.7-highspeed` 用于 OAuth 设置。
|
||||
4. 运行：
|
||||
|
||||
@ -230,13 +229,13 @@ x-i18n:
|
||||
|
||||
并从列表中选择（或在聊天中使用 `/model list`）。
|
||||
|
||||
参见 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。
|
||||
请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="我可以将 MiniMax 作为默认值，并将 OpenAI 用于复杂任务吗？">
|
||||
可以。将 **MiniMax 作为默认值**，并在需要时**按会话**切换模型。
|
||||
回退用于**错误**，而不是“困难任务”，因此请使用 `/model` 或单独的智能体。
|
||||
<Accordion title="我可以默认使用 MiniMax，并在复杂任务中使用 OpenAI 吗？">
|
||||
可以。将 **MiniMax 设为默认值**，并在需要时**按会话**切换模型。
|
||||
回退用于**错误**，不是用于“困难任务”，因此请使用 `/model` 或单独的智能体。
|
||||
|
||||
**选项 A：按会话切换**
|
||||
|
||||
@ -272,18 +271,18 @@ x-i18n:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="opus / sonnet / gpt 是内置快捷方式吗？">
|
||||
是的。OpenClaw 附带一些默认简写（仅在模型存在于 `agents.defaults.models` 中时应用）：
|
||||
是。OpenClaw 附带一些默认简写（仅当模型存在于 `agents.defaults.models` 中时应用）：
|
||||
|
||||
- `opus` → `anthropic/claude-opus-4-6`
|
||||
- `sonnet` → `anthropic/claude-sonnet-4-6`
|
||||
- `gpt` → `openai/gpt-5.5` 用于 API key 设置，或在配置为 Codex OAuth 时使用 `openai-codex/gpt-5.5`
|
||||
- `gpt` → `openai/gpt-5.5` 用于 API-key 设置，或在配置为 Codex OAuth 时为 `openai-codex/gpt-5.5`
|
||||
- `gpt-mini` → `openai/gpt-5.4-mini`
|
||||
- `gpt-nano` → `openai/gpt-5.4-nano`
|
||||
- `gemini` → `google/gemini-3.1-pro-preview`
|
||||
- `gemini-flash` → `google/gemini-3-flash-preview`
|
||||
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
|
||||
|
||||
如果你用相同名称设置自己的别名，你的值会优先。
|
||||
如果你设置了同名的自定义别名，你的值优先。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -305,12 +304,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
然后 `/model sonnet`（或在受支持时使用 `/<alias>`）会解析为该模型 ID。
|
||||
然后 `/model sonnet`（或在支持时使用 `/<alias>`）会解析到该模型 ID。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="如何添加来自 OpenRouter 或 Z.AI 等其他提供商的模型？">
|
||||
OpenRouter（按 token 付费；许多模型）：
|
||||
OpenRouter（按 token 付费；很多模型）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -340,7 +339,7 @@ x-i18n:
|
||||
|
||||
如果你引用了某个提供商/模型，但缺少所需的提供商密钥，你会遇到运行时认证错误（例如 `No API key found for provider "zai"`）。
|
||||
|
||||
**添加新智能体后找不到提供商的 API 密钥**
|
||||
**添加新智能体后未找到提供商的 API key**
|
||||
|
||||
这通常表示**新智能体**的认证存储为空。认证按智能体隔离，并存储在：
|
||||
|
||||
@ -351,143 +350,119 @@ x-i18n:
|
||||
修复选项：
|
||||
|
||||
- 运行 `openclaw agents add <id>`，并在向导中配置认证。
|
||||
- 或者只将可移植的静态 `api_key` / `token` 配置档案从主智能体的认证存储复制到新智能体的认证存储中。
|
||||
- 对于 OAuth 配置档案，当新智能体需要自己的账号时，从新智能体登录；否则 OpenClaw 可以透传读取默认/主智能体，而无需克隆刷新令牌。
|
||||
- 或者仅将可移植的静态 `api_key` / `token` 配置文件从主智能体的认证存储复制到新智能体的认证存储。
|
||||
- 对于 OAuth 配置文件，当新智能体需要自己的账号时，从新智能体登录；否则 OpenClaw 可以读取默认/主智能体，而无需克隆刷新令牌。
|
||||
|
||||
不要在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。
|
||||
**不要**跨智能体复用 `agentDir`；这会导致认证/会话冲突。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 模型故障转移和“All models failed”
|
||||
## 模型故障转移和 “All models failed”
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="故障转移如何工作？">
|
||||
故障转移分两个阶段发生：
|
||||
|
||||
1. 同一提供商内的**认证配置档案轮换**。
|
||||
1. 同一提供商内的**认证配置文件轮换**。
|
||||
2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。
|
||||
|
||||
冷却时间会应用到失败的配置档案（指数退避），因此即使提供商受到速率限制或暂时失败，OpenClaw 也能继续响应。
|
||||
冷却时间会应用到失败的配置文件（指数退避），因此即使提供商受到速率限制或暂时失败，OpenClaw 仍可继续响应。
|
||||
|
||||
速率限制桶包含的不只是普通的 `429` 响应。OpenClaw
|
||||
也会将 `Too many concurrent requests`、
|
||||
`ThrottlingException`、`concurrency limit reached`、
|
||||
`workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性的
|
||||
使用窗口限制（`weekly/monthly limit reached`）等消息视为值得触发故障转移的
|
||||
速率限制。
|
||||
速率限制桶包含的不只是普通 `429` 响应。OpenClaw
|
||||
还会将 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性使用窗口限制（`weekly/monthly limit reached`）等消息视为值得触发故障转移的速率限制。
|
||||
|
||||
某些看起来像计费问题的响应不是 `402`，而某些 HTTP `402`
|
||||
响应也仍会留在这个瞬时桶中。如果提供商在 `401` 或 `403` 上返回
|
||||
明确的计费文本，OpenClaw 仍然可以将其保留在
|
||||
计费通道中，但提供商特定的文本匹配器会保持在其所属提供商的作用域内（例如 OpenRouter `Key limit exceeded`）。如果 `402`
|
||||
消息反而看起来像可重试的使用窗口或
|
||||
组织/工作区支出限制（`daily limit reached, resets tomorrow`、
|
||||
`organization spending limit exceeded`），OpenClaw 会将其视为
|
||||
`rate_limit`，而不是长期计费停用。
|
||||
一些看起来像计费问题的响应并不是 `402`，而一些 HTTP `402`
|
||||
响应也会留在该临时桶中。如果提供商在 `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` 这样的签名会留在压缩/重试路径上，而不是推进模型
|
||||
回退。
|
||||
上下文溢出错误则不同：`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` 等签名会留在压缩/重试路径上，而不是推进模型回退。
|
||||
|
||||
通用服务器错误文本有意比“任何包含
|
||||
unknown/error 的内容”更窄。当提供商上下文
|
||||
匹配时，OpenClaw 确实会将提供商作用域内的瞬时形态，
|
||||
例如 Anthropic 裸 `An unknown error occurred`、OpenRouter 裸
|
||||
`Provider returned error`、像 `Unhandled stop reason:
|
||||
error` 这样的停止原因错误、带有瞬时服务器文本的 JSON `api_error` 载荷
|
||||
（`internal server error`、`unknown error, 520`、`upstream error`、`backend
|
||||
error`），以及像 `ModelNotReadyException` 这样的提供商繁忙错误
|
||||
视为值得触发故障转移的超时/过载信号。
|
||||
像 `LLM request failed with an unknown
|
||||
error.` 这样的通用内部回退文本会保持保守，本身不会触发模型回退。
|
||||
通用服务器错误文本的范围有意比“任何包含 unknown/error 的内容”更窄。当提供商上下文匹配时，OpenClaw 确实会将提供商范围内的临时形态视为值得触发故障转移的超时/过载信号，例如 Anthropic 裸 `An unknown error occurred`、OpenRouter 裸 `Provider returned error`、类似 `Unhandled stop reason: error` 的停止原因错误、包含临时服务器文本（`internal server error`、`unknown error, 520`、`upstream error`、`backend error`）的 JSON `api_error` 载荷，以及类似 `ModelNotReadyException` 的提供商繁忙错误。
|
||||
类似 `LLM request failed with an unknown error.` 的通用内部回退文本会保持保守，本身不会触发模型回退。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='“No credentials found for profile anthropic:default”是什么意思？'>
|
||||
这表示系统尝试使用认证配置档案 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭据。
|
||||
<Accordion title='“No credentials found for profile anthropic:default” 是什么意思？'>
|
||||
这表示系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭证。
|
||||
|
||||
**修复检查清单：**
|
||||
**修复清单：**
|
||||
|
||||
- **确认认证配置档案的存放位置**（新路径与旧路径）
|
||||
- **确认认证配置文件的位置**（新路径与旧路径）
|
||||
- 当前：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）
|
||||
- **确认你的环境变量已由 Gateway 网关加载**
|
||||
- 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。把它放到 `~/.openclaw/.env`，或启用 `env.shellEnv`。
|
||||
- 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。
|
||||
- **确保你正在编辑正确的智能体**
|
||||
- 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。
|
||||
- **对模型/认证状态做完整性检查**
|
||||
- 使用 `openclaw models status` 查看已配置的模型，以及提供商是否已通过认证。
|
||||
- **完整性检查模型/认证 Status**
|
||||
- 使用 `openclaw models status` 查看已配置的模型以及提供商是否已认证。
|
||||
|
||||
**“No credentials found for profile anthropic”的修复检查清单**
|
||||
**“No credentials found for profile anthropic” 的修复清单**
|
||||
|
||||
这表示运行被固定到某个 Anthropic 认证配置档案，但 Gateway 网关
|
||||
这表示本次运行固定到了 Anthropic 认证配置文件，但 Gateway 网关
|
||||
无法在其认证存储中找到它。
|
||||
|
||||
- **使用 Claude CLI**
|
||||
- 在网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。
|
||||
- **如果你想改用 API 密钥**
|
||||
- 将 `ANTHROPIC_API_KEY` 放到**网关主机**上的 `~/.openclaw/.env` 中。
|
||||
- 清除任何强制使用缺失配置档案的固定顺序：
|
||||
- 在 gateway 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。
|
||||
- **如果你想改用 API key**
|
||||
- 将 `ANTHROPIC_API_KEY` 放入 **gateway 主机**上的 `~/.openclaw/.env`。
|
||||
- 清除任何强制使用缺失配置文件的固定顺序：
|
||||
|
||||
```bash
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
- **确认你是在网关主机上运行命令**
|
||||
- 在远程模式下，认证配置档案位于网关机器上，而不是你的笔记本电脑上。
|
||||
- **确认你正在 gateway 主机上运行命令**
|
||||
- 在远程模式下，认证配置文件位于 gateway 机器上，而不是你的笔记本电脑上。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="为什么它还尝试了 Google Gemini 并失败？">
|
||||
如果你的模型配置包含 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 请求被拒绝：需要 thinking 签名（Google Antigravity）**
|
||||
|
||||
原因：会话历史包含**没有签名的 thinking 块**（通常来自
|
||||
被中止/不完整的流）。Google Antigravity 要求 thinking 块具有签名。
|
||||
原因：会话历史包含**没有签名的 thinking 块**（通常来自中止/部分流）。Google Antigravity 要求 thinking 块带有签名。
|
||||
|
||||
修复：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking 块。如果仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。
|
||||
修复：OpenClaw 现在会为 Google Antigravity Claude 剥离未签名的 thinking 块。如果仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 认证配置档案：它们是什么以及如何管理
|
||||
## 认证配置文件：它们是什么以及如何管理
|
||||
|
||||
相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账号模式）
|
||||
相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流、令牌存储、多账号模式）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="什么是认证配置档案？">
|
||||
认证配置档案是一个命名的凭据记录（OAuth 或 API 密钥），绑定到某个提供商。配置档案位于：
|
||||
<Accordion title="什么是认证配置文件？">
|
||||
认证配置文件是绑定到提供商的命名凭证记录（OAuth 或 API key）。配置文件位于：
|
||||
|
||||
```
|
||||
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
|
||||
```
|
||||
|
||||
若要在不转储密钥的情况下检查已保存的配置文件，请运行 `openclaw models auth list`（可选 `--provider <id>` 或 `--json`）。详情请参阅 [Models CLI](/zh-CN/cli/models#openclaw-models-auth-list)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="典型的配置档案 ID 是什么？">
|
||||
<Accordion title="典型的配置文件 ID 有哪些？">
|
||||
OpenClaw 使用带提供商前缀的 ID，例如：
|
||||
|
||||
- `anthropic:default`（没有邮箱身份时常见）
|
||||
- `anthropic:default`（没有电子邮件身份时常见）
|
||||
- OAuth 身份使用 `anthropic:<email>`
|
||||
- 你选择的自定义 ID（例如 `anthropic:work`）
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="我可以控制先尝试哪个认证配置档案吗？">
|
||||
可以。配置支持配置档案的可选元数据，以及每个提供商的排序（`auth.order.<provider>`）。这**不会**存储密钥；它将 ID 映射到提供商/模式，并设置轮换顺序。
|
||||
<Accordion title="我可以控制首先尝试哪个认证配置文件吗？">
|
||||
可以。配置支持配置文件的可选元数据，以及每个提供商的顺序（`auth.order.<provider>`）。这**不会**存储密钥；它会将 ID 映射到提供商/模式并设置轮换顺序。
|
||||
|
||||
如果某个配置档案处于短暂**冷却**状态（速率限制/超时/认证失败）或较长的**停用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。
|
||||
如果某个配置文件处于短暂**冷却**（速率限制/超时/认证失败）或较长的**禁用**状态（计费/额度不足），OpenClaw 可能会暂时跳过它。若要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优：`auth.cooldowns.billingBackoffHours*`。
|
||||
|
||||
速率限制冷却可以按模型划分。某个配置档案如果正在为
|
||||
一个模型冷却，仍然可用于同一提供商上的同级模型，
|
||||
而计费/停用窗口仍会阻止整个配置档案。
|
||||
速率限制冷却可以按模型限定。一个配置文件如果针对某个模型正在冷却，仍可用于同一提供商上的同级模型，而计费/禁用窗口仍会阻止整个配置文件。
|
||||
|
||||
你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）：
|
||||
|
||||
@ -505,30 +480,29 @@ x-i18n:
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
要指定特定智能体：
|
||||
若要指定某个智能体：
|
||||
|
||||
```bash
|
||||
openclaw models auth order set --provider anthropic --agent main anthropic:default
|
||||
```
|
||||
|
||||
要验证实际会尝试什么，请使用：
|
||||
若要验证实际会尝试什么，请使用：
|
||||
|
||||
```bash
|
||||
openclaw models status --probe
|
||||
```
|
||||
|
||||
如果某个已存储的配置档案被显式顺序省略，探测会为该配置档案报告
|
||||
`excluded_by_auth_order`，而不是静默尝试它。
|
||||
如果已存储的配置文件被显式顺序省略，probe 会为该配置文件报告 `excluded_by_auth_order`，而不是静默尝试它。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OAuth 与 API 密钥有什么区别？">
|
||||
<Accordion title="OAuth 和 API key 有什么区别？">
|
||||
OpenClaw 两者都支持：
|
||||
|
||||
- **OAuth** 通常会利用订阅访问权限（在适用时）。
|
||||
- **API 密钥**使用按令牌计费。
|
||||
- **OAuth** 通常会利用订阅访问权限（如果适用）。
|
||||
- **API key** 使用按令牌计费。
|
||||
|
||||
向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。
|
||||
向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- 你希望针对 SSRF 和 DNS 重绑定攻击提供纵深防御
|
||||
- 你需要针对 SSRF 和 DNS 重绑定攻击的纵深防御
|
||||
- 为 OpenClaw 运行时流量配置外部正向代理
|
||||
summary: 如何将 OpenClaw 运行时的 HTTP 和 WebSocket 流量经由操作方管理的过滤代理进行路由
|
||||
summary: 如何通过由操作员管理的过滤代理路由 OpenClaw 运行时 HTTP 和 WebSocket 流量
|
||||
title: 网络代理
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T11:08:49Z"
|
||||
generated_at: "2026-05-05T00:55:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
|
||||
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# 网络代理
|
||||
|
||||
OpenClaw 可以通过运维方管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于希望集中控制出口流量、加强 SSRF 防护并提升网络审计能力的部署来说，这是一种可选的纵深防御措施。
|
||||
OpenClaw 可以通过由操作员管理的正向代理路由运行时 HTTP 和 WebSocket 流量。对于需要集中出站控制、更强 SSRF 防护以及更好网络可审计性的部署，这是可选的纵深防御措施。
|
||||
|
||||
OpenClaw 不会附带、下载、启动、配置或认证代理。你运行适合自己环境的代理技术，OpenClaw 会通过它路由普通的进程本地 HTTP 和 WebSocket 客户端。
|
||||
OpenClaw 不会随附、下载、启动、配置或认证代理。你运行适合你的环境的代理技术，OpenClaw 会通过它路由普通的进程本地 HTTP 和 WebSocket 客户端。
|
||||
|
||||
## 为什么使用代理？
|
||||
|
||||
代理为运维方提供一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使不考虑 SSRF 加固，这也很有用：
|
||||
代理为操作员提供了一个用于出站 HTTP 和 WebSocket 流量的网络控制点。即使在 SSRF 加固之外，这也很有用：
|
||||
|
||||
- 集中策略：维护一套出口策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。
|
||||
- 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标地址。
|
||||
- DNS 重新绑定防御：缩小应用级 DNS 检查与实际出站连接之间的空隙。
|
||||
- 更广泛的 JavaScript 覆盖：将普通的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 以及类似客户端路由到同一路径。
|
||||
- 可审计性：在出口边界记录允许和拒绝的目标。
|
||||
- 集中策略：维护一套出站策略，而不是依赖每个应用 HTTP 调用点都正确处理网络规则。
|
||||
- 连接时检查：在 DNS 解析之后、代理打开上游连接之前立即评估目标。
|
||||
- DNS 重新绑定防御：缩小应用级 DNS 检查与实际出站连接之间的间隙。
|
||||
- 更广泛的 JavaScript 覆盖：通过同一路径路由普通 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 和类似客户端。
|
||||
- 可审计性：在出站边界记录允许和拒绝的目标。
|
||||
- 运维控制：无需重新构建 OpenClaw，就能强制执行目标规则、网络分段、速率限制或出站允许列表。
|
||||
|
||||
代理路由是普通 HTTP 和 WebSocket 出口的进程级护栏。它为运维方提供了一条故障关闭路径，用于将受支持的 JavaScript HTTP 客户端路由到他们自己的过滤代理，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证代理的目标策略。
|
||||
代理路由是普通 HTTP 和 WebSocket 出站流量的进程级护栏。它为操作员提供了一条故障关闭路径，用于将受支持的 JavaScript HTTP 客户端通过自己的过滤代理路由，但它不是操作系统级网络沙箱，也不会让 OpenClaw 认证代理的目标策略。
|
||||
|
||||
## OpenClaw 如何路由流量
|
||||
|
||||
当 `proxy.enabled=true` 且配置了代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出口：
|
||||
当 `proxy.enabled=true` 且配置了代理 URL 时，受保护的运行时进程（例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`）会通过配置的代理路由普通 HTTP 和 WebSocket 出站流量：
|
||||
|
||||
```text
|
||||
OpenClaw process
|
||||
@ -43,27 +43,28 @@ OpenClaw process
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
公开契约是路由行为，而不是用于实现它的内部 Node 钩子。当 Gateway 网关 URL 使用 `localhost` 或字面量环回 IP（例如 `127.0.0.1` 或 `[::1]`）时，OpenClaw Gateway 网关控制平面 WebSocket 客户端会为 local loopback Gateway 网关 RPC 流量使用一条狭窄的直连路径。即使运维方代理阻止环回目标，该控制平面路径也必须能够访问环回 Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍会使用配置的代理。
|
||||
公共合约是路由行为，而不是用于实现它的内部 Node 钩子。OpenClaw Gateway 网关控制平面 WebSocket 客户端在 Gateway 网关 URL 使用 `localhost` 或字面量 loopback IP（例如 `127.0.0.1` 或 `[::1]`）时，会对 local loopback Gateway RPC 流量使用一条狭窄的直连路径。即使操作员代理阻止 loopback 目标，该控制平面路径也必须能够访问 loopback Gateway 网关。普通运行时 HTTP 和 WebSocket 请求仍然使用配置的代理。
|
||||
|
||||
在内部，OpenClaw 为此功能使用两个进程级路由钩子：
|
||||
|
||||
- Undici dispatcher 路由覆盖 `fetch`、基于 undici 的客户端，以及提供自身 undici dispatcher 的传输协议。
|
||||
- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多构建在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的库。托管代理模式会强制使用该全局 agent，这样显式 Node HTTP agent 不会意外绕过运维方代理。
|
||||
- Undici dispatcher 路由覆盖 `fetch`、基于 undici 的客户端，以及提供自己的 undici dispatcher 的传输协议。
|
||||
- `global-agent` 路由覆盖 Node 核心 `node:http` 和 `node:https` 调用方，包括许多基于 `http.request`、`https.request`、`http.get` 和 `https.get` 分层的库。托管代理模式会强制使用该全局 agent，因此显式 Node HTTP agent 不会意外绕过操作员代理。
|
||||
|
||||
一些插件拥有自定义传输协议，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输协议使用自己的 HTTP/1 undici dispatcher，因此会在该 owner 专用传输路径中遵循进程代理环境以及托管的 `OPENCLAW_PROXY_URL` 回退。
|
||||
某些插件拥有自定义传输协议，即使存在进程级路由，也需要显式代理接线。例如，Telegram 的 Bot API 传输使用自己的 HTTP/1 undici dispatcher，因此会在该所有者特定的传输路径中遵循进程代理环境以及托管的 `OPENCLAW_PROXY_URL` 回退。
|
||||
|
||||
代理 URL 本身必须使用 `http://`。HTTPS 目标仍支持通过代理使用 HTTP `CONNECT`；这只表示 OpenClaw 期望一个普通 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。
|
||||
代理 URL 本身必须使用 `http://`。HTTPS 目标仍然通过带有 HTTP `CONNECT` 的代理受支持；这只表示 OpenClaw 期望一个普通 HTTP 正向代理监听器，例如 `http://127.0.0.1:3128`。
|
||||
|
||||
代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标地址，因此如果将 `localhost` 或 `127.0.0.1` 留在那里，高风险 SSRF 目标就能跳过过滤代理。
|
||||
代理处于活动状态时，OpenClaw 会清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。这些绕过列表基于目标，因此如果其中保留 `localhost` 或 `127.0.0.1`，高风险 SSRF 目标就会跳过过滤代理。
|
||||
|
||||
关闭时，OpenClaw 会恢复之前的代理环境，并重置缓存的进程路由状态。
|
||||
关闭时，OpenClaw 会恢复先前的代理环境并重置缓存的进程路由状态。
|
||||
|
||||
## 相关代理术语
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 运行时出口的出站正向代理路由。本页介绍此功能。
|
||||
- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理认证。参见[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
- `openclaw proxy`：用于开发和支持的本地调试代理和捕获检查器。参见 [openclaw proxy](/zh-CN/cli/proxy)。
|
||||
- 渠道或提供商专用代理设置：特定传输协议的 owner 专用覆盖。当目标是在整个运行时集中控制出口流量时，优先使用托管网络代理。
|
||||
- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 运行时出站流量的出站正向代理路由。此页面记录该功能。
|
||||
- `gateway.auth.mode: "trusted-proxy"`：用于 Gateway 网关访问的入站身份感知反向代理认证。请参阅 [可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
- `openclaw proxy`：用于开发和支持的本地调试代理和捕获检查器。请参阅 [openclaw proxy](/zh-CN/cli/proxy)。
|
||||
- `tools.web.fetch.useTrustedEnvProxy`：为 `web_fetch` 选择启用由操作员控制的 HTTP(S) 环境代理来解析 DNS，同时保留默认的严格 DNS 固定和主机名策略。请参阅 [Web fetch](/zh-CN/tools/web-fetch#trusted-env-proxy)。
|
||||
- 渠道或提供商特定的代理设置：特定传输协议的所有者特定覆盖。当目标是在整个运行时中进行集中出站控制时，优先使用托管网络代理。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
|
||||
`proxy.proxyUrl` 优先于 `OPENCLAW_PROXY_URL`。
|
||||
|
||||
如果 `enabled=true` 但未配置有效的代理 URL，受保护命令会启动失败，而不是回退到直接网络访问。
|
||||
如果 `enabled=true` 但没有配置有效的代理 URL，受保护命令会在启动时失败，而不是回退到直接网络访问。
|
||||
|
||||
对于使用 `openclaw gateway start` 启动的托管 Gateway 网关服务，建议将 URL 存储在配置中：
|
||||
对于使用 `openclaw gateway start` 启动的托管 Gateway 网关服务，优先将 URL 存储在配置中：
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -94,49 +95,49 @@ openclaw gateway start
|
||||
|
||||
环境回退最适合前台运行。如果你将它用于已安装的服务，请将 `OPENCLAW_PROXY_URL` 放入服务的持久环境中，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然后重新安装服务，让 launchd、systemd 或 Scheduled Tasks 使用该值启动 Gateway 网关。
|
||||
|
||||
对于 `openclaw --container ...` 命令，当设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将它转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器自身，而不是主机。除非你显式覆盖该安全检查，否则 OpenClaw 会拒绝面向容器命令的环回代理 URL。
|
||||
对于 `openclaw --container ...` 命令，设置了 `OPENCLAW_PROXY_URL` 时，OpenClaw 会将它转发到面向容器的子 CLI。该 URL 必须能从容器内部访问；`127.0.0.1` 指的是容器自身，而不是主机。除非你显式覆盖该安全检查，否则 OpenClaw 会拒绝面向容器的命令中的 loopback 代理 URL。
|
||||
|
||||
## 代理要求
|
||||
|
||||
代理策略是安全边界。OpenClaw 无法验证代理是否阻止了正确的目标。
|
||||
|
||||
请将代理配置为：
|
||||
配置代理以：
|
||||
|
||||
- 仅绑定到环回或可信的私有接口。
|
||||
- 仅绑定到 loopback 或私有可信接口。
|
||||
- 限制访问，使只有 OpenClaw 进程、主机、容器或服务账号可以使用它。
|
||||
- 自行解析目标，并在 DNS 解析后阻止目标 IP。
|
||||
- 对普通 HTTP 请求和 HTTPS `CONNECT` 隧道都在连接时应用策略。
|
||||
- 拒绝针对环回、私有、链路本地、元数据、多播、保留或文档范围的基于目标的绕过。
|
||||
- 除非你完全信任 DNS 解析路径，否则避免使用主机名允许列表。
|
||||
- 记录目标、决策、状态和原因，但不要记录请求正文、授权标头、Cookie 或其他机密。
|
||||
- 自行解析目标，并在 DNS 解析之后阻止目标 IP。
|
||||
- 在连接时对普通 HTTP 请求和 HTTPS `CONNECT` 隧道应用策略。
|
||||
- 拒绝基于目标的绕过，覆盖 loopback、私有、链路本地、元数据、多播、保留或文档范围。
|
||||
- 避免主机名允许列表，除非你完全信任 DNS 解析路径。
|
||||
- 记录目标、决策、状态和原因，但不记录请求正文、授权标头、Cookie 或其他机密。
|
||||
- 将代理策略置于版本控制之下，并像审查安全敏感配置一样审查更改。
|
||||
|
||||
## 建议阻止的目标
|
||||
## 推荐阻止的目标
|
||||
|
||||
将此拒绝列表作为任何正向代理、防火墙或出口策略的起点。
|
||||
将此拒绝列表作为任何正向代理、防火墙或出站策略的起点。
|
||||
|
||||
OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的对等钩子包括 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及用于 NAT64、6to4、Teredo、ISATAP 和 IPv4 映射形式的嵌入式 IPv4 哨兵处理。这些文件在维护外部代理策略时是有用的参考，但 OpenClaw 不会自动导出这些规则或在你的代理中强制执行它们。
|
||||
OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相关的对等钩子是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及针对 NAT64、6to4、Teredo、ISATAP 和 IPv4-mapped 形式的嵌入式 IPv4 哨兵处理。在维护外部代理策略时，这些文件是有用的参考，但 OpenClaw 不会自动在你的代理中导出或强制执行这些规则。
|
||||
|
||||
| 范围或主机 | 阻止原因 |
|
||||
| 范围或主机 | 阻止原因 |
|
||||
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 环回 |
|
||||
| `::1/128` | IPv6 环回 |
|
||||
| `0.0.0.0/8`, `::/128` | 未指定地址和本网络地址 |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有网络 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | 链路本地地址和常见云元数据路径 |
|
||||
| `169.254.169.254`, `metadata.google.internal` | 云元数据服务 |
|
||||
| `100.64.0.0/10` | 运营商级 NAT 共享地址空间 |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | 基准测试范围 |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档范围 |
|
||||
| `224.0.0.0/4`, `ff00::/8` | 多播 |
|
||||
| `240.0.0.0/4` | 保留 IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | IPv6 本地/私有范围 |
|
||||
| `100::/64`, `2001:20::/28` | IPv6 丢弃和 ORCHIDv2 范围 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | 带嵌入式 IPv4 的 NAT64 前缀 |
|
||||
| `2002::/16`, `2001::/32` | 带嵌入式 IPv4 的 6to4 和 Teredo |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4 兼容和 IPv4 映射的 IPv6 |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
|
||||
| `::1/128` | IPv6 loopback |
|
||||
| `0.0.0.0/8`, `::/128` | 未指定地址和本网络地址 |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC1918 私有网络 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | 链路本地地址和常见云元数据路径 |
|
||||
| `169.254.169.254`, `metadata.google.internal` | 云元数据服务 |
|
||||
| `100.64.0.0/10` | 运营商级 NAT 共享地址空间 |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | 基准测试范围 |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文档范围 |
|
||||
| `224.0.0.0/4`, `ff00::/8` | 多播 |
|
||||
| `240.0.0.0/4` | 保留 IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | IPv6 本地/私有范围 |
|
||||
| `100::/64`, `2001:20::/28` | IPv6 丢弃和 ORCHIDv2 范围 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | 带嵌入式 IPv4 的 NAT64 前缀 |
|
||||
| `2002::/16`, `2001::/32` | 带嵌入式 IPv4 的 6to4 和 Teredo |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4-compatible 和 IPv4-mapped IPv6 |
|
||||
|
||||
如果你的云提供商或网络平台记录了额外的元数据主机或保留范围，也请将它们加入。
|
||||
如果你的云提供商或网络平台记录了额外的元数据主机或保留范围，也请加入这些目标。
|
||||
|
||||
## 验证
|
||||
|
||||
@ -146,9 +147,9 @@ OpenClaw 应用级分类器逻辑位于 `src/infra/net/ssrf.ts` 和 `src/shared/
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
默认情况下，如果没有提供自定义目标，该命令会检查 `https://example.com/` 是否成功，并启动一个临时环回 canary，代理不得访问该 canary。当代理返回非 2xx 拒绝响应，或以传输失败阻止 canary 时，默认拒绝检查通过；如果成功响应到达 canary，则检查失败。如果未启用并配置代理，验证会报告配置问题；在更改配置前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试部署特定预期。添加 `--apns-reachable` 还可验证直接 APNs HTTP/2 递送是否能够通过代理打开 CONNECT 隧道并收到沙箱 APNs 响应；该探测使用故意无效的提供商令牌，因此预期结果为 `403 InvalidProviderToken`，并会计为可达。自定义拒绝目标采用故障关闭：任何 HTTP 响应都表示目标可通过代理访问，而任何传输错误都会报告为无法判定，因为 OpenClaw 无法证明代理阻止了一个可达来源。验证失败时，该命令以代码 1 退出。
|
||||
默认情况下，如果没有提供自定义目标，该命令会检查 `https://example.com/` 是否成功，并启动一个临时 loopback 金丝雀，代理不得访问它。当代理返回非 2xx 拒绝响应，或通过传输失败阻止金丝雀时，默认拒绝检查通过；如果成功响应到达金丝雀，则检查失败。如果未启用和配置代理，验证会报告配置问题；在更改配置之前，可使用 `--proxy-url` 进行一次性预检。使用 `--allowed-url` 和 `--denied-url` 测试部署特定预期。添加 `--apns-reachable` 还可以验证直接 APNs HTTP/2 交付能否通过代理打开 CONNECT 隧道并收到沙箱 APNs 响应；该探测使用故意无效的提供商令牌，因此预期会得到 `403 InvalidProviderToken`，并将其计为可达。自定义拒绝目标采用故障关闭：任何 HTTP 响应都表示目标可通过代理访问，任何传输错误都会报告为不确定，因为 OpenClaw 无法证明代理阻止了可达源站。验证失败时，该命令以代码 1 退出。
|
||||
|
||||
使用 `--json` 进行自动化。JSON 输出包含总体结果、有效代理配置来源、任何配置错误，以及每个目标检查。代理 URL 凭据会在文本和 JSON 输出中被遮盖：
|
||||
使用 `--json` 进行自动化处理。JSON 输出包含总体结果、实际生效的代理配置来源、任何配置错误，以及每个目标检查。代理 URL 凭证会在文本和 JSON 输出中被遮蔽：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -176,7 +177,7 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
}
|
||||
```
|
||||
|
||||
你也可以使用 `curl` 手动验证：
|
||||
你也可以用 `curl` 手动验证：
|
||||
|
||||
```bash
|
||||
curl -x http://127.0.0.1:3128 https://example.com/
|
||||
@ -184,7 +185,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
公共请求应成功。回环和元数据请求应被代理阻止。对于 `openclaw proxy validate`，内置回环探针可以区分代理拒绝和可达源站。自定义 `--denied-url` 检查没有该探针，因此除非你的代理公开了可单独验证的部署特定拒绝信号，否则应将 HTTP 响应和含糊的传输失败都视为验证失败。
|
||||
公共请求应当成功。回环和元数据请求应当被代理阻止。对于 `openclaw proxy validate`，内置回环探针可以区分代理拒绝和可访问的来源。自定义 `--denied-url` 检查没有该探针，因此请将 HTTP 响应和含糊的传输失败都视为验证失败，除非你的代理暴露了特定于部署的拒绝信号，并且你可以单独验证它。
|
||||
|
||||
然后启用 OpenClaw 代理路由：
|
||||
|
||||
@ -204,11 +205,11 @@ proxy:
|
||||
|
||||
## 限制
|
||||
|
||||
- 该代理改善了进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是 OS 级网络沙箱。
|
||||
- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及子进程可能绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。
|
||||
- IRC 是一个原始 TCP/TLS 渠道，位于操作员管理的正向代理路由之外。在要求所有出站流量都经过该正向代理的部署中，除非已明确批准直接 IRC 出站流量，否则请设置 `channels.irc.enabled=false`。
|
||||
- 本地调试代理是诊断工具；在托管代理模式处于活动状态时，默认禁用其对代理请求和 CONNECT 隧道的直接上游转发；仅为已批准的本地诊断启用直接转发。
|
||||
- 需要时，应在操作员代理策略中允许用户本地 WebUI 和本地模型服务器；OpenClaw 不会为它们公开通用的本地网络绕过机制。
|
||||
- Gateway 网关控制平面的代理绕过有意限制为 `localhost` 和字面量回环 IP URL。请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789` 进行本地直连 Gateway 网关控制平面连接；其他主机名会像普通基于主机名的流量一样路由。
|
||||
- 代理可以提升对进程本地 JavaScript HTTP 和 WebSocket 客户端的覆盖范围，但它不是操作系统级网络沙箱。
|
||||
- 原始 `net`、`tls` 和 `http2` 套接字、原生插件以及子进程可能会绕过 Node 级代理路由，除非它们继承并遵守代理环境变量。
|
||||
- IRC 是原始 TCP/TLS 渠道，位于运维方管理的正向代理路由之外。在要求所有出站流量都通过该正向代理的部署中，除非明确批准直接 IRC 出站，否则请设置 `channels.irc.enabled=false`。
|
||||
- 本地调试代理是诊断工具；当托管代理模式处于活动状态时，它对代理请求和 CONNECT 隧道的直接上游转发默认禁用；仅为已批准的本地诊断启用直接转发。
|
||||
- 需要时，应在运维方代理策略中将用户本地 WebUI 和本地模型服务器加入允许列表；OpenClaw 不会为它们暴露通用的本地网络绕过能力。
|
||||
- Gateway 网关控制平面代理绕过被有意限制为 `localhost` 和字面回环 IP URL。对本地直连 Gateway 网关控制平面连接，请使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主机名会像普通基于主机名的流量一样路由。
|
||||
- OpenClaw 不会检查、测试或认证你的代理策略。
|
||||
- 将代理策略更改视为安全敏感的运维更改。
|
||||
- 请将代理策略变更视为安全敏感的运维变更。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user