Claude Codeのサブエージェントも「1時間キャッシュ」に　書き込みは2倍の単価

米Anthropicのコーディングエージェント「Claude Code」で、サブエージェントやワークフローが使うプロンプトのキャッシュを、設定1行で1時間保てる。Claude Codeのプロンプトキャッシュの説明によると、subagentPromptCacheTtlを "1h" にすればよく、v2.1.242以降で使える。サブスクでもサブエージェントの既定は5分で、5分を超える間が空くと同じ内容を読み直すことになる。ただし1時間のキャッシュは書き込みの単価が高く、どの使い方でも得になるとは限らない。

サブエージェントは既定で5分

Claude Codeは、毎回の依頼で会話の履歴をまるごとAPIに送り直す。前回と同じ先頭部分はキャッシュから読み、変わった部分だけを処理する仕組みだ。キャッシュは使われないまま一定の時間がたつと消え、その次の依頼は全体を処理し直すため、遅く高くつく。この保持時間を「TTL」と呼ぶ。

ドキュメントは、依頼を2つの組に分けてTTLを決めると書く。1つは、利用者とやり取りする本体の会話だ。もう1つはそれ以外で、サブエージェント、ワークフロー、会話の圧縮、セッションの題付けなどが入る。

Claudeのサブスクの枠内で使う場合、本体の会話は既定で1時間になる。ところがサブエージェントなどは、Anthropicが決める一部の補助の依頼を除き、5分のままだ。サブエージェントは本体と別の会話として動き、本体のキャッシュを使わずに自分のキャッシュを温める。APIキーやクラウド経由で使う場合は、どちらの組も既定で5分だ。サブスクの上限を超えて追加の利用分に入ると、本体の会話も5分に下がる。

設定ファイルに1行で済む

Claude Codeの設定の一覧によると、サブエージェント側はsubagentPromptCacheTtl、本体の会話はpromptCacheTtlで決める。値は "5m" か "1h" の2つだけで、ほかの値は無視される。settings.jsonに "subagentPromptCacheTtl": "1h" と書けば、サブエージェントやワークフロー、圧縮などの依頼が1時間のキャッシュを使う。

環境変数CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTLでも同じ指定ができ、設定ファイルより優先される。FORCE_PROMPT_CACHING_5M=1は全てを5分に戻し、ほかのどの指定よりも強い。v2.1.248以降は、サブエージェントの定義ファイルのexperimentalの欄にあるcacheTtlでも決められる。ただしサブスクで追加の利用分を使っている間は、ここでの1時間の指定は無視される。APIキーで使う人が本体の会話も1時間にしたい時は、promptCacheTtlも "1h" にする。ENABLE_PROMPT_CACHING_1H=1は両方の組に1時間を求めるが、優先順位は個別の設定より低い。

中継のサーバー（LLMゲートウェイ）を通す場合は注意がいる。1時間の指定の一部はリクエストのヘッダーで届くため、ゲートウェイがそのヘッダーをそのまま渡す設定にしておく必要がある。Amazon Bedrockでは、1時間のキャッシュを使えるかがモデルによって変わる。

効いているかは、/usageの「Prompt cache (main)」の行で、本体の会話のキャッシュの当たり具合を確かめられる。v2.1.251以降の機能だ。中断したサブエージェントを再開すると、最初の依頼は前回の実行で温めたキャッシュを読める。1時間にしておけば、この再開までの間に余裕ができる。

書き込みは基本単価の2倍

Claude APIのプロンプトキャッシュの料金では、5分のキャッシュへの書き込みは入力の基本単価の1.25倍、1時間は2倍だ。キャッシュからの読み出しは基本単価の10分の1で、「Opus 5.5」と「Sonnet 5.5」は20分の1、「Fable 5.1」と「Mythos 5.1」は40分の1になる。読み出すたびに保持の時間は延びる。なおClaude Codeのキャッシュは、事実上1台のマシンと1つのディレクトリの中でしか共有されない。別のディレクトリで開いたセッションは、互いのキャッシュを読めない。

Claude Codeのドキュメントも、この差をはっきり書く。1時間のキャッシュは、席を外して戻った時の読み直しを省ける。だが5分以内に次の依頼が続く短い作業では、高い書き込み単価だけを払い、長い保持は使われない。APIのドキュメントは、5分より間隔が空き1時間より短い使い方に1時間を勧め、その例に5分以上かかる脇のエージェントを挙げる。

つまり、長いビルドやテストを待つサブエージェント、時間をおいて再開するサブエージェントでは得になりやすい。一方、数分で終わるサブエージェントを大量に回す使い方では、書き込みの割増しが残る。

節約の幅はまだ分からない

Xでは、サブエージェントが既定で5分だと指摘し、設定を1時間に変えるよう勧める利用者の投稿や同じ設定を紹介する投稿が出た。どちらもXのみで、どれだけ減ったかの数字は示していない。1時間の書き込みがサブスクの使用量の上限にどう数えられるかも、未確認だ。

Claude Codeのサブエージェントは、設定1行で1時間のキャッシュを使える。効くのは間が空く使い方に限られ、そうでなければ割高になる。

編集部の見方

編集部は、この設定を「入れれば安くなる」ものではなく、自分の使い方を測ってから選ぶものと見る。1時間の書き込みは5分の1.6倍の単価で、得をするのは5分を超える待ちが多いサブエージェントに限られる。まず /usageや依頼ごとのトークン数で、キャッシュの書き込みと読み出しの比を見るとよい。書き込みが毎回多いなら、TTLより先に、途中でキャッシュを壊す操作を疑う方が早い。節約の幅を測った公開の数字は、まだ無い。