[LinuxでCacheRetention付きモデル定義がProvider Cooldownの原因となる] - Model Definitions with CacheRetention Cause Provider Cooldown on Linux

主なエラーの現れ方

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ではエラーなく動作する
• ゲートウェイ再起動時に設定構文エラーは報告されない
• エラーは複数のエージェント呼び出しで持続する

システムコンテキスト

• 影響を受けるOS： Ubuntu 24.04 (Linux 6.8.0-101-generic)
• 動作するOS： macOS（同じOpenClawバージョン）
• インストール方法： ワンライナーインストール
• Nodeランタイム： 22.22.0

技術的分析

この失敗は、OpenClawのプロバイダ初期化パイプラインにおけるプラットフォーム固有のモデル解決の不整合に起因します。調査により、複数の層にわたる原因が明らかになりました：

1. 期間サフィックス付きモデルID解析の相違

期間サフィックス付き（:5m、:1h）のモデル識別子は、プロバイダ登録時に正規化プロセスを経ます。Linuxでは、正規化ルーチンがサフィックス付きIDをその基本プロバイダ設定に正しくマッピングすることに失敗します：

モデル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が引き続き機能することを確認します：

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