Konfiguration — Tools und benutzerdefinierte Provider

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

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

CLI-Eintrag (type: "cli"):

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

Gemeinsame Felder:

• capabilities: Liste mit einem oder mehreren der Werte image, audio und video.
• prompt, maxChars, maxBytes, timeoutSeconds, language: eintragsspezifische Überschreibungen.
• Übereinstimmende timeoutSeconds-Einträge für Bildmodelle gelten auch, wenn der Agent das explizite image-Tool aufruft. Für die Bildverarbeitung gilt dieses Zeitlimit 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.

• self: nur der Schlüssel der aktuellen Sitzung.
• tree: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Subagenten). Bei Lesevorgängen umfasst dies außerdem Gruppensitzungen desselben Agenten, welche die aktuelle Sitzung über die nebenläufige Gruppenwahrnehmung beobachtet.
• agent: jede Sitzung, die zur aktuellen Agenten-ID gehört (kann andere Benutzer einschließen, wenn Sie absenderspezifische Sitzungen unter derselben Agenten-ID ausführen).
• all: jede Sitzung. Agentenübergreifender Zugriff erfordert weiterhin tools.agentToAgent.
• Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox ausgeführt wird und agents.defaults.sandbox.sessionToolsVisibility="spawned" gilt (der Standardwert), wird die Sichtbarkeit auf tree beschränkt, selbst wenn tools.sessions.visibility="all" festgelegt ist.
• Wenn nicht all, enthält sessions_list ein kompaktes visibility-Feld, das den wirksamen Modus beschreibt und darauf hinweist, dass einige Sitzungen außerhalb des aktuellen Geltungsbereichs möglicherweise nicht enthalten sind.

• Anhänge erfordern enabled: true.
• Anhänge von Subagenten werden unter .openclaw/attachments/<uuid>/ mit einem .manifest.json im untergeordneten Arbeitsbereich bereitgestellt.
• ACP-Anhänge sind ausschließlich Bilder und werden inline an die ACP-Laufzeit weitergeleitet, nachdem dieselben Grenzwerte für Dateianzahl, Bytes pro Datei und Gesamtbytes eingehalten wurden.
• Der Inhalt von Anhängen wird automatisch aus der dauerhaften Transkriptspeicherung entfernt.
• Base64-Eingaben werden durch strenge Prüfungen von Alphabet und Auffüllung sowie eine Größenprüfung vor der Dekodierung validiert.
• Die Dateiberechtigungen für Anhänge von Subagenten sind 0700 für Verzeichnisse und 0600 für Dateien.
• Die Bereinigung von Subagenten folgt der cleanup-Richtlinie: delete entfernt Anhänge immer; keep behält sie nur bei, wenn retainOnSessionKeep: true.

• Verwenden Sie authHeader: true + headers für benutzerdefinierte Authentifizierungsanforderungen.
• Überschreiben Sie das Stammverzeichnis der Agentenkonfiguration mit OPENCLAW_AGENT_DIR.
• Zusammenführungsrangfolge für übereinstimmende Provider-IDs:
  • Nicht leere models.json-baseUrl-Werte des Agenten haben Vorrang.
  • Nicht leere apiKey-Werte des Agenten haben nur dann Vorrang, wenn dieser Provider im aktuellen Konfigurations-/Authentifizierungsprofilkontext nicht von SecretRef verwaltet wird.
  • Von SecretRef verwaltete apiKey-Werte des Providers werden anhand von Quellmarkierungen aktualisiert (ENV_VAR_NAME für Umgebungsreferenzen, secretref-managed für Datei-/Ausführungsreferenzen), statt aufgelöste Geheimnisse dauerhaft zu speichern.
  • Von SecretRef verwaltete Provider-Headerwerte werden anhand von Quellmarkierungen aktualisiert (secretref-env:ENV_VAR_NAME für Umgebungsreferenzen, secretref-managed für Datei-/Ausführungsreferenzen).
  • Leere oder fehlende apiKey/baseUrl des Agenten greifen auf models.providers in der Konfiguration zurück.
  • Übereinstimmende Modellwerte für contextWindow/maxTokens: Der explizite Konfigurationswert hat Vorrang, wenn er vorhanden und gültig ist (eine positive endliche Zahl); andernfalls wird der implizite/generierte Katalogwert verwendet.
  • Übereinstimmendes Modell-contextTokens folgt derselben Regel „explizit hat Vorrang, andernfalls implizit“; verwenden Sie es, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern.
  • Kataloge von Provider-Plugins werden als generierte, Plugin-eigene Katalogfragmente im Plugin-Status des Agenten gespeichert.
  • Verwenden Sie models.mode: "replace", wenn die Konfiguration models.json vollständig neu schreiben und die Zusammenführung Plugin-eigener Katalogfragmente überspringen soll.
  • Die dauerhafte Speicherung von Markierungen richtet sich maßgeblich nach der Quelle: Markierungen werden aus dem aktiven Snapshot der Quellkonfiguration (vor der Auflösung) und nicht aus aufgelösten Laufzeitwerten von Geheimnissen geschrieben.

• models.mode: Verhalten des Provider-Katalogs (merge oder replace).
• models.providers: nach Provider-ID indizierte Zuordnung benutzerdefinierter Provider.
  • 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-Anmeldedaten (SecretRef-/Umgebungsersetzung bevorzugen).
