| |

6 Gründe, warum Claude Code den OpenAI-kompatiblen Modus anstelle von /v1/messages verwendet (Vollständiger Leitfaden zur Fehlerbehebung für die NPM-Version)

VonAPIYI - Stable and affordable AI API

Anmerkung des Autors: Die über NPM installierte Claude Code sollte eigentlich die native /v1/messages-Schnittstelle verwenden, sendet aber stattdessen Anfragen an /v1/chat/completions? Dieser Artikel analysiert die 6 Hauptursachen basierend auf den offiziellen Mechanismen, bietet einen 5-stufigen Diagnoseplan und zeigt die korrekte Konfiguration für die Anbindung an APIYI.

Gemäß der offiziellen Dokumentation sollte @anthropic-ai/claude-code, das über NPM installiert wurde, in einer Befehlszeilenumgebung immer Anfragen an den /v1/messages-Endpunkt senden – dies ist das native Messages-API-Protokoll von Anthropic, das den anthropic-version-Header und das native messages-Format enthält.

Wenn Ihr Client jedoch beim Abfangen des Datenverkehrs /v1/chat/completions (OpenAI Chat Completions-Format) sieht, deutet dies darauf hin, dass an irgendeiner Stelle eine Protokollkonvertierung oder eine Verwechslung der Paketnamen stattgefunden hat. Dies ist kein Bug von Claude Code selbst, sondern eines von 6 häufigen Konfigurations- oder Umgebungsproblemen.

Kernnutzen: Dieser Artikel analysiert diese 6 Ursachen vollständig (einschließlich der versehentlichen Installation von Drittanbieter-Paketen, einer auf einen kompatiblen Gateway zeigenden ANTHROPIC_BASE_URL, Abfangkonvertierungen durch claude-code-router usw.), bietet einen 5-stufigen Diagnoseplan und stellt die korrekte Konfiguration für die Anbindung über APIYI (apiyi.com) bereit, um sicherzustellen, dass der native /v1/messages-Pfad genutzt wird.

claude-code-openai-compatible-mode-instead-of-v1-messages-de 图示

I. Claude Code sollte standardmäßig /v1/messages verwenden: Analyse der Kernmechanismen

Bevor Sie mit der Fehlersuche beginnen, sollten Sie das erwartete Verhalten des offiziellen Claude Code verstehen, um beurteilen zu können, wo das Problem liegt.

1.1 Protokolldesign des offiziellen @anthropic-ai/claude-code

Das von Anthropic offiziell gewartete NPM-Paket @anthropic-ai/claude-code verwendet in allen Versionen ausschließlich das native Messages-API-Protokoll von Anthropic, was sich wie folgt äußert:

Dimension Verhalten von offiziellem Claude Code
Anfrage-Endpunkt POST {ANTHROPIC_BASE_URL}/v1/messages
Anfrage-Header x-api-key, anthropic-version: 2023-06-01, anthropic-beta
Anfrage-Body-Format { "model": "...", "messages": [...], "system": "...", "max_tokens": ... }
Antwort-Format { "content": [...], "stop_reason": "...", "usage": {...} }
Streaming-Antwort SSE-Event-Stream, Ereignistypen wie message_start, content_block_delta

Wenn Ihr Client beim Abfangen des Datenverkehrs /v1/chat/completions, Authorization: Bearer ... oder einen Anfrage-Body mit einem choices-Array sieht, handelt es sich um Merkmale des OpenAI-Protokolls. Dies deutet darauf hin, dass die Anfrage nicht den Pfad nimmt, den der offizielle Claude Code nehmen sollte.

1.2 Korrekte Semantik der kritischen Umgebungsvariablen

Der offizielle Claude Code erkennt nur die folgenden Umgebungsvariablen, um das API-Verhalten anzupassen:

# Erforderlich: Anthropic API-Schlüssel oder Schlüssel eines kompatiblen Dienstes
ANTHROPIC_AUTH_TOKEN=sk-your-key
# Oder synonyme Variable:
ANTHROPIC_API_KEY=sk-your-key

# Optional: Benutzerdefinierte API-Gateway-Adresse (ohne /v1-Suffix)
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Optional: Benutzerdefinierte Modell-ID
ANTHROPIC_MODEL=claude-sonnet-4-5
ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

