Claude Code トラブルシューティング
Claude Codeのトラブルシューティングにおける重要なポイントは、Claude / Anthropic専用の設定が正しく読み込まれているかを確認することです。OpenAI互換のアドレス、Codexのモデル名、GeminiのAPI KeyなどをClaude Codeに混入させないようご注意ください。
最初に確認すべき項目
| 確認項目 | 確認方法 | 理由 |
|---|---|---|
| 対象ツール | CodexやGemini CLIではなく、Claude Codeをトラブルシューティングしていることを確認 | ツールによって設定ファイル、プロトコル、モデル名が異なります。 |
| プロバイダーの対応プロトコル | 管理画面やチュートリアルでClaude、Anthropic、Claude Codeについて明記されているか確認 | OpenAI互換インターフェースのみ提供しているプロバイダーは、Claude Codeに対応していない場合があります |
| Keyの種類 | Claude / Anthropic専用のKeyを使用 | Keyの種類が正しくない場合、401エラーや認証失敗が直接発生します |
| ターミナルの状態 | 設定を切り替えた後、ターミナルを再起動して再テスト | 古いターミナルには切り替え前の環境変数や設定が残っている可能性があります |
よくあるエラーと対処法
| 症状 | 優先確認事項 | 解決方法 |
|---|---|---|
| コマンドは起動できるが、リクエストに失敗する | Claude Codeが新しい設定を取得できているか | 現在のターミナルウィンドウを閉じて再度開き、最短のテスト用プロンプトを送信してください。CC-Switchで切り替えた後は、同じ設定を手動で同時に変更しないでください。 |
| 401 / Unauthorized | Keyの種類と完全性 | Claude / Anthropic専用のKeyを使用しているか確認し、OpenAI互換のKeyを入力しないようにしてください。また、コピー時に前後に不要な空白が入っていないか再確認してください。 |
| 404 / model not found | Claudeモデル名 | プロバイダーの管理画面に記載されているClaudeモデル名をそのまま正確に入力し、大文字・小文字、ハイフン、バージョン番号を変更しないでください。 |
| 接続タイムアウトまたは応答なし | Claude Base URL | 管理画面でClaude / AnthropicのAPIアドレスを確認してください。OpenAI互換アドレスのみを提供するプロバイダーは、Claude Codeに対応していない可能性があります。 |
| 切り替え後も古いプロバイダーが使用される | ターミナルセッションと設定元 | ターミナルを再起動して再度テストしてください。それでも反映されない場合は、CC-Switchの現在のProviderがClaude Codeに正しく適用されているか確認してください。 |
最小限の接続テスト
テスト時は、まず定型の短い質問を送信して応答を確認してから、実際のプロジェクトでの作業に進んでください。
Claude Code 最小接続テスト
claude "Please reply only: Claude Code configuration test successful"問題報告用テンプレート
プロバイダーへ問い合わせる際の記入例
Tool: Claude Code System version: Provider dashboard Base URL: Model ID / model name: Exact error: I have checked: no spaces in the Key / balance is sufficient / model name copied exactly / Base URL copied from the dashboard / terminal reopened