• 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: optionale HTTP-Anfragezeitüberschreitung pro Provider und Modell in Sekunden, einschließlich Verbindung, Headern, Body und Behandlung des Abbruchs der gesamten Anfrage.
• models.providers.*.injectNumCtxForOpenAICompat: Fügt bei Ollama + openai-completions den Wert options.num_ctx in Anfragen ein (Standard: true).
• models.providers.*.authHeader: Erzwingt bei Bedarf die Übertragung von Anmeldedaten im Authorization-Header.
• models.providers.*.baseUrl: Basis-URL der vorgelagerten API.
• models.providers.*.headers: zusätzliche statische Header für Proxy-/Mandantenrouting.

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

• request.headers: zusätzliche Header (mit Provider-Standardwerten zusammengeführt). 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: HTTP-Proxy-Überschreibung. 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 zu privaten, CGNAT- oder ähnlichen Bereichen über die HTTP-Abrufsicherung des Providers zugelassen. Basis-URLs benutzerdefinierter/lokaler Provider vertrauen bereits dem exakt konfigurierten Ursprung, mit Ausnahme von Metadaten-/Link-Local-Ursprüngen, die ohne explizites Opt-in weiterhin blockiert bleiben. Setzen Sie dies auf false, um das Vertrauen in den exakten Ursprung zu deaktivieren. WebSocket verwendet dieselben request für Header/TLS, jedoch nicht diese Abrufsicherung gegen SSRF. Standard: false.

• models.providers.*.models: explizite Modellkatalogeinträge des Providers.
• models.providers.*.models.*.input: Modelleingabemodalitäten. Verwenden Sie ["text"] für reine Textmodelle und ["text", "image"] für native Bild-/Vision-Modelle. Bildanhänge werden nur dann in Agentendurchläufe eingefügt, wenn das ausgewählte Modell als bildfähig gekennzeichnet ist.
• models.providers.*.models.*.contextWindow: Metadaten des nativen Modellkontextfensters. Dies überschreibt contextWindow auf Provider-Ebene für dieses Modell.
• models.providers.*.models.*.contextTokens: optionale Laufzeit-Kontextobergrenze. Dies überschreibt contextTokens auf Provider-Ebene; verwenden Sie sie, 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.

Funktionsdeklarationen für benutzerdefinierte Provider

Provider-Kataloge besitzen compat für gebündelte und katalogbekannte Modellrouten. Kopieren Sie diese Flags nicht in die Konfiguration: OpenClaw verwendet die Katalogzeile, solange die konfigurierten api und baseUrl weiterhin diese Route identifizieren. openclaw doctor --fix entfernt übereinstimmende veraltete Überschreibungen und meldet abweichende Werte zur Überprüfung.

Ein compat-Block wird weiterhin für einen tatsächlich benutzerdefinierten Provider, ein benutzerdefiniertes Modell oder ein zu einem anderen Endpunkt geroutetes Katalogmodell unterstützt. Legen Sie nur Funktionen fest, die für diesen Endpunkt verifiziert wurden:

• plugins.entries.amazon-bedrock.config.discovery: Stammeinstellung für die automatische Bedrock-Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.enabled: implizite Erkennung aktivieren/deaktivieren.
• 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 die gezielte Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: Abfrageintervall für die Aktualisierung der Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: Ersatzwert für das Kontextfenster erkannter Modelle.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: Ersatzwert für die maximale Anzahl an Ausgabe-Tokens erkannter 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 auf leistungsfähiger Hardware ein großes lokales Modell über die LM Studio Responses API aus; behalten Sie gehostete Modelle zusammengeführt als Rückfalloption bei.

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

Legen Sie MINIMAX_API_KEY fest. Kurzformen: 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. Beim Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw das Thinking von MiniMax M2.x standardmäßig, sofern Sie thinking nicht selbst explizit festlegen; MiniMax-M3 (und M3.x) verbleibt standardmäßig auf dem vom Provider vorgegebenen Pfad für ausgelassenes/adaptives Thinking. /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 die Kompatibilität der Streaming-Nutzungsdaten für den gemeinsam verwendeten openai-completions-Transport an, und OpenClaw richtet sich dabei nach den Endpunktfähigkeiten statt ausschließlich nach der integrierten Provider-ID.

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

Legen Sie OPENCODE_API_KEY (oder OPENCODE_ZEN_API_KEY) fest. Verwenden Sie opencode/...-Referenzen für den Zen-Katalog oder opencode-go/...-Referenzen für den Go-Katalog. Kurzform: 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-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,          },        ],      },    },  },}

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

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

Legen Sie ZAI_API_KEY fest. Modellreferenzen verwenden die kanonische Provider-ID zai/*. Kurzform: 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 Authentifizierungsoption zai-api-key prüft Ihren Schlüssel und erkennt automatisch, zu welchem Endpunkt er gehört. Falls die Erkennung kein eindeutiges Ergebnis liefert, wird eine Abfrage angezeigt, deren Standardwert Global ist. Für eine explizite Auswahl stehen außerdem spezielle Authentifizierungsoptionen für CN und den Coding-Plan zur Verfügung.
• Definieren Sie für den allgemeinen Endpunkt einen benutzerdefinierten Provider mit überschriebener Basis-URL.