Hinweis: Der offizielle Claude Code kennt keine Variablen wie OPENAI_BASE_URL oder CLAUDE_CODE_USE_OPENAI. Wenn diese Variablennamen in Ihrer Umgebung auftauchen, verwenden Sie einen Wrapper eines Drittanbieters.

💡 Empfehlung zur schnellen Überprüfung: Führen Sie im Terminal which claude aus, um den Installationspfad von Claude Code zu sehen, und führen Sie dann cat $(which claude) | head -20 aus. Wenn Sie den Schriftzug @anthropic-ai/claude-code sehen, ist die offizielle Version installiert. Wenn Sie Schlüsselwörter wie openclaude, claudex oder cli-agent-openai-adapter sehen, haben Sie die Ursache gefunden.

Zwei. 6 mögliche Gründe, warum Claude Code den OpenAI-Kompatibilitätsmodus nutzt

Sortiert nach Eintrittswahrscheinlichkeit; wir empfehlen, diese in der angegebenen Reihenfolge zu prüfen.

2.1 Grund 1: Versehentliche Installation eines Drittanbieter-OpenAI-Wrappers (ca. 35 % der Fälle)

Auf NPM gibt es mehrere Pakete mit ähnlichen Namen, die jedoch völlig andere Funktionen haben als "Claude Code" und speziell für die OpenAI-Kompatibilitätskonvertierung gedacht sind. Kunden könnten versehentlich eines davon installiert haben:

Paketname Tatsächliche Funktion Standardprotokoll
@anthropic-ai/claude-code ✅ Offizielles Paket /v1/messages
@gitlawb/openclaude OpenAI-Shim /v1/chat/completions
@aryanjsx/openclaude OpenAI-Shim /v1/chat/completions
cli-agent-openai-adapter Protokoll-Konverter /v1/chat/completions
claude-code-openai-wrapper Dual-Protokoll-Wrapper Unterstützt beide
claudex In Go geschriebener OpenAI-Proxy /v1/chat/completions

Prüfmethode:

# 1. Tatsächlichen Installationspfad anzeigen
which claude
# Ausgabebeispiel: /usr/local/bin/claude

# 2. Den Namen in der package.json des Pakets prüfen
cat $(npm root -g)/@anthropic-ai/claude-code/package.json 2>/dev/null | grep '"name"'

# 3. Alle global installierten Claude-bezogenen Pakete auflisten
npm list -g --depth=0 | grep -i claude

Wenn npm list kein @anthropic-ai/claude-code enthält, aber andere ähnlich benannte Pakete, liegt eine Fehlinstallation vor.

2.2 Grund 2: Konfiguration von Routing-Tools wie claude-code-router (ca. 25 % der Fälle)

