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

プロバイダーエントリ（type: "provider" または省略）：

• provider：API プロバイダー ID（openai、anthropic、google／gemini、groq など）
• model：モデル ID のオーバーライド
• profile／preferredProfile：auth-profiles.json プロファイルの選択

CLI エントリ（type: "cli"）：

• command：実行する実行ファイル
• args：テンプレート化された引数（{{AttachmentPath}}、{{AttachmentUrl}}、{{AttachmentContentType}}、{{AttachmentDir}}、{{AttachmentIndex}}、{{Prompt}}、{{MaxChars}} などをサポート。openclaw doctor --fix は非推奨の {input} プレースホルダーを {{AttachmentPath}} に移行します）。旧 {{MediaPath}}、{{MediaUrl}}、{{MediaType}}、{{MediaDir}} エイリアスも互換期間中は引き続き使用できますが、非推奨です。

共通フィールド：

• capabilities：image、audio、video のうち 1 つ以上を含むリスト。
• prompt、maxChars、maxBytes、timeoutSeconds、language：エントリ単位のオーバーライド。
• 一致する画像モデルの timeoutSeconds エントリは、エージェントが明示的な image ツールを呼び出す場合にも適用されます。画像理解では、このタイムアウトはリクエスト自体に適用され、先行する準備作業によって短縮されることはありません。
• 失敗した場合は次のエントリにフォールバックします。

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

• self：現在のセッションキーのみ。
• tree：現在のセッション＋現在のセッションから生成されたセッション（サブエージェント）。読み取り操作では、現在のセッションがアンビエントなグループ認識を通じて監視している、同じエージェントのグループセッションも含まれます。
• agent：現在のエージェント ID に属する任意のセッション（同じエージェント ID で送信者単位のセッションを実行している場合、他のユーザーを含むことがあります）。
• all：任意のセッション。エージェントをまたぐ対象指定には、引き続き tools.agentToAgent が必要です。
• サンドボックスによる制限：現在のセッションがサンドボックス化され、agents.defaults.sandbox.sessionToolsVisibility="spawned"（デフォルト）の場合、tools.sessions.visibility="all" であっても可視性は強制的に tree になります。
• all でない場合、sessions_list には、有効なモードと、現在のスコープ外にある一部のセッションが省略される可能性があるという警告を説明する簡潔な visibility フィールドが含まれます。

• 添付ファイルには enabled: true が必要です。
• サブエージェントの添付ファイルは、子ワークスペース内の .openclaw/attachments/<uuid>/ に .manifest.json とともに実体化されます。
• ACP の添付ファイルは画像のみで、同じファイル数、ファイル単位のバイト数、合計バイト数の制限を通過した後、ACP ランタイムにインラインで転送されます。
• 添付ファイルの内容は、トランスクリプトの永続化時に自動的に秘匿化されます。
• Base64 入力は、厳格なアルファベット／パディングチェックとデコード前のサイズガードによって検証されます。
• サブエージェントの添付ファイル権限は、ディレクトリでは 0700、ファイルでは 0600 です。
• サブエージェントのクリーンアップは cleanup ポリシーに従います。delete は添付ファイルを常に削除し、keep は retainOnSessionKeep: true の場合にのみ保持します。

