claude doctorの警告は鵜呑みにしない、Fix行を実行する前の裏取り手順

はじめに

claude doctor は警告ごとに Fix: 行を添えてくれます。コマンドが書いてあるので、そのまま貼り付けて実行したくなるでしょう。しかし、その Fix は本当に手元の環境に合っているのでしょうか。診断ツールは「何が見えたか」を報告しますが、「なぜそうなっているか」までは確かめてくれません。

この記事では、Claude Code 2.1.300 の claude doctor が出した警告 3 件を、which -a・readlink・npm -g ls で 1 件ずつ裏取りします。結果として、3 件のうち 1 件は Fix 行どおりに実行すると claude コマンドが PATH から消える構成でした。

CLI の claude doctor が修正機能を持たないことや CI への組み込み方は、別記事「claude doctor CLI、3つの警告を出したのに1つも直せなかった」で扱っています。本記事は、出てきた警告をどう読み、どう確かめてから直すかに絞ります。

対象読者は、claude doctor で警告が出て、Fix 行を実行してよいか迷っている Claude Code 利用者です。npm とネイティブインストーラーの両方で入れた覚えがある人ほど当てはまります。

TL;DR

• claude doctor は読み取り専用のインストール診断で、警告が出ても終了コードは 0 です。2.1.300 では組織ポリシーや管理設定の読み込み状況も表示されます
• 警告の Fix: 行は「その場所に何があるか」から機械的に組み立てられており、実体（シンボリックリンクの向き先や PATH 上の順序）までは考慮していません
• 本環境では「npm グローバルの残骸」と判定された /opt/node22/bin/claude が、実はネイティブ版バイナリへのシンボリックリンクで、PATH 上で唯一の claude でした。Fix 行の npm -g uninstall を打つと、このリンクごと消える構成です
• Fix を打つ前に、公式トラブルシューティングガイドの順番（which -a claude → 3 か所の実体確認）で裏取りするのが安全です

2.1.300 の出力

2026-10-15 JST、Claude Code on the web のクラウドセッション（Linux コンテナ）で実行した生の出力です。

$ claude --version
2.1.300 (Claude Code)

$ claude doctor
Claude Code doctor

Running: native (2.1.300)
Commit: c6733ae12768
Platform: linux-x64
Path: /opt/claude-code/bin/claude
Config install method: unknown
Search: OK (/usr/bin/rg)
Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)
Auto-update channel: latest
Last update attempt: none recorded
Managed settings (remote): none configured for this organization
Organization policy: Loaded from api.anthropic.com

Remote Control
Inside a cloud session — Remote Control is unavailable here. Use it from the local session instead.

3 warnings found
- Running native installation but config install method is 'unknown'
  Fix: Run claude install to update configuration
- claude command at /root/.local/bin/claude missing or broken
  Fix: Run claude install to repair the installation.
- Leftover npm global installation at /opt/node22/bin/claude
  Fix: Run: npm -g uninstall @anthropic-ai/claude-code

For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.

同じコマンドの終了コード（$?）は 0 でした。警告の有無を終了コードで判定するスクリプトは書けないため、N warnings found の行を読む必要があります。

上の各行は、次の 3 層に分けて読むと整理しやすくなります。

層	該当行	読みどころ
実行中のバイナリ	Running / Commit / Path	いま動いているのがどの経路のどのバージョンか
設定と方針	Config install method / Auto-updates / Managed settings / Organization policy	自動更新が誰の設定で止まっているか、組織の方針が届いているか
警告	N warnings found 以下	パスの存在チェックから導かれた症状と Fix 案

この中で行動につながるのは 3 層目ですが、判断の根拠になるのは 1 層目の Path です。Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER) のように、止めている主体（ここでは環境変数）まで表示される点は、更新されない原因を探すときに役立ちます。

警告 3 件を裏取りする

公式の「Troubleshoot installation and login」は、重複インストールの確認手順として which -a claude で PATH 上の候補を列挙し、続いてネイティブ版（~/.local/bin/claude）・旧ローカル npm 版（~/.claude/local/）・npm グローバル版の 3 か所を見る順番を示しています¹。同じ順で確かめました。

$ which -a claude
/opt/node22/bin/claude

$ ls -la /root/.local/bin/claude /opt/node22/bin/claude
ls: cannot access '/root/.local/bin/claude': No such file or directory
lrwxrwxrwx 1 root root 27 Oct 15 14:34 /opt/node22/bin/claude -> /opt/claude-code/bin/claude

$ npm ls -g --depth=0
/opt/node22/lib
+-- @anthropic-ai/claude-code@2.1.42
...

npm ls -g の出力は、関係する 1 行以外を省略しています。

警告 2: /root/.local/bin/claude が無い

これは事実どおりでした。ファイルが存在しません。ただし、PATH には /root/.local/bin が /opt/node22/bin より前に入っているため、ここにネイティブ版のリンクが置かれれば以後はそちらが優先されます。Fix の claude install は --help によると「Install Claude Code native build」で、ネイティブ版を入れ直すコマンドです。

警告 3: npm グローバルの残骸

