Konfiguration — Tools und benutzerdefinierte Provider

Provider-Eintrag (type: "provider" oder weggelassen):

• provider: ID des API-Providers (openai, anthropic, google/gemini, groq usw.)
• model: Überschreibung der Modell-ID
• profile / preferredProfile: Profilauswahl aus auth-profiles.json

CLI-Eintrag (type: "cli"):

• command: auszuführbare Datei
• args: vorlagenbasierte Argumente (unterstützt {{MediaPath}}, {{Prompt}}, {{MaxChars}} usw.; openclaw doctor --fix migriert veraltete {input}-Platzhalter zu {{MediaPath}})

Gemeinsame Felder:

• capabilities: optionale Liste (image, audio, video). Jedes Provider-Plugin deklariert seinen eigenen Standardsatz an Fähigkeiten; beispielsweise verwendet der gebündelte openai-Provider standardmäßig Bild+Audio, anthropic/minimax Bild, google Bild+Audio+Video und groq Audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: Überschreibungen je Eintrag.
• tools.media.image.timeoutSeconds und entsprechende timeoutSeconds-Einträge des Bildmodells gelten auch, wenn der Agent das explizite image-Tool aufruft. Für das Bildverständnis gilt diese Zeitüberschreitung für die Anfrage selbst und wird nicht durch vorherige Vorbereitungsarbeiten verkürzt.
• Bei Fehlern wird auf den nächsten Eintrag zurückgegriffen.

Die Provider-Authentifizierung folgt der Standardreihenfolge: auth-profiles.json → Umgebungsvariablen → models.providers.*.apiKey.

Felder für den asynchronen Abschluss:

• asyncCompletion.directSend: veraltetes Kompatibilitätsflag. Abgeschlossene asynchrone Medienaufgaben bleiben über die Sitzung des Anforderers vermittelt, sodass der Agent das Ergebnis erhält, entscheidet, wie er es dem Benutzer mitteilt, und das Nachrichten-Tool verwendet, wenn die Zustellung an die Quelle dies erfordert.

• self: nur der Schlüssel der aktuellen Sitzung.
• tree: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Subagenten).
• agent: jede Sitzung, die zur aktuellen Agenten-ID gehört (kann andere Benutzer einschließen, wenn Sie Sitzungen je Absender unter derselben Agenten-ID ausführen).
• all: jede Sitzung. Die agentenübergreifende Zielauswahl erfordert weiterhin tools.agentToAgent.
• Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox ausgeführt wird und agents.defaults.sandbox.sessionToolsVisibility="spawned" (der Standardwert) gilt, wird die Sichtbarkeit auf tree festgelegt, selbst wenn tools.sessions.visibility="all" gesetzt ist.
• Wenn der Wert nicht all ist, enthält sessions_list ein kompaktes Feld visibility, das den effektiven Modus beschreibt und davor warnt, dass einige Sitzungen außerhalb des aktuellen Bereichs möglicherweise ausgelassen werden.

• Anhänge erfordern enabled: true.
• Subagenten-Anhänge werden im untergeordneten Arbeitsbereich unter .openclaw/attachments/<uuid>/ mit einer .manifest.json bereitgestellt.
• ACP-Anhänge unterstützen nur Bilder und werden nach erfolgreicher Prüfung derselben Grenzwerte für Dateianzahl, Bytes pro Datei und Gesamtbytes eingebettet an die ACP-Laufzeit weitergeleitet.
• Der Inhalt von Anhängen wird bei der dauerhaften Speicherung des Transkripts automatisch geschwärzt.
• Base64-Eingaben werden mit strengen Prüfungen von Alphabet und Auffüllzeichen sowie einer Größenprüfung vor der Dekodierung validiert.
• Die Dateiberechtigungen für Subagenten-Anhänge sind 0700 für Verzeichnisse und 0600 für Dateien.
• Die Bereinigung von Subagenten folgt der Richtlinie cleanup: delete entfernt Anhänge immer; keep behält sie nur bei, wenn retainOnSessionKeep: true gilt.

