OpenAI → Claude Migration Tutorial (2026)

Beide SDKs akzeptieren jetzt die gleiche `messages: [{role, content}]` Array-Form. Die Unterschiede: Methodenname, Response-Struktur und wie System-Prompts übergeben werden. Hier ist der kanonische Diff für eine einfache Completion.

```python # OpenAI (vorher) from openai import OpenAI client = OpenAI() resp = client.chat.completions.create( model="gpt-5.5", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize: ..."} ], max_tokens=500, ) answer = resp.choices[0].message.content ```

```python # Anthropic (nachher) import anthropic client = anthropic.Anthropic() resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system="You are a helpful assistant.", messages=[ {"role": "user", "content": "Summarize: ..."} ], ) answer = resp.content[0].text ```

Drei Unterschiede. **System-Prompt ist ein eigenes Feld** bei Claude (`system=`), nicht eine Message im Array. **`max_tokens` ist erforderlich** bei Claude (OpenAI defaultet auf Model-Max). **Response-Form** ist `resp.content[0].text` (ein Array von Content-Blöcken) statt `resp.choices[0].message.content`.

Streaming funktioniert konzeptionell auf die gleiche Weise — beide bieten `with client.<x>.stream(...)` Context-Manager. Anthropics Events sind stärker strukturiert (`content_block_start`, `content_block_delta`, `content_block_stop`), wo OpenAIs Stream eine flache Sequenz von Completion-Chunks ist. Die meisten Production-Codes iterieren einfach über den Stream und verketteten `delta.text` (Claude) oder `delta.content` (OpenAI) — beide funktionieren.

GPT-Modelle funktionieren gut mit Markdown-strukturierten System-Prompts (`# Überschrift`, `**fett**`, nummerierte Listen). Claude-Modelle funktionieren deutlich besser mit XML-Tag-Struktur. Anthropics eigener Prompt-Engineering-Guide empfiehlt XML-Tags als kanonische Methode zur Abgrenzung von Abschnitten — `<context>`, `<instructions>`, `<example>`, `<output_format>`, `<constraints>`.

Vorher (GPT-optimiert):

``` You are a senior product analyst. ## Task Write a competitive analysis of X. ## Context The customer is... ## Output Return JSON with... ```

Nachher (Claude-optimiert):

``` You are a senior product analyst. <task> Write a competitive analysis of X. </task> <context> The customer is... </context> <output_format> Return JSON with... </output_format> ```

Warum das wichtig ist: Claudes Attention-Muster ist darauf ausgerichtet, XML-Tag-Grenzen zu erkennen und Content darin angemessen zu gewichten. Markdown-Überschriften funktionieren, erfordern aber, dass Claude die Struktur aus Konvention ableitet. XML-Tags machen die Struktur explizit und verbessern Output-Qualität bei komplexen Prompts erheblich. In einer 50-Prompt-Evaluation, die wir im Mai 2026 über Customer-Support-Klassifizierungsaufgaben laufen ließen, erhöhte die gleiche Prompt-Umstrukturierung von Markdown zu XML die Sonnet-4.6-Genauigkeit um 7-12 Prozentpunkte.

Few-Shot-Beispiele funktionieren auch besser, wenn sie in `<example>...</example>` Tags eingebunden sind. Das schließende Tag ist wichtig — unvollständige Tags (`<example>` ohne `</example>`) verwirren Claudes Parsing.

OpenAIs Prompt-Caching ist opportunistisch und Präfix-nur — Sie erhalten Einsparungen automatisch, wenn Ihr System-Prompt stabil ist. Claudes Prompt-Caching ist *explizit* — Sie markieren Breakpoints im Message-Array und zahlen einen Premium auf den Cache-Write (1,25x für 5-Min TTL, 2x für 1-Stunden TTL) im Austausch für 10% Read-Kosten (90% Einsparung) bei nachfolgenden Hits.

Das explizite Modell ist stärker, weil Sie jeden Teil des Inputs cachen können, nicht nur das wörtliche Präfix. Cache System-Prompt + Tools + erstes Few-Shot-Beispiel; variieren Sie die User-Query frei. Beispiel:

```python # Cache das stabile Präfix (System + Tools + Few-Shot) resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system=[ { "type": "text", "text": SYSTEM_PROMPT, # stabil über Aufrufe "cache_control": {"type": "ephemeral"} } ], tools=TOOL_DEFINITIONS, # auch gecacht über den System-Breakpoint oben messages=[ {"role": "user", "content": user_input} # nicht gecacht ], ) ```

Break-Even auf dem 1-Stunden-Cache-Write (2x Premium) tritt nach exakt 2 Hits auf — trivial, für Production-Agenten zu löschen. Bei einem 2.000-Token-System-Prompt + 1.500-Token-Tools (3.500 gecachte Token) auf Sonnet 4.6 100-mal in einer Stunde gelesen:

