Claude Codeのメモリリークで使用量が急増しOOM Killされる原因と対処

Claude Codeが120GB超まで膨らみOOM Killされる報告

Claude Codeのメモリ使用量が増え続けてOOM Killされるとき、原因は特定の1つではなく、使っている機能ごとに異なる複数のリークです。まずclaude --continueで再開するか、フルスクリーン表示でなければ/compactで解放し、--safe-modeで原因の層を絞ります。セッションのヒープが2.5GBを超えると警告が出るので、そこが目安です。

Claude Codeのプロセスが長時間セッション中に肥大化し、LinuxカーネルのOOM Killer(out-of-memory killer)に強制終了される事例がGitHub issueで報告されています。公式が案内する動作要件は4GB以上のRAMですが、実際の報告では120GB以上まで膨れ上がったケースが複数あります。

発端はissue #4953です。2025年8月1日、Ubuntu 24.04・RAM 128GB・Claude Code v1.0.53の環境で登録されました。インタラクティブモードで30〜60分ほど作業を続けると、claudeプロセスのRSS(実メモリ使用量)が120〜125GB前後まで増え続け、dmesgのログにKilled process ... (claude) ... anon-rss:124857720kBのようなカーネルの強制終了記録が残ります。

復旧しても、症状は再発します。OOM Killで落ちた直後は使用量が約400MBまで下がりますが、セッションを続けるとまた同じペースで増えていきます。報告者は、頻繁な再起動が必要になり長時間の作業には使えないと書いています。

同じissueには2025年10月から12月にかけても新しい報告が続きました。34GB(Mac M1 Max・32GB)、97GB、107GB、130GB超と、別々の報告者が数値を挙げ、環境やOSを問わず同じ症状が観測されています。130GB超の報告者は、後からaudioとntfyのhookが原因だったと追記しています。VS Code拡張ではclaudeプロセスが1つずつ約250MBを使いながら大量に立ち上がる、という別パターンの報告(2025年12月28日)もあり、単一プロセスの肥大化だけが症状ではありません。

コメントに挙がったバージョンを追うと、報告はv1.0.53にとどまりません。「サブエージェントを使い始めたv1.0.70前後から発生している」という報告、v1.0.98で4プロセスが1つあたり2.5GBを使っていたという報告、v2.0.1では安定していたRSSが60秒で7倍に跳ねたという報告、v2.0.27でも同様の報告があったという声が並びます。バージョンをまたいで似た急増パターンが繰り返し報告されている点が、単発の実装ミスではないことを示唆しています。

メモリリークの原因は1つではない

公式changelogを追うと、「長時間セッションでメモリが増え続ける」という同じ症状に、まったく別のコードパスが関わっていたことが分かります。原因は1つの巨大なバグではなく、性質の異なる複数のリークが積み重なったものです。

大きく4つの系統に分けられます。

同じ「OOM Kill」という症状の裏に、使っている機能によって異なる原因が隠れています。MCPサーバーを多用する環境と、hookを多用する環境では、当てはまる原因も有効な対処も変わってきます。

v2.1.50からv2.1.257まで続く修正の系譜

2026年2月から9月にかけて、ほぼ毎月のリリースで具体的なメモリリークの修正が入っています。1回のリリースで5件以上まとめて修正された回もあり、断続的にではなく継続的に手が入ってきたことが分かります。

中でもv2.1.63は突出していて、1回のリリースだけでリスナー・キャッシュ系のリークが11件まとめて修正されました。内訳はブリッジのポーリングループ、MCP OAuthフローの後始末、hooks設定メニューの操作、権限確認の自動承認、bashコマンドのプレフィックスキャッシュ、MCPツール・リソースキャッシュの再接続時、WebSocketの再接続時、gitルート検出キャッシュ、JSONパースキャッシュ、Agent Teamsの会話圧縮後のメッセージ保持、MCPサーバーのフェッチキャッシュです。

issue #4953が報告されたv1.0.53は、この一覧より前のバージョン体系です。個々の修正が同issueの再現条件を直接解消したという確認は取れていませんが、症状として報告されていた「長時間セッションでの際限のない増加」に該当する原因は、この7か月ほどの間だけでも表の14リリースにわたって個別に特定・修正されています。

