OpenClaw モデル設定ガイド：優先順位とフォールバックの最適化

開発を進めていると、複数の AI モデルを使い分けたり、API のエラーに備えてフォールバックを設定したりするのが意外と面倒に感じることがありますよね。設定ファイルを手書きで直すのは時間がかかりますし、ミスも起きやすいものです。

OpenClaw の Models CLI を使えば、こうしたモデル管理をスマートに行えます。認証プロファイルのローテーションやクールダウン、フォールバックとの連携については /concepts/model-failover を、プロバイダーの概要と例については /concepts/model-providers を参照してください。

モデル選択の仕組み

OpenClaw は以下の順序でモデルを選択します。

1. Primary モデル（agents.defaults.model.primary または agents.defaults.model）
2. agents.defaults.model.fallbacks に指定された Fallbacks（記載順）
3. 次のモデルに移る前に、プロバイダー内での Provider auth failover が実行される

関連する設定：

• agents.defaults.models は、OpenClaw が使用できるモデルの許可リスト（カタログ）およびエイリアスです。
• agents.defaults.imageModel は、プライマリモデルが画像を受け入れられない場合にのみ使用されます。
• agents.defaults.imageGenerationModel は、共有の画像生成機能で使用されます。省略された場合、image_generate は互換性のある認証済み画像生成プラグインからプロバイダーのデフォルトを推測します。特定のプロバイダーやモデルを設定する場合は、そのプロバイダーの認証や API key も設定してください。
• エージェントごとのデフォルト設定は、agents.list[].model とバインディングを使用して agents.defaults.model を上書きできます（詳細は /concepts/multi-agent を参照）。

モデルポリシーのクイックガイド

• プライマリモデルには、利用可能な中で最も強力な最新世代のモデルを設定するのがおすすめです。
• コストやレイテンシが重要なタスク、または重要度の低いチャットにはフォールバックを活用しましょう。
• ツールを使用するエージェントや、信頼できない入力（untrusted inputs）を扱う場合は、古いモデルや低スペックなモデルティアは避けてください。

オンボーディング（推奨）

設定ファイルを手動で編集したくない場合は、オンボーディングを実行しましょう。

openclaw onboard

このコマンドで、OpenAI Code (Codex) subscription (OAuth) や Anthropic (API key または claude setup-token) を含む、主要なプロバイダーのモデルと認証をセットアップできます。

設定キーの概要

• agents.defaults.model.primary および agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary および agents.defaults.imageModel.fallbacks
• agents.defaults.imageGenerationModel.primary および agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.models（許可リスト + エイリアス + プロバイダーパラメータ）
• models.providers（models.json に書き込まれるカスタムプロバイダー）

