Claude Codeが動かない時に/doctorで原因を特定する直し方

「なんか動かない」――Claude Codeを使っていると、そんな状況に突然ぶつかることがあります。スキルが認識されない、エラーが出る、急に遅くなった。どこに原因があるのか、何から確認すればいいのか。まずは /doctor を実行してみましょう。これひとつで、問題のありかがかなりの程度見えてきます。

どんな時に使う？—/doctorはClaude Codeの健康診断

Claude Codeで次のような症状にぶつかった経験はないでしょうか。

コマンドを実行しても反応がない、またはエラーが出る
さっきまで認識されていたスキルが急に見えなくなった
MCPサーバーを追加したら動作が不安定になった
なんとなくレスポンスが遅い
設定ファイルをいじった覚えがないのに急に動かなくなった

こうした「なんかおかしい」の原因をまとめてチェックしてくれるのが /doctor コマンドです。バージョン情報、設定ファイルの不備、MCPサーバーの接続状態――Claude Code自身が診断して結果を出してくれます。

不具合にぶつかったら、まず /doctor を実行する。これだけで問題の切り分けが大きく進みます。

/doctorの実行方法

実行方法は使っている環境で2パターンあります。

CLI（ターミナル）で使っている場合

Claude Codeのチャット画面でそのまま入力します。

/doctor

プロンプトに /doctor と打ってEnterを押すだけです。他のスラッシュコマンド（/help や /clear など）と同じ要領です。

デスクトップアプリで使っている場合

デスクトップ版でも同じようにチャット入力欄に /doctor と入力して実行します。コマンド候補が表示されるので、そこから選んでも構いません。

実行すると、Claude Codeが自身の環境をチェックして結果を一覧で出力します。表示される項目はおおむね次の内容です。

Claude Codeのバージョン
インストール方法（npmグローバルインストールか、その他か）
自動更新の設定状態
設定ファイル（settings.json）の妥当性
MCPサーバーの接続状態
CLAUDE.md のサイズに関する警告
実行環境（Node.jsのバージョンなど）

すべての項目が「問題なし」なら、少なくとも /doctor が確認できる範囲では大きな問題は見つかっていない、と判断できます。どこかに警告やエラーが表示されていれば、そこが怪しい箇所です。

まず確認すること—診断結果の全体像

/doctor を実行したら、出力を上から順に見ていきます。それぞれの項目が何を意味するのか、押さえておきましょう。

バージョン情報

現在インストールされているClaude Codeのバージョンが表示されます。古いバージョンを使っていると、既知のバグが原因で不具合が起きている可能性があります。

インストール方法

npm install -g @anthropic-ai/claude-code で入れたのか、他の方法で入れたのかが分かります。インストール方法によって設定ファイルの場所や更新の挙動が変わることがあります。

自動更新設定

自動更新が有効か無効かが確認できます。無効になっていると、古いバージョンを使い続けることになります。

正常時と異常時の違い

正常時は各項目にチェックマークや「OK」のような表示が出ます。異常があると、該当箇所に警告アイコンや Invalid Settings のような赤いメッセージが表示されます。

❌ Invalid Settings: C:\Users\ユーザー名\.claude\settings.json
   - Unexpected property: "allowedTooks" (did you mean "allowedTools"?)

⚠ CLAUDE.md size: 42KB (recommended: < 30KB)

上記は /doctor の出力イメージです。settings.json にプロパティ名の誤りがあり、CLAUDE.md が大きすぎるという2つの問題が検出されている例です。実際の表示内容はバージョンによって異なります。どこに問題があるかが一目で分かるのが /doctor の便利なところです。

原因候補—/doctorが見つけてくれる問題

/doctor が検出できる問題を、発生しやすい順に挙げます。

1. settings.jsonの書式エラー（いちばん多い）

設定ファイル settings.json にJSONの書式ミスや、存在しないプロパティ名が書かれている場合に Invalid Settings と表示されます。手動で設定を書き換えた時によく起きます。

症状: スキルが動かない、コマンドが効かない、起動時にエラーが出る
/doctorでの表示: Invalid Settings に続いて、具体的なエラー内容が表示される

2. MCPサーバーの接続エラー

MCPサーバーの設定はあるのに、サーバー自体が起動していない、またはパスが間違っている場合に検出されます。

症状: MCPツールが使えない、レスポンスが極端に遅い、MCP関連のエラーメッセージが出る
/doctorでの表示: 該当するMCPサーバー名の横にエラー表示

