FAQ: Modelle und Authentifizierung

Festgelegt wird es mit:

agents.defaults.model.primary

Modelle sind Referenzen im Format provider/model (Beispiel: openai/gpt-5.5, anthropic/claude-sonnet-4-6). Geben Sie provider/model immer explizit an. Wenn Sie den Provider weglassen, versucht OpenClaw zuerst, einen passenden Alias zu finden, dann eine eindeutige Übereinstimmung bei den konfigurierten Providern für diese Modell-ID und greift anschließend auf den konfigurierten Standard-Provider zurück (veralteter Kompatibilitätspfad). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, greift OpenClaw auf den ersten konfigurierten Provider mit Modell zurück statt auf eine veraltete Standardeinstellung.

Verwenden Sie das leistungsfähigste Modell der neuesten Generation, das Ihr Provider-Stack anbietet, insbesondere für Agenten mit Werkzeugzugriff oder nicht vertrauenswürdigen Eingaben — schwächere oder übermäßig quantisierte Modelle sind anfälliger für Prompt-Injection und unsicheres Verhalten (siehe Sicherheit). Leiten Sie routinemäßige Chats mit geringem Risiko abhängig von der Agentenrolle an günstigere Modelle weiter.

Leiten Sie Modelle agentenspezifisch weiter und verwenden Sie Unteragenten, um lange Aufgaben zu parallelisieren (jeder Unteragent verbraucht eigene Tokens). Siehe Modelle, Unteragenten, MiniMax und Lokale Modelle.

Ändern Sie nur die Modellfelder — vermeiden Sie den vollständigen Austausch der Konfiguration.

• /model im Chat (sitzungsspezifisch, siehe Slash-Befehle)
• openclaw models set ... (aktualisiert nur die Modellkonfiguration)
• openclaw configure --section model (interaktiv)
• bearbeiten Sie agents.defaults.model direkt in ~/.openclaw/openclaw.json

Prüfen Sie bei RPC-Änderungen zuerst mit config.schema.lookup (normalisierter Pfad, kurze Schemadokumentation, Zusammenfassungen untergeordneter Elemente) und verwenden Sie anschließend vorzugsweise config.patch mit einem partiellen Objekt statt config.apply. Falls Sie die Konfiguration überschrieben haben, stellen Sie sie aus einer Sicherung wieder her oder führen Sie zur Reparatur openclaw doctor aus.

Dokumentation: Modelle, Konfigurieren, Konfiguration, Doctor.

Ja — Ollama ist der einfachste Weg. Schnelle Einrichtung:

1. Installieren Sie Ollama von https://ollama.com/download
2. Laden Sie ein lokales Modell herunter, z. B. mit ollama pull gemma4
3. Führen Sie für Cloud-Modelle zusätzlich ollama signin aus
4. Führen Sie openclaw onboard aus, wählen Sie Ollama und anschließend Local oder Cloud + Local

Cloud + Local bietet Ihnen Cloud-Modelle sowie Ihre lokalen Ollama-Modelle; Cloud-Modelle wie kimi-k2.5:cloud müssen nicht lokal heruntergeladen werden. So wechseln Sie manuell: openclaw models list, dann openclaw models set ollama/<model>.

Kleinere/stark quantisierte Modelle sind anfälliger für Prompt-Injection. Verwenden Sie für jeden Bot mit Werkzeugzugriff große Modelle; wenn Sie dennoch kleine Modelle verwenden, aktivieren Sie Sandboxing und strikte Werkzeug-Zulassungslisten.

Dokumentation: Ollama, Lokale Modelle, Modell-Provider, Sicherheit, Sandboxing.

Senden Sie /model <name> als eigenständige Nachricht. Unter Slash-Befehle finden Sie die vollständige Befehlsliste, einschließlich der nummerierten Auswahl (/model, /model list, /model 3), /model default zum Löschen einer Sitzungsüberschreibung und /model status für Details zum Endpunkt/API-Modus.

Erzwingen Sie mit @profile ein bestimmtes Authentifizierungsprofil pro Sitzung:

/model opus@anthropic:default/model opus@anthropic:work

