目次
不具合の概要
Claude Codeを使っていて何らかのエラーに遭遇したとき、いちいち原因を一から調べるのは骨が折れます。そこで役立つのが、「症状」を起点にして原因の候補を絞り込んでいく逆引き型のアプローチです。今回は、よく報告される症状ごとに、想定される原因と対処法を整理します。
症状「固まる・応答がない」
まず試してほしいのが、公式のトラブルシューティングドキュメントでも案内されている一次対応です。応答が返ってこないように見える場合は、Ctrl+Cで現在の操作をキャンセルするか、ターミナルそのものを再起動します。それでも状況が改善しない場合は、「/doctor」コマンドを実行してみるとよいでしょう。このコマンドは、インストール状況、設定内容、MCPサーバーの接続状態、コンテキストの使用量などを自動的にチェックしてくれるため、原因の切り分けに役立ちます。
頻度：中影響度：高（作業が完全に止まってしまうため）
症状「途中で応答が切れる・コンテキストエラー」
「Autocompact is thrashing」というメッセージが出る場合は、会話が長くなったことでコンテキストの自動圧縮処理が繰り返し失敗している状態だと考えられます。この場合は、大きなファイルを一度にまるごと読み込ませるのではなく、小さなチャンクに分割して読ませるように指示を変えるか、「/compact」コマンドを実行して手動でコンテキストを整理するとよさそうです。
症状「インストールできない・起動しない」
そもそも環境構築の段階でつまずいているケースも多いようです。よくある原因が、Node.jsのバージョンが18未満であることです。この場合はNode.jsのアップグレードが必須になります。nvmを使っている場合は、LTS版に切り替えるコマンドを実行することで解決できることが多いようです。
症状「認証エラー・接続できない」
APIキーに起因するエラーが発生した場合は、APIキーが正しくコピーされているか、環境変数の設定名が合っているか、サンドボックス環境と本番環境でキーを取り違えていないか、といった点を確認する必要がありそうです。特に複数の環境を切り替えながら開発している場合は、どちらのキーを参照しているのかを見失いやすいため注意したいところです。
症状「出力が雑になった気がする」
明確なエラーメッセージが出ているわけではないものの、「以前より応答の質が落ちた」と感じることもあるようです。この場合は、思考予算(thinking budget)のデフォルト値が自動的に下方修正されている可能性があります。セッション内で「/effort high」を実行することで、思考予算を最大まで引き上げることができます。
症状「Windows環境だけでエラーになる」
Windows環境でClaude Codeを使っている場合、Windows特有の症状に遭遇することもあるようです。「claudeコマンドが見つからない」というエラーは、インストールディレクトリがシェルの検索パスに含まれていないことが原因のケースが多く、WSLを使っている場合は「which npm」「which node」といったコマンドで、実行されているものがWindows側のバイナリ(パスが/mnt/c/から始まる)なのか、Linux側のバイナリ(パスが/usr/などから始まる)なのかを確認するとよいです。
また、古いバージョンのWSL(WSL1)を使っていると、「cannot execute binary file: Exec format error」というエラーが出ることがあり、この場合はPowerShellからディストリビューションをWSL2に変換するのが最もクリーンな解決策です。加えて、WSL2環境でブラウザ経由のログインを行おうとすると、開いたブラウザからのリダイレクトがClaude Code側のローカルサーバーに届かず、ログインが完了しないという固有の問題が起きることもあるようです。Windowsネイティブ版とWSL版のどちらを使っているかによって対処法が変わってくるため、まずは自分がどちらの環境で動かしているのかを明確にしておくことが、トラブル解決の第一歩になりそうです。
まとめ：まず試すべき3つのコマンド
Claude Codeで何らかの不調を感じたら、次の3つのコマンドをまず試してみてください。
- 「/doctor」：インストール・設定・MCPサーバー・コンテキスト使用量を自動診断
- 「/compact」：コンテキストが肥大化している場合の手動整理
- 「/effort high」：出力の質が落ちたと感じる場合の思考予算引き上げ
症状から原因を逆引きする発想を持っておくと、闇雲に再インストールを繰り返すよりもずっと早く問題を解決できそうです。