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 enthält er mehrere Breaking Changes in der API; ein bloßer Modellnamen-Tausch kann zu 400 Bad Request führen.

Zielgruppe dieses Leitfadens:

• Entwicklerinnen und Entwickler, die claude-opus-4-6 über Anthropic-API/SDK nutzen
• Teams, die Claude über 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 Primärquelle dient der offizielle Migrationsleitfaden von Anthropic — hier sind vor allem die im deutschsprachigen Alltag häufigsten Stolpersteine aufbereitet. Die offiziellen Angaben stehen unter platform.claude.com (Migration Guide).

2. Kurzfassung in drei Zeilen

Das TL;DR für alle, die es eilig haben:

1. Modellnamen von claude-opus-4-6 auf claude-opus-4-7 wechseln (SDK-Version aktualisieren)
2. Drei große 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 dafür bekommt: bessere Coding-Leistung, 1M Kontext (zum Standard-Tarif) und das neue Effort-Level xhigh

Details folgen ab dem nächsten 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 nächste 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 ändern 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 führt diese Form zum 400-Fehler.

Stattdessen steuert das Modell die Denktiefe selbst — „adaptive thinking“. Außerdem ist in 4.7 Denken standardmäßig aus. Ohne thinking-Feld läuft das Modell ohne Denken. Für tiefere Reasoning-Fähigkeit 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 entfällt
• Stattdessen legt output_config.effort fest, „wie gründlich“ 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 für temperature, top_p oder top_k außerhalb der Defaults führen zum 400-Fehler. Anthropic formuliert klar: Verhalten wird über den Prompt gesteuert — nicht über 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 „möglichst stabile Ausgabe“ abzielte, erreicht das nun durch explizite Prompt-Anweisungen wie „bitte auf die gleiche Frage möglichst konsistent antworten“ oder durch strukturierte Ausgaben mit JSON-Schema.

Und wer temperature=1.2 für „mehr Kreativität“ nutzte, schreibt im Prompt Tonalitaetsvorgaben wie „bildhaft und überraschend formulieren“.

6. Breaking Change 3: Denkinhalt standardmäßig verborgen

In 4.6 wurde der Denkinhalt bei aktivem Denken standardmäßig als „summarized“ im Response-Stream mitgeliefert. Viele UIs nutzten das für ein „denke nach…“-Indiz.

In 4.7 hat sich das leise geändert: Thinking-Blöcke 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 fängt gefuehlt spät an. Nutzer sagen dann „Aufgehaengt?“.

Lösung

# 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 Qualität — kostet aber pro Text 1,0–1,35x mehr Tokens als in 4.6.

Folgen:

• Vorgänge am max_tokens-Limit werden mitten in der Antwort abgeschnitten
• Eigene Token-Schaetzer a la tiktoken (für Abrechnung/Laengenprüfung) werden ungenau
• Werte aus /v1/messages/count_tokens weichen zwischen 4.6 und 4.7 ab
• Bei gleichem Prompt steigen Kosten und Latenz leicht

Lösung

# 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 übernommen: 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 für Prefill:

1. Structured Outputs (output_config.format) — Ausgabeform über 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 wählen (xhigh ist neu)

Für output_config.effort gibt es nun fünf Stufen. Neu ist xhigh.

Wer bisher budget_tokens manuell setzte, wählt 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 Verhaltensänderungen

Auch ohne API-Änderung reagiert das Modell anders als 4.6. Wer das nicht kennt, hört in Produktion schnell „das ist jetzt knapper/kuehler geworden“.

10.1 Antwortlänge passt sich an

4.7 skaliert die Antwortlänge nach Komplexität. „Bitte drei Absätze“ als festes Korsett gibt es nicht mehr. Empfehlenswert: alte Längen-Prompts einmal entfernen und die Baseline neu messen.

10.2 Anweisungen werden woertlicher genommen

Besonders bei niedrigem effort. „Kurz fassen“ heißt wirklich kurz; „drei Punkte“ heißt drei, nicht vier. Bequem — aber das „zwischen-den-Zeilen-ergänzen“ von 4.6 gibt es seltener.

10.3 Direkterer Ton

Floskeln wie „tolle Frage!“, schmueckende Emojis, einleitende Begrüber 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 ließ: 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 Änderungen (nicht zwingend)

Nicht nötig zum Laufenlassen, aber ratsam:

1. max_tokens neu bewerten: mit dem neuen Tokenizer wächst auch der Output — bisherige Werte um den Faktor 1,2–1,35 anheben und neu testen
2. Eigene Token-Schaetzer prüfen: selbst implementierte Abrechnung/Laengenprüfung auf count_tokens-API umstellen oder Faktor anpassen
3. task_budgets (beta) einführen: für 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+ für Denken + Output
5. Bilder herunterskalieren: wenn keine hohe Auflösung nötig ist — spart Tokens und Kosten

11.1 task_budgets — Minimalbeispiel (Python-SDK)

task_budgets ist Beta; dafür 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 für die gesamte Agenten-Schleife (das Modell sieht den Countdown)
• Wer strikt Kosten deckeln will: max_tokens. Wer Qualität und Effizienz balanciert: task_budget
• Bei offenen, qualitätsgetriebenen Aufgaben ist es besser, kein task_budget zu setzen (es neigt sonst zu früher „Rundung nach oben“)

12. Migration ab Opus 4.5/4.1 oder früher

Wer 4.6 überspringt und direkt von 4.5 oder 4.1 auf 4.7 geht, muss zusätzlich:

• Sampling-Parameter entfernen: Claude-3.x-Nutzer haben temperature ganz selbstverständlich gesetzt — restlos löschen
• Beta-Header aufräumen: 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 Schlüssel heißt 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 Stück:

13.1 Pflicht (sonst 400-Fehler oder kaputtes Verhalten)

• ☐ Modellnamen von claude-opus-4-6 auf claude-opus-4-7 ändern
• ☐ 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 Qualität 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 für hohe Auflösungen einplanen
• ☐ Für xhigh/max max_tokens ≥ 64k setzen
• ☐ Bei Agenten: task_budgets (Beta) in Erwägung ziehen

13.3 Prompt und Betrieb überdenken

• ☐ Längen-Anpassung, woertliche Auslegung und Tonalität mit echten Prompts prüfen
• ☐ Bestehende Längen-Steuerprompts entfernen und Baseline neu aufnehmen
• ☐ Bei Ablehnungen in Sicherheitsthemen: Cyber Verification Program beantragen
• ☐ Agenten-Scaffoldings (manuelle Fortschrittsmeldungen) verschlanken
• ☐ Wer von 4.5 oder früher 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 schlägt die Änderungen vor. Prompt-Feinschliff und Benchmark-Wiederholung sind nicht automatisierbar — bitte mit der Checkliste nachziehen.

FAQ

Dieser Artikel basiert auf dem Anthropic-Migrationsleitfaden für Claude Opus 4.7 (Stand April 2026). API-Spezifikationen können sich ändern — vor Produktivbetrieb bitte die offizielle Dokumentation prüfen.