本文へ移動
ハック！でAI
投稿する

Claude Code 入門 第12回

Claude Code がうまく動かないときの対処

ハック！でAI編集部AIにより執筆読了 約9分
Claude Code に「こんにちは」と送ると API Error: 400 と表示されたターミナルの画面

この記事でわかること

  • 「command not found」と出たときの直し方
  • API エラーなど、よく出るメッセージの意味と対処
  • claude doctor と /doctor の使い分け

確認した環境: Claude Code 2.1.296 / 撮影は Linux のターミナル / 2026年10月11日に確認

Claude Code が起動しないときや、エラーが出て答えが返ってこないときに確かめることを、症状ごとにまとめました。編集部の検証環境で実際に出た画面を使って説明します。

まず、どこで止まっているかを見分ける

起動できないときは claude doctor、起動できるときは /doctor、エラーが出たらメッセージを読む、反応しないときは Ctrl+C と claude --resume、という 4 つの区画の図
困ったときの調べ方。Claude Code が起動できるかどうかで、使うコマンドが変わる撮影・作図: 編集部

公式のドキュメントでは、困ったときの順番として、Claude Code が起動できるなら中で /doctor、起動しないならターミナルで claude doctor を使うよう案内しています。MCP(外部のサービスとつなぐ仕組み)の問題は /mcp で確かめます。

「command not found」と出る

claude と入力して command not found(Windows では 'claude' is not recognized)と出るときは、Claude Code のインストール先が PATH(コマンドを探しに行く場所の一覧)に入っていません。

1 回目の claude --version は command not found、PATH に追加するコマンドを実行したあとは 2.1.296 (Claude Code) と表示されている
PATH を直す前と後。① command not found と出る ② インストールのときに案内されたコマンドで PATH に追加 ③ 版の番号が表示された撮影・作図: 編集部

  1. インストール先を PATH に追加する

    Mac・Linux のインストール先は ~/.local/bin です。インストールのときに表示された案内のコマンドを、そのまま実行します。編集部の環境(bash)では、次のコマンドでした。

    ターミナル
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

    Windows のインストール先は %USERPROFILE%\.local\bin です。この場所を、環境変数の PATH に追加します。

  2. 新しいターミナルを開いて確かめる

    ターミナル
    claude --version

    版の番号のあとに (Claude Code) と出れば直っています。

インストールの手順は、第 2 回のClaude Code をインストールするで説明しています。

インストールのときに出る、ほかのエラー
画面のメッセージ 原因と対処
syntax error near unexpected token '<'、curl: (22) The requested URL returned error: 403 インストール用のスクリプトの代わりに、Web ページ(HTML)が返ってきています。社内のプロキシや地域の制限などが原因です。社内のプロキシを使う場合は、HTTP_PROXY・HTTPS_PROXY を設定してから実行します
The token '&&' is not a valid statement separator PowerShell で、コマンドプロンプト(CMD)用のコマンドを実行しています
'irm' is not recognized コマンドプロンプト(CMD)で、PowerShell 用のコマンドを実行しています
Killed(Linux) メモリが足りず、インストールが強制終了されました。メモリを空けるか、スワップを追加します
App unavailable in region Claude Code に対応していない国から使おうとしています

ダウンロード先に接続できるかは、次のコマンドで確認できます。

ターミナル
curl -sI https://downloads.claude.ai/claude-code-releases/latest

診断する: claude doctor と /doctor

診断のコマンドは 2 つあります。

claude doctor /doctor
実行する場所 ターミナル(Claude Code を起動しないで使う) Claude Code の中
できること 読み取りだけで調べる。設定は変えない 調べたうえで修正案を出し、確認してから修正する
調べる項目 インストールの状態、設定ファイルの誤り、最後の更新の結果など インストール・設定・拡張機能・CLAUDE.md など

ターミナルで claude doctor

ターミナル
claude doctor
Remote Control の項目に使えない理由が並び、その下に No installation issues found. と、/doctor を案内する文が表示されている
claude doctor の結果(後半)。① Remote Control の機能についての確認の結果 ② インストールに問題は見つからなかった ③ 修正まで行うなら /doctor を使う、という案内撮影・作図: 編集部

①は、Remote Control(スマートフォンの Claude アプリなどから、手元の Claude Code を操作する機能)についての表示です。画面のとおり、この機能には claude.ai のプランが必要です。編集部の環境は API キーで使っているため、使えない理由が並んでいます。インストールに問題がなければ、②の「No installation issues found.」が出ます。