claude-code-router (CCR) ist ein beliebtes Community-Tool, das Claude Code-Anfragen abfängt und an verschiedene Modelle (z. B. OpenAI, DeepSeek, Zhipu) weiterleitet. Funktionsweise:

  1. Startet einen lokalen Proxy-Server (Standard http://localhost:3456)
  2. Der Benutzer leitet ANTHROPIC_BASE_URL auf diesen lokalen Proxy um
  3. CCR empfängt die /v1/messages-Anfrage, übersetzt sie in /v1/chat/completions und leitet sie an das Zielmodell weiter
  4. Bei einer Paketaufzeichnung sieht man daher das OpenAI-Protokoll

Prüfmethode:

# Umgebungsvariablen prüfen
env | grep -i ANTHROPIC

# Wenn Sie ANTHROPIC_BASE_URL=http://localhost:3456 oder ähnlich sehen,
# handelt es sich höchstwahrscheinlich um CCR / claude-code-router oder einen ähnlichen lokalen Proxy.

2.3 Grund 3: ANTHROPIC_BASE_URL verweist auf ein OpenAI-kompatibles Gateway (ca. 20 % der Fälle)

Einige LLM-Gateways (wie LiteLLM Proxy, OneAPI, Bifrost) unterstützen zwar die Konfiguration von Anthropic-Modellen, exponieren jedoch nur die /v1/chat/completions-Schnittstelle. Wenn der Kunde ANTHROPIC_BASE_URL auf ein solches Gateway richtet:

  • Claude Code sendet weiterhin Anfragen gemäß /v1/messages
  • Das Gateway gibt einen 404-Fehler zurück oder schreibt den Pfad automatisch um
  • Das Gateway konvertiert intern in das OpenAI-Format für den Upstream-Aufruf
  • Wenn das Paket-Sniffing-Tool hinter dem Gateway eingesetzt wird, sieht man das OpenAI-Protokoll

Prüfmethode: Prüfen Sie, ob ANTHROPIC_BASE_URL auf ein bekanntes OpenAI-kompatibles Gateway verweist und ob die Anfrage tatsächlich erfolgreich ist (200 oder 404).

2.4 Grund 4: Umgebungsvariablen für Drittanbieter-Wrapper gesetzt (ca. 10 % der Fälle)

Einige Wrapper-Pakete schalten den Protokollmodus über Umgebungsvariablen um, zum Beispiel:

# Umschaltvariable für openclaude
CLAUDE_CODE_USE_OPENAI=1
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://api.openai.com/v1

Selbst wenn das offizielle Paket via npm installiert wurde, greifen diese Variablen, falls sich ein Wrapper-Skript im PATH befindet (z. B. wenn /usr/local/bin/claude tatsächlich ein Wrapper ist).

Prüfmethode:

# Alle ausführbaren Dateien namens claude im PATH auflisten
type -a claude

# Auf relevante Umgebungsvariablen prüfen
env | grep -E 'CLAUDE_CODE|OPENAI_BASE_URL|OPENAI_MODEL'

2.5 Grund 5: Shell-Alias oder Wrapper-Skript-Abfang (ca. 7 % der Fälle)

Kunden könnten in ihrer ~/.bashrc oder ~/.zshrc einen Alias konfiguriert haben:

# Dieser Alias ersetzt den ursprünglichen claude-Befehl
alias claude='openclaude'
alias claude='claude-code-router run'

# Oder eine Funktion mit gleichem Namen definiert
claude() {
  CCR_PROXY=http://localhost:3456 command claude "$@"
}

Prüfmethode:

# Alias anzeigen
alias | grep claude

# Funktion anzeigen
type claude

# Shell-Startdateien durchsuchen
grep -nE 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

2.6 Grund 6: Fehlinterpretation durch Paketaufzeichnung (ca. 3 % der Fälle)

In seltenen Fällen ist das Paketaufzeichnungstool des Kunden falsch platziert, sodass die beobachteten Anfragen nicht die sind, die Claude Code tatsächlich sendet. Beispiel:

  • Claude Code → lokaler transparenter Proxy (z. B. mitmproxy) → Remote-OpenAI-Gateway
  • Das Aufzeichnungstool ist hinter dem Gateway platziert und sieht die umgeschriebene Anfrage
  • Tatsächlich sendet Claude Code jedoch /v1/messages

Prüfmethode: Verwenden Sie mitmproxy lokal auf dem Rechner des Kunden, um den Claude Code-Prozess direkt zu proxen und zu bestätigen, welches Protokoll der erste Hop verwendet.

Drei. 5 Schritte zur schnellen Diagnose von Claude Code-Protokollfehlern

claude-code-openai-compatible-mode-instead-of-v1-messages-de 图示

Gehen Sie die Punkte in der folgenden Reihenfolge durch; die meisten Protokollfehler lassen sich innerhalb der ersten 3 Schritte beheben.

3.1 Schritt 1: Sicherstellen, dass das offizielle NPM-Paket installiert ist

# Alle möglichen Wrapper deinstallieren
npm uninstall -g @gitlawb/openclaude @aryanjsx/openclaude cli-agent-openai-adapter claudex claude-code-router 2>/dev/null

# Offizielles Paket deinstallieren und neu installieren
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Versionsquelle verifizieren
claude --version
npm list -g @anthropic-ai/claude-code

Erfolgsbedingung: Die Ausgabe von npm list -g enthält @anthropic-ai/[email protected].

3.2 Schritt 2: PATH und Shell-Alias bereinigen

# Alle ausführbaren Dateien namens claude im PATH finden
type -a claude
which -a claude

# Alias / Funktion mit gleichem Namen aufheben
unalias claude 2>/dev/null
unset -f claude 2>/dev/null

# Claude-bezogene Konfigurationen in Shell-Startskripten prüfen und bereinigen
grep -n 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

Erfolgsbedingung: type -a claude gibt nur einen Pfad aus, der auf das offizielle Paket im globalen npm-Verzeichnis verweist.

3.3 Schritt 3: Konfliktverursachende Umgebungsvariablen bereinigen

# Alle Claude / OpenAI-bezogenen Variablen anzeigen
env | grep -iE 'claude|openai|anthropic'

# Mögliche Konfliktvariablen löschen
unset CLAUDE_CODE_USE_OPENAI
unset OPENAI_BASE_URL
unset OPENAI_MODEL
unset CCR_PROXY

# Nur die für das offizielle Paket benötigten Variablen beibehalten
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"

🎯 Wichtiger Hinweis: ANTHROPIC_BASE_URL sollte auf die Domain-Wurzel zeigen (ohne /v1-Suffix), da Claude Code automatisch /v1/messages anhängt. Wenn Sie https://vip.apiyi.com/v1 eingeben, wird daraus https://vip.apiyi.com/v1/v1/messages, was zu einem 404-Fehler führt.

3.4 Schritt 4: Testen, ob base_url nativ /v1/messages unterstützt

Verwenden Sie curl, um die Anfrage von Claude Code zu simulieren und zu verifizieren, ob das Gateway das native Anthropic-Protokoll tatsächlich unterstützt:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Erfolgsbedingung: Antwort 200, der Antwortkörper enthält "type": "message" und "content": [...].

Wenn ein 404-Fehler zurückgegeben wird oder der Antwortkörper das OpenAI-Format (mit choices) aufweist, unterstützt das Gateway unter ANTHROPIC_BASE_URL das native Anthropic-Protokoll nicht. In diesem Fall löst ein Wechsel zu APIYI (apiyi.com) das Problem sofort – es unterstützt nativ /v1/messages und ist zudem mit /v1/chat/completions kompatibel, sodass beide Protokolle funktionieren.

3.5 Schritt 5: Lokale Paketaufzeichnung zur Verifizierung der endgültigen Anfrage

Wenn die ersten 4 Schritte erfolgreich waren, das Problem aber weiterhin besteht, verwenden Sie mitmproxy für eine lokale Paketaufzeichnung:

# mitmproxy starten (Standardport 8080)
mitmproxy --listen-port 8080

# Claude Code über den lokalen Proxy leiten
export HTTPS_PROXY=http://localhost:8080
export HTTP_PROXY=http://localhost:8080

# Claude Code starten
claude

Erfolgsbedingung: Die erste von mitmproxy aufgezeichnete Anfrage ist POST /v1/messages und der Request-Header enthält anthropic-version.

IV. Vollständige Konfiguration für die Anbindung von Claude Code an APIYI über das native /v1/messages-Protokoll

APIYI (apiyi.com) ist einer der wenigen API-Proxy-Dienste, der das native Anthropic Messages API-Protokoll unterstützt. Dies stellt sicher, dass Claude Code über /v1/messages und nicht über /v1/chat/completions kommuniziert.

4.1 Konfiguration der Umgebungsvariablen (einfachste Methode)

# macOS / Linux
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
# Optional: Standardmodell festlegen
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://vip.apiyi.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-apiyi-key"

# Claude Code starten
claude

4.2 Dauerhafte Konfiguration in der Shell-Startdatei

# An ~/.zshrc oder ~/.bashrc anhängen
cat >> ~/.zshrc <<'EOF'

# Claude Code → APIYI apiyi.com Proxy-Konfiguration
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
export ANTHROPIC_MODEL="claude-sonnet-4-5"
EOF

# Änderungen laden
source ~/.zshrc

4.3 Über die integrierten Konfigurationsbefehle von Claude Code (empfohlen)

Claude Code bietet ein eigenes CLI zur Konfiguration, um das Durchsickern von Umgebungsvariablen zu vermeiden:

# Methode 1: Interaktiv
claude /login
# Wählen Sie "Custom Endpoint" und geben Sie https://vip.apiyi.com sowie Ihren API-Schlüssel ein

# Methode 2: Konfigurationsdatei direkt bearbeiten
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-apiyi-key"
  }
}
EOF

