無料相談する

カテゴリー / エラー・不具合の対処

Claude Codeのエラーログはどこ？デバッグログの出力と保存期間

NO WAVE公開 更新 読了目安 11分

この記事の目次

Claude Codeのエラーログを調べるときに主に見るのは、会話の記録とデバッグログです。会話の記録は既定で ~/.claude/projects/<project>/<session-id>.jsonl に保存されます。一方、エラーの手がかりになるデバッグログは既定ではオフで、claude --debug での起動やセッション中の /debug などでデバッグを有効にすると、既定では ~/.claude/debug/<session-id>.txt に書かれます。どちらも既定の保存期間は30日で、それより古くなるとセッション開始後のバックグラウンド処理で削除されます。

以下、保存場所、デバッグログの出し方、MCPやフックの不具合での読み方、保存期間、人に渡す前の確認点を、公式ドキュメントの記述に沿って説明します。エラーメッセージごとの原因調査と対処はClaude Codeのエラー対処ガイドで扱っています。

Claude Codeのエラーログはどこに保存される？

エラーログの調査で主に見るのは次の2つです。

種類 保存場所 いつ書かれるか 中身
会話の記録 ~/.claude/projects/<project>/<session-id>.jsonl 既定で自動保存（書き込みを止める設定もある） すべてのメッセージ、ツール呼び出し、ツールの結果
デバッグログ ~/.claude/debug/<session-id>.txt デバッグを有効にしたときだけ MCPサーバーの出力、フックの実行結果など

<project> は基本的に、作業ディレクトリのパスの英数字以外を - に置き換えた名前です。変換後の名前が200字を超える場合は、200字で切ったうえでフルパスのハッシュが付きます。公式の例では、~/work/my-repo のプロジェクトは projects/ の下に -home-user-work-my-repo のような名前で入ります。別のディレクトリで起動したセッションは別フォルダに入るので、見つからないときはここを確認してください。

同じセッションのフォルダには、サブエージェントの会話記録（subagents/）と、大きすぎて別ファイルに分けられたツール出力（tool-results/）も置かれます。

Windowsでは ~/.claude は %USERPROFILE%\.claude を指します。環境変数 CLAUDE_CONFIG_DIR を設定している場合は、~/.claude がすべてその指定先に置き換わります。なお ~/.claude/logs/ は旧バージョンの名残で、現在は書き込まれません。中身が空でも異常ではありません。

デバッグログはどうやって出力する？

出し方は4通りです。

方法 使いどころ
claude --debug で起動 起動直後から記録したいとき
claude --debug-file <path> で起動 書き出し先を自分で決めたいとき（デバッグも同時に有効になる）
セッション中に /debug を実行 作業中に、ここから記録したいとき
環境変数 DEBUG=1 起動オプションを変えにくいとき

--debug はカテゴリで絞り込めます。絞り込みが効くのは = でつないだ形だけで、スペース区切りだとデバッグは有効になっても絞り込みはかかりません。

claude --debug='mcp,startup'

ログの出力先を固定したい場合は --debug-file を使います。

claude --debug-file /tmp/claude-debug.log

つまずきやすい点

--debug を付けても端末には何も表示されません。ログはファイルに書かれるだけなので、~/.claude/debug/ の中を確認してください。画面上で各ターンの出力を詳しく見る --verbose は表示の切り替えで、デバッグログとは別物です。

/debug は実行した時点からしか記録しません。エラーの後に実行しても、それ以前のデバッグ記録は残っていないので、/debug を実行してから同じ操作をもう一度行います。/debug は記録を始めたうえでClaudeがログを読んで原因を調べる仕組みで、引数に症状を書くと調査の焦点を絞れます。

CLAUDE_CODE_DEBUG_LOGS_DIR は名前に反してディレクトリではなくファイルパスを指定する変数で、これだけではログは有効になりません。また DEBUG は 1、true、yes、on のときだけ有効なので、他のツール向けの DEBUG=express:* のような値では始まりません。記録の細かさは CLAUDE_CODE_DEBUG_LOG_LEVEL（verbose、debug（既定）、info、warn、error）で変えられます。

MCPやフックが動かないときはログのどこを見る？

MCPサーバーがツールを返さないとき

/mcp で接続済みなのにツールが0件なら、サーバーは起動しているもののツール一覧を返していない状態です。まず /mcp から Reconnect を選び、それでも0件なら次のコマンドで起動して、デバッグログに記録されたサーバーの標準エラー出力（stderr）を読みます。

claude --debug=mcp

サーバー側の標準エラー出力を、ここで確認できます。設定そのものはClaude CodeのMCP設定ガイドを参照してください。

フックが発火しない、遅いとき

/hooks に表示されるのに発火しない場合は、claude --debug で起動して対象のツール呼び出しを起こします。デバッグログには、発生したイベント、照合したマッチャー、フックの終了コードと出力が記録されます。公式の例では、行は次のようにタイムスタンプと [DEBUG] で始まります。

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text

遅いフックは、Hooks: で始まり所要時間で終わる行を検索します。v2.1.296以降では Hooks: PostToolUse:Write [.claude/hooks/log-write.sh] finished with status 0 (31ms) のような行が残り、終わり方には timed out after <N>ms、cancelled、moved to the background、failed to start もあります。書き方はClaude Codeのフック設定ガイドで扱っています。

原因がプラグイン、MCPサーバー、フックのどれか見当がつかないときは、claude --safe-mode で起動するとカスタマイズをすべて無効にして試せます。

会話の記録（jsonl）はどう読む？

