[Linux系统上不同cacheRetention配置导致提供商冷却] - Model Definitions with CacheRetention Cause Provider Cooldown on Linux
多个具有不同cacheRetention周期的模型定义会在Linux系统上触发model_not_found错误和提供商冷却，而相同配置在macOS上则正常工作。
🔍 症状
主要错误表现
当 OpenClaw 网关初始化配置了持续时间后缀（:5m、:1h）并结合 cacheRetention 参数的模型时，会发生初始化失败。错误表现为：
⚠️ Agent failed before reply: All models failed (3):
anthropic/claude-sonnet-4-6:5m: Provider anthropic is in cooldown (all profiles unavailable) (model_not_found) |
anthropic/claude-opus-4-6: Provider anthropic is in cooldown (all profiles unavailable) (model_not_found) |
anthropic/claude-haiku-4-5:5m: Provider anthropic is in cooldown (all profiles unavailable) (model_not_found)触发问题的配置
以下 openclaw.json 结构会导致失败：
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6:1h",
"fallbacks": [
"anthropic/claude-opus-4-6",
"anthropic/claude-haiku-4-5:5m"
]
},
"models": {
"anthropic/claude-sonnet-4-6:1h": {
"alias": "sonnet-1h",
"params": { "cacheRetention": "long" }
},
"anthropic/claude-haiku-4-5:5m": {
"alias": "haiku-5m",
"params": { "cacheRetention": "short" }
}
}
}
}
}诊断证据
日志条目显示了具体的失败模式：
{"0":"Embedded agent failed before reply: All models failed (3):
anthropic/claude-sonnet-4-6:5m: Provider anthropic is in cooldown...",...}关键观察：
- 不带持续时间后缀的纯模型 ID（例如 `anthropic/claude-opus-4-6`）可以正确解析
- 相同配置在 macOS 上运行无错误
- 网关重启期间没有报告配置语法错误
- 错误在多次代理调用中持续存在
系统环境
- 受影响操作系统： Ubuntu 24.04 (Linux 6.8.0-101-generic)
- 正常工作的操作系统： macOS（相同 OpenClaw 版本）
- 安装方式： 一键安装
- Node 运行时版本： 22.22.0
🧠 根因分析
技术分析
该故障源于 OpenClaw 提供商初始化管道中的平台特定模型解析不一致问题。调查揭示了多层次的因果关系：
1. 带持续时间后缀的模型 ID 解析差异
带有持续时间后缀（:5m、:1h）的模型标识符在提供商注册期间会经历规范化处理。在 Linux 上，规范化例程未能正确地将带后缀的 ID 映射回其基础提供商配置：
Model ID: anthropic/claude-sonnet-4-6:1h ↓ [Linux] 规范化产生: anthropic/claude-sonnet-4-6:1h（未改变） ↓ [Linux] 提供商查找失败 → model_not_found ↓ [macOS] 规范化产生: anthropic/claude-sonnet-4-6（已剥离） ↓ [macOS] 提供商查找成功
2. CacheRetention 参数交互
模型定义中的 cacheRetention 参数会触发次级配置路径。当指定 cacheRetention 时：
- 系统尝试注册带有扩展缓存设置的新提供商配置
- 在 Linux 上，此注册发生在基础提供商完全初始化之前
- 过早的注册在提供商注册表中造成竞态条件
- 结果是部分提供商状态报告为"不可用"
3. 提供商冷却级联
当首次模型解析失败并返回 model_not_found 时，提供商进入冷却状态：
model_not_found → Provider.cooldown = true → 所有配置不可用
这种级联阻止了备用模型尝试解析，即使对于应该工作的基础模型 ID 也不例外。
4. 平台特定文件系统行为
Linux 文件系统在配置加载期间的大小写敏感性和 inode 处理引入了时序变化：
- 在 Linux 上配置文件按顺序加载，而 macOS 上可能是并行加载
- Linux 更严格的文件锁定可能会延迟提供商注册
- npm 全局安装路径（`~/.npm-global`）可能具有不同的权限状态
5. 架构流程图
openclaw.json 加载 ↓ 解析模型定义 ↓ 提供商注册（anthropic） ↓ CacheRetention 参数触发配置扩展 ↓ [Linux] 竞态：配置注册在基础就绪前 → 失败 [macOS] 串行：基础就绪 → 配置扩展 → 成功 ↓ 模型解析尝试 ↓ model_not_found → 冷却
🛠️ 逐步修复
主要解决方案：按顺序重组模型定义
重组配置以按依赖顺序定义模型，避免并行提供商配置注册。
修复前（失败配置）
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6:1h",
"fallbacks": ["anthropic/claude-opus-4-6", "anthropic/claude-haiku-4-5:5m"]
},
"models": {
"anthropic/claude-sonnet-4-6": {
"alias": "sonnet"
},
"anthropic/claude-sonnet-4-6:5m": {
"alias": "sonnet-5m",
"params": { "cacheRetention": "short" }
},
"anthropic/claude-sonnet-4-6:1h": {
"alias": "sonnet-1h",
"params": { "cacheRetention": "long" }
}
}
}
}
}修复后（正常工作配置）
{
"agents": {
"defaults": {
"model": {
"primary": "sonnet-1h",
"fallbacks": ["opus", "haiku-5m"]
},
"models": {
"anthropic/claude-sonnet-4-6": {
"alias": "sonnet"
},
"anthropic/claude-opus-4-6": {
"alias": "opus"
},
"anthropic/claude-haiku-4-5": {
"alias": "haiku"
}
}
}
}
}注意： 在 primary 和 fallbacks 中使用 alias 引用，让 OpenClaw 先解析基础提供商。
替代修复方案：提供商级 CacheRetention
在提供商级别而非单个模型定义中应用 cacheRetention：
{
"providers": {
"anthropic": {
"config": {
"cacheRetention": "long"
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "sonnet",
"fallbacks": ["opus", "haiku"]
},
"models": {
"anthropic/claude-sonnet-4-6": { "alias": "sonnet" },
"anthropic/claude-opus-4-6": { "alias": "opus" },
"anthropic/claude-haiku-4-5": { "alias": "haiku" }
}
}
}
}基于 CLI 的修复步骤
步骤 1：备份现有配置
cp ~/.config/openclaw/openclaw.json ~/.config/openclaw/openclaw.json.bak步骤 2：停止 OpenClaw 网关
openclaw gateway stop步骤 3：清除 Linux 上的提供商缓存
rm -rf ~/.npm-global/lib/node_modules/openclaw/dist/.provider-cache
rm -rf ~/.cache/openclaw/providers步骤 4：应用修正后的配置（使用上面的 JSON 结构）
步骤 5：使用详细日志重启
openclaw gateway start --log-level debug
openclaw logs --follow步骤 6：验证提供商初始化
openclaw provider list预期输出应显示 anthropic 提供商状态为 active，无冷却状态。
🧪 验证
验证命令和预期输出
测试 1：提供商状态检查
openclaw provider list预期输出：
PROVIDER STATUS MODELS
anthropic active 3
google active 2
...失败指示： 提供商显示 cooldown 或 unavailable 状态。
测试 2：模型解析测试
openclaw model resolve sonnet预期输出：
anthropic/claude-sonnet-4-6测试 3：代理调用测试
openclaw chat --model sonnet --prompt "Hello"预期输出：
✓ Response received from anthropic/claude-sonnet-4-6
...失败指示： model_not_found 错误或提供商冷却消息。
测试 4：备用链测试
openclaw chat --model sonnet-1h --prompt "Test" 2>&1预期输出： 成功响应，无冷却错误。
测试 5：日志验证
openclaw logs --filter "model_not_found"预期输出： 无返回条目。
失败指示： 显示 Provider anthropic is in cooldown 的条目。
跨平台验证矩阵
| 平台 | 模型 ID 类型 | CacheRetention | 预期结果 |
|---|---|---|---|
| macOS | claude-sonnet-4-6:1h | 是 | ✓ 通过 |
| Linux | claude-sonnet-4-6:1h | 是 | ✗ 失败（修复前） |
| Linux | sonnet（别名） | 否 | ✓ 通过 |
| Linux | sonnet（别名） | 提供商级别 | ✓ 通过 |
回归预防测试
应用修复后，验证纯模型 ID 继续正常工作：
openclaw model list --provider anthropic预期：列出所有不带持续时间后缀的基础模型。
⚠️ 常见陷阱
环境特定陷阱
- npm 全局路径权限： 在 Linux 上，npm 全局目录（`~/.npm-global`）可能具有不同的所有权。修复方法：
sudo chown -R $(whoami) ~/.npm-global/lib/node_modules/openclaw - 配置文件位置差异： Linux 发行版在 XDG_CONFIG_HOME 处理上有所不同。验证实际配置路径：
echo $XDG_CONFIG_HOME # 在 Ubuntu 上通常为 ~/.config ls -la ~/.config/openclaw/ - Systemd 服务用户： 如果作为 systemd 服务运行，服务可能使用不同用户的配置目录。检查方法：
systemctl show openclaw | grep User
配置错误
- 重复别名定义： 对多个模型使用相同的别名会导致解析歧义：
// 错误 "models": { "claude-sonnet-4-6": { "alias": "sonnet" }, "claude-opus-4-6": { "alias": "sonnet" } // 重复别名 } - CacheRetention 值验证： 只有 `short`、`medium` 和 `long` 是有效值。无效值在 Linux 上静默失败，但在 macOS 上可能正常工作：
// 有效值 "cacheRetention": "short" // 5 分钟 "cacheRetention": "medium" // 1 小时 "cacheRetention": "long" // 24 小时 - 模型 ID 大小写： 模型 ID 区分大小写。确保精确的提供商名称匹配：
// 使用小写提供商 "anthropic/claude-sonnet-4-6" // ✓ 正确 "Anthropic/claude-sonnet-4-6" // ✗ 在 Linux 上会失败
Docker 和容器特定问题
- 卷挂载权限： 如果在 Docker 中运行，确保配置目录以正确的 uid/gid 挂载：
docker run -v /home/user/.config/openclaw:/root/.config/openclaw:ro ... - 网络命名空间隔离： 提供商 API 调用在容器内部可能表现不同。验证网络连接：
docker exec <container> curl -I https://api.anthropic.com
macOS 特定行为
- 不区分大小写的文件系统： macOS HFS+/APFS 不区分大小写，这掩盖了在 Linux 上会暴露的大小写敏感性问题。
- 路径解析差异： macOS 解析符号链接的方式不同。验证实际配置路径：
readlink -f ~/.config/openclaw/openclaw.json
时序边缘情况
- 提供商 API 速率限制： 在首次启动时，多个模型注册可能会触发速率限制。添加启动延迟：
openclaw gateway start && sleep 5 && openclaw chat --model sonnet - 过期的提供商缓存： 先前失败的状态会保存在缓存中。在 Linux 上更改配置后务必清除缓存。
🔗 相关错误
直接相关错误
- `model_not_found` — 表示模型标识符无法解析到已注册的提供商。Linux 解析差异的主要症状。
- `Provider anthropic is in cooldown (all profiles unavailable)` — 在首次 `model_not_found` 之后阻止后续模型尝试的级联失败状态。
- `all profiles unavailable` — 表示提供商注册完成但没有成功注册任何配置。与 cacheRetention 竞态条件相关。
上下文相关错误
- `Provider authentication failed` — 如果提供商冷却阻止了凭证验证尝试，可能会发生。
- `Configuration parse error` — 如果持续时间后缀解析遇到格式错误的 JSON（例如，尾随空格），可能会出现。
- `Alias resolution failed` — 在基础模型注册之前使用别名引用时可能发生（取决于配置顺序）。
- `Rate limit exceeded` — 与多个 cacheRetention 定义触发的提供商注册突发相关。
历史问题模式
- 问题：带有持续时间后缀的模型别名 — 早期版本在 `model-id:duration` 别名格式上有已知问题。确保安装了 OpenClaw 2026.2.25+ 版本。
- 问题：Linux 提供商初始化时序 — 异步提供商注册管道中的已知竞态条件，由于不同的调度行为而影响 Linux。
- 问题：XDG_CONFIG_HOME 未被尊重 — 某些 Linux 发行版不正确地遵循 XDG 路径，导致配置加载失败，表现为模型解析错误。
诊断参考命令
# 完整系统诊断
openclaw doctor
# 提供商调试输出
openclaw provider debug anthropic
# 配置验证
openclaw config validate
# 清除所有缓存并重启
openclaw gateway stop && rm -rf ~/.cache/openclaw && openclaw gateway start