プロバイダー設定

すべてのモデルプロバイダーは [providers.models.<type>.<alias>] に配置されます。<type> は正規のファミリースロットです（各スロットとそのエンドポイントについてはカタログを参照してください）。<alias> はオペレーターが割り当てるインスタンス名で、任意のわかりやすい名前を選択できます（home、work、cn、gpt5 など）。

最小限の動作例

クリーンに読み込まれる最小構成には、4つのセクションヘッダーがあります。プロバイダーエントリ、それを参照するエージェント、そしてエージェントがゲートとして使用するリスクプロファイルです。これらはゲートウェイ、zerocode、または zeroclaw config set を通じて設定します。全フィールドのインデックスについては設定リファレンスを参照してください。

フィールドリファレンス: プロバイダーエントリ

ほぼすべてのファミリーは、ModelProviderConfig からの共有フィールドも取ります:

api_key: bearer 認証またはサブスクリプション形式の API キーを使用するプロバイダー向けの認証情報。
uri: エンドポイント全体のオーバーライド。未設定のままにすると、ファミリのエンドポイントリゾルバが使用されます。
model: プロバイダーに送信されるモデル識別子。
temperature: オプションのサンプリング温度。
timeout_secs: HTTPリクエストのタイムアウト（秒単位）。
max_tokens: レスポンス長の上限（オプション）。
extra_headers: カスタムゲートウェイや認証ブリッジ用の追加HTTPヘッダー。
fallback_models: 同じプロバイダーエイリアス上の代替モデルID。
fallback: このエイリアスが失敗した後に試す、ドット区切りの他のプロバイダーエイリアスの順序付きリスト。
wire_api、native_tools、provider_extra、think、chat_template_kwargs: 高度なプロトコルおよびリクエストボディのオーバーライド。
vision: プロバイダーの画像入力（vision）機能を上書きします。未設定のままにすると、ファミリーの組み込みデフォルトが使用されます。vision対応ファミリーで提供されるテキスト専用モデル（例: llama.cpp の背後にあるテキストモデル）の場合は false を設定すると、画像メッセージがエラーになる代わりに、設定済みの [multimodal] vision_model_provider にルーティングされます。強制的に有効にするには true を設定します。
tool_result_image_policy: 対応する chat-completions プロバイダーに送信されるネイティブな role = "tool" 結果に含まれる画像マーカーの処理。デフォルトは "image_url" です。"omit" に設定すると、画像 URI/base64 ペイロードを削除し、固定の通知を追加します。直接送信されるユーザー画像や OpenAI Responses プロバイダーには影響しません。
tls_ca_cert_path: このプロバイダーへの TLS 接続に使用する PEM エンコードされた CA 証明書への絶対パス（プロバイダーごとの信頼のオーバーライドで、ゲートウェイの TLS ca_cert_path とは別のもの）。~ などのシェル展開は行われません。システムの信頼ストアを使用する場合は未設定のままにしてください。

ファミリー固有のエントリは、これらの共有フィールドの上に独自の型付きフィールドを追加します。

フィールド解決順序

ほとんどのファミリーでは、URL は次の順序で解決されます:

演算子による上書き: エイリアスエントリの uri フィールド（設定されている場合）。
Family endpoint: ファミリーの *Endpoint 列挙型が URL を提供します（例: OpenAIEndpoint::Default -> https://api.openai.com/v1）。マルチリージョンのファミリーでは、エイリアスエントリに endpoint フィールドがあり、バリアントを選択します（例: Moonshot の場合は endpoint = "cn"）。
テンプレート化されたファミリ: Azure は型付き入力（resource、deployment、api_version）を受け取り、それらをファミリの URI テンプレートに代入します。フィールドが欠落している場合は、実行時にエラーになります。

BedrockはAWSクレデンシャルチェーン（AWS_REGION、AWS_DEFAULT_REGION、またはアクティブなcredential_processやIMDSプロファイルのregion）を通じて解決された署名リージョンからリクエスト時にエンドポイントのホスト名が構築されるという例外があります。uriエイリアスフィールドおよびスキーマレベルのproviders.models.bedrock.<alias>.regionフィールドは、現在の実装では効果がありません。

