設定 — ツールとカスタムプロバイダー

プロバイダー項目（type: "provider" または省略）:

• provider: API プロバイダー ID（openai、anthropic、google/gemini、groq など）
• model: モデル ID の上書き
• profile / preferredProfile: auth-profiles.json プロファイル選択

CLI 項目（type: "cli"）:

• command: 実行する実行可能ファイル
• args: テンプレート化された引数（{{MediaPath}}、{{Prompt}}、{{MaxChars}} などをサポートします。openclaw doctor --fix は非推奨の {input} プレースホルダーを {{MediaPath}} に移行します）

共通フィールド:

• capabilities: 任意のリスト（image、audio、video）。デフォルト: openai/anthropic/minimax → 画像、google → 画像+音声+動画、groq → 音声。
• prompt、maxChars、maxBytes、timeoutSeconds、language: 項目ごとの上書き。
• tools.media.image.timeoutSeconds と、一致する画像モデルの timeoutSeconds 項目は、エージェントが明示的な image ツールを呼び出す場合にも適用されます。
• 失敗した場合は次の項目にフォールバックします。

プロバイダー認証は標準の順序に従います: auth-profiles.json → 環境変数 → models.providers.*.apiKey。

非同期完了フィールド:

• asyncCompletion.directSend: 非推奨の互換性フラグ。完了した非同期メディアタスクは、リクエスターのセッション経由のままになるため、エージェントが結果を受け取り、ユーザーへの伝え方を決定し、ソース配信で必要な場合にメッセージツールを使用します。

• self: 現在のセッションキーのみ。
• tree: 現在のセッション + 現在のセッションにより生成されたセッション（サブエージェント）。
• agent: 現在のエージェント ID に属する任意のセッション（同じエージェント ID の下で送信者ごとのセッションを実行している場合、他のユーザーを含むことがあります）。
• all: 任意のセッション。エージェントをまたぐターゲット指定には引き続き tools.agentToAgent が必要です。
• サンドボックス制限: 現在のセッションがサンドボックス化されており、agents.defaults.sandbox.sessionToolsVisibility="spawned" の場合、tools.sessions.visibility="all" であっても可視性は tree に強制されます。

• 添付ファイルは runtime: "subagent" でのみサポートされます。ACP ランタイムは添付ファイルを拒否します。
• ファイルは子ワークスペースの .openclaw/attachments/<uuid>/ に .manifest.json とともに実体化されます。
• 添付ファイルの内容は、トランスクリプトの永続化から自動的に編集されます。
• Base64 入力は、厳密なアルファベット/パディング検査と、デコード前のサイズガードで検証されます。
• ファイル権限は、ディレクトリが 0700、ファイルが 0600 です。
• クリーンアップは cleanup ポリシーに従います。delete は常に添付ファイルを削除します。keep は retainOnSessionKeep: true の場合にのみ添付ファイルを保持します。

• カスタム認証が必要な場合は、authHeader: true + headers を使用します。
• エージェント設定ルートは OPENCLAW_AGENT_DIR (またはレガシー環境変数エイリアスの PI_CODING_AGENT_DIR) でオーバーライドします。
• 一致するプロバイダー ID のマージ優先順位:
  • 空でないエージェント models.json の baseUrl 値が優先されます。
  • 空でないエージェント 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 にフォールバックします。
  • 一致するモデルの contextWindow/maxTokens は、明示的な設定値と暗黙のカタログ値のうち高い方を使用します。
  • 一致するモデルの contextTokens は、存在する場合は明示的なランタイム上限を保持します。ネイティブモデルメタデータを変更せずに有効コンテキストを制限するために使用します。
  • 設定で models.json を完全に書き換えたい場合は、models.mode: "replace" を使用します。
  • マーカーの永続化はソースを正とします。マーカーは、解決済みランタイムシークレット値からではなく、アクティブなソース設定スナップショット (解決前) から書き込まれます。

• models.mode: プロバイダーカタログの動作 (merge または replace)。
• models.providers: プロバイダー ID をキーにしたカスタムプロバイダーマップ。
  • 安全な編集: 追加更新には openclaw config set models.providers.<id> '<json>' --strict-json --merge または openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge を使用します。config set は、--replace を渡さない限り破壊的な置換を拒否します。

