以下是由我的AI助理與我一起攻克的FALLBACK MODEL設置方法,FYI

OpenRouter Free Model Fallback 配置指南

📝 文档信息

• 创建日期：2026-04-01
• 作者：小K (OpenClaw Assistant)
• 适用版本：OpenClaw 2026.2.26+
• 最后更新：2026-04-01

🎯 背景与动机

问题陈述

在使用 OpenRouter 的免费模型时，经常会遇到 Rate Limit (429) 错误。为了保持服务可用性，需要配置 fallback 机制：当主模型失败时，自动切换到备用模型。

本配置文件以 stepfun/step-3.5-flash:free 为主模型，配置了两个免费 fallback 模型作为后备。

🏗️ OpenClaw 配置结构

1. Auth Profiles (认证配置)

位置：openclaw.json → auth.profiles

"auth": {
  "profiles": {
    "openrouter:primary": {
      "provider": "openrouter",
      "mode": "api_key"
      // ⚠️ 注意：这里可以写 "apiKey" 字段，也可以留空依赖环境变量
    },
    "openrouter:fallback1": {
      "provider": "openrouter",
      "mode": "api_key"
    },
    "openrouter:fallback2": {
      "provider": "openrouter",
      "mode": "api_key"
    }
  },
  "order": {
    "openrouter": [
      "openrouter:primary",
      "openrouter:fallback1",
      "openrouter:fallback2"
    ]
  }
}

关键点：

• 每个 profile 代表一个 OpenRouter 身份（可以绑定不同的 API key）
• order 定义了使用顺序：先用 primary，失败后用 fallback1，再失败用 fallback2
• mode: "api_key" 表示使用 API key 认证

2. Agents Model Configuration (代理模型配置)

位置：openclaw.json → agents.defaults.model

"agents": {
  "defaults": {
    "model": {
      "primary": "openrouter/stepfun/step-3.5-flash:free",
      "fallbacks": [
        "openrouter/openrouter/free",
        "openrouter/z-ai/glm-4.5-air:free"
      ]
    },
    "models": {
      "openrouter/stepfun/step-3.5-flash:free": {
        "alias": "STEP 3.5 FREE"
        // 可以添加 "params": { "maxTokens": 4000 } 来限制输出长度
      },
      "openrouter/openrouter/free": {
        "streaming": true
        // ⚠️ 这是 Free Model Router，内部会轮询多个底层免费模型
      },
      "openrouter/z-ai/glm-4.5-air:free": {
        "alias": "Z-AI FREE"
      }
    }
  }
}

关键点：

• primary：主用模型
• fallbacks：备用模型列表（按顺序尝试）
• models：每个模型的额外参数（别名、流式输出、maxTokens 等）
• 注意：openrouter/openrouter/free 是「免费模型路由」，不是单一模型

🔄 优先级与选择逻辑

完整请求流程

用户请求
   ↓
OpenClaw 选择模型（primary）
   ↓
发起 OpenRouter API 请求
   ↓
    ├─ 成功 → 返回结果
    ├─ 429 Rate Limit → 尝试 fallbacks[0]
    │      ↓
    │   ├─ 成功 → 返回
    │   └─ 失败 → 尝试 fallbacks[1]
    │          ↓
    │       ├─ 成功 → 返回
    │       └─ 失败 → 报错
    └─ 其他错误（500/503）→ 同上 fallback 流程

API Key 选择逻辑

对于每个 model 配置，OpenClaw 会：

1. 看 auth.profiles 里对应 profile 是否显式配置了 apiKey
2. 如果没有，去环境变量 OPENROUTER_API_KEY 或 OPENROUTER_API_KEYS 中取
3. 如果 OPENROUTER_API_KEYS 有多个，按 auth.order.openrouter 的顺序轮询使用

你的实际配置示例：

