作業用の隔離環境で Claude Code の状態を確かめようと claude doctor を打ったところ、最後の行に「4 warnings found」と出ました。
数字を見た瞬間、胃のあたりが少し重くなりました。4 つも壊れているのなら、更新も認証も怪しいのではないか、と身構えたのです。
けれども、結論から先にお伝えすると、この 4 つの警告は 原因が 1 つ でした。順番に直していたら、同じ作業を 3 回やるところでした。
そのとき実際に出た出力を材料に、警告を「直す前に仕分ける」やり方を書き残します。いま思えば、数字の大きさに気を取られて、文言そのものをまだ読んでいなかったのだと思います。
実際に出た出力を、先に並べます
claude doctor は読み取り専用の診断コマンドで、セッションを始めずにインストールと設定の状態を表示してくれます。私の環境では、要点が次のように出ました。
Running: native (2.1.309)
Path: /usr/local/bin/claude
Config install method: not set
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
4 warnings found
- Native installation exists but ~/.local/bin is not in your PATH
- Running native installation but config install method is 'not set'
- claude command at $HOME/.local/bin/claude missing or broken
- claude command at $HOME/.local/bin/claude missing or broken警告の 3 番目と 4 番目は、パスもメッセージも同じです。同じ指摘が 2 回並んでいるだけで、数字の「4」は実質 3 件分に水増しされていました。
もう一つ、警告ではない行にも目が止まりました。「Organization policy」や「Remote Control」の欄は、サインインしていない状態だと「取得できませんでした」と並びます。これは壊れているのではなく、まだ名乗っていないだけです。警告の件数にも数えられていませんでした。
4 つを「原因」でグループに分けます
仕分けは、表を一枚書くだけで終わります。
| 出た文言 | 言っていること | 原因のグループ |
|---|---|---|
| ~/.local/bin が PATH にない | ネイティブ版の置き場が、シェルの検索経路に入っていない | A: 起動経路 |
| claude command at …/.local/bin/claude missing or broken（1 回目） | その置き場に起動用ファイルがない | A: 起動経路 |
| 同上（2 回目） | 1 回目の重複 | A: 起動経路 |
| config install method is 'not set' | 設定側に、どの方法で入れたかの記録がない | B: 設定の記録 |
グループは A と B の 2 つになりました。さらに言えば、A の「置き場に起動用ファイルがない」と「置き場が PATH にない」は、同じ置き場の話です。公式の手順どおりに入れれば、起動用ファイルは ~/.local/bin/claude に置かれ、~/.local/share/claude/versions/ 配下の実体を指します。その置き場が欠けているから、二つの文言が同時に出ていたのです。
「今、動いているか」で重さが変わります
警告の数より先に確かめたのは、動いているかどうかでした。
claude --version は問題なく版番号を返しました。claude update も「Current version: 2.1.309」と表示して更新確認まで進み、そこでも同じ PATH の警告が付いてきました。
動いていて、更新の確認も走り、Auto-updates は enabled のままです。つまり、いま困っているのではなく、次に困る可能性がある状態 でした。
ここで線を引きました。動いている間は急がず、動かなくなる前に起動経路を 1 本に揃えます。 警告が出た日にやるのは、その準備だけにしています。
逆に、claude と打って「command not found」になる場合は、話が変わります。その場合は公式の「Fix your PATH」の節に進んでいただくのが先です。
直す手順は短く、3 つだけです
A のグループは、doctor が示した文のとおりに進めます。
- 起動経路を直します。シェルの設定ファイルに次の 1 行を足します（zsh なら
~/.zshrc）。
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc-
新しいターミナルを開きます。
source ~/.zshrcでも構いません。 -
claude doctorをもう一度打ちます。
B のグループ（config install method が 'not set'）には、claude install が案内されていました。この記事を書いた時点で、私は まだ claude install を実行していません。起動用ファイルを作り直す操作で、いまの動いている経路を置き換える可能性があるからです。実行したあとの結果は、書けるようになってから書き足します。
直したあとの確認で、見る場所は 3 つです
警告が消えたかどうかに加えて、次の 3 か所を見ます。
Path:の行が、意図した場所を指しているかを見ますAuto-updatesとAuto-update channelが、自分の選んだ値のままかを見ますLast update attemptに失敗の記録がないかを見ます
なお、which -a claude で複数の claude が見つかる場合は、別の入れ方が重なっています。公式の「Check for conflicting installations」の節に沿って、どれか 1 本に絞ってください。起動経路が 2 本あると、更新が片方にだけ効いて、もう片方が古いまま残ります。
警告が 1 行だけのときも、同じ見方ができます
今回は 4 行でしたが、1 行だけ出たときも手順は変わりません。その 1 行が「動かなくなる」話なのか、「次に困るかもしれない」話なのか、あるいは「サインイン前だから空欄なだけ」の話なのかを、先に決めます。
壁紙アプリのリリース作業のように、ビルドや公開を何度も繰り返す個人開発では、道具の状態が前触れなく変わっていることがあります。作業の前に claude doctor を一度打ち、版番号・Path:・更新の記録の 3 行だけ見ておく。そのくらいの軽さが、続けやすいのだと感じています。
直す前の 30 秒を、習慣にします
今回の学びは、警告の数と問題の数は別物だった、という一点です。
- 同じ文言の重複を畳みます
- サインイン前の情報行を、警告と区別します
- グループごとに「動いているか」を確かめます
この 3 つを済ませてから手を動かすと、修正は 2〜3 手で終わります。数字に押されて 4 回直していたら、どこで効いたのかさえ分からなくなっていたと思います。
まずは今日、手元の claude doctor の出力を貼り出して、原因ごとに色を分けてみていただければと思います。私はそこから始めました。