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: 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). Standardwerte: openai/anthropic/minimax → Bild, google → Bild+Audio+Video, groq → Audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: Überschreibungen pro Eintrag.
• tools.media.image.timeoutSeconds und passende timeoutSeconds-Einträge für Bildmodelle gelten auch, wenn der Agent das explizite image-Tool aufruft.
• Fehler fallen auf den nächsten Eintrag zurück.

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

Felder für asynchrone Fertigstellung:

• asyncCompletion.directSend: veraltetes Kompatibilitäts-Flag. Abgeschlossene asynchrone Medienaufgaben bleiben über die anfragende Sitzung vermittelt, sodass der Agent das Ergebnis erhält, entscheidet, wie er den Benutzer informiert, und das Nachrichtentool verwendet, wenn die Quelldelivery dies erfordert.

• self: nur der aktuelle Sitzungsschlüssel.
• tree: aktuelle Sitzung + Sitzungen, die von der aktuellen Sitzung gestartet wurden (Subagents).
• agent: jede Sitzung, die zur aktuellen Agent-ID gehört (kann andere Benutzer einschließen, wenn Sie sitzungsbezogene Sitzungen pro Absender unter derselben Agent-ID ausführen).
• all: jede Sitzung. Agent-übergreifende Adressierung erfordert weiterhin tools.agentToAgent.
• Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox ausgeführt wird und agents.defaults.sandbox.sessionToolsVisibility="spawned" ist, wird die Sichtbarkeit auf tree erzwungen, auch wenn tools.sessions.visibility="all" ist.

• Anhänge werden nur für runtime: "subagent" unterstützt. Die ACP-Laufzeit lehnt sie ab.
• Dateien werden im untergeordneten Arbeitsbereich unter .openclaw/attachments/<uuid>/ mit einer .manifest.json materialisiert.
• Anhangsinhalte werden automatisch aus der Transcript-Persistenz redigiert.
• Base64-Eingaben werden mit strengen Prüfungen von Alphabet/Polsterung und einer Größenbegrenzung vor dem Dekodieren validiert.
• Dateiberechtigungen sind 0700 für Verzeichnisse und 0600 für Dateien.
• Die Bereinigung folgt der cleanup-Richtlinie: delete entfernt Anhänge immer; keep behält sie nur bei, wenn retainOnSessionKeep: true gesetzt ist.

• Verwenden Sie authHeader: true + headers für benutzerdefinierte Authentifizierungsanforderungen.
• Überschreiben Sie den Stamm der Agent-Konfiguration mit OPENCLAW_AGENT_DIR (oder PI_CODING_AGENT_DIR, einem Alias einer älteren Umgebungsvariable).
• Zusammenführungspriorität für übereinstimmende Provider-IDs:
  • Nicht leere Agent-models.json-baseUrl-Werte gewinnen.
  • Nicht leere Agent-apiKey-Werte gewinnen nur, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profil-Kontext nicht SecretRef-verwaltet ist.
  • SecretRef-verwaltete Provider-apiKey-Werte werden aus Quellmarkern (ENV_VAR_NAME für Env-Referenzen, secretref-managed für Datei-/Exec-Referenzen) aktualisiert, anstatt aufgelöste Secrets persistent zu speichern.
  • SecretRef-verwaltete Provider-Header-Werte werden aus Quellmarkern aktualisiert (secretref-env:ENV_VAR_NAME für Env-Referenzen, secretref-managed für Datei-/Exec-Referenzen).
  • Leere oder fehlende Agent-apiKey/baseUrl fallen auf models.providers in der Konfiguration zurück.
  • Übereinstimmende Modellwerte contextWindow/maxTokens verwenden den höheren Wert aus expliziter Konfiguration und impliziten Katalogwerten.
  • Übereinstimmende Modellwerte contextTokens behalten eine explizite Laufzeitobergrenze bei, wenn vorhanden; verwenden Sie sie, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern.
  • Verwenden Sie models.mode: "replace", wenn die Konfiguration models.json vollständig neu schreiben soll.
  • Marker-Persistenz ist quellenautoritativ: Marker werden aus dem aktiven Quellkonfigurations-Snapshot (vor der Auflösung) geschrieben, nicht aus aufgelösten Laufzeit-Secret-Werten.

• models.mode: Verhalten des Provider-Katalogs (merge oder replace).
• models.providers: benutzerdefinierte Provider-Map, indiziert nach Provider-ID.
  • 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 verweigert destruktive Ersetzungen, sofern Sie nicht --replace übergeben.