"auth": {
  "profiles": {
    "openrouter:primary": {
      "mode": "api_key"
      // 没有 "apiKey" → 用环境变量 OPENROUTER_API_KEYS 里的第一个 key
    },
    "openrouter:fallback1": {
      "mode": "api_key"
      // 也没有 → 用环境变量里的下一个 key（轮询）
    },
    "openrouter:fallback2": {
      "mode": "api_key"
      // 同上
    }
  },
  "order": ["openrouter:primary", "openrouter:fallback1", "openrouter:fallback2"]
}

环境变量：

OPENROUTER_API_KEYS=key1,key2,key3

对应关系：

• openrouter:primary → 使用 key1
• openrouter:fallback1 → 使用 key2
• openrouter:fallback2 → 使用 key3

⚠️ Free Model 的限制与陷阱

1. openrouter/openrouter/free 是路由，不是具体模型

含义：

• 它会在后台选择某个底层免费模型（如 Llama 3.3 70B、Claude 3 Haiku、或小模型）
• 选择是动态的、随机的，取决于哪个提供商有Capacity
• maxTokens 限制不统一：小模型可能只有 512 tokens，大模型可达 4000+

问题：

• 有时输出被截断（选到小模型）
• 不稳定，不适合需要稳定长输出的任务

实测案例：

• 早上 09:00 SYSLOG 报告 → fallback 到 openrouter/free → 输出仅 541 tokens（截断）
• 因为当时选到了 maxTokens=512 的底层模型

2. 环境变量的多 key 轮询机制

如果你的 OPENROUTER_API_KEYS 有多个 key，OpenClaw 会按 auth.order 顺序使用：

• 第一次请求（primary）→ 用 primary profile 绑定的 key（环境变量第一个）
• 如果 primary 429 → 用 fallback1 profile → 环境变量下一个 key
• 再失败 → 用 fallback2 profile → 环境变量再下一个 key

这意味着：

• fallback1 和 fallback2 用的 different keys（来自同一个环境变量列表）
• 但底层模型还是 fallbacks 列表里指定的模型（如 openrouter/free、glm-4.5-air:free）

3. maxTokens 的有效性

情况 A：具体模型（如 stepfun/step-3.5-flash:free）

"params": { "maxTokens": 4000 }

✅ 有效，因为该模型本身支持长输出。

情况 B：路由模型（如 openrouter/openrouter/free）

"params": { "maxTokens": 4000 }

⚠️ 可能无效，因为底层小模型硬性限制 512 tokens，传 4000 也没用。

📊 实际使用记录分析

当前 auth.profiles 使用统计

根据 usageStats：

解读：

• 主模型（primary）最近没被使用（可能因为无请求或未被调用）
• 昨天（3/31）有一次 fallback → 用了 fallback1
• 刚才（22:35）又有一次 fallback → 用了 fallback2
• 说明最近有连续 fallback 事件（可能主模型持续 429）

🛠️ 配置验证方法

1. 检查当前生效的配置

# 查看 openclaw.json 中 auth 和 model 部分
cat ~/.openclaw/openclaw.json | jq '.auth, .agents.defaults.model'

2. 查看环境变量

echo "OPENROUTER_API_KEY: $OPENROUTER_API_KEY"
echo "OPENROUTER_API_KEYS: $OPENROUTER_API_KEYS"

3. 查看模型使用日志

# 查看当前会话 history，每条消息的 model 字段
# 例如：使用 sessions_history 工具

4. 测试 fallback 是否工作

故意触发 429：

1. 短时间内发送大量请求（超过 rate limit）
2. 观察 sessions_history 中是否出现不同 model 字段
3. 检查消息内容是否完整（无截断）

🎯 推荐的优化配置

方案 A：保持当前结构，但显式指定 API Keys

