Claude Opus 4.7 Migrationsleitfaden — Breaking Changes und Loesungen (komplett)

1. An wen sich dieser Leitfaden richtet

Wie im Release-Artikel zu Claude Opus 4.7 beschrieben, ist Opus 4.7 der direkte Nachfolger von 4.6. Allerdings enthaelt er mehrere Breaking Changes in der API; ein blosser Modellnamen-Tausch kann zu 400 Bad Request fuehren.

Zielgruppe dieses Leitfadens:

• Entwicklerinnen und Entwickler, die claude-opus-4-6 ueber Anthropic-API/SDK nutzen
• Teams, die Claude ueber Bedrock oder Vertex AI einsetzen
• Wer bisher bei Opus 4.5 oder 4.1 geblieben ist und jetzt auf 4.7 springen will
• Produktivsysteme mit Extended Thinking (thinking: enabled) oder temperature

Als Primaerquelle dient der offizielle Migrationsleitfaden von Anthropic — hier sind vor allem die im deutschsprachigen Alltag haeufigsten Stolpersteine aufbereitet. Die offiziellen Angaben stehen unter platform.claude.com (Migration Guide).

2. Kurzfassung in drei Zeilen

Das TL;DR fuer alle, die es eilig haben:

1. Modellnamen von claude-opus-4-6 auf claude-opus-4-7 wechseln (SDK-Version aktualisieren)
2. Drei grosse Breaking Changes: Extended Thinking enabled weg (adaptive Thinking + effort), temperature/top_p/top_k weg, neuer Tokenizer (bis zu 1,35x mehr Tokens pro Text)
3. Was man dafuer bekommt: bessere Coding-Leistung, 1M Kontext (zum Standard-Tarif) und das neue Effort-Level xhigh

Details folgen ab dem naechsten Abschnitt.

3. Modellnamen aktualisieren

Der erste Schritt ist einfach — die Modellkennung austauschen.

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

Wenn die ID in Umgebungsvariablen oder Konfigurationsdateien steckt, sollte sie an einer zentralen Stelle liegen — das erleichtert auch die naechste Migration.

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

Die Tuecke dieser Migration: nur den Modellnamen zu aendern reicht oft nicht. Im Folgenden die Breaking Changes einzeln.

4. Breaking Change 1: Extended Thinking weg, adaptive Thinking ran

In Opus 4.6 hat man Extended Thinking mit thinking: {type: "enabled", budget_tokens: N} aktiviert. In 4.7 fuehrt diese Form zum 400-Fehler.

Stattdessen steuert das Modell die Denktiefe selbst — „adaptive thinking". Ausserdem ist in 4.7 Denken standardmaessig aus. Ohne thinking-Feld laeuft das Modell ohne Denken. Fuer tiefere Reasoning-Faehigkeit muss man explizit opt-in machen.

Before (4.6) / After (4.7)

# Before: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Before: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// After: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

Merkpunkte

• budget_tokens zur direkten Steuerung des Denkvolumens entfaellt
• Stattdessen legt output_config.effort fest, „wie gruendlich" nachgedacht wird
• Ohne thinking-Feld antwortet das Modell ohne Denken (Verhalten weicht von 4.6 ab — bitte beachten)

5. Breaking Change 2: Sampling-Parameter entfernt

Werte fuer temperature, top_p oder top_k ausserhalb der Defaults fuehren zum 400-Fehler. Anthropic formuliert klar: Verhalten wird ueber den Prompt gesteuert — nicht ueber Sampling.

# Before
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# After
client.messages.create(
    model="claude-opus-4-7",
    # temperature / top_p / top_k komplett entfernen
    messages=[...],
)

Wer bisher mit temperature=0.2 auf „moeglichst stabile Ausgabe" abzielte, erreicht das nun durch explizite Prompt-Anweisungen wie „bitte auf die gleiche Frage moeglichst konsistent antworten" oder durch strukturierte Ausgaben mit JSON-Schema.

