%20(%E8%83%8C%E6%99%AF%E3%81%82%E3%82%8A).png?width=130&height=39&name=%E6%9C%80%E7%B5%82Start%20Link%20(500%20x%20150%20px)%20(%E8%83%8C%E6%99%AF%E3%81%82%E3%82%8A).png "StartLink"){kind=logo}
この記事の結論
Claude Codeが正常に動作しないときにまず実行すべきコマンドが、/doctorです。インストール・設定ファイル・拡張機能・権限の状態を一括で点検し、どこから調べるべきかの見当をつけやすくなります。
Claude Codeが正常に動作しないときにまず実行すべきコマンドが、/doctorです。インストール・設定ファイル・拡張機能・権限の状態を一括で点検し、どこから調べるべきかの見当をつけやすくなります。
「Claude Codeを起動したら認証エラーが出た」「MCPサーバーに接続できない」「昨日まで動いていたのに今日は動かない」——こうした症状に直面したとき、どこから手をつければよいか迷う方は多いのではないでしょうか。手動で認証状態・ネットワーク・設定ファイルを一つずつ確認していくと、原因にたどり着くまでに時間がかかってしまいます。
/doctorとは、Claude Codeの動作環境を自動診断するビルトインコマンドです。インストールの状態・設定ファイル・拡張機能・CLAUDE.md・権限などを点検し、実行するとその場で所見がまとめて示されます。手動で一つずつ確認する手間を省き、トラブルの原因を短時間で絞り込める点が最大の価値です。
この領域の全体像はClaude Code完全ガイドで体系的に整理しています。
この記事でわかること
ここでは、Claude Codeが思うように動かなくなったときに、何をどの順番で確認すればよいかを整理します。エンジニア個人での利用だけでなく、チームで運用ルールを作る際の考え方にも触れています。
/doctorの診断結果の読み方 — 点検される領域と、見つかった問題への対応の優先順位のつけ方がわかります- よくあるエラーと解決手順 — 認証エラー、ネットワーク接続エラー、設定ファイルの不整合、MCPサーバー接続エラーなど、頻出パターンの原因と対処法を整理しています
- 体系的な問題切り分けフロー —
/doctorで原因が特定できないときに、どのステップで詳細調査に進むかを示しています - チームで運用する際の設計の考え方 —
/doctorを個人の勘に頼らず仕組みとして定着させる方法を紹介します
Claude Codeを実務で使い始めたばかりの方から、チームでの運用ルールを整備したい方まで参考にしていただける内容です。最後まで読むと、トラブル発生時に自分でどこまで切り分けられるかの見取り図を持てるようになります。
/doctorコマンドとは
/doctorは、Claude Codeのセッション中に実行するビルトインの診断コマンドです。2026年10月時点の公式ドキュメントでは、インストール・設定・拡張機能・CLAUDE.mdの問題を診断し、直せるものは確認のうえでClaudeが修正を提案・適用する「セットアップ診断」と説明されています。セッションを開始せずにターミナルから確認したいときは、読み取り専用の診断を表示するclaude doctorを使います。トラブル発生時に最初に打つべき一手といえます。なお、本記事の優先度の表と出力例は、診断の見方を伝えるための整理・イメージであり、実際の表示は版によって異なります。
StartLinkがClaude Codeの導入支援を行う際も、セットアップ完了後の動作確認として/doctorの実行をルール化することをおすすめしています。個人の経験や勘に頼って一つずつ確認するのではなく、まず/doctorを実行して全体像を把握してから対処するという順番をチームで共有しておくことが、結果的に手戻りの少ないトラブルシューティングにつながります。
実行方法
/doctorは次の2通りの方法で実行できます。
# セッション中に実行
/doctor
# ターミナルから直接実行（読み取り専用の診断を表示）
claude doctor以下の図は、セッション中に使う/doctor・/status・/configと、ターミナルで使うclaude doctor・claude auth status・claude auth logout・claude auth loginを並べたものです。ログイン・ログアウトはclaude authのサブコマンドで行います。
診断項目
2026年10月時点の公式ドキュメントでは、/doctorは次の領域を点検するとされています。
| 診断領域 | チェック内容 |
|---|---|
| インストールの状態 | 重複・残存したインストール、PATHの問題、解析できない設定ファイル、新しいバージョンの有無 |
| 拡張機能 | 使われていないスキル・MCPサーバー・プラグインと、そのコンテキスト消費、動作の遅いhooks |
CLAUDE.md |
重複している内容、コードから導けるため不要な記述、常時読み込まれる指示の整理 |
| パーミッション | autoモードの既定化や、拒否が多い読み取り系コマンドの事前許可の提案 |
| 使用量 | Pro・Max・Team・Enterpriseプランで、直近7日間の使用量を下げる提案 |
認証状態・ネットワーク接続・MCPサーバーの接続といった個別の確認は、claude auth statusやclaude mcp listなど別のコマンドで行います。本記事では、この使い分けも含めて整理しています。
診断結果の読み方
/doctorは、Claudeが環境を調べて所見をまとめ、修正案を提示する形で動作します。修正を適用する前に確認を求められるため、まずは所見の全体を見渡してからどこに手をつけるかを決めることをおすすめします。固定の「PASS・WARN・FAIL」といった判定ラベルが決まって表示される仕様ではなく、表示の形式は版や環境によって変わります。
優先度のつけ方
出力に決まったステータスはありませんが、実務では次の3段階に分けて考えると判断しやすくなります。この表は本記事で用いる整理であり、/doctor自体の表示ではありません。
| 優先度 | 状態の例 | 対応の目安 |
|---|---|---|
| 高 | 設定ファイルが解析できない、認証できない、起動できない | 即座に対応する |
| 中 | 古いバージョン、重複したインストール、動作の遅いhooks | 作業の区切りで対応する |
| 低 | 使われていないスキル、CLAUDE.mdの整理提案 |
次の機会に検討する |
所見の読み方のイメージ
次は、所見の読み方を説明するための架空のイメージです。実際の表示とは異なります。
（イメージ）
重要:
- ~/.claude/settings.json を解析できません（カンマの過不足の可能性）
改善の提案:
- MCPサーバー "slack" が長期間使われていません（コンテキストを消費しています）
- 新しいバージョンがあります
整理の提案:
- CLAUDE.md に重複した記述がありますこの例では、設定ファイルの解析エラーが最優先です。使われていないMCPサーバーの整理やCLAUDE.mdの見直しは、動作自体を止めるものではないため、実務上は後回しにしても問題ありません。優先順位は、動作を止める問題から順に考えるのが基本です。
よくあるエラーと解決手順
/doctorや実際の画面で問題が見つかったとき、どう対処すればよいかを症状別に整理します。いずれも原因がいくつか考えられるため、上から順に確認していく形で問題ありません。なお、以下のエラー文言は症状を伝えるための説明用の言い回しで、実際のメッセージは版によって異なります。
認証エラー
症状: 起動時やリクエスト時に「認証に失敗した」「ログインが必要」といったメッセージが表示されます。claude auth statusでも未ログインと表示されます。
| 原因 | 解決策 |
|---|---|
| 認証トークンの期限切れ | claude auth loginで再認証する |
| APIキーの削除・無効化 | Anthropicコンソールで新しいキーを発行する |
| 環境変数の設定ミス | ANTHROPIC_API_KEYの値を確認する |
| プラン（Max）の期限切れ | サブスクリプションの支払い状態を確認する |
# 認証状態の確認（JSONで表示。--textで人が読みやすい形式）
claude auth status
# 再認証
claude auth login
# 環境変数が設定されているかを確認（値そのものは画面に出さない）
[ -n "$ANTHROPIC_API_KEY" ] && echo "set" || echo "not set"
# 認証状態をリセット
claude auth logout
claude auth loginMaxプラン（月額サブスクリプション）を利用している場合は、支払い状態も合わせて確認してください。支払いが失敗すると認証が無効化されるケースがあります。
ネットワーク接続エラー
症状: 「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への接続許可を依頼するのが近道です。
設定ファイル・MCPサーバーのエラー
症状: 起動時やセッション中に「settings.jsonの解析に失敗した」という趣旨のメッセージが出るか、MCPサーバーが接続済みになりません。/doctorでは、解析できない設定ファイルも点検の対象です。
設定ファイルの問題では、JSON構文エラー（カンマの過不足、引用符の欠落など）がよくある原因のひとつです。
# 設定ファイルのJSON構文を検証
cat ~/.claude/settings.json | python3 -m json.tool
# プロジェクト設定の確認
cat .claude/settings.json | python3 -m json.toolMCPサーバー側のエラーは、次の4つの原因が考えられます。
| 原因 | 解決策 |
|---|---|
| MCPサーバーが起動していない | サーバーを手動起動して確認する |
| 設定ファイルのパスが間違っている | プロジェクトのMCP設定は.mcp.json、user・localスコープの設定は~/.claude.jsonにあるため、定義の場所を確認する |
| 認証情報が無効 | MCPサーバーのAPIキー・トークンを更新する |
| ポート競合 | 他のプロセスが同じポートを使用していないか確認する |
MCPサーバーの定義は、プロジェクト共有のものが.mcp.json（プロジェクト直下）、個人用（user・localスコープ）のものが~/.claude.jsonに保存されます。.claude/settings.jsonには置かれません。ファイルを直接開かなくても、次のコマンドで登録内容と接続状態を確認できます。
# 登録済みサーバーと接続状態の一覧
claude mcp list
# 特定のサーバーの詳細（スコープ・コマンド・接続状態）
claude mcp get <サーバー名>.mcp.jsonのサーバーは、一度claudeを起動して承認するまで「Pending approval」のままになる場合があります。起動しない・接続できない場合は、サーバーの状態表示と、セッション中の/mcpの画面を合わせて確認してください。
MCPサーバーの問題は、MCP連携ガイドでも詳しく解説しています。
ツールが利用できない
症状: 特定のツール（Edit、Bashなど）がセッション中に使えません。
| 原因 | 解決策 |
|---|---|
パーミッションモードがplan |
--permission-mode defaultなどで起動し直す（セッション中はShift+Tabでも切り替えられる） |
permissions.allowに許可ルールが無い（確認待ちで止まっている） |
設定ファイルのpermissions.allowを確認する |
permissions.denyに追加されている |
permissions.denyのルールを確認する |
パーミッションモードの設定が意図通りになっているかを確認してください。planモードは、ファイルの読み取りや調査用のコマンド実行はできますが、ソースコードの編集は計画を承認するまでブロックされる仕様です。ただし例外があり、--allow-dangerously-skip-permissionsなどで起動してbypassPermissionsがモードの切り替え候補に入っている対話型ターミナルでは、planの編集ブロックは強制されません（Claudeには編集せず計画するよう指示されますが、試みた編集は確認なしで実行されます）。そのため、意図せずplanのまま作業しようとして「編集ツールが使えない」と感じるケースが少なくありません。
体系的な問題切り分けフロー
/doctorで問題が特定できない場合や、より詳細な調査が必要な場合の進め方を整理します。ポイントは、いきなり細部を疑うのではなく、まず/doctorで全体像をつかんでからカテゴリを絞り込むという順序です。
全体診断とカテゴリの特定
まず/doctorを実行し、指摘された項目があればそこから対処します。症状の言葉から、次のようにカテゴリを見分けられます。
| 症状 | カテゴリ | 次に確認すること |
|---|---|---|
| 「認証エラー」系のメッセージ | 認証 | ログイン状態とAPIキー |
| 「接続できない」「タイムアウト」 | ネットワーク | DNS・プロキシ・証明書 |
| 「設定が読み込めない」 | 設定ファイル | JSON構文とパス |
| 「ツールが使えない」 | パーミッション | モードとpermissions.allow/permissions.deny |
| 「レスポンスが遅い」「途中で止まる」 | パフォーマンス | コンテキストサイズとMCPの応答速度 |
認証・ネットワークの詳細診断
認証系の症状であれば、次のコマンドで詳細を確認します。
# ログイン状態の確認
claude auth status
# 再認証
claude auth logout
claude auth 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-5","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'ネットワーク系であれば、DNS・TCP接続・SSL証明書・プロキシ経由の順に切り分けます。
# DNS解決の確認
nslookup api.anthropic.com
# 接続の確認（TCPレベル）
nc -zv api.anthropic.com 443
# SSL証明書の確認
openssl s_client -connect api.anthropic.com:443 -brief
# プロキシ経由の接続テスト
curl -v --proxy $HTTPS_PROXY https://api.anthropic.com設定ファイル・パーミッションの詳細診断
設定ファイル系の症状では、ユーザー設定とプロジェクト設定の両方を確認します。
# ユーザー設定
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パーミッション系の症状では、現在のモードとpermissions.allow・permissions.denyの中身を直接確認するのが早道です。
# 現在のモードと許可ルールを確認（セッション中）
/permissions設定ファイル側は、permissionsの内容を直接確認します。
# プロジェクト設定のpermissionsを確認
python3 -c "
import json
config = json.load(open('.claude/settings.json'))
perms = config.get('permissions', {})
print('Mode:', perms.get('defaultMode', '未設定'))
print('Allow:', perms.get('allow', []))
print('Deny:', perms.get('deny', []))
"ここで表示されるModeは、このファイルに保存されたpermissions.defaultModeの値であり、いま動いているセッションの実効モードではありません。起動時のモードは--permission-modeフラグ、各設定ファイルのpermissions.defaultMode（優先順位に従う）、組み込みの既定の順で決まり、セッション中にShift+Tabで切り替えることもできます。実際のモードは、ターミナルではプロンプト下のステータスバー（⏸ plan mode onなど）で確認してください。
パフォーマンスの調査
レスポンスが遅い、または途中で止まる場合は、次の3点を確認します。
- コンテキストサイズ: 大量のファイルを読み込んでいないか、
CLAUDE.mdや参照ファイルが肥大化していないか - MCPサーバーの応答速度: 外部サービスのレスポンスが遅くなっていないか
- ネットワーク帯域: 回線速度が十分か
ただし、パフォーマンスの問題は/doctor単体では原因を特定しきれないことが多く、コンテキストの持たせ方や利用しているMCPサーバーの構成そのものを見直す必要が出てくるケースもあります。コンテキストの状況は/context、使用量は/usageで確認できます。この点は/doctorの限界として率直にお伝えしておきます。
/doctor以外の診断コマンドと組み合わせ方
/doctorはセットアップの点検に役立つコマンドですが、これ一つで解決できない問題もあります。他のコマンドと組み合わせることで、より深い調査ができます。
関連コマンド一覧
| コマンド | 用途 |
|---|---|
/status |
バージョン・モデル・アカウント・接続状態の確認（設定画面のStatusタブ） |
/usage |
セッションのコスト・プランの使用量上限・利用状況の確認 |
/context |
現在のコンテキスト使用量の可視化と、肥大化している要素の確認 |
/config |
現在の設定値の一覧表示 |
claude --version |
Claude Codeのバージョン確認 |
claude update |
最新バージョンへのアップデート |
上の画面は、claude --helpを実行し、auth・--version・updateに関する説明行だけを抜き出した実出力です。バージョンが古い場合、既知の不具合が原因で問題が発生している可能性があるため、claude updateで最新版に更新してから改めて/doctorを実行することをおすすめします。
以下の画面は、claude --helpのauth・--version・update関連の出力です。
設定のリセットと再構築
設定ファイルの問題が解決しない場合、設定をリセットして再構築する方法があります。
# ユーザー設定のバックアップと削除
cp ~/.claude/settings.json ~/.claude/settings.json.bak
rm ~/.claude/settings.json
# Claude Codeを再起動
claude
# /doctorで確認
/doctorログの確認
Claude Codeのログファイルを確認すると、/doctorでは表示されない詳細なエラー情報を得られる場合があります。セッションごとのデバッグログは、--debug付きで起動するか/debugを実行するなどデバッグログを有効にしているときに~/.claude/debug/へ書き込まれます。以前の版にあった~/.claude/logs/は現行版では書き込まれない旧ディレクトリのため、確認先にはなりません（2026年10月時点の公式ドキュメントの記載です）。
# デバッグログを有効にして起動
claude --debug
# 別のターミナルで、ログディレクトリと最新のログを確認
ls ~/.claude/debug/
cat ~/.claude/debug/$(ls -t ~/.claude/debug/ | head -1)デバッグログには認証情報の断片やファイルパスが含まれる場合があるため、第三者に共有する前に内容を確認してください。
カスタムコマンドでの診断自動化
頻繁にトラブルシューティングが必要な環境では、カスタムコマンドとして診断スクリプトを定義しておくと、特定の担当者に頼らずチームの誰が実行しても同じ手順で診断できるようになります。個人の経験値に依存させず仕組みとして残しておく発想は、/doctorの運用でも有効です。
自社の運用に合わせた/doctor活用設計
/doctorは実行するたびに、その環境の状態をもとに診断結果が変わります。その結果をどう日々の運用に落とし込むかは、チーム構成や開発体制によって変わってきます。企業様によって最適な形は異なりますので、ここでは考え方の整理として3つの視点を紹介します。
定期実行をルール化するところから始める
いきなり全メンバーにCI組み込みまで求めるのではなく、まずは週1回など軽い頻度で/doctorを実行する習慣づけから始めることをおすすめします。運用が定着してきた段階で、コミット前に自動実行する仕組みへと段階的に広げていくとスムーズです。自動化の具体的な組み込み方は、Claude Code hooksで開発ワークフローを自動化する実践ガイドで解説しています。
設定ファイルとパーミッションは自社のルールに合わせて設計する
permissions.allow・permissions.deny・パーミッションモードの組み合わせは、セキュリティ要件が厳しい環境と、スピード重視で個人開発するような環境とでは最適な設計が異なります。企業のネットワークポリシーや扱うコードの機密度に応じて、/doctorの指摘のうちどこまでを許容し、どこから優先して直すかの基準をチームであらかじめ決めておくと、トラブル発生時の判断が速くなります。
診断結果の判断はAIではなく人が行う
/doctorは設定や拡張機能を点検して改善案を出す仕組みであり、出てきた提案のうちどれを優先し、どこまで手を打つかという判断は人が行うべき部分です。指摘があっても業務影響が小さければ後回しにする、といった優先順位づけは、現場の状況を知っている人の判断に委ねるのが適切だと考えています。修正の適用も、内容を確認してから承認する運用をおすすめします。
よくある質問
Q1. /doctorコマンドはオフラインでも実行できますか？
部分的に実行できます。claude doctorによるインストールや設定ファイルの診断など、ローカル環境の確認はオフラインでも動作します。一方、セッション中の/doctorはClaudeが診断を進める仕組みのため、モデルへの接続（インターネット接続）が必要です。認証の有効性やネットワーク接続の確認は、claude auth statusやcurlなど、前述のコマンドで個別に行ってください。
Q2. /doctorで問題が見つからないのにClaude Codeが正常に動作しません。どうすればよいですか？
/doctorのチェック項目は主要なセットアップ上の問題をカバーしていますが、すべてのエラーを検出できるわけではありません。次のステップとして、claude updateで最新版にアップデート、claude auth logoutとclaude auth loginで認証をリセット、設定ファイルのバックアップ後に削除して再構築、の順で試してください。それでも解決しない場合は、Anthropicのサポートページで既知の問題を確認することをおすすめします。
Q3. MCPサーバーの接続エラーが頻発します。安定化するにはどうすればよいですか？
MCPサーバーの接続安定性は、サーバー側の実装とネットワーク環境に依存します。サーバーの起動や接続の待ちで失敗する場合は、環境変数MCP_TIMEOUT（ミリ秒）で起動待ちの時間を延ばせます。2026年10月時点の公式ドキュメントでは既定値が30000（30秒）なので、延ばすときはそれより大きい値を指定します（例：MCP_TIMEOUT=60000 claudeで60秒）。既定より小さい値にすると、かえって待ち時間が短くなり失敗しやすくなります。設定ファイルのtimeoutは個々のツール呼び出しの実行時間に対する上限であり、接続や起動の待ちを延ばす設定ではない点に注意してください。また、MCPサーバーが外部API（Slack、HubSpotなど）に依存している場合、そのAPIのレートリミットや接続制限に引っかかっている可能性もあります。どのMCPサーバーが失敗しているかはclaude mcp listやclaude mcp get <サーバー名>、セッション中の/mcpで確認し、そのサーバーの設定を個別に調査することをおすすめします。
Q4. チームで/doctorの運用ルールを作る際、何から決めればよいですか？
まずは問題が見つかったときの一次対応者を決め、認証・ネットワーク・設定ファイルのどれに該当するかをチームで共通言語化しておくと動きやすくなります。その上で、定期実行の頻度やpermissions.allow・permissions.denyの基準を決めていくと、特定の詳しいメンバーだけに頼らない運用に近づきます。
まとめ
/doctorは、Claude Codeのトラブルシューティングにおける最初の一手であり、インストール・設定・拡張機能・CLAUDE.md・権限の状態を点検して、直せるものは確認のうえで修正まで進めてくれるコマンドです。見つかった問題の中から優先度の高いものを対処し、それでも解決しない場合は認証・ネットワーク・設定ファイル・パーミッションのどのカテゴリかを見極めて詳細診断に進む、という順序を押さえておくと、原因の切り分けにかかる時間を大きく減らせます。
最初の一歩として、まずは/doctorを実行する習慣を自分の中に作ることから始めてみてください。そのうえで、次の3ステップで運用を広げていくことをおすすめします。
- トラブルが起きたら、まず
/doctorを実行して全体像を確認する - 問題が見つかった項目から、本記事の該当セクションの手順で切り分ける
- 解決しない場合は、認証の再ログイン・設定ファイル再構築・デバッグログ確認の順で詳細調査に進む
Claude Codeの全コマンド一覧はClaude Codeチートシートをご覧ください。AI活用の全体像はAI活用完全ガイドで解説しています。
CRMを活用した業務効率化やAIとの連携に関するご相談は、CRM特化型コンサルティングのHubSpotゴールドパートナーのStartLinkまでお気軽にお問い合わせください。
あわせて読みたい
記事の内容を、そのまま実務に落とし込みたい方向け
HubSpotゴールドパートナーのStartLinkが、HubSpot導入・AI活用・CRM整備・業務効率化までをまとめて支援しています。記事で気になったテーマを、そのまま相談ベースで整理できます。
次に読む
株式会社StartLinkは、事業推進に関わる「販売促進」「DXによる業務効率化（ERP/CRM/SFA/MAの導入）」などのご相談を受け付けております。 サービスのプランについてのご相談/お見積もり依頼や、ノウハウのお問い合わせについては、無料のお問い合わせページより、お気軽にご連絡くださいませ。
著者情報