• Verwenden Sie authHeader: true + headers für benutzerdefinierte Authentifizierungsanforderungen.
• Überschreiben Sie das Stammverzeichnis der Agent-Konfiguration mit OPENCLAW_AGENT_DIR.
• Zusammenführungspriorität für übereinstimmende Provider-IDs:
  • Nicht leere baseUrl-Werte aus der models.json des Agenten haben Vorrang.
  • Nicht leere apiKey-Werte des Agenten haben nur dann Vorrang, wenn dieser Provider im aktuellen Konfigurations-/Authentifizierungsprofil-Kontext nicht von SecretRef verwaltet wird.
  • Von SecretRef verwaltete apiKey-Werte des Providers werden anhand von Quellmarkierungen (ENV_VAR_NAME für Umgebungsreferenzen, secretref-managed für Datei-/Exec-Referenzen) aktualisiert, anstatt aufgelöste Geheimnisse dauerhaft zu speichern.
  • Von SecretRef verwaltete Header-Werte des Providers werden anhand von Quellmarkierungen (secretref-env:ENV_VAR_NAME für Umgebungsreferenzen, secretref-managed für Datei-/Exec-Referenzen) aktualisiert.
  • Leere oder fehlende apiKey-/baseUrl-Werte des Agenten greifen auf models.providers in der Konfiguration zurück.
  • Bei übereinstimmenden Modellwerten für contextWindow/maxTokens hat der explizite Konfigurationswert Vorrang, wenn er vorhanden und gültig ist (eine positive endliche Zahl); andernfalls wird der implizite/generierte Katalogwert verwendet.
  • Für contextTokens eines übereinstimmenden Modells gilt dieselbe Regel „explizit vor implizit“; verwenden Sie diesen Wert, um den effektiven Kontext zu begrenzen, ohne die nativen Modellmetadaten zu ändern.
  • Kataloge von Provider-Plugins werden als generierte, dem Plugin gehörende Katalog-Shards im Plugin-Zustand des Agenten gespeichert.
  • Verwenden Sie models.mode: "replace", wenn die Konfiguration models.json vollständig neu schreiben und die Zusammenführung von Katalog-Shards im Besitz von Plugins überspringen soll.
  • Die dauerhafte Speicherung von Markierungen richtet sich verbindlich nach der Quelle: Markierungen werden aus dem aktiven Snapshot der Quellkonfiguration (vor der Auflösung) geschrieben, nicht aus aufgelösten Geheimniswerten der Laufzeit.

• models.mode: Verhalten des Provider-Katalogs (merge oder replace).
• models.providers: benutzerdefinierte Provider-Zuordnung, nach Provider-ID verschlüsselt.
  • Sichere Änderungen: Verwenden Sie openclaw config set models.providers.<id> '<json>' --strict-json --merge oder openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge für additive Aktualisierungen. config set lehnt destruktive Ersetzungen ab, sofern Sie nicht --replace übergeben.

