【Bug已解决】openclaw: "model not found" / Invalid model name — OpenClaw 模型不存在解决方案
1. 问题描述
OpenClaw 使用了不存在或已弃用的模型名称：
# 模型不存在 $ openclaw --model claude-3 "task" Error: model_not_found Model 'claude-3' does not exist. # 或模型已弃用 $ openclaw --model claude-2 "task" Error: model_deprecated Model 'claude-2' is no longer available. # 或模型名拼写错误 $ openclaw --model Claude-Sonnet "task" Error: model_not_found Model 'Claude-Sonnet' does not exist. # 或配置中的模型不存在 $ cat .openclaw/config.json {"model": "claude-3-opus"} $ openclaw "task" Error: model_not_found这个问题在以下场景中特别常见：
- 模型名拼写错误（大小写）
- 使用了已弃用的模型
- 模型名不完整（缺少日期后缀）
- 配置中的模型名错误
- 版本不支持新模型
- 混淆了不同 API 的模型名
2. 原因分析
原因分类表
| 原因分类 | 具体表现 | 占比 |
|---|---|---|
| 拼写错误 | 大小写/空格 | 约 35% |
| 已弃用 | claude-2 | 约 25% |
| 不完整 | 缺少日期 | 约 20% |
| 配置错误 | config.json | 约 10% |
| 版本不支持 | 旧版本 | 约 5% |
| 混淆 API | OpenAI 名称 | 约 5% |
3. 解决方案
方案一：使用正确的模型名（最推荐）
# 步骤 1：查看可用模型 openclaw --list-models # 或 openclaw --help | grep -A20 model # 步骤 2：使用正确的名称 openclaw --model claude-sonnet-4-20250514 "task" openclaw --model claude-opus-4-20250514 "task" openclaw --model claude-3-haiku-20240307 "task" # 步骤 3：避免错误名称 # 错误: claude-3, Claude-Sonnet, claude-sonnet # 正确: claude-sonnet-4-20250514 # 步骤 4：验证 openclaw --model claude-sonnet-4-20250514 --print "hello"方案二：修复配置文件
# 步骤 1：检查配置 cat .openclaw/config.json | grep model # 步骤 2：修复模型名 cat > .openclaw/config.json << 'EOF' { "model": "claude-sonnet-4-20250514" } EOF # 步骤 3：验证 python3 -m json.tool .openclaw/config.json # 步骤 4：测试 openclaw --print "hello"方案三：使用环境变量
# 步骤 1：设置模型 export OPENCLAW_MODEL=claude-sonnet-4-20250514 # 步骤 2：永久设置 echo 'export OPENCLAW_MODEL=claude-sonnet-4-20250514' >> ~/.bashrc source ~/.bashrc # 步骤 3：测试 openclaw --print "hello" # 步骤 4：验证模型 openclaw --debug 2>&1 | grep -i model方案四：检查大小写
# 步骤 1：模型名是大小写敏感的 # 正确: claude-sonnet-4-20250514 (全小写) # 错误: Claude-Sonnet-4-20250514 # 错误: CLAUDE-SONNET-4-20250514 # 步骤 2：避免空格 # 错误: claude sonnet 4 # 正确: claude-sonnet-4-20250514 # 步骤 3：包含日期后缀 # 错误: claude-sonnet-4 # 正确: claude-sonnet-4-20250514 # 步骤 4：验证 openclaw --model claude-sonnet-4-20250514 --print "hello"方案五：使用默认模型
# 步骤 1：不指定模型，使用默认 openclaw "task" # 步骤 2：或移除配置中的 model python3 -c " import json with open('.openclaw/config.json') as f: config = json.load(f) config.pop('model', None) with open('.openclaw/config.json', 'w') as f: json.dump(config, f, indent=2) " # 步骤 3：使用默认模型 openclaw --print "hello" # 步骤 4：验证 openclaw --debug 2>&1 | grep -i "model\|default"方案六：更新版本
# 步骤 1：检查版本 openclaw --version # 步骤 2：更新 pip install --upgrade openclaw # 步骤 3：验证模型支持 openclaw --list-models # 步骤 4：测试 openclaw --model claude-sonnet-4-20250514 --print "hello"4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一：正确名称 | 通用 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二：修复配置 | config | ⭐⭐⭐⭐⭐ | 低 |
| 方案三：环境变量 | 替代 | ⭐⭐⭐⭐ | 低 |
| 方案四：检查大小写 | 拼写 | ⭐⭐⭐⭐⭐ | 低 |
| 方案五：默认模型 | 临时 | ⭐⭐⭐⭐ | 低 |
| 方案六：更新 | 版本 | ⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.1 如何查看可用模型
openclaw --list-models5.2 常用的模型名
claude-sonnet-4-20250514claude-opus-4-20250514claude-3-haiku-20240307
5.3 模型名大小写重要吗
是的。使用全小写claude-sonnet-4-20250514。
5.4 需要日期后缀吗
是的。claude-sonnet-4不够，需要claude-sonnet-4-20250514。
5.5 claude-2 还可用吗
不可用。已弃用。
5.6 如何在配置中设置
{"model": "claude-sonnet-4-20250514"}5.7 可以用环境变量吗
export OPENCLAW_MODEL=claude-sonnet-4-202505145.8 不指定模型会怎样
使用默认模型（通常是最新的 Sonnet）。
5.9 混淆了 OpenAI 模型名
不要使用gpt-4o等 OpenAI 模型名。使用claude-*格式。
5.10 排查清单速查表
□ 1. openclaw --list-models 查看 □ 2. 全小写: claude-sonnet-4-20250514 □ 3. 包含日期后缀 □ 4. 不用 claude-2（已弃用） □ 5. 不用 gpt-4o（OpenAI 名） □ 6. 修复 config.json model 字段 □ 7. OPENCLAW_MODEL 环境变量 □ 8. 不指定用默认模型 □ 9. python3 -m json.tool 验证 □ 10. pip install --upgrade 更新6. 总结
- 根本原因：模型不存在最常见原因是拼写错误（35%）和已弃用（25%）
- 最佳实践：使用
openclaw --list-models查看可用模型 - 正确格式：全小写 + 日期后缀，如
claude-sonnet-4-20250514 - 配置修复：在 config.json 中设置正确的模型名
- 最佳实践建议：使用环境变量
OPENCLAW_MODEL或在 config.json 中设置
故障排查流程图
flowchart TD A[模型不存在] --> B[openclaw --list-models] B --> C{找到正确名?} C -->|是| D[使用正确模型名] C -->|否| E[使用默认模型] D --> F[--model claude-sonnet-4-20250514] F --> G[openclaw --print hello 验证] E --> H[openclaw "task" 不指定] H --> G G --> I{成功?} I -->|是| j[✅ 问题解决] I -->|否| K[检查配置] K --> L[cat config.json | grep model] L --> M{配置有 model?} M -->|是| N[修复配置中的模型名] M -->|否| O[添加正确模型名] N --> P[config.json: "model": "claude-sonnet-4-20250514"] O --> P P --> G G --> Q{成功?} Q -->|是| j Q -->|否| R[检查大小写] R --> S[全小写 + 日期后缀] S --> G G --> T{成功?} T -->|是| j T -->|否| U[使用环境变量] U --> V[OPENCLAW_MODEL=claude-sonnet-4-20250514] V --> G G --> W{成功?} W -->|是| j W -->|否| X[更新版本] X --> Y[pip install --upgrade openclaw] Y --> G j --> Z[长期: 正确名 + config + 验证] Z --> AA[✅ 长期方案]
