|

Vollständige 5-Schritte-Konfiguration zur Anbindung von OpenClaw an die Claude API: Fehler beim Tool-Aufruf mit dem Anthropic Messages-Format beheben

VonAPIYI - Stable and affordable AI API

openclaw-claude-api-apiyi-anthropic-messages-guide-de 图示

Haben Sie diesen Fehler schon einmal erlebt, wenn Sie Claude-Modelle mit OpenClaw ausgeführt haben?

400 ... ValidationException: Operation not allowed

Beim reinen Chatten funktioniert alles einwandfrei, aber sobald es zum Tool-Aufruf (Tool Use) kommt, schlägt es fehl – das ist eine Falle, in die fast jeder OpenClaw-Nutzer tappt, der die Claude API anbindet.

Die Ursache ist simpel: Sie verwenden das falsche API-Format.

Bei der Anbindung von Claude in OpenClaw gibt es zwei Formatoptionen: openai-completions und anthropic-messages. Im OpenAI-Kompatibilitätsmodus funktioniert der einfache Chat, aber bei mehrstufigen Tool-Aufrufen (tool_calls → tool_result → tool loop) wird die Anfrage abgelehnt. Nur durch den Wechsel zum Format anthropic-messages laufen Tool-Aufrufe stabil.

Dieser Artikel basiert auf einer praxiserprobten Konfiguration und zeigt Ihnen Schritt für Schritt, wie Sie APIYI (apiyi.com) als API-Proxy-Dienst nutzen, um die Claude API in 5 Schritten korrekt in OpenClaw zu konfigurieren.

Analyse der Kernprobleme bei der Anbindung von OpenClaw an die Claude API

Bevor wir zu den Lösungen kommen, klären wir zunächst, warum es überhaupt zu Fehlermeldungen kommt.

Was ist OpenClaw?

OpenClaw ist eines der gefragtesten Open-Source-Frameworks für AI-Agents der Jahre 2025-2026, entwickelt von Peter Steinberger (Gründer von PSPFKit). Seine Hauptmerkmale sind:

  • Multi-Plattform-Unterstützung: Signal, Telegram, Discord, WhatsApp, iMessage
  • Multi-Modell-Anbindung: Claude, GPT, DeepSeek und andere führende Modelle
  • Werkzeugaufruf-Funktionen (Tool Calling): Über 50 integrierte Tools, unterstützt Code-Ausführung, Websuche, Smart Home etc.
  • Lokale Ausführung: Konfiguration und Chatverlauf werden lokal gespeichert, was die Privatsphäre schützt
OpenClaw Kernfunktionen Beschreibung
Entwickler Peter Steinberger (Gründer von PSPFKit)
Open-Source-Lizenz Kostenlos und quelloffen
Unterstützte Plattformen Signal / Telegram / Discord / WhatsApp / iMessage
Unterstützte Modelle Claude / GPT / DeepSeek etc.
API-Format openai-completions / anthropic-messages
Tool-Integrationen 50+ integrierte Tools
Datenspeicherung Lokal gespeichert, volle Kontrolle über Privatsphäre

Grundlegende Unterschiede zwischen den beiden API-Formaten

OpenClaw unterstützt zwei Wege zur Anbindung der Claude API:

Vergleichsdimension openai-completions anthropic-messages
Endpunkt-Pfad /v1/chat/completions /v1/messages
Reiner Text-Chat ✅ Normal ✅ Normal
Werkzeugaufruf (Tool Use) ❌ 400 Fehlermeldung ✅ Stabil verfügbar
Multi-Turn-Tool-Loops ❌ Fehlermeldung ✅ Stabil verfügbar
Prompt-Caching ❌ Nicht unterstützt ✅ Unterstützt
Extended Thinking ⚠️ Unvollständig ✅ Vollständige Unterstützung
Anforderungen an den Header Keine besonderen Anforderungen Erfordert anthropic-version

🎯 Technischer Rat: Bei der Anbindung von OpenClaw an die Claude API muss das Format anthropic-messages verwendet werden, um die Werkzeugaufruf-Funktionen stabil nutzen zu können. Wir empfehlen APIYI (apiyi.com) als API-Proxy-Dienst, da diese Plattform das native Messages API-Format von Anthropic vollständig unterstützt.