• models.providers.*.api: Anfrageadapter (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). Verwenden Sie für selbst gehostete /v1/chat/completions-Backends wie MLX, vLLM, SGLang und die meisten OpenAI-kompatiblen lokalen Server openai-completions. Ein benutzerdefinierter Provider mit baseUrl, aber ohne api, verwendet standardmäßig openai-completions; legen Sie openai-responses nur fest, wenn das Backend /v1/responses unterstützt.
• models.providers.*.apiKey: Provider-Zugangsdaten (SecretRef-/Umgebungsersetzung bevorzugt).
• models.providers.*.auth: Authentifizierungsstrategie (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: standardmäßiges natives Kontextfenster für Modelle dieses Providers, wenn der Modelleintrag contextWindow nicht festlegt.
• models.providers.*.contextTokens: standardmäßige effektive Laufzeit-Kontextobergrenze für Modelle dieses Providers, wenn der Modelleintrag contextTokens nicht festlegt.
• models.providers.*.maxTokens: standardmäßige Ausgabetoken-Obergrenze für Modelle dieses Providers, wenn der Modelleintrag maxTokens nicht festlegt.
• models.providers.*.timeoutSeconds: optionales Provider-spezifisches Zeitlimit in Sekunden für Modell-HTTP-Anfragen, einschließlich Verbindungsaufbau, Headern, Body und Behandlung des Abbruchs der Gesamtanfrage.
• models.providers.*.injectNumCtxForOpenAICompat: Fügt für Ollama + openai-completions options.num_ctx in Anfragen ein (Standard: true).
• models.providers.*.authHeader: Erzwingt bei Bedarf die Übertragung der Zugangsdaten im Authorization-Header.
• models.providers.*.baseUrl: Basis-URL der vorgelagerten API.
• models.providers.*.headers: zusätzliche statische Header für Proxy-/Mandanten-Routing.

models.providers.*.request: Transportüberschreibungen für HTTP-Anfragen an Modell-Provider.

• request.headers: zusätzliche Header (mit den Provider-Standardwerten zusammengeführt). Die Werte akzeptieren SecretRef.
• request.auth: Überschreibung der Authentifizierungsstrategie. Modi: "provider-default" (integrierte Authentifizierung des Providers verwenden), "authorization-bearer" (mit token), "header" (mit headerName, value, optional prefix).
• request.proxy: Überschreibung des HTTP-Proxys. Modi: "env-proxy" (Umgebungsvariablen HTTP_PROXY/HTTPS_PROXY verwenden), "explicit-proxy" (mit url). Beide Modi akzeptieren ein optionales tls-Unterobjekt.
• request.tls: TLS-Überschreibung für direkte Verbindungen. Felder: ca, cert, key, passphrase (alle akzeptieren SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: Wenn true, werden HTTP-Anfragen an Modell-Provider durch die HTTP-Abrufsicherung des Providers an private, CGNAT- oder ähnliche Bereiche zugelassen. Benutzerdefinierte/lokale Basis-URLs von Providern vertrauen bereits exakt dem konfigurierten Ursprung; ausgenommen sind Metadaten-/Link-Local-Ursprünge, die ohne ausdrückliche Zustimmung weiterhin blockiert bleiben. Setzen Sie dies auf false, um das Vertrauen in den exakten Ursprung zu deaktivieren. WebSocket verwendet dieselbe request-Konfiguration für Header/TLS, jedoch nicht diese SSRF-Sicherung für Abrufe. Standard: false.

• models.providers.*.models: explizite Modellkatalogeinträge des Providers.
• models.providers.*.models.*.input: Eingabemodalitäten des Modells. Verwenden Sie ["text"] für reine Textmodelle und ["text", "image"] für native Bild-/Vision-Modelle. Bildanhänge werden nur in Agent-Durchläufe eingefügt, wenn das ausgewählte Modell als bildfähig gekennzeichnet ist.
• models.providers.*.models.*.contextWindow: Metadaten des nativen Modellkontextfensters. Dies überschreibt für dieses Modell contextWindow auf Provider-Ebene.
• models.providers.*.models.*.contextTokens: optionale Laufzeit-Kontextobergrenze. Dies überschreibt contextTokens auf Provider-Ebene; verwenden Sie den Wert, wenn Sie ein kleineres effektives Kontextbudget als das native contextWindow des Modells wünschen; openclaw models list zeigt beide Werte an, wenn sie voneinander abweichen.
• models.providers.*.models.*.compat.supportsDeveloperRole: optionaler Kompatibilitätshinweis. Bei api: "openai-completions" mit einer nicht leeren, nicht nativen baseUrl (Host ist nicht api.openai.com) erzwingt OpenClaw zur Laufzeit den Wert false. Eine leere/ausgelassene baseUrl behält das standardmäßige OpenAI-Verhalten bei.
• models.providers.*.models.*.compat.requiresStringContent: optionaler Kompatibilitätshinweis für ausschließlich Zeichenfolgen unterstützende OpenAI-kompatible Chat-Endpunkte. Wenn true, wandelt OpenClaw reine Textarrays vom Typ messages[].content vor dem Senden der Anfrage in einfache Zeichenfolgen um.
• models.providers.*.models.*.compat.strictMessageKeys: optionaler Kompatibilitätshinweis für strikte OpenAI-kompatible Chat-Endpunkte. Wenn true, reduziert OpenClaw ausgehende Chat-Completions-Nachrichtenobjekte vor dem Senden der Anfrage auf role und content.
• models.providers.*.models.*.compat.thinkingFormat: optionaler Hinweis zum Thinking-Payload. Verwenden Sie "together" für reasoning.enabled im Together-Stil, "qwen" für enable_thinking auf oberster Ebene oder "qwen-chat-template" für chat_template_kwargs.enable_thinking auf OpenAI-kompatiblen Servern der Qwen-Familie, die Chat-Template-Kwargs auf Anfrageebene unterstützen, beispielsweise vLLM. Konfigurierte Qwen-Modelle von vLLM stellen für diese Formate binäre /think-Optionen (off, on) bereit.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: optionaler Kompatibilitätshinweis für Chat-Completions-Backends im DeepSeek-Stil, die verlangen, dass vorherige Assistentennachrichten bei der erneuten Wiedergabe reasoning_content beibehalten. Wenn true, bewahrt OpenClaw dieses Feld in ausgehenden Assistentennachrichten. Verwenden Sie dies beim Einrichten eines benutzerdefinierten DeepSeek-kompatiblen Proxys, der Anfragen nach dem Entfernen der Reasoning-Inhalte ablehnt. Standard: false.

• plugins.entries.amazon-bedrock.config.discovery: Stamm der Einstellungen für die automatische Bedrock-Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.enabled: implizite Erkennung ein-/ausschalten.
• plugins.entries.amazon-bedrock.config.discovery.region: AWS-Region für die Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: optionaler Provider-ID-Filter für eine gezielte Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: Abfrageintervall für die Aktualisierung der Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: Ersatz-Kontextfenster für erkannte Modelle.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: maximale Anzahl an Ausgabetoken als Ersatzwert für erkannte Modelle.

Das offizielle externe Provider-Plugin cerebras kann dies über openclaw onboard --auth-choice cerebras-api-key konfigurieren. Verwenden Sie eine explizite Provider-Konfiguration nur, wenn Sie Standardwerte überschreiben.

{  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)" },        ],      },    },  },}

Verwenden Sie cerebras/zai-glm-4.7 für Cerebras und zai/glm-4.7 für den direkten Zugriff auf Z.AI.

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

Anthropic-kompatibler, integrierter Provider. Kurzform: openclaw onboard --auth-choice kimi-code-api-key.

Siehe Lokale Modelle. Kurz gesagt: Führen Sie über die LM Studio Responses API auf leistungsfähiger Hardware ein großes lokales Modell aus; führen Sie gehostete Modelle weiterhin zusammen, um einen Fallback bereitzustellen.

{  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,          },        ],      },    },  },}

