モデル（Models CLI）

認証プロファイルのローテーション、クールダウン、およびフォールバックとの相互作用については、''/concepts/model-failover'' を参照してください。

ReferenceConceptsModelsPage.intro.p3

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

1. ''プライマリ''モデル（''agents.defaults.model.primary'' または ''agents.defaults.model''）。

2. ''agents.defaults.model.fallbacks'' 内の''フォールバック''（順序通り）。

3. プロバイダー認証フェイルオーバーは、次のプロバイダーモデルに移動する前に

プロバイダー内で行われます。

- ''agents.defaults.models'' is the allowlist/catalog of models OpenClaw can use (plus aliases).

- ''agents.defaults.imageModel'' は、OpenClaw が使用できるモデルの許可リスト/カタログ（エイリアスを含む）です。

- Per-agent defaults can override ''agents.defaults.model'' via ''agents.list[].model'' plus bindings (see ''/concepts/multi-agent'').

- GLM：コーディング/ツール呼び出しに適しています。

- MiniMax：執筆と共鳴に適しています。

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

openclaw onboard

It can set up model + auth for common providers, including ''OpenAI Code (Codex)'' subscription (OAuth) and ''Anthropic'' (API key recommended; also supports ''claude setup-token'').

ReferenceConceptsModelsPage.step03.p3

- ''agents.defaults.model.primary'' および ''agents.defaults.model.fallbacks''

- ''agents.defaults.imageModel.primary'' および ''agents.defaults.imageModel.fallbacks''

- ''agents.defaults.models''（許可リスト + エイリアス + プロバイダーパラメータ）

- ''models.providers''（''models.json'' に書き込まれるカスタムプロバイダー）

Model refs are normalized to lowercase. Provider aliases like ''z.ai/*'' normalize to ''zai/*''.

Provider configuration examples (including OpenCode Zen) live in ''/gateway/configuration''.

ReferenceConceptsModelsPage.step04.p7

ReferenceConceptsModelsPage.step04.p8

If ''agents.defaults.models'' is set, it becomes the ''allowlist'' for ''/model'' and for session overrides. When a user selects a model that isn't in that allowlist,

セッションオーバーライド。ユーザーがその許可リストにないモデルを選択すると、

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

OpenClaw は以下を返します：

- Add the model to ''agents.defaults.models'', or

- Clear the allowlist (remove ''agents.defaults.models''), or

- モデルを ''/model list'' に追加する、または

ReferenceConceptsModelsPage.step05.p7

ReferenceConceptsModelsPage.step05.p8

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

再起動せずに現在のセッションのモデルを切り替えることができます：

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

Notes:

- ''/model''（および ''/model list''）は、コンパクトな番号付きセレクター（モデルファミリー + 利用可能なプロバイダー）です。

- ''/model <#>'' はそのセレクターから選択します。

- ''/model status'' は詳細ビュー（認証候補および設定されたプロバイダーエンドポイント ''baseUrl'' + ''api'' モード）です。

- モデル参照は、''最初の'' ''/'' で分割して解析されます。''/model <ref>'' を入力するときは ''/model <ref>'' を使用します。

- モデル ID 自体に ''/'' が含まれている場合（OpenRouter スタイル）、プロバイダープレフィックスを含める必要があります（例：''/model openrouter/moonshotai/kimi-k2''）。

- If you omit the provider, OpenClaw treats the input as an alias or a model for the ''default provider'' (only works when there is no ''/'' in the model ID).

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'' のショートカットです。

#

デフォルトで設定されたモデルを表示します。便利なフラグ：

- ''--all''：完全なカタログ

- ''--local''：ローカルプロバイダーのみ

- ''--provider <name>''：プロバイダーでフィルタリング

- ''--plain''：1 行に 1 つのモデル

- ''--json'': machine‑readable output

#

Shows the resolved primary model, fallbacks, image model, and an auth overview of configured providers. It also surfaces OAuth expiry status for profiles found in the auth store (warns within 24h by default). ''--plain'' prints only the resolved primary model.

OAuth status is always shown (and included in ''--json'' output). If a configured provider has no credentials, ''models status'' prints a ''Missing auth'' section.

JSON includes ''auth.oauth'' (warn window + profiles) and ''auth.providers'' (effective auth per provider).

Use ''--check'' for automation (exit ''1'' when missing/expired, ''2'' when expiring).

Preferred Anthropic auth is the Claude Code CLI setup-token (run anywhere; paste on the gateway host if needed):

ReferenceConceptsModelsPage.step09.p6

ReferenceConceptsModelsPage.step09.p7

claude setup-token
openclaw models status

''openclaw models scan'' は OpenRouter の''無料モデルカタログ''をチェックし、

オプションでツールとイメージサポートのためにモデルをプローブできます。

- ''--no-probe'': skip live probes (metadata only)

- ''--min-params <b>''：ライブプローブをスキップ（メタデータのみ）

- ''--max-age-days <days>''：最小パラメータサイズ（十億）

- ''--provider <name>''：古いモデルをスキップ

- ''--max-candidates <n>''：プロバイダープレフィックスフィルター

- ''--set-default'': set ''agents.defaults.model.primary'' to the first selection

- ''--set-image''：''agents.defaults.imageModel.primary'' を最初の選択に設定

Probing requires an OpenRouter API key (from auth profiles or ''OPENROUTER_API_KEY''). Without a key, use ''--no-probe'' to list candidates only.

Scan results are ranked by:

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

1. 画像サポート

2. ツールレイテンシ

3. コンテキストサイズ

When run in a TTY, you can select fallbacks interactively. In non‑interactive mode, pass ''--yes'' to accept defaults.

ReferenceConceptsModelsPage.step10.p17

ReferenceConceptsModelsPage.step10.p18

ReferenceConceptsModelsPage.step10.p19

Custom providers in ''models.providers'' are written into ''models.json'' under the agent directory (default ''~/.openclaw/agents/<agentId>/models.json''). This file is merged by default unless ''models.mode'' is set to ''replace''.

ReferenceConceptsModelsPage.step11.p2