ai-docs

Thinking

Properties1
tagsthinking, effort, tools, prompt-caching, context, api

原典: Thinking ／ 日本語版

一行要約

thinking は「thinking ブロックで考えるかどうか」、effort は「応答全体にどれだけ労力を割くか」。混同しやすいが別の軸で、adaptive を effort の値として渡してはいけない。

要点

Thinking has a cost: the tokens Claude spends reasoning are billed as output tokens, even when the thinking text isn’t returned to you, and they count toward max_tokens alongside the response text.

thinking にはコストがある。Claude が推論に費やしたトークンは、その思考テキストが返されない場合でも出力トークンとして課金され、応答テキストと合わせて max_tokens を消費する。

設定（モデルによって既定が違う）

モデル既定
Opus 5.5 / Opus 5 / Sonnet 5.5 / Sonnet 5 / Fable 5.1 / Mythos 5.1 / Fable 5 / Mythos 5 / Mythos Previewthinking はすでにオン。設定不要
Opus 4.8 / 4.7 / 4.6 / Sonnet 4.6thinking: {type: "adaptive"} を設定するまでオフ

thinking の値ごとにモデルが何をするかは、原典の表にまとまった。要点:

thinking の値受け付けないモデル（400）
"disabled"Opus 5.5 / Sonnet 5.5 / Fable 5.1 / Mythos 5.1 / Fable 5 / Mythos 5 / Mythos Preview。Opus 5 は effort high 以下なら受け付ける
"enabled"（budget_tokens）Opus 4.7 以降の Opus、Sonnet 5 以降、Fable / Mythos 5 系（Mythos Preview と Opus 4.6 / Sonnet 4.6 以前は受け付ける）
"between_tools"Sonnet 5.5 以外すべて。Sonnet 5.5 でも effort xhigh / max では 400

Sonnet 5.5 で事前の thinking を切るには、disabled ではなく thinking: {type: "between_tools"}。 Sonnet 5.5 の最も低い thinking 設定で、effort high 以下でだけ受け付ける。ツール呼び出しの合間の進捗更新は返り続け（display: "updates" のときのように要約テキストつき）、ツールが無ければ応答はテキストだけになる（Sonnet 5 の disabled と同じ）。between_tools は他のフィールドを取らない —— display / budget_tokens / block_binding を一緒に送ると 400。beta ヘッダは要らない。返ってきたブロックはそのまま送り返す（送り返した進捗更新ブロックは、要約ではなくモデルが書いた全文をモデルに渡す）。

display — thinking テキストを返すか

値挙動既定のモデル
"summarized"要約された thinking テキストを返すOpus 4.6 / Sonnet 4.6 以前
"omitted"thinking フィールドが空のブロックを返す。signature は暗号化された完全な thinking を保持するFable 5.1 / Mythos 5.1 / Fable 5 / Mythos 5 / Opus 5.5 / Opus 5 / Sonnet 5.5 / Sonnet 5 / Opus 4.8 / Opus 4.7 / Mythos Preview
"updates"（beta）推論ブロックは空のまま、進捗更新のブロックだけ要約テキストを返す—（beta ヘッダ thinking-display-updates-2026-08-18 が要る）

You’re still charged for the full thinking tokens. Omitting reduces latency, not cost.

それでも thinking トークンの全量が課金される。省略が減らすのはレイテンシであって、コストではない。

omitted の主な利点はストリーミング時の time-to-first-text-token が速くなること — thinking のテキストは流れない。ただし 各 thinking ブロックについて空文字列の thinking_delta が1つ届き、その後に signature_delta が来る（以前の取得では「thinking_delta は1つも来ない」だった）。thinking_delta が来ないことを前提にしたストリーム処理は書かない。

summarized についての重要な注意:

  • 返ってくるのは要約であって、生の chain of thought ではない。 どの display 設定でも生の思考は返らない
  • 課金は元のリクエストが生成した完全な thinking トークンに対して行われる（要約のトークン数ではない）。課金される出力トークン数はレスポンスで見えるトークン数と一致しない
  • 要約は、リクエストで指定したモデルとは別のモデルが処理する。thinking したモデルは要約を見ない

推論を見たいなら、応答本文に書かせず thinking ブロックを読む。 Fable 5.1 / Opus 5.5 / Opus 5 / Sonnet 5.5 / Fable 5 では、内部の推論を応答本文として引き出そうとするリクエストは stop_details.category: "reasoning_extraction" で拒否されることがある（以前の取得で Opus 5 が加わった）。

thinking と effort の使い分け

