カスタムプロバイダー

ZeroClaw に同梱されていないプロバイダーを追加する3つの方法:

custom スロットを使用します。 既存の正規スロットでカバーされていない OpenAI 互換エンドポイントに使用します。
ファーストクラスのローカルサーバースロットを使用する（lmstudio、llamacpp、sglang、vllm、osaurus、litellm）。適切なデフォルト値を備えたシンラッパーです。
Rustで**ModelProviderトレイトを実装**します。OpenAI互換ではないものすべてに対して使用します。

OpenAI互換エンドポイント: `custom` スロットを使用します

サービスが OpenAI の chat-completions に対応している場合、これは設定のみの変更です。custom スロットには uri が必要です（このファミリのエンドポイント enum にはデフォルト値がありません）。エージェントの model_provider から参照してください。

これは groq、mistral、xai、およびカタログに独自の正規スロットを持つ他のすべてのベンダーで使用されているものと同じ OpenAiCompatibleModelProvider ランタイム実装です。違いは使用するファミリースロットにあります。custom はベンダースロットで表現されないエンドポイント向けの汎用スロットです。

画像を含むツール結果を受け付けられないゲートウェイでは、それらの画像ペイロードを省略し、周囲のツールテキストは保持します。ツールの画像は、ネイティブのツール結果キャリアにある attachments 配列で宣言されているため、省略しても結果テキストは一切変更されません。このポリシーはネイティブの role = "tool" キャリアの attachments 配列のみを対象とします。ユーザーメッセージで配信されるプロンプトモードのツール結果（件数行キャリア）は、宣言された画像を別の経路で解決するため、この設定の影響を受けません。オプトインするには:

[providers.models.custom.gateway]
uri = "https://gateway.example.com/v1"
model = "my-model"
tool_result_image_policy = "omit"

接続のウォームアップ

OpenAI互換プロバイダーは、モデル一覧取得と同じ認証およびHTTPクライアント設定を使い、GET {base_url}/models で接続をウォームアップします。プローブはレスポンスボディを読み捨て、成功以外のHTTPステータスコードも受け入れるため、モデルエンドポイントを持たないサービスでも起動できます。チャット補完リクエストは引き続きPOSTを使用します。ウォームアップは推論を実行せず、モデルカタログも必要としません。

ファーストクラスのローカル推論サーバー

ZeroClawは、人気のあるローカル推論スタック向けの標準スロットを同梱しています。これらはすべて内部的にOpenAI互換ですが、デフォルトのuri値があらかじめ適用されているため、通常はuriを完全に省略できます。

llama.cpp: スロット `llamacpp`

sh

llama-server -hf ggml-org/gpt-oss-20b-GGUF --jinja -c 133000 --host 127.0.0.1 --port 8033

オプションフィールドは、任意の compat-slot ファミリー（llamacpp を含む）に適用されます。スキーマから導出された完全なセットは次のとおりです。

api_key 🔑 secret · default —

この model_provider のシークレット API トークン。model_provider のダッシュボード（OpenAI platform、Anthropic console、OpenRouter keys ページなど）から取得します。可能な場合は OS キーリング経由で保存され、config.toml に直接コミットしないでください。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.api_key フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.api_key フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.api_key    # マスクされた入力、暗号化して保存

環境変数

オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。

export ZEROCLAW_providers__models__custom__<alias>__api_key=

cache_passthrough bool · default —

true にすると、構造化パス（エージェントのターン、ツール呼び出し、構造化ストリーミング）のリクエストボディに、Anthropic 形式の cache_control ブレークポイントが追加されます。配置はネイティブの Anthropic プロバイダーの方針に合わせ、システムプロンプトと、会話に system 以外のメッセージが 2 件以上ある場合は最後のメッセージに付与します。ゲートウェイが報告するキャッシュ使用量は、キャッシュトークンのカウンターに反映されます。merge_system_into_user を使う場合は、マージされた最初の user メッセージにシステムのブレークポイントが付与されます。chat_with_system、chat_with_history、従来のチャンクストリーム API などのテキスト専用ヘルパーは、意図的にブレークポイントを付与しません。これらはレスポンスから使用量を返さないため、割増料金のキャッシュ書き込みが発生しても会計処理できないからです。このブレークポイントを転送するのは、OpenAI Chat Completions と Anthropic Messages API の間で変換を行うゲートウェイ（例: LiteLLM）のみです。デフォルトは false で、リクエストボディとレスポンス処理は変更されません。利用前に、設定したルートがキャッシュ読み取りを返すことを確認してください。キャッシュを作成するリクエストを直後に繰り返したとき、cache_read_input_tokens > 0 が報告されること。ゲートウェイの中には、キャッシュ書き込みを受け付けて課金するものの、キャッシュ読み取りを一度も返さないルートがあります。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.cache_passthrough フィールドを設定します。

