配置与迁移修复

检查 0-2 涵盖配置规范化和旧版配置键迁移， 以及 doctor 如何在更新期间发布共享状态模式。

更新期间的通道所有权¶

当 Doctor 将没有 default: true 标记的旧版 agents.list 名册迁移到显式所有权时，它还会保留未绑定账户，并为其建立到旧列表中第一个 agent 的绑定，这些账户在更新前接收了它们的隐式流量。现有账户绑定和更窄的会话路由保持不变。Doctor 会报告每个新增绑定，并通过正常的配置备份和验证流程将其与名册迁移一起保存。

更新通道迁移和手动 openclaw doctor --fix 使用配置快照中的原始名册。更窄的会话路由永远不会建立账户范围所有权。如果原始名册不可用，Doctor 会报告 unresolved: original roster unavailable，并给出需要添加的确切绑定，同时保持该账户的绑定不变。未解决账户会因该原因保持阻塞，同时 Gateway 和其他账户继续运行；它不会进入重启循环。添加所报告的绑定并重启 Gateway。

通道 Webhook 监听器¶

Feishu、Nextcloud Talk 和 Telegram 在 Gateway HTTP 路由上接收 Webhook。其插件拥有的 Doctor 迁移将显式配置的 webhookPort 和有效绑定主机移动到 legacyWebhook: { port, host? }。未指定端口的显式主机将保留该主机，并使用通道的先前端口（Feishu 为 3000，Nextcloud Talk 为 8788，Telegram 为 8787）。 Doctor 通过正常写入流程验证并备份配置。兼容性监听器仅将其已注册的 Webhook 路由通过相同的 Gateway 请求管道转发，并在通道重启期间保留签名和重试响应。

导出的 Feishu、Microsoft Teams、Nextcloud Talk 和 Telegram 配置类型保留已弃用的监听器输入属性（webhookPort、webhookHost 或 webhook.port），直到下一个 Plugin SDK 主要版本。TypeScript 配置生产者保持源码兼容，但解析后的运行时配置仅使用 legacyWebhook；在使用旧版输入之前运行 Doctor。此类型兼容窗口不会安排移除默认监听器。

将外部回调或反向代理上游更新为 Gateway 端口和通道的 Webhook 路径，验证投递，然后设置 legacyWebhook: false 以关闭旧端口。省略 legacyWebhook 会在 Webhook 传输处于活动状态时保留 Feishu 先前的 127.0.0.1:3000 监听器、Nextcloud Talk 的 0.0.0.0:8788 监听器或 Telegram 的 127.0.0.1:8787 监听器。 显式对象选择其配置的端点；账户级值覆盖通道级设置。Doctor 会解释规范的 Gateway 路由和退出选项，而不更改隐式设置。当没有账户保留该端点时，共享兼容性端口会关闭。

此行为对现有安装和新安装相同。它不需要升级资格检查或迁移回执。移除 legacyWebhook: false 会恢复默认监听器；移除显式对象也会返回默认。退役这些监听器是另一项未来变更，此处未引入移除截止日期或自动过期。

Telegram 在启动时重新注册其配置的公共 webhookUrl。它保留该 URL，因为其反向代理上游无法安全推断。在不同显式端口上共享路径和密钥的账户保留其旧端口路由；在将它们迁移到一个 Gateway 端口之前，分配不同的密钥或路径。

在 2026.9.6 主机上单独安装的 Telegram 插件执行相同的配置迁移，但该主机早于 Gateway 拥有的转发。Telegram 在那里保留前任的直接按账户监听器；账户需要不同的旧版端点。Doctor 将监听器指导放入其支持的警告输出中，并指出此限制。在较新的主机上，共享 Gateway 监听器和信息性说明保持不变。

Microsoft Teams 使用相同的所有者：Doctor 将显式 channels.msteams.webhook.port 移动到 channels.msteams.legacyWebhook.port，保留 webhook.path。省略的监听器设置保留端口 3978 及其先前的通配符绑定。通过 Gateway 端口验证 Azure Bot 端点后，设置 channels.msteams.legacyWebhook: false 以关闭兼容性监听器。Teams 在两个监听器上保留其 Express 主体解析器和 SDK 身份验证。

ACP 代理的模型优先级¶

对于具有 runtime.type: "acp" 的代理，agents.entries.*.model（字符串形式）或 agents.entries.*.model.primary（对象形式）选择 ACP 框架模型。这也适用于看起来像 provider/model 引用的框架选择。OpenClaw 解析一个独立的原生默认值，在配置时使用 agents.defaults.model。显式的原生会话、实用程序和子代理模型选择保留其优先级。