Setzen Sie MINIMAX_API_KEY. Kurzbefehle: openclaw onboard --auth-choice minimax-global-api oder openclaw onboard --auth-choice minimax-cn-api. Der Modellkatalog verwendet standardmäßig M3 und enthält außerdem die M2.7-Varianten. Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw standardmäßig das Thinking von MiniMax M2.x, sofern Sie thinking nicht ausdrücklich selbst festlegen; MiniMax-M3 (und M3.x) verbleibt standardmäßig auf dem ausgelassenen/adaptiven Thinking-Pfad des Providers. /fast on oder params.fastMode: true schreibt MiniMax-M2.7 in MiniMax-M2.7-highspeed um.

{  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,          },        ],      },    },  },}

Für den China-Endpunkt: baseUrl: "https://api.moonshot.cn/v1" oder openclaw onboard --auth-choice moonshot-api-key-cn.

Native Moonshot-Endpunkte geben auf dem gemeinsam verwendeten openai-completions-Transport Kompatibilität mit der Streaming-Nutzungsstatistik an, und OpenClaw richtet dieses Verhalten nach den Endpunktfunktionen aus statt allein nach der integrierten Provider-ID.

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

Setzen Sie OPENCODE_API_KEY (oder OPENCODE_ZEN_API_KEY). Verwenden Sie opencode/...-Referenzen für den Zen-Katalog oder opencode-go/...-Referenzen für den Go-Katalog. Kurzbefehl: openclaw onboard --auth-choice opencode-zen oder 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,          },        ],      },    },  },}

Die Basis-URL sollte /v1 weglassen (der Anthropic-Client hängt es an). Kurzbefehl: openclaw onboard --auth-choice synthetic-api-key.

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

Setzen Sie ZAI_API_KEY. Modellreferenzen verwenden die kanonische Provider-ID zai/*. Kurzbefehl: openclaw onboard --auth-choice zai-api-key.

• Allgemeiner Endpunkt: https://api.z.ai/api/paas/v4
• Coding-Endpunkt: https://api.z.ai/api/coding/paas/v4
• Die standardmäßige Authentifizierungsauswahl zai-api-key prüft Ihren Schlüssel und erkennt automatisch, zu welchem Endpunkt er gehört (wenn die Erkennung kein eindeutiges Ergebnis liefert, wird auf eine Eingabeaufforderung zurückgegriffen, deren Standardwert Global ist). Für eine explizite Auswahl stehen außerdem separate Authentifizierungsauswahlen für CN und den Coding-Plan zur Verfügung.
• Definieren Sie für den allgemeinen Endpunkt einen benutzerdefinierten Provider mit überschriebener Basis-URL.