OpenClaw �� 你的小龙虾健康吗?用这个tor命令一键诊断.

今天我升级 OpenClaw，从 5.20 升到 5.27。

顺手把openclaw doctor跑了一遍，修复了一下最近一直告警的问题。满心欢喜想试试新功能。结果一启动网关，终端给我甩了句话，

openclaw doctor是啥呢？这玩意是整个 OpenClaw 的体检+修复工具。而且它不是那种「你出了问题才想起来用」的玩意儿，它是你应该定期跑的。

今天就聊聊这个。

我一开始对 doctor 是有偏见的。CLI 工具的「修复命令」嘛，大多数就是跑个脚本把配置重写一遍。但 OpenClaw 的 doctor 不太一样。

怎么说呢，它像一个真正的家庭医生。不只是开药，还告诉你哪里有问题、为什么会有问题、怎么预防下次再出问题。而且它分了好几种就诊模式，不同的场景用不同的模式。

咱们一个一个来。

openclaw doctor

这是最基础的用法。不加任何参数，直接跑，

openclaw doctor

这个是我运行的截图，第一条就是配置警告，意思是“飞书插件已禁用（由配置项关闭），但该插件配置条目依然存在”，这个是前面版本不稳定，我把禁用飞书造成的，这次修改成可用状态。

然后重新运行openclaw doctor命令,飞书插件警告消失。

先检查你能不能更新，如果你是 git 装的，它会问要不要先升个级。

然后开始翻你的配置文件。依次看 Cron、Security、Browser、Skills status、Plugins和Memory search，最后提醒你运行“openclaw doctor –fix”命令自动应用相关修复。

但它不会直接动手改。至少 doctor 模式不会。它只是「告诉你」。

我的安全检查就提示我key明文存储。

下一篇文章专门说说这个问题的修复。

它还会检查会话文件有没有问题。我遇到过一种情况，之前的某个版本 bug 导致会话记录出现了重复分支doctor 检测出来了，告诉我有重复的会话分支需要修复。

跑一遍，能查出来的毛病全列你面前。

但 doctor 模式有个烦人的地方，它是交互式的。每修一个问题它都要问你一句，要不要修这个？要不要重启网关？如果你没在终端前盯着，它就卡在那等你。

所以如果你想放脚本里自动跑，得换别的模式。

openclaw doctor –yes

--yes 的意思是「我同意所有默认操作」。

openclaw doctor --yes

它跟 doctor 的区别就是，遇到需要你确认的地方，它自动选「是」。包括重启网关、修复服务配置、修 sandbox 镜像这些需要人点头的操作，它都默认同意。

适合你已经跑过一次 doctor，知道要修什么了，然后 –yes 一把梭。

但不建议上来就用 –yes。你连问题都没看呢，万一它要改你不想改的东西咋办。

openclaw doctor –fix

这是最常用的修复模式。

openclaw doctor --fix

–fix 和 –yes 的区别是，–yes 是你手动同意每个操作，–fix 是直接动手修，不需要你点头。自动重写配置、迁移旧格式、清会话锁、重启网关，一条龙。

比如说，我的那个旧配置迁移，doctor 只是列出来给我看，但 --fix 直接帮我改好了。改完之后还写了份「做了什么」的日志。

还有会话锁清理。如果你之前 OpenClaw 非正常退出过（断电、强制关机什么的），会话目录里可能会留下 stale 锁文件。--fix 会自动清理掉。

