1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Opus 5系のthinkingとeffort移行ガイド、4.8から5.5で変わる設定

1
Posted at

はじめに

対象読者は、Anthropic API（Messages API）や Claude Code で Opus 系モデルを使っていて、Opus 4.8 から Opus 5、あるいは Opus 5.5 へ切り替える開発者です。

モデル ID を1行書き換えるだけのつもりでも、thinking と effort の組み合わせは世代ごとに意味が変わっています。Opus 4.8 では「何も書かなければ thinking なし」だったリクエストが、Opus 5 では thinking ありで動き、Opus 5.5 では thinking を切る手段そのものがなくなりました。既定の effort も Opus 5 の high から Opus 5.5 では medium に下がっています。

厄介なのは、こうした違いが SDK の型では検出できない点です。この記事では、公式ドキュメント（2026年10月15日時点）の対応表を3世代分並べ、移行時にどの設定を書き換えるべきかを整理します。あわせて、型チェックを通ってしまうことの確認と、対応表をコードにした事前チェックの実行結果も載せます。

Opus 5 から Opus 5.5 への移行全体（forced tool use の廃止やコンピュータ操作ツールの変更など、thinking 以外の破壊的変更を含む）は、別記事の「Claude Opus 5.5 リリース、Opus 5 からの移行で400エラーになる4つの破壊的変更と対処コード」で扱っています。本記事は thinking と effort の設定に絞ります。

参照した一次情報

TL;DR

  • thinking の既定: Opus 4.8 は thinking を書かなければ thinking なし、Opus 5 と Opus 5.5 は書かなくても adaptive thinking で動く
  • thinking の無効化: Opus 4.8 はいつでも可、Opus 5 は effort が high 以下のときだけ可（xhigh / max では 400）、Opus 5.5 はどの effort でも 400
  • 既定 effort: Opus 4.8 と Opus 5 は high、Opus 5.5 は medium。effort を省略しているコードは Opus 5.5 で思考が浅くなる
  • budget_tokens: Opus 4.8 以降の Opus ではすべて 400。深さは output_config.effort で決める
  • 型では防げない: @anthropic-ai/sdk 0.134.0 の型は claude-opus-5-5 と thinking: {type: "disabled"} の組み合わせを許すため、事前チェックは自前で持つ必要がある
  • Claude Code: ユーザー設定のトップレベル effortLevel は Opus 5.5 には効かない

3世代の対応表

公式の Thinking ページと Effort ページから、Opus 4.8・Opus 5・Opus 5.5 の行だけを抜き出すと次のとおりです。

設定 Opus 4.8 Opus 5 Opus 5.5
thinking を書かない thinking なし adaptive adaptive
{"type": "adaptive"} adaptive adaptive adaptive
{"type": "enabled", "budget_tokens": N} 400 400 400
{"type": "disabled"} thinking なし high 以下なら thinking なし 400
既定 effort high high medium
対応 effort 5段階 5段階 5段階
display の既定 omitted omitted omitted

5段階は low / medium / high / xhigh / max です。max と xhigh は Opus 4.8 の時点ですでに使えたため、Opus 5 の新機能ではありません。

この表から読み取れる世代間の変化は2つの軸に分けられます。1つは「thinking を書かないときの意味」で、Opus 4.8 から Opus 5 で反転しました。もう1つは「thinking を切れる範囲」で、世代ごとに狭まり、Opus 5.5 でゼロになっています。

Opus 4.8 から Opus 5: 書かなかった thinking が動き出す

Opus 4.8 では、thinking: {"type": "adaptive"} を明示しない限り thinking はオフでした。Opus 5 では同じリクエストが adaptive thinking で動きます。effort が思考の深さを決め、モデルがターンごとに考えるかどうかを判断します。

コード上は何も変えていないのに出力トークンが増えるのはこのためです。Thinking ページによると、思考に使ったトークンは返却されない場合（既定の display: "omitted"）でも出力トークンとして課金され、max_tokens にも数えられます。thinking なしを前提に決めていた max_tokens では、思考の分だけ本文の枠が減り、stop_reason が "max_tokens" で切れることがあります。Effort ページは、Opus 5 を xhigh / max で動かす場合は max_tokens を 64k から調整し始めるよう勧めています。

thinking を切りたい場合、Opus 5 では thinking: {"type": "disabled"} を指定できます。ただし effort が high 以下のときに限られ、xhigh / max と組み合わせると 400 になります。Opus 4.8 で「高い effort かつ thinking オフ」を組んでいた構成は、effort を high 以下に下げるか、thinking を外して有効にするかのどちらかを選ぶことになります。

Opus 5 から Opus 5.5: thinking は切れず、既定 effort は下がる

Opus 5.5 では adaptive thinking が常に有効です。thinking: {"type": "disabled"} も budget_tokens 付きの enabled も、effort に関係なく 400 invalid_request_error になります。ドキュメントに載っているエラーメッセージは次のとおりです。

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

