How to switch Claude Code to Opus 5.5 and keep it selected

You run /model, choose Opus, and Claude Code still uses another model—or it returns a 400 before the first response. The reliable fix is to separate three things: the model command, the Claude Code version, and any request-level fallback triggered by a refusal.

Use the full model ID when you need a reproducible setup, use the opus alias only after checking what it resolves to, and remember that Opus 5.5 defaults to medium effort rather than the high default used by Opus 5.

Use the full model ID to pin Opus 5.5

The most explicit command is:

/model claude-opus-5-5

Anthropic documents claude-opus-5-5 as a fixed model ID without a date suffix. That makes it the better choice for project instructions, team runbooks, and custom providers where you need everyone to request the same model.

The shorter alternative is:

/model opus

Use the alias only when Claude Code—or the provider behind your custom Base URL—shows that it resolves to Opus 5.5. An alias is convenient for interactive work, but the full ID is easier to audit when a session, script, or gateway behaves differently than expected.

Your goal	Prefer	Why
Pin the exact model	/model claude-opus-5-5	The requested ID is explicit and reproducible
Use the current Opus alias interactively	/model opus	Faster to type, but you should verify the resolved model
Diagnose a custom provider	Full ID first	It separates alias mapping problems from model availability problems

If you run Claude Code through an Anthropic-compatible custom Base URL such as BetterToken, the /model procedure is unchanged; confirm that the provider actually exposes claude-opus-5-5 before treating an alias result as proof.

Update Claude Code before switching

A client that predates the model may reject the selection even when your account or provider supports it. Update first:

claude update

Then restart the active Claude Code session or update the Claude desktop app if that is the client you use. After the restart, run the full-ID command again.

A community issue captured one concrete error on September 22, 2026: Claude Code 2.1.257 was rejected with claude_code_version_too_old, and the response required 2.1.280 or newer. That report is useful as an example of the version gate, not as a permanent universal minimum. Follow the minimum named by the error you actually receive, because later releases can raise it.

Switch the model and verify the result

Follow this order so that one failure does not hide another:

1. Run claude update, then restart Claude Code.
2. Enter /model claude-opus-5-5 in the session where you will work.
3. Check the model selection that Claude Code displays after the command. Do not infer success only because the command was accepted.
4. Reopen /model before a long or expensive task and confirm the current selection again.

If the full ID works but /model opus does not, keep the full ID. That points to alias resolution rather than a general inability to use Opus 5.5.

If neither works and you use a third-party endpoint, verify model availability and mapping on that provider. The Claude API can expose the official ID while a compatible gateway uses a separate catalog or has not enabled it yet.

Expect medium effort unless you set another level

Claude Opus 5.5 uses adaptive thinking and its documented default effort is medium. This differs from Claude Opus 5, whose default was high, so a model switch can change latency, token use, and how much reasoning the model applies even when you do not change any visible Claude Code setting.

For ordinary Claude Code use, there is no need to invent an effort value just to complete the switch. First confirm the model, then evaluate whether the default behavior fits the task. If your client or API gateway exposes an effort control, set it deliberately rather than assuming the old Opus default carried over.

Custom integrations also need to respect the Opus 5.5 request rules. The model rejects requests that disable thinking or send a manual thinking budget. If model selection succeeds but the first request returns a 400, inspect any upstream payload transformation instead of repeatedly changing /model.

A flagged message can take a fallback path

A safety refusal is separate from your normal model selection. At the API level, Opus 5.5 can return HTTP 200 with stop_reason: "refusal" and a stop_details object. A client or provider with fallback enabled may retry that request on another model.

Treat that event as a request-level fallback, not proof that your saved /model choice changed. Before continuing important work, reopen /model and verify the active selection. If the fallback moved the conversation from Opus 5.5 to most other models, Anthropic notes that the later turns run without the previous Opus 5.5 thinking blocks; restate critical constraints instead of assuming all hidden reasoning carried over.

The practical sequence is:

1. Read the refusal or flagged-message notice instead of resending the same request unchanged.
2. Remove or reframe the part that triggered the safeguard when the request is legitimate.
3. Check whether your client or provider used a fallback model.
4. Confirm Opus 5.5 again before resuming a task that depends on a fixed model.

Troubleshoot the common failure modes

Symptom	Most likely check	Next action
400 with claude_code_version_too_old	Claude Code or desktop version	Run claude update, restart, and retry the full ID
Opus 5.5 is missing from the model list	Client catalog or provider catalog is stale	Update the client; then check provider availability
/model opus chooses an unexpected model	Alias resolution	Use /model claude-opus-5-5 and verify the displayed selection
Full ID is accepted, but the first request returns 400	Upstream payload is incompatible	Check for disabled/manual thinking settings or other gateway rewrites
A message is flagged and another model answers	Refusal fallback	Review the refusal, verify the active model, and restate critical constraints
A mid-session switch feels less consistent	Thinking blocks may not transfer to the target model	Confirm the model and give the new turn the context it needs

Final checklist

Before starting the real task, confirm all five points:

• Claude Code has been updated and restarted.
• /model claude-opus-5-5 is accepted.
• The displayed selection resolves to Opus 5.5.
• You expect the default medium effort unless another level is explicitly configured.
• A flagged or refused request has not silently moved that request onto a fallback model without your review.

Once those checks pass, the exact model ID is the safest way to keep a session reproducible. The opus alias remains useful for quick interactive switching, but it should be verified rather than assumed.

Sources

• Anthropic: Opus 5.5 migration guide
• Anthropic: What’s new in Claude Opus 5.5
• GitHub issue #12870: one reported old-client version error