Und wer temperature=1.2 fuer „mehr Kreativitaet" nutzte, schreibt im Prompt Tonalitaetsvorgaben wie „bildhaft und ueberraschend formulieren".

6. Breaking Change 3: Denkinhalt standardmaessig verborgen

In 4.6 wurde der Denkinhalt bei aktivem Denken standardmaessig als „summarized" im Response-Stream mitgeliefert. Viele UIs nutzten das fuer ein „denke nach…"-Indiz.

In 4.7 hat sich das leise geaendert: Thinking-Bloecke erscheinen zwar in der Antwort, das thinking-Feld ist aber leer. Ohne Opt-in bekommt man den Inhalt nicht.

Symptom

Das „denke nach"-Icon dreht ewig, die Antwort faengt gefuehlt spaet an. Nutzer sagen dann „Aufgehaengt?".

Loesung

# Wenn das Thinking-Summary wie in 4.6 ins UI fliessen soll
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # explizit setzen
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

Wer den Denkinhalt nur serverseitig braucht und dem UI nichts zeigt, kann display weglassen — das funktioniert weiter.

7. Breaking Change 4: Neuer Tokenizer (ca. 1,35x)

Opus 4.7 nutzt intern einen neuen Tokenizer. Das hilft der Qualitaet — kostet aber pro Text 1,0–1,35x mehr Tokens als in 4.6.

Folgen:

• Vorgaenge am max_tokens-Limit werden mitten in der Antwort abgeschnitten
• Eigene Token-Schaetzer a la tiktoken (fuer Abrechnung/Laengenpruefung) werden ungenau
• Werte aus /v1/messages/count_tokens weichen zwischen 4.6 und 4.7 ab
• Bei gleichem Prompt steigen Kosten und Latenz leicht

Loesung

# Before: in 4.6 fuer 16k Token Output-Puffer ausgelegt
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# After: Faktor 1,35 einrechnen
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1.35 ≈ 21600 → aufrunden
    messages=[...],
)

Gute Nachricht: 4.7 erlaubt das 1M-Kontextfenster zum Standard-API-Tarif (kein Long-Context-Premium). Die Token-Zahl steigt, aber man kann leichter „einfach alles in den Input werfen".

8. Breaking Change 5: Prefill entfernt

Bereits aus 4.6 uebernommen: Assistant-Prefill — also ein {role: "assistant", content: "```json"}-Eintrag am Ende von messages, um „Antwort beginnt mit JSON" zu erzwingen — liefert 400.

# Before: JSON-Ausgabe per Prefill erzwingen
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "Gib die User-Daten als JSON zurueck."},
        {"role": "assistant", "content": "```json\n{"},  # Prefill
    ],
)

# After: Structured Outputs verwenden
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "Gib die User-Daten als JSON zurueck."},
    ],
)

Drei Ersatz-Wege fuer Prefill:

1. Structured Outputs (output_config.format) — Ausgabeform ueber JSON-Schema festlegen
2. System-Prompt mit „Gib nur JSON aus, keine Markdown-Formatierung, keine Einleitung."
3. Tool Use — als Funktionsaufruf empfangen (Argumente sind strukturiertes JSON)

9. Effort-Level richtig waehlen (xhigh ist neu)

Fuer output_config.effort gibt es nun fuenf Stufen. Neu ist xhigh.

Wer bisher budget_tokens manuell setzte, waehlt jetzt einfach ein effort-Level. Faustregeln:

• Coding-Agenten (a la Claude Code): mit xhigh starten
• Q&A-Chats oder RAG-Antworten: high ist eine gute Wahl
• Tagging, JSON-Extraktion, Klassifikation: medium oder low
• max: nur, wenn es eine Einzelfrage wirklich wert ist, um jeden Preis tief durchzudenken

10. Umgang mit Verhaltensaenderungen

