Migrating From OpenAI to Claude Without a Rewrite

Switching your primary model from OpenAI to Claude sounds like a rewrite: different SDK, different request shape, different streaming format, scattered across every service that calls a model. It does not have to be. There are two honest paths to Claude, and the one most teams should take keeps your existing OpenAI-shaped code exactly as it is.

This post lays out both paths, why Anthropic’s first-party compatibility shim is a testing tool rather than a production answer, and how to run the migration as a reversible, incremental change instead of a big-bang cutover. The compatibility details below are from Anthropic’s OpenAI SDK compatibility documentation, as of October 2026.

Two paths to Claude

Path one is to port your code to Claude’s native Messages API — the full-featured, Anthropic-recommended way to build on Claude. It is the right destination eventually, and it is also real work across a codebase.

Path two is to keep speaking the OpenAI Chat Completions format and let something translate it to Claude. This is where the nuance lives, because who does the translating matters a lot.

If you use Anthropic’s own OpenAI-compatibility endpoint, you point the OpenAI SDK at https://api.anthropic.com/v1/, swap in a Claude API key and a Claude model name, and it works. But Anthropic is explicit that this layer is “primarily intended to test and compare model capabilities, and is not considered a long-term or production-ready solution for most use cases.” A gateway that speaks OpenAI-in and native-Claude-out does the same translation without that ceiling — which is the difference the next section is about.

Want to point your OpenAI code at Claude and keep caching and thinking?

Book a demo

Why the first-party compatibility layer isn’t the answer

The compatibility shim is genuinely useful for one thing — evaluating Claude against your existing prompts with zero code change — and genuinely limited for production.

The limits are specific. Prompt caching is not supported through the compatibility layer, so you lose Claude’s biggest cost lever. Thinking is not returned — you can enable it via extra_body, but the SDK won’t surface the thinking blocks. Many OpenAI fields are silently ignored (response_format, seed, logprobs, presence_penalty, frequency_penalty, and more), so behavior you relied on can quietly change. And the newest models tighten parameters: on Claude Opus 5.5 and Sonnet 5.5, forced tool_choice returns an error (use "auto"), and on 4.7-plus models temperature below 1 or a non-default top_p returns a 400. System and developer messages are hoisted and concatenated, losing their mid-conversation position.

None of that is a knock on Anthropic — the layer does exactly what its docs say. It just means “point the OpenAI SDK at Anthropic” is a way to try Claude, not a way to run it. A gateway closes the gap: your services keep sending OpenAI Chat Completions requests, and the gateway maps them onto Claude’s native Messages API, so prompt caching, thinking, structured outputs, and the rest are available rather than stripped.

The migration, step by step

Because the gateway sits in the request path and speaks your existing format, the migration is a sequence of small, reversible changes rather than a rewrite.

1. Put the gateway in the path. Change your OpenAI client’s base URL to the gateway’s OpenAI-compatible endpoint and route one non-critical service through it. Your code is otherwise untouched.
2. Point a logical model name at Claude. Instead of hard-coding claude-opus-5-5, use a logical name (say production-chat) backed by a Claude tier, so later changes are config, not code.
3. Keep OpenAI as a fallback. During the migration, configure the logical name to fall back to your current OpenAI model on error — so the switch cannot cause an outage.
4. Compare before you commit. Run your real prompts against Claude and OpenAI side by side and check quality, latency, and cost.

5. Shift traffic and turn on Claude’s features. Move the logical name to Claude, enable prompt caching on the static prefix, and add thinking where it helps — features the first-party compat layer couldn’t give you.

Models are added to one catalog and addressed by a logical name; swapping providers is a config change. Source: TrueFoundry docs.

Steps 1 to 3 change nothing a user can see. Step 4 is where you earn confidence. Step 5 is the actual switch — and because it is a config change behind a logical name, rolling back or splitting traffic between providers is also a config change.

Where teams get this wrong

They ship the compatibility shim to production. It’s a testing tool. You lose caching and thinking and inherit silent field drops. Translate through a gateway to the native API instead.

They cut over all at once. A big-bang provider switch with no fallback turns any behavior difference into an incident. Migrate one service at a time behind a logical name with OpenAI as fallback.

They assume prompts transfer unchanged. Models differ; a prompt tuned for one may need adjustment for Claude. Compare on real traffic before committing, and keep evals on after.

They hard-code claude-opus-5-5 everywhere. That just recreates the original problem with a new string. Use a logical name so the next change — a tier swap, a split, a rollback — is config.

‍