Claude Codeでよくあるエラーとつまずきを、インストール・認証・権限・コンテキスト超過などのタイプ別に整理。/doctor や --safe-mode での切り分け、/compact や /clear での文脈対処まで、非エンジニア目線で手順化。最新は公式ドキュメントで確認する前提でまとめました。
Claude Codeのエラーは「インストール／認証」「設定・MCPが効かない」「動作が重い」「コンテキスト超過」の4タイプに分けると対処が早いです。困ったらまず /doctor で診断、原因を切り分けたいときは claude --safe-mode でカスタマイズを全無効化して起動する——この2つが起点になります。
仕様やページ構成は更新が早いので、個別のエラー詳細は必ず公式ドキュメントで最新を確認してください。
Claude Codeは便利ですが、最初のうちは「起動できない」「ログインが通らない」「なんか重い」といったつまずきに必ずぶつかります。私も何度も止まりました。ただ、エラーはタイプ分けすると対処が一気にシンプルになります。この記事では、よくあるつまずきをタイプ別に整理し、非エンジニア目線で「まず何を打つか」を手順にしました。
実体験メモ
私は非プログラマーですが、Claude CodeでWebサイトや自分用のツールを実際に作ってきました。正直、エラーの多くは「原因を特定できないこと」がいちばんの壁でした。慣れてからは、まず /doctor で状態を見て、それでも変なら claude --safe-mode で自分の設定をいったん外して起動する——この順番に固定したら、切り分けがぐっと楽になりました。あと、作業が噛み合わなくなったら /clear、重くなったら /compact。エラーメッセージそのものをClaudeに貼って「これ直して」と頼むのも、地味に効きます。
まず試す2つ（診断と切り分け）
個別の対処に入る前に、ほぼ全部のつまずきで起点になる2つを覚えておくと迷いません。
/doctor… セットアップを診断します。そもそも起動できない・コマンドが立ち上がらないときは、シェルでclaude doctorと打ちます。claude --safe-mode… CLAUDE.mdやhooks、MCPなどすべてのカスタマイズを無効にして起動します。これで直るなら、原因は自分のカスタマイズ側にある、と切り分けられます。
「まず診断、次に切り分け」。この2手で、原因がツール本体側か、自分の設定側かの当たりが付きます。
つまずき別の対処一覧
よくあるエラーを4タイプに整理しました。下表は公式ドキュメントで確認した内容をもとにしていますが、ページ構成やコマンドは変わるため、最新は公式で確認してください。
| タイプ | 症状の例 | まず試すこと |
|---|---|---|
| インストール・認証 | 起動しない／ログインループ／OAuthエラー／403 | /doctor（起動不可なら claude doctor）、/login、公式のTroubleshootページ |
| 設定・MCPが効かない | hooks・MCP・設定が反映されない | /mcp で状態確認、claude --safe-mode で切り分け |
| 動作が重い | 高CPU・高メモリ、もたつき | /compact、タスク間で再起動、大きなビルドを .gitignore |
| コンテキスト超過 | 圧縮の警告、話が噛み合わない、thrashing | /compact、/clear、分割読み、サブエージェントに逃がす |
このほか、4タイプに並ぶ頻出の「詰まりどころ」として権限・承認まわりがあります。これはエラーというより仕様の理解不足で起きやすいので、後述の権限セクションで別立てにしました。
インストール・認証でつまずいたとき
いちばん最初に当たりやすいのがここです。
- 起動しない・セットアップが不安 → まず
/doctorで診断します。そもそもClaude Codeが立ち上がらず/doctorすら打てない場合は、シェルでclaude doctorと打ってください。 - ログインループ・OAuthエラー・403 → 公式の「Troubleshoot installation and login」ページに手順があります。セッション内での再認証やアカウント切替は
/loginです。 - 認証の基本 →
claudeを実行すると、初回はブラウザでログインを促されます。ここが通らないときは、上記のTroubleshootページを確認するのが確実です。
なお、インストール方法自体は現在ネイティブインストーラが推奨に変わっています。macOS/Linux/WSLは curl -fsSL https://claude.ai/install.sh | bash、Windows PowerShellは irm https://claude.ai/install.ps1 | iex、Homebrewは brew install --cask claude-code などです。WindowsはWSLなしのネイティブ対応が正式化されており、「Windowsだから必ずWSLが要る」という古い情報でつまずかないよう注意してください。
注意：npm版（
@anthropic-ai/claude-code）も存在しますが、Node.js 22以上が必要で、自動更新が効くのはネイティブ版のみです。「古いバージョンのまま動いていて最近の記事と挙動が違う」というつまずきは、npm版を放置しているケースで起きやすいので、迷ったらネイティブインストーラで入れ直すのが確実です。最新の手順は公式のsetupページで確認してください。
始め方をひととおり確認したい場合は Claude Codeの始め方 にまとめています。
設定・hooks・MCPが効かないとき
「設定したはずなのに反映されない」というつまずきです。
/mcpで状態を見る … MCPサーバーの接続状態、OAuth、有効／無効を確認できます。そもそも繋がっていない、認証が切れている、といったことが分かります。claude --safe-modeで切り分ける … CLAUDE.md・hooks・MCPなど全カスタマイズを無効化して起動します。これで症状が消えるなら、原因は自分のカスタマイズ側です。あとは怪しい設定を1つずつ戻していけば、犯人が特定できます。- 公式の「Debug your configuration」を見る … 設定回りの詳しい切り分けはこのページに手順があります。
MCPの追加・管理そのもので迷っている場合は Claude CodeのMCP設定と活用、CLAUDE.mdの書き方は Claude CodeのCLAUDE.md を参照してください。設定は「近い（作業ディレクトリに近い）ほど後に読まれる」など読み込みの順序に癖があるので、意図しない上書きが起きていないかも確認ポイントです。
権限・承認まわりでつまずいたとき
「承認ダイアログが出続ける」「自動にしたのに聞かれる」「起動を拒否された」——このあたりはエラーではなく仕様であることがほとんどです。
まず前提として、Claude Codeの権限モードは default(Manual)／acceptEdits／plan／auto／dontAsk／bypassPermissions の6種があります。セッション中に Shift+Tab で循環できるのは基本の default→acceptEdits→plan の3つで、autoは条件を満たすと循環に加わり、bypassPermissionsは起動フラグ指定時のみ、dontAskはフラグでのみ指定します。
- 編集のたびに毎回確認される → 標準（default）の挙動です。編集を自動承認したいなら acceptEdits などへ切り替えます。まず計画だけ立てさせたいときは plan（読み取り専用で計画→承認後に実行）が安全です。
- 自動承認のモードなのに確認が入る →
.gitや.claude、.vscodeなどの保護されたパスは自動承認されない仕様です。バグではありません。認証情報や設定を壊さないためのガードなので、内容を見て個別に承認します。 - bypassPermissions で起動できない・拒否される → bypassPermissions は隔離された環境（コンテナ等）専用の設計で、root／sudoでの起動は拒否されます。通常のPCで「全部自動にしたいから」と使うモードではありません。日常用途は acceptEdits や auto までにとどめるのが安全です。
権限を「ゆるくして通す」のではなく、モードの役割を知って使い分けるのが正解です。詳細は公式の権限（permissions）関連ページを確認してください。
動作が重い・CPUやメモリを食うとき
長い作業を続けると、もたつきや高負荷が出ることがあります。
/compactで文脈を縮小 … 会話を要約して軽くします。まずこれを試すのが基本です。- タスクの区切りで再起動 … 大きな作業が一段落したら、いったん立ち上げ直すと安定します。
- 大きなビルドディレクトリを
.gitignore… 巨大な生成物を対象から外すと負荷が下がります。 claude --safe-mode… 重さがカスタマイズ由来か切り分けたいときに有効です。- ハングしたら
Ctrl+C… いったん止めて、claude --resumeで会話を失わず再開できます。
「重い＝故障」ではなく、文脈やファイルが膨らんだサインと捉えると対処しやすいです。
コンテキスト超過・圧縮の警告が出たとき
非エンジニアがいちばん戸惑いやすいのがここかもしれません。「圧縮」や「文脈」の警告は、多くの場合エラーではありません。
- 圧縮の警告 … 使用量の上限に達したのではなく、会話がモデルの最大入力に近づき、古い履歴を自動で要約している状態です。慌てなくて大丈夫です。
- auto-compactのthrashing（何度も再圧縮が走る） … 大きなファイルが文脈を再び埋めてしまうのが原因です。対処は「ファイルを分割して読む」「
/compactで対象を絞る」「サブエージェントに逃がす」「思い切って/clear」。 - 話が噛み合わなくなった … 話題を切り替えるなら
/clearでリセットするのが早いです。
今どれくらい文脈を使っているかは /context で可視化できます。大量出力を伴う調査やログ処理は、独立した文脈を持つサブエージェントに任せて要約だけ受け取ると、本会話が圧迫されません。この考え方は Claude Codeのサブエージェントで自動化 にまとめています。
その他の細かいつまずき
- 検索（コード検索）が効かない … 内蔵のripgrepが動かない場合、OS側のripgrepを入れて
USE_BUILTIN_RIPGREP=0を指定する方法が公式に案内されています。 - エラーメッセージをそのまま貼る … 原因が分からないエラーは、メッセージ本文をClaude Codeに貼って「これを直して」と頼むと、原因追跡と修正案を出してくれます。これは公式にも用途として挙げられている使い方です。頼み方があいまいで迷走しがちな人は、無料の AIプロンプトビルダー で「目的・状況・してほしいこと」を先に整理してから貼ると切り分けが速くなります。
- スラッシュコマンドが効かない … コマンドはメッセージの先頭でのみ認識されます。文の途中に書いても効きません（コマンド一覧の解説）。
公式ドキュメントの確認先（ドメインに注意）
エラー対処は仕様変更の影響を受けやすい領域です。個別の詳細は必ず公式で最新を確認してください。
- 公式ドキュメント（入口）：https://code.claude.com/docs/en/overview
- 公式ドキュメントのドメインは
docs.claude.comからcode.claude.com/docs/en/*へ移転済みです（旧URLは新ドメインへリダイレクト）。「Troubleshoot installation and login」「Debug your configuration」などのページはここから辿れます。ブックマークやメモが古いドメインのままの人は更新しておくと迷いません。
料金の疑問（/usage・/cost の見え方など）は Claude Codeの料金 に切り出しています。Pro/Maxのドル表示は目安で、実際の請求とは直結しない点だけ先にお伝えしておきます（正確な料金・上限は claude.com/pricing と公式で確認を）。
まとめ
- エラーはインストール・認証／設定・MCP／動作が重い／コンテキスト超過の4タイプで整理すると対処が早い。
- 起点は2つ。まず
/doctorで診断、次にclaude --safe-modeで切り分け。 - 権限・承認の「詰まり」は多くが仕様。保護パス（.git/.claude/.vscode等）は自動承認されず、bypassPermissionsはroot/sudo起動を拒否する隔離環境専用。基本3モード（default/acceptEdits/plan）はShift+Tabで切替。
- コンテキストの警告は多くがエラーではなく要約中のサイン。
/compact・/clear・分割読み・サブエージェントで対処。 - 仕様・ページは更新が早いので、最新は公式ドキュメントで確認する（https://code.claude.com/docs/en/overview）。
そもそもClaude Codeって何？という方は Claude Codeとは？、始め方は Claude Codeの始め方 をどうぞ。
関連記事：Claude Codeの始め方 / Claude Codeのコマンド完全ガイド / Claude CodeのMCP設定と活用 / Claude Codeのサブエージェントで自動化。カテゴリ一覧は AI活用・ノウハウ へ。
よくある質問（FAQ）
Claude Codeが起動しない・ログインできないときは？
まず切り分けが先です。セットアップ診断は /doctor（起動できない場合はシェルで claude doctor）を使い、ログインループやOAuthエラーは公式の「Troubleshoot installation and login」ページを確認します。セッション内での再ログイン・アカウント切替は /login です。詳しい手順は公式ドキュメントを参照してください。
設定やMCPが効いていない気がするときの調べ方は？
/mcp で接続状態やOAuth、有効・無効を確認します。設定・hooks・MCPが原因か切り分けたいときは claude --safe-mode で全カスタマイズを無効にして起動し、それで直るならカスタマイズ側が原因、と判断できます。公式の「Debug your configuration」も参考になります。
会話が長くなって「圧縮」の警告や動作が重いのはエラーですか？
多くの場合エラーではなく、会話がモデルの最大入力に近づき古い履歴を要約している状態です。対処は /compact で文脈を圧縮、話題を切り替えるなら /clear、大きなファイルは分割読みやサブエージェントに逃がすのが有効です。今の使用量は /context で確認できます。
動作が重い・CPUやメモリを食うときは？
/compact で文脈を縮小し、タスクの区切りで再起動するのが基本です。大きなビルドディレクトリは .gitignore で除外し、原因の切り分けには claude --safe-mode が使えます。ハングしたときは Ctrl+C で止め、claude --resume で会話を失わず再開できます。
自動承認モードにしたのに毎回確認される・bypassPermissionsで起動できないのはバグですか？
どちらも仕様です。.git や .claude、.vscode などの保護されたパスへの変更は、自動承認系のモードでも承認が自動化されず確認が入ります。またbypassPermissionsは隔離された環境専用の設計で、root（sudo）で起動しようとすると拒否されます。権限モードは6種ありますが、Shift+Tabで循環できるのは基本のdefault→acceptEdits→planで、bypassPermissionsは起動フラグ指定時のみ、dontAskはフラグ専用です。