• models.providers.*.api: リクエストアダプター (openai-completions、openai-responses、anthropic-messages、google-generative-ai など)。MLX、vLLM、SGLang、およびほとんどの OpenAI 互換ローカルサーバーなどのセルフホスト /v1/chat/completions バックエンドには、openai-completions を使用します。baseUrl があり api がないカスタムプロバイダーは、デフォルトで openai-completions になります。バックエンドが /v1/responses をサポートしている場合にのみ、openai-responses を設定します。
• models.providers.*.apiKey: プロバイダー資格情報 (SecretRef/env 置換を推奨)。
• models.providers.*.auth: 認証戦略 (api-key、token、oauth、aws-sdk)。
• models.providers.*.contextWindow: モデルエントリが contextWindow を設定していない場合に、このプロバイダー配下のモデルに使用されるデフォルトのネイティブコンテキストウィンドウ。
• models.providers.*.contextTokens: モデルエントリが contextTokens を設定していない場合に、このプロバイダー配下のモデルに使用されるデフォルトの有効ランタイムコンテキスト上限。
• models.providers.*.maxTokens: モデルエントリが maxTokens を設定していない場合に、このプロバイダー配下のモデルに使用されるデフォルトの出力トークン上限。
• models.providers.*.timeoutSeconds: 接続、ヘッダー、本文、およびリクエスト全体の中止処理を含む、省略可能なプロバイダーごとのモデル HTTP リクエストタイムアウト秒数。
• models.providers.*.injectNumCtxForOpenAICompat: Ollama + openai-completions の場合に、リクエストへ options.num_ctx を注入します (デフォルト: true)。
• models.providers.*.authHeader: 必要な場合に、資格情報の転送を Authorization ヘッダーで強制します。
• models.providers.*.baseUrl: アップストリーム API ベース URL。
• models.providers.*.headers: プロキシ/テナントルーティング用の追加静的ヘッダー。

models.providers.*.request: モデルプロバイダー HTTP リクエストの転送オーバーライド。

• request.headers: 追加ヘッダー (プロバイダーのデフォルトとマージされます)。値は SecretRef を受け付けます。
• request.auth: 認証戦略のオーバーライド。モード: "provider-default" (プロバイダー組み込みの認証を使用)、"authorization-bearer" (token を使用)、"header" (headerName、value、省略可能な prefix を使用)。
• request.proxy: HTTP プロキシのオーバーライド。モード: "env-proxy" (HTTP_PROXY/HTTPS_PROXY 環境変数を使用)、"explicit-proxy" (url を使用)。どちらのモードも、省略可能な tls サブオブジェクトを受け付けます。
• request.tls: 直接接続の TLS オーバーライド。フィールド: ca、cert、key、passphrase (すべて SecretRef を受け付けます)、serverName、insecureSkipVerify。
• request.allowPrivateNetwork: true の場合、プロバイダー HTTP フェッチガードを介して、DNS がプライベート、CGNAT、または類似の範囲に解決されるときでも baseUrl への HTTPS を許可します (信頼済みセルフホスト OpenAI 互換エンドポイント向けのオペレーターによるオプトイン)。localhost、127.0.0.1、[::1] などのループバックモデルプロバイダーストリーム URL は、明示的に false に設定されていない限り自動的に許可されます。LAN、tailnet、およびプライベート DNS ホストには引き続きオプトインが必要です。WebSocket はヘッダー/TLS には同じ request を使用しますが、そのフェッチ SSRF ゲートは使用しません。デフォルトは false です。

• models.providers.*.models: 明示的なプロバイダーモデルカタログエントリ。
• models.providers.*.models.*.input: モデル入力モダリティ。テキスト専用モデルには ["text"] を、ネイティブ画像/ビジョンモデルには ["text", "image"] を使用します。画像添付ファイルは、選択されたモデルが画像対応としてマークされている場合にのみエージェントターンに注入されます。
• models.providers.*.models.*.contextWindow: ネイティブモデルコンテキストウィンドウメタデータ。これは、そのモデルのプロバイダーレベルの contextWindow をオーバーライドします。
• models.providers.*.models.*.contextTokens: 省略可能なランタイムコンテキスト上限。これはプロバイダーレベルの contextTokens をオーバーライドします。モデルのネイティブ contextWindow より小さい有効コンテキスト予算にしたい場合に使用します。openclaw models list は、値が異なる場合に両方を表示します。
• models.providers.*.models.*.compat.supportsDeveloperRole: 省略可能な互換性ヒント。空でない非ネイティブの baseUrl (ホストが api.openai.com ではない) を持つ api: "openai-completions" では、OpenClaw はランタイムでこれを false に強制します。空または省略された baseUrl は、デフォルトの OpenAI 動作を維持します。
• models.providers.*.models.*.compat.requiresStringContent: 文字列専用の OpenAI 互換チャットエンドポイント向けの、省略可能な互換性ヒント。true の場合、OpenClaw はリクエスト送信前に純粋なテキストの messages[].content 配列をプレーン文字列にフラット化します。
• models.providers.*.models.*.compat.strictMessageKeys: 厳密な OpenAI 互換チャットエンドポイント向けの、省略可能な互換性ヒント。true の場合、OpenClaw はリクエスト送信前に送信する Chat Completions メッセージオブジェクトを role と content に削ります。
• models.providers.*.models.*.compat.thinkingFormat: 省略可能な thinking ペイロードヒント。トップレベルの enable_thinking には "qwen" を使用し、vLLM など、リクエストレベルの chat-template kwargs をサポートする Qwen ファミリーの OpenAI 互換サーバーで chat_template_kwargs.enable_thinking を使う場合は "qwen-chat-template" を使用します。