ファミリースロット

すべてのスロット、そのデフォルトエンドポイント、ローカルで実行されるかどうかは、Catalog に記載されています。ベンダーごとに正規のキーが1つあります。同義語はありません。

認証情報

サポートされている認証情報の入力および保存形式：

エイリアスエントリ内のインライン api_key = "..."（開発用には問題ありませんが、チェックインされた設定ではリスクがあります）。
1Password 参照: シークレットフィールドに op://vault/item/field を設定します。ZeroClaw は参照を config に保持し、実行時に op read で解決するため、1Password CLI がインストールされサインインされている必要があります。
設定レベルのシークレットストア: ローカルのキーファイルを使用して ~/.zeroclaw/secrets で暗号化されます。
汎用的な環境変数オーバーライド: ZEROCLAW_providers__models__<type>__<alias>__api_key=... は起動時に providers.models.<type>.<alias>.api_key を設定します。完全な文法については環境変数を参照してください。

スキーマミラーの環境変数オーバーライドは起動時に優先されます。これらはディスク上に保存されたインライン値、暗号化された値、または op:// 値を書き換えることなく、そのプロセスのメモリ内の認証情報を置き換えます。

zeroclaw quickstart はデフォルトで認証情報をシークレットストアに書き込みます。コミットする設定ファイルには、インラインのキーを含めないでください。シェルですでにエクスポートしているエコシステム標準の名前（$ANTHROPIC_API_KEY、$OPENROUTER_API_KEY など）については、env-vars リファレンスに、スキーマミラー名を既存の値に向ける1行の bash 展開が示されています。

OAuth とサブスクリプション認証

いくつかのプロバイダーは、生のAPIキーの代わりにOAuthまたはサブスクリプション形式のトークンを受け付けます。ベンダー独自のダッシュボードまたはCLIフローからトークンを取得し、APIキーと同じ方法でエイリアスエントリに設定してください:

Anthropic / Claude: Claude Max 用の claude setup-token で生成された Console API キーとトークンは、[providers.models.anthropic.<alias>] の api_key に設定します。クイックスタートでは api_key または setup_token を選択してください。保存されたプロバイダーエントリは、引き続き正規の anthropic スロットです。
OpenAI Codex サブスクリプション: zeroclaw auth login --model-provider openai-codex を実行する（または --import ~/.codex/auth.json で既存の Codex CLI ログインをインポートする）。次に [providers.models.openai.<alias>] で requires_openai_auth = true を設定し、api_key は未設定のままにする。ランタイムは ZeroClaw に保存された openai-codex 認証プロファイルを読み取ります。
Gemini CLI: [providers.models.gemini_cli.<alias>] は gemini CLI を呼び出します。CLI 自体の認証フローを使用してください。
Grok Build CLI: [providers.models.grok_cli.<alias>] は、文書化された grok agent stdio ACP インターフェース経由で外部コマンドを実行します。組み立てられたプロンプトは stdin 上の JSON-RPC であり、argv やプロンプトファイル経由ではありません。認証にはデフォルトで CLI のログインキャッシュが使用されます。API キー認証では、デーモン環境に XAI_API_KEY をエクスポートし、エイリアスに env_passthrough = ["XAI_API_KEY"] を明示的に追加します。型付きエイリアス api_key は引き続きサポートされません。存在する絶対パスの working_directory が必要で、子プロセスの cwd と ACP セッション境界の両方を定義します。子プロセスの環境は起動前にクリアされ、env_passthrough のデフォルトは空です。他のプロバイダー所有の XAI_* 名とすべての GROK_* 名は拒否されます。ZeroClaw のデフォルトは --sandbox strict、--permission-mode dontAsk、空の組み込みツールセット、およびフェイルクローズの ACP 権限応答です。extra_args は、これらの制御を緩和するための明示的なエイリアスごとのオプトインです。バイパスフラグ --always-approve、--dangerously-skip-permissions、--yolo、および --permission-mode=bypassPermissions により、ヘッドレス ACP クライアントは allow_once を選択します。それ以外の権限モードでは引き続き reject_once が選択されます。ACP のトランスポート、モデル、セッション、cwd に関するフラグに加え、位置引数と短形式の引数は予約されています。値を受け取る未知のロングオプションには --flag=value を使用します。エイリアスの vision = true は、ZeroClaw による ACP 画像ブロックの送信をオプトインするだけです。Grok は 0.2.118 まで promptCapabilities.image = false を引き続き通知し、画像コンテンツを確実には使用しません。本番環境では未設定のままにしてください。ACP ビジョン / 画像入力を参照してください。
Qwen / MiniMax: エイリアスエントリに auth_mode = "o_auth" を設定し、関連する oauth_* フィールドも設定します（env-vars → OAuth と CLI パスのフィールドを参照）。