4.4 Überprüfung des tatsächlichen Anforderungspfads

Starten Sie nach der Konfiguration von Claude Code ein neues Terminal und führen Sie den folgenden Befehl zur Überprüfung aus:

# Methode 1: Paket-Capture mit mitmproxy (am genauesten)
mitmproxy --listen-port 8080
# Starten Sie Claude Code in einem anderen Terminal mit HTTPS_PROXY=http://localhost:8080

# Methode 2: Debug-Protokolle von Claude Code aktivieren
ANTHROPIC_LOG=debug claude
# Das Protokoll zeigt die vollständige Anforderungs-URL und die Methode an

Erwartetes Ergebnis: Alle Anforderungs-URLs lauten https://vip.apiyi.com/v1/messages, die Methode ist POST und der Header enthält anthropic-version: 2023-06-01.

4.5 Kernvorteile der Anbindung an APIYI

Vorteil Beschreibung
Natives /v1/messages-Support Standardprotokoll für Claude Code, kein Konvertierungsverlust
Unterstützt auch /v1/chat/completions Ein Schlüssel für zwei Protokolle, flexible Anpassung
Vollständige Beibehaltung der anthropic-beta-Header Unterstützt Prompt Caching, Tool Use und weitere erweiterte Funktionen
Keine Begrenzung der Parallelität Keine Ratenbegrenzung bei langen Claude Code-Sitzungen
10% Bonus bei 100 USD Aufladung Entspricht einem Rabatt von 15% gegenüber der offiziellen Website
Zahlung in RMB möglich Direkte Zahlung via WeChat/Alipay