目的使うもの
thinking 有効のワークロードでコスト / レイテンシを下げたいまず effort を下げる（応答全体が縮む）
thinking の頻度が低い / 浅いeffort を上げる
thinking を完全に切りたいthinking: {type: "disabled"}。Opus 5.5 / Sonnet 5.5 / Fable 5.1 / Mythos 5.1 / Fable 5 / Mythos 5 / Mythos Preview は拒否する（切れない。Sonnet 5.5 は between_tools で事前の thinking だけ切れる）。Opus 5 は effort high 以下なら受け付け、xhigh / max では 400
支出に厳密な上限が要るmax_tokens。effort はソフトな指針で、max_tokens は厳密な上限

ツール使用時の2つの制約

1. tool choice の制約（manual モードのみ）

tool use with manual extended thinking (thinking: {type: "enabled"}) only supports tool_choice: {"type": "auto"} (the default) or tool_choice: {"type": "none"}. […] Adaptive thinking, including on models where thinking is on by default, supports forced tool use, except on Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1

手動の extended thinking（thinking: {type: "enabled"}）でのツール使用は、tool_choice: {"type": "auto"}（既定）か tool_choice: {"type": "none"} しかサポートしない。[…] adaptive thinking は、thinking が既定で有効なモデルも含め、ツール使用の強制をサポートする。ただし Claude Opus 5.5・Claude Sonnet 5.5・Claude Fable 5.1・Claude Mythos 5.1 は除く。

この4モデルは強制ツール使用（tool_choice の any / tool）をどのリクエストでも 400 で拒否する（Opus 5.5（以前の取得）、Sonnet 5.5（その後の取得）の順に加わった）。これらのモデルでは tool_choice: {"type": "auto"} に strict tool use か structured outputs を組み合わせる。

2. thinking ブロックの保持（必須）

Pass every thinking block back to the API complete and unmodified, alongside the tool_use block it accompanied.

すべての thinking ブロックを、それが伴っていた tool_use ブロックとともに、完全かつ未改変のまま API へ返せ。

ツール使用ループは1つの assistant ターン。複数のツール呼び出しと結果を含んでも、モデルから見れば1ターン。

扱い
必須ツール使用ターン内では thinking ブロックを返す
推奨ターンをまたいでも全部返す
許容ツール使用の外では過去ターンの thinking を省いてよい

You don’t need to prune old thinking yourself. Pass all thinking blocks back, and the API automatically filters them, keeps the blocks needed, and bills input tokens only for the blocks actually shown to Claude.

古い thinking を自分で刈り取る必要はない。すべての thinking ブロックを返せば、API が自動的に選別して必要なブロックを保持し、実際に Claude へ見せたブロックのぶんだけ入力トークンを課金する。

改変された thinking ブロックは 400 エラーで拒否される。 例外は omitted ブロックの空の thinking フィールドに置いたテキスト（無視される）。

interleaved thinking

ツール呼び出しの間で考える。adaptive thinking では対応する全モデルで自動（beta header 不要）。Haiku 4.5 は非対応。

Consecutive tool calls do not require interleaved thinking. Interleaving changes where thinking blocks appear between tool calls, not whether tool calls can chain.

連続したツール呼び出しに interleaved thinking は必要ない。interleaving が変えるのは、ツール呼び出しの間のどこに thinking ブロックが現れるかであって、ツール呼び出しを連鎖できるかどうかではない。

ツール呼び出しの合間の進捗更新

Fable 5.1 / Mythos 5.1 / Opus 5.5 / Sonnet 5.5 / Fable 5 では、ツール呼び出しの合間にモデルが進捗を書ける。

A progress update is a note on what the model just found and what it’s about to do next, written for the person watching the agent rather than as reasoning.

進捗更新とは、モデルがいま何を見つけ次に何をしようとしているかを書いた短い記録で、推論としてではなく、エージェントを見ている人に向けて書かれる。

推論ブロックとは別物。それぞれ独自の signature を持つ thinking ブロックとして返り、紹介する tool_use の直前に置かれる。ツール呼び出し1回につき最大1つで、モデルは省略できる。

Progress updates aren’t interleaved thinking: they appear whether or not reasoning blocks appear between tool calls, and a response can contain both.

進捗更新は interleaved thinking ではない。ツール呼び出しの間に推論ブロックが出るかどうかに関わらず現れ、1つの応答に両方が入りうる。

display: "updates" の使いどころが具体的に書かれている。

Use display: "updates" for an agent interface that keeps reasoning hidden and shows the user a status line at each step. Under it, any thinking block with non-empty text is a progress update, so render those and nothing else.

推論は隠したまま各段階でユーザーに状態行を見せるエージェント UI には display: "updates" を使う。この設定では、テキストが空でない thinking ブロックはすべて進捗更新なので、それだけを描画すればよい。