3. CLAUDE.mdのサイズ警告

プロジェクトの CLAUDE.md が大きすぎる場合に警告が出ます。CLAUDE.md の内容は毎回の会話に含まれるため、サイズが大きいとコンテキストを圧迫して動作に影響します。

症状: レスポンスが遅い、文脈を忘れることが増える
/doctorでの表示: CLAUDE.md size に警告マークとファイルサイズ

4. パスや権限の問題

設定ファイルやプロジェクトのパスに問題がある場合に検出されます。Windowsでは日本語のユーザー名が含まれているパスで問題が起きることがあります。

症状: 特定のプロジェクトだけ動かない、ファイルの読み書きでエラーが出る
/doctorでの表示: パス関連の警告やエラー

上から順に確認していくと、効率よく原因にたどり着けます。

いちばん確率が高い対処—settings.jsonの問題を直す

/doctor で Invalid Settings と表示された場合、settings.json に問題があります。ここがいちばん発生頻度が高いので、まずここから確認します。

settings.jsonの場所（Windows環境）

C:\Users\ユーザー名\.claude\settings.json

エクスプローラーで C:\Users\ユーザー名\.claude フォルダを開いて、settings.json を探します。

Invalid Settingsの読み取り方

/doctor の出力に Invalid Settings がある場合、その直後に具体的なエラー内容が書かれています。よくあるパターンは次の3つです。

Unexpected property — 存在しないプロパティ名が書かれている
Type mismatch — 値の型が間違っている（文字列であるべきところに数値が入っている等）
Parse error — JSONの書式そのものが壊れている

修正手順

settings.json をメモ帳やVS Codeなどのテキストエディタで開く
/doctor で指摘された箇所を確認する
書式エラーなら修正し、不要なプロパティなら削除する
ファイルを上書き保存する
Claude Codeで再度 /doctor を実行して Invalid Settings が消えたか確認する

架空の汎用プロジェクトでの例を挙げます。

修正前（プロパティ名の誤り）:

{
  "allowedTooks": [
    "Bash(npm:*)"
  ]
}

修正後:

{
  "allowedTools": [
    "Bash(npm:*)"
  ]
}

allowedTooks を allowedTools に直すだけで解決します。タイポはよくあることなので、まずは指摘された内容をそのまま確認してみてください。

JSONの書式が壊れている場合

カンマの忘れや括弧の対応ミスが原因のこともあります。JSONバリデータ（「JSON format check」で検索するとオンラインツールが見つかります）に貼り付けて確認するのが手軽です。ただし、設定の内容を外部サイトに送ることになるので、機密性が気になる場合はローカルのエディタで括弧の対応を確認してください。

修正が終わったら、必ず /doctor を再実行してエラーが解消されたか確認します。

ダメな時の次の対処—MCPサーバーの接続エラー

settings.jsonの問題を直してもまだ動かない場合、次に疑うのはMCPサーバーの接続です。

/doctorでどう表示されるか

MCPサーバーに関するエラーがあると、サーバー名とともに接続状態が表示されます。接続に失敗している場合は、エラーの内容が付記されます。

MCP設定ファイルの確認場所（Windows環境）

MCPの設定場所は、追加したスコープによって変わります。

ユーザー単位・ローカル単位のMCP設定は、主に次のファイルに保存されます。

C:\Users\ユーザー名\.claude.json

プロジェクトで共有するMCP設定は、プロジェクト内の次のファイルに保存されることがあります。

.mcp.json

そのため、MCPサーバーの接続エラーが出た場合は、まず /mcp や claude mcp list で登録状況を確認し、必要に応じて .claude.json と .mcp.json の両方を確認します。

接続エラーの主な原因と対処

サーバーが起動していない: MCPサーバーのプロセスが動いているか確認する。Playwright MCPならPlaywrightがインストール済みか、ファイルシステムMCPなら指定したパスが存在するかを確認する
パスの間違い: 設定内のコマンドパスやディレクトリパスが実際の場所と一致しているか見直す。Windowsではバックスラッシュ \ の扱いに注意する
パッケージの未インストール: MCPサーバーが依存するパッケージが入っていない場合、npm install や pip install で導入する必要がある

対処後の確認

設定を修正したら、Claude Codeを再起動してから /doctor を実行します。MCPサーバーは起動時に接続を試みるため、設定変更後は再起動が必要なことがあります。