• models.providers.*.api: Request-Adapter (openai-completions, openai-responses, anthropic-messages, google-generative-ai usw.). Für selbst gehostete /v1/chat/completions-Backends wie MLX, vLLM, SGLang und die meisten OpenAI-kompatiblen lokalen Server verwenden Sie openai-completions. Ein benutzerdefinierter Provider mit baseUrl, aber ohne api, verwendet standardmäßig openai-completions; setzen Sie openai-responses nur, wenn das Backend /v1/responses unterstützt.
• models.providers.*.apiKey: Provider-Zugangsdaten (SecretRef-/Env-Ersetzung bevorzugt).
• models.providers.*.auth: Authentifizierungsstrategie (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: standardmäßiges natives Kontextfenster für Modelle unter diesem Provider, wenn der Modelleintrag contextWindow nicht setzt.
• models.providers.*.contextTokens: standardmäßige effektive Laufzeit-Kontextobergrenze für Modelle unter diesem Provider, wenn der Modelleintrag contextTokens nicht setzt.
• models.providers.*.maxTokens: standardmäßige Obergrenze für Ausgabe-Token für Modelle unter diesem Provider, wenn der Modelleintrag maxTokens nicht setzt.
• models.providers.*.timeoutSeconds: optionaler HTTP-Request-Timeout pro Provider-Modell in Sekunden, einschließlich Verbindungsaufbau, Headern, Body und Behandlung des Abbruchs der gesamten Anfrage.
• models.providers.*.injectNumCtxForOpenAICompat: für Ollama + openai-completions wird options.num_ctx in Anfragen injiziert (Standard: true).
• models.providers.*.authHeader: erzwingt bei Bedarf den Transport von Zugangsdaten im Authorization-Header.
• models.providers.*.baseUrl: Basis-URL der Upstream-API.
• models.providers.*.headers: zusätzliche statische Header für Proxy-/Tenant-Routing.

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

• request.headers: zusätzliche Header (mit Provider-Standards 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" (Env-Variablen 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, wird HTTPS zu baseUrl erlaubt, wenn DNS auf private, CGNAT- oder ähnliche Bereiche auflöst, über den HTTP-Fetch-Guard des Providers (Operator-Opt-in für vertrauenswürdige selbst gehostete OpenAI-kompatible Endpunkte). Stream-URLs von local loopback-Modell-Providern wie localhost, 127.0.0.1 und [::1] werden automatisch zugelassen, sofern dies nicht explizit auf false gesetzt ist; LAN-, Tailnet- und private DNS-Hosts erfordern weiterhin ein Opt-in. WebSocket verwendet dieselbe request-Konfiguration für Header/TLS, aber nicht dieses Fetch-SSRF-Gate. 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 in Agent-Turns injiziert, wenn das ausgewählte Modell als bildfähig markiert ist.
• models.providers.*.models.*.contextWindow: Metadaten zum nativen Kontextfenster des Modells. 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 es, wenn Sie ein kleineres effektives Kontextbudget als das native contextWindow des Modells wünschen; openclaw models list zeigt beide Werte an, wenn sie sich unterscheiden.
• models.providers.*.models.*.compat.supportsDeveloperRole: optionaler Kompatibilitätshinweis. Für api: "openai-completions" mit einer nicht leeren, nicht nativen baseUrl (Host nicht api.openai.com) erzwingt OpenClaw dies zur Laufzeit auf false. Leere/ausgelassene baseUrl behält das standardmäßige OpenAI-Verhalten bei.
• models.providers.*.models.*.compat.requiresStringContent: optionaler Kompatibilitätshinweis für string-only OpenAI-kompatible Chat-Endpunkte. Wenn true, reduziert OpenClaw reine Text-messages[].content-Arrays vor dem Senden der Anfrage auf einfache Strings.

• plugins.entries.amazon-bedrock.config.discovery: Stamm der Bedrock-Auto-Discovery-Einstellungen.
• 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 gezielte Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: Polling-Intervall für die Aktualisierung der Erkennung.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: Fallback-Kontextfenster für erkannte Modelle.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: Fallback-Maximum für Ausgabe-Token für erkannte Modelle.

Das gebündelte Provider-Plugin cerebras kann dies über openclaw onboard --auth-choice cerebras-api-key konfigurieren. Verwenden Sie 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; zai/glm-4.7 für den direkten Zugriff auf Z.AI.

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

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

Siehe Lokale Modelle. Kurz gesagt: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsstarker Hardware aus; behalten Sie gehostete Modelle als zusammengeführte Fallbacks bei.

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

Setzen Sie MINIMAX_API_KEY. Kurzformen: openclaw onboard --auth-choice minimax-global-api oder openclaw onboard --auth-choice minimax-cn-api. Der Modellkatalog verwendet standardmäßig nur M2.7. Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw MiniMax Thinking standardmäßig, sofern Sie thinking nicht selbst explizit setzen. /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 Streaming-Usage-Kompatibilität auf dem gemeinsamen openai-completions-Transport an, und OpenClaw leitet dies aus den Endpunktfunktionen ab, nicht nur aus 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. 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-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). Kurzform: 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. z.ai/* und z-ai/* werden als Aliasse akzeptiert. Kurzform: openclaw onboard --auth-choice zai-api-key.

• Allgemeiner Endpunkt: https://api.z.ai/api/paas/v4
• Coding-Endpunkt (Standard): https://api.z.ai/api/coding/paas/v4
• Definieren Sie für den allgemeinen Endpunkt einen benutzerdefinierten Provider mit Überschreibung der Basis-URL.