Claude Code が起動しない？セットアップのつまずきポイント FAQ

Claude Code をインストール直後に「コマンドが見つからない」「API キーが認識されない」などのエラーが出る方へ。初心者がセットアップ時によくぶつかる7つの課題と、それぞれの具体的な解決方法をご説明します。

Q1: npm install で権限エラー（Permission Denied）が出る場合は？

原因

node_modules ディレクトリをインストールしようとしている権限がない、または npm グローバルパッケージのディレクトリ設定が不正です。

解決法

方法1：sudo を使わずに権限を修正（推奨）

# まず、現在の npm 設定を確認
npm config get prefix
# 出力例：/usr/local
 
# npm のディレクトリを修正
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
 
# PATH に追加（詳細は後述）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
 
# 再度インストール
npm install

方法2：権限を修正（Node.js が /usr/local にインストールされている場合）

# /usr/local ディレクトリの所有者を現在のユーザーに変更
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
 
# 再度インストール
npm install

方法3：sudo を使用（一時的な解決策のみ）

# 推奨されていませんが、急ぐ場合のみ
sudo npm install -g claude-code

:::warning sudo を使用して npm install すると、将来のセットアップで問題が増える可能性があります。できるだけ方法1または2を使用してください。 :::

方法4：Docker を使用 権限問題を避けたい場合は、Docker で完全に隔離された環境を構築：

docker run -it node:latest /bin/bash
npm install -g claude-code

Q2: API キーが認識されない、または設定されていないというエラー

原因

環境変数 ANTHROPIC_API_KEY が設定されていない、設定場所が間違っている、またはシェルが再起動されていません。

解決法

ステップ1：API キーを確認

Anthropic コンソールにログイン
「API Keys」セクションから新しいキーを生成（または既存キーをコピー）
キーは sk-ant- で始まります

ステップ2：環境変数を設定

Bash を使用している場合：

# ~/.bashrc に追加
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
 
# 確認
echo $ANTHROPIC_API_KEY

Zsh を使用している場合（Mac のデフォルト）：

# ~/.zshrc に追加
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc
 
# 確認
echo $ANTHROPIC_API_KEY

Windows (PowerShell) の場合：

# 環境変数を永続的に設定
[Environment]::SetEnvironmentVariable(
    "ANTHROPIC_API_KEY",
    "your-key-here",
    [EnvironmentVariableTarget]::User
)
 
# PowerShell を再起動してから確認
$env:ANTHROPIC_API_KEY

ステップ3：設定が反映されたか確認

# シェルを再起動（重要）
exec $SHELL
 
# または単に新しいターミナルタブを開く
 
# キーが設定されているか確認
echo $ANTHROPIC_API_KEY
# 出力例：sk-ant-XXXXXXXXXXX...

:::warning API キーは絶対に以下の場所に保存しないでください：

Git リポジトリ（.gitignore で防ぐ）
公開ファイル
メール
他のユーザーが見られるシェルスクリプト :::

ステップ4：.env ファイルを使用（プロジェクト単位の設定）

# プロジェクトフォルダに .env ファイルを作成
echo 'ANTHROPIC_API_KEY=your-key-here' > .env
 
# .env を .gitignore に追加
echo '.env' >> .gitignore
 
# Python を使用している場合は python-dotenv を使用
pip install python-dotenv
 
# スクリプトで読み込む
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv('ANTHROPIC_API_KEY')

Q3: `claude` コマンドが見つからない（PATH 関連のエラー）

原因

Claude Code が PATH に登録されていない、またはシェルが新しい PATH を認識していません。

解決法

ステップ1：Claude Code のインストール場所を確認

# npm でグローバルインストール
npm list -g claude-code
 
# 出力例：
# /Users/username/.npm-global/lib/node_modules/claude-code
 
# またはローカルインストールの確認
npm list claude-code
# node_modules/claude-code

ステップ2：PATH に追加

方法A：npm のグローバルインストール位置を PATH に追加

# npm のプレフィックスを確認
npm config get prefix
# 出力例：~/.npm-global
 
# ~/.bashrc または ~/.zshrc に追加
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
# 確認
which claude

方法B：明示的に PATH を設定

# ~/.bashrc に追加
export PATH="/usr/local/lib/node_modules/.bin:$PATH"
 
# または Node.js のバージョンマネージャー（nvm）を使用している場合
export PATH="$HOME/.nvm/versions/node/v20.0.0/bin:$PATH"
 
# 変更を反映
source ~/.bashrc

ステップ3：シェルを再起動

# ターミナルを完全に再起動
exec $SHELL
 
# または新しいタブを開く
 
# コマンドが見つかるか確認
claude --version

ステップ4：ローカルインストールの場合

# カレントディレクトリのプロジェクトに Claude Code がインストールされている場合
npx claude --version
 
# または
./node_modules/.bin/claude --version

:::tip Mac の M1/M2/M3 チップを使用している場合、別の PATH が必要になることがあります。その場合は、以下を確認してください：

# ARM64 アーキテクチャの確認
uname -m
# 出力：arm64（M1/M2 の場合）
 