コンテナフレンドリーなオーバーライド

ZeroClaw をコンテナ内で実行し、プロバイダーがホスト上にある場合（例: Ollama）は、uri をホストから到達可能なアドレスに設定してください。汎用の環境変数オーバーライド機構（ZEROCLAW_<dotted_path_with_double_underscores>=<value>）を使えば、設定を編集せずに実行時に同じフィールドを設定できます:

sh

ZEROCLAW_providers__models__ollama__home__uri=http://ollama:11434 zeroclaw agent -a assistant

__ はパス区切り文字です。上記の例では providers.models.ollama.home.uri を設定しています。完全な文法については環境変数を参照してください。

モデルごとのビジョン機能

vision は、あるプロバイダーファミリーがマルチモーダルモデルとテキスト専用モデルの両方に対応できる場合に使用します。この値はプロバイダーエイリアスに属するため、ルーティングおよびフォールバックのパスでは、そのエイリアスのエンドポイント、認証情報、モデルとともに解決されます。

[providers.models.openai.vision]
model = "gpt-4o"
wire_api = "responses"
vision = true

[providers.models.llamacpp.text]
model = "qwen3-4b"
vision = false

vision を未設定のままにすると、プロバイダーファミリーの組み込みデフォルトが保持されます。OpenAI Responses のエイリアスでは、画像入力を受け付けるモデルに対して vision = true を設定してください。このオプトインにより、テキストのみの Responses モデルが誤って画像ペイロードを受け取ることを防ぎます。

vision = true の設定は、選択したエイリアスが画像入力を受け付けるという、オペレーターによる明示的なアサーションです。これにより画像のルーティングが変わります。ZeroClaw は画像添付をテキスト専用として扱ったり multimodal.vision_model_provider にルーティングしたりせず、そのエイリアスに保持します。テスト済みのプロバイダーとモデルの組み合わせに対してのみ設定してください。grok_cli では、同じフィールドは ZeroClaw が ACP 画像ブロックを 送信するかどうかだけを制御します。Grok の promptCapabilities.image のアドバタイズ内容を書き換えるものではなく（0.2.118 までは引き続き false）、CLI が画像を確実に説明するようになるわけでもありません。ACP ビジョン / 画像入力を参照してください。

[multimodal] vision_model_provider がドット区切りのプロバイダーエイリアスを指定している場合、その model が自動的に使用されます。明示的な [multimodal] vision_model はエイリアスのモデルより優先されます。どちらも設定されていない場合は、後方互換性のためにプライマリターンモデルが使用されます。

ネイティブ思考表示 (Anthropic)

agent.thinking.display は、ネイティブ思考が有効な場合（agent.thinking.native_thinking = true）に Anthropic の拡張思考をどのように配信するかを制御します。指定可能な値:

off（デフォルト）: display フィールドは送信されません。リクエストは以前の ZeroClaw バージョンとバイト単位で同一で、推論リクエストでは非ストリーミングのフォールバックが使用されます。
omitted: Anthropic はレスポンスから思考テキストを省略します。ブロックは署名のみ（空の thinking、必須の署名）で届き、表示される推論を最小限に抑えながらリプレイを完全な状態に保ちます。
updates: リクエストには thinking-display-updates-2026-08-18 ベータが含まれ、ストリーミング応答パスが使用されます。モデルの処理中、読みやすい思考の進行状況がリアルタイムで表示されます。署名付き推論ペイロードは履歴の再生用に別途保持され、表示されることはありません。
summarized: 同じストリーミング動作で、思考の要約をリクエストします。

[agent.thinking]
native_thinking = true
display = "updates"

この設定には、thinking-display-updates ベータ版に登録された Anthropic アカウントが必要です。登録されていない場合、API はリクエストを拒否します。以前のワイヤー動作に戻すには、display = “off” を設定するか、フィールドを削除してください。

ファミリーごとの調整: 実例

Ollama

Ollama はデフォルトでローカルエンドポイントを使用するため、ローカルエイリアスにはモデル名のみが必要です:

[providers.models.ollama.local]
model = "llama3.1"

ZeroClaw が Ollama と同じホスト上で実行されていない場合は uri を設定してください:

[providers.models.ollama.host]
model = "llama3.1"
uri = "http://host.docker.internal:11434"

Ollama 固有のオプションフィールドは num_ctx、num_predict、および temperature_override です。

Azure OpenAI

Azure OpenAI は、入力された Azure フィールドからエンドポイントを計算します:

[providers.models.azure.work]
api_key = "op://platform/azure-openai/api-key"
model = "gpt-4o"
resource = "example-resource"
deployment = "gpt-4o-prod"
api_version = "2024-10-21"

resource、deployment、api_version の各値はこの型付き設定に格納されており、Azure 固有の環境変数からは読み込まれません。計算されたエンドポイントを完全に上書きする必要がある場合にのみ uri を使用してください。

Amazon Bedrock

Bedrock ではモデルを指定したエイリアスが必要です。エンドポイントのリージョンは現在、Bedrock の認証環境/プロファイルパスから取得されます。

[providers.models.bedrock.work]
model = "anthropic.claude-sonnet-4-6"

Bedrock プロバイダーは、crates/zeroclaw-providers/src/bedrock.rs に実装されている認証情報パスを使用します。

Bedrock エイリアスの api_key または BEDROCK_API_KEY は、Bedrock のベアラートークン認証を使用し、SigV4 の認証情報より優先されます。
AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を使用すると SigV4 が利用されます。AWS_SESSION_TOKEN はオプションです。AWS_REGION または AWS_DEFAULT_REGION で署名リージョンを選択し、指定がない場合は us-east-1 にフォールバックします。
~/.aws/config のアクティブプロファイル、または AWS_CONFIG_FILE に設定された credential_process は SigV4 を使用します。AWS_PROFILE はプロファイルを選択し、デフォルトは default です。
EC2 IMDSv2 インスタンス認証情報は、最後の SigV4 フォールバックです。

設定スキーマには providers.models.bedrock.<alias>.region フィールドも定義されていますが、現在の実装ではこのフィールドは読み込まれません。エンドポイントのリージョンは、上記のとおり常に AWS 認証情報チェーン（環境変数、credential_process、または IMDS）から解決されます。

現在の Bedrock 実装では、~/.aws/credentials にある通常の静的プロファイルは読み込まれません。~/.zeroclaw/secrets には、エイリアス api_key などの ZeroClaw 設定シークレットのみが保存され、プロバイダー向けに AWS_* 変数をエクスポートすることはありません。

実装済みのプロファイルパス経由で AWS CLI プロファイルを再利用するには、~/.aws/config に credential_process を記述します:

[profile zeroclaw-bedrock]
credential_process = /usr/bin/aws configure export-credentials --profile my-existing-profile
region = us-east-1

/usr/bin/aws は Debian と Ubuntu でのデフォルトパスです。他のシステムでは、command -v aws で得られる絶対パスを使用してください。

次に、AWS_PROFILE=zeroclaw-bedrock を指定して ZeroClaw を実行します。systemd ユーザーサービスについては、サービス管理を参照してください。

マルチリージョン (Moonshot / Qwen / GLM / MiniMax / …)

ファミリーごとに1つの型を指定します。エイリアスエントリの型付き endpoint フィールドを使用してリージョンを選択してください。

カスタム OpenAI 互換エンドポイント

custom スロットには uri が必要です。Custom providers を参照してください。

エージェントが使用するプロバイダーの選択

エージェントはドット区切りのエイリアスでプロバイダーを参照します。プロバイダーのエントリーは、それ単体では何も行いません。

risk_profile と runtime_profile は独立したエイリアスマップを参照するため、両者の名前は一致する必要はありません（runtime_profile もオプションです）。Config::validate() は、model_provider が設定済みの [providers.models.<type>.<alias>] エントリに解決されない場合、または risk_profile が設定済みの [risk_profiles.<alias>] エントリに解決されない場合、起動時に明示的にエラーを発生させます。

複数のエージェントを異なるプロバイダーに向ける場合は、Routing を参照してください。

失敗時のフォールバック

プロバイダーへのリクエストがリトライを使い果たした後に失敗した場合（プロバイダーのダウン、キーのレート制限、モデルの利用不可）、エイリアスはエイリアスエントリーで宣言した代替先にフェイルオーバーできます。2つの独立した順序付き軸：

fallback_models: _この_プロバイダーで試行される代替モデルID。同じエンドポイント、キー、ヘッダーを使用します。変更されるのはモデル識別子のみです。プロバイダーを完全に離れる前に試すべきバックアップモデル（より小型または古いバリアント）をプロバイダーが提供している場合に使用します。
fallback: 他のプロバイダーエイリアスの順序付きリスト（[providers.models] への <type>.<alias> 形式のドット区切り参照）。各フォールバックエイリアスはそれ自身の認証情報、エンドポイント、モデルで解決され、フォールバックが失敗したエイリアスのキーを継承することはありません。

試行順序

このウォークは深さ優先です。エイリアスのモデルリスト全体を使い切ってからそのエイリアスを離れ、その後各 fallback エイリアスを順番に降りていき、そのエイリアス自身の fallback_models と fallback を再帰的に適用します。anthropic.prod が claude-sonnet-4-5 を提供し、その fallback_models に claude-haiku-4-5 を列挙し、その fallback に openai.backup（gpt-4.1 を提供）を指定しているとします。この場合の試行順序は次のとおりです。

anthropic.prod/claude-sonnet-4-5
  -> anthropic.prod/claude-haiku-4-5
  -> openai.backup/gpt-4.1
  -> (request fails)

フォールバックエイリアス自体もfallbackを宣言できるため、チェーンは設定次第で長くなり、最大で3エイリアスの深さまで到達します。自分自身にループバックするチェーン（a -> b -> a）は検出され、循環するエッジは切り取られます。また、制限を超える深さの非循環チェーンは、残りのリンクが切り取られます。いずれの場合も、ループ、ハング、スタックオーバーフローが発生することはありません。

設定の誤り

設定されていないエイリアスを指定する fallback エントリ、循環を形成するもの、または最大深度を超える連鎖は 致命的ではありません。Config::validate() は引き続き成功し、問題のあるエッジは実行時にスキップされ、その問題は CLI とダッシュボード上で検証警告（dangling_fallback_ref / fallback_cycle / max_fallback_depth_exceeded）として表示されます。空欄であるか、エイリアスのプライマリ model と重複する fallback_models エントリも同様に実行時にスキップされ、表示されます（empty_fallback_model / fallback_model_duplicates_primary）。不正なフォールバックリンクは適切に劣化し、エージェントの実行を妨げることは決してありません。

ZeroClaw Docs