Claude Code autocompactの使い方とコンテキスト圧縮の調整

Claude Code autocompactとは

autocompact windowは、会話がどこまでコンテキストウィンドウを埋めたらClaude Codeが自動で圧縮するかを決める値です。/autocompact コマンドはこの値をセッション内から直接調整します。既定ではモデルに合わせてチューニングされた値が使われます。長いセッションを続けたいとき、あるいは早めに圧縮しておきたいときに、500k のようなサイズや auto を指定して上書きします。

Messages APIを直接使う場合のしきい値の決め方は、既定15万トークン・最小5万トークンという別の基準で動きます。

/autocompact を使うにはClaude Code v2.1.221以降が必要です。引数なしで実行すると現在のウィンドウを表示するダイアログが開き、値を渡すとその場で設定が変わります。圧縮が何を残し何を捨てるかはClaude Code compactの発火条件と要約後に残る情報で扱っています。この記事が扱うのは、圧縮が走るタイミングの調整です。

/autocompact 500k

起動フラグはclaude --helpに出る

v2.1.287で claude --help を実行すると、フラグの一覧に次の2行が出ます。値には auto かトークン数を渡します。

claude --help | grep -A1 autocompact

  --autocompact <auto|tokens>           Auto-compact window size (auto, or
                                        100k–1M tokens)

公式のCLIリファレンスにも同じフラグが載っています。ヘルプの記載はこの1行だけで、サフィックスの書式や優先順位は書かれていません。そこは次の節以降で補います。

指定できる値の書式

コマンドとフラグは、次のどの書式でも値を受け付けます。

• 生のトークン数: 200000
• k または M サフィックス: 500k / 1M
• 100〜1000の裸の数値(千単位として解釈): 200 は 200,000 と同じ

指定できる範囲は100Kから1Mトークンです。モデルのコンテキストウィンドウを超える値は、そのウィンドウまで切り詰められます。auto を渡すと、モデルに合わせた既定のウィンドウに戻ります。

設定したのに効かないときの3つの切り分け

autocompact windowを決める場所は3つあり、優先順位は環境変数、フラグ、/autocompact の順です。まず3つの性格を見比べます。

値を入れたのに挙動が変わらないときは、次の順に確かめると原因を絞れます。

/autocompact が書き込む autoCompactWindow はユーザー設定のキーです。設定の優先度はmanaged settings・コマンドライン引数・プロジェクト個人設定・プロジェクト共有設定・ユーザー設定の順で、ユーザー設定は最も低い階層にあたります。プロジェクトの共有設定やmanaged settingsが同じキーを定義していれば、そちらが先に効きます。

ファイルに直接書くなら、キーの型は100000から1000000のトークン数です。

{
  "autoCompactWindow": 500000
}

環境変数にkを付けると100Kに切り上がる

環境変数で k や M を使うのは落とし穴です。CLAUDE_CODE_AUTO_COMPACT_WINDOW=500k は整数として読まれず、「500」というトークン数になって最低値の100Kに切り上げられます。500Kにしたいなら CLAUDE_CODE_AUTO_COMPACT_WINDOW=500000 と書きます。

サフィックスが使えるのはコマンドとフラグだけです。claude --autocompact auto は、保存済み設定に値があってもチューニング済みのウィンドウでセッションを起動します。なお、CLAUDE_CODE_AUTO_COMPACT_WINDOW を設定すると、ステータスラインの used_percentage は圧縮の時期を示さなくなります。この割合は常にモデルのフルのコンテキストウィンドウを基準に測るためです。スクリプトやCIに組み込むときは、一度 /autocompact を引数なしで開いて、反映結果を確かめておくと安心です。

圧縮を早めたい割合指定と、止めたいときの設定

「何トークンで」ではなく「何%で」早めたいときは、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE が使えます。1〜100の割合で、50 のような低い値で早く圧縮します。既定の割合より大きい値は無視されるので、遅らせる用途には使えません。メインの会話とサブエージェントの両方に効きますが、モデルの上限より手前で圧縮するセッションにだけ働きます。

圧縮そのものを止める設定は2系統あり、止める範囲が違います。

autoCompactEnabled と DISABLE_AUTO_COMPACT は、片方でも自動圧縮を切っていれば、もう片方では戻せません。DISABLE_AUTO_COMPACT は autoCompactEnabled の設定を上書きします。

圧縮を止めた状態でウィンドウが埋まったとき

