OpenClaw mit OmniaKey einrichten: Provider und Modell-Allowlist

Aktualisiert am 30. Oktober 2026: unten stehen vier häufige Einrichtungsfehler, jeweils mit Symptom, Ursache und der Lösung aus der OpenClaw-Dokumentation.

Bei der Suche nach OpenClaw API einrichten werden zwei Schritte oft vermischt: den Provider definieren und das Modell in der Allowlist freigeben. OpenClaw liefert den Agent-Loop und die Tools; das angeschlossene Modell liefert die eigentliche Antwort.

OmniaKey als Provider eintragen

Die Konfiguration liegt in ~/.openclaw/openclaw.json. Ergänze OmniaKey unter models.providers:

{
  "models": {
    "mode": "merge",
    "providers": {
      "omniakey": {
        "baseUrl": "https://api.omniakey.com/v1",
        "apiKey": "your-omniakey-api-key",
        "api": "openai-completions",
        "models": [
          { "id": "claude-opus-4-8" },
          { "id": "gpt-5.5" },
          { "id": "gemini-3.1-pro-preview" },
          { "id": "grok-4.5" }
        ]
      }
    }
  }
}

mode: merge ergänzt den Provider, ohne die vorhandene Konfiguration zu ersetzen. Trage deinen echten Key ein, aber speichere ihn nicht in Git oder öffentlichen Nachrichten. Ein OpenAI-kompatibler Provider deckt vier Modellfamilien ab: OmniaKey sucht das Modell anhand der ID, deshalb laufen claude-opus-4-8, gpt-5.5, gemini-3.1-pro-preview und grok-4.5 alle über denselben Eintrag.

Der oft fehlende Schritt: Modell freigeben

Die Provider-Definition allein reicht nicht. OpenClaw verlangt zusätzlich eine Allowlist. Füge agents als Geschwister von models in derselben Datei hinzu:

{
  "agents": {
    "defaults": {
      "models": ["omniakey/claude-opus-4-8", "omniakey/gpt-5.5", "omniakey/gemini-3.1-pro-preview", "omniakey/grok-4.5"],
      "model": "omniakey/claude-opus-4-8"
    }
  }
}

Der Request verwendet die Modell-ID; provider/model-id ist der interne OpenClaw-Verweis. Beide Einträge sind erforderlich. Fehlt die Allowlist, erscheint oft model not allowed, obwohl der Key korrekt ist.

Prüfen

openclaw doctor

doctor prüft Datei, Provider, Key-Format, Live-Verbindung und Modellzugriff. Danach kannst du unter agents.defaults z. B. omniakey/gpt-5.5 als aktives Modell setzen.

Häufige Einrichtungsfehler

• Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow. Der gewählte Ref fehlt in einer nicht leeren Liste agents.defaults.modelPolicy.allow, und genau diese Liste prüft OpenClaw bei /model, bei Sitzungs-Overrides und bei --model. Nimm den exakten Ref oder einen Provider-Wildcard wie omniakey/* auf, leere die Liste oder wähle ein Modell aus /model list (OpenClaw-Modell-FAQ).

• model_not_found oder ein 404, obwohl ein direkter Aufruf mit derselben Modell-ID funktioniert. Ein eigener Eintrag wird nur aufgelöst, wenn baseUrl auf /v1 endet, api gleich "openai-completions" ist und der Katalog die ID ohne Präfix behält, während du sie mit Provider-Präfix auswählst. Prüfe diese drei Punkte, wähle das Modell einmal mit Provider-Präfix und starte denselben Prompt erneut (Fehlersuche bei lokalen Backends).

• Ein nacktes 403 mit "Your request was blocked" im Antwortkörper. Dieser Text kommt meist von einer Sicherheitsschicht vor dem Endpoint — CDN, WAF, Bot-Regel oder Reverse Proxy — und nicht aus openclaw.json; openclaw logs --follow zeigt, ob mehrere Modelle desselben Providers gleich scheitern. Repariere zuerst die Provider-Seite mit einer Erlaubnisregel, die nur den Pfad abdeckt, den OpenClaw aufruft, und lass den Schutz für den Rest der Seite aktiv (Fehlersuche beim Upstream-403).

• messages[...].content: invalid type: sequence, expected a string bei jedem Agent-Lauf. Das Backend lehnt strukturierte Content-Teile im OpenAI-Stil ab. Setze compat.requiresStringContent: true am Eintrag dieses Modells und starte denselben Prompt erneut.

Warum OmniaKey für OpenClaw?

Ein Key und ein Guthaben decken Claude, GPT, Gemini und Grok ab; abgerechnet wird nach Tokens. Die freigegebene Modell-ID läuft tatsächlich, ohne stillen Wechsel zu einem vermeintlich gleichwertigen Modell. Der Modellkatalog listet jede erlaubte ID, und Preise zeigt den Tokenpreis.

Weitere Tool-Konfigurationen stehen im Guide für Coding-Agents. Schritt für Schritt zeigen die Anleitungen Hermes Agent einrichten, Cline mit eigenem API-Key und Claude Code einrichten.

Häufige Fragen

Wohin gehört der Provider-Block für OmniaKey?

In ~/.openclaw/openclaw.json unter models.providers. Lass "mode": "merge" stehen, damit der Block zu deinen vorhandenen Providern hinzukommt statt sie zu ersetzen.

Warum sagt OpenClaw, ein Modell sei nicht erlaubt?

Der Provider ist definiert, aber der Modell-Ref steht nicht in der Allowlist von OpenClaw, deshalb scheitert der Lauf auch bei korrektem Key. Ergänze den vollständigen Ref omniakey/model-id und führe dann openclaw doctor aus.

Reicht ein OmniaKey-Key für Claude, GPT, Gemini und Grok in OpenClaw?

Ja. Ein Provider-Eintrag mit api: "openai-completions" erreicht alle vier Familien, und die Modell-ID im Request entscheidet, welche läuft.

Wie prüfe ich, ob OpenClaw OmniaKey erreicht?

openclaw doctor prüft Konfigurationsdatei, Provider, Key-Format, eine Live-Verbindung und den Modellzugriff. Danach zeigt openclaw models list die OmniaKey-Modelle, die du freigegeben hast.

Muss ich ~/.openclaw/agents/main/agent/models.json bearbeiten?

Nein. Die Datei wird aus openclaw.json neu erzeugt; Provider und Allowlist änderst du deshalb in openclaw.json.

Geprüfte Quellen

• OpenClaw: FAQ zu Modellen und Authentifizierung
• OpenClaw: Skills und Modell-Provider