Warum Werkzeugaufrufe im openai-completions-Format fehlschlagen

Wenn OpenClaw das Format openai-completions verwendet, um Claude aufzurufen, passiert Folgendes:

  1. Formatkonvertierung: OpenClaw sendet die Felder tool_calls und function im OpenAI-Format.
  2. Protokoll-Inkompatibilität: Claude verwendet nativ die Formate tool_use und tool_result.
  3. Multi-Turn-Konflikte: Tool-Loops erfordern die Konsistenz der tool_use_id über mehrere Anfragen hinweg. Bei der Formatkonvertierung gehen diese Informationen leicht verloren.
  4. Validierungsablehnung: Der API-Proxy-Dienst oder die Upstream-API erkennt die Format-Diskrepanz und gibt einen 400 ValidationException zurück.

openclaw-claude-api-apiyi-anthropic-messages-guide-de 图示

OpenClaw-Anbindung an die Claude API: In 5 Schritten fertig konfiguriert

Die folgende Konfiguration basiert auf Praxistests unter Verwendung von APIYI (apiyi.com) als Claude API-Proxy-Dienst.

Schritt 1: Provider konfigurieren (Kernkonfiguration)

Fügen Sie in der Datei openclaw.json unter models.providers die folgende Konfiguration hinzu:

{
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com",
        "apiKey": "sk-YOUR_APIYI_KEY",
        "api": "anthropic-messages",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "claude-opus-4-6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-sonnet-4-6-thinking",
            "name": "claude-sonnet-4-6-thinking",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          }
        ]
      }
    }
  }
}

Details zu den Konfigurationspunkten:

Konfigurationselement Korrekter Wert Beschreibung
baseUrl https://api.apiyi.com Nicht /v1 anhängen, sonst wird der Pfad zu .../v1/v1/messages zusammengesetzt.
api "anthropic-messages" Muss verwendet werden; nutzen Sie nicht openai-completions.
anthropic-version "2023-06-01" Muss enthalten sein, sonst wird die Anfrage abgelehnt.
anthropic-beta "" (leerer String) Deaktiviert Beta-Funktionen explizit, um 400-Fehler zu vermeiden.
reasoning false Deaktiviert das thinking-Feld, um eine ValidationException zu vermeiden.
streaming Deaktivierung empfohlen In Proxy-Szenarien ist die Deaktivierung von Streaming stabiler.

💡 Wichtiger Hinweis: Schreiben Sie die baseUrl auf keinen Fall als https://api.apiyi.com/v1. Wenn OpenClaw das Format anthropic-messages verwendet, wird automatisch /v1/messages angehängt. Wenn Ihre baseUrl bereits /v1 enthält, führt dies zu einem 404-Fehler, da der Pfad dann /v1/v1/messages lautet.

Schritt 2: Modelle in die Whitelist (allowlist) aufnehmen

Fügen Sie die Modelle zu agents.defaults.models hinzu. Andernfalls meldet OpenClaw, dass das Modell „nicht registriert/nicht erlaubt“ ist und führt heimlich einen Fallback auf ein anderes Modell durch – eine sehr tückische Falle.

{
  "agents": {
    "defaults": {
      "models": {
        "apiyi/claude-opus-4-6": { "streaming": false },
        "apiyi/claude-sonnet-4-6-thinking": { "streaming": false }
      }
    }
  }
}

Schritt 3: Agent konfigurieren

Hier am Beispiel des tasks Agents:

{
  "agents": {
    "list": [
      {
        "id": "tasks",
        "model": "apiyi/claude-opus-4-6",
        "tools": {
          "profile": "coding",
          "alsoAllow": ["group:web"]
        }
      }
    ]
  }
}

Schritt 4: Bestehende Sessions behandeln (wird oft übersehen)

Dies ist der am häufigsten übersehene Schritt. Selbst wenn Sie die Konfiguration ändern, speichern bestehende Kanal-Sessions möglicherweise noch alte modelProvider/model-Überschreibungen, wodurch es so aussieht, als ob die Konfiguration nicht greift.

Es gibt zwei Möglichkeiten zur Behebung:

Methode A: Modell der aktuellen Session patchen

openclaw gateway call sessions.patch \
  --params '{"key":"agent:tasks:discord:channel:<CHANNEL_ID>","model":"apiyi/claude-opus-4-6"}'