thinking を書かない形と {"type": "adaptive"} は同じ扱いで、ベータヘッダーも要りません。コスト削減のために thinking を切っていた箇所は、thinking を削除して effort を low などに下げる形に置き換えます。

# Opus 5 では effort が high 以下なら受理、Opus 5.5 では 400
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

# Opus 5.5 向け: thinking を外し、深さは effort で決める
client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "..."}],
)

もう1つの変化は既定 effort です。Opus 5 では effort を省略すると high でしたが、Opus 5.5 では medium になりました。effort を書いていないコードは、モデル ID を変えただけで思考が1段浅くなります。品質を Opus 5 の high と比べたいなら、effort を明示したうえで比較し直す必要があります。一方で What's new ページは、同じ effort でも Opus 5.5 は Opus 5 よりターンあたりの思考が増える傾向があり、xhigh と max で特に顕著だと説明しています。既定が下がった分と1段あたりの思考が増えた分が相殺されるかどうかは、ワークロードごとに測るしかありません。

同系統の他モデルとの違い

Opus 5.5 と同じ時期のモデルでも、thinking を切る方法は揃っていません。Thinking ページの対応表では次のようになっています。

モデル thinking を最も弱くする指定 使える effort
Opus 5.5 なし（常に adaptive） ―
Sonnet 5.5 {"type": "between_tools"} high 以下
Haiku 5.5 {"type": "disabled"} high 以下

Sonnet 5.5 の between_tools は「最初の思考を省く」指定で、ツール呼び出しの合間の進捗は残ります。display などの他のフィールドと一緒に送ると 400 になります。複数のモデルを同じコードで切り替えている場合、thinking の値をモデルごとに出し分ける必要があります。

型チェックでは見つからない

SDK の型がモデルごとの制約を表現していれば、移行時にコンパイルエラーで気づけます。実際にどうなるかを、@anthropic-ai/sdk の最新版（0.134.0・2026-10-14 公開）で確認しました。

$ npm view @anthropic-ai/sdk version
0.134.0

型定義を見ると、thinking は4種類のユニオン型で、モデル ID とは独立に定義されています。

$ grep -n -E "export type ThinkingConfigParam|effort\?: " node_modules/@anthropic-ai/sdk/resources/messages/messages.d.ts
3591:    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
3993:export type ThinkingConfigParam = ThinkingConfigEnabled | ThinkingConfigDisabled | ThinkingConfigBetweenTools | ThinkingConfigAdaptive;

Opus 5.5 では必ず 400 になる組み合わせを TypeScript 5.9.3 の --strict で型チェックした結果が次です。

import Anthropic from "@anthropic-ai/sdk";
const params: Anthropic.MessageCreateParamsNonStreaming = {
  model: "claude-opus-5-5",
  max_tokens: 16000,
  thinking: { type: "disabled" },
  output_config: { effort: "max" },
  messages: [{ role: "user", content: "hi" }],
};

$ npx tsc --noEmit --strict --module nodenext --moduleResolution nodenext --skipLibCheck t.ts; echo "tsc exit=$?"
tsc exit=0

型チェックは通ります。制約はサーバー側で判定されるため、気づくのは実際にリクエストを送って 400 が返ったときです。なお display: "updates" は通常の messages の型には含まれず、ベータ側（resources/beta/messages/messages.d.ts）の型にだけ 'summarized' | 'omitted' | 'updates' として載っていました。

対応表を事前チェックにする

型で防げない以上、移行前にリクエストの組み立て部分を検査する仕組みを自前で持つのが確実です。先ほどの3世代の対応表をそのまま関数にしたものが次です（API は呼びません）。

const HIGH_OR_BELOW = new Set(["low", "medium", "high"]);
const MODELS = {
  "claude-opus-4-8": { defaultEffort: "high", noField: "off", disabled: "any" },
  "claude-opus-5":   { defaultEffort: "high", noField: "adaptive", disabled: "high-or-below" },
  "claude-opus-5-5": { defaultEffort: "medium", noField: "adaptive", disabled: "never" },
};

export function preflight(req) {
  const m = MODELS[req.model];
  if (!m) return [`未知のモデル: ${req.model}`];
  const effort = req.output_config?.effort ?? m.defaultEffort;
  const type = req.thinking?.type ?? null;
  const issues = [];
  if (type === "enabled") issues.push("400: budget_tokens 指定は 4.8 以降の Opus で不可（adaptive + effort へ）");
  if (type === "disabled") {
    if (m.disabled === "never") issues.push("400: このモデルは thinking を無効化できない");
    if (m.disabled === "high-or-below" && !HIGH_OR_BELOW.has(effort))
      issues.push(`400: effort=${effort} では disabled 不可（high 以下に下げるか thinking を外す）`);
  }
  if (!req.output_config?.effort) issues.push(`注意: effort 省略 → ${m.defaultEffort} で動く`);
  const thinkingOn = type === "adaptive" || (type === null && m.noField === "adaptive");
  if (thinkingOn && req.max_tokens < 64000 && ["xhigh", "max"].includes(effort))
    issues.push(`注意: effort=${effort} で max_tokens=${req.max_tokens}（公式は 64k からの調整を推奨）`);
  return issues;
}