V. Protokollvergleich: Natives /v1/messages vs. OpenAI /v1/chat/completions

claude-code-openai-compatible-mode-instead-of-v1-messages-de 图示

Das Verständnis der Kernunterschiede zwischen beiden Protokollen ist entscheidend, um zu beurteilen, warum Claude Code das native Protokoll benötigt, um sein volles Potenzial auszuschöpfen.

Dimension Anthropic /v1/messages OpenAI /v1/chat/completions
Authentifizierungs-Header x-api-key: sk-... Authorization: Bearer sk-...
Versions-Header anthropic-version: 2023-06-01 Keine (über URL-Versionsnummer)
Feature-Header anthropic-beta: prompt-caching-... Kein einheitlicher Standard
System-Feld Unabhängiges Feld auf oberster Ebene Als Systemrolle in messages[0]
Antwortformat { "content": [...], "stop_reason": "..." } { "choices": [{ "message": {...} }] }
Streaming-Ereignisse Strukturierte Ereignisse wie message_start, content_block_delta Generisches SSE data: {...}
Tool-Aufrufe Eingebettetes tool_use in Inhaltsblöcken choices[0].message.tool_calls
Token-Zählung usage.input_tokens / usage.output_tokens usage.prompt_tokens / usage.completion_tokens

Wichtiges Fazit: Claude Code nutzt intensiv exklusive Anthropic-Funktionen (Prompt Caching, Tool-Use-Streaming, Reasoning Content etc.). Bei einer erzwungenen Konvertierung in das OpenAI-Protokoll gehen diese Fähigkeiten verloren oder führen zu inkonsistentem Verhalten. Deshalb ist es zwingend erforderlich, sicherzustellen, dass die Kommunikation über das native /v1/messages-Protokoll erfolgt.

VI. Checkliste für die Fehlerbehebung nach Einsatzszenarien

6.1 Szenario 1: Lokale Nutzung durch Einzelentwickler

Häufigste Ursache: Ein Shell-Alias oder ein Wrapper mit demselben Namen im PATH.

Checkliste:

  • Enthält npm list -g das Paket @anthropic-ai/claude-code?
  • Zeigt type -a claude ausschließlich auf das offizielle Paket?
  • Gibt es in ~/.zshrc / ~/.bashrc einen alias claude=...?
  • Gibt es in env | grep -i claude nicht standardmäßige Variablen?
  • Wurde bei ANTHROPIC_BASE_URL ein /v1-Suffix angehängt? (Dies sollte nicht der Fall sein.)

6.2 Szenario 2: Bereitstellung in Team-/Unternehmensumgebungen

Häufigste Ursache: Das interne LLM-Gateway unterstützt nur das OpenAI-Protokoll.

Checkliste:

  • Unterstützt das Unternehmens-Gateway nativ den /v1/messages-Endpunkt?
  • Leitet das Gateway die Request-Header anthropic-version und anthropic-beta weiter?
  • Behält das Gateway das ursprüngliche SSE-Event-Format bei?
  • Gibt es ein einheitliches Wrapper-Skript für das Team?