自動圧縮を無効にした構成では、上限に達しても圧縮されず、リクエストが Prompt is too long で失敗します。対話セッションでは Context limit reached · /compact or /clear to continue という行で表示されます。/config で自動圧縮を切っている場合は、行末に auto-compact is off · /config to turn it on が付きます。

/context も、会話がモデルのウィンドウを超えると出力の先頭に警告を出します。対処は、/clear や /compact で不要なコンテキストを減らすか、無効化の設定を外して自動圧縮を戻すかのどちらかです。

autocompact windowを100Kまで下げても、圧縮の回数が増えるだけで、モデル自体の上限が縮むわけではありません。自動圧縮が走ったうえで失敗するケースは別の症状で、Error during compactionの意味と対処で扱っています。

何も設定しないときの既定値

/autocompact を一度も使わなければ、Claude Codeは基本的にモデルのコンテキスト上限に達したところで圧縮します。例外は次のとおりです。

• クラウドセッションは、上限に近づいた時点で圧縮する(境界ぴったりを待たない)
• 拡張コンテキストなしのSonnet 4.6・Opus 4.6は、200K境界で圧縮する
• Opus 4.8以降も、200Kウィンドウで動くときは200K境界で圧縮する。v2.1.287より前のBedrock・Google CloudのAgent Platform・Microsoft Foundryや、CLAUDE_CODE_DISABLE_1M_CONTEXT=1 を設定したときが当たる
• v2.1.287以降は、Opus 4.7以降とFableがBedrock・Vertex・Foundry・Claude appsのgatewayでも、[1m] なしで既定が1Mになる
• ネイティブで1Mウィンドウを持つモデルは、窓が埋まる前、約967Kトークンで圧縮する。Anthropic APIでは、Sonnet 5・Fableの各モデル・Opus 4.7以降がこれに当たる
• CLAUDE_CODE_DISABLE_1M_CONTEXT=1 を設定すると、Sonnet 5やFableのようなネイティブ1Mのモデルも200K境界で圧縮する
• Claude Codeが認識しないモデルID(LLM gatewayのエイリアスなど)は、そのIDに対して想定するウィンドウで圧縮する

Sonnet 5の既定値は約97万トークンに動いてきた

Anthropic APIのSonnet 5.5とSonnet 5は、常に1Mのコンテキストウィンドウで動きます。200Kの別バリアントも [1m] の接尾辞もなく、どのプランでも追加のusage creditは要りません。既定では約967,000トークンで自動圧縮が入ります。変えたいときは CLAUDE_CODE_AUTO_COMPACT_WINDOW に別の値を指定します。

この既定値は、changelogを遡ると固定ではありませんでした。

gatewayの上限が200Kのとき

LLM gateway経由のセッションでは、認識できるモデルにはAnthropic APIと同じウィンドウが与えられます。Fable 5.1・Fable 5・Sonnet 5以降・Opus 4.7以降は1Mです。[1m] を選んではじめて1Mになるモデル(Opus 4.6など)は、選ばなければ200Kで動きます。

困るのは、gateway側やその後ろのサーバーが200K超を拒否する構成です。Claude Codeはこの下限を検出できません。

対処は、/autocompact 200k で圧縮の境界を手前に引くことです。

モデルIDが想定とずれるときはCLAUDE_CODE_MAX_CONTEXT_TOKENS

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はこの解決に該当する。@YYYYMMDD のように読み取り時に外される接尾辞が付くIDは、上の2つのケースで扱われる

認識できないモデルIDには、CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 という選択肢もあります。v2.1.223から、認識できないIDのセッションは想定ウィンドウの範囲内に収めるのが既定です。この変数はその既定を外し、APIが「長すぎる」と実際に拒否するまで圧縮を待たせる以前の挙動に戻します。ただしgatewayがエラーを書き換えて転送する構成では、この回復処理は働きません。

コストへの効き方

1Mウィンドウのトークンは、標準のモデル料金で課金され、200Kを超えた分の割増はありません。そのため、autocompact windowを大きくしても、トークン単価が上がるわけではありません。ただし会話が長いほど、1回のリクエストに載る入力は増えます。

不要な履歴を会話から外したいときは、無関係なタスクの合間に /clear を挟む方法もあります。圧縮のタイミングを調整する /autocompact とは役割が違い、履歴そのものを捨てる操作です。

まとめ

ウィンドウを広げても200K超の割増はないので、圧縮の頻度が気になるときは大きめの値から試す選択肢があります。ただし会話が長いほど1回の入力は増えるため、トークン消費は見ておく必要があります。