Claude Code の中で /doctor

  1. /doctor と入力して送る

    読み取りだけで各項目を調べるところから始まります。

    /doctor と入力したあと、まず読み取りだけで各項目を調べます、という説明が表示されている
    /doctor を実行したところ。① 入力したコマンド ② まず読み取りだけで調べる、という説明撮影・作図: 編集部

  2. 修正案ごとに、修正するかどうかを選ぶ

    調べ終わると、結果の報告のあとに、修正案ごとに質問が表示されます。編集部の環境では「整理」(CLAUDE.md の整理)と「権限」の 2 つの修正案が出ました。

    整理・権限・Submit のタブが並び、CLAUDE.md の 2 つの節を削るかどうかの質問と、整理する(おすすめ)・そのままにする の選択肢が出ている
    修正案の確認。① 修正案ごとのタブ(整理・権限)と、送信する Submit ② 修正案の説明 ③ 選択肢撮影・作図: 編集部

    矢印のキーで選び、Enter で決めます。Tab か矢印のキーで次の修正案へ移り、最後の「Submit」で送ります。やめるときは Esc を押します。公式の説明では、修正案は確認のあとに適用されます。

/doctor は /checkup と入力しても動きます。

API エラーが出る

送ったのに、答えのかわりに「API Error:」と出ることがあります。

こんにちは と送ったあとに、API Error: 400 This API key is not scoped to a workspace という黄色のエラーが表示されている
API エラーの例。① 使っている支払いの方法(API Usage Billing は API の利用料で払う方法) ② 送った文 ③ エラーのメッセージ撮影・作図: 編集部

「API Error:」のあとに、数字(この例では 400)と、理由が英語で書かれています。この例は「この API キーはワークスペースに割り当てられていない」というエラーで、直し方として、ワークスペースに割り当てられた API キーを使うことが書かれています。

まず /status で、どのアカウント・どの方法でログインしているかを確かめます(版・モデル・アカウントなどが表示されます)。よく出るメッセージと、公式のドキュメントに書かれた対処は次のとおりです。

画面のメッセージ 意味 対処
Not logged in · Please run /login ログインしていない /login でログインする
Invalid API key · Fix external API key API キーが正しくない、または使えなくなっている キーを確かめる。.env などから古いキーが読み込まれていないか確かめる。プランで使うなら、API キーの設定を解除して /login
API Error: 403 Request not allowed 使う権限がない Pro・Max は契約が有効かを確かめる。Claude Console は「Claude Code」か「Developer」の役割(ロール)が必要。社内のプロキシの設定も確認する
This organization has been disabled プランで契約しているのに、古い API キーが使われている unset ANTHROPIC_API_KEY で解除し、~/.zshrc などからも削除する。/status で確かめる
API Error: Repeated 529 Overloaded errors API 側が一時的に混み合っている(自分の使用量の上限ではない) 少し待つ。Claude の稼働状況のページを見る。/model で別のモデルにする
You've hit your session limit 使用量の上限に達した リセットの時刻まで待つ。/usage で使用量を確かめる。上位のプランや、API の料金で続ける usage credits(/usage-credits)もある
Context limit reached · /compact or /clear to continue 会話が長くなり、扱える量の上限に達した /compact(会話を要約する)か /clear(新しい会話を始める)

反応しない・重い

  • 反応しない: Ctrl+C で中断します。それでも動かないときは、ターミナルを閉じて、同じフォルダで claude --resume を実行します。会話は消えていません。
  • 重い・メモリを多く使う: こまめに /compact で会話を要約し、大きな作業の区切りで再起動します。
  • 原因が分からない: claude --safe-mode で起動すると、自分で追加した設定(カスタマイズ)をすべて無効にした状態で動かせます。これで直るなら、追加した設定のどれかが原因です。
WSL を使っているとき

WSL(Windows の中で Linux を動かす仕組み)で、検索の結果が少ないときは、プロジェクトを /mnt/c/ の下ではなく、Linux 側(/home/ の下)に置きます。

それでも直らないとき

  • 不具合は、Claude Code の中で /feedback(/bug も同じ)を使って報告するか、GitHub の Issuesに書きます。
  • アカウントや請求の問題は、claude.ai(Claude Console を使っている人は platform.claude.com)の Get help から問い合わせます。

Claude Code を安全に使うための設定は、AI コーディングの道具を安全に使うでまとめています。

参考にした公式の情報

XFacebookはてブLINE

この記事は、ハック！でAI編集部が AI を使って執筆しました。画面の画像は、編集部の検証環境で実際に操作して撮影したものです(引用の画像は出典を記載しています)。内容の誤りはお問い合わせからお知らせください。

連載

Claude Code 入門
前の回(第11回)画面の画像を渡して Claude Code に直してもらう
全 12 回の目次
  1. 1Claude Code とは？ できること・使える場所・料金
  2. 2Claude Code をインストールする(Mac・Windows・Linux)
  3. 3Claude Code を初めて起動する(テーマ・ログイン・フォルダの信頼)
  4. 4Claude Code に最初の質問をする(@ でファイルを指定)
  5. 5Claude Code にファイルを直してもらう(変更の確認と許可)
  6. 6権限モードを使い分ける(auto・manual・accept edits・plan)
  7. 7CLAUDE.md でルールを覚えさせる(/init・/memory)
  8. 8よく使うコマンドとキー操作
  9. 9Git と組み合わせる(コミットを頼む・「!」でコマンド)
  10. 10Claude Code を VS Code で使う(拡張機能)
  11. 11画面の画像を渡して Claude Code に直してもらう
  12. 12Claude Code がうまく動かないときの対処(この記事)