✅ MCP Server: filesystem — connected
✅ MCP Server: playwright — connected

connected と表示されれば問題ありません。

それでも解決しない時—CLAUDE.mdとその他の確認ポイント

settings.jsonとMCPサーバーの両方に問題がないのに動かない場合、別の箇所を確認します。

CLAUDE.mdのサイズ警告

/doctor で CLAUDE.md size に警告が出ている場合、プロジェクトルートの CLAUDE.md が大きすぎます。このファイルの内容は毎回の会話に含まれるため、サイズが大きすぎるとコンテキストを圧迫して動作に影響が出ます。

対処としては、CLAUDE.md の内容を整理して不要な記述を削るか、複数のファイルに分割して CLAUDE.md から参照する形にします。どの程度のサイズまでなら問題ないかは会話の長さや他のコンテキスト量にも依存するため、/doctor の警告が出なくなれば一旦問題ないと考えて構いません。

パスや権限の問題

Windowsでは、ユーザーフォルダのパスに日本語が含まれている場合に問題が起きることがあります。プロジェクトを C:\Projects\my-app のような日本語を含まないパスに置くことで解決することがあります。

/doctorで「問題なし」なのに動かない場合

/doctor のすべての項目に問題がないのに不具合が続く場合、設定以外の原因が考えられます。

セッションの不具合: /clear で会話をリセットしてみる
コンテキストの圧迫: 会話が長すぎる場合、新しいセッションを始める
一時的なサーバー側の問題: しばらく待ってから再試行する
バージョンの不具合: インストール方法に合わせて最新版に更新してみる。npmで入れた場合は npm update -g @anthropic-ai/claude-code、WinGetで入れた場合は winget upgrade Anthropic.ClaudeCode を使います。ネイティブインストールの場合は自動更新されることがあります

不具合報告時に/doctorの結果を活用する

公式フォーラムやサポートに不具合を報告する際、/doctor の出力を添えると状況が伝わりやすくなります。設定の不備が原因であれば自己解決でき、そうでなければサポート側でも原因の切り分けがスムーズに進みます。出力にAPIキーや個人的なパスが含まれていないか、共有前に一通り確認してください。

症状別フローチャート—何が起きたらどこを見るか

ここまでの内容を、症状ごとの確認手順に整理します。

症状	最初に確認する項目	次に確認する項目
コマンドが効かない・起動エラー	settings.jsonの `Invalid Settings`	MCPサーバーの接続状態
スキルが認識されない	settings.jsonのプロパティ名	スキルファイルの場所と内容
MCPツールが使えない	MCPサーバーの接続状態	MCPのパスとパッケージ
レスポンスが遅い	CLAUDE.mdのサイズ	セッションの長さ（`/clear`を試す）
特定のプロジェクトだけ動かない	プロジェクトのパス	`CLAUDE.md`の内容

基本的な流れ

/doctor を実行する
Invalid Settings があれば settings.json を修正する
MCPの接続エラーがあれば設定とサーバーの起動を確認する
CLAUDE.mdの警告があればファイルサイズを整理する
すべて問題ない場合はセッションをリセットするかバージョンを更新する

解決したかどうかの判断基準

/doctor の再実行で警告やエラーが消えた → おそらく解決
修正後に対象の操作が正常に動いた → 解決確認
/doctor に問題がないのに症状が続く → セッションのリセットまたは最新版への更新を試す

不具合にぶつかったら、まず /doctor を実行する。この癖をつけておけば、Windows初心者でも原因の切り分けがかなり進みます。診断結果の読み方が分からない時は、出力をそのままコピーしてサポートに相談するのも手です。

まとめ

Claude Codeが動かない時、最初にやることはシンプルです。/doctor を実行して、出力された診断結果を上から見る。設定ファイルの書式エラー、MCPサーバーの接続問題、CLAUDE.md のサイズ超過――この3つが大半の原因を占めます。

発生頻度が高い順に確認していくことがポイントです。まず settings.json の Invalid Settings を確認し、次にMCPサーバーの接続状態を見て、それでも解決しない時に CLAUDE.md のサイズやパス周りをチェックする。この順で進めれば、無駄なく原因にたどり着けます。

各ステップで「修正したら /doctor を再実行して解消されたか確認する」を繰り返すだけで、Windows初心者でも不具合の切り分けができるようになります。

Claude Codeでどこまでできる？