Claude Code のトラブルシューティング：インストール、認証、設定、Gateway とパフォーマンス

インストールと PATH、認証、モデルルーティング、プロジェクト設定、拡張ツール、長時間セッションのパフォーマンスはそれぞれ異なる故障階層です。まず最小再現、完全なエラー、現在のディレクトリ、直近の正常状態を記録します。

同時に CLI のバージョン、gateway URL、Key、モデル名を変更すると、どのようなエラーも原因帰属が困難になります。既知の状態に戻してから一度に1つの変数だけを変更してください。

まずバージョンコマンドと claude doctor を実行します。コマンドが存在しない場合は shell が実際に解決したパスを確認します。存在するがバージョンが合わない場合は、ネイティブ、Homebrew、WinGet、古い npm 版を同時にインストールしていないか確認します。

インストールスクリプトが HTML、403、TLS エラーを返す場合はダウンロードのネットワーク問題であり、認証方式を絶えず切り替えて解決すべきではありません。プロキシ、証明書、リージョン、公式インストール URL を確認してください。

/status を使って ANTHROPIC_BASE_URL と認証情報の取得元を確認します。Bearer gateway は ANTHROPIC_AUTH_TOKEN を使用し、x-api-key gateway は ANTHROPIC_API_KEY を使用します。リクエストヘッダーの不一致は通常 401 を返します。

404 は多くの場合 base URL に余分なパスが含まれていることが原因です。未知のモデルはモデルの ID またはルーティングを指します。まず /v1/messages に直接リクエストし、次に Claude Code を確認して、両階層を同時に推測することを避けます。

claude doctor を実行して JSON を確認し、セッション内で /context を使って CLAUDE.md とルールを確認します。起動ディレクトリ、ファイルのスコープ、設定の優先順位、組織の管理ポリシーを確認します。

セッション途中で CLAUDE.md を変更しても、既にコンテキストに入ったバージョンは自動的に置き換えられません。新しいセッションを開いてから再確認し、ルールの表現をひたすら強くしないでください。

MCP は claude mcp list、get、セッション内の /mcp で確認します。stdio サービスはその起動コマンドを単独で実行し、HTTP サービスは URL、TLS、認証を個別に確認します。

Hook ではまず固定の JSON 入力でスクリプトを実行し、次に /hooks で読み込まれたかを検証します。matcher、実行ディレクトリ、権限、タイムアウト、終了コードを確認し、スクリプトのエラーをモデルのせいにしないでください。

長時間のセッションでは大量のファイル、ログ、ツール結果が蓄積される可能性があります。まず /context で構成を確認し、無関係なタスクには /clear を、同じタスクには保持要件付きの /compact を使用します。

リポジトリ検索の異常時は ripgrep、生成ディレクトリ、大型の vendored コードを確認します。monorepo は具体的なパッケージディレクトリから起動します。gateway が SSE をバッファリングする場合も、長時間の出力なしとして現れるため、サーバー側でストリーム転送を検証する必要があります。

OS、インストール方法、claude --version、再現コマンド、期待される動作と実際の動作、完全なエラー、gateway を使用しているかを記録します。設定の問題には秘匿化した関連箇所を添付し、home ディレクトリ全体を送付しないでください。

どの確認が完了し、その結果がどうであったかを明示します。例えば、Messages への直接接続は成功したが CLI は失敗した、あるいは特定の MCP を無効化した後に復旧したなどです。質の高い証拠は問題切り分けの経路を直接的に短縮します。