1. OpenClaw 运维日常到底在维护什么OpenClaw 跑起来只是开始真正花时间的是后面那些琐碎事通道突然不回消息、模型 API 报 429、某个 Skill 行为诡异、升级之后配置字段对不上。这些问题的共同点是——它们不会在第一次部署时暴露而是在你用了两三周、Session 攒了几百条、Skill 装了十几个之后才慢慢浮现。所以这一章我把它当成一本随身运维手册来写重点放在三件事升级流程怎么走不翻车、排障路径怎么按顺序查、模型 Failover 怎么配才能真正在主模型挂掉时自动切换。如果你刚开始接触 OpenClaw可以把它理解成一个本地常驻的 AI Agent 网关它对外连接 Slack、Discord、iMessage 这些通道对内调度模型 API 和一堆 Skill每个 Skill 就是一个 Markdown 说明文件加底层 CLI 工具。它自己不做推理而是把消息转发给模型再把模型的动作指令翻译成对 Skill 的调用。这个结构决定了它的故障面比普通脚本大得多——通道、模型、Skill、Cron、存储任何一环出问题都会表现为“机器人不回消息”。适合读这篇的人有三类一是已经把 OpenClaw 跑起来、正在被日常小故障折磨的二是准备上生产、想提前把 Failover 和备份做好的三是想理解一个 Agent 网关的运维模型长什么样的。下面所有命令和配置我都尽量给完整你可以直接复制到本地复现。2. TaoToken 前置把模型接入层先理顺在讲 Failover 之前得先把模型接入这一层说清楚。OpenClaw 本身不绑定任何一家模型服务它通过统一的 API 端点去调用模型。我实测下来用 TaoToken 作为模型接入层比较省心原因是它的 API 格式兼容主流协议OpenClaw 的 model 配置里只要改 baseUrl 和 apiKey 就能接上不用为每个模型单独写适配。TaoToken 在这里扮演的角色是“模型调用的统一入口”。你可以在它的控制台里创建 API Key然后 OpenClaw 的每个模型配置项都指向同一个 baseUrl只是 model 字段不同。这样做的好处是 Failover 配置会非常干净——主模型和备用模型走同一个接入层切换时不需要改网络配置只需要换 model 名字。具体要准备的东西一个 TaoToken 账号在控制台里生成一个 API Key建议给 OpenClaw 单独建一个 Key方便后面按 Key 维度看用量然后记下 API 端点。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。控制台里创建 Key 的页面在 console 下接入文档在 doc 下这两个后面排障时会反复用到。注意API Key 不要写进会提交到 Git 的配置文件里。OpenClaw 支持从环境变量读取建议用TAOTOKEN_API_KEY这个变量名配置文件里只写${TAOTOKEN_API_KEY}。3. 可复制配置config.toml 与 settings.json 骨架OpenClaw 的配置分两层config.toml管网关级别的行为端口、日志、通道settings.json管 Agent 和模型层模型列表、Failover、Session 上下文。下面这两份骨架你可以直接拿去改。3.1 config.toml网关与通道骨架# ~/.openclaw/config.toml [gateway] host 0.0.0.0 port 18789 logLevel info dataDir ~/.openclaw/data [health] enabled true path /health [channels.slack] enabled true mode socket botToken ${SLACK_BOT_TOKEN} appToken ${SLACK_APP_TOKEN} [channels.discord] enabled true botToken ${DISCORD_BOT_TOKEN} [channels.imessage] enabled false [logging] file ~/.openclaw/logs/gateway.log maxSize 50MB maxFiles 5这份配置里我特意把logLevel设成 info 而不是 debug因为 debug 模式下模型调用的完整 payload 都会落盘跑一天日志能到几个 G。排障时临时改成 debug查完记得改回来。3.2 settings.json模型与 Failover 骨架{ agent: { model: taotoken/claude-opus-4-6, contextWindowTokens: 8000 }, models: [ { id: primary, model: taotoken/claude-opus-4-6, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, priority: 1, timeout: 60000, maxRetries: 2 }, { id: fallback-gpt, model: taotoken/gpt-4o, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, priority: 2, timeout: 60000 }, { id: fallback-local, model: ollama/llama3.3, baseUrl: http://localhost:11434, priority: 3, timeout: 120000 } ], models.failoverNotify: { enabled: true, channel: slack, chatId: slack:channel:YOUR_CHANNEL_ID, message: 主模型 {primaryModel} 不可用已降级到 {fallbackModel} } }priority数字越小优先级越高Gateway 按这个顺序从上往下试。timeout是单个模型的超时时间本地 Ollama 我给了 120 秒因为消费级显卡跑大模型首 token 延迟经常超过 60 秒。maxRetries只对主模型设了 2备用模型不重试避免故障时整体响应时间被拖长。3.3 升级与配置迁移命令升级流程我固定成三步顺序不能反# 1. 先看当前版本和可用更新 openclaw version openclaw update --check # 2. 升级到最新稳定版或指定版本 openclaw update # openclaw update --version 2026.3.1 # 3. 配置 schema 迁移 自检 openclaw config migrate openclaw doctorconfig migrate会把旧格式配置转成新格式原文件备份成openclaw.json.bak。我踩过的坑是升级后直接启动 Gateway结果因为字段重命名导致模型配置被忽略机器人还在跑但用的是默认模型。所以升级后一定先跑doctor它会明确告诉你哪些字段已经废弃。Skill 的升级是独立的通常热加载不需要重启openclaw skill list --show-updates openclaw skill update --all4. 验证 Failover 是否真的生效配置写完不代表 Failover 就生效了必须手动验证。下面这套步骤我每次改完模型配置都会跑一遍。4.1 先确认模型本身可用openclaw model test taotoken/claude-opus-4-6 # 期望输出✓ taotoken/claude-opus-4-6: response in 1.2s如果这一步就失败说明 API Key 或 baseUrl 有问题先解决这个再谈 Failover。4.2 人为制造主模型故障最直接的办法是把主模型的 apiKey 改成一个无效值然后发一条测试消息# 临时把主模型 key 指向错误值 export TAOTOKEN_API_KEYinvalid-key-for-test openclaw gateway restart # 发测试消息通过 CLI 直接触发 Agent openclaw agent send 现在几点了如果 Failover 生效你会看到回复正常返回同时日志里出现降级记录openclaw logs --filter model --tail 20 # 期望看到类似 # WARN Model primary failed, falling back to next { err: 401 } # INFO Using fallback model fallback-gpt4.3 验证降级通知如果配了failoverNotify降级发生时 Slack 频道里应该收到一条消息。没收到的话检查chatId格式必须是slack:channel:频道ID这种三段式少一段都不会发出去。4.4 验证全部模型不可用时的行为把主模型和备用模型的 key 都改成无效值再发消息。期望行为是返回一个明确的错误而不是无限重试卡死openclaw agent send 测试全部失败 # 期望快速返回 All models unavailable 类错误如果这里卡住超过 30 秒说明timeout或maxRetries配得太大需要调小。5. 本篇常见错排查5.1 通道断线按四步走通道断线的典型现象是发消息没反应openclaw channel list显示某通道 disconnected。排查顺序固定为状态 → 日志 → 重连 → 重授权。openclaw channel list openclaw logs --channel discord --tail 50 openclaw channel restart discord openclaw channel discord authSlack 有个特有问题Socket Mode 连接中断时先检查 App Token 是否还有效。如果你切换过工作区或被管理员撤权必须重新授权。HTTP 模式的用户还要去 Slack App 后台确认 Event Subscriptions 的 Request URL 返回 200。5.2 模型调用失败先看错误码openclaw logs --filter agent --tail 30429 是速率限制401 是 Key 无效529 是模型过载408/504 是超时。429 和 529 会触发 Failover401 不会——因为如果主模型 Key 错了备用模型用同一个 Key 大概率也错降级没意义。这个逻辑在isRetriableError里写死了改配置改不了。5.3 Skill 调用异常查底层 CLISkill 本身只是 Markdown 说明文件不持有 OAuth Token。它依赖的 CLI 工具需要各自独立授权openclaw skill status gmail # ✗ gmail: requires himalaya (not found)看到 not found 就去装对应的 CLI看到 env not set 就去补环境变量。Skill 的授权和 OpenClaw 的授权是两套东西这点很容易搞混。5.4 Cron 不触发先查时区openclaw cron list openclaw cron history morning-briefing --limit 10 openclaw cron trigger morning-briefing date timedatectl status手动触发正常但自动不触发九成是时区问题。Cron 表达式按 Gateway 所在机器的本地时区解析机器时区配错会导致时间整体偏移。5.5 升级后启动变慢启动慢通常是 Skill 太多。每个启用的 Skill 都要读 SKILL.md 并解析 frontmatter装几十个会明显拖慢openclaw skill disable name openclaw gateway start --verbose用 verbose 模式能看到每个阶段的耗时找到最慢的环节。6. 把运维动作固化成习惯上面这些命令和配置单看每一条都不复杂难的是在故障发生时能按顺序想起来。我的做法是把健康检查固化成每周一次openclaw doctor加openclaw stats tokens --period 7d加openclaw channel list三分钟看完。升级固定在低峰期做升级前先tar -czf备份整个~/.openclaw/目录出问题能整体回滚。模型 Failover 这块配置只是第一步真正让它可靠的是定期验证。我建议每次改完模型配置都跑一遍第 4 节那套步骤确认降级路径是通的。如果你还在用单一模型、没配 Failover可以先从加一个备用模型开始——哪怕备用模型只是本地 Ollama在主模型 API 抖动时也能保证机器人不至于完全失联。需要看模型调用用量和 Key 管理的话TaoToken 的 console 页面在 https://taotoken.net/api 对应的控制台里接入文档在 doc 下排障时对着文档核对参数比猜要快得多。
