Claude Codeの/doctorコマンド｜トラブルシューティング完全ガイド

Claude Codeが正常に動作しないとき、最初に実行すべきコマンドが/doctorだ。認証状態・ネットワーク接続・設定ファイルの整合性・ツールの利用可能状況を一括診断し、問題の原因を特定できる。手動で一つずつ確認する手間を省き、トラブルシューティングの時間を大幅に短縮できる。

「Claude Codeを起動したが認証エラーが出る」「MCPサーバーが接続できない」「昨日まで動いていたのに今日は動かない」——こうした問題に直面したとき、/doctorコマンドを実行することで診断が格段に速くなります。

この記事でわかること

• /doctorコマンドの診断結果の読み方と、各チェック項目の意味

• 認証エラー、ネットワーク問題、設定ファイルの不整合など、よくあるエラーの具体的な解決手順

• トラブル発生時の体系的な問題切り分けフローと、/doctor以外の診断手段

/doctorコマンドとは

/doctorは、Claude Codeの動作環境を自動診断するビルトインコマンドです。Claude Codeのセッション中、またはターミナルからclaude /doctorで実行できます。StartLinkのClaude Code活用プロジェクトでは、セットアップ完了後の動作確認として必ず/doctorを実行することをルールにしています。実際、トラブルの80%以上は/doctor実行後10分以内に解決できています。

実行方法

`# セッション中に実行
/doctor

# ターミナルから直接実行
claude /doctor`

診断項目

/doctorは以下の項目を自動的にチェックします。

診断カテゴリ

チェック内容

確認対象

認証

APIキーの有効性、ログイン状態

~/.claude/の認証情報

ネットワーク

AnthropicのAPIエンドポイントへの接続

api.anthropic.com

設定ファイル

settings.json、CLAUDE.mdの読み込み状態

プロジェクト・ユーザー設定

ツール

利用可能なツール、MCPサーバーの接続状態

MCP設定、パーミッション

環境

Node.jsバージョン、OS情報、Claude Codeバージョン

システム環境

診断結果の読み方

/doctorの出力は、各チェック項目の結果がステータスアイコンとともに表示されます。実行は通常5〜15秒で完了します。

ステータスの種類

出力例

`Claude Code Doctor
==================

Authentication
  ✓ API key is valid
  ✓ Account is active

Network
  ✓ Can reach api.anthropic.com
  ✓ SSL certificate is valid

Configuration
  ✓ User settings loaded (~/.claude/settings.json)
  ✓ Project settings loaded (.claude/settings.json)
  ✓ CLAUDE.md found and loaded

Tools
  ✓ Core tools available (Read, Edit, Write, Bash, Glob, Grep)
  ⚠ MCP server "slack" connection timeout (retrying...)
  ✓ MCP server "hubspot" connected

Environment
  ✓ Node.js v20.11.0 (minimum: v18.0.0)
  ✓ Claude Code v1.0.16
  ✓ OS: macOS 15.3`

この例では、SlackのMCPサーバーに接続タイムアウトが発生していますが、他の項目はすべて正常です。Slack MCPの設定を確認すれば問題が解決します。

よくあるエラーと解決法

エラー1: 認証エラー（Authentication Failed）

症状: /doctorで「API key is invalid」または「Authentication failed」と表示される。

原因と解決策:

原因

解決策

APIキーの有効期限切れ

claude loginで再認証

APIキーの削除・無効化

Anthropicコンソールで新しいキーを発行

環境変数の設定ミス

ANTHROPIC_API_KEYの値を確認

プラン（Max）の期限切れ

サブスクリプション状態を確認

`# 再認証
claude login

# 環境変数を確認
echo $ANTHROPIC_API_KEY

# 認証状態をリセット
claude logout
claude login`

Maxプラン（月額サブスクリプション）を利用している場合は、支払い状態を確認してください。支払いが失敗すると認証が無効化されます。

エラー2: ネットワーク接続エラー

症状: /doctorで「Cannot reach api.anthropic.com」と表示される。

原因と解決策:

原因

解決策

インターネット接続の問題

Wi-Fi/有線接続を確認

プロキシ設定

HTTPS_PROXY環境変数を設定

ファイアウォール

api.anthropic.comをホワイトリストに追加

VPN干渉

VPNを一時的に無効化して確認

DNS解決の失敗

nslookup api.anthropic.comで確認

`# 手動で接続確認
curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01"

# プロキシ設定（企業ネットワークの場合）
export HTTPS_PROXY=http://proxy.company.com:8080

# DNS確認
nslookup api.anthropic.com`

企業ネットワーク環境では、プロキシやファイアウォールが原因であるケースが多く見られます。IT部門にapi.anthropic.com:443への接続許可を依頼してください。

エラー3: 設定ファイルのパースエラー

症状: /doctorで「Failed to parse settings.json」と表示される。

原因と解決策:

