Migrate to Claude Opus 5 or Sonnet 5: Complete Guide (2026)

Anthropic’s current lineup is Claude Opus 5, Sonnet 5, Haiku 4.5, and Fable 5.1 (long-horizon agentic work). If your agents are still pinned to Opus 4.7, 4.8, or an older Sonnet, this guide walks through a safe migration on Paperclip — including which model to pick, and the things that typically go wrong in the first 48 hours. Model IDs and pricing were verified against Anthropic’s model documentation in September 2026.

Migration summary: One-line change in agent config. Prompts stay mostly identical. Rollback is 30 seconds. Expected outcome for agents moving to Sonnet 5: similar or better quality on tool-use/support tasks at roughly a third of Opus pricing ($2 / $10 permanent vs $5 / $25). For agents moving to Opus 5: flagship-tier coding depth with a 1M-token context, at the same per-token price as Opus 4.8.

Before you start — pick your target model

Not every agent should land on the same model. Use your current agent’s job to decide:

Your agent does	Migrate to
Deep, multi-file autonomous coding	Opus 5 ($5 / $25, 1M context)
Browser/tool-driving, computer use	Sonnet 5 ($2 / $10)
General support, research, knowledge work	Sonnet 5 ($2 / $10)
Simple routing/classification	Stay on Haiku 4.5 ($1 / $5)
Long-horizon reasoning where Opus falls short	Trial Fable 5.1

Sonnet 5’s $2 / $10 pricing is now permanent list pricing (no longer the introductory rate it launched with) and Anthropic positions it as the starting point for most workloads. Opus 5 is the flagship for complex agentic coding and enterprise work.

Validation checklist

Do these three things before touching a single agent:

1. Pin your current success-rate baseline. Open your Paperclip monitoring dashboard and note, per agent: success rate over the last 7 days, median tokens per successful run, median latency, error-to-success ratio.

2. Identify one low-risk agent to migrate first. Something that runs frequently enough to produce a signal in 24-48 hours but isn’t mission-critical — internal tooling, support-triage with human review, research agents with reviewed output.

3. Confirm your BYOK Anthropic API key is current. Paperclip → Settings → Providers → Anthropic → regenerate if it’s been more than 6 months.

Step 1 — Update the model ID

Via the HostAgentes dashboard

1. Open the agent → Settings → Model
2. Select Claude Opus 5 or Claude Sonnet 5 from the dropdown
3. Leave temperature, max tokens, and system prompt unchanged initially
4. Save — no redeploy, no cold start.

Via paperclip.yaml

  agent:
    name: "support-handler"
    model:
      provider: anthropic
-     id: claude-opus-4-8
+     id: claude-sonnet-5
      temperature: 0.3
      max_tokens: 8000

Commit, push, Paperclip reloads the agent config on next run.

Via the Anthropic API directly

- model: "claude-opus-4-8"
+ model: "claude-sonnet-5"

Tool definitions, system prompt, and stop sequences stay the same. Anthropic publishes its own migration guide for Opus 4.8 → Opus 5 covering API-level behavior changes.

Step 2 — Re-baseline token counts (Sonnet 5 only)

Sonnet 5 ships an updated tokenizer: the same input can map to 1.0–1.35× more tokens than on Sonnet 4.6 or Opus models, depending on content type. Don’t assume the lower per-token price translates directly to lower total cost — measure tokens-per-task after the swap, not before.

Step 3 — Use the 1M context window (Opus 5)

If you’re migrating a large-scope research or refactor agent to Opus 5, its permanent 1M-token context removes the chunking step many Opus 4.x workflows needed: whole codebases, long run histories, and big document sets fit in a single context window. Where you previously split tasks to stay under 200K, try the whole task first and compare quality and cost:

agent:
  name: "autonomous-refactor"
  model:
    provider: anthropic
    id: claude-opus-5
    temperature: 0.3
    max_tokens: 16000

Step 4 — Monitor for 48 hours

Success rate

Should hold steady or rise. If an agent moved from Opus to Sonnet 5 and success rate drops more than a few points on hard tasks, that agent likely needs the Opus tier — now Opus 5.

Tokens per successful task

For Sonnet 5 migrations, compute this fresh — don’t extrapolate from the old model’s token counts given the tokenizer change.

Total spend