"summarized" では進捗更新と推論ブロックを区別できない。

モデル別の thinking ブロック保持

挙動モデル
過去ターンを全部保持Opus 4.5 以降の Opus、Sonnet 4.6 以降の Sonnet、Fable 5.1、Mythos 5.1、Fable 5、Mythos 5、Mythos Preview
直近ターンのみ保持それ以前の Opus / Sonnet、Haiku 4.5 までの全 Haiku。古いブロックを返しても API が自動的に剥がす

保持の利点: ツール使用中のキャッシュヒットを可能にする（assistant ターンをまたいで増分的にキャッシュされる）、知能への悪影響はない。

トレードオフ: keep-all モデルでは長い会話が context を食う。

モデルを切り替えるときの助言は 途中で逆転した。 以前は「前の assistant ターンから thinking と redacted_thinking を取り除け」だったが、いまは逆にそのまま渡し続けよである。

Switching models mid-conversation. Keep passing thinking blocks back unchanged when you switch models, for example after a classifier refusal fallback. A thinking block is readable only by the model that produced it and certain other models, and the API ignores or drops the blocks the target model can’t read.

会話の途中でモデルを切り替える場合。 切り替えるときも thinking ブロックはそのまま渡し続けよ（たとえば分類器による拒否の fallback のあと）。thinking ブロックはそれを作ったモデルと、特定の他のモデルだけが読める。対象のモデルが読めないブロックは API が無視するか捨てる。

以前の取得では「作ったモデルか、より新しいモデル」だった。Fable 5.1 は Opus 5.5 のブロックを読めるが、Opus 5.5 は Fable 5.1 のブロックを読めない。 Claude Code に来たのは Opus 5.5 のほうが後（Fable 5.1 は W36 = v2.1.251–261、Opus 5.5 は v2.1.280。whats-new / model-config）なので、「新しいほど読める」とは言えなくなった。原典は「決まった範囲」としか言わず、順序の規則を示していない。

On Claude Fable 5.1 and Claude Mythos 5.1 the direction matters: they read every earlier model’s thinking blocks and no earlier model reads theirs, so switching up to them keeps the conversation’s reasoning and switching down drops it.

Claude Fable 5.1 と Claude Mythos 5.1 では向きが効く。これらは以前のどのモデルの thinking ブロックも読めるが、以前のモデルはこれらのものを読めない。したがって上げる切り替えでは会話の推論が保たれ、下げる切り替えでは失われる。

Sonnet 5.5 は、読めるブロックの範囲がさらに狭い。 Sonnet 5 / Opus 4.8 / Haiku 4.5 とそれ以前のモデルのブロックは読めるが、Opus 5 / Opus 5.5 / Fable 系 / Mythos 系のブロックは読めない。そしてSonnet 5.5 のブロックを読める他のモデルは、Claude API と Google Cloud 上の Opus 5.5 だけなので、そこで Sonnet 5.5 から Opus 5.5 に上げる切り替えは前のターンの推論を保ち、それ以外の切り替えでは失われる（以前の取得で変わった。以前は「読める他のモデルは無い」）。

On the Claude API and Google Cloud, Claude Opus 5.5 reads Claude Sonnet 5.5’s blocks and no other model does: a switch from Claude Sonnet 5.5 up to Claude Opus 5.5 on the Claude API and Google Cloud keeps the earlier turns’ reasoning, and any other switch away from Claude Sonnet 5.5 drops it.

Claude API と Google Cloud では、Claude Opus 5.5 が Claude Sonnet 5.5 のブロックを読み、他のモデルは読まない。Claude API と Google Cloud で Claude Sonnet 5.5 から Claude Opus 5.5 へ上げる切り替えは前のターンの推論を保ち、Sonnet 5.5 からのそれ以外の切り替えは推論を落とす。

Sonnet 5.5 の thinking ブロックは、それを生んだアカウントにも結びついている（どこで強制されるかは preserved-thinking のページ）。

自分で剥がしてよいのは、捨てずに無視するだけのモデルで入力トークンを節約したいときだけ。fallback credit を使うときは本文をそのまま送る必要があるので絶対に剥がさない。

Preserved thinking —— signature の2つの検査

Fable 5.1 以降、API はリクエスト中のすべての thinking / redacted_thinking ブロックの signature を2点で検査する。

① 作ったモデル。 各モデルが読めるのは自分のブロックと、決まった範囲の他のモデルのもの。たとえば Fable 5.1 は Opus 5 と（Claude API 上では）Opus 5.5 のブロックを読めるが、Opus 5 も Opus 5.5 も Fable 5.1 のブロックは読めない。読めないブロックは エラーも課金も無しに捨てられる。

