第 16 章 运维日常升级、排障、模型 FailoverOpenClaw 跑起来之后你会遇到各种日常问题通道断了、模型 API 超额了、某个 Skill 行为异常……本章是一本运维手册按场景整理了常用的排查思路和操作命令。16.1 日常健康检查16.1.1 快速确认 Gateway 是否正常# 检查进程是否在运行openclaw gateway status# 或psaux|grepopenclaw# 检查 HTTP 健康端点如果不在本机替换 IPcurlhttp://localhost:18789/health# 正常返回{status:ok,uptime:123456}# 全面自检openclaw doctor16.1.2 定期关注的几个指标建议养成每周看一次的习惯# Token 消耗统计按 Session / Agent 聚合openclaw stats tokens--period7d# Skill 调用次数和错误率openclaw stats skills--period7d# 通道连接状态openclaw channel list# 最近 Cron Job 的执行记录openclawcronhistory--limit2016.2 升级 OpenClaw16.2.1 版本更新# 检查当前版本和是否有新版本openclaw version# 升级到最新稳定版openclaw update# 升级到特定版本openclaw update--version2026.3.1升级后建议先运行openclaw doctor确认一切正常然后检查CHANGELOG.md或官方发布说明看看有没有破坏性变更。如果升级了 Node.js 大版本注意检查兼容性问题。16.2.2 Skills 的升级# 列出所有 Managed Skills 及其版本openclaw skill list --show-updates# 升级特定 Skillopenclaw skill update gmail# 升级所有 Managed Skillsopenclaw skill update--allSkill 升级通常不需要重启 Gateway热加载。如果升级涉及 API 变更建议先在测试消息里验证一下。16.2.3 配置迁移如果新版本涉及配置 schema 变更例如字段重命名可以运行迁移工具openclaw config migrate# 自动把旧格式配置转换为新格式原文件备份为 openclaw.json.bak16.3 常见问题排查16.3.1 通道断线Slack/Discord/iMessage 无法收发消息典型现象是发消息没有反应openclaw channel list里显示某通道disconnected。排查步骤如下# 1. 查看通道状态openclaw channel list# 输出示例# ✓ slack: connected (mybot)# ✗ discord: disconnected (last error: token expired)# ✓ imessage: connected# 2. 查看通道的详细错误日志openclaw logs--channeldiscord--tail50# 3. 重新授权针对 OAuth 过期openclaw channel discord auth# 4. 强制重连针对网络抖动导致的断线openclaw channel restart discord# 5. 如果还不行检查对应平台的 Bot/App 设置# Slack: 检查 App 的 OAuth Token 是否被撤销# Discord: 检查 Bot 是否被踢出服务器Slack 有个特有问题值得一提Socket Mode 连接中断时先检查 App Token 是否还有效。如果你切换了 Slack 工作区或被管理员撤权需要重新授权。对于 HTTP 模式的用户还需要去https://api.slack.com/apps你的 App 下确认 Event Subscriptions 的 Request URL 是否返回 200。16.3.2 模型调用失败API 报错或超时典型现象是向 OpenClaw 发消息后长时间无回复或者回复一句「抱歉我遇到了一个错误」。# 1. 查看最近的模型调用日志openclaw logs--filteragent--tail30# 2. 常见错误码# 429: Rate limit exceeded请求过快触发速率限制# 401: Invalid API keyAPI Key 无效或过期# 529: Model overloaded模型服务器过载临时性问题# 408/504: Timeout网络超时或模型响应慢# 3. 手动测试模型 API 是否可用openclaw modeltestanthropic# 输出✓ Anthropic (claude-opus-4-6): response in 1.2s16.3.3 Skill 调用异常典型现象是某个 Skill 的操作没生效或模型说「调用工具时出错」。# 1. 查看 Skill 相关日志openclaw logs--skillgmail--tail30# 2. 手动测试 Skill 依赖的 CLI 工具是否可用openclaw skill status gmail# 输出示例# ✓ gmail: requires himalaya (found), requires GMAIL_AUTH env (set)# ✗ gmail: requires himalaya (not found)# 3. 检查底层 CLI 工具的授权状态# Skills 本身是 Markdown 说明文件SKILL.md不持有 OAuth Token# 它们依赖的 CLI 工具需要各自独立授权例如himalaya account list# 检查 himalaya 邮件客户端的账号状态gh auth status# 检查 GitHub CLI 的登录状态# 4. 查看审计日志中该 Skill 的调用历史openclaw audit list--skillgmail--limit1016.3.4 Cron Job 没有触发# 查看 Cron Job 配置和状态openclawcronlist# 查看 Cron 调度历史最近 10 次触发记录openclawcronhistorymorning-briefing--limit10# 手动触发一次验证任务本身是否正常openclawcrontrigger morning-briefing# 如果手动触发正常但自动不触发检查系统时区datetimedatectl status# Linux有一个常见坑Cron 表达式按 Gateway 所在机器的本地时区解析。如果你的 Mac 在 UTC8但设备时区配置有误Cron 时间会偏移。16.4 模型 Failover主模型不可用时的降级策略16.4.1 为什么需要 FailoverAI 模型 API 服务并不总是 100% 可用。Anthropic 或 OpenAI 偶尔会有服务中断你的 API 配额可能用尽网络也可能不通例如你的网络环境无法访问某些域名。Failover降级切换让 OpenClaw 在主模型不可用时自动切换到备用模型保持基本可用性。16.4.2 配置多模型与优先级// ~/.openclaw/openclaw.json宽松 JSON{// 主模型Anthropic Claude最高优先级agent:{model:anthropic/claude-opus-4-6,},// Failover 备用模型列表按优先级排列models:[{id:primary,model:anthropic/claude-opus-4-6,priority:1,timeout:60000,maxRetries:2},{id:fallback-openai,model:openai/gpt-4o,priority:2,timeout:60000},{id:fallback-local,model:ollama/llama3.3,baseUrl:http://localhost:11434,priority:3,timeout:120000}]}priority字段表示优先级1 最高Gateway 按优先级从高到低尝试。16.4.3 Failover 逻辑伪代码// src/agents/model-client.ts伪代码asyncfunctionchatWithFailover(input:ModelInput,models:ModelConfig[]):PromiseModelOutput{constsortedModels[...models].sort((a,b)a.priority-b.priority);for(constmodelConfigofsortedModels){try{constclientgetModelClient(modelConfig);constoutputawaitwithTimeout(client.chat(input),modelConfig.timeout);returnoutput;}catch(err){constshouldFallbackisRetriableError(err);if(!shouldFallback||modelConfigsortedModels[sortedModels.length-1]){throwerr;// 最后一个模型也失败了}// 记录降级事件logger.warn(Model${modelConfig.id}failed, falling back to next,{err});}}thrownewError(All models unavailable);}functionisRetriableError(err:unknown):boolean{if(errinstanceofApiError){// 429速率限制、503/529服务不可用时降级return[429,503,529].includes(err.status);// 401认证失败不降级因为其他模型的 key 也可能错}if(errinstanceofTimeoutError)returntrue;if(errinstanceofNetworkError)returntrue;returnfalse;}16.4.4 模型降级通知当发生模型降级时Gateway 可以选择通知你// ~/.openclaw/openclaw.json宽松 JSON{models:{failoverNotify:{enabled:true,channel:slack,chatId:slack:channel:YOUR_CHANNEL_ID,message:⚠️ 主模型 {primaryModel} 不可用已降级到 {fallbackModel}}}}这样即使你不主动看日志也能第一时间知道发生了降级。16.5 数据管理与存储16.5.1 数据存储位置OpenClaw 的持久化数据通常存储在以下位置Session 数据和消息历史在~/.openclaw/data/sessions.dbSQLite或data/目录下Skills 授权凭据OAuth Token 等在~/.openclaw/data/auth/审计日志在~/.openclaw/data/audit/Skill 文件在~/.openclaw/workspace/skills/包括 Managed 和 Workspace Skills。16.5.2 清理过期数据# 查看数据目录大小openclaw data info# 清理超过 30 天的旧消息历史保留最近 30 天openclaw data prune --older-than 30d--typemessages# 清理临时文件截图、下载等openclaw data prune--typetmp# 完全重置删除所有 Session 和消息历史但保留配置和 Skill 授权openclaw data reset--confirm16.5.3 备份与恢复建议定期备份以下内容# 备份配置 数据 Skills均在 ~/.openclaw/ 下tar-czfopenclaw-backup-$(date%Y%m%d).tar.gz ~/.openclaw/# 恢复tar-xzfopenclaw-backup-20260301.tar.gz-C~/对于 Docker 部署数据卷的备份更重要dockerrun--rm\-vopenclaw_data:/data\-v$(pwd):/backup\busyboxtarczf /backup/openclaw-data-backup.tar.gz /data16.6 性能调优16.6.1 Gateway 启动变慢如果 Gateway 启动时间越来越长可以从几个方面排查。首先检查已安装的 Skill 数量禁用不常用的 Skillopenclaw skill disable name——每个启用的 Skill 都需要读取 SKILL.md 并解析 frontmatterSkill 过多会拖慢启动。其次检查是否有某个 Channel 适配器的连接初始化阶段卡住了关注启动日志中 Channel 连接相关的输出。还可以使用--verbose模式启动找到最慢的环节。16.6.2 消息响应变慢如果感觉 OpenClaw 回复越来越慢通常有几个原因。模型延迟方面通过openclaw stats tokens查看 context window 是否过大考虑调小contextWindowTokens。Session 历史过长也是常见原因在sessionConfig.contextWindowTokens里设置合理上限例如 4000-8000。Skill 调用慢可以通过openclaw stats skills找到耗时最高的 Skill 对症下药。如果使用 Ollama 等本地模型考虑升级 GPU 或切换到更小的模型。16.7 小结本章整理了 OpenClaw 日常运维的核心操作。健康检查靠openclaw doctor加定期查看 Stats 指标。通道断线按「状态 → 日志 → 重连 → 重授权」四步排查。模型故障靠配置多模型优先级加 Failover 自动切换加降级通知。升级流程是openclaw update加openclaw skill update --all加openclaw config migrate。数据管理上定期data prune并做好备份即可。接下来是全书的最后一章架构复盘与未来展望。在理解了 OpenClaw 的全部组件之后我们退一步反思它的设计取舍以及个人 AI Agent 这条路可能的走向。