• カスタム認証が必要な場合は、authHeader: true + headers を使用します。
• OPENCLAW_AGENT_DIR でエージェント設定のルートを上書きします。
• 一致するプロバイダー ID のマージ優先順位:
  • 空でないエージェントの models.json baseUrl 値が優先されます。
  • 空でないエージェントの apiKey 値は、現在の設定または認証プロファイルのコンテキストで、そのプロバイダーが SecretRef によって管理されていない場合にのみ優先されます。
  • SecretRef で管理されるプロバイダーの apiKey 値は、解決済みのシークレットを永続化する代わりに、ソースマーカー（環境変数参照の場合は ENV_VAR_NAME、ファイルまたは実行参照の場合は secretref-managed）から更新されます。
  • SecretRef で管理されるプロバイダーのヘッダー値は、ソースマーカー（環境変数参照の場合は secretref-env:ENV_VAR_NAME、ファイルまたは実行参照の場合は secretref-managed）から更新されます。
  • エージェントの apiKey/baseUrl が空または欠落している場合は、設定の models.providers にフォールバックします。
  • 一致するモデルの contextWindow/maxTokens: 明示的な設定値が存在し、有効（正の有限数）である場合はその値が優先されます。それ以外の場合は、暗黙的または生成されたカタログ値が使用されます。
  • 一致するモデルの contextTokens も同じ「明示値があれば優先し、それ以外は暗黙値」というルールに従います。ネイティブモデルのメタデータを変更せずに有効なコンテキストを制限するには、これを使用します。
  • プロバイダー Plugin のカタログは、エージェントの Plugin 状態内に生成された Plugin 所有のカタログシャードとして保存されます。
  • 設定で models.json を完全に書き換え、Plugin 所有のカタログシャードをマージしない場合は、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、openai-chatgpt-responses、anthropic-messages、google-generative-ai、google-vertex、github-copilot、bedrock-converse-stream、ollama、azure-openai-responses）。MLX、vLLM、SGLang、およびほとんどの OpenAI 互換ローカルサーバーなど、セルフホストの /v1/chat/completions バックエンドには openai-completions を使用します。baseUrl があり、api がないカスタムプロバイダーは、デフォルトで openai-completions を使用します。バックエンドが /v1/responses をサポートする場合にのみ、openai-responses を設定してください。
• models.providers.*.apiKey: プロバイダーの認証情報（SecretRef または環境変数置換を推奨）。
• 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 フェッチガードを通じて、プライベート、CGNAT、または同様の範囲へのモデルプロバイダー HTTP リクエストを許可します。カスタムまたはローカルプロバイダーのベース URL は、メタデータまたはリンクローカルのオリジンを除き、設定された正確なオリジンをすでに信頼します。これらのオリジンは明示的にオプトインしない限り、引き続きブロックされます。正確なオリジンの信頼をオプトアウトするには、これを false に設定します。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 には両方の値が表示されます。

カスタムプロバイダーの機能宣言

プロバイダーカタログは、同梱モデルおよびカタログで既知のモデルルートに対する compat を所有します。これらのフラグを設定にコピーしないでください。設定された api と baseUrl が引き続きそのルートを識別する場合、OpenClaw はカタログ行を使用します。openclaw doctor --fix は一致するレガシー上書きを削除し、確認が必要な相違値を報告します。

compat ブロックは、真にカスタムなプロバイダー、カスタムモデル、または別のエンドポイントにルーティングされるカタログモデルで引き続きサポートされます。そのエンドポイントに対して検証済みの機能のみを設定してください。

• 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-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

MINIMAX_API_KEY を設定します。ショートカット: openclaw onboard --auth-choice minimax-global-api または openclaw onboard --auth-choice minimax-cn-api。モデルカタログのデフォルトは M3 で、M2.7 の各バリアントも含まれます。Anthropic 互換のストリーミング経路では、thinking を明示的に設定しない限り、OpenClaw はデフォルトで MiniMax M2.x の思考を無効にします。MiniMax-M3（および M3.x）は、デフォルトでプロバイダーの省略時／適応型思考の経路を維持します。/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-M3" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M3": { alias: "MiniMax M3" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 262144,            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 を設定します。モデル参照では、正規の zai/* プロバイダー ID を使用します。ショートカット: openclaw onboard --auth-choice zai-api-key。

• 汎用エンドポイント: https://api.z.ai/api/paas/v4
• コーディング用エンドポイント: https://api.z.ai/api/coding/paas/v4
• デフォルトの zai-api-key 認証オプションではキーを検証し、そのキーが属するエンドポイントを自動検出します（検出結果が不確かな場合は確認プロンプトにフォールバックし、デフォルトで Global を選択します）。明示的に選択できる専用の CN および Coding-Plan 認証オプションもあります。
• 汎用エンドポイントを使用する場合は、ベース URL を上書きしたカスタムプロバイダーを定義します。