② その前に送られたすべて。

A block stays valid only while the top-level system prompt, the tools, and the messages before it are unchanged. If any of them changes, that block and every later thinking block are invalid, and the API rejects the request with a 400 error or drops the invalid blocks, whichever you choose.

ブロックが有効なのは、top-level の system プロンプト、tools、そしてそれより前のメッセージが変わらない間だけである。どれかが変われば、そのブロックと以降のすべての thinking ブロックが無効になり、API は 400 で拒否するか無効なブロックを捨てる（どちらかを選べる）。

強制の開始がアカウントの作成日で決まる。

The API enforces the prefix check by default for accounts created on or after a set date. On older accounts it enforces the check only on requests that set thinking.block_binding.prefix_mismatch_behavior. Make your integration append-only regardless of your account’s age, so the same code works on every account, including newer accounts enforced by default.

API は 一定の日以降に作られたアカウントに対して prefix の検査を既定で強制する。それ以前のアカウントでは thinking.block_binding.prefix_mismatch_behavior を設定したリクエストにだけ適用する。アカウントの古さに関わらず append-only にしておけ。そうすれば、既定で強制される新しいアカウントを含め、どのアカウントでも同じコードが動く。

以前の取得にあった「後のモデルはすべてのアカウントに強制する」という予告は、その後の取得では消えている。append-only にせよという結論は変わらない。

守り方は一つ —— assistant ターンは受け取ったままそっくり返し、新しいメッセージは messages の末尾にだけ足す。 prefix を書き換えたくなる操作には、それぞれ代わりの API 機能がある（新しい指示は mid-conversation system メッセージ、ツールの増減は tool_addition / tool_removal、effort の変更は per-message output_config、切り詰めはサーバ側の compaction と context editing）。

prompt caching との相互作用

Configuration changes invalidate caching. The thinking configuration and the resolved effort level are rendered into the prompt itself. Switching between adaptive, enabled, and disabled, changing budget_tokens, and changing the effort value all invalidate cache breakpoints.

設定の変更はキャッシュを無効にする。thinking の設定と、解決後の effort レベルはプロンプトそのものにレンダリングされる。adaptive / enabled / disabled の切り替え、budget_tokens の変更、effort 値の変更は、いずれもキャッシュの breakpoint を無効にする。

設定を明示的に既定値にすることは、省略することと等価。

thinking ブロックはツール結果と一緒にキャッシュされる。 これは cache_control を付けなくても自動的に起きる。トレードオフ: レスポンスで二度と見ない thinking ブロックも、キャッシュから読まれるときに入力トークンとして計上される。

Thinking-heavy tasks often take longer than the default 5-minute cache lifetime. Consider the 1-hour cache duration.

thinking の重いタスクは、既定の5分というキャッシュ寿命を超えることが多い。1時間のキャッシュ期間を検討せよ。

context window との関係

扱い
現ターンの thinking常に max_tokens に算入、出力トークンとして課金、そのターンの context を占める
過去ターンの thinking保持されるモデルでは context に残り、入力トークンとして課金。剥がされるモデルでは window も入力トークンも消費しない

実務的には:

  • keep-all モデルでは、thinking を通常の会話履歴と同じものとして context 予算を組む。 長い agentic セッションでは thinking が context に蓄積する
  • last-turn-only モデルでは、thinking はターンごとのコストだけ

そのまま使える具体例

thinking を有効にして可視化する（Opus 4.8 など、既定オフのモデル）:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "What is the greatest common divisor of 1071 and 462?"}],
)
 
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

既定オンのモデル（Opus 5 / Sonnet 5 / Fable 5）で thinking を見たいとき（display の既定が omitted なので）:

thinking={"type": "adaptive", "display": "summarized"}

display: "omitted" のときのレスポンス:

{
  "content": [
    {"type": "thinking", "thinking": "", "signature": "EosnCkYICxIMMb3LzNrMu..."},
    {"type": "text", "text": "The answer is 12,231."}
  ]
}

ツール使用ループが1ターンであることの図:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

last-turn-only モデルでは、tool result でない user メッセージが来た時点で過去の thinking が全部剥がされる:

実際に送るもの:

User: ["What's the weather in Paris?"]
Assistant: [thinking_block_1] + [tool_use block 1]
User: [tool_result_1, cache=True]
Assistant: [thinking_block_2] + [text block 2]
User: [Text response, cache=True]

処理されるもの:

User: ["What's the weather in Paris?"]
Assistant: [tool_use block 1]
User: [tool_result_1, cache=True]
Assistant: [text block 2]
User: [Text response, cache=True]

原典で言及されている関連文書

バックリンク