Methode B: Session zurücksetzen (löscht den Chatverlauf)

openclaw gateway call sessions.reset \
  --params '{"key":"agent:tasks:discord:channel:<CHANNEL_ID>","reason":"reset"}'

🚀 Schnellstart: Nach der Registrierung auf der Plattform APIYI (apiyi.com) erhalten Sie Ihren API-Schlüssel. Ersetzen Sie sk-YOUR_APIYI_KEY in der obigen Konfiguration durch Ihren tatsächlichen Schlüssel, um die OpenClaw-Anbindung an die Claude API abzuschließen.

Schritt 5: Überprüfen, ob die Konfiguration aktiv ist

Führen Sie die folgenden Befehle aus, um die Korrektheit zu bestätigen:

# Modellstatus prüfen
openclaw models status --agent tasks

# Testnachricht senden
openclaw agent --agent tasks --message "Antworte nur mit pong" --json

Prüfen Sie im zurückgegebenen JSON, ob meta.agentMeta.provider und meta.agentMeta.model den Erwartungen entsprechen:

{
  "meta": {
    "agentMeta": {
      "provider": "apiyi",
      "model": "claude-opus-4-6"
    }
  }
}

Wenn der Provider oder das Modell nicht den von Ihnen konfigurierten Werten entspricht, wurde das Session-Überschreibungsproblem noch nicht gelöst. Gehen Sie zurück zu Schritt 4.

OpenClaw Claude API: Häufige Fehler und Fehlerbehebung

Während der Konfiguration könnten Ihnen folgende Probleme begegnen:

Fehler 1: 400 ValidationException: Operation not allowed

400 ... ValidationException: Operation not allowed

Ursache: Die Anfrage enthielt die Felder thinking oder output_config. Einige Claude 4.6 Modelle unterstützen diese Parameter über bestimmte Proxy-Routen nicht.

Lösung:

  1. Stellen Sie sicher, dass in der Modellkonfiguration reasoning: false gesetzt ist.
  2. Stellen Sie sicher, dass der Header anthropic-beta: "" (leerer String) gesetzt ist.
  3. Prüfen Sie, ob Ihre OpenClaw-Version thinking-bezogene Felder sendet.

Fehler 2: 404 Not Found

Ursache: Die baseUrl ist falsch konfiguriert und enthält fälschlicherweise /v1.

Lösung: Ändern Sie die baseUrl in https://api.apiyi.com (ohne /v1).

Fehler 3: Heimlicher Modell-Fallback

Symptom: Der Stil der Antworten ändert sich plötzlich oder das Modell behauptet in der Antwort, nicht Claude zu sein.

Ursache: Das Modell wurde nicht in die allowlist aufgenommen, weshalb OpenClaw automatisch auf ein Standardmodell ausweicht.

Lösung: Registrieren Sie alle zu verwendenden Modelle unter agents.defaults.models.

Fehler 4: Tool-Aufruf-Schleife fehlgeschlagen

Symptom: Der erste Tool-Aufruf ist erfolgreich, aber beim Zurücksenden des nachfolgenden tool_result tritt ein Fehler auf.

Ursache: Es wurde das openai-completions-Format verwendet, wodurch die tool_use_id für die Tool-Schleife bei der Formatkonvertierung verloren ging.

Lösung: Wechseln Sie zum Format api: "anthropic-messages".

openclaw-claude-api-apiyi-anthropic-messages-guide-de 图示

Warum APIYI als Claude API-Proxy für OpenClaw wählen?

Bei der Auswahl eines API-Proxy-Dienstleisters gibt es einige entscheidende Faktoren zu berücksichtigen.

Vergleich der Claude API-Proxy-Optionen

Bewertungskriterien Direktverbindung Anthropic APIYI (apiyi.com) Andere Proxy-Dienste
Anthropic Messages Format ✅ Native Unterstützung ✅ Vollständige Unterstützung ⚠️ Teilweise Unterstützung
Tool-Aufrufe (tool use) ✅ Unterstützt ✅ Stabile Unterstützung ⚠️ Möglicherweise instabil
Prompt Caching ✅ Unterstützt ✅ Unterstützt ❌ Meist nicht unterstützt
Direkte Verbindung (lokales Netzwerk) ❌ Proxy erforderlich ✅ Direkt verfügbar ✅ Teilweise direkt verfügbar
Einheitliche Schnittstelle für mehrere Modelle ❌ Nur Claude ✅ Claude + GPT + weitere ✅ Teilweise unterstützt
Abrechnung nach Verbrauch ✅ Offizielle Preise ✅ Flexible Abrechnung ⚠️ Preise intransparent
OpenClaw Praxistest – ✅ Verifiziert ⚠️ Nicht verifiziert