Cache-Write: 3.500 / 1M × $6 = $0,021 (einmalig). Cache-Reads: 99 × 3.500 / 1M × $0,30 = $0,10395. Gesamte gecachte Kosten: $0,125. Ohne Cache: 100 × 3.500 / 1M × $3 = $1,05. **Einsparung: $0,925 — 88% Rabatt auf den Präfix-Teil der Rechnung**.

Dies ist der größte Kostenhebel der Migration. Teams, die von OpenAI zu Claude wechseln, ohne explizite Cache-Breakpoints einzurichten, zahlen oft *mehr* — weil die Annahme ‚Claude ist günstiger' auf gecachten Preisen beruhte, die sie nicht aktiviert haben. Cache-Setup ist nicht optional für Production-Migrationen.

Beide APIs unterstützen Tool-Use (Function-Calling). Die Schemas unterscheiden sich leicht. OpenAIs Tools sind `{type: 'function', function: {name, description, parameters}}`. Claudes Tools sind `{name, description, input_schema}` — flacher, kein umhüllendes `function`-Wrapper.

OpenAI (vorher):

```python tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather", "parameters": { "type": "object", "properties": { "location": {"type": "string"} } } } } ] ```

Claude (nachher):

```python tools = [ { "name": "get_weather", "description": "Get current weather", "input_schema": { "type": "object", "properties": { "location": {"type": "string"} } } } ] ```

Tool-Responses unterscheiden sich auch. OpenAI gibt `tool_calls` auf der Assistant-Message zurück. Claude gibt `tool_use`-Content-Blöcke im Messages-Array zurück. Loop-Konstruktion:

```python # Claude Tool-Loop while True: resp = client.messages.create(model="claude-sonnet-4-6", tools=tools, messages=messages) if resp.stop_reason == "end_turn": break messages.append({"role": "assistant", "content": resp.content}) for block in resp.content: if block.type == "tool_use": result = run_tool(block.name, block.input) messages.append({"role": "user", "content": [ {"type": "tool_result", "tool_use_id": block.id, "content": result} ]}) ```

Zwei Fallstricke. Erstens erfordert Claude, dass das Tool-Result eine `user`-Message mit `tool_result`-Content-Block ist — nicht eine separate `tool`-Role wie OpenAI. Zweitens werden parallele Tool-Aufrufe als mehrere `tool_use`-Blöcke im gleichen Assistant-Turn zurückgegeben — Ihr Tool-Runner muss sie parallel verarbeiten und alle Results in einer User-Message zurückgeben.

Jetzt die echte Kostenrechnung für Ihren Workload. Nehmen Sie eine repräsentative Production-Form: 1M Aufrufe/Monat, durchschnittlich 2.000 Token Input, 500 Token durchschnittlicher Output, mit einem 1.500-Token-stabilen System-Präfix (Caching-Kandidat).

**Vorher — gpt-5.5 ohne Cache** (OpenAIs opportunistischer Cache kann helfen, aber nicht hier modelliert):

Input: 1M × 2.000 / 1M = 2.000M Token × $5/1M = $10.000. Output: 1M × 500 / 1M = 500M Token × $30/1M = $15.000. **Gesamt: $25.000/Monat**.

**Nachher — Claude Sonnet 4.6 ohne Cache**:

Input: 2.000M × $3/1M = $6.000. Output: 500M × $15/1M = $7.500. **Gesamt: $13.500/Monat** — 46% Einsparung selbst ohne Caching.

**Nachher — Claude Sonnet 4.6 mit explicitem Caching** (1-Stunden TTL auf 1.500-Token-Präfix, 90% Cache-Hit-Rate):

Cache-Writes: 0,1M (Cache Miss) × 1.500/1M × $6 = $900. Cache-Reads: 0,9M × 1.500/1M × $0,30 = $405. Nicht-gecachte Input-Portion (500 verbleibende Token × 1M) = 500M × $3/1M = $1.500. Output: $7.500. **Gesamt: $10.305/Monat** — 59% Einsparung gegenüber OpenAI.

**Jährliches Delta**: $25.000 × 12 - $10.305 × 12 = $300.000 - $123.660 = **$176.340/Jahr gespart** bei diesem Workload.

Wichtiger Vorbehalt: gpt-5.5 → Sonnet 4.6 ist die High-Leverage-Migration. gpt-5.4 → Sonnet 4.6 kostet tatsächlich *mehr* pro Aufruf ($3 Input vs $2,50). gpt-5.4-mini → Haiku 4.5 kostet auch mehr (+33% Input). Bei der Small/Nano-Stufe gewinnt OpenAI bei Preis. Migrieren Sie Premium und Mid-Tier; behalten Sie Small und Nano auf OpenAI. Der Kostenrechner wird workload-spezifisch, nicht organisationsspezifisch.

