中/EN
实战 SOP
实战 SOP

升级前先把状态目录备份了：OpenClaw 2.0 迁移、回滚与凭证加固实操 SOP

写给已在跑 OpenClaw 的工程师：怎么安全升 2.0、升不上去怎么退、升完怎么收紧凭证。第一原则——升级前整体备份 Gateway 的 configuration 与 state（不是单个客户端），并验证可恢复。四步升级：检查→openclaw doctor --fix→重启 Gateway→验证健康（模型访问验证通过才算生效）。两个 breaking change：OpenProse 插件与 /prose 命令移除（.prose 源文件保留）、codex/* 与 openai-codex/* 路由迁 openai/*（冲突手动修）。2026-09-01 插件 SDK 弃用（plugin-sdk-config-runtime-subpath → api.pluginConfig）死线就在今天。降级有界：SQLite 之后新建会话旧版读不到，整体回滚还会带回 approvals 与 dedup 记录。升后主动配五件事：开掩码凭证请求、配 proxy 白名单、精确授权、角色收敛、纠正 Incognito 误用。

发布于 2026年9月1日14 分钟阅读
<!-- openclaw-2-0-upgrade-migration-sop | sop | 升级前先把状态目录备份了：OpenClaw 2.0 迁移、回滚与凭证加固实操 SOP -->

OpenClaw 上一个稳定版停更了近 7 周。把它放回这个项目自己的节奏里看，这是个反常信号：此前 230 天里它发了 106 个版本，平均两天多一个。2026 年 8 月 31 日 03:30:51（UTC），答案落地：版本 tag v2026.8.1，release 名 "OpenClaw 2026.8.1"，Mac / Linux / Windows 三端同发。这个版本有 933 位贡献者参与，合并了 16,000 多个 PR，约占项目历史累计合并 PR 的 50%。

这一篇不是复述"2.0 发布了什么"——那部分我们单独写了一篇 OpenClaw 2.0 发布热点。这一篇写给已经在跑 OpenClaw 的工程师：现有部署怎么安全升上去、升不上去怎么退、升完之后怎么把凭证收紧。全文只回答一个问题的可操作版本：你今天下午坐在机器前，具体该按什么顺序做什么。

先说清边界：本文的操作依据来自官方 release notes 与官方博客，涉及具体路径、参数、插件内部接口的地方，以官方 release notes 与 openclaw doctor 的实际输出为准。

一、为什么这次不能无脑点更新

三个理由，每一个都足以让"点一下自动更新然后去接咖啡"变成一次事故。

第一，有两个 breaking change。 一个是 OpenProse migration：内置的 OpenProse 插件和 /prose 命令被移除，你需要跑 openclaw doctor --fix 清理陈旧配置，再按上游的 Agent Skill 迁移路径重接。另一个是 OpenAI route migration：codex/* 和 openai-codex/* 的模型引用、provider config、已存储的会话、automation routes，全部要迁到 openai/*，而且冲突不会自动替你决定。

第二，会话存储格式变了，且降级是有界的。 升级会把文件支持的会话记录与 transcript 校验、归档、迁进 SQLite；代价是旧版本读不到迁到 SQLite 之后新建的会话。详见第九节。

第三，也是最容易被忽略的一条——官方自己就预期自动更新会失败。 release notes 里给出的更新建议原文是这样的：

"If the automatic update fails, use a local coding harness to help complete the update, diagnose any migration errors, and verify that the Gateway starts correctly. Back up your configuration and state before making changes."

翻成中文：如果自动更新失败，用一个本地 coding harness 帮忙完成更新、诊断迁移错误、确认 Gateway 能正常启动；动手之前，先备份 configuration 和 state。这句话由发布方自己写出来，本身就是信号，也是本文的第一原则。

二、升级前：备份 configuration 与 state，这是第一原则

备份之前先搞清备份对象。这一步很多人会做错，因为他们把 OpenClaw 理解成"我电脑上跑的一个客户端"。

正确的心智模型是：Gateway 是那个持有普通会话状态、模型凭据、权限与持久工作的服务；browser、命令行、连接的设备、remote workers，都只是操作这个 Gateway 的不同入口。

由此得出一个直接结论：你要备份的是 Gateway 的 configuration 和 state，不是某一个客户端。 只把某个客户端的配置导出一份，等于什么都没做。

具体动作：

1. 备份整个状态目录，不要只备份配置文件。 用操作系统级的整体复制，保留时间戳与权限：

bash
# macOS / Linux：整体归档，保留权限与时间戳
# <state-dir> 的实际路径以 openclaw doctor 的输出或官方文档为准
cp -a "<state-dir>" "<state-dir>.bak.$(date +%Y%m%d-%H%M%S)"

# Windows（PowerShell）：镜像复制
# robocopy "<state-dir>" "<state-dir>.bak.20260831" /MIR /COPYALL

2. 备份完必须验证可恢复。 一份没验证过的备份等于没有备份。至少做一次"复制回来能启动"的验证，或者直接检查归档里的文件数量与体积是否和源目录对得上。

3. 记录当前版本号与已装插件清单。 回滚时你需要知道自己从哪儿来的，尤其是外部插件——因为第六节要讲的那条弃用死线就压在插件身上。

4. 盘点两个 breaking change 的命中面。 在现有仓库、配置、脚本里检索 /prose 的调用位置，以及 codex/*、openai-codex/* 的模型引用位置：

bash
# 盘点 codex 路由引用（在被管理的项目与配置目录下执行）
grep -rn "codex/\*\|openai-codex/\*\|codex/" --include="*.json" --include="*.toml" --include="*.yaml" --include="*.yml" --include="*.ts" --include="*.js" .

# 盘点 /prose 用法
grep -rn "/prose" .

这份清单是第四、第五节的施工单，也是第九节回滚时的对照表。

三、执行升级四步：检查、修复、重启、验证

官方给出的更新路径是四步，顺序不能乱：

  1. 检查安装（checks the installation）
  2. 跑配置与迁移工具，也就是 openclaw doctor --fix
  3. 重启 Gateway
  4. 验证服务健康（verify that the service is healthy）
bash
# 第 2 步：跑配置与迁移工具
openclaw doctor --fix

这里有一个必须写进操作手册的补充事实：现有安装不会自动变成 2.0。 你必须在本地完成更新，走完 checks，重启，并且模型访问验证通过，2.0 才算真正生效。也就是说，版本号变了不等于迁移完成了——很多人就是在这里以为自己已经升好了，然后在第二天发现某个自动化跑不通。

关于自动更新失败的处理，照抄官方建议：用本地 coding harness 参与诊断与修复，确认 Gateway 能正常启动，别自己硬猜参数。

四、处理 OpenProse migration：插件和 /prose 命令没了，但文件还在

这是第一个 breaking change（对应 issue #128494，Thanks @obviyus, @vincentkoc）。它的实际影响分三层，要分开处理：

第一层：内置的 OpenProse 插件与 /prose 命令已被移除。 升级之后，任何依赖 /prose 的调用都会失效。你需要在升级前就完成第二节点出来的那份盘点，把命中位置列成清单。

第二层：陈旧配置需要清理。 跑 openclaw doctor --fix，清掉指向已移除插件的陈旧配置项。残留配置是后续启动里常见的报错来源。

第三层：迁移到 Agent Skill。 上游给出的路径是遵循 Agent Skill 迁移，文档在 https://docs.openclaw.ai/prose ，具体方式以该文档为准，不要凭印象照搬旧写法。

最重要的一句也在这里：你现有的 .prose 源文件是保留的。 所以正确的心态不是"资产没了"，而是"资产要换个入口接回去"。备份在第二节已做，这里可以放心施工。

五、处理 OpenAI route migration：四类对象逐个查，冲突手动修

这是第二个 breaking change（Thanks @vincentkoc），也是本次升级里最容易漏的一块，因为它的命中面分散在四个不同的地方。

用 openclaw doctor --fix 迁移以下内容，统一迁到 openai/*：

  • 模型引用：codex/* 和 openai-codex/* 的引用
  • provider config
  • 已存储的会话（stored sessions）
  • automation routes（自动化路由）

操作时注意三点：

1. 四类对象都要查，不能只查配置。 大部分人只改配置文件里的模型名，漏掉已存储会话和自动化路由里残留的旧 ref。这两处漏了，症状会延迟到几天后才暴露——比如某个自动化在某天凌晨静默失败。

2. 迁移会保留 Codex runtime intent。 也就是说，这次改动是路由与命名的统一，不是语义的改写。你原本想要的那个运行时意图不会被抹掉。

3. 冲突需要操作员手动修复。 这一条请当成硬约束记住：openclaw doctor --fix 不会替你决定冲突该怎么解。遇到冲突，它会停下来交给你。这时候不要猜，按官方建议让本地 coding harness 参与诊断，或者回到第二节点盘出来的清单逐条比对。自动化工具的沉默区域，就是人工必须站岗的位置。

六、处理 2026-09-01 插件 SDK 弃用：死线就在今天

时效性最强的一条，压在写外部插件的人身上。

外部插件需要在 SDK removal gate 之前完成迁移：

  • plugin-sdk-config-runtime-subpath → api.pluginConfig

这条的生效日期是 2026-09-01，也就是今天。如果你维护或依赖外部插件，这是本批操作里唯一一条"不做就一定出事、且没有宽限期"的项目。

需要说明的是，release notes 里这个条目是截断的，我们没有更完整的上下文；拿到完整表述请以官方 release notes 与 openclaw doctor 的输出为准。可以用下面的方式拉 GitHub release 正文全文自行核对，重点搜索 "Upcoming deprecations"：

bash
curl -s "https://api.github.com/repos/openclaw/openclaw/releases/latest"

如果你同时也在别的开源 agent 项目上维护插件，建议横向对照一下各自的接口稳定性节奏，本站 OpenHuman 开源项目档案 是另一个可对照的样本。

七、升级后验证清单：四件事，缺一不可

重启 Gateway 之后，不要看到进程起来了就收工。按顺序验这四项：

  1. Gateway 健康：服务健康、能正常响应。官方第四步要求的就是 verify that the service is healthy。
  2. 会话迁移完整性：历史会话与 transcript 是否完整迁进 SQLite，抽查几条老会话能否正常打开。
  3. 自动化路由是否还指向旧 ref：这是第五节点出的高频漏点，逐条过一遍 automation routes。
  4. 定时任务是否照常触发：不要只看配置，等一个真实触发周期，或者手动触发一次验证。

外加一项：模型访问验证通过。它是"这次升级算不算生效"的最终判定条件，不是可选项。

八、凭证加固：升完之后要主动配的五件事

2.0 带来了一组凭证治理能力，但它们不会因为你升级了就自动生效——大部分需要你主动开启或配置，这里只给操作步骤。

1. 开 Private credential requests。 agent 通过掩码提示请求凭证，凭证值不进 chat、不进模型上下文（对应 #129670、#123216、#132122）。这一条应该默认开启：它的价值是把"密钥出现在对话里"从可能变成不可能。

2. 配置 opt-in proxy 的目标白名单。 开启后，protected-secret substitution 会被限制在你批准的目标地址内——也就是密钥只会被替换进你批准的域名或地址。这直接堵死了一类真实攻击面：agent 把密钥带到别的站点去。

3. 给自动化做精确授权（Approve recurring work once）。 给自动化授予的是精确操作的权限，不是笼统的一次性放行；授予之后你随时可以 inspect 或 revoke。关键机制是：一旦 job 或 operation 发生变化，会要求重新批准（#129526、#131602）。请把这条当成自动化的默认姿势，而不是"先全放开以后再说"。

4. 用角色收敛访问范围。 Gateway 用角色来收窄访问范围（roles narrow access）。按人、按用途分角色，不要所有人共用一个全权身份。

5. 纠正对 Incognito 的误解。 这一条单独强调，因为它是最常见的误用：Incognito 模式只是把 transcript 保留在内存里直到重启，它不会停掉 provider 或 tools。它不是隐私开关。 开着 Incognito 让 agent 去调外部服务，请求照样出去，provider 照样看到。如果你要的是"不外发"，那需要的是网络层与权限层的控制，不是一个叫 Incognito 的开关。

另外补一条架构红利：共享云会话下 Gateway 代理模型请求，provider 凭据留在 Gateway 侧；remote worker 消失后还能从持久 Gateway 状态再启一个。

九、回滚预案：降级可行，但它是有界的

这一节是全篇最该读完的部分。

升级会把文件支持的会话记录与 transcript 校验、归档、迁进 SQLite。而降级路径是有界的，边界有两条，务必分清：

边界一：会话可见性。 旧的文件支持版本能恢复迁移之前就存在的归档记录，但看不到迁到 SQLite 之后新建的会话。翻译成人话：你升到 2.0，用了三天，觉得不对想退回旧版——这三天里新开的会话，旧版本读不到。它们未必丢失，但你手上的旧版本拿它们没办法。

边界二：整体状态目录回滚的影响更大。 如果你采取"把整个状态目录换回旧副本"这种粗暴做法，影响面不止会话：approvals 与 delivery/dedup 记录也会跟着回退，部分 ratcheting channel 凭据可能需要重新关联。这意味着回滚会把你授予过的权限、已经投递过的消息去重状态一并带走——在自动化场景里，dedup 记录回退是能造成真实损失的，重复投递不是理论风险。

所以结论必须写清，一个字都不能含糊：能回到旧软件，但不能假设更新的会话或状态变更会自动跟随。备份不是可选项，它是你唯一的退路。

回滚前的强制动作：确认备份可恢复、已导出 2.0 状态下新产生的关键会话内容、已知晓 approvals 与 dedup 记录会回退。

十、可复制检查清单

升级前：

  • 已完整备份 Gateway 的 configuration 与 state（不是单个客户端配置）
  • 备份已验证可恢复
  • 已记录当前版本号与已装插件清单
  • 已盘点 /prose 调用位置
  • 已盘点 codex/*、openai-codex/* 模型引用位置
  • 已确认外部插件是否需要应对 2026-09-01 的 SDK 弃用

升级中：

  • 自动更新失败时，已按官方建议用本地 coding harness 参与诊断
  • openclaw doctor --fix 已执行且无未处理冲突
  • Gateway 已重启
  • 模型访问验证已通过

升级后：

  • Gateway 服务健康
  • 历史会话与 transcript 迁移完整
  • .prose 源文件仍在，调用方式已按 Agent Skill 迁移路径重接
  • 模型引用 / provider config / 已存储会话 / automation routes 四类对象均无旧 ref 残留
  • 定时任务已实际触发验证过一次
  • 掩码凭证请求已开启
  • proxy 目标白名单已配置
  • 自动化已改为精确授权，并确认变更会触发重新批准
  • 角色已收敛
  • 团队已知晓 Incognito 不是隐私开关

十一、七个踩坑点

  1. 只备份配置文件，不备份状态目录。 会话、权限、dedup 记录都在 state 里，配置丢了能重写，state 丢了就真没了。
  2. 以为版本号变了就是升完了。 必须走完"本地更新 → checks → 重启 → 模型访问验证通过"四步。
  3. 把 Incognito 当隐私开关。 它只让 transcript 留在内存直到重启，不停 provider、不停 tools。
  4. 只改配置文件里的模型名，漏掉已存储会话和 automation routes。 症状会延迟到几天后的凌晨才暴露。
  5. 指望 openclaw doctor --fix 自动解决所有冲突。 不会。冲突是留给操作员的，工具不替你做决定。
  6. 以为 .prose 文件被删了，于是手忙脚乱去找备份。 文件保留，变的是调用方式，走 Agent Skill 迁移即可。
  7. 以为回滚是无损的。 降级有界：SQLite 之后的新会话旧版读不到；整体回滚还会把 approvals、delivery/dedup 记录一起带回去，部分 ratcheting channel 凭据要重连。

常见问题

Q1：自动更新失败了，第一步该做什么？ A1：先确认备份在不在——官方的原话就是改动前先备份 configuration 和 state。然后按官方建议，用本地 coding harness 帮忙完成更新、诊断迁移错误、验证 Gateway 能正常启动。不要自己硬猜参数，具体报错以 openclaw doctor 的输出为准。

Q2：升级后 /prose 命令没了，我写的那些 .prose 文件还在吗？ A2：在。这次 breaking change 移除的是内置的 OpenProse 插件与 /prose 命令，你现有的 .prose 源文件是保留的。你需要做的是跑 openclaw doctor --fix 清理陈旧配置，然后按上游的 Agent Skill 迁移路径把调用方式接回去，文档见 https://docs.openclaw.ai/prose 。

Q3：openclaw doctor --fix 报冲突，它能自己解决吗？ A3：不能。冲突需要操作员手动修复，工具不会替你决定。正确做法是用本地 coding harness 参与诊断，或者对照升级前盘出来的 codex/*、openai-codex/* 引用清单逐条比对。迁移本身会保留 Codex runtime intent，所以冲突通常不是语义问题，而是"该用哪个目标 ref"的判定问题。

Q4：我回滚到旧版本，升级之后新建的会话还在吗？ A4：旧版本看不到它们。降级是有界的：旧的文件支持版本能恢复迁移之前就存在的归档记录，但看不到迁到 SQLite 之后新建的会话。如果整体回滚状态目录，影响更大——approvals 与 delivery/dedup 记录也会回退，部分 ratcheting channel 凭据可能需要重新关联。回滚前请把新产生的关键内容另行导出。

Q5：开了 Incognito，是不是 provider 就看不到了？ A5：不是。Incognito 模式把 transcript 保留在内存中直到重启，但它不会停掉 provider 或 tools。它不是一个隐私开关。如果你需要的是"请求不外发"，要靠网络层与权限层的控制来实现，而不是靠这个模式。

参考来源

本文由 AI 辅助生成，经人工审核编辑。最后更新：2026-09-01

常见问题

自动更新失败了，第一步该做什么？
先确认备份在不在——官方的原话就是改动前先备份 configuration 和 state。然后按官方建议，用本地 coding harness 帮忙完成更新、诊断迁移错误、验证 Gateway 能正常启动。不要自己硬猜参数，具体报错以 `openclaw doctor` 的输出为准。
升级后 `/prose` 命令没了，我写的那些 `.prose` 文件还在吗？
在。这次 breaking change 移除的是内置的 OpenProse 插件与 `/prose` 命令，你现有的 `.prose` 源文件是保留的。你需要做的是跑 `openclaw doctor --fix` 清理陈旧配置，然后按上游的 Agent Skill 迁移路径把调用方式接回去，文档见 https://docs.openclaw.ai/prose 。
`openclaw doctor --fix` 报冲突，它能自己解决吗？
不能。冲突需要操作员手动修复，工具不会替你决定。正确做法是用本地 coding harness 参与诊断，或者对照升级前盘出来的 `codex/*`、`openai-codex/*` 引用清单逐条比对。迁移本身会保留 Codex runtime intent，所以冲突通常不是语义问题，而是"该用哪个目标 ref"的判定问题。
我回滚到旧版本，升级之后新建的会话还在吗？
旧版本看不到它们。降级是有界的：旧的文件支持版本能恢复迁移之前就存在的归档记录，但看不到迁到 SQLite 之后新建的会话。如果整体回滚状态目录，影响更大——approvals 与 delivery/dedup 记录也会回退，部分 ratcheting channel 凭据可能需要重新关联。回滚前请把新产生的关键内容另行导出。
开了 Incognito，是不是 provider 就看不到了？
不是。Incognito 模式把 transcript 保留在内存中直到重启，但它不会停掉 provider 或 tools。它不是一个隐私开关。如果你需要的是"请求不外发"，要靠网络层与权限层的控制来实现，而不是靠这个模式。

相关文章

实战 SOP

LLaDA-Image 本地部署 SOP：五步跑通 6B 生图模型

把蚂蚁开源 6B 生图模型 LLaDA-Image 跑起来的五步 SOP：①环境准备（依赖与国内镜像加速下载）；②四档权重怎么选（Base 50 步 / Turbo 4 步 × BF16 / FP8，国内走 ModelScope）；③跑通第一张图（Base 与 Turbo 最小可用命令）；④进阶（参考图编辑、文字渲染、ComfyUI 接入、显存不足时的降级策略）；⑤生产化（批量队列、并发容量规划、成本监控、结果入库与故障降级）。含 6 条踩坑与 10 项上线自检清单，命令逐字取自官方 README；仓库 license 为 null，商用前须确权。

2026年9月9日11 分钟阅读
实战 SOP

自建 OpenMAIC 课堂 SOP：从取码到接 Agent 工作台

从零把 OpenMAIC 跑起来的完整 SOP：①零部署路线（open.maic.chat 取访问码即用）；②本地标准部署（pnpm >= 10，clone → pnpm install → .env → pnpm dev）；③生产化（pnpm build && pnpm start、Vercel 一键、docker compose up --build）；④进阶（Postgres 持久化 profile、ACCESS_CODE 访问码、MP4 导出 profile、Lemonade/FunASR 本地化）；⑤接进 agent 工作台（clawhub install openmaic 或导入 skills/openmaic/，从飞书/Slack 发消息生成课堂）。含 6 条踩坑与 10 项上线自检清单，全部命令逐字取自官方 README。

2026年9月8日11 分钟阅读
实战 SOP

Kimi 双协议接入：一套配置打通 Codex 与 Claude Code

月之暗面 2026-09-02 宣布 Kimi API 原生双协议：OpenAI Responses（`api.moonshot.cn/v1`）+ Anthropic Messages（`api.moonshot.cn/anthropic`），主推模型 kimi-k3。实战 SOP：改 Claude Code 的 `~/.claude/settings.json` 把 ANTHROPIC_BASE_URL 指向 /anthropic、模型设 kimi-k3[1m]；改 Codex 的 `~/.codex/config.toml` 设 wire_api="responses"。即可把 Kimi 当统一模型路由网关，切底层模型不改客户端代码。边界：Responses 仅文本+图片、K2.7 Code 强制思考、旧 ANTHROPIC_API_KEY 须删。

2026年9月5日11 分钟阅读