自分の症状の原因を切り分ける

原因が複数系統に分かれているため、まず「どの機能を使っているときに悪化するか」を絞り込むのが近道です。公式のトラブルシューティングガイドが高CPU・高メモリに対して挙げる手順は次のとおりです。

ここから先は、症状のパターン別にさらに系統を絞り込みます。

OOM Killされたのは本体か子プロセスか

Linuxでは、OOM Killerの記録がカーネルログに残ります。dmesg -t | grep -i oomで絞り込むと、強制終了されたプロセス名とanon-rssの値を確認できます。権限の都合でdmesgが読めない環境ではsudoが要る場合があります。

カーネルの記録に残るプロセス名が最初の手がかりです。issue #4953の記録では(claude)が強制終了の対象でした。名前がclaudeなら、本体のメモリ増加が疑われます。コンテナがexit code 137で落ちた場合の切り分けは、exit code 137のOOMをdockerとdmesgで切り分ける手順にあります。

別の名前が並んでいる場合は、Claude Codeが起動したコマンド側の話かもしれません。Linux・WSLではCLAUDE_CODE_TOOL_MEMORY_LIMITでBash・PowerShell・Monitorツールのコマンドにメモリ上限を掛けられます。上限はコマンドごとではなくセッション全体で1つで、3つのツールのコマンドがまとめて数えられます。上限を超えたコマンドはカーネルに殺されますが、結果の出力に上限の名前は出ません。そのため、コマンドだけが理由もなく落ちたときは、この設定が有効になっていないかを疑う価値があります。cgroupを作れなかった場合は上限なしで動き、理由はclaude --debugのログに残ります。

Writeツールが「Out of memory」と表示する別の症状もあります。v2.1.246で直ったのは、巨大な既存ファイルを上書きしたあとにこの表示が出たり長く固まったりする問題で、ファイル自体は書き込まれていました。プロセス全体の肥大化とは別の経路です。

長時間セッションの予防策と警告の意味

セッションのヒープが2.5GBを超えると、メモリ使用量が危険水準だという警告が表示されます。対処は、Claude Codeを再起動してclaude --continueで会話を再開することです。フルスクリーン表示でない場合は/compactでも解放でき、使用量が2.5GBを下回れば警告は消えます。

フルスクリーン表示はCLAUDE_CODE_NO_FLICKER=1、または/tui fullscreenで有効にします。見えているメッセージだけを描画ツリーに保持するため、会話が長くなってもメモリが一定に保たれる、と公式は説明しています。研究プレビュー扱いの機能です。前述のとおり、このトランスクリプト表示にも行ごとの保持が見つかり、v2.1.246で直りました。

同時に動くエージェントの数も、メモリに響きます。v2.1.217から、同時実行のサブエージェントは既定で20に制限されました。上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変えられます。ワークフロー機能の同時実行数はCLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSで決まり、既定は16(CPUが少なければそれ未満、範囲は1〜256)です。各エージェントのトランスクリプトがClaude Codeのメモリに残るため、値を上げるほど使用量も増えます。この環境変数はv2.1.269以降が対象です。

バックグラウンドのシェルコマンドには、メモリ逼迫時の自動回収があります。v2.1.193で追加された機能で、macOSとLinuxにおいてOSが危険水準のメモリ逼迫を報告し、セッションが30分アイドルでターンもサブエージェントも動いていないとき、バックグラウンドシェルを終了します。止めたい場合はCLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1です。放置したビルド監視などが、使用中に消えたように見えて戸惑う場合の原因になりえます。

/heapdumpの出力と、カスタマイズ層の切り分け

/heapdumpはメモリ使用量が高止まりしたときの診断コマンドです。~/Desktop(Linuxでデスクトップフォルダが無い場合はホームディレクトリ)に、JSヒープのスナップショット(.heapsnapshot)と内訳を示す診断用JSON(-diagnostics.json)の2ファイルを書き出します。コマンドメニューの候補には出てこないため、/heapdumpと全文入力する必要があります。