Falls das Unternehmens-Gateway tatsächlich nur das OpenAI-Protokoll unterstützt, empfiehlt es sich, die ANTHROPIC_BASE_URL des Clients auf APIYI (apiyi.com) umzustellen. Dies ermöglicht eine direkte native Protokollverbindung und vermeidet Konvertierungsverluste.

6.3 Szenario 3: Aufruf von Claude Code in CI/CD-Umgebungen

Häufigste Ursache: Ein Drittanbieter-Wrapper ist fest im CI-Skript verankert.

Checkliste:

  • Installiert die CI-Konfigurationsdatei per npm install -g ein inoffizielles Paket?
  • Gibt es in den CI-Umgebungsvariablen Einträge wie CLAUDE_CODE_USE_OPENAI=1?
  • Ist im CI-Runner-Image ein Wrapper vorinstalliert?

6.4 Szenario 4: Ausführung innerhalb von Docker-Containern

Häufigste Ursache: Das Basis-Image enthält einen vorinstallierten Wrapper.

Checkliste:

  • Ist der Paketname bei RUN npm install -g im Dockerfile der offizielle?
  • Wohin zeigt which claude innerhalb des Containers?
  • Sind in den ENV-Variablen des Containers Variablen für den Protokollwechsel gesetzt?

VII. FAQ zu Protokollproblemen bei Claude Code

Q1: Ich habe das offizielle @anthropic-ai/claude-code installiert, warum wird trotzdem das OpenAI-Protokoll verwendet?

Die wahrscheinlichste Ursache ist, dass die ANTHROPIC_BASE_URL auf ein OpenAI-kompatibles Gateway zeigt. Einige Gateways wandeln /v1/messages-Anfragen intern in /v1/chat/completions um, um das Upstream-Modell anzusprechen. Wenn Sie ein Paket-Sniffing-Tool hinter dem Gateway einsetzen, sehen Sie das konvertierte Protokoll.

Die Lösung besteht darin, die ANTHROPIC_BASE_URL auf APIYI (apiyi.com) zu setzen, da dieses nativ /v1/messages unterstützt und keine Konvertierungsverluste verursacht.

Q2: Wie deinstalliere ich alle potenziellen Claude-Wrapper vollständig?

# Alle claude-bezogenen globalen Pakete auflisten
npm list -g --depth=0 | grep -i claude

# Bekannte Wrapper in einem Schritt deinstallieren
npm uninstall -g \
  @gitlawb/openclaude \
  @aryanjsx/openclaude \
  cli-agent-openai-adapter \
  claudex \
  claude-code-router \
  ccr \
  2>/dev/null

# Offizielles Paket neu installieren
npm install -g @anthropic-ai/claude-code

# Überprüfung
which claude
claude --version

Q3: Auf welcher Ebene sollte der Pfad für ANTHROPIC_BASE_URL angegeben werden?

Geben Sie nur die Domain-Wurzel an, ohne /v1-Suffix. Claude Code fügt intern automatisch /v1/messages hinzu.

# ✅ Korrekt
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"

# ❌ Falsch (würde zu /v1/v1/messages führen)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"

# ❌ Falsch (enthält bereits den Endpunkt-Pfad)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1/messages"

Q4: Warum empfehlen manche Anleitungen die Installation von claude-code-router?

claude-code-router ist ein Community-Tool, das hauptsächlich dazu dient, Claude Code dazu zu bringen, Nicht-Anthropic-Modelle aufzurufen (wie DeepSeek, Zhipu, lokales Ollama usw.). Dies wird durch Protokollkonvertierung erreicht.

Wenn Sie lediglich das originale Anthropic Claude-Modell (wie Claude Sonnet 4.5, Opus 4.7) nutzen möchten, benötigen Sie CCR nicht. Verbinden Sie sich einfach direkt mit APIYI (apiyi.com) über das native /v1/messages-Protokoll für ein besseres Erlebnis ohne Konvertierungsverluste.

Q5: Unterstützt APIYI (apiyi.com) sowohl /v1/messages als auch /v1/chat/completions?

Ja, APIYI ist vollständig kompatibel mit beiden Protokollen:

  • https://vip.apiyi.com/v1/messages — Anthropic natives Format (Standard bei Claude Code)
  • https://vip.apiyi.com/v1/chat/completions — OpenAI-kompatibles Format

