运维与升级：日志、健康检查、备份与回滚

“能跑一次”不难，“天天都能跑”才是真本事。
这章给你一套小白也能照做的运维流程：看状态、做体检、留备份、出事能回滚。

本章你将学会什么

建立统一观测入口（status / logs / doctor / health）。
做一次完整的健康自检并读懂结果。
用冻结点策略安全升级，不做“盲升”。
规划 workspace 与 state 的备份与回滚。
快速判断“坏的是模型、配置还是渠道”。

读者前置

你已完成前 6 章基础配置。
你可以正常运行：

openclaw gateway status

openclaw logs --follow

7.1 观测入口（日志/指标/事件）

7.1.1 运维第一原则：先看事实，再下结论

系统不对劲？别急着改配置！先跑这五条命令，把“现场情况”摸清楚。

这就跟看病一样，医生也得先问诊再开药，不能上来就输液。

# 基础状态，看核心组件在不在跑
openclaw status

# 全部状态，包括插件、模型、渠道的详细信息
openclaw status --all

# 网关状态，API 请求都经过它
openclaw gateway status

# 探测所有渠道，看哪些能连上、哪些歇菜了
openclaw channels status --probe

# 实时日志，滚动显示最新日志条目
openclaw logs --follow

7.1.2 日志有两层，别搞混了

OpenClaw 的日志分两层：

层级	怎么看到	用途
控制台日志	你执行命令的终端窗口	实时debug用
文件日志	磁盘上的JSON文件	事后查问题、跑分析用

特别注意：--verbose 这个参数只影响控制台输出，不会让文件日志变得更详细。
如果你需要更细粒度的文件日志，得去改配置文件里的 logging.level。

7.1.3 建议的巡检频率

别等到出事了才想起来看日志。养成定期巡检的习惯：

每天：跑一遍 status + gateway status，花不了一分钟
每周：跑 doctor 深度检查 + 安全检查
每次改完配置：logs --follow 至少盯 10 分钟，确认没有持续报错再走人

7.2 健康检查与自测

7.2.1 快速健康检查

想知道系统“体温”正不正常？跑这个：

openclaw health --json

这会返回一个 JSON，里面包含 Gateway 的健康状态。适合：

写自动化脚本监控
CI/CD 流水线里做探活检测
接入监控系统（比如 Prometheus）

你可以把它理解成“系统体温计”——38度以上就说明有点问题了。

7.2.2 “第一分钟”排查序列

觉得系统有问题？按这个顺序来，别跳步：

# 第1步：看整体状态
openclaw status

# 第2步：专门探测网关
openclaw gateway probe

# 第3步：让系统自己给自己做体检
openclaw doctor

# 第4步：检查所有渠道
openclaw channels status --probe

# 第5步：看实时日志
openclaw logs --follow

为什么要按顺序？

这顺序是官方设计好的“排查阶梯”：

先看整体能不能跑
再看网关通不通
再让 doctor 全面检查
最后看具体渠道和日志

跳步容易误判，比如你以为是渠道问题，结果是网关挂了。

7.2.3 体检报告要看这些指标

跑完 doctor 和 status，重点关注这几个信号：

信号	正常应该显示	异常意味着什么
Gateway Runtime	`running`	没在跑？启动命令再试试
RPC probe	`ok`	不 ok？网关API可能有问题
channel 状态	`connected` 或 `ready`	某渠道断了，看日志查原因
日志	无持续 fatal 错误	有 fatal？赶紧查，别犹豫

7.3 升级策略（冻结点/变更记录）

7.3.1 什么是“冻结点”？

你可以把 OpenClaw 的版本想象成一条河流——它一直在流，每天都有新commit。

“冻结点”就是官方标记为“稳定可用”的版本。本书用的是 v2026.2.17，这就是一个冻结点。

升级原则：只升级到冻结点，别追每天的最新版。
就像开车别追最新那班过山车，等它验证稳定了再上。

7.3.2 升级前清单（必做！）

别嫌麻烦，按这个清单来：

备份配置文件：openclaw.json 复制一份
备份工作区：workspace 里的文档、技能、项目文件
记录当前版本信息：当前版本、用了哪些插件、模型怎么路由的
跑一遍深度体检：

openclaw doctor --deep

如果体检有问题，先修好再升级，别带着病升级。

7.3.3 升级后验收（别只看启动！）

很多人升级完只验证“能启动”就跑了，结果后面功能闭环出问题。

至少验证这三件事：

对话能跑：发一条消息，确认能收到回复
渠道能收发：从外部发条消息，确认能进来也能出去
技能能用：跑一个你定义的技能，确认能执行成功

只验证启动不验证闭环，后面大概率会补坑。

7.4 备份与回滚预案

7.4.1 备份什么、不备份什么

要备份	不要备份（或脱敏后备份）
workspace（你的文档、技能、项目）	明文密码/API Key
openclaw.json（配置文件）	未脱敏的完整日志
关键会话数据（按隐私策略处理）	临时缓存文件

7.4.2 回滚要有“后悔药”

建议保留最近三份备份：

T-1：昨天那版（万一一小时前改坏了）
T-7：一周前（上周稳定版）
T-30：一个月前（月初快照）

出大事了怎么办？先回滚到最近一个验证可用的版本，先把服务恢复再说。
别在现场临时修，现场修通常越修越乱。

7.4.3 workspace 用 Git 管理

workspace 就是你的“记忆资产”，建议用私有 Git 仓库管理。

# 初始化仓库
cd your-workspace
git init
git remote add origin your-private-repo

# 添加 .gitignore，防止提交敏感文件
echo "*.log" >> .gitignore
echo "credentials.json" >> .gitignore
echo ".cache/" >> .gitignore

git add .
git commit -m "backup: workspace snapshot"
git push origin main

7.5 “坏的是模型还是配置”

有时候系统报错，你根本不知道是模型抽风还是自己配置写错了。教你三步定位。

7.5.1 三步定位法

第一步：看系统层（基础健壮吗？）

openclaw gateway status
openclaw doctor
openclaw health --json

如果这步就挂了，说明不是模型问题，是整个系统有问题。

第二步：看模型层（模型能调用吗？）

openclaw models list

检查：

模型在列表里吗？
鉴权（auth）通过了吗？
有没有触发 fallback（备胎模型）？

第三步：看渠道层（消息能进出吗？）

openclaw channels status --probe

检查：

渠道配对（pairing）成功了吗？
allowlist（白名单）有没有漏？

7.5.2 常见误判（坑别踩）

别把这种情况	当成这种情况
渠道权限没配好	模型太笨
配置文件悄悄漂移了	版本 bug
请求太多队列积压了	系统卡死

7.5.3 一张最短决策表

收藏这个表，出事先查它：

现象	最可能的原因	第一步该做什么
所有请求都失败	Gateway 挂了 / 配置错了	跑 `openclaw doctor`
单独某个模型不行	模型鉴权失败 / 路由写错	跑 `openclaw models list` + 查日志
单独某个渠道不通	渠道权限问题 / 没配对	跑 `openclaw channels status --probe`
偶尔超时	负载太高 / 网络抖动 / 重试没配	看 `logs --follow` + 检查重试策略

本章小结

观测面要统一：大家用同一套命令，别每人一套排障方法
健康检查要跑在前面：doctor 和 health 不是出事才跑，是每天该跑的例行体检
升级不能裸奔：冻结点 + 回滚点，缺一不可
先定位再动手：分层排查效率最高，别一上来就改配置