zerocode

In the Config pane, set the providers.models.custom.<alias>.cache_passthrough field.

Wait, I should translate this to Japanese. Following the system rules: preserve bold, backticks, and the exact substring unchanged, translate the rest.

設定ペインで、providers.models.custom.<alias>.cache_passthrough フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.cache_passthrough <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__cache_passthrough=

cache_ttl CacheTtl · default —

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.cache_ttl フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.cache_ttl フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.cache_ttl <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__cache_ttl=

chat_template_kwargs table · default —

OpenAI互換プロバイダーのリクエスト本文で、トップレベルの chat_template_kwargs オブジェクトとして任意のキーと値のペアをそのまま転送します。vLLM、SGLang、llama.cpp などのチャットテンプレート対応バックエンドがこれを使用し、他のフィールドでは公開されていない動作を制御するモデルファミリー固有のテンプレート変数を渡します。JSON オブジェクト（TOML インラインテーブル）である必要があり、オブジェクト以外の値は警告とともに無視されます。例（Qwen3 の思考抑制）：chat_template_kwargs = { enable_thinking = false }

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.chat_template_kwargs フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.chat_template_kwargs フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.chat_template_kwargs <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__chat_template_kwargs=

context_window integer? · default —

このモデルのコンテキストウィンドウサイズ（最大入力トークン数）。利用可能な場合、セットアップ時にプロバイダーの /models エンドポイントから自動入力されます。カスタムエンドポイントの場合や自動検出が失敗した場合は手動で上書きします。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.context_window フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.context_window フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.context_window <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__context_window=

extra_headers 🔑 secret map · default —

すべてのリクエストに付与される追加のHTTPヘッダー。ニッチな用途: 認証ブリッジ、企業プロキシ、またはトレーシングヘッダーを要求するカスタムゲートウェイで使用されます。ほとんどのユーザーが触れることはありません。必要な場合はconfig.tomlを直接編集してください。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.extra_headers フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.extra_headers フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.extra_headers.<KEY>    # masked input, stored encrypted
zeroclaw config set providers.models.custom.<alias>.extra_headers.<KEY> # 空の値はエントリを削除します

環境変数

export ZEROCLAW_providers__models__custom__<alias>__extra_headers=

fallback ModelProviderRef[] · default —

このエイリアスのすべてのモデルが失敗したときに試行する、他のプロバイダーエイリアスの順序付きリストです。各エントリは providers.models 内のドット区切りの <type>.<alias> 参照であり、独自の認証情報、エンドポイント、モデルで解決されます。フォールバックがこのエイリアスのキーを継承することはありません。走査は深さ優先で行われます。まずこのエイリアスのモデルが使い尽くされ、次に各フォールバックエイリアスが順番に降下されます（それぞれ独自の fallback_models と fallback を適用します）。空の場合、プロバイダーレベルのフォールバックはありません。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.fallback フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.fallback フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.fallback <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__fallback=

fallback_models string[] · default —

fallback エイリアスにフォールバックする前に、このプロバイダーで試行する代替モデルの順序付きリスト。プライマリの model と同じエンドポイント、キー、ヘッダーを使用します。変更されるのはモデル識別子のみです。プロバイダーが（例えばより小さい、または古いバリアントの）バックアップモデルを提供しており、プロバイダーを完全に離れる前に試行すべき場合に使用します。空の場合は model のみが試行されます。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.fallback_models フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.fallback_models フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.fallback_models <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__fallback_models=

kind string? · default —