Ein API-Schlüssel kann für beide Protokolle verwendet werden, je nachdem, was das Client-Tool automatisch anfordert.

Q6: Ist die URL https://vip.apiyi.com/v1/messages beim Sniffing ein Garant für den nativen Modus?

Nicht unbedingt. Sie müssen zusätzlich prüfen:

  1. Der Request-Header enthält anthropic-version: 2023-06-01.
  2. Der Request-Body enthält auf oberster Ebene ein messages-Array und ein separates system-Feld (nicht als System-Rolle innerhalb von messages).
  3. Der Response-Body enthält "type": "message" und content: [...] (nicht choices: [...]).

Wenn die URL zwar /v1/messages lautet, der Request-Body aber das OpenAI-Format verwendet (mit System-Rolle innerhalb von messages), besitzt der Client eine eigene Konvertierungsschicht.

Q7: Welche Umgebungsvariable aktiviert die Debug-Protokolle für Claude Code?

# Ausgabe detaillierter HTTP-Request/Response-Logs
ANTHROPIC_LOG=debug claude

# Oder den Verbose-Modus verwenden
claude --verbose

# Diagnoseinformationen von Claude Code selbst anzeigen
claude /doctor

Die Debug-Logs zeigen die vollständige URL, Header und den Request-Body (sensible Felder werden maskiert) und sind der direkteste Weg, Protokollprobleme zu lokalisieren.

Q8: Mein Claude Code funktionierte bisher einwandfrei, ist aber plötzlich auf das OpenAI-Protokoll umgesprungen. Was könnte der Grund sein?

Die häufigsten Ursachen für plötzliche Änderungen:

  • Ein Update von Claude Code, bei dem versehentlich ein Drittanbieter-Paket mit demselben Namen per npm install -g installiert wurde.
  • Das Team hat kürzlich ein LLM-Gateway bereitgestellt und eine neue ANTHROPIC_BASE_URL verteilt.
  • Nach einem macOS-Update wurden bestimmte Aliase wieder aktiv.
  • Das Unternehmen hat einen transparenten Proxy für die Protokollkonvertierungs-Prüfung aktiviert.

Prüfen Sie bei der Fehlersuche zuerst die letzten Umgebungsänderungen (npm-Installationsprotokolle, Änderungen an der Shell-Konfiguration, Gateway-Änderungsmitteilungen).

VIII. Key Takeaways – Die wichtigsten Punkte

  • ✅ Das offizielle @anthropic-ai/claude-code verwendet immer /v1/messages; es gibt keinen offiziellen OpenAI-Kompatibilitätsmodus.
  • ✅ 6 mögliche Ursachen (nach Wahrscheinlichkeit): Installation eines Drittanbieter-Pakets / Abfangen durch claude-code-router / base_url verweist auf ein OpenAI-Gateway / Drittanbieter-Umgebungsvariablen / Shell-Alias / Fehlinterpretation durch Paket-Sniffing.
  • ✅ 5-Schritte-Schnelldiagnose: Paketnamen prüfen → PATH/Alias bereinigen → Umgebungsvariablen bereinigen → curl-Test der base_url → lokales Paket-Sniffing zur Validierung.
  • ✅ ANTHROPIC_BASE_URL darf kein /v1-Suffix enthalten, da Claude Code dies automatisch anhängt.
  • ✅ APIYI (apiyi.com) unterstützt nativ /v1/messages und ist gleichzeitig mit /v1/chat/completions kompatibel – ein Schlüssel für beide Protokolle.
  • ✅ Vorteile des nativen Protokolls: Volle Unterstützung für Anthropic-spezifische Funktionen wie Prompt Caching, Tool-Use und Reasoning Content.
  • ✅ Schnelle Validierungsmethode: Verwenden Sie ANTHROPIC_LOG=debug claude, um die tatsächliche Anforderungs-URL und -Methode einzusehen.

IX. Fazit