Um die Bindung eines mit @profile festgelegten Profils aufzuheben, führen Sie /model erneut ohne das Suffix aus (z. B. /model anthropic/claude-opus-4-6) oder wählen Sie den Standard aus /model. Verwenden Sie /model status, um das aktive Authentifizierungsprofil zu bestätigen.

/model provider/model wählt genau diese Provider-Route aus. Beispielsweise sind qianfan/deepseek-v4-flash und deepseek/deepseek-v4-flash unterschiedliche Referenzen, obwohl die Modell-ID übereinstimmt — OpenClaw wechselt bei einer bloßen Übereinstimmung der ID nicht stillschweigend den Provider.

Eine vom Benutzer ausgewählte /model-Referenz ist für den Fallback strikt: Wenn dieses Provider-/Modell-Paar nicht mehr verfügbar ist, schlägt die Antwort sichtbar fehl, anstatt auf agents.defaults.model.fallbacks zurückzufallen. Konfigurierte Fallback- Ketten gelten weiterhin für konfigurierte Standardwerte, Primärmodelle von Cron-Aufträgen und den automatisch ausgewählten Fallback-Zustand. Wenn ein Lauf ohne Sitzungsüberschreibung einen Fallback verwenden darf, versucht OpenClaw zuerst den angeforderten Provider/das angeforderte Modell, dann die konfigurierten Fallbacks und anschließend das konfigurierte Primärmodell — identische reine Modell-IDs springen daher nie direkt zum Standard-Provider zurück.

Siehe Modelle und Modell-Failover.

Ja — Modellauswahl und Laufzeitauswahl sind voneinander getrennt:

• Nativer Codex-Programmieragent: Legen Sie agents.defaults.model.primary auf openai/gpt-5.5 fest. Melden Sie sich mit openclaw models auth login --provider openai für die Authentifizierung per ChatGPT-/Codex-Abonnement an.
• Direkte OpenAI-API-Aufgaben außerhalb der Agentenschleife: Konfigurieren Sie OPENAI_API_KEY für Bilder, Einbettungen, Sprache, Echtzeit und andere OpenAI-API-Oberflächen außerhalb des Agenten.
• OpenAI-Agentenauthentifizierung per API-Schlüssel: /model openai/gpt-5.5 mit einem geordneten openai-API-Schlüsselprofil.
• Unteragenten: Leiten Sie Programmieraufgaben an einen Codex-orientierten Agenten mit einem eigenen Modell openai/gpt-5.5 weiter.

Siehe Modelle und Slash-Befehle.

• Pro Sitzung: Senden Sie /fast on, während Sie openai/gpt-5.5 verwenden.
• Als Standard pro Modell: Setzen Sie agents.defaults.models["openai/gpt-5.5"].params.fastMode auf true.
• Automatischer Grenzwert: /fast auto oder params.fastMode: "auto" führt neue Modellaufrufe bis zum Grenzwert schnell aus und führt spätere Wiederholungs-, Fallback-, Tool-Ergebnis- oder Fortsetzungsaufrufe anschließend ohne schnellen Modus aus. Der Grenzwert beträgt standardmäßig 60 Sekunden; überschreiben Sie ihn mit params.fastAutoOnSeconds für das Modell.

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

Der schnelle Modus entspricht service_tier = "priority" bei nativen OpenAI-Responses- Anfragen; vorhandene service_tier-Werte bleiben erhalten und der schnelle Modus ändert weder reasoning noch text.verbosity. Sitzungsbezogene /fast-Überschreibungen haben Vorrang vor den Konfigurationsstandards.

Siehe Denken und schneller Modus sowie den Abschnitt zum schnellen Modus unter „Erweiterte Konfiguration“ auf der Provider-Seite OpenAI.

Wenn agents.defaults.models festgelegt ist, wird es zur Positivliste für /model und Sitzungsüberschreibungen. Wenn Sie ein Modell außerhalb dieser Liste auswählen, wird anstelle einer normalen Antwort Folgendes zurückgegeben:

Das Modell "provider/model" ist nicht zulässig. Verwenden Sie /models, um Provider aufzulisten, oder /models <provider>, um Modelle aufzulisten.Fügen Sie es wie folgt hinzu: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Lösung: Fügen Sie das genaue Modell zu agents.defaults.models hinzu, fügen Sie für dynamische Kataloge einen Provider-Platzhalter wie "provider/*": {} hinzu, entfernen Sie die Positivliste oder wählen Sie ein Modell aus /model list. Wenn der Befehl außerdem --runtime codex enthielt, aktualisieren Sie zunächst die Positivliste und wiederholen Sie dann denselben Befehl /model provider/model --runtime codex.

Wenn Sie eine ältere OpenClaw-Version verwenden, aktualisieren Sie diese zuerst (oder führen Sie main aus dem Quellcode aus) und starten Sie den Gateway neu — MiniMax-M3 ist möglicherweise noch nicht im Katalog Ihrer installierten Version enthalten. Andernfalls ist der MiniMax-Provider nicht konfiguriert (es wurde kein Provider-Eintrag oder Authentifizierungsprofil gefunden), sodass das Modell nicht aufgelöst werden kann. Die vollständige Prüfliste zur Fehlerbehebung, die Tabelle der Provider-/Modell-IDs und ein Beispiel für einen Konfigurationsblock finden Sie im Abschnitt zur Fehlerbehebung auf der Provider-Seite MiniMax.

Ja. Verwenden Sie MiniMax als Standard und wechseln Sie das Modell pro Sitzung — Fallbacks sind für Fehler vorgesehen, nicht für „schwierige Aufgaben“. Verwenden Sie daher /model oder einen separaten Agenten.

Option A: pro Sitzung wechseln