Doctor 将此分离报告为信息（core/doctor/acp-agent-model），指明配置路径、框架模型和解析后的原生默认值。匹配和不匹配的选择都是受支持的配置。此通知不建议修复，也不重写配置；ACP 回合保留其配置的框架选择。

迁移期间缺失的插件¶

已配置但缺失或无法完成安装的插件不会阻塞 Doctor、更新或 Gateway 启动。OpenClaw 记录一条警告，指明插件、其待处理迁移以及完成安装或修复的命令。Gateway 继续提供可用插件的服务。

doctor --fix 在记录待处理插件迁移之前修复较旧的共享数据库模式。因此，缺失的插件不会阻止数据库修复；它们的输入保持可用，以便稍后重试。

延迟迁移保留其状态和旧版配置输入。配置修复仍可以更新无关设置，而待处理插件的已退役字段保持不活动。安装或修复插件后，运行 openclaw doctor --fix 以完成其迁移并清除待处理警告。在由较旧版本驱动的更新期间，插件安装可以保持延迟，直到该更新器完成；其待处理输入获得相同的保护。核心导入后进行的会话编辑和删除在插件迁移恢复时仍然具有权威性。

在迁移待处理期间，任何会修改或删除其保留输入的显式配置编辑都会通过恢复命令被拒绝。无关设置仍可写入。请在编辑这些输入之前完成插件迁移。

已退役的 TaskFlow Webhooks 插件¶

捆绑的 TaskFlow Webhooks 插件已被移除。现有的 plugins.entries.webhooks 设置会被忽略，并带有 plugin removed: webhooks 警告，以便 Gateway 在更新后能够启动。运行 openclaw doctor --fix 通过正常的配置备份和修复流程移除其过期条目以及 plugins.allow 或 plugins.deny 引用。此次退役不会更改数据库架构，也不会删除已存储的 Tasks 或 TaskFlows。

如果 Webhooks 是 plugins.allow 中唯一的插件，Doctor 会保留其他已启用插件作为显式允许列表条目，包括已配置的捆绑通道以及选定的 memory 或 context-engine 插件。现有的 deny 和 disable 设置仍然适用。Doctor 会报告保留的 ID；在更改通道或插件槽位时请审查此列表，因为这些条目仍然是显式插件权限。

如果没有已启用插件保留，Doctor 会设置 plugins.enabled: false。否则，空的允许列表会允许无关的已安装插件加载。请审查剩余的插件选项，将 plugins.allow 设置为你想要的插件，然后重新启用插件。

如果某个活动插件的旧 ID 别名指向不同的所有者，Doctor 会保持过期的插件设置不变，并发出警告，而不是授予该其他所有者访问权限。请选择不冲突的允许插件 ID，然后重新运行 openclaw doctor --fix 以完成清理。其他 Doctor 修复会继续进行。

使用 Gateway HTTP hooks 从外部服务唤醒 agent 或提交 agent 回合。它们的 hooks.* 设置、内部事件 hooks 以及 openclaw webhooks gmail 命令仍然可用。来自已退役插件的 TaskFlow 记录操作没有等效的 HTTP 端点。

2026.9.2 更新期间的架构发布¶

当 OpenClaw 2026.9.2 驱动需要更新共享状态架构的更新时，Doctor 会应用迁移内容并报告 schema content applied; version publication deferred until update run <id> finishes。旧 updater 可以完成其 ledger 访问，而新 Gateway 会使用迁移后的内容。发布会等待，直到所有受影响的终结运行至少已有五分钟；运行超过 30 分钟未变化的行被视为已放弃。每个可写入的数据库打开都遵循此规则，Gateway watcher 会在截止时间后安排发布。

当该 Gateway 运行时，普通 CLI 命令（包括 Doctor）仍可使用。已应用的内容视为就绪；只有拥有该状态的 Gateway，或者在没有 Gateway 拥有状态目录时的可写入打开者，会在宽限期后发布版本。

Agent 数据库迁移不会延迟版本。在已发布的 2026.9.2 updater 的回滚窗口期间，Doctor 会验证私有状态副本，并保持实时数据库和配置不变。在包回滚不再可能之后，新的更新继续操作要求经过验证的备份覆盖每个待处理的 agent 数据库和当前更新所有权，然后 Doctor 才会迁移实时状态。受管更新会保留随附 helper 的原始交接记录不变。

