モデル CLI

モデル参照はプロバイダーとモデルを選択します。通常、低レベルのエージェントランタイムは選択しません。OpenAI エージェント参照は主な例外です。openai/gpt-5.5 は、公式 OpenAI プロバイダー上でデフォルトでは Codex app-server ランタイムを通じて実行されます。サブスクリプション Copilot 参照（github-copilot/*）は、さらに外部 GitHub Copilot エージェントランタイム Plugin にオプトインできます。このパスは明示的なままです（auto フォールバックなし）。明示的なランタイムオーバーライドは、エージェント全体やセッションではなく、プロバイダー/モデルポリシーに属します。Codex ランタイムモードでは、openai/gpt-* 参照は API キー課金を意味しません。認証は Codex アカウントまたは openai OAuth プロファイルから取得できます。エージェントランタイム と GitHub Copilot エージェントランタイム を参照してください。

モデル選択の仕組み

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

選択元とフォールバック動作

同じ provider/model でも、どこから来たかによって意味が異なる場合があります。

• 設定済みデフォルト（agents.defaults.model.primary とエージェント固有のプライマリ）は通常の開始点であり、agents.defaults.model.fallbacks を使用します。
• 自動フォールバック選択は一時的な復旧状態です。modelOverrideSource: "auto" として保存されるため、後続のターンでは既知の不良プライマリを毎回プローブせずにフォールバックチェーンを使い続けることができます。OpenClaw は元のプライマリを定期的に再度プローブし、復旧すると自動選択をクリアし、フォールバック/復旧の遷移を状態変更ごとに一度通知します。
• ユーザーセッション選択は厳密です。/model、モデルピッカー、session_status(model=...)、および sessions.patch は modelOverrideSource: "user" を保存します。その選択されたプロバイダー/モデルに到達できない場合、OpenClaw は別の設定済みモデルにフォールスルーするのではなく、目に見える形で失敗します。
• agents.defaults.model.primary を変更しても、既存のセッション選択は書き換えられません。ステータスに This session is pinned to X; config primary Y will apply to new/unpinned sessions. と表示される場合は、/model default で現在のセッション選択をクリアし、設定済みプライマリを再び継承させてください。
• Cron --model / ペイロード model はジョブごとのプライマリです。ジョブが明示的なペイロード fallbacks を指定しない限り、設定済みフォールバックを引き続き使用します（厳密な cron 実行には fallbacks: [] を使用します）。
• CLI のデフォルトモデルおよび許可リストピッカーは、完全な組み込みカタログを読み込む代わりに明示的な models.providers.*.models を一覧表示することで、models.mode: "replace" を尊重します。
• Control UI のモデルピッカーは、Gateway に設定済みモデルビューを問い合わせます。存在する場合は agents.defaults.models（プロバイダー全体の provider/* エントリを含む）、それ以外の場合は明示的な models.providers.*.models と利用可能な認証を持つプロバイダーです。完全な組み込みカタログは、view: "all" を指定した models.list や openclaw models list --all などの明示的な閲覧ビュー用に予約されています。

簡単なモデルポリシー

• 利用可能な最も強力な最新世代モデルをプライマリに設定します。
• コスト/レイテンシーに敏感なタスクや低リスクのチャットにはフォールバックを使用します。
• ツール有効エージェントや信頼できない入力では、古い/弱いモデル階層を避けてください。

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

設定を手動編集したくない場合は、オンボーディングを実行します。

openclaw onboard

これは、OpenAI Code (Codex) サブスクリプション（OAuth）や Anthropic（API キーまたは Claude CLI）を含む一般的なプロバイダーのモデル + 認証を設定できます。

設定キー（概要）

• agents.defaults.model.primary と agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary と agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary と agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary と agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary と agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models（許可リスト + エイリアス + プロバイダーパラメーター + provider/* 動的プロバイダーエントリ）
• models.providers（models.json に書き込まれるカスタムプロバイダー）

安全な許可リスト編集

agents.defaults.models を手動で更新する場合は、追加書き込みを使用します。

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

「Model is not allowed」（および返信が止まる理由）

agents.defaults.models が設定されている場合、それは /model とセッションオーバーライドの許可リストになります。ユーザーがその許可リストにないモデルを選択すると、OpenClaw は次を返します。

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

拒否されたコマンドに /model openai/gpt-5.5 --runtime codex のようなランタイムオーバーライドが含まれていた場合は、まず許可リストを修正してから、同じ /model ... --runtime ... コマンドを再試行してください。ネイティブ Codex 実行の場合でも、選択されるモデルは openai/gpt-5.5 のままです。codex ランタイムはハーネスを選択し、Codex 認証を別途使用します。

ローカル/GGUF モデルの場合は、完全なプロバイダー接頭辞付き参照を許可リストに保存します。 たとえば ollama/gemma4:26b、lmstudio/Gemma4-26b-a4-it-gguf、または openclaw models list --provider <provider> に表示される正確な provider/model です。 許可リストが有効な場合、素のローカルファイル名や表示名だけでは不十分です。

すべてのモデルを手動で列挙せずにプロバイダーを制限したい場合は、 provider/* エントリを agents.defaults.models に追加します。

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

このポリシーでは、/model、/models、モデルピッカーは、それらのプロバイダーで検出された カタログのみを表示します。選択されたプロバイダーの新しいモデルは、 許可リストを編集せずに表示できます。別のプロバイダーから特定のモデルを 1 つ必要とする場合は、正確な provider/model エントリを provider/* エントリと混在させることができます。

許可リスト設定の例:

{  agents: {    defaults: {      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.4/model default/model status

完全なコマンド動作/設定: スラッシュコマンド。

CLI コマンド

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

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

models list

デフォルトでは、設定済み/認証で利用可能なモデルを表示します。便利なフラグ:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> プロバイダー ID でフィルターします。例: moonshot。対話型ピッカーの表示ラベルは受け付けません。

models status

解決済みのプライマリモデル、フォールバック、画像モデル、設定済みプロバイダーの認証概要を表示します。また、認証ストア内で見つかったプロファイルの OAuth 有効期限ステータスも表示します（デフォルトでは 24 時間以内に警告）。--plain は解決済みのプライマリモデルのみを出力します。

例（Claude CLI）:

claude auth loginopenclaw models status

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

openclaw models scan は OpenRouter の無料モデルカタログを検査し、任意でツールと画像サポートについてモデルをプローブできます。

スキャン結果は次でランク付けされます。

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

入力:

• OpenRouter /models リスト（:free でフィルター）
• ライブプローブには、認証プロファイルまたは OPENROUTER_API_KEY からの OpenRouter API キーが必要です（環境変数 を参照）
• 任意のフィルター: --max-age-days、--min-params、--provider、--max-candidates
• リクエスト/プローブ制御: --timeout、--concurrency

ライブプローブを TTY で実行すると、フォールバックを対話的に選択できます。非対話モードでは、デフォルトを受け入れるために --yes を渡します。メタデータのみの結果は情報提供用です。--set-default と --set-image にはライブプローブが必要です。これは、OpenClaw が使用不能なキーなし OpenRouter モデルを設定しないようにするためです。

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

models.providers のカスタムプロバイダーは、エージェントディレクトリ配下の models.json（デフォルトは ~/.openclaw/agents/<agentId>/agent/models.json）に書き込まれます。プロバイダー Plugin カタログは、エージェントの Plugin 状態配下に生成された Plugin 所有のカタログシャードとして保存され、自動的に読み込まれます。このファイルは、models.mode が replace に設定されていない限り、デフォルトでマージされます。

関連

• エージェントランタイム — OpenClaw、Codex、およびその他のエージェントループランタイム
• 設定リファレンス — モデル設定キー
• 画像生成 — 画像モデル設定
• モデルフェイルオーバー — フォールバックチェーン
• モデルプロバイダー — プロバイダールーティングと認証
• 音楽生成 — 音楽モデル設定
• 動画生成 — 動画モデル設定