# Rosetta 2 経由で実行
arch -x86_64 zsh

:::

Q4: プロキシ環境で Claude と接続できない

原因

会社の内部ネットワークやファイアウォール経由でインターネットに接続している場合、プロキシ設定が必要です。

解決法

ステップ1：プロキシ情報を確認 社内 IT チームに以下の情報を確認：

プロキシサーバーアドレス（例：proxy.company.com:8080）
ユーザー名とパスワード（必要な場合）
プロトコル（HTTP、HTTPS、SOCKS）

ステップ2：npm でプロキシを設定

# HTTP プロキシ
npm config set proxy http://[user:password@]proxyserver:port
 
# HTTPS プロキシ
npm config set https-proxy http://[user:password@]proxyserver:port
 
# 例：
npm config set proxy http://proxy.company.com:8080
 
# 認証が必要な場合：
npm config set proxy http://username:password@proxy.company.com:8080

ステップ3：環境変数でも設定

# Bash/Zsh
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"
 
# PowerShell (Windows)
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"

ステップ4：Claude Code でプロキシを使用

# 環境変数を設定した後
claude --help
 
# または anthropic-cli の場合
export ANTHROPIC_API_KEY="your-key"
npm install -g @anthropic-ai/sdk

ステップ5：接続テスト

# curl でプロキシ経由のテスト
curl -x http://proxy.company.com:8080 https://api.anthropic.com
 
# 成功すると、接続情報が表示されます

:::warning プロキシ設定に認証情報が含まれている場合は、.npmrc ファイルに保存されます。.npmrc ファイルを .gitignore に追加してください：

echo '.npmrc' >> .gitignore

:::

Q5: CLAUDE.md が読み込まれない、または認識されない

原因

CLAUDE.md ファイルの位置が間違っている、ファイル形式が不正、またはパーミッションが不足しています。

解決法

ステップ1：CLAUDE.md の位置を確認 Claude Code はプロジェクトのルートディレクトリで CLAUDE.md を探します：

# 正しい位置
/your-project/CLAUDE.md
 
# 間違った位置
/your-project/docs/CLAUDE.md  # ❌ 読み込まれない
/your-project/src/CLAUDE.md   # ❌ 読み込まれない

ステップ2：ファイルが存在するか確認

ls -la CLAUDE.md
 
# ファイルがない場合は作成
touch CLAUDE.md
 
# または既存ファイルをコピー
cp /path/to/template/CLAUDE.md ./

ステップ3：ファイルのパーミッションを確認

# 読み取り権限があるか確認
ls -la CLAUDE.md
# 出力例：-rw-r--r--  1 user  group  1234 Mar 21 10:00 CLAUDE.md
 
# 読み取り権限がない場合は追加
chmod 644 CLAUDE.md

ステップ4：ファイル形式を確認

# UTF-8 エンコーディングか確認
file CLAUDE.md
# 出力例：CLAUDE.md: UTF-8 Unicode text
 
# Markdown フォーマットが正しいか確認
head -5 CLAUDE.md
# `---` で始まる YAML フロントマターがあるか確認

ステップ5：Claude Code で明示的に指定

# プロジェクトディレクトリから実行
cd /your-project
claude
 
# または明示的にパスを指定
claude --config ./CLAUDE.md
 
# 複数の設定ファイルがある場合
claude --config ./CLAUDE.md --workspace ./src

:::tip CLAUDE.md の標準的な構成：

---
name: "Project Name"
description: "What this project does"
---
 
# System Prompt
 
You are an AI assistant helping with this project.
 
## Context
 
- Tech stack: Node.js, React
- Database: PostgreSQL
- ...

:::

Q6: サブエージェントが起動しない、または通信できない

原因

サブエージェント用の API キー設定がない、ポート競合、またはネットワーク設定が不正です。

解決法

ステップ1：サブエージェント用の設定を確認

# CLAUDE.md でサブエージェント設定を確認
grep -A 5 "agent" CLAUDE.md
 
# または環境変数で設定
export CLAUDE_AGENT_URL="http://localhost:8000"
export CLAUDE_AGENT_TOKEN="your-agent-token"

ステップ2：ポート競合を確認

# 使用されているポートを確認（MacおよびLinux）
lsof -i :8000
# または
netstat -tulpn | grep 8000
 
# ポートが使用されている場合は別のポートを使用
export CLAUDE_AGENT_PORT=8001

ステップ3：エージェントプロセスを起動

# エージェントを別のターミナルで起動
claude agent start
 
# または Docker で起動
docker run -p 8000:8000 claude-agent:latest
 
# 起動を確認
curl http://localhost:8000/health

ステップ4：接続テスト

# エージェントが応答しているか確認
curl -X POST http://localhost:8000/message \
  -H "Authorization: Bearer $CLAUDE_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

ステップ5：ログを確認

# Claude Code のログを確認
claude --log-level debug
 
# エージェントのログを確認
tail -f ~/.claude/logs/agent.log

:::warning サブエージェント通信はセキュアチャネルで行われるべきです。本番環境では HTTPS と認証トークンを必ず使用してください。 :::

Q7: Git hook との競合、または pre-commit / pre-push フックが実行されない

原因

Claude Code と Git hook 管理ツール（Husky など）が同じフックを実行しようとしている、またはフックの権限設定が不正です。

解決法

ステップ1：既存の Git hook を確認

# Git hook ディレクトリを確認
ls -la .git/hooks/
 
# 既存のフック内容を確認
cat .git/hooks/pre-commit
 
# hook 管理ツール（Husky など）がインストールされているか確認
npm list husky

ステップ2：Husky と Claude Code の共存設定

# Husky がインストールされている場合
npx husky install
 
# .husky/pre-commit に Claude Code を追加
cat >> .husky/pre-commit << 'EOF'
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
 
# Claude Code 自体のチェック
claude lint
 
# または既存のチェックを実行
npm run lint
EOF
 
# 実行権限を追加
chmod +x .husky/pre-commit

ステップ3：フックの実行権限を確認

# フックが実行可能か確認
ls -la .git/hooks/pre-commit
# 出力例：-rwxr-xr-x（x があるので実行可能）
 
# 実行権限がない場合は追加
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push
chmod +x .git/hooks/commit-msg

ステップ4：Claude Code フック設定

# CLAUDE.md で Git フック設定を定義
cat >> CLAUDE.md << 'EOF'
 
## Git Hooks
 
```json
{
  "hooks": {
    "pre-commit": ["claude lint", "npm test"],
    "pre-push": ["claude validate"]
  }
}

EOF


**ステップ5：フック実行の順序を制御**
```bash
# .git/hooks/pre-commit の例
#!/bin/bash

set -e  # エラーで停止

echo "Running Claude Code checks..."
claude lint

echo "Running npm tests..."
npm test

echo "Running Husky hooks..."
husky pre-commit

echo "All checks passed!"

ステップ6：フックの実行をスキップ（デバッグ用）

# pre-commit フックをスキップしてコミット
git commit --no-verify
 
# pre-push フックをスキップしてプッシュ
git push --no-verify

:::warning --no-verify フラグは CI/CD パイプラインの品質チェックをバイパスするため、ローカルデバッグ時のみ使用してください。本番環境ではフックを無効化しないでください。 :::

トラブルシューティングチェックリスト

セットアップがうまくいかない場合、この順番でチェックしてください：

Node.js と npm がインストールされているか確認
```
node --version
npm --version
```

npm パッケージの権限が正しいか確認

npm config get prefix
npm config get cache

API キーが正しく設定されているか確認
```
echo $ANTHROPIC_API_KEY | head -c 10
```
PATH が正しく設定されているか確認
```
which claude
claude --version
```
ネットワーク接続を確認
```
curl -I https://api.anthropic.com
```

キャッシュをクリアして再インストール

npm cache clean --force
npm install -g claude-code

全体を振り返って

Claude Code のセットアップエラーはほぼすべてが以下の3つのカテゴリのいずれかです：

権限問題（npm、ファイル、ディレクトリ）
環境変数設定（API キー、PATH、プロキシ）
ネットワーク接続（プロキシ、ファイアウォール、DNS）

各エラーログを詳しく読むと、多くの場合は自己診断メッセージが含まれています。エラーメッセージ全文を記録し、このガイドと照らし合わせることで、ほぼすべての問題が解決します。

Happy coding!

Claude Code が起動しない？セットアップのつまずきポイント FAQ

Q1: npm install で権限エラー（Permission Denied）が出る場合は？

原因

解決法

Q2: API キーが認識されない、または設定されていないというエラー

原因

解決法

Q3: `claude` コマンドが見つからない（PATH 関連のエラー）

原因

解決法

Q4: プロキシ環境で Claude と接続できない

原因

解決法

Q5: CLAUDE.md が読み込まれない、または認識されない

原因

解決法

Q6: サブエージェントが起動しない、または通信できない

原因

解決法

Q7: Git hook との競合、または pre-commit / pre-push フックが実行されない

原因

解決法

トラブルシューティングチェックリスト

全体を振り返って

お読みいただきありがとうございます

関連記事

Claude Code が起動しない？セットアップのつまずきポイント FAQ

Q1: npm install で権限エラー（Permission Denied）が出る場合は？

原因

解決法

Q2: API キーが認識されない、または設定されていないというエラー

原因

解決法

Q3: claude コマンドが見つからない（PATH 関連のエラー）

原因

解決法

Q4: プロキシ環境で Claude と接続できない

原因

解決法

Q5: CLAUDE.md が読み込まれない、または認識されない

原因

解決法

Q6: サブエージェントが起動しない、または通信できない

原因

解決法

Q7: Git hook との競合、または pre-commit / pre-push フックが実行されない

原因

解決法

トラブルシューティング チェックリスト

全体を振り返って

お読みいただきありがとうございます

関連記事

Q3: `claude` コマンドが見つからない（PATH 関連のエラー）

トラブルシューティングチェックリスト