当无法验证此交接、缺少备份覆盖、所需的共享状态元数据表缺失或迁移失败时，Doctor 会报告 update-schema-bump-unfenced。请从拒绝信息开始遵循 手动更新序列。请参阅 数据库架构，了解发布契约以及旧 CLI 停滞超过宽限期后剩余的风险。

Tasks 移除后的原生 Codex 恢复¶

Codex 插件的 codex-native-task-assignments Doctor 迁移在从 Tasks 运行时升级时保留可恢复的原生子工作。它通过现有的插件状态迁移生命周期运行，包括更新时的 Doctor。在直接二进制替换后，请在启动新 Gateway 之前运行 openclaw doctor --fix。

在维护期间，Doctor 读取 ~/.openclaw/state/openclaw.sqlite 的快照，并选择具有 runtime = 'subagent' 和 task_kind = 'codex-native' 的旧 task_runs 记录。它仅导入唯一标识的、未确认的工作，其 nativeHistory 所有者标记与当前请求方的物理会话、生命周期修订版本和 Codex 连接匹配。这些所有权标记已存在于已发布的 2026.9.4 状态中。原生线程轮换后，原始原生父级可能不同，但轮换无法提供缺失的请求方所有权。已提升为 Task 行的初始子项和后续项保留其精确的子项和回合定位器。当原生历史不再包含结果时，已持久化的终结摘要、状态和完成时间仍可用。

在重试预算耗尽后标记为 failed 的终结交付保持为历史记录，不会自动重启。

该迁移在现有 app-server-thread-bindings 插件状态上，通过一次比较并应用操作同时写入 nativeSubagentAssignments 和每个源 Task ID 标记 nativeSubagentTaskImport。已更改的绑定会被保留并报告以供重试。确认可以消耗该分配，而导入标记会在确认、原生轮换、清除和重置后保留，因此未更改的旧行无法复活已完成的工作。共享数据库在迁移的备份清单中声明；每个源 Task 行保持字节级一致。没有新的 SQL 表、架构版本提升、Tasks 运行时读取器或替代 Task 台账。原生执行和完成交付仍需要当前请求方权限。

未标记的记录（包括 2026.9.2 时代的行）无法建立缺失的物理请求方和连接历史。Doctor 还会保留存在歧义的重复运行 ID 以及所有权不再匹配的记录。它会发出可恢复的警告，标识 Task 和原生运行，而不会禁用 Gateway 或无关会话。请在其原始原生 Codex 账户中检查该子项，或恢复与其匹配的 OpenClaw 版本的更新前备份以完成交付。在解决可修复的绑定冲突后，再次运行 openclaw doctor --fix。该迁移不会仅根据当前父级猜测所有权。

重放 2026 年 7 月配置升级¶

在已安装其 pnpm 依赖项的源代码检出目录中，运行：

node scripts/doctor-config-upgrade-replay.mjs

该驱动脚本使用纯 Node 运行，并且仅导入 Node 内置模块。它需要该检出目录中的 fixture 和 pnpm openclaw 构建包装器；仅安装 npm 包无法运行此重放。驱动脚本无需调用 tsx。

该重放使用合成的 test/fixtures/doctor-2026.7.1.json 配置。它通过 pnpm openclaw 构建，将 home、state、config 和 logs 隔离在 .local 下，并选择空闲的 loopback 端口。它会捕获修复前的验证、两次 doctor --fix --non-interactive 运行、第一次运行后的验证以及 Gateway 启动。它会将原始配置、两个修复后的副本以及命令输出保留在打印出的目录中。第二次运行必须使配置字节保持不变。它永远不需要凭据或正在运行的 Gateway。

第二个 fixture 覆盖在移除已弃用的 TTS 字段之前，messages.tts 迁移到 tts 的情况。Doctor 在移除 prefsPath 之前，会在共享机器状态中保留旧的偏好文件路径；现有规范设置和已存储状态保持优先，并且偏好文件保持完整。

该 fixture 组合了一个双 agent 的 agents.list 名册、旧版模型允许列表、本地内存搜索、一个 CLI 音频模型、Telegram 账户允许列表，以及已弃用的 meta.lastTouchedAt、gateway.tailscale.resetOnExit 和 gateway.nodes.denyCommands 键。当前媒体字段是可选的复数 capabilities；Doctor 在将仅音频模型迁移到 tools.media.models 时会添加 ["audio"]。不需要单数 capability 字段。