このプロファイルでインスタンス化するプロバイダー実装です。正規の型付きスロットを互換性のある実装で実行する場合に使用します。例: [providers.models.openai.proxy] kind = "openai-compatible"。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.kind フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.kind フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.kind <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__kind=

live_pricing bool · default —

このプロバイダーのモデルのライブトークン価格を、プロバイダー自身のOpenAI互換の /models リストから取得し（ゲートウェイがその価格の信頼できる情報源です）、オペレーターが [cost.rates] / pricing で価格を設定していないモデルのコスト追跡レートを補完します。ゲートウェイが価格を設定していないモデル（または kilocli のようなサブプロセスゲートウェイなど、HTTP /models リスト自体が存在しないプロバイダー）は、公開されている models.dev カタログにフォールバックします。設定されたレートが常に優先され、ライブ価格は不足分を補完するだけです。バックグラウンドタスクが価格スナップショットを1時間ごとに更新します。コスト記録パスはキャッシュされたスナップショットを読み取り、ネットワークでブロックすることはありません。デフォルトは false：オフの場合、取得は行われず、この機能なしでビルドした場合と同一の動作になります。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.live_pricing フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.live_pricing フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.live_pricing <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__live_pricing=

max_tokens integer? · default —

応答の長さの上限をトークン数で指定するハードキャップです。ほとんどのモデルにはすでに適切な組み込みの上限が設定されているため、コストやレイテンシの理由で長い出力を切り詰める必要が特にない限り、未設定のままにしてください。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて providers.models.custom.<alias>.max_tokens フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.max_tokens フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.max_tokens <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__max_tokens=

merge_system_into_user bool · default —

ModelProvider 固有の癖: システムプロンプトを別の system ロールとして送信せず、最初のユーザーメッセージに統合します。単独の system ロールを拒否する（または正しく処理できない）モデル、例えば一部の古い Mistral バリアントでのみ必要です。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.merge_system_into_user フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.merge_system_into_user フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.merge_system_into_user <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__merge_system_into_user=

model string? · default —

各リクエストで送信するモデル識別子: model_provider のカタログにある ID 文字列（例: gpt-4o、claude-sonnet-4-5、llama-3.3-70b）。このアカウントで model_provider が実際に提供しているモデルと一致する必要があります。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.model フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.model フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.model <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__model=

native_tools bool? · default —

ネイティブツール呼び出しに関するプロバイダーのデフォルト設定をオーバーライドします。None（デフォルト）はプロバイダーの組み込み設定を尊重します。Some(true) はネイティブツール呼び出しを強制的に有効化し、Some(false) はテキストフォールバックを強制します。現在はGroqファクトリーのみが参照しており、llamaファミリーのGroqモデルがネイティブツール呼び出しをHTTP 400で拒否するため、デフォルトでテキストフォールバックになっています。native_tools = true を設定すると、対応するGroqモデルでネイティブツール呼び出しが再度有効になります。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.native_tools フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.native_tools フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.native_tools <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__native_tools=

pricing map · default —

コスト追跡用のモデルごとの料金設定。100万トークンあたりのUSD。自由形式のキー/値マップ。キーはユーザー定義のモデル識別子で、オプションの .input / .output サフィックスは、オペレーターがレートを分割したい場合に料金の次元を示します。サフィックスのない単純なキーは、いずれの次元も指定されていない場合にトークンごとの一律レートとして使用されます。デフォルトは空です。この場合、コスト追跡は「不明」レートにフォールバックし、トークン使用量のみが記録されます。例: pricing = { opus = 15.0, sonnet = 3.0 } または分割する場合: pricing = { "opus.input" = 15.0, "opus.output" = 75.0 }

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.pricing フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.pricing フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.pricing <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__pricing=

provider_extra table · default —

API リクエストに含める追加の JSON パラメーター。リクエストボディのトップレベルでマージされ、コードを変更することなくプロバイダー固有の機能（ルーティング、変換など）を利用できます。例: provider_extra = { model_provider = { only = ["Anthropic"] } }

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.provider_extra フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.provider_extra フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.provider_extra <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__provider_extra=

reasoning_effort_passthrough bool · default —