"auth": {
  "profiles": {
    "openrouter:primary": {
      "provider": "openrouter",
      "mode": "api_key",
      "apiKey": "sk-or-v1-你的primary-key"
    },
    "openrouter:fallback1": {
      "provider": "openrouter",
      "mode": "api_key",
      "apiKey": "sk-or-v1-第二个key"
    },
    "openrouter:fallback2": {
      "provider": "openrouter",
      "mode": "api_key",
      "apiKey": "sk-or-v1-第三个key"
    }
  },
  "order": {
    "openrouter": ["openrouter:primary", "openrouter:fallback1", "openrouter:fallback2"]
  }
}

优点：清晰、独立、便于管理

方案 B：使用具体长文本模型作为 fallback（避免 openrouter/free 路由）

"agents": {
  "defaults": {
    "model": {
      "primary": "openrouter/stepfun/step-3.5-flash:free",
      "fallbacks": [
        "meta-llama/llama-3.3-70b-instruct:free",   // 明确 70B 大模型
        "anthropic/claude-3-haiku:free",           // 明确 Haiku
        "openrouter/openrouter/free"                // 最后才用路由
      ]
    },
    "models": {
      "openrouter/stepfun/step-3.5-flash:free": {
        "alias": "STEP 3.5 FREE",
        "params": { "maxTokens": 4000 }
      },
      "meta-llama/llama-3.3-70b-instruct:free": {
        "params": { "maxTokens": 4000 }
      },
      "anthropic/claude-3-haiku:free": {
        "params": { "maxTokens": 4000 }
      },
      "openrouter/openrouter/free": {
        "params": { "maxTokens": 4000 }  // 尽力而为
      }
    }
  }
}

优点：fallback 模型更稳定，maxTokens 真正生效

📈 监控与维护

监控指标

定期检查

• 每周：查看 usageStats，确认 fallback 使用正常
• 每月：轮换 API keys（安全最佳实践）
• 每次遇到截断：检查是否 fallback 到 openrouter/free，考虑调整 fallback 列表

🔧 故障排除

问题：fallback 后输出被截断（只有几百 tokens）

可能原因：

• fallback 到了 openrouter/free，且选到了底层小模型

解决方案：

1. 检查 sessions_history 确认哪个模型被使用
2. 调整 fallbacks 列表，把 openrouter/free 放到最后
3. 添加具体的大模型作为 fallback（如 llama-3.3-70b:free）

问题：所有模型都 429，fallback 也没用

可能原因：

• 所有 keys 都达到 rate limit（免费账户总共 1000 req/day）
• 或 OpenRouter 服务商级故障

解决方案：

1. 检查 OpenRouter dashboard 的 usage 和 credits
2. 增加 OPENROUTER_API_KEYS 数量（更多 keys = 更高总配额）
3. 考虑升级到付费 credits

问题：不确定当前用的是哪个 API key

排查方法：

1. 检查 openclaw.json 中 auth.profiles 是否有显式 apiKey
2. 如果没有，环境变量 OPENROUTER_API_KEYS 的顺序决定哪个 key 被用
3. 在第 3 个 key 前加上前缀 "fallback2": "sk-or-v1-xxx" 显式指定

🧠 关键概念总结

📚 参考资料

• OpenRouter 文档：https://openrouter.ai/docs
• OpenClaw 配置指南：/usr/lib/node_modules/openclaw/docs
• 本工作区记忆文件：
• MEMORY.md – 长期记忆（包含本次配置的完整背景）
• memory/2026-04-01.md – 当日操作日志

✅ 当前配置总览（2026-04-01 22:54 状态）

• 主模型：openrouter/stepfun/step-3.5-flash:free
• Fallback 模型：openrouter/openrouter/free（第一备）、openrouter/z-ai/glm-4.5-air:free（第二备）
• Auth Profiles：3 个 profiles（primary, fallback1, fallback2），均依赖 OPENROUTER_API_KEYS 环境变量
• API Keys：3 个，通过 OPENROUTER_API_KEYS 提供
• 最近 fallback 事件：今天 22:35 使用了 fallback2
• 主要问题：openrouter/free 输出限制导致长报告截断（需要调整为具体大模型）

文档结束