モデル CLI

モデル参照はプロバイダーとモデルを選択します。通常、低レベルのエージェントランタイムは選択しません。たとえば、openai/gpt-5.5 は agents.defaults.agentRuntime.id に応じて、通常の OpenAI プロバイダーパス経由でも、Codex app-server ランタイム経由でも実行できます。Codex ランタイムモードでは、openai/gpt-* 参照は API キー課金を意味しません。認証は Codex アカウントまたは openai-codex 認証プロファイルから取得できます。エージェントランタイムを参照してください。

# モデル選択の仕組み

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

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

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

• 設定済みのデフォルト (agents.defaults.model.primary とエージェント固有のプライマリ) は通常の開始点であり、agents.defaults.model.fallbacks を使用します。
• 自動フォールバック選択は一時的な復旧状態です。modelOverrideSource: "auto" とともに保存されるため、後続のターンでは、既知の問題があるプライマリを最初に試さずにフォールバックチェーンを使い続けられます。
• ユーザーセッション選択は厳密です。/model、モデルピッカー、session_status(model=...)、sessions.patch は modelOverrideSource: "user" を保存します。その選択されたプロバイダー/モデルに到達できない場合、OpenClaw は別の設定済みモデルへフォールスルーせず、見える形で失敗します。
• Cron --model / ペイロード model はジョブごとのプライマリです。ジョブが明示的なペイロード fallbacks を指定しない限り、設定済みフォールバックを引き続き使用します (厳格な cron 実行には fallbacks: [] を使用します)。
• CLI のデフォルトモデルと許可リストのピッカーは、完全な組み込みカタログを読み込む代わりに明示的な models.providers.*.models を一覧表示することで、models.mode: "replace" を尊重します。
• コントロール UI のモデルピッカーは、Gateway に設定済みモデルビューを要求します。存在する場合は agents.defaults.models、それ以外は明示的な models.providers.*.models と使用可能な認証を持つプロバイダーです。完全な組み込みカタログは、models.list の view: "all" や 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 (許可リスト + エイリアス + プロバイダーパラメーター)
• models.providers (models.json に書き込まれるカスタムプロバイダー)

# 安全な許可リスト編集

手動で agents.defaults.models を更新するときは、追加型の書き込みを使用してください。

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

# 「モデルは許可されていません」(返信が止まる理由)

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 です。 許可リストが有効な場合、裸のローカルファイル名や表示名だけでは不十分です。

許可リスト設定例:

{
  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.4
/model status

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

# 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

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

--allboolean

完全なカタログ。認証が設定される前の、同梱プロバイダー所有の静的カタログ行も含まれるため、検出専用ビューで、一致するプロバイダー認証情報を追加するまで利用できないモデルを表示できます。

--localboolean

ローカルプロバイダーのみ。

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

--plainboolean

1 行に 1 つのモデル。

--jsonboolean

機械可読出力。

# models status

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

例（Claude CLI）:

claude auth login
openclaw models status

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

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

--no-probeboolean

ライブプローブをスキップします（メタデータのみ）。

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

agents.defaults.model.primary を最初の選択に設定します。

--set-imageboolean

agents.defaults.imageModel.primary を最初の画像選択に設定します。

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

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

入力:

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

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

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

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

# 関連

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