同じ6パターンのリクエストを流すと、Node.js 22.22.0 で次の出力になりました。

$ node preflight.mjs
claude-opus-4-8 thinking=disabled effort=xhigh -> OK
claude-opus-5 thinking=disabled effort=xhigh -> 400: effort=xhigh では disabled 不可（high 以下に下げるか thinking を外す）
claude-opus-5 thinking=disabled effort=high -> OK
claude-opus-5-5 thinking=disabled effort=low -> 400: このモデルは thinking を無効化できない
claude-opus-5-5 thinking=(なし) effort=(省略) -> 注意: effort 省略 → medium で動く
claude-opus-5-5 thinking=(なし) effort=max -> OK

1行目と2行目は同じリクエストで、モデル ID だけが違います。Opus 4.8 で通っていた構成が Opus 5 で 400 になることが、表の読み違いなしに確認できます。この判定は公式の対応表を写したものなので、実際の API の挙動を保証するものではありません。新しいモデルが出たら MODELS に行を足し、Thinking ページの表と突き合わせてください。

Claude Code での effort 設定

Claude Code 側でも、Opus 5.5 は既定 effort が medium です。Model configuration ページによると、opus エイリアスは Anthropic API では Opus 5.5 に解決され、Opus 5.5 を使うには Claude Code v2.1.280 以降が必要です。

見落としやすいのは、ユーザー設定ファイルのトップレベルにある effortLevel が Opus 5.5 には効かない点です。この項目は、Claude Code がモデルごとに effort を保存するようになる前の形式で、Opus 5 や Fable 5.1 以前のモデルには引き続き適用されます。Opus 5.5 以降のモデルは、/effort か /model の選択画面で effort を選ぶまで自分の既定値（medium）で動きます。ユーザー設定で "effortLevel": "high" にしているから大丈夫、と考えていると、Opus 5.5 だけ1段浅いまま使うことになります。

なお、プロジェクト設定・ローカル設定・管理設定にトップレベルの effortLevel を書いた場合や --settings で渡した場合は、全モデルに適用されると同ページは説明しています。セッション単位で変えるなら起動時の --effort が使え、手元の CLI（v2.1.300）のヘルプでも値は5段階でした。

$ claude --version
2.1.300 (Claude Code)
$ claude --help | grep -A1 -- '--effort'
  --effort <level>                      Effort level for the current session
                                        (low, medium, high, xhigh, max)

設定ファイルの effortLevel と modelSettings には max を書けない、という制約もあります。max を使いたいときは、セッションごとに指定します。

会話の途中で effort を変える

エージェントのループでは、計画は高い effort、定型作業は低い effort で回したいことがあります。Opus 5 と Opus 5.5 は、会話の途中で effort を切り替える機能（ベータ）に対応しています。messages 配列に effort だけを持つ system メッセージを差し込む形で、ベータヘッダー mid-conversation-output-config-2026-07-01 が必要です。

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "high"},
    messages=[
        {"role": "user", "content": "移行手順を3段階で計画してください。"},
        {"role": "assistant", "content": "1. ... 2. ... 3. ..."},
        # ここから先の応答は low で動く
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "計画を1文に要約してください。"},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

Effort ページによると、手前の部分が変わらないためプロンプトキャッシュはそのまま効きます。ヘッダーなしで送ると messages.N.output_config: Extra inputs are not permitted の 400 になります。上のコード例はドキュメントの例をモデル ID と文面だけ置き換えたもので、実際の API 呼び出しによる確認はしていません。

まとめ

冒頭の「モデル ID を1行書き換えるだけ」の移行で問題になるのは、主に次の3点です。

  • thinking: {"type": "disabled"} を使っているか（Opus 5 では effort 次第、Opus 5.5 では常に 400）
  • effort を省略していないか（Opus 5.5 では medium に下がる）
  • max_tokens が thinking なし前提の値のままになっていないか

どれも SDK の型では検出できないため、リクエストを組み立てる箇所を grep で洗い出すか、上の preflight のような対応表ベースのチェックを CI に置いておくと、400 を本番で踏む前に気づけます。Claude Code を使っている場合は、Opus 5.5 に切り替えたあと /effort で effort を選び直すところまでを移行作業に含めてください。

Opus 5 は現在 legacy 扱いで、What's new ページには「2027年7月24日より前には提供終了しない」とあります。急いで移行する必要はありませんが、Opus 5.5 は価格も下がっているため、上の3点を確認したうえで切り替えを検討する価値があります。

参考リンク

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?