Die via NPM installierte Claude Code-Anwendung sollte in der Befehlszeilenumgebung immer das native /v1/messages-Protokoll verwenden – dies ist das fest kodierte Verhalten des offiziellen @anthropic-ai/claude-code-Pakets. Es gibt keinen offiziellen Schalter, um in den OpenAI-Kompatibilitätsmodus zu wechseln. Wenn bei der Paketüberprüfung tatsächlich /v1/chat/completions festgestellt wird, liegt das Problem definitiv in der Client-Umgebung: Entweder wurde ein Drittanbieter-Wrapper installiert, die ANTHROPIC_BASE_URL verweist auf ein Gateway, das nur das OpenAI-Protokoll unterstützt, oder ein Shell-Alias bzw. eine Umgebungsvariable führt zu einer Umleitung.

Wenn Sie den 5-Schritte-Diagnoseprozess aus Kapitel 3 befolgen, lassen sich die meisten Probleme innerhalb von 10 Minuten lokalisieren. Die häufigste Lösung ist: Deinstallation aller inoffiziellen Pakete → Neuinstallation von @anthropic-ai/claude-code → Konfiguration der ANTHROPIC_BASE_URL auf einen API-Proxy-Dienst, der nativ /v1/messages unterstützt.

APIYI (apiyi.com) wurde genau für solche Szenarien entwickelt – es bietet native Unterstützung für die Anthropic Messages API (inklusive vollständiger Durchleitung der Header anthropic-version und anthropic-beta) und ist gleichzeitig mit OpenAI Chat Completions kompatibel (ein Schlüssel für beide Protokolle). Es gibt keine Begrenzung der Parallelität (lange Claude Code-Sitzungen werden nicht gedrosselt), bei einer Aufladung von 100 USD erhalten Sie 10 % Bonus (entspricht einem Rabatt von 15 % gegenüber der offiziellen Website) und Zahlungen sind in RMB (via WeChat/Alipay) möglich. Die Konfiguration erfordert lediglich das Setzen der ANTHROPIC_BASE_URL auf https://vip.apiyi.com, ohne dass Codeänderungen erforderlich sind.

🎯 Nächste Schritte: Lassen Sie den Kunden die Prüfung gemäß Kapitel 3.1 → 3.2 → 3.3 durchführen, die ANTHROPIC_BASE_URL auf https://vip.apiyi.com ändern und nach dem Neustart von Claude Code mit ANTHROPIC_LOG=debug claude verifizieren, ob die Anforderungs-URL wieder auf /v1/messages zurückgekehrt ist.

Referenzmaterialien

  1. Offizielle Dokumentation zu Claude Code: Konfigurationsanleitung für das LLM-Gateway

    • Link: code.claude.com/docs/en/llm-gateway
    • Hinweis: Die offizielle Dokumentation stellt klar, dass Claude Code das Anthropic Messages API-Format verwendet.

  2. @anthropic-ai/claude-code NPM-Paket: Offizielle NPM-Paketseite

    • Link: npmjs.com/package/@anthropic-ai/claude-code
    • Hinweis: Stellen Sie sicher, dass Sie das offizielle Paket installiert haben.

  3. Offizielle Dokumentation zur Anthropic Messages API: Spezifikation des nativen Protokolls

    • Link: docs.anthropic.com/en/api/messages
    • Hinweis: Enthält vollständige Informationen zu Feldern, Request-Headern und Antwortformaten für den /v1/messages-Endpunkt.

  4. APIYI-Website: API-Proxy-Dienst für das native Anthropic-Protokoll

    • Link: apiyi.com
    • Hinweis: Unterstützt nativ /v1/messages sowie kompatible /v1/chat/completions-Endpunkte, bietet unbegrenzte Parallelität und gewährt 10 % Bonus bei einer Aufladung von 100 USD.

Autor: Technisches Team
Letzte Aktualisierung: 02.05.2026
Über APIYI: APIYI (apiyi.com) ist ein professioneller API-Proxy-Dienstleister für Claude, der die Anthropic Messages API nativ unterstützt (/v1/messages, inklusive vollständiger Durchleitung von anthropic-version und anthropic-beta) und gleichzeitig mit OpenAI Chat Completions (/v1/chat/completions) kompatibel ist. Wir bieten einen stabilen Zugang zur gesamten Claude-Serie, einschließlich Claude Sonnet 4.5, Claude Opus 4.7 und Claude Haiku 4.5. Bei einer Aufladung von 100 USD erhalten Sie 10 % Bonus (entspricht 15 % Rabatt gegenüber den offiziellen Preisen), profitieren von unbegrenzter Parallelität und erhalten schnellen technischen Support.

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