本地嵌入保留 local 提供程序及其现有模型选择。进程内 node-llama-cpp 运行时已被受管理的 llama-server 取代。当缺少受管理设置时，Doctor 和 Gateway 启动会指明降级的语义召回以及插件的引导设置命令：

openclaw models --agent main auth login --provider llama-cpp --method local

交互式运行该命令并选择适当的受管理设置，然后使用 openclaw memory status --deep 验证。设置可以提供嵌入而不更改聊天模型。下载需要设置同意。在 7 月提供程序中，memorySearch.model 未选择本地 GGUF：是 local.modelPath 选择了它。因此，Doctor 会保留这两个字段，而不是将某个被忽略的模型值静默转换为不同的嵌入模型。参见 llama.cpp。

检查 0-2¶

普通 Doctor（包括 `doctor --non-interactive`）会在共享迁移转换产生完全有效结果时，自动规范化旧版单文件配置。这也涵盖调用 Doctor 时未使用 `--fix` 的旧版 npm 更新器。规划器仍要求完整的插件验证。Doctor 会在配置备份环中保留原始配置，并保持状态迁移顺序完整。包含项、外部管理的配置、较新写入的配置以及剩余的验证错误需要现有的显式修复或操作员恢复路径。明确推迟插件修复或表明稍后写入配置交接的更新器会保持自动规范化推迟。没有 `--fix`，这不会启用修复维护、服务变更或 exec-approval 迁移。

