第 16 章 运维日常：升级、排障、模型 Failover

OpenClaw 跑起来之后，你会遇到各种日常问题：通道断了、模型 API 超额了、某个 Skill 行为异常……本章是一本运维手册，按场景整理了常用的排查思路和操作命令。

16.1 日常健康检查

16.1.1 快速确认 Gateway 是否正常

# 检查进程是否在运行
openclaw gateway status
# 或
ps aux | grep openclaw

# 检查 HTTP 健康端点（如果不在本机，替换 IP）
curl http://localhost:18789/health
# 正常返回：{"status":"ok","uptime":123456}

# 全面自检
openclaw doctor

16.1.2 定期关注的几个指标

建议养成每周看一次的习惯：

# Token 消耗统计（按 Session / Agent 聚合）
openclaw stats tokens --period 7d

# Skill 调用次数和错误率
openclaw stats skills --period 7d

# 通道连接状态
openclaw channel list

# 最近 Cron Job 的执行记录
openclaw cron history --limit 20

16.2 升级 OpenClaw

16.2.1 版本更新

# 检查当前版本和是否有新版本
openclaw version

# 升级到最新稳定版
openclaw update

# 升级到特定版本
openclaw update --version 2026.3.1

升级后，建议先运行 openclaw doctor 确认一切正常，然后检查 CHANGELOG.md 或官方发布说明看看有没有破坏性变更。如果升级了 Node.js 大版本，注意检查兼容性问题。

16.2.2 Skills 的升级

# 列出所有 Managed Skills 及其版本
openclaw skill list --show-updates

# 升级特定 Skill
openclaw skill update gmail

# 升级所有 Managed Skills
openclaw skill update --all

Skill 升级通常不需要重启 Gateway（热加载）。如果升级涉及 API 变更，建议先在测试消息里验证一下。

16.2.3 配置迁移

如果新版本涉及配置 schema 变更（例如字段重命名），可以运行迁移工具：

openclaw config migrate
# 自动把旧格式配置转换为新格式，原文件备份为 openclaw.json.bak

16.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 --channel discord --tail 50

# 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 --filter agent --tail 30

# 2. 常见错误码
# 429: Rate limit exceeded（请求过快，触发速率限制）
# 401: Invalid API key（API Key 无效或过期）
# 529: Model overloaded（模型服务器过载，临时性问题）
# 408/504: Timeout（网络超时或模型响应慢）

# 3. 手动测试模型 API 是否可用
openclaw model test anthropic
# 输出：✓ Anthropic (claude-opus-4-6): response in 1.2s

16.3.3 Skill 调用异常

典型现象是某个 Skill 的操作没生效，或模型说「调用工具时出错」。

# 1. 查看 Skill 相关日志
openclaw logs --skill gmail --tail 30

# 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 --skill gmail --limit 10

16.3.4 Cron Job 没有触发

# 查看 Cron Job 配置和状态
openclaw cron list

# 查看 Cron 调度历史（最近 10 次触发记录）
openclaw cron history morning-briefing --limit 10

# 手动触发一次，验证任务本身是否正常
openclaw cron trigger morning-briefing

# 如果手动触发正常，但自动不触发，检查系统时区
date
timedatectl status  # Linux

有一个常见坑：Cron 表达式按 Gateway 所在机器的本地时区解析。如果你的 Mac 在 UTC+8，但设备时区配置有误，Cron 时间会偏移。

16.4 模型 Failover：主模型不可用时的降级策略

16.4.1 为什么需要 Failover

AI 模型 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（伪代码）

async function chatWithFailover(
  input: ModelInput,
  models: ModelConfig[]
): Promise<ModelOutput> {
  const sortedModels = [...models].sort((a, b) => a.priority - b.priority);

  for (const modelConfig of sortedModels) {
    try {
      const client = getModelClient(modelConfig);
      const output = await withTimeout(
        client.chat(input),
        modelConfig.timeout
      );
      return output;
    } catch (err) {
      const shouldFallback = isRetriableError(err);
      if (!shouldFallback || modelConfig === sortedModels[sortedModels.length - 1]) {
        throw err; // 最后一个模型也失败了
      }
      // 记录降级事件
      logger.warn(`Model ${modelConfig.id} failed, falling back to next`, { err });
    }
  }

  throw new Error("All models unavailable");
}

function isRetriableError(err: unknown): boolean {
  if (err instanceof ApiError) {
    // 429（速率限制）、503/529（服务不可用）时降级
    return [429, 503, 529].includes(err.status);
    // 401（认证失败）不降级（因为其他模型的 key 也可能错）
  }
  if (err instanceof TimeoutError) return true;
  if (err instanceof NetworkError) return true;
  return false;
}

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.db（SQLite）或 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 --type messages

# 清理临时文件（截图、下载等）
openclaw data prune --type tmp

# 完全重置（删除所有 Session 和消息历史，但保留配置和 Skill 授权）
openclaw data reset --confirm

16.5.3 备份与恢复

建议定期备份以下内容：

# 备份（配置 + 数据 + Skills，均在 ~/.openclaw/ 下）
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 恢复
tar -xzf openclaw-backup-20260301.tar.gz -C ~/

对于 Docker 部署，数据卷的备份更重要：

docker run --rm \
  -v openclaw_data:/data \
  -v $(pwd):/backup \
  busybox tar czf /backup/openclaw-data-backup.tar.gz /data

16.6 性能调优

16.6.1 Gateway 启动变慢

如果 Gateway 启动时间越来越长，可以从几个方面排查。首先检查已安装的 Skill 数量，禁用不常用的 Skill（openclaw skill disable <name>）——每个启用的 Skill 都需要读取 SKILL.md 并解析 frontmatter，Skill 过多会拖慢启动。其次检查是否有某个 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 这条路可能的走向。