OpenAI互換のこのプロバイダー上のすべてのモデルに、実行時に設定されたreasoning_effortを転送します。OpenAIの推論系モデル名 (o1*/o3*/o4*/gpt-5*/gpt-codex) だけに限定しません。モデル名によるフィルタは、一部の厳格なバックエンドが未知のリクエストパラメータを HTTP 400 で拒否するために存在します。このオプションは、reasoning_effortを受け付けることが確認されたバックエンドでのみ有効にしてください（OpenAI互換ゲートウェイ経由のGLM/Kimi/DeepSeek/Qwen系の推論モデルは一般的に受け付けます）。デフォルトはfalseです：モデル名フィルタが引き続き判定し、OpenAI以外のモデル名には決してこのパラメータは送信されません。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.reasoning_effort_passthrough フィールドを設定してください。

zerocode

Configペインで、providers.models.custom.<alias>.reasoning_effort_passthroughフィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.reasoning_effort_passthrough <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__reasoning_effort_passthrough=

replay_assistant_reasoning bool? · default —

保存されたアシスタントの推論を、送信するアシスタント履歴メッセージで再生するかどうか。Some(false) は送信前に reasoning_content と reasoning を除去します。None（デフォルト）はプロバイダーの組み込みデフォルト（ほとんどの互換プロバイダーでは true、Groq では false）に従います。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.replay_assistant_reasoning フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.replay_assistant_reasoning フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.replay_assistant_reasoning <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__replay_assistant_reasoning=

requires_openai_auth bool · default —

true の場合、クライアントは上記の api_key フィールドではなく、ZeroClaw に保存された openai-codex 認証プロファイルから認証情報を取得します。既存の Codex CLI ログインをインポートするには zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json を実行するか、zeroclaw auth login --model-provider openai-codex を実行してください。OpenAI Codex の model_provider の場合にのみ有効にし、標準の API キーによる model_provider では無効のままにしてください。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.requires_openai_auth フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.requires_openai_auth フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.requires_openai_auth <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__requires_openai_auth=

temperature number? · default —

モデルに渡されるサンプリング温度です。低い値（0.0〜0.3）は決定論的でほぼ忠実な出力となり、コード、ルーティング、要約に適しています。高い値（0.7〜1.2）はより多様な出力となり、自由形式のチャットに適しています。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.temperature フィールドを設定してください。

zerocode

Configペインで、providers.models.custom.<alias>.temperatureフィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.temperature <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__temperature=

think bool? · default —

これをサポートするモデル（例：Qwen3、GLM-4）で連鎖的思考（chain-of-thought）を有効または無効にします。true で思考をオンにし、false でオフにします。None（デフォルト）の場合はモデルが判断します。リクエストボディ内で enable_thinking として転送され、Ollama プロバイダーの think フィールドに対応します。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.think フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.think フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.think <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__think=

thinking_passthrough bool · default —

このOpenAI互換プロバイダー経由でAnthropicの拡張思考を転送します。trueに設定され、ランタイムがネイティブな思考を要求した場合、リクエストボディにAnthropic形式のthinkingオブジェクト（{"type":"enabled","budget_tokens":N}）が追加され、ゲートウェイからの思考レスポンスは再送可能な署名付きブロックに正規化されます。OpenAI Chat CompletionsとAnthropic APIの間で変換を行うゲートウェイ（例: LiteLLM）のみがこの機能をサポートします。変換を行わない上流サービスは、注入されたthinkingオブジェクトを拒否し、HTTP 400を返します。デフォルトはfalseで、その場合リクエストボディとレスポンス処理は変更されません。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

Open /config/providers.models/custom を開き、providers.models.custom.<alias>.thinking_passthrough フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.thinking_passthrough フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.thinking_passthrough <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__thinking_passthrough=

timeout_secs integer? · default —

HTTP リクエストのタイムアウト秒数です。低速なローカル model_providers（CPU 上の Ollama、大規模なローカルモデル）や遅延の大きいネットワークでは値を大きくしてください。未設定のままで問題ない場合は設定しないでください。300 を超える値を設定すると、OpenAI 互換および OpenAI Responses プロバイダーのストリーミングのアイドル上限（デフォルトは 300 秒で、ストリーム読み取り間の最大待機時間）も引き上げられます。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.timeout_secs フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.timeout_secs フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.timeout_secs <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__timeout_secs=

