Updating OpenRouter Free Models
Overview
A systematic, test-driven process for updating OpenRouter free models that ensures only verified working models are added to configuration files. Combines automated fetching, batch testing, and multi-config synchronization.
When to Use
Use when:
- - Adding new OpenRouter free models to configurations
- Syncing model lists between Claude Code and OpenClaw
- need to verify model availability before adding
- Managing model fallbacks and availability allowlists
Do NOT use for:
- - Single model additions (manual edit is faster)
- Paid model configurations (different testing criteria)
- Other provider types (Anthropic, OpenAI direct)
Core Workflow
CODEBLOCK0
Quick Reference
| Step | Command | Purpose |
|---|
| 1 | INLINECODE0 | Fetch all free models |
| 2 |
python3 test_models.py | Batch test availability |
| 3 |
node apply_updates_openclaw.js | Update OpenClaw config |
| 4 |
./restart_openclaw.sh | Restart service |
| 5 | Validate JSON | Prevent syntax errors |
Implementation
Step 1: Fetch Free Models from OpenRouter API
CODEBLOCK1
Free Model Detection: The script identifies free models by:
- - ID containing
:free suffix, OR - All pricing fields (
prompt, completion, request) equaling 0 or INLINECODE9
This captures models like openrouter/hunter-alpha that have zero pricing but lack the :free tag.
Step 2: Batch Test Availability
CODEBLOCK2
The script will:
- - Read models from INLINECODE12
- Test each with a short API call
- Save verified models to INLINECODE13
- Save failed models to
/tmp/failed_models.txt with error reasons
Note: The script supports multiple token sources:
- -
ANTHROPIC_AUTH_TOKEN (Claude Code compatibility) - INLINECODE16 (OpenRouter direct)
- OpenClaw config (
~/.openclaw/openclaw.json → models.providers.openrouter.apiKey)
Step 3: Update Claude Code Settings
CODEBLOCK3
Then manually or programmatically insert into ~/.claude/settings.json.
Step 4: Update OpenClaw Configuration
CODEBLOCK4
Step 5: Validate and Self-Test
CODEBLOCK5
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|
| Missing rate limiting | API errors/timeouts | Add time.sleep(0.5) between tests |
| Not filtering duplicates |
Same model twice | Use
set() on results |
| Forgetting fallbacks array | Only primary works | Update both
models and
fallbacks |
| Invalid JSON after edit | Config won't load | Run
python3 -m json.tool to validate |
| Skipping self-test | Broken config deployed | Always run validation commands |
Real-World Example
Before: Manually copying models from website → errors, outdated models, missing configs
After: Automated fetch + test → only verified models, synchronized configs, repeatable process
Anti-Patterns
❌ Add All Models Without Testing
CODEBLOCK6
❌ One Configuration Only
CODEBLOCK7
❌ No Self-Test
CODEBLOCK8
Testing Checklist
- - [ ] Fetch produces non-empty model list
- [ ] All verified models pass API test in batch
- [ ] Claude settings JSON is valid
- [ ] OpenClaw JSON is valid
- [ ]
availableModels exists and is array - [ ] OpenClaw
models.providers.openrouter.models updated - [ ] OpenClaw
agents.defaults.model.fallbacks includes all except primary - [ ] OpenClaw
agents.defaults.models has entries for all - [ ] Actual API call works with at least one model from new list
Maintenance
When to rerun this skill:
- - Monthly (OpenRouter adds/removes free models regularly)
- After API error indicates specific model unavailable
- Adding new configuration targets (e.g., new tool that uses OpenRouter)
What to update if API changes:
- - Model filter logic (free detection criteria may change - see
is_free_model() in fetch_models.py) - Test request format (API endpoint may version)
- Rate limits (adjust sleep duration)
OpenClaw-Specific Notes
OpenClaw Scripts
This skill includes OpenClaw-specific scripts in the workspace:
| Script | Purpose |
|---|
| INLINECODE31 | Batch test models (same as Claude Code version) |
| INLINECODE32 |
Node.js version for OpenClaw config updates |
|
restart_openclaw.sh | Restart OpenClaw gateway service after update |
Full OpenClaw Workflow
CODEBLOCK9
Why restart? OpenClaw loads configuration at startup. Changes to openclaw.json require restart to take effect.
Restart Methods
INLINECODE35 tries multiple methods:
- 1.
launchctl (if running as macOS service) - INLINECODE37 +
nohup (manual restart) - Reports errors if both fail
Logs: INLINECODE39
Testing After Update
CODEBLOCK10
See Also
- - OpenRouter API docs: https://openrouter.ai/docs
- Claude Code settings schema:
~/.claude/settings.json structure - OpenClaw configuration:
~/.openclaw/openclaw.json model sections - OpenClaw gateway docs: INLINECODE42
更新 OpenRouter 免费模型
概述
一个系统化、测试驱动的流程，用于更新 OpenRouter 免费模型，确保只有经过验证可用的模型才会被添加到配置文件中。结合了自动获取、批量测试和多配置同步。
何时使用
适用场景：
- - 向配置中添加新的 OpenRouter 免费模型
- 在 Claude Code 和 OpenClaw 之间同步模型列表
- 在添加前需要验证模型可用性
- 管理模型回退和可用性白名单
不适用于：
- - 单个模型添加（手动编辑更快）
- 付费模型配置（测试标准不同）
- 其他提供商类型（Anthropic、OpenAI 直连）
核心工作流程
mermaid
graph LR
A[从 OpenRouter API 获取模型] --> B[批量测试每个模型];
B --> C{通过测试？};
C -->|是| D[添加到已验证列表];
C -->|否| E[跳过 + 记录原因];
D --> F[更新配置];
F --> G[验证 JSON 语法];
G --> H[自测更新后的配置];
H --> I[重启 OpenClaw 服务];
快速参考
| 步骤 | 命令 | 目的 |
|---|
| 1 | python3 fetchmodels.py | 获取所有免费模型 |
| 2 |
python3 testmodels.py | 批量测试可用性 |
| 3 | node apply
updatesopenclaw.js | 更新 OpenClaw 配置 |
| 4 | ./restart_openclaw.sh | 重启服务 |
| 5 | 验证 JSON | 防止语法错误 |
实现
步骤 1：从 OpenRouter API 获取免费模型
bash
使用提供的获取脚本，该脚本实现了全面的免费模型检测
python3 fetch_models.py
免费模型检测： 脚本通过以下方式识别免费模型：
- - ID 包含 :free 后缀，或
- 所有定价字段（prompt、completion、request）等于 0 或 0
这可以捕获像 openrouter/hunter-alpha 这样定价为零但缺少 :free 标签的模型。
步骤 2：批量测试可用性
bash
通过 API 测试每个获取的模型
python3 test_models.py
脚本将：
- - 从 /tmp/freemodels.txt 读取模型
- 使用简短的 API 调用测试每个模型
- 将验证通过的模型保存到 /tmp/verifiedmodels.txt
- 将失败的模型及其错误原因保存到 /tmp/failed_models.txt
注意： 脚本支持多种令牌来源：
- - ANTHROPICAUTHTOKEN（Claude Code 兼容）
- OPENROUTERAPIKEY（OpenRouter 直连）
- OpenClaw 配置（~/.openclaw/openclaw.json → models.providers.openrouter.apiKey）
步骤 3：更新 Claude Code 设置
bash
为 availableModels 生成 JSON 数组
cat > /tmp/availableModels.json << EOF
$(python3 -c
models = open(/tmp/verified_models.txt).read().strip().split(\n)
print( \availableModels\: [)
for i, m in enumerate(models):
comma = , if i < len(models)-1 else
print(f \{m}\{comma})
print( ],)
)
然后手动或通过程序插入到 ~/.claude/settings.json 中。
步骤 4：更新 OpenClaw 配置
python
import json
from pathlib import Path
读取现有配置
with open(Path.home() / .openclaw / openclaw.json, r) as f:
config = json.load(f)
更新提供商模型
verified = open(/tmp/verified_models.txt).read().strip().split(\n)
provider_models = []
fallbacks = []
for i, model_id in enumerate(verified):
provider_models.append({
id: model_id,
name: model_id.split(/)[-1],
api: openai-completions
})
if i > 0: # 从回退列表中跳过主要模型（stepfun）
fallbacks.append(fopenrouter/{model_id})
config[models][providers][openrouter][models] = provider_models
config[agents][defaults][model][fallbacks] = fallbacks
添加到 agents.defaults.models
for model_id in verified:
key = fopenrouter/{model_id}
if key not in config[agents][defaults][models]:
config[agents][defaults][models][key] = {}
保存
with open(Path.home() / .openclaw / openclaw.json, w) as f:
json.dump(config, f, indent=2)
print(f已更新 OpenClaw 配置，包含 {len(verified)} 个模型)
步骤 5：验证和自测
bash
验证 JSON 语法
python3 -m json.tool ~/.claude/settings.json > /dev/null && echo ✓ Claude 设置有效
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null && echo ✓ OpenClaw 配置有效
自测：验证 models 字段存在且为数组
python3 -c
import json
with open(~/.claude/settings.json) as f:
cfg = json.load(f)
assert availableModels in cfg
assert isinstance(cfg[availableModels], list)
print(f✅ Claude：{len(cfg[\availableModels\])} 个模型可用)
常见陷阱
| 陷阱 | 症状 | 修复 |
|---|
| 缺少速率限制 | API 错误/超时 | 在测试之间添加 time.sleep(0.5) |
| 未过滤重复项 |
同一模型出现两次 | 对结果使用 set() |
| 忘记回退数组 | 只有主要模型工作 | 同时更新 models 和 fallbacks |
| 编辑后 JSON 无效 | 配置无法加载 | 运行 python3 -m json.tool 验证 |
| 跳过自测 | 部署了损坏的配置 | 始终运行验证命令 |
实际示例
之前： 手动从网站复制模型 → 错误、过时模型、缺少配置
之后： 自动获取 + 测试 → 仅验证通过的模型、同步配置、可重复流程
反模式
❌ 不测试就添加所有模型
python
错误：直接获取列表并全部添加
models = fetch_all()
问题：某些模型可能受速率限制、已弃用或地区限制
❌ 只更新一个配置
python
错误：只更新 Claude 设置，忘记 OpenClaw
update
claudesettings(verified_models)
问题：OpenClaw 仍使用旧列表 → 行为不一致
❌ 不自测
python
错误：写入文件并假设正确
with open(settings.json, w) as f:
json.dump(config, f)
问题：语法错误会破坏整个应用程序
测试清单
- - [ ] 获取产生非空模型列表
- [ ] 所有验证通过的模型在批量测试中通过 API 测试
- [ ] Claude 设置 JSON 有效
- [ ] OpenClaw JSON 有效
- [ ] availableModels 存在且为数组
- [ ] OpenClaw models.providers.openrouter.models 已更新
- [ ] OpenClaw agents.defaults.model.fallbacks 包含除主要模型外的所有模型
- [ ] OpenClaw agents.defaults.models 包含所有模型的条目
- [ ] 使用新列表中的至少一个模型进行实际 API 调用有效
维护
何时重新运行此技能：
- - 每月一次（OpenRouter 定期添加/移除免费模型）
- API 错误指示特定模型不可用后
- 添加新的配置目标（例如，使用 OpenRouter 的新工具）
如果 API 更改需要更新什么：
- - 模型过滤逻辑（免费检测标准可能变化 - 请查看 fetchmodels.py 中的 isfree_model()）
- 测试请求格式（API 端点可能版本化）
- 速率限制（调整休眠时长）
OpenClaw 特定说明
OpenClaw 脚本
此技能包含工作区中的 OpenClaw 特定脚本：
| 脚本 | 目的 |
|---|
| testmodels.py | 批量测试模型（与 Claude Code 版本相同） |
| applyupdates_openclaw.js |
用于 OpenClaw 配置更新的