使い方の詳細は/heapdumpでメモリ使用量の高さを診断するにまとめています。CLAUDE.mdやhooks、MCPサーバーなど自分で積んだカスタマイズが原因かどうかを切り分けたい場合は、全カスタマイズを無効化して起動するclaude --safe-modeが使えます。v2.1.286のヘルプには、フラグと並んで次のように載っています。

claude --version
claude --help | grep -E -- "--(safe-mode|bare)"

手元のv2.1.286では、1行目が2.1.286 (Claude Code)と返りました。2行目の抜粋では、--bareが「Minimal mode」、--safe-modeが「Start with all customizations ... disabled」と説明され、--safe-modeには環境変数CLAUDE_CODE_SAFE_MODE=1でも同じ動作になる旨が書かれています。

safe modeで症状が消えれば、原因はカスタマイズ側にある可能性が高いと分かります。手順の詳細と--bareとの違いはClaude Code safe modeで「壊れた」設定を1コマンドで切り分けるで扱っています。

環境変数CLAUDE_CODE_SIMPLE=1は、もう1つの切り分け手段です。ただし--safe-modeとは性格が違い、認証まわりに落とし穴があります。

CLAUDE_CODE_SIMPLE=1 claude

サブスクリプションでログインしている環境でこれを実行すると、認証が通らない可能性があります。メモリの切り分けにはまず--safe-modeを使い、さらに削りたいときだけSIMPLEを選ぶ順序が無難です。

暫定的な回避策として、長時間セッションを続ける場合はps aux | grep claudeでRSSを定期的に確認し、増加が続くようなら区切りの良いところで一度セッションを終了して再起動する運用が挙げられます。

Bash・PowerShellが実行するコマンド側がメモリを使い切っている場合は、ここまでの原因とは別です。CLAUDE_CODE_TOOL_MEMORY_LIMITでBash・PowerShellのメモリを制限するで扱うcgroup上限が対処になります。インストール直後に「Installation was killed」で止まる場合も別の話で、Installation was killedエラーの原因と対処にまとめています。

それでも新しいリークが見つかり続ける理由

7か月ほどの間、ほぼ毎月のリリースで個別修正が入ってもなお、新しいメモリリークの修正がリリースノートに載り続けています。長時間の対話セッションは、キャッシュ・トランスクリプト・サブプロセスのハンドルを抱え続ける実行モデルです。保持先が増えるたびに、解放の抜けが新しい場所で見つかる余地が残ります。

修正履歴の中身を見ると、保持先が増える方向に機能が足されてきた様子も読み取れます。エージェントビュー、Agent Teams、ワークフロー、バックグラウンドシェルは、いずれも長く生きるプロセスと状態を増やす機能です。上限(サブエージェントの同時20、LSPドキュメントの50件、編集読み取りキャッシュの16MB)が後から付く形で対処されているのも、この流れと整合します。

個別のパッチを待つだけでなく、/heapdumpでの定点観測や長時間セッションの定期的な区切りを運用に組み込んでおく方が現実的です。

/heapdumpが出す要約は、使用量の大半がJSヒープ(スナップショットで追える範囲)にあるか、ネイティブメモリ(追えない範囲)にあるかを示します。ネイティブメモリが大半という結果が出た場合はスナップショットでは中身を特定できないため、要約に含まれるリーク兆候の数値(メモリの増加速度、開いているハンドルの多さなど)を添えて報告する経路が公式に用意されています。

まとめ

Claude Codeの「120GB超・OOM Kill」は、2025年8月の単一issueに閉じた話ではなく、キャッシュ・UI表示・サブプロセス・バックグラウンド処理にまたがる継続的な課題です。持ち帰る判断は2つです。症状が出たら、まず更新とカーネルの記録で「本体か子プロセスか」を分けます。本体なら--safe-modeでカスタマイズ層を外し、それでも残れば/heapdumpで診断します。

長時間セッションを運用に組み込むチームでは、claude --continueで区切る前提にしておくと、突然のOOM Killによる作業ロスを避けやすくなります。