Claude Codeは、前回までと同じ先頭部分をプロンプトキャッシュに残して、次のメッセージで読み直す費用と時間を抑えています。キャッシュが残る時間は「5分」と「1時間」の2種類で、Claudeのサブスクリプションをプランの使用量の範囲内で使う会話は1時間、サブエージェントやAPI課金の会話は5分が既定です。この時間はsettings.jsonのpromptCacheTtlとsubagentPromptCacheTtlで変えられます。
Claude CodeチームのLydia Hallieさんが日本時間2026年10月10日4時17分、「サブスクリプションは1時間、サブエージェントとAPI課金は5分。settings.jsonのpromptCacheTtl（サブエージェントはsubagentPromptCacheTtl）で変えられる」と返信しました。同じ日の12時55分には、開発者のBoris Chernyさんがこの使い分けの理由を説明しています。本記事はこの2つの投稿と公式資料を10月12日に確認して書いています。編集部でも、promptCacheTtlを5mにした時としない時で同じ依頼を1回ずつ実行し、キャッシュの書き込みが5分と1時間のどちらに入ったかを、Claude Codeの実行記録で確かめました。
元資料：Lydia Hallieさんの返信（キャッシュの保持時間とpromptCacheTtl）。2026年10月12日確認。
キャッシュの保持時間とは
Claude Codeは、メッセージを送るたびに、システムプロンプトやそれまでの会話をまとめてモデルに送ります。毎回すべてを読み直すと時間も費用もかかるため、前回と同じ部分をキャッシュに残して読み直しを省きます。公式資料によると、キャッシュは使われないまま一定の時間がたつと消え、使うたびに残り時間が戻ります。この「使われないまま残せる時間」が保持時間です。
画像を拡大 ↗Claude Code公式ドキュメントの図：毎回送り直す会話のうち、変わらない先頭部分をキャッシュから読む
灰色がキャッシュから読んだ部分、オレンジが新しく処理して書き込んだ部分です。2回目以降は前回までの内容をまとめて読み、4回目のようにシステムプロンプトが変わると、後ろの変わっていない部分も処理し直しになります。図には描かれていませんが、保持時間が過ぎてキャッシュが消えた時も、次のメッセージで全体を処理し直します。
出典：Anthropic / Claude ↗- 5分：書き込みの料金が安い。5分以上手を止めると消えるので、休憩の後の最初のメッセージは全体を読み直す
- 1時間：書き込みの料金が高い代わりに、1時間までの休憩なら残る。短い時間に続けて作業するだけなら、高い書き込み料金の分だけ損になる
API料金で見ると、Claude Platformの公式資料では、5分のキャッシュへの書き込みは通常の入力の1.25倍、1時間は2倍、キャッシュからの読み込みは通常0.1倍の料金です。読み込みは、Opus 5.5とSonnet 5.5では0.05倍など、モデルによってさらに安くなります。
この倍率から編集部で計算すると、同じ先頭部分を何回使えば元が取れるかの目安は次のとおりです。5分のキャッシュは2回目の利用から、1時間のキャッシュは3回目の利用から、キャッシュを使わない場合より安くなります。1時間が得になるのは、5分以上あけて何度も戻ってくる使い方の時です。
どの会話が5分で、どの会話が1時間か
公式資料では、Claude Codeが送るリクエストを「メインの会話」と「それ以外」の2つに分けて、保持時間を決めています。メインの会話は、ふだんの対話、claude -pでの実行、Agent SDKでの会話です。それ以外は、サブエージェント、ワークフロー、会話の要約（コンパクト）、セッション名の作成などです。
| リクエスト | サブスクリプションで、プランの使用量の範囲内 | 使用量クレジット・APIキー・クラウド経由 |
|---|---|---|
| メインの会話 | 1時間 | 5分 |
| それ以外（サブエージェントなど） | 5分（Anthropicが決める一部の補助リクエストだけ1時間） | 5分 |
プランの上限を超えて、使用量クレジット（上限を超えた分を支払って使い続ける仕組み）で支払う状態になると、メインの会話も5分に下がります。書き込みの安い5分にして、請求額を抑えるためです。
Borisさんは、この使い分けの理由を次のように説明しています。
- APIは、Agent SDKで動かすような処理に使われることが多い。そこで1時間にすると平均では費用が高くなるので、安全のために5分にしている
- 対話で使う場合は、平均すると1時間の方が安くなるので1時間にしている
- 多くの人にはこれで合うが、完全ではない。だから設定で変えられるようにしている
保持時間を変える設定
設定できる値は5mと1hの2つだけで、それ以外の値は無視されます。どちらもClaude Code v2.1.242以降で使えます。
| 変えたいもの | settings.jsonの項目 | 環境変数 |
|---|---|---|
| メインの会話 | promptCacheTtl | CLAUDE_CODE_PROMPT_CACHE_TTL |
| サブエージェントなど、それ以外 | subagentPromptCacheTtl | CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL |
たとえば、APIキーで使っていて、会議の合間などに手を止めることが多いなら、メインの会話を1時間にします。
{
"promptCacheTtl": "1h"
}サブスクリプションで使っていて、長く調べ物をさせるサブエージェントの途中で手が止まることが多いなら、サブエージェント側も1時間にできます。
{
"subagentPromptCacheTtl": "1h"
}複数の指定がある時は、次の順で先に当てはまったものが使われます。
FORCE_PROMPT_CACHING_5M=1（両方とも5分に固定。挙動を調べる時や、管理者の設定の1時間を上書きしたい時に使う）- それぞれの環境変数
- それぞれのsettings.jsonの項目
- サブエージェントの定義ファイルの先頭にある
experimental欄に書いたcacheTtl（v2.1.248以降。サブスクリプションで使用量クレジットを使っている間は1hが無視される） ENABLE_PROMPT_CACHING_1H=1（両方とも1時間）- 上の表の既定値
社内の中継サーバー（LLMゲートウェイ）をANTHROPIC_BASE_URLで指定している場合は、1時間の指定の一部がリクエストのヘッダーで送られるため、中継サーバーがそのヘッダーをそのまま通す必要があります。企業が自社で運用し、Amazon Bedrockなどにつなぐ公式のゲートウェイ（Claude apps gateway）経由では、1時間は使えません。Amazon Bedrockでは、モデルによって1時間が使えない場合があります。
編集部で試した：5分にしたら書き込み先が変わるか
2026年10月12日、設定が本当に効いているかを確かめるため、架空の会議メモnotes.mdを要約させる同じ依頼を、2つのフォルダーで1回ずつ実行しました。モデルはHaiku 5.5、認証はClaudeのサブスクリプションです。1つ目のフォルダーには.claude/settings.jsonに"promptCacheTtl": "5m"を書き、2つ目には何も置いていません。ふだんの設定の影響を受けないよう、--setting-sources projectを付けて、ユーザー設定などほかの設定ファイルを読まないようにしました。環境変数と管理者の設定はこのオプションでは外れませんが、今回の環境にはキャッシュに関する環境変数も管理者の設定もありません。
画面は、Claude Code CLIをclaude -pで実際に動かし、その出力をそのまま映した編集部の確認用の画面です。Claude Codeのターミナル画面そのものではありません。確認欄の2行目は、1つ目の実行が終わった後に同じ画面から2つ目のフォルダーで実行した結果です。
実行記録のusage.cache_creationに書かれた数字は次のとおりです。公式資料も、どちらの保持時間で書き込まれたかはこの項目で確かめるよう案内しています。
| 実行 | 5分のキャッシュへの書き込み | 1時間のキャッシュへの書き込み |
|---|---|---|
promptCacheTtlを5mにしたフォルダー | 10,571トークン | 0トークン |
| 設定を置かないフォルダー | 0トークン | 10,577トークン |
- サブスクリプションの既定どおり、設定なしではメインの会話が1時間のキャッシュに書き込まれました。
5mを書いたフォルダーでは、ほぼ同じ大きさの書き込みがすべて5分の側に入りました。設定が実行に反映されていることが分かります。- 要約の結果は2回とも、公開日・確認すること・担当・次回の日付を3行にまとめたもので、言い回しは違っても内容は同じでした。
- 今回は1回ずつの実行で、料金や使用量の差は測っていません。
編集部で試した入力と結果
Claude Codeを実際に動かした手順（CLI）
- 起動した画面：検証コンソールを開き、claude --versionが2.1.296を返すことと、promptCacheTtlを5mにしたsettings.jsonとnotes.mdを確認した
- 実際の依頼を入力：要約の依頼文を入力欄に入れた。モデルはHaiku 5.5、使える道具はReadだけ
- 実行中の様子：Claude Code 2.1.296がHaiku 5.5で起動し、Readでnotes.mdを読んだ時点の画面
- 完了後の結果を確認：要約が返り、確認欄にpromptCacheTtl=5mの実行は5分のキャッシュに、設定なしの実行は1時間のキャッシュに書き込まれたことが表示された
成果物の確認：確認コマンドが、録画した実行のstream-jsonと、設定なしの比較実行のstream-jsonから usage.cache_creation を読み、5分と1時間の書き込み量を表示。
今回、実際に入力した内容
notes.md を読んで、内容を3行で要約してください。
実際に得られた結果
- 新しい問い合わせフォームは10月20日に公開する予定です。
- 公開前に、スマホ表示とメール通知を確認します（画面は山田さん、通知は佐藤さんが担当）。
- 次回の10月19日に最終確認を行います。
どちらにするか：編集部の目安
ここからは編集部の提案です。迷ったら既定のままにして、気になる場面だけ変えます。
- サブスクリプションで対話しながら使う人：既定の1時間のままでよいでしょう。Borisさんの説明どおり、対話では1時間の方が平均して安くなるよう決められています。
- APIキーやクラウド経由で、手を止めながら使う人：会議や休憩で5分以上あくことが多いなら、
promptCacheTtlを1hにすると、戻った後の読み直しを減らせます。続けて短く作業するだけなら5分のままの方が書き込みは安く済みます。 - Agent SDKや
claude -pで自動処理を回す人：APIキーやクラウド経由なら、既定の5分のままが合います。Borisさんが5分を既定にしている理由もここです。サブスクリプションではclaude -pもメインの会話なので既定は1時間です。数分で終わる処理だけなら、promptCacheTtlを5mにする選択肢があります。編集部の実験でも、5mにすると5分の側に書き込まれることを確かめました。 - 長いサブエージェントを使う人：サブエージェントはサブスクリプションでも5分です。途中で長く待つ作業が多い時だけ
subagentPromptCacheTtlを1hにして、使用量の変化を見ます。 - 効いているか確かめたい人：
claude -p "hello" --output-format jsonの結果のusage.cache_creationを見ます。v2.1.251以降は/usageに「Prompt cache (main)」の行が出て、キャッシュの当たり具合と、今キャッシュが残っているかを確認できます。
モデルの切り替えや、MCPサーバーの追加・削除など、キャッシュを作り直す操作もあります。長い会話を安く続けるコツは、自動コンパクトの記事とコンテキスト管理の記事にまとめています。
よくある質問
サブスクリプションで1時間にしても、使用量は増えませんか？
サブスクリプションのメインの会話は、プランの使用量の範囲内なら、はじめから1時間が既定です。promptCacheTtlを1hにしても、この範囲では既定と同じなので変わりません。変わるのは使用量クレジットに切り替わった後です。既定では5分に下がりますが、1hを書いておくと1時間のまま続き、書き込みは5分の時より高い料金で請求されます。
サブエージェントだけ1時間にすると、親の会話のキャッシュに影響しますか？
公式資料によると、サブエージェントは親とは別の会話として始まり、自分用のキャッシュを作ります。親の会話のキャッシュはそのまま残ります。
5分と1時間以外の値は書けますか？
書けません。5mと1h以外の値は無視されます。
Sonnet 5.5のキャッシュ読み込みが値下げされたと聞きました
@ClaudeDevsが日本時間10月9日5時04分、Claude PlatformでのSonnet 5.5のキャッシュ読み込みを半額の100万トークンあたり0.10ドルにしたと投稿しています。API料金だけが対象で、Claude Codeの使用量の上限は変わらないとしています。
まとめ：既定のまま使い、手が止まる使い方の時だけ変える
Claude Codeのプロンプトキャッシュは、サブスクリプションの会話ではプランの使用量の範囲内なら1時間、サブエージェントとAPI課金では5分残るのが既定です。promptCacheTtlとsubagentPromptCacheTtlで変えられ、編集部の実験でも、5mを書くと書き込み先が5分の側に変わることを実行記録で確かめました。APIで手を止めながら使う時は1時間、数分で終わる自動処理は5分（サブスクリプションではpromptCacheTtlで指定）、と使い方と課金の方法に合わせて選び、変えた後はusage.cache_creationか/usageで確かめてください。
