モデルCLI

認証プロファイルのローテーション、クールダウン、フォールバックとの連携については/concepts/model-failoverを参照してください。 プロバイダーの概要と例: /concepts/model-providers

モデル選択の仕組み

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

  1. プライマリモデル（agents.defaults.model.primary または agents.defaults.model）。
  2. agents.defaults.model.fallbacks 内のフォールバック（順番に）。
  3. 次のモデルに移る前に、プロバイダー内でプロバイダー認証フェイルオーバーが実行されます。

関連:

  • agents.defaults.models はOpenClawが使用できるモデルの許可リスト/カタログです（エイリアスも含む）。
  • agents.defaults.imageModel はプライマリモデルが画像を受け付けられない場合のみ使用されます。
  • エージェントごとのデフォルトは agents.list[].model とバインディングで agents.defaults.model をオーバーライドできます（/concepts/multi-agentを参照）。

モデル選定の基本方針

  • プライマリには利用可能な最新世代の最も強力なモデルを設定。
  • フォールバックにはコスト/レイテンシ重視のタスクや低リスクなチャット用のモデルを使用。
  • ツール対応エージェントや信頼されていない入力には、旧世代/低性能のモデルは避けてください。

セットアップウィザード（推奨）

設定を手動編集したくない場合は、オンボーディングウィザードを実行:

openclaw onboard

OpenAI Code（Codex）サブスクリプション（OAuth）やAnthropic（APIキーまたは claude setup-token）を含む一般的なプロバイダーのモデル＋認証設定が可能です。

設定キー（概要）

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

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

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

「Model is not allowed」（応答が止まる原因）

agents.defaults.models が設定されている場合、/model やセッションオーバーライドの許可リストとして機能します。許可リストにないモデルを選択すると、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-5" },
    models: {
      "anthropic/claude-sonnet-4-5": { 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 status は詳細ビュー（認証候補と、設定されている場合はプロバイダーエンドポイントの baseUrl ＋ api モード）。
  • モデル参照は最初の / で分割してパースされます。/model <ref> では provider/model 形式を使用してください。
  • モデルID自体に / が含まれる場合（OpenRouterスタイル）、プロバイダープレフィックスを含める必要があります（例: /model openrouter/moonshotai/kimi-k2）。
  • プロバイダーを省略した場合、OpenClawは入力をエイリアスまたはデフォルトプロバイダーのモデルとして扱います（モデルIDに / が含まれない場合のみ有効）。

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

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キーが最も予測可能です。サブスクリプショントークンフローもサポートされています。

例（Anthropic setup-token）:

claude setup-token
openclaw models status

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

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

主なフラグ:

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

プローブにはOpenRouter APIキー（認証プロファイルまたは OPENROUTER_API_KEY）が必要。キーなしの場合は --no-probe で候補のみを一覧表示。

スキャン結果のランキング基準:

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

入力

  • OpenRouter /models リスト（:free でフィルタ）
  • 認証プロファイルまたは OPENROUTER_API_KEY からのOpenRouter APIキーが必要（/environmentを参照）
  • オプションフィルタ: --max-age-days、--min-params、--provider、--max-candidates
  • プローブ制御: --timeout、--concurrency

TTYで実行する場合、フォールバックをインタラクティブに選択できます。非インタラクティブモードでは --yes でデフォルトを受け入れます。

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

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

マージモードのマッチングプロバイダーIDに対する優先順位:

  • エージェント models.json に既存の空でない baseUrl が優先。
  • エージェント models.json の空でない apiKey は、そのプロバイダーが現在の設定/認証プロファイルコンテキストでSecretRef管理されていない場合のみ優先。
  • SecretRef管理のプロバイダー apiKey 値は、解決されたシークレットを永続化するのではなく、ソースマーカー（env参照の場合は ENV_VAR_NAME、file/exec参照の場合は secretref-managed）から更新。
  • SecretRef管理のプロバイダーヘッダー値は、ソースマーカー（env参照の場合は secretref-env:ENV_VAR_NAME、file/exec参照の場合は secretref-managed）から更新。
  • エージェント apiKey/baseUrl が空または欠落の場合、設定の models.providers にフォールバック。
  • その他のプロバイダーフィールドは設定と正規化されたカタログデータから更新。

マーカーの永続化はソース権威です: OpenClawは解決されたランタイムシークレット値からではなく、アクティブなソース設定スナップショット（解決前）からマーカーを書き込みます。 これは openclaw agent のようなコマンド駆動パスを含め、OpenClawが models.json を再生成するたびに適用されます。

arrow_back
前へ
Models
次へ
Model Providers
arrow_forward