会話の記録はJSONL形式で、1行がメッセージ、ツールの使用、メタデータのいずれかを表すJSONです。テキストエディタで開けば、どのツールに何を渡し、何が返ったかを時系列でたどれます。エラー時に実際に実行されたコマンドと出力を確かめるのに向いています。

ただし形式はClaude Codeの内部仕様で、バージョンごとに変わると明記されています。キー名を前提にしたスクリプトはアップデートで壊れることがあるため、公式の手段を使い分けます。

  • 人が読める形で残す: /export（ファイル名を渡すとそのファイルへ平文で書き出す）
  • 特定の記録から再開する: claude --resume <transcript-path>（jsonlのフルパスを指定）
  • 終了時に保管する: フックに渡される transcript_path を使い、SessionEnd フックで保存する

ログは何日残る？保存期間を変えるには

会話記録とデバッグログは、cleanupPeriodDays の日数より古くなると削除されます。既定は30日です。削除はセッション開始後にバックグラウンドで行われ、保存期間を安全に判断できる場合に実行されます。メッセージは出ません。しばらく使っていないセッションが /resume の一覧から消えているのはこのためです。

期間は settings.json で変えます。公式の例は次のとおりです。

{
  "cleanupPeriodDays": 20
}

最小値は 1 で、0 は検証エラーになります。長く残したい場合、公式は 3650 のような大きな値を例に挙げています。反対に記録を書かせたくない場合は、環境変数 CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 で会話記録とプロンプト履歴の書き込みを止められます。claude -p の1回だけなら --no-session-persistence を併用します。

Claude DesktopやCoworkで開始した、または最後に続けたセッションの記録は、既定では日数にかかわらず残ります。期限を付けるには desktopSessionCleanupPeriodDays を設定します（v2.1.248以降）。設定ファイルの置き場所はClaude Codeのsettings.json設定ガイドで説明しています。

ログを人に渡す前に何を確認する？

~/.claude の下のファイルは平文で、保存時に暗号化されていません。ツールを通ったものは記録に書かれ、ツールが .env を読んだりコマンドが認証情報を表示したりすると、その値がjsonlに残ります。渡す前に次を確認してください。

  • APIキー、トークン、パスワード、.env の中身が含まれていないか
  • 機密情報（社外秘のコードやファイルの内容）、顧客情報が含まれていないか
  • /heapdump のファイル（~/Desktop に書かれる <session-id>.heapsnapshot など）を混ぜていないか。公式によると、会話全体とプロセスが持っていた認証情報を含み、自動削除の対象にもなりません

予防策として、認証情報ファイルの読み取りを権限ルールで拒否する方法が公式で挙げられています。組織としての対策はClaude Codeの法人利用向けセキュリティガイドにまとめています。

/bugや/feedbackで報告すると何が送られるか

/bug や /feedback で報告すると、コードを含む会話履歴のコピーがAnthropicに送られます。送信前に、含める範囲を「現在のセッションのみ」（既定）か、同じプロジェクトの過去24時間または7日間の他のセッションも含める共有範囲を選び、同意画面で確認します。

確認点 公式ドキュメントの記述
保持期間 /feedback、/bug、/share で共有した記録は5年間保持
公開範囲 任意で、公開リポジトリにGitHubのissueが作成される
Amazon Bedrockなどサードパーティのプロバイダー経由、またはAnthropicの認証情報がない場合 送信されず ~/.claude/feedback-bundles/ に保存。既知のAPIキーとトークンのパターンは伏せられ、自分で送るまで手元から出ない
組織で止めたい場合 DISABLE_FEEDBACK_COMMAND=1 で /feedback、/bug、/share を無効化

範囲を広げるほど無関係なセッションの情報まで送られるので、再現に必要なセッションだけを選ぶのが安全です。

不要になったログはどう消す？

プロジェクト単位の削除手順では claude purge を使います。会話記録、タスクリスト、デバッグログ、ファイル編集履歴、プロンプト履歴の該当行などがまとめて削除されます。まず --dry-run で対象を確認できます。

claude purge ~/work/my-repo --dry-run

v2.1.288より前は claude project purge という名前でした。手作業で消す場合、~/.claude/debug/ は消しても利用者に見える影響はありませんが、~/.claude/projects/ を消すと過去セッションの再開や巻き戻し、自動メモリが失われます。~/.claude.json、~/.claude/settings.json、~/.claude/plugins/ は認証情報や設定が入っているので消さないでください。

エラーログが保存されるファイルの場所、オプション名、既定値は2026年10月時点の公式ドキュメント（code.claude.com/docs）の記述です。挙動が違う場合は、お使いのバージョンに合わせて公式の該当ページを確認してください。それでも原因が分からないときは、公式のトラブルシューティングが挙げる /doctor（セットアップの点検）と /mcp（MCPサーバーの状態確認）から始めます。

まとめ

Claude Codeのエラー調査で主に見るのは、既定で保存される会話記録（~/.claude/projects/ のjsonl）と、デバッグを有効にしたときに書かれるデバッグログ（~/.claude/debug/）です。原因を追うなら claude --debug か /debug でデバッグログを取り、MCPは --debug=mcp でサーバーの出力を、フックは Hooks: の行を見ます。どちらも既定の保存期間は30日（Claude DesktopとCoworkの記録は例外）で、平文で保存されるため、人に渡す前に認証情報や社外秘の情報が含まれていないかを確認してください。

CLIの基本操作から見直したい方はClaude Codeの使い方ガイドへ進んでください。ログを読めるようになると、設定やフックを自分で調整できる範囲が広がります。そうした運用の工夫を仲間と一緒に学びたい方には、月額1,980円から参加できる学習コミュニティ「AI駆動ラボ」も選択肢のひとつです。

CONTINUE THE SESSION

関連記事