npm -g ls には確かに @anthropic-ai/claude-code@2.1.42 が残っています。パッケージの package.json は "bin": {"claude": "cli.js"} を宣言しているので、本来なら /opt/node22/bin/claude は npm 版の cli.js を指すはずです。

ところが実際のリンク先は /opt/claude-code/bin/claude、つまり doctor 自身が Path に表示したネイティブ版バイナリでした。環境構築の途中で、npm が作ったリンクがネイティブ版へ向け直されたと考えられます。パッケージの中身は 2.1.42 のまま残っていますが、実際に起動されるのは 2.1.300 です。

ここで Fix 行の npm -g uninstall @anthropic-ai/claude-code を実行すると、npm はパッケージが宣言した bin のリンク（/opt/node22/bin/claude）も削除します。which -a の結果から分かるとおり、このリンクは PATH 上で唯一の claude です。警告 2 を先に解消していない状態でこれを打つと、claude コマンドが見つからなくなります。本記事では破壊的な操作になるため実行はしていませんが、手順の順番を誤ると壊れる構成であることは上の出力から読み取れます。

警告 1: install method が unknown

ネイティブ版で動いているのに、設定上のインストール方法が記録されていないという指摘です。Fix は警告 2 と同じ claude install です。

3 件をまとめると

裏取りで分かった実体の関係を図にすると、次のとおりです。

3 件は独立した不具合ではありません。「ネイティブ版がネイティブインストーラーの経路を通らずに配置され、npm 版の入口だけが流用されている」という 1 つの構成から派生した症状です。公式ガイドが推奨する解消順に沿えば、claude install でネイティブ版の正規の入口（~/.local/bin/claude）を作り、which -a claude の先頭がそこに変わったことを確認してから npm uninstall -g を実行する、という並びになります¹。

doctor の警告は、存在チェックの結果を独立に並べる形式で出てきます。そのため、どの順で直せば安全かは読み手が判断するしかありません。

裏取りの手順（ローカル環境向け）

手元の macOS / Linux で警告が出たときは、次の順で確かめてから Fix を実行すると手戻りが減ります。

1. claude doctor の Path 行で、いま実際に動いているバイナリを確認する
2. which -a claude で PATH 上の候補と優先順を確認する
3. 候補ごとに ls -la でシンボリックリンクの向き先を確認する（Path と同じ実体を指していないか）
4. 消す予定の経路が、手順 2 の先頭（＝実際に使われている入口）でないことを確かめてから削除する

クラウドの使い捨てコンテナでは、セッションが終わればこの構成ごと破棄されるため、警告を放置しても実害はありません。手を入れる価値があるのは、同じマシンを使い続けるローカル環境です。

doctor が止まる・出力が出ないとき

公式ガイドによると、claude doctor と claude update はシェル設定ファイル（~/.zshrc・~/.bashrc など）を走査して古い claude エイリアスを探します。v2.1.214 より前は、これらのパスのどれかがディレクトリだと両コマンドが無出力のまま止まっていました¹。現在のバージョンではディレクトリを読み飛ばして完了します。古いバージョンで止まった場合は ls -ld ~/.zshrc ~/.bashrc などで d から始まる行を探し、そのディレクトリを退避するか、インストールスクリプトで更新します（claude update 自体が止まるため）。

セッション内 /doctor との分担

公式のコマンドリファレンスでは、セッション内の /doctor（別名 /checkup）はバンドルされたスキルとして扱われています²。スキル解説ページによると、点検範囲はインストールの健全性に加え、使っていないスキル・MCP サーバー・プラグインとその文脈コスト、遅いフック、重複した CLAUDE.md、auto mode を既定にする提案や読み取り専用コマンドの事前承認まで及び、変更前に必ず確認を求めます³。v2.1.283 以降は /doctor prompt-audit で、セットアップではなく指示ファイル（CLAUDE.md やスキル）の古い記述・矛盾を点検するモードも使えます³。

同じページは「セッションを起動せずに読み取り専用のインストール診断をしたいなら、ターミナルで claude doctor を実行する」と案内しています³。インストール経路の警告については、セッション内 /doctor に修正を任せる場合も、上の裏取り手順で出した結論と提案内容が一致しているかを見比べると判断しやすくなります。

まとめ

冒頭の問いに戻ると、claude doctor の Fix 行は「その場所に何があるか」から組み立てられた提案であり、手元の構成で安全かどうかは保証されていません。本環境では、3 件の警告が 1 つの構成から派生しており、そのうち npm -g uninstall は順番を誤ると claude を PATH から消す操作でした。

警告が出たら、まず Path 行と which -a claude の先頭が一致しているかを見てください。そこが一致していれば、残りの経路は安心して整理できます。

参考リンク

1. Troubleshoot installation and login - Claude Code Docs：重複インストールの確認手順（which -a claude と 3 か所の確認）、claude doctor が止まる問題と v2.1.214 での修正 ↩ ↩² ↩³

2. Commands - Claude Code Docs：/doctor [prompt-audit [path]] の説明（Skill・別名 /checkup・prompt-audit は v2.1.283 以降） ↩

3. Skills - Claude Code Docs：「Check your setup with /doctor」節。点検範囲と、読み取り専用診断としての claude doctor の位置づけ ↩ ↩² ↩³