tls_ca_cert_path string? · default —

このプロバイダーへのTLS接続に使用するPEMエンコードされたCA証明書へのパス。絶対パスである必要があります。シェル展開（例: ~）は実行されません。システムのデフォルトのトラストストアを使用する場合は未設定のままにしてください。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開いて、providers.models.custom.<alias>.tls_ca_cert_path フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.tls_ca_cert_path フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.tls_ca_cert_path <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__tls_ca_cert_path=

tool_result_image_policy ToolResultImagePolicy · default —

ネイティブ互換の chat-completions プロバイダーが、attachments 配列で宣言された role=tool の結果内の画像をどう扱うか。image_url の場合は構造化された画像パーツとして送信します。omit の場合は画像を破棄して固定の通知を追記しますが、結果のテキストはそのまま保持します。レガシーなツール結果（配列キーなし）は、どちらの設定でも原文のまま通過します。これらは何も宣言しておらず、本文はテキストであるため、ツール出力内のリテラルなマーカー構文がこのポリシーを決定することはありません。これは、ユーザーが直接入力した画像コンテンツや OpenAI Responses プロバイダーには影響しません。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.tool_result_image_policy フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.tool_result_image_policy フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.tool_result_image_policy <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__tool_result_image_policy=

uri string? · default —

クライアントが接続するエンドポイント URI。セルフホスト型のゲートウェイ（LiteLLM、vLLM、Ollama）、カスタムプロキシ、または非標準の URL を指定する場合に、ファミリーのデフォルトエンドポイントを上書きします。未設定のままにすると、ファミリーの ModelEndpoint 実装によるデフォルト URI が使用されます。これにはエンドポイントの完全な URL を設定してください。パスサフィックス用の個別フィールドはありません。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.uri フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.uri フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.uri <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__uri=

vision bool? · default —

プロバイダーの vision（画像入力）機能を上書きします。None（デフォルト）はプロバイダーファミリーの組み込みデフォルトを使用します。いくつかのファミリー（llama.cpp、汎用の OpenAI 互換エンドポイントなど）は、マルチモーダルモデルを提供できるため vision 対応と見なされます。そのようなファミリーで提供されるテキスト専用モデル（例: llama.cpp の背後にあるテキスト LLM）の場合は vision = false を設定してください。これにより、画像メッセージは、それらを拒否するモデルに送信される代わりに、設定された [multimodal] vision_model_provider にルーティングされます。Some(true) は vision を強制的に有効にします。

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.vision フィールドを設定します。

zerocode

Config ペインで、providers.models.custom.<alias>.vision フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.vision <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__vision=

wire_api WireApi · default —

任意のサーフェスに設定する場合:

ゲートウェイダッシュボード

/config/providers.models/custom を開き、providers.models.custom.<alias>.wire_api フィールドを設定してください。

zerocode

Config ペインで、providers.models.custom.<alias>.wire_api フィールドを設定します。

zeroclaw config

zeroclaw config set providers.models.custom.<alias>.wire_api <value>

環境変数

export ZEROCLAW_providers__models__custom__<alias>__wire_api=

思考モードの制御はモデルファミリーによって異なります。think = false はリクエスト内のトップレベルの enable_thinking フィールドを設定します。一部のモデル（例: Qwen3）は、代わりに chat_template_kwargs を介して Jinja テンプレートからこのフラグを読み取ります:

他のモデルファミリーでは異なるテンプレート変数名を使用します。お使いのモデルのチャットテンプレートを確認し、chat_template_kwargsの下に適切なキーを設定してください。

SGLang: スロット `sglang`

sh

python -m sglang.launch_server --model meta-llama/Llama-3.1-8B-Instruct --port 30000

vLLM: スロット `vllm`

sh

vllm serve meta-llama/Llama-3.1-8B-Instruct

LM Studio, Osaurus, LiteLLM

スロット lmstudio、osaurus、litellm も同じパターンに従います。詳しくはカタログを参照してください。

ワイヤープロトコル: `wire_api = "responses"`