{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Anschließend /model gpt.

Option B: separate Agenten — Agent A verwendet standardmäßig MiniMax, Agent B standardmäßig OpenAI; leiten Sie nach Agent weiter oder verwenden Sie /agent, um zu wechseln.

Dokumentation: Modelle, Multi-Agent-Routing, MiniMax, OpenAI.

Ja — integrierte Kurzformen, die nur angewendet werden, wenn das Zielmodell in agents.defaults.models vorhanden ist:

Ihr eigener Alias mit demselben Namen überschreibt den integrierten Alias.

Aliasse werden unter agents.defaults.models.<modelId>.alias festgelegt:

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

Anschließend wird /model sonnet (oder /<alias>, sofern unterstützt) zu dieser Modell-ID aufgelöst.

OpenRouter (Abrechnung pro Token; viele Modelle):

{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (GLM-Modelle):

{  agents: {    defaults: {      model: { primary: "zai/glm-5.1" },      models: { "zai/glm-5.1": {} },    },  },  env: { ZAI_API_KEY: "..." },}

Ein fehlender Provider-Schlüssel für einen referenzierten Provider bzw. ein referenziertes Modell löst zur Laufzeit einen Authentifizierungsfehler aus (z. B. No API key found for provider "zai").

Nach dem Hinzufügen eines neuen Agenten wurde kein API-Schlüssel für den Provider gefunden

Ein neuer Agent besitzt einen leeren Authentifizierungsspeicher — die Authentifizierung erfolgt pro Agent und wird hier gespeichert:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Lösung: Führen Sie openclaw agents add <id> aus und konfigurieren Sie die Authentifizierung im Assistenten, oder kopieren Sie nur portable statische api_key-/token-Profile aus dem Speicher des Hauptagenten. Melden Sie sich bei OAuth über den neuen Agenten an, wenn dieser ein eigenes Konto benötigt. Unter Multi-Agent-Routing finden Sie die vollständigen Regeln zur Wiederverwendung von agentDir und zur gemeinsamen Nutzung von Anmeldedaten — verwenden Sie agentDir niemals für mehrere Agenten.

Zwei Stufen:

1. Rotation der Authentifizierungsprofile innerhalb desselben Providers.
2. Modell-Fallback auf das nächste Modell in agents.defaults.model.fallbacks.

Für fehlschlagende Profile gelten Cooldowns (exponentielles Backoff), sodass OpenClaw weiterhin antwortet, wenn ein Provider ratenbegrenzt ist oder vorübergehend ausfällt.

Die Ratenbegrenzungskategorie umfasst mehr als nur 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted und periodische Nutzungslimits (weekly/monthly limit reached) gelten alle als Ratenbegrenzungen, die ein Failover rechtfertigen.

Abrechnungsantworten haben nicht immer den Status 402, und einige 402-Antworten verbleiben in der Kategorie für vorübergehende Fehler/Ratenbegrenzungen, statt der Abrechnungskategorie zugeordnet zu werden. Explizite Abrechnungshinweise bei 401/403 können weiterhin der Abrechnung zugeordnet werden; providerspezifische Textabgleiche (z. B. OpenRouter Key limit exceeded) bleiben auf ihren jeweiligen Provider beschränkt. Eine 402-Antwort, die auf ein wiederholbares Nutzungslimit oder ein Ausgabenlimit für Organisation/Arbeitsbereich hindeutet (daily limit reached, resets tomorrow, organization spending limit exceeded), wird als rate_limit behandelt und führt nicht zu einer langfristigen Deaktivierung wegen der Abrechnung.

Kontextüberlauf-Fehler bleiben vollständig außerhalb des Fallback-Pfads — Signaturen wie request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model oder ollama error: context length exceeded führen zu Compaction und einem erneuten Versuch, statt zum nächsten Modell-Fallback überzugehen.

Allgemeiner Serverfehlertext wird enger ausgelegt als „alles, was unknown/error enthält“. Auf einen Provider beschränkte vorübergehende Fehlerformen, die als Failover- Signale gelten: das alleinstehende Anthropic An unknown error occurred, das alleinstehende OpenRouter Provider returned error, Fehler bei Beendigungsgründen wie Unhandled stop reason: error, JSON-api_error-Nutzlasten mit Text zu vorübergehenden Serverfehlern (internal server error, unknown error, 520, upstream error, backend error) und Fehler wegen ausgelasteter Provider wie ModelNotReadyException, wenn der Provider- Kontext übereinstimmt. Allgemeiner interner Fallback-Text wie LLM request failed with an unknown error. wird konservativ behandelt und löst für sich allein keinen Fallback aus.

Die Authentifizierungsprofil-ID anthropic:default enthält im erwarteten Authentifizierungsspeicher keine Anmeldedaten.

Checkliste zur Behebung:

• Prüfen Sie, wo die Profile gespeichert sind — aktuell: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; veraltet: ~/.openclaw/agent/* (durch openclaw doctor migriert).
• Prüfen Sie, ob der Gateway Ihre Umgebungsvariable lädt. Wenn ANTHROPIC_API_KEY nur in Ihrer Shell gesetzt ist, erreicht die Variable einen über systemd/launchd ausgeführten Gateway nicht — tragen Sie sie in ~/.openclaw/.env ein oder aktivieren Sie env.shellEnv.
• Prüfen Sie, ob Sie den richtigen Agenten bearbeiten — Multi-Agent-Konfigurationen verfügen über mehrere auth-profiles.json-Dateien.
• Führen Sie openclaw models status aus, um konfigurierte Modelle und den Authentifizierungsstatus des Providers anzuzeigen.

Für „No credentials found for profile anthropic“ (ohne E-Mail-Suffix):

Der Lauf ist an ein Anthropic-Profil gebunden, das der Gateway nicht finden kann.

• Verwenden Sie die Claude CLI: Führen Sie openclaw models auth login --provider anthropic --method cli --set-default auf dem Gateway-Host aus.

• Verwenden Sie stattdessen vorzugsweise einen API-Schlüssel: Tragen Sie ANTHROPIC_API_KEY auf dem Gateway-Host in ~/.openclaw/.env ein und löschen Sie anschließend jede festgelegte Reihenfolge, die das fehlende Profil erzwingt:

  openclaw models auth order clear --provider anthropic

• Remote-Modus: Authentifizierungsprofile befinden sich auf dem Gateway-Rechner, nicht auf Ihrem Laptop — stellen Sie sicher, dass Sie die Befehle dort ausführen.

Wenn Ihre Modellkonfiguration Google Gemini als Fallback enthält (oder Sie zu einer Gemini-Kurzform gewechselt haben), versucht OpenClaw während des Fallbacks, dieses Modell zu verwenden. Wenn keine Google-Anmeldedaten konfiguriert sind, wird No API key found for provider "google" ausgegeben. Lösung: Fügen Sie eine Google-Authentifizierung hinzu oder entfernen Sie Google-Modelle aus agents.defaults.model.fallbacks bzw. den Aliasen.

LLM-Anfrage abgelehnt: Thinking-Signatur erforderlich (Google Antigravity)

Ursache: Der Sitzungsverlauf enthält Thinking-Blöcke ohne Signaturen (häufig aufgrund eines abgebrochenen/unvollständigen Streams); Google Antigravity verlangt Signaturen für Thinking-Blöcke. OpenClaw entfernt unsignierte Thinking-Blöcke für Google Antigravity Claude; falls der Fehler weiterhin auftritt, starten Sie eine neue Sitzung oder legen Sie für diesen Agenten /thinking off fest.

Ein benannter, einem Provider zugeordneter Anmeldedatensatz (OAuth oder API-Schlüssel), der hier gespeichert wird:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Prüfen Sie gespeicherte Profile, ohne Geheimnisse auszugeben: openclaw models auth list (optional mit --provider <id> oder --json). Siehe Modelle-CLI.

Mit Provider-Präfix: anthropic:default (üblich, wenn keine E-Mail-Identität vorhanden ist), anthropic:<email> für OAuth-Identitäten oder eine benutzerdefinierte ID Ihrer Wahl (z. B. anthropic:work).

Ja. Die Konfiguration auth.order.<provider> legt die Rotationsreihenfolge pro Provider fest (nur Metadaten — es werden keine Geheimnisse gespeichert).

OpenClaw kann ein Profil während eines kurzen Cooldowns (Ratenbegrenzungen, Zeitüberschreitungen, Authentifizierungsfehler) oder eines längeren deaktivierten Zustands (Abrechnung/unzureichendes Guthaben) überspringen. Prüfen Sie dies mit openclaw models status --json und kontrollieren Sie auth.unusableProfiles. Passen Sie das Verhalten mit auth.cooldowns.billingBackoffHours* an. Cooldowns wegen Ratenbegrenzungen können modellspezifisch sein — ein Profil, das sich für ein Modell im Cooldown befindet, kann weiterhin ein anderes Modell desselben Providers bedienen; Abrechnungs-/Deaktivierungszeiträume sperren das gesamte Profil.

Legen Sie eine agentspezifische Reihenfolgeüberschreibung fest (gespeichert in der auth-state.json dieses Agenten):

# Verwendet standardmäßig den konfigurierten Standardagenten (--agent weglassen)openclaw models auth order get --provider anthropic # Rotation auf ein einzelnes Profil beschränkenopenclaw models auth order set --provider anthropic anthropic:default # Oder eine explizite Reihenfolge festlegen (Fallback innerhalb des Providers)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Überschreibung löschen (auf auth.order aus der Konfiguration/Round-Robin zurückfallen)openclaw models auth order clear --provider anthropic # Einen bestimmten Agenten ansprechenopenclaw models auth order set --provider anthropic --agent main anthropic:default

Prüfen Sie mit openclaw models status --probe, was tatsächlich ausprobiert wird. Ein gespeichertes Profil, das in einer expliziten Reihenfolge fehlt, meldet excluded_by_auth_order, statt stillschweigend ausprobiert zu werden.

• OAuth-/CLI-Anmeldung verwendet häufig einen Abonnementzugang, sofern der Provider dies unterstützt. Bei Anthropic verwendet das Claude-CLI-Backend von OpenClaw Claude Code claude -p, was Anthropic derzeit als Agent-SDK-/programmatische Nutzung behandelt, die auf die Nutzungslimits des Abonnements angerechnet wird — den aktuellen Status der Abrechnungspause und Quellenlinks finden Sie unter Anthropic.
• API-Schlüssel verwenden eine tokenbasierte Abrechnung.

Der Assistent unterstützt Anthropic Claude CLI, OpenAI Codex OAuth und API- Schlüssel.