Older Git updaters can keep an in-memory config snapshot and write it after Doctor exits. When that parent marks the update in progress without advertising support for Doctor config writes, Doctor preserves the config and defers importing retired plugin install records, including with --fix. A supported fresh update continuation runs Doctor before plugin convergence and rereads the repaired config. Existing canonical plugin install records keep precedence. Doctor imports missing records before rewriting config and completes required workspace-state migration in the same repair pass. An older Git updater without that continuation requires openclaw doctor --fix after the update; Gateway startup does not finish its legacy repair.

    旧版 Git 更新器可能会保留内存中的配置快照，并在 Doctor 退出后写入它。当该父进程将更新标记为进行中，但未声明支持 Doctor 配置写入时，Doctor 会保留配置，并推迟导入已退役的插件安装记录，包括使用 `--fix` 时。受支持的新更新续接会在插件收敛之前运行 Doctor，并重新读取修复后的配置。现有的规范插件安装记录保持优先。Doctor 会在重写配置之前导入缺失的记录，并在同一修复过程中完成所需的工作区状态迁移。没有该续接的旧版 Git 更新器需要在更新后运行 `openclaw doctor --fix`；Gateway 启动不会完成其遗留修复。

    Gateway 和本地 CLI 启动时会验证当前配置，而不会重写遗留键。无效的遗留配置保持不变，启动时会打印 `openclaw doctor --fix` 提示。交互式终端可以提供运行 Doctor 并重试一次；无头服务会带着该提示停止。Doctor 在写入经过验证的修复之前，会将原始配置保留在五个槽位的 `openclaw.json.bak` / `.bak.1` 到 `.bak.4` 备份环中。包含项、外部管理的配置、较新写入的配置以及未解决的验证错误，均保留其现有的修复和恢复保护机制。

    普通配置恢复可以恢复已经有效的备份，而不改变其原始字节。需要遗留转换的备份必须通过 Doctor 恢复，Doctor 会在验证和恢复之前应用相同的共享迁移转换。

    Doctor 在迁移写入之前会检查原始配置修订版本、包含的文件以及环境解析后的值。运行时路径展开（例如 Windows 上的 `~/.openclaw/wiki`）不算作输入变更。真实变更会报告配置路径、文件内容、包含的文件或解析后的值是否发生变化；请重新运行 Doctor，以便迁移可以验证新的输入。

    当模型迁移在订阅/OAuth 与按量 API 密钥计费之间更改已配置的消费者时，Doctor 会在保存配置后报告该消费者、模型以及旧路由和新路由。该警告还会出现在诊断日志和更新运行记录中。如果解析后的计费路由未发生变化，后续 Doctor 运行不会重复该警告。缺少凭据不会被视为计费变更的证据。

    在更新期间，Doctor 会记录必须等待插件安装完成才能执行的模型退役修复。更新后的 OpenClaw 会在插件收敛后完成这些修复，即使没有插件版本发生变化。`openclaw update status` 会记录它们的完成状态，以免已退役的订阅模型回退到按量 API 凭据。

    实用模型分离会在记录 `meta.migrations.utilityModelSeparation: true` 之前保留旧配置中的隐式主模型。Doctor 和常规配置写入会使用之前的配置显式保存该主模型；现有的主模型选择、回退和凭据绑定仍保持权威。当旧的隐式主模型同时服务于实用任务时，这可以保持常规聊天可用。全新的实用设置会记录该分离而不选择主模型，且在实用设置期间添加的提供商不会被误认为之前的主模型。参见 [代理模型配置](../config-agents/models.md#agentsdefaultsmodel)。

    遇到遗留键的其他命令仍会要求你运行 `openclaw doctor`。Doctor 会解释这些问题，显示其迁移，并使用更新后的架构重写 `~/.openclaw/openclaw.json`。Cron 作业存储迁移也由 `openclaw doctor --fix` 处理；自动配置键迁移不会导入遗留会话存储或修复服务。

    当可读的活动配置可以完全迁移时，Doctor 会在考虑最后已知正常恢复之前保留它。这包括带有 `default: true` 所有者的遗留多代理名册：无关设置和原始代理所有权会在迁移中保留下来。

    按代理迁移同时适用于键控 `agents.entries` 和遗留 `agents.list` 名册，包括已设置 `agents.ownership: "explicit"` 的名册。例如，Doctor 会将代理的遗留 `memorySearch` 设置保留在 `memory.search` 下。当前配置路径中已有的值优先。

    对于包含多个代理且没有可解析环境所有者的遗留名册，Doctor 会从唯一标记为 `default: true` 的代理中填充 `agents.defaults.systemAgent.agentId`，如果存在 `main` 则使用 `main`。单代理名册以及运行时已认可的遗留默认标记无需所有者修复，也不会产生缺少所有者的建议。显式舰队所有权会禁用遗留默认标记回退，因此这些名册可能仍需要修复。Doctor 还仅在心跳注册否则无法解析时固定 `agents.defaults.heartbeat.agentId`；现有心跳所有者、共享默认值和按代理注册均会保留。这些更改会由 `doctor --fix` 报告并保存，包括更新时的 Doctor 处理。如果无法识别默认值，请显式配置系统代理所有者。

!!! note

    Doctor 仅在键退役后大约两个月内保留自动迁移。更旧的遗留键（例如原始
    `routing.queue`、`routing.bindings`、`routing.agents`/`defaultAgentId`、
    `routing.transcribeAudio`、顶层 `agent.*`，或多代理配置形态之前的顶层
    `identity`）不再有迁移路径；使用它们的配置现在会验证失败，而不是被重写。
    在 Doctor 能够继续之前，请根据当前
    [配置参考](../configuration-reference.md) 手动修复这些键。

    Doctor 不再修复这些六月之前的键：

    - 代理 `embeddedHarness`、`embeddedPi`、`sandbox.perSession` 和 `agents.defaults.llm`。
    - 顶层 `heartbeat`、`routing.allowFrom` 和 `routing.groupChat`。
    - `channels.telegram.requireMention`、`channels.feishu.accounts.<id>.botName`，
      以及已退役的 `channels.webchat` / `gateway.webchat` 部分。
    - `session.threadBindings.ttlHours` 以及 Discord/LINE/Matrix/Telegram 的 `threadBindings.ttlHours`，
      包括按账户设置。

包含这些键的配置必须在当前校验成功之前修复。Doctor 会保留配置并停止，同时提供恢复指引，而不是删除这些设置或用备份替换它们。对于较旧的安装，请通过 2026.9.5 升级，并在安装最新版本之前运行其 Doctor 迁移。

当前迁移：

Code Mode 的运行时迁移会在全局配置、键控代理条目和旧版代理名册中保留显式的 QuickJS 选择。现有 executor 值优先，激活和限制保持不变。即使通用插件被禁用或加入允许列表，选择捆绑的 QuickJS 运行时也能工作，且无需启用其他插件；针对 code-mode-quickjs 的显式拒绝或禁用条目仍会阻止它。从未选择运行时的配置使用新的 node 默认值。在启用 Node 执行之前，请参阅 Code Mode 执行器；node:vm 不是安全边界。

Doctor 会在一条通知中列出它实际移除的已退役调优路径，包括显式 false 值：Removed retired runtime tuning knobs: diagnostics.memoryPressureSnapshot; built-in defaults now apply. 在启动并使用这些已退役键之前，请运行 openclaw doctor --fix。内存压力事件仍然可用；请使用 诊断导出或手动分配分析 获取当前证据。