モデルの参照名は小文字に正規化されます。z.ai/* のようなプロバイダーエイリアスは zai/* に正規化されます。

OpenCode を含むプロバイダー設定の例は /providers/opencode にあります。

「Model is not allowed」エラーと応答が止まる理由

agents.defaults.models が設定されている場合、それが /model コマンドやセッションの上書きに対する 許可リスト（allowlist） として機能します。ユーザーがこのリストにないモデルを選択すると、OpenClaw は以下のエラーを返します。

Model "provider/model" is not allowed. Use /model to list available models.

これは通常の応答が生成される前に発生するため、メッセージが「無視された」ように感じることがあります。解決するには、以下のいずれかを行ってください。

• モデルを agents.defaults.models に追加する
• 許可リストをクリアする（agents.defaults.models を削除する）
• /model list からモデルを選択する

許可リストの設定例：

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

チャット内でのモデル切り替え（/model）

再起動することなく、現在のセッションのモデルを切り替えることができます。

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

注意点：

• /model（および /model list）は、モデルファミリーと利用可能なプロバイダーを表示するコンパクトな番号付きピッカーです。
• Discord では、/model と /models を実行すると、プロバイダーとモデルのドロップダウン、および送信ボタンを備えたインタラクティブなピッカーが開きます。
• /model <#> でピッカーから選択できます。
• /model はセッションの選択を即座に更新します。エージェントがアイドル状態なら、次の実行から新しいモデルが使われます。実行中の場合は、現在の処理が終わった後のキューや将来のタスクに適用されます。
• /model status では、認証候補や、設定されている場合はプロバイダーのエンドポイント baseUrl + api モードなどの詳細を確認できます。
• モデルの参照名は、最初の / で分割して解析されます。/model <ref> と入力するときは provider/model の形式を使ってください。
• モデル ID 自体に / が含まれる場合（OpenRouter スタイルなど）は、プロバイダーのプレフィックスを含める必要があります（例：/model openrouter/moonshotai/kimi-k2）。
• プロバイダーを省略した場合、OpenClaw は入力をエイリアス、またはデフォルトプロバイダーのモデルとして扱います（モデル ID に / が含まれていない場合のみ有効）。

コマンドの動作や設定の詳細は Slash commands を確認してください。

CLI コマンド

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models（サブコマンドなし）は models status のショートカットです。

models list

デフォルトで設定済みのモデルを表示します。便利なフラグ：

• --all: フルカタログを表示
• --local: ローカルプロバイダーのみ
• --provider <name>: プロバイダーでフィルタリング
• --plain: 1行に1モデルずつ表示
• --json: 機械読み取り可能な形式で出力

models status

解決されたプライマリモデル、フォールバック、画像モデル、および設定済みプロバイダーの認証概要を表示します。認証ストアにあるプロファイルの OAuth 有効期限も表示されます（デフォルトで24時間以内に切れる場合に警告）。--plain を使うと、解決されたプライマリモデルのみを出力します。 OAuth のステータスは常に表示され、--json 出力にも含まれます。設定済みプロバイダーに認証情報がない場合、models status は Missing auth セクションを表示します。 JSON には auth.oauth（警告ウィンドウとプロファイル）および auth.providers（プロバイダーごとの有効な認証）が含まれます。 自動化には --check を使用してください（認証欠如や期限切れで終了コード 1、期限切れ間近で 2 を返します）。

認証の選択はプロバイダーやアカウントに依存します。常時稼働の Gateway ホストの場合、API key が最も予測しやすいですが、サブスクリプショントークンのフローもサポートされています。

例（Anthropic setup-token）：

claude setup-token
openclaw models status

スキャン機能（OpenRouter の無料モデル）

openclaw models scan は OpenRouter の 無料モデルカタログ を調査し、オプションでツールのサポートや画像サポートをテストできます。

主なフラグ：

• --no-probe: ライブテストをスキップ（メタデータのみ）
• --min-params <b>: 最小パラメータサイズ（10億単位）
• --max-age-days <days>: 古いモデルをスキップ
• --provider <name>: プロバイダープレフィックスでフィルタリング
• --max-candidates <n>: フォールバックリストのサイズ
• --set-default: 最初の選択肢を agents.defaults.model.primary に設定
• --set-image: 最初の画像対応モデルを agents.defaults.imageModel.primary に設定

テストの実行には OpenRouter の API key（認証プロファイルまたは OPENROUTER_API_KEY）が必要です。キーがない場合は --no-probe を使用して候補のリストアップのみを行ってください。

スキャン結果は以下の順でランク付けされます。

1. 画像サポート
2. ツールのレイテンシ
3. コンテキストサイズ
4. パラメータ数

入力情報：

• OpenRouter の /models リスト（:free でフィルタリング）
• 認証プロファイルまたは OPENROUTER_API_KEY からの OpenRouter API key（詳細は /environment）
• オプションのフィルタ：--max-age-days, --min-params, --provider, --max-candidates
• テストの制御：--timeout, --concurrency

TTY で実行している場合は、フォールバックをインタラクティブに選択できます。非インタラクティブモードでは、--yes を渡してデフォルトを承認してください。

モデルレジストリ（models.json）

models.providers にあるカスタムプロバイダーは、エージェントディレクトリ（デフォルトは ~/.openclaw/agents/<agentId>/agent/models.json）の models.json に書き込まれます。models.mode が replace に設定されていない限り、このファイルはデフォルトでマージされます。

プロバイダー ID が一致する場合のマージ優先順位は以下の通りです。

• エージェントの models.json に既に存在する空でない baseUrl が優先されます。
• エージェントの models.json にある空でない apiKey は、そのプロバイダーが現在の設定や認証プロファイルで SecretRef 管理されていない場合にのみ優先されます。
• SecretRef 管理されているプロバイダーの apiKey は、解決されたシークレットを永続化するのではなく、ソースマーカー（環境変数の場合は ENV_VAR_NAME、ファイルや実行リファレンスの場合は secretref-managed）からリフレッシュされます。
• SecretRef 管理されているプロバイダーのヘッダー値は、ソースマーカー（環境変数の場合は secretref-env:ENV_VAR_NAME、ファイルや実行リファレンスの場合は secretref-managed）からリフレッシュされます。
• エージェント側の apiKey や baseUrl が空または欠落している場合は、設定ファイルの models.providers が使用されます。
• その他のプロバイダーフィールドは、設定や正規化されたカタログデータからリフレッシュされます。

マーカーの永続化はソースが優先されます。OpenClaw は、解決された実行時のシークレット値ではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。これは、openclaw agent コマンドなど、OpenClaw が models.json を再生成する際に適用されます。

関連情報

• Model Providers — プロバイダールーティングと認証
• Model Failover — フォールバックチェーン
• Image Generation — 画像モデルの設定
• Configuration Reference — モデル設定キー

AI Setup Assistant

次のステップ

• 環境変数の設定
• スラッシュコマンドの使い方
• マルチエージェント構成