Claude Code autocompactの使い方とコンテキスト圧縮の調整
/autocompactでコンテキストウィンドウの何トークン使った時点で自動圧縮するかを調整できます。設定方法・優先順位・モデル別の既定値をまとめます。
Claude Code autocompactとは
autocompact windowは、会話がどこまでコンテキストウィンドウを埋めたらClaude Codeが自動で圧縮するかを決める値です。/autocompact コマンドはこの値をセッション内から直接調整します。既定では各モデルに合わせてチューニングされた値が使われますが、長いセッションを続けたい場合や逆に早めに圧縮しておきたい場合に、500k のようなサイズや auto を指定して上書きできます。
/autocompact コマンドの利用にはClaude Code v2.1.221以降が必要です。引数なしで実行すると現在のウィンドウを表示するダイアログが開き、値を渡すとその場で設定が変わります。圧縮そのものが何を残し何を捨てるかはClaude Code compactの発火条件と要約後に残る情報で扱っています。本記事はそのタイミングを調整する /autocompact に絞ります。
/autocompact 500k指定できる値の書式
コマンドとあとで説明するフラグは、次のいずれの書式でも値を受け付けます。
- 生のトークン数:
200000 kまたはMサフィックス:500k/1M- 100〜1000の裸の数値(千単位として解釈):
200は200,000と同じ
指定できる範囲は100Kから1Mトークンまでで、Claude Codeは実際のモデルのコンテキストウィンドウを超える値を自動的に切り詰めます。auto を渡すとモデルに合わせてチューニングされた既定のウィンドウに戻ります。
今の設定を確認する
引数なしで /autocompact を実行すると、現在のウィンドウを示すダイアログが開くだけで値は変更されません。
/autocompactセッション中の残り余地を見たいときは /context を使います。コンテキストウィンドウがautocompact windowに近づくと、/context の出力先頭に警告が表示され、モデルの上限そのものを超えている場合は別の警告に切り替わります。
設定できる3つの場所と優先順位
autocompact windowは用途に応じて3つの場所で設定できます。優先順位を誤ると「設定したのに反映されない」現象に当たるので、まず順序を押さえます。
| 設定場所 | 効く範囲 | 優先順位の扱い |
|---|---|---|
CLAUDE_CODE_AUTO_COMPACT_WINDOW(環境変数) | 効く範囲スクリプト・クラウド環境 | 優先順位の扱い設定されている間はコマンド・フラグ・設定より常に優先。/autocompact は上書き中であることを報告する |
--autocompact(起動フラグ) | 効く範囲その1回の起動のみ | 優先順位の扱い保存済み設定を変えずにその起動だけ上書き。managed settingsのような上位スコープにも先勝ちする(/autocompact コマンドと違う点) |
/autocompact(セッション内コマンド) | 効く範囲今のセッションと以降のセッション | 優先順位の扱いautoCompactWindow としてユーザー設定に保存。managed settingsなど上位スコープが同じキーを設定していると、値自体は保存されるがセッションは上位スコープのウィンドウを使い続け、コマンドがその旨を表示する |
環境変数はプレーンなトークン数のみを受け付け、k / M サフィックスは使えません。フラグはコマンドと同じ書式(サフィックス・千単位省略)に対応し、claude --autocompact auto は保存済み設定に値があってもチューニング済みウィンドウでセッションを起動します。
/autocompact が書き込む autoCompactWindow はユーザー設定のキーです。Claude Codeの設定はmanaged settings・コマンドライン引数・プロジェクト個人設定・プロジェクト共有設定・ユーザー設定の順で優先度が決まり、ユーザー設定はこの中で最も低い階層に位置します。この順序はCLI・VS Code拡張・JetBrains IDEのどれで実行しても変わりません。プロジェクトの共有設定やmanaged settingsが同じキーを定義していれば、/autocompact で保存した値より必ずそちらが優先されるのはこのためです。
見落としやすい落とし穴
- 環境変数に
k/Mサフィックスを付けると誤動作する:CLAUDE_CODE_AUTO_COMPACT_WINDOW=500kは整数として解釈されず「500」というトークン数と読まれ、最低値の100Kに切り上げられます。500Kを指定したいならCLAUDE_CODE_AUTO_COMPACT_WINDOW=500000と書きます - 環境変数を設定するとステータスラインの目安が崩れる:
used_percentageは常にモデルのフルコンテキストウィンドウに対する割合を表示するため、CLAUDE_CODE_AUTO_COMPACT_WINDOWを設定した後は、この数値がいつ圧縮が起きるかの目安にならなくなります CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENTはv2.1.223以降が必要: 未認識モデルIDでの圧縮回避を古いバージョンで試しても効きません
何も設定しないときの既定値
/autocompact を一度も使わない場合、Claude Codeは基本的にモデルのコンテキスト上限に達したところで圧縮しますが、次のケースは例外です。
- クラウドセッションは上限に近づいた時点で圧縮する(境界ぴったりを待たない)
- 拡張コンテキストなしのSonnet 4.6・Opus 4.6、およびBedrock・Google CloudのAgent Platform・Microsoft Foundry上で200Kウィンドウで動くOpus 4.8・Opus 5は、200K境界で圧縮する
CLAUDE_CODE_DISABLE_1M_CONTEXT=1を設定すると、Sonnet 5やFable 5のようにネイティブで1Mウィンドウを持つモデルも200K境界で圧縮する- Sonnet 5は自身の構成(後述)に応じた閾値で圧縮する
- Claude Codeが認識しないモデルID(LLM gatewayのエイリアスなど)は、そのIDに対して想定しているウィンドウで圧縮する
Sonnet 5は既定で約97万トークンまで
Anthropic APIでは、Sonnet 5は常に1Mトークンのコンテキストウィンドウで動きます。既定ではウィンドウが埋まりきる前、約967,000トークンの時点で自動圧縮が入ります。この閾値を変えたいときは CLAUDE_CODE_AUTO_COMPACT_WINDOW で別の値を指定します。
これが200Kに絞られる構成が2つあります。ひとつはLLM gateway経由(ANTHROPIC_BASE_URL がgatewayを指している)で、Claude Codeが1M対応を確認できないケースです。フルのウィンドウを使うには /model のピッカーで「Sonnet 5(1M context)」を選び、sonnet[1m] に切り替えます。もうひとつは前述の CLAUDE_CODE_DISABLE_1M_CONTEXT=1 で、ネイティブ1Mウィンドウを持つすべてのモデルを200Kに固定する構成です。
LLM gatewayやカスタムモデルIDでウィンドウがずれるとき
LLM gatewayなどのカスタムデプロイでは、Claude Codeがモデルの実際のウィンドウとは違うサイズを想定してしまうことがあります。この想定を上書きするのが CLAUDE_CODE_MAX_CONTEXT_TOKENS で、モデルIDの形によって効き方が3通りに分かれます。
- IDが
claude-で始まらず[1m]も含まず、Claude Codeがどのモデルか解決できない場合: 変数がそのまま適用され、宣言したウィンドウで先回りの圧縮が続く - IDが
claude-で始まらないが[1m]を含む場合: Claude Codeは1Mウィンドウを想定してしまい、変数単独では効かない。CLAUDE_CODE_DISABLE_1M_CONTEXT=1も併用すると想定ウィンドウを補正でき、200K超のウィンドウを宣言している場合は起動時に「200Kの上限は強制されていません」という想定内の警告が出る - IDが
claude-で始まる、またはClaudeモデルに解決される場合: 変数はDISABLE_COMPACT(全圧縮の無効化)も同時に設定したときだけ効く。anthropic/claude-opus-4-8のようにモデル名を含むIDはこの解決に該当する
Claude Codeが認識しないモデルIDに対しては、CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 を設定すると、APIが「長すぎる」と実際に拒否するまで圧縮を待たせる挙動に変えられます。ただしgatewayがエラーを書き換えて転送する構成では、この回復処理は働きません。
圧縮を無効化したときの注意
autocompactを無効にする(DISABLE_COMPACT を設定するなど)構成では、モデルのコンテキスト上限に達すると圧縮する代わりに Prompt is too long エラーで停止します。/context はこの状態になると出力の先頭に警告を表示し、対話セッションでは Context limit reached という行で同じ状況を知らせます。ウィンドウを広げても解決しないタイプのエラーで、対処は不要なコンテキストを /clear や /compact で減らすか、DISABLE_COMPACT を外して自動圧縮を戻すかのどちらかです。
autocompact windowを下限の100Kまで下げても圧縮回数が増えるだけで、モデル自体のコンテキスト上限を実質的に縮めるわけではありません。逆に1M超のモデルで上限より大きい値を指定しても、Claude Codeがモデルのコンテキストウィンドウに合わせて自動的に切り詰めます。自動圧縮そのものが失敗して止まるケースは Prompt is too long とは別の症状で、Error during compactionの意味と対処で個別に扱っています。
トークンコストとの関係
Claude Codeがトークンコストを自動で抑える仕組みは2つあります。ひとつはシステムプロンプトのような繰り返し内容を安く再利用するプロンプトキャッシュ、もうひとつがコンテキスト上限に近づいたときに古い履歴を要約するautocompactです。会話がautocompact windowに近づくと表示される警告は、プランの利用上限に達したことを意味しません。無関係なタスクの合間に /clear で会話をリセットする、タスクの難度に応じてモデルを使い分けるといった運用のほうが、autocompact windowの調整そのものよりトークンコストへの影響は大きくなりがちです。
まとめ
/autocompact はコンテキストウィンドウの何トークン使った時点で圧縮するかを直接コントロールする手段です。単発の起動だけ変えたいなら --autocompact フラグ、スクリプトやクラウド環境で固定したいなら CLAUDE_CODE_AUTO_COMPACT_WINDOW 環境変数、日常的な既定値を変えたいなら /autocompact コマンドという使い分けになります。環境変数が常に最優先で、フラグはmanaged settingsのような上位スコープにも勝ちますが、コマンドはmanaged settingsに設定があると上書きできません。Sonnet 5のように既定で1Mウィンドウを持つモデルは、そのままだと約97万トークンで自動圧縮される点も押さえておくと、長いセッションでの挙動を予測しやすくなります。
つまずきやすいのは環境変数の書式です。k / M サフィックスが使えるのはコマンドとフラグだけで、環境変数はプレーンな整数しか受け付けません。CLAUDE_CODE_AUTO_COMPACT_WINDOW にサフィックス付きの値を書いてしまうと、意図しない小さい値に丸められたまま気づきにくいので、スクリプトやCI設定に組み込むときは一度 /autocompact の表示で反映結果を確認しておくと安全です。