`# 設定ファイルのJSON構文を検証
cat ~/.claude/settings.json | python3 -m json.tool

# プロジェクト設定の確認
cat .claude/settings.json | python3 -m json.tool`

JSON構文エラー（カンマの過不足、引用符の欠落など）が最も多い原因です。上記コマンドでエラー箇所を特定し、修正してください。

エラー4: MCPサーバー接続エラー

症状: /doctorで「MCP server connection failed」と表示される。

原因と解決策:

原因

解決策

MCPサーバーが起動していない

サーバーを手動起動して確認

設定ファイルのパスが間違っている

.claude/settings.jsonのMCP設定を確認

認証情報が無効

MCPサーバーのAPIキー・トークンを更新

ポート競合

他のプロセスが同じポートを使用していないか確認

`# MCP設定の確認
cat .claude/settings.json | python3 -c "
import json, sys
config = json.load(sys.stdin)
print(json.dumps(config.get('mcpServers', {}), indent=2))
"`

MCPサーバーの問題は、MCP連携ガイドで詳しく解説しています。

エラー5: ツールが利用できない

症状: 特定のツール（Edit、Bashなど）がセッション中に使えない。

原因と解決策:

原因

解決策

パーミッションモードがplan

--mode autoまたは--mode defaultに変更

allowedToolsから除外されている

設定ファイルのallowedToolsを確認

blockedToolsに追加されている

blockedToolsリストを確認

パーミッションモードの設定が意図通りになっているか確認してください。planモードではファイルの書き込みやコマンド実行がすべてブロックされます。

体系的な問題切り分けフロー

/doctorで問題が特定できない場合や、より詳細な調査が必要な場合のフローを示します。

1/doctorで全体診断`

/doctor

まず全体像を把握します。FAILの項目があれば、そこから対処します。

↓
2問題カテゴリの特定

  症状
  カテゴリ
  次のアクション

  「認証エラー」系のメッセージ
  認証
  ステップ3A

  「接続できない」「タイムアウト」
  ネットワーク
  ステップ3B

  「設定が読み込めない」
  設定ファイル
  ステップ3C

  「ツールが使えない」
  パーミッション
  ステップ3D

  「レスポンスが遅い」「途中で止まる」
  パフォーマンス
  ステップ3E

↓
3ステップ3A: 認証の詳細診断```
`# ログイン状態の確認
claude auth status

# 再認証
claude logout
claude login

# APIキーの直接テスト
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'`

↓

4ステップ3B: ネットワークの詳細診断`

`# DNS解決の確認

nslookup api.anthropic.com

nc -zv api.anthropic.com 443

openssl s_client -connect api.anthropic.com:443 -brief

プロキシ経由の接続テストコマンドを実行してAnthropicエンドポイントへの到達性を確認します。

↓
5ステップ3C: 設定ファイルの詳細診断```
`# ユーザー設定
ls -la ~/.claude/
cat ~/.claude/settings.json | python3 -m json.tool

# プロジェクト設定
ls -la .claude/
cat .claude/settings.json | python3 -m json.tool

# CLAUDE.mdの存在確認
cat .claude/CLAUDE.md | head -20`

↓

6ステップ3D: パーミッションの確認`

`# 現在のモードを確認

/doctor

cat .claude/settings.json | python3 -c "

import json, sys

config = json.load(sys.stdin)

perms = config.get('permissions', {})

print('Mode:', perms.get('defaultMode', 'default'))

print('Allowed:', perms.get('allowedTools', []))

print('Blocked:', perms.get('blockedTools', []))

"`

↓
7ステップ3E: パフォーマンスの調査レスポンスが遅い場合は、以下を確認します。

- **コンテキストサイズ**: 大量のファイルを読み込んでいないか。CLAUDE.mdや参照ファイルが肥大化していないか

- **MCPサーバーの応答速度**: 外部サービスのレスポンスタイムが遅くないか

- **ネットワーク帯域**: 回線速度が十分か

## /doctor以外の診断コマンド
`/doctor`と合わせて使える診断コマンドを紹介します。

  コマンド
  用途

  `/status`
  現在のセッション情報（モデル、トークン使用量）

  `/config`
  現在の設定値の一覧表示

  `claude --version`
  Claude Codeのバージョン確認

  `claude update`
  最新バージョンへのアップデート

バージョンが古い場合、既知のバグが原因で問題が発生している可能性があります。`claude update`で最新版に更新してから再度`/doctor`を実行してください。

## 関連コマンドとの組み合わせ
### 設定のリセットと再構築
設定ファイルの問題が解決しない場合、設定をリセットして再構築する方法があります。

`# ユーザー設定のバックアップと削除

cp ~/.claude/settings.json ~/.claude/settings.json.bak

rm ~/.claude/settings.json

claude

/doctor`

### ログの確認
Claude Codeのログファイルを確認することで、`/doctor`では表示されない詳細なエラー情報を取得できます。

`# ログディレクトリの確認

ls ~/.claude/logs/

最新のログファイルを開いてエラーログを確認します。