💰 Kostenoptimierung: APIYI (apiyi.com) unterstützt das native Anthropic Messages API-Format. Das bedeutet, dass Sie bei der Nutzung in OpenClaw von Claude Prompt Caching profitieren können – die Kosten für Input-Token bei einem Cache-Hit betragen nur 10 % des Basispreises.

Die 3 Kernvorteile des APIYI API-Proxy-Dienstes

1. Vollständige Unterstützung des nativen Anthropic-Formats

Die APIYI-Plattform ist nicht nur eine einfache Weiterleitung im OpenAI-Format, sondern unterstützt die Anthropic Messages API (/v1/messages Endpunkt) vollständig, einschließlich:

  • cache_control Parameter zur Cache-Steuerung
  • tool_use / tool_result natives Format für Tool-Aufrufe
  • anthropic-version Request-Header
  • Extended Thinking (Erweitertes Denken)

2. In OpenClaw praxiserprobt

Alle Konfigurationen in diesem Artikel basieren auf Praxistests mit der APIYI-Plattform, um Folgendes sicherzustellen:

  • Stabiler Betrieb von Tool-Aufruf-Zyklen über mehrere Runden
  • Korrekte Übergabe der tool_use_id zwischen mehreren Anfragen
  • Kein Verlust des Kontextes in langen Dialogszenarien

3. Zentrale Verwaltung mehrerer Modelle

Mit nur einem API-Schlüssel können Sie verschiedene Modelle wie Claude, GPT und DeepSeek aufrufen. In OpenClaw lassen sich verschiedenen Agents unterschiedliche Modelle zuweisen und flexibel wechseln.

Fortgeschrittene Konfigurationstipps für die Claude API-Anbindung in OpenClaw

Sobald Sie die Basiskonfiguration beherrschen, helfen Ihnen diese Tipps bei der weiteren Optimierung.

Tipp 1: Verschiedene Modelle für verschiedene Agents konfigurieren

{
  "agents": {
    "list": [
      {
        "id": "tasks",
        "model": "apiyi/claude-opus-4-6",
        "tools": { "profile": "coding" }
      },
      {
        "id": "chat",
        "model": "apiyi/claude-sonnet-4-6-thinking",
        "tools": { "profile": "default" }
      }
    ]
  }
}
  • tasks agent: Nutzen Sie Opus 4.6 für komplexe Aufgaben und Codegenerierung.
  • chat agent: Nutzen Sie Sonnet 4.6 für alltägliche Chats bei geringeren Kosten.

Tipp 2: Kosten senken mit Prompt Caching

Da APIYI das native Anthropic-Format unterstützt, kann die System-Eingabeaufforderung (System Prompt) von OpenClaw automatisch zwischengespeichert werden. Bei Agents mit langen System-Eingabeaufforderungen sinken die Input-Kosten bei einem Cache-Hit auf nur 10 %.

Tipp 3: Sicherheitshinweise

  • Geben Sie Ihren API-Schlüssel niemals in öffentlichen Discord-Kanälen preis.
  • Der Schlüssel in openclaw.json wird im Klartext gespeichert; stellen Sie sicher, dass die Dateiberechtigungen korrekt gesetzt sind.
  • Falls ein Schlüssel kompromittiert wurde, rotieren Sie ihn umgehend im Dashboard von APIYI (apiyi.com).

OpenClaw Anbindung an die Claude API: FAQ

Q1: Muss ich für Claude in OpenClaw zwingend einen Proxy verwenden?

Nicht zwingend, aber für Nutzer in Regionen mit eingeschränktem Zugriff wird dies dringend empfohlen. Eine direkte Verbindung zur Anthropic API erfordert eine entsprechende Netzwerkumgebung im Ausland. Über den API-Proxy-Dienst von APIYI (apiyi.com) können Sie die API direkt aufrufen und gleichzeitig die volle Unterstützung der Anthropic Messages API genießen.