• plugins.entries.amazon-bedrock.config.discovery: Bedrock 自動検出設定ルート。
• plugins.entries.amazon-bedrock.config.discovery.enabled: 暗黙の検出のオン/オフを切り替えます。
• plugins.entries.amazon-bedrock.config.discovery.region: 検出用の AWS リージョン。
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: 対象を絞った検出用の省略可能なプロバイダー ID フィルター。
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: 検出更新のポーリング間隔。
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: 検出されたモデルのフォールバックコンテキストウィンドウ。
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: 検出されたモデルのフォールバック最大出力トークン数。

バンドル済みの cerebras プロバイダー Plugin は、openclaw onboard --auth-choice cerebras-api-key でこれを設定できます。明示的なプロバイダー設定は、デフォルトを上書きする場合にのみ使用してください。

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

Cerebras には cerebras/zai-glm-4.7 を使用し、Z.AI 直接利用には zai/glm-4.7 を使用します。

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },    },  },}

Anthropic 互換の組み込みプロバイダーです。ショートカット: openclaw onboard --auth-choice kimi-code-api-key。

ローカルモデルを参照してください。要約: 十分なハードウェア上で LM Studio Responses API 経由で大規模ローカルモデルを実行し、フォールバック用にホスト型モデルをマージしたままにします。

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M2.7",            name: "MiniMax M2.7",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },            contextWindow: 204800,            maxTokens: 131072,          },        ],      },    },  },}

MINIMAX_API_KEY を設定します。ショートカット: openclaw onboard --auth-choice minimax-global-api または openclaw onboard --auth-choice minimax-cn-api。モデルカタログのデフォルトは M2.7 のみです。Anthropic 互換のストリーミングパスでは、OpenClaw は自分で thinking を明示的に設定しない限り、デフォルトで MiniMax の思考を無効化します。/fast on または params.fastMode: true は MiniMax-M2.7 を MiniMax-M2.7-highspeed に書き換えます。

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },    },  },  models: {    mode: "merge",    providers: {      moonshot: {        baseUrl: "https://api.moonshot.ai/v1",        apiKey: "${MOONSHOT_API_KEY}",        api: "openai-completions",        models: [          {            id: "kimi-k2.6",            name: "Kimi K2.6",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

中国エンドポイントの場合: baseUrl: "https://api.moonshot.cn/v1" または openclaw onboard --auth-choice moonshot-api-key-cn。

ネイティブの Moonshot エンドポイントは、共有 openai-completions トランスポート上でストリーミング使用量の互換性を公開し、OpenClaw は組み込みプロバイダー ID だけではなくエンドポイント機能に基づいてそれを判断します。

{  agents: {    defaults: {      model: { primary: "opencode/claude-opus-4-6" },      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },    },  },}

OPENCODE_API_KEY（または OPENCODE_ZEN_API_KEY）を設定します。Zen カタログには opencode/... 参照を使用し、Go カタログには opencode-go/... 参照を使用します。ショートカット: openclaw onboard --auth-choice opencode-zen または openclaw onboard --auth-choice opencode-go。

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M2.5",            name: "MiniMax M2.5",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

ベース URL では /v1 を省略してください（Anthropic クライアントが追加します）。ショートカット: openclaw onboard --auth-choice synthetic-api-key。

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

ZAI_API_KEY を設定します。z.ai/* と z-ai/* はエイリアスとして受け付けられます。ショートカット: openclaw onboard --auth-choice zai-api-key。

• 汎用エンドポイント: https://api.z.ai/api/paas/v4
• コーディングエンドポイント（デフォルト）: https://api.z.ai/api/coding/paas/v4
• 汎用エンドポイントの場合は、ベース URL の上書きを指定したカスタムプロバイダーを定義します。