**Eval-Parität zuerst**. Führen Sie beide Provider auf Ihrem Held-Out-Eval-Set aus, bevor Sie umschalten. Der gleiche Prompt für Claude umstrukturiert sollte das GPT-Baseline-Level treffen oder übersteigen; falls nicht, haben Sie ein Prompt-Problem, nicht ein Model-Problem.

**Shadow-Traffic für eine Woche**. Leiten Sie 5-10% des Production-Traffic an Claude parallel zu OpenAI, protokollieren Sie beide Outputs, vergleichen Sie Qualität. Erfassen Sie stille Regressionen, bevor sie zu Benutzern gelangen.

**Richten Sie Ihr Monitoring vor der Umstellung ein**. Token-Counts, Latenz, Fehlerquoten, Cache-Hit-Ratio. Die Cache-Hit-Ratio ist die Metrik, die bestimmt, ob Ihre Migrations-Mathematik in Production hält — verfolgen Sie sie explizit.

**Planen Sie einen Rollback-Pfad**. Feature-Flag die Model-Wahl in Ihrem Code; wechseln Sie in Sekunden zurück zu OpenAI, falls Qualität sinkt. Reißen Sie OpenAI nicht am Tag 1 der Umstellung aus Ihrer Abhängigkeitsliste.

**Kommunizieren Sie mit Benutzern nur wenn relevant**. Die meisten benutzerseitigen AI-Features müssen Model-Änderungen nicht bewerben. Interne Tools könnten (Entwickler interessieren sich für welches Model ihren Code vorschlägt).

Beide APIs streamen Token. Die Event-Form unterscheidet sich genug, dass naives Copy-Paste von Streaming-Code subtil fehlschlägt. OpenAI streamt eine flache Sequenz von `chunk.choices[0].delta.content`-Strings; Claude streamt strukturierte Events mit expliziten Start/Delta/Stop-Grenzen auf jedem Content-Block.

OpenAI-Streaming-Muster:

```python stream = client.chat.completions.create( model="gpt-5.5", messages=messages, stream=True, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ```

Claude-Streaming-Muster:

```python with client.messages.stream( model="claude-sonnet-4-6", max_tokens=500, messages=messages, ) as stream: for text in stream.text_stream: print(text, end="") ```

Der `text_stream`-Helper auf Claude vereinfacht die strukturierten Events zu einem einfachen String-Stream — die meisten Production-Codes nutzen ihn. Falls Sie feiner kontrollen müssen (z.B. Tool_use-Blöcke mid-Stream verarbeiten, Reasoning-Content separat anzeigen), fallen Sie auf die Event-Level-API zurück und pattern-match auf `event.type`.

Tool-Use-Streaming unterscheidet sich sinnvoll auf Claude. Tool-Input-JSON streamt als partiales JSON-Delta innerhalb `content_block_delta`-Events mit `delta.type === 'input_json_delta'`. Naives String-Concatenation funktioniert, aber Sie müssen auf das `content_block_stop`-Event warten, bevor Sie das vollständige JSON parsen. OpenAIs Streaming-Tool-Calls haben ein ähnliches partiales-JSON-Muster; die Feldnamen unterscheiden sich.

**Fehler 1: Annahme, Claude ist günstiger, ohne die Stufe zu überprüfen.** Sonnet 4.6 vs gpt-5.4 ist ungefähr ausgeglichen, und Haiku 4.5 ist tatsächlich *teurer* als gpt-5.4-mini. Die Einsparungen kommen von der Premium-Stufe (Opus 4.8 vs gpt-5.5-pro) und der Mid-Tier mit Caching (Sonnet 4.6 + 1-Stunden-Cache vs gpt-5.5).

**Fehler 2: Prompts wörtlich kopieren.** Markdown-Struktur funktioniert auf Claude, aber XML-Tag-Struktur funktioniert besser. Die Prompt-Umstrukturierung überspringen, lässt Qualität auf dem Tisch liegen.

**Fehler 3: Explizite Cache-Breakpoints überspringen.** Die Behauptung ‚Claude ist günstiger' hängt von Caching ab. Ohne explizite Breakpoints zahlen Sie möglicherweise mehr pro Aufruf als das OpenAI-Äquivalent. Richten Sie Caching als Teil der Migration ein, nicht als Follow-Up.

**Fehler 4: Parallele Tool-Calls nicht verarbeiten.** Claude gibt mehrere `tool_use`-Blöcke pro Turn zurück, wenn es parallele Tool-Calls tätigt. Ihr Tool-Runner muss sie parallel verarbeiten und alle Results in einer User-Message zurückgeben.

**Fehler 5: `max_tokens` auf OpenAI-Defaults halten.** Claude erfordert `max_tokens` zu sein explizit. Alter Code, der auf OpenAIs Default (Model-Max) vertraute, muss eine echte Obergrenze setzen — typischerweise 500-2.000 für Chat-Use-Cases. Setzen Sie es nicht zu hoch; Sie zahlen für Output, den Sie nicht brauchen.