Auch ohne API-Aenderung reagiert das Modell anders als 4.6. Wer das nicht kennt, hoert in Produktion schnell „das ist jetzt knapper/kuehler geworden".

10.1 Antwortlaenge passt sich an

4.7 skaliert die Antwortlaenge nach Komplexitaet. „Bitte drei Absaetze" als festes Korsett gibt es nicht mehr. Empfehlenswert: alte Laengen-Prompts einmal entfernen und die Baseline neu messen.

10.2 Anweisungen werden woertlicher genommen

Besonders bei niedrigem effort. „Kurz fassen" heisst wirklich kurz; „drei Punkte" heisst drei, nicht vier. Bequem — aber das „zwischen-den-Zeilen-ergaenzen" von 4.6 gibt es seltener.

10.3 Direkterer Ton

Floskeln wie „tolle Frage!", schmueckende Emojis, einleitende Begrueber werden weniger. Wer freundlich bleiben will, formuliert die Tonlage explizit im System-Prompt.

10.4 Fortschrittsmeldungen sind ins Agenten-Tracking eingebaut

Wer in eigenen Scaffoldings Zwischenrufe wie „ich tue jetzt X", „ich mache X" erzeugen liess: 4.7 liefert das eingebaut. Die doppelte Scaffolding kann raus.

10.5 Weniger Sub-Agenten und Tool-Aufrufe

Per Default spawnt 4.7 seltener Sub-Agenten und ruft weniger Tools. Wenn „mit Reasoning loesbar" erkannt wird, antwortet das Modell ohne Tools. Erwartungen in Agent-Designs entsprechend anpassen.

10.6 Echtzeit-Cybersecurity-Schutz

Auch legitime Offensive-Security-Arbeit (Red Team, Vulnerability PoCs) kann je nach Kontext abgelehnt werden. Wer das produktiv macht, bewirbt sich beim Cyber Verification Program von Anthropic.

10.7 Hochaufloesende Bilder

Bilder bis 2576px werden direkt verarbeitet. Ein Vollbild kostet allerdings etwa das Dreifache an Tokens. Bei bildlastigen Workloads: (a) max_tokens neu verteilen, (b) vor dem Versand herunterskalieren.

11. Empfohlene Aenderungen (nicht zwingend)

Nicht noetig zum Laufenlassen, aber ratsam:

1. max_tokens neu bewerten: mit dem neuen Tokenizer waechst auch der Output — bisherige Werte um den Faktor 1,2–1,35 anheben und neu testen
2. Eigene Token-Schaetzer pruefen: selbst implementierte Abrechnung/Laengenpruefung auf count_tokens-API umstellen oder Faktor anpassen
3. task_budgets (beta) einfuehren: fuer Agenten; Header task-budgets-2026-03-13 setzen, Minimum 20k. Beachten: kein Hard Cap, sondern Advisory
4. max_tokens auf 64k+: bei Nutzung von xhigh/max empfehlen sich insgesamt 64k+ fuer Denken + Output
5. Bilder herunterskalieren: wenn keine hohe Aufloesung noetig ist — spart Tokens und Kosten

11.1 task_budgets — Minimalbeispiel (Python-SDK)

task_budgets ist Beta; dafuer bitte den client.beta.messages.create-Endpoint nutzen und betas explizit angeben. Aufruf unterscheidet sich vom GA-Pfad.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

Eckpunkte der Spezifikation:

• Minimum ist 20.000 Tokens. Niedriger wird nicht akzeptiert
• max_tokens ist der Hard Cap pro Request (nicht dem Modell offengelegt), task_budget ist Advisory fuer die gesamte Agenten-Schleife (das Modell sieht den Countdown)
• Wer strikt Kosten deckeln will: max_tokens. Wer Qualitaet und Effizienz balanciert: task_budget
• Bei offenen, qualitaetsgetriebenen Aufgaben ist es besser, kein task_budget zu setzen (es neigt sonst zu frueher „Rundung nach oben")

12. Migration ab Opus 4.5/4.1 oder frueher

Wer 4.6 ueberspringt und direkt von 4.5 oder 4.1 auf 4.7 geht, muss zusaetzlich:

• Sampling-Parameter entfernen: Claude-3.x-Nutzer haben temperature ganz selbstverstaendlich gesetzt — restlos loeschen
• Beta-Header aufraeumen: effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14 sind mittlerweile im Kern — entfernen
• Endpoint wechseln: von client.beta.messages.create auf client.messages.create
• output_format → output_config.format: der Schluessel heisst jetzt anders
• Tool-Argument-Parsing: ab 4.6 unterscheidet sich das JSON-Escape-Verhalten teilweise. Statt Roh-String-Parsing bitte offizielle Parser wie JSON.parse oder json.loads verwenden

Zu den neuen Funktionen von Claude Opus 4.7 lohnt sich der Einstiegsartikel: Claude Opus 4.7 Release: neue Funktionen, Benchmarks und Preise.

13. Migrations-Checkliste (alle Punkte)

Zum Ausdrucken und Abhaken — alle Punkte am Stueck:

13.1 Pflicht (sonst 400-Fehler oder kaputtes Verhalten)

• ☐ Modellnamen von claude-opus-4-6 auf claude-opus-4-7 aendern
• ☐ temperature / top_p / top_k entfernen
• ☐ thinking: {type: "enabled", budget_tokens: N} durch {type: "adaptive"} + output_config.effort ersetzen
• ☐ Assistant-Prefill entfernen und durch Structured Outputs / System-Prompt ersetzen
• ☐ Wenn Thinking im UI angezeigt wird: thinking.display: "summarized" explizit setzen

13.2 Tuning (Kosten und Qualitaet optimieren)

• ☐ Kosten und Latenz mit dem neuen Tokenizer neu benchmarken
• ☐ max_tokens um den Faktor 1,35 anheben
• ☐ Token-Schaetzer auf Client-Seite neu testen
• ☐ Bei Bildversand Tokens fuer hohe Aufloesungen einplanen
• ☐ Fuer xhigh/max max_tokens ≥ 64k setzen
• ☐ Bei Agenten: task_budgets (Beta) in Erwaegung ziehen

13.3 Prompt und Betrieb ueberdenken

• ☐ Laengen-Anpassung, woertliche Auslegung und Tonalitaet mit echten Prompts pruefen
• ☐ Bestehende Laengen-Steuerprompts entfernen und Baseline neu aufnehmen
• ☐ Bei Ablehnungen in Sicherheitsthemen: Cyber Verification Program beantragen
• ☐ Agenten-Scaffoldings (manuelle Fortschrittsmeldungen) verschlanken
• ☐ Wer von 4.5 oder frueher kommt: Beta-Header entfernen und auf client.messages.create wechseln

14. Automatisiertes Migrations-Tool

Wer Claude Code nutzt, kann mit der von Anthropic bereitgestellten Claude-API-Skill den mechanischen Teil der Umstellung automatisieren. Einfach in Claude Code aufrufen:

/claude-api migrate

Bitte migriere das Projekt von Claude Opus 4.6 auf 4.7:
- Modellnamen aendern
- temperature / top_p / top_k entfernen
- thinking: enabled durch adaptive + effort: high ersetzen
- Verbliebene Prefills auf Structured Outputs umstellen

Die Skill durchsucht das Repo, findet Dateien mit anthropic-Imports und schlaegt die Aenderungen vor. Prompt-Feinschliff und Benchmark-Wiederholung sind nicht automatisierbar — bitte mit der Checkliste nachziehen.

FAQ

Dieser Artikel basiert auf dem Anthropic-Migrationsleitfaden fuer Claude Opus 4.7 (Stand April 2026). API-Spezifikationen koennen sich aendern — vor Produktivbetrieb bitte die offizielle Dokumentation pruefen.