还有一个我觉得挺实用的，Codex 路由修复。如果你以前用过 openai-codex/* 这种旧格式的模型引用，--fix 会自动帮你重写成 openai/*。省得你手动去翻配置文件一条条改。

不过 –fix 也不是什么都敢动。重写 supervisor 配置这种大操作，它还是要你点头的。

openclaw doctor –fix –force

openclaw doctor --fix --force

--force 是 --fix 的激进版。

–fix 只管 OpenClaw 自己的配置，不动系统级别的东西。–force 就不一样了，它连 supervisor 配置都给你重写。你之前手动改过的 systemd 服务文件、Windows 计划任务，统统给你覆盖掉。

所以我建议，这个命令想清楚再用。除非你确定当前的 supervisor 配置确实过时了，不然别手滑。

我的建议是，先跑 doctor 看看问题，再用 –fix 修，实在不行再考虑 –force。

openclaw doctor –lint

这个模式很有意思。

openclaw doctor --lint

--lint 是「只检查，不动手」。它不会改任何东西，不会提示你确认，不会重启网关。就是纯扫描，输出结构化的检查结果。

共运行 19 项检查，发现 6 个问题。

它还有一个 JSON 输出模式，

openclaw doctor --lint --json

输出的 JSON 包含，

• • ok，布尔值，是否有达到阈值的问题
• • checksRun，跑了多少项检查
• • checksSkipped，跳过了多少项
• • findings，具体的问题列表，每条有 checkId、severity、message，还可能有 path、line、column、ocPath、fixHint

这对自动化工具来说太友好了。直接接进监控系统完事。

还有一些子选项可以配合 --lint 使用，

# 只看 warning 级别以上的问题openclaw doctor --lint --severity-min warning# 只看某一项检查openclaw doctor --lint --only core/doctor/gateway-config# 跳过某一项检查openclaw doctor --lint --skip core/doctor/bootstrap-size

这些子选项只能跟 –lint 一起用，普通 doctor 和 –fix 模式下是不能用的。我一开始没注意，在 doctor 模式下加了 –json，结果给我报了个参数不合法。踩坑了。

openclaw doctor –non-interactive

openclaw doctor --non-interactive

这个模式是给无人值守场景用的。

跟 –yes 有点像，都是自动操作。但 –non-interactive 更怂一些，它只做安全的迁移，比如配置格式标准化、磁盘状态迁移这些肯定不会搞砸的事。

重启网关、修复服务配置、sandbox 镜像修复这种需要人点头的，它直接跳过。

旧版 cron 任务格式的迁移也会自动跑。

所以如果你在脚本里跑 doctor，又不想承担 –fix 那种改坏了我负责的风险，–non-interactive 比较稳。

openclaw doctor –deep

openclaw doctor --deep

这个模式是深度扫描。

它会翻你的系统服务，看有没有多余的网关装在那。比如你之前装过一次 OpenClaw，后来又装了一次，两个网关服务都注册到系统里了。它 会找出这些多余的，给你清理建议。

我的感觉是，–deep 适合两种人，一种是系统洁癖患者，想看看机器上有没有历史遗留垃圾；另一种是遇到怪问题了，普通 doctor 找不到原因，上 –deep 碰碰运气。

再聊几个实用子命令

除了上面的模式，doctor 还有一些零散但很实用的功能。

–generate-gateway-token

openclaw doctor --generate-gateway-token

如果你开了网关的 token 认证但没有 token，这个命令会帮你生成一个。但它不会覆盖已经配置好的 SecretRef 配置。所以如果你已经用 SecretRef 管理 token 了，它不会乱动。

–json

这个前面提到了，配合 --lint 使用，输出结构化 JSON。适合脚本解析。

–severity-min

控制检查的严重程度门槛，

openclaw doctor --lint --severity-min warning

可选值，info、warning、error。默认是 info（所有问题都显示）。

如果你只想看严重问题，设成 error。如果不想被 info 级别的提示刷屏，设成 warning 比较合适。

一个真实的升级场景

来串一个完整的场景，把上面的命令串起来。

假设你要从 OpenClaw 5.20 升级到 5.26。

第一步，升级完启动网关，报错说配置旧了。你跑，

openclaw doctor

它列出一堆需要迁移的旧配置项。你看了一遍，觉得没问题。

第二步，跑修复，

openclaw doctor --fix

它自动迁移了配置、清理了会话锁文件。你重启网关，成功启动了。

第三步，你想确认一下网关的健康状态和技能状态，

openclaw doctor --lint

输出显示一切正常。

第四步，你想深度检查一下系统里有没有残留的旧服务，

openclaw doctor --deep

发现之前的一个旧网关服务还在，提示你清理。你手动清理掉。

第五步，如果你想把这些检查写进自动化脚本，以后每次更新都自动跑一遍，

openclaw doctor --non-interactive

或者更严格一点，用 --lint 做门禁，

openclaw doctor --lint --severity-min warning --json

如果返回非零，就触发告警。

说到这，我觉得 doctor 这个设计思路挺有意思的。

很多 CLI 工具都有修复功能，但大多数是你出了事才想起来用。

OpenClaw 的 doctor 不太一样，它把体检、报告、修复、预防串成了一整条线。

就像个家庭医生。平时定期体检，发现问题就治疗，遇到疑难杂症就深度检查，出差不在家也能自动保养。

我第一次看到 doctor 的时候，说实话没太当回事。觉得就是个配置迁移工具嘛。但用了一段时间才发现，它真正值钱的地方不是能修配置，而是能让你知道你机器上到底发生了什么。

对于一个长期跑的服务来说，这种能看见底层在发生什么的能力，比修复本身更重要。

以上，如果觉得不错，随手点个赞、在看、转发三连吧～谢谢你看我的文章，我们，下次再见。

文章内容基于OpenClaw版本2026.5.27。