Q2: Warum ändert sich das Verhalten von OpenClaw nicht, obwohl ich die Konfiguration geändert habe?

Das ist das am häufigsten auftretende Problem. In 99 % der Fälle liegt es daran, dass eine bestehende Session die alte Konfiguration zwischengespeichert hat. Verwenden Sie die Befehle sessions.patch oder sessions.reset, um die Session zu aktualisieren, oder testen Sie die Änderungen in einem neuen Kanal. Die spezifischen Befehle finden Sie in Schritt 4.

Q3: Funktioniert die Thinking-Funktion von Claude 4.6 in OpenClaw?

Aktuell kann das Thinking-Feld (thinking / output_config) über Proxy-Verbindungen eine 400 ValidationException auslösen. Es wird empfohlen, reasoning: false zu setzen. Verfolgen Sie den Support-Status der Thinking-Funktion über zukünftige Updates auf der Plattform von APIYI (apiyi.com).

Q4: Kann ein APIYI-Schlüssel gleichzeitig für mehrere OpenClaw-Agents verwendet werden?

Ja. Ein API-Schlüssel von APIYI beschränkt nicht die Anzahl der gleichzeitigen Agents. Sie können denselben Schlüssel für verschiedene Agents wie tasks, chat oder coder konfigurieren. Die Abrechnung erfolgt basierend auf dem tatsächlichen Token-Verbrauch.

Q5: Ist die Latenz bei Modellaufrufen mit Tools in OpenClaw normal?

Tool-Aufrufe beinhalten mehrere API-Anfragen (Anfrage senden → tool_use erhalten → Tool ausführen → tool_result zurückgeben → finale Antwort erhalten). Dieser Prozess ist naturgemäß langsamer als ein reiner Chat. Durch die latenzarme Proxy-Verbindung von APIYI (apiyi.com) lässt sich die Verzögerung pro API-Aufruf jedoch in einem angemessenen Rahmen halten.

Zusammenfassung: 3 Kernpunkte für die OpenClaw-Anbindung an die Claude API

Basierend auf unseren Praxistests sollten Sie bei der Anbindung von OpenClaw an die Claude API folgende Punkte beachten:

  1. Das anthropic-messages Format ist obligatorisch: Setzen Sie api: "anthropic-messages". Dies ist die Voraussetzung für stabile Tool-Aufrufe. Das Format openai-completions führt bei mehrstufigen Tool-Aufrufen zu 400-Fehlern.
  2. 3 häufige Fehlerquellen vermeiden: baseUrl ohne /v1 angeben, anthropic-beta und reasoning deaktivieren sowie den Cache bestehender Sessions berücksichtigen.
  3. Den richtigen Proxy-Anbieter wählen: APIYI (apiyi.com) unterstützt die native Anthropic Messages API vollständig. In OpenClaw-Tests wurde bestätigt, dass sowohl Tool-Aufrufe als auch Prompt Caching stabil funktionieren.

Wir empfehlen, die Anbindung von OpenClaw an die Claude API über APIYI (apiyi.com) vorzunehmen. Die Konfiguration ist in 5 Minuten erledigt und die Tool-Aufrufe sind sofort einsatzbereit.

openclaw-claude-api-apiyi-anthropic-messages-guide-de 图示

Referenzen

  1. OpenClaw Offizielle Dokumentation – Model Providers: Konfigurationsanleitung für Modellanbieter

    • Link: docs.openclaw.ai/concepts/model-providers

  2. Anthropic Offizielle Dokumentation – Messages API: Natives Claude API-Aufrufformat

    • Link: platform.claude.com/docs/en/api/messages

  3. Anthropic Offizielle Dokumentation – OpenAI SDK Kompatibilität: Funktionseinschränkungen im Kompatibilitätsmodus

    • Link: platform.claude.com/docs/en/api/openai-sdk

  4. OpenClaw GitHub Repository: Open-Source-Code und Issue-Diskussionen

    • Link: github.com/openclaw/openclaw

📝 Autor: APIYI Team | APIYI Technik-Team, spezialisiert auf die Integration von APIs für große Sprachmodelle und technischen Wissensaustausch. Besuchen Sie apiyi.com für weitere technische Tutorials und API-Schlüssel.

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Ähnliche Beiträge