Should fall for agents moved to Sonnet 5, given the ~2.5x price gap even after accounting for more tokens per call. Agents moved to Opus 5 should hold roughly flat (same $5 / $25 flagship pricing as 4.8). If spend rises unexpectedly, check for accidentally elevated max_tokens or effort settings.

Latency and tool call patterns

Watch for regressions, especially on agents that lean heavily on tool-calling — Sonnet 5 was specifically built for this, so patterns should be at least as clean as before.

Things that typically go wrong

1. Assuming Sonnet 5’s price cut maps directly to cost cut

The tokenizer change means it doesn’t always. Measure, don’t assume.

2. Keeping coding-heavy agents on Sonnet 5 when they need the Opus tier

If a coding agent’s success rate drops after moving to Sonnet 5, that’s the signal to move it to Opus 5 — the flagship tier exists for exactly this workload.

3. Prompts over-tuned for older model quirks

Phrases like “think carefully,” “do not skip steps” were often compensating for older model weaknesses. On the current lineup they can cause over-reasoning and inflate output tokens. Remove them one at a time and A/B test.

4. Forgetting BYOK rate limits on new model IDs

Some Anthropic accounts need explicit verification before new model IDs unlock at full rate limits. Check your Anthropic console if you see 403s.

How to Switch Back (Rollback Plan)

If quality dips after a migration — for example a coding agent’s success rate drops on Sonnet 5 — here is how to switch back:

Via dashboard: Open the agent → Settings → Model → select the previous model. Zero downtime.

Via yaml:

  model:
    provider: anthropic
-   id: claude-sonnet-5
+   id: claude-opus-4-8

Commit, redeploy, done. Anthropic keeps prior model versions available, so there’s no urgent forcing function — migrate on your own timeline.

Rolling migration across multiple agents

Once one agent has run cleanly on its new model for 3-5 days, batch-migrate the rest:

1. Dashboard → Fleet view
2. Select agents by tag (e.g., environment=production)
3. Bulk action → Update model
4. Monitor fleet-level metrics for another 48 hours

FAQ

Should I go straight to Opus 5 and Sonnet 5, or stop at Opus 4.8 first? Skip intermediate versions — go directly to whichever of Sonnet 5 or Opus 5 fits the agent’s job, per the table above.

Will migrating break my existing prompts? Unlikely for prompt structure. The main gotcha is Sonnet 5’s token counts changing due to its updated tokenizer — re-measure cost, don’t assume.

Does Opus 5 cost more to run than Opus 4.8? No — flagship pricing is unchanged at $5 / $25 per million tokens. Sonnet 5 ($2 / $10 permanent) is meaningfully cheaper than any Opus tier.

What if my BYOK Anthropic account isn’t approved for the new models yet? Check your Anthropic console — new model IDs sometimes need billing re-verification before they unlock.

How do I switch back to a previous Claude model after migrating? Open the agent in your Paperclip dashboard, go to Settings → Model, and select the previous model from the dropdown — or change the model id back (e.g. claude-opus-4-8) in paperclip.yaml and redeploy. It is a one-line change with zero downtime; Anthropic keeps prior model versions available, so you can switch back at any time.

Can I switch back to Opus after moving an agent to Sonnet 5? Yes. If a coding-heavy agent’s success rate drops after moving to Sonnet 5, switch it to Opus 5 immediately — same dropdown or yaml field, no config rewrite needed. Prompts and tool definitions carry over unchanged in both directions.

How do I change the Claude model ID in my agent config? Set model.id to claude-opus-5 (or claude-sonnet-5): in the HostAgentes dashboard use Settings → Model, in paperclip.yaml edit model.id, or in a direct API call change the model parameter. Temperature, max tokens, and system prompt stay the same.

What does it cost to migrate from Opus 4.x to the current lineup? Nothing on the HostAgentes side — model switching is included in every Paperclip plan. On the Anthropic side, Sonnet 5 is $2 / $10 per million tokens (permanent) versus Opus 4.x’s $5 / $25, so most migrations cut model spend by roughly two-thirds. Opus 5 is $5 / $25, the same flagship price as 4.8.

---

Related: Deploy Claude Opus 5 & Sonnet 5 Agents on Paperclip → · Claude coding benchmarks: what still applies → · Paperclip + Anthropic integration →