設定に書き込まれる 新しい OpenAI プロバイダースロット（zeroclaw quickstart またはゲートウェイ/設定 UI で作成される providers.models.openai.<alias>）は、デフォルトで wire_api = "responses" になります。これは、OpenAI の最近の GPT モデルがプライマリワイヤーとして POST /v1/responses を使用するためです。その他の独自エンドポイント持ち込み型スロット（custom、llamacpp、および OpenAI 互換ベンダー）は、依然として chat-completions ワイヤーがデフォルトです。OpenAI の responses ワイヤーのみに対応するエンドポイント（一部のセルフホスト型 vLLM / TGI デプロイメント）では、エイリアスエントリーに明示的な wire_api = "responses" のオプトインが必要です。

"responses" に設定すると、プロバイダーは chat-completions プロバイダーではなく、OpenAiResponsesModelProvider（responses プロトコル経由の完全なストリーミングツール呼び出し）として構築されます。レガシーのワイヤー形式を強制するには "chat_completions" を設定します。後方互換性のため、実行時に chat-completions を維持するケースが 2 つあるため、アップグレード時に既存のセットアップのワイヤー形式が変更されることはありません:

wire_api を省略した永続化された providers.models.openai.<alias> エントリは、未設定としてデシリアライズされ、chat-completions のままになります。
bare な model_provider = "openai" 参照（または存在しないエイリアスへのドット区切りの参照）には、読み取る config エントリがありません。これは family fallback から構築され、chat-completions のままです。responses のデフォルトは、スロットが実際に config に書き込まれている場合にのみ適用されます。

wire_apiは、ワイヤをオペレーターが設定可能な bring-your-own-endpoint ファミリーで尊重されます：openai、llamacpp、custom（さらに汎用の openai-compatible パス）。ブランド付きベンダースロット（groq、mistral、deepseek、…）はワイヤプロトコルが固定されており、このフィールドを無視します。ただし1つ例外があります：opencodeはwire_api = "responses"を尊重します。これは OpenCode Zen が両方のワイヤを提供するためです。uriのオーバーライドがない場合、OpenCode responses ルートはhttps://opencode.ai/zen/v1/responsesを対象とします：

[providers.models.opencode.default]
model    = "big-pickle"
wire_api = "responses"

この設定はプライマリエージェントパスとデリゲートターゲットの両方を制御するため、ターゲットエイリアスが wire_api = "responses" を宣言しているデリゲートは、responsesワイヤー経由でエンドポイントに到達します。

OpenCode セッションアフィニティ

opencode.ai ホストへのすべての推論リクエストには、ストリーミングと非ストリーミングの両方で x-opencode-session ヘッダーが付与されます。OpenCode はこのヘッダーを使って、1 つの会話のターンを同じアップストリームのバックエンドに固定し、そのバックエンドのプロンプトキャッシュをターン間で温かく保ちます。また、アップストリームはこのヘッダーを、アカウントがフラグ付けされるのを防ぐためのガイダンスにも挙げています。さらに、一部の OpenCode Go モデルは、このヘッダーがないリクエストを一律に拒否します。モデルカタログとウォームアップのリクエスト（GET /models）にはこのヘッダーは付与されません。これらは会話の一部ではないため、固定すべきバックエンドが存在しないからです。

この値は、アクティブな会話スコープから導出される不透明な128ビットの16進トークンです。そのため、各会話は固有のバックエンドに固定され、同じ会話はデーモンを再起動しても同じバックエンドを維持します。会話のセッションキーはハッシュ化され、決して送信されません。セッションキーにはチャネルとユーザーの識別子が含まれるため、そのまま転送すると第三者のリレーにユーザーごとの識別子を渡すことになります。会話に属さない推論リクエストは、代わりにプロセスの存続期間中は変わらない共通のトークンを使用します。

ありません。レプリカ間で同じアフィニティスコープを共有するなど、値を自分で固定したい場合は明示的に設定してください。設定された値は ZeroClaw が変更しません:

[providers.models.opencode.default]
model = "big-pickle"

[providers.models.opencode.default.extra_headers]
x-opencode-session = "my-fixed-scope"

opencode.ai およびそのサブドメイン以外のホストには、このヘッダーが送信されることはありません。これを維持するため、OpenCode のリクエストは同一ホスト内のリダイレクトのみに従います。異なるホストへのリダイレクトには従わず、そのリダイレクトステータスでリクエストが失敗します。

検証

アプローチに関わらず：

sh

zeroclaw config list                          # 設定を読み込む。検証に失敗した場合は stderr に出力される
zeroclaw models refresh --model-provider <type>.<alias>   # list models the endpoint advertises
zeroclaw agent -a <alias> -m "hello"          # `[agents.<alias>]` のエージェントに対するスモークテスト

新しい `ModelProvider` トレイトの実装

エンドポイントが OpenAI 互換ではなく、ローカルサーバースロットのいずれにも該当しない場合は、コードが必要です。

このトレイトは crates/zeroclaw-api/src/model_provider.rs にあります:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait ModelProvider: Send + Sync {
    fn name(&self) -> &str;
    fn supports_streaming(&self) -> bool { true }
    fn supports_streaming_tool_events(&self) -> bool { false }

    async fn chat(
        &self,
        messages: Vec<Message>,
        tools: Vec<ToolSchema>,
        options: ChatOptions,
    ) -> Pin<Box<dyn Stream<Item = Result<StreamEvent>> + Send>>;
}
}

実装パターン:

crates/zeroclaw-config/src/schema.rs で型付き設定を定義します:

#![allow(unused)]
fn main() {
pub struct MyProviderModelProviderConfig {
    #[serde(flatten)]
    pub base: ModelProviderConfig,
    pub endpoint: MyProviderEndpoint,
    // ファミリー固有のフィールド
}

pub enum MyProviderEndpoint { Default }
impl ModelEndpoint for MyProviderEndpoint {
    fn uri(&self) -> &'static str {
        match self { Self::Default => "https://my-provider.example.com/v1" }
    }
}
}

crates/zeroclaw-config/src/providers.rs の for_each_model_provider_slot! にスロットを追加します。すべてのヘルパーが新しいスロットを自動的に認識します。
crates/zeroclaw-providers/src/myprovider.rs にランタイム実装を追加します。Vec<Message> をワイヤーフォーマットに変換し、レスポンスをストリーミングして StreamEvent の値を出力します。
crates/zeroclaw-providers/src/lib.rs::create_provider_with_url_and_options のファクトリーブランチを接続します。
プロバイダーが重い依存関係を取り込む場合は、Cargo.toml にフィーチャーフラグを追加してください。

完全にカスタムなワイヤーフォーマットを持つプロバイダーの例については、anthropic.rs を参照してください。SSEストリーミングのOpenAI互換パターンについては、compatible.rs を参照してください。

トラブルシューティング

認証エラー

APIキーがエンドポイントと一致していることを確認してください（多くのベンダーはキーのプレフィックスを使用しています：sk-、gsk_、sk-ant-）。
uri にスキーム（http:// / https://）が含まれていること、およびエンドポイントが必要とする場合は /v1 パスが含まれていることを確認してください。
VPN またはプロキシの背後にあるエンドポイントですか？ZeroClaw ホストからのルーティングを確認してください。

モデルが見つかりません

エンドポイントが宣伝しているものをリストします：

sh

  curl -sS $URI/models -H `Authorization: Bearer $API_KEY` | jq

- If the endpoint doesn't implement `/models`, send a direct chat request and read the error, most endpoints return the expected model family in the error body. - Gateway services often expose only a subset of upstream models.

接続の問題

curl -I $URI、応答はありますか？
ファイアウォール、プロキシ、egressルールは？VPSプロバイダーは送信用の高位ポートをブロックすることがあります。
ホステッドサービスの場合はベンダーのステータスページ。

ゲートウェイが `temperature` を拒否します

一部のゲートウェイ（例えば claude-opus-4-7 をフロントエンドとする LiteLLM プロキシ）は、temperature フィールドが存在するだけでエラーを返します。ZeroClaw は Option の規約を尊重します。設定で temperature を未設定のままにした場合、そのフィールドはリクエストボディから完全に省略され、バックエンドが独自のデフォルト値を選択します。エンドポイントが受け付ける場合にのみ、temperature を明示的に設定してください。

Keyboard shortcuts

ZeroClaw Docs