# トラブルシューティングガイド

## Key を設定したのにリクエストが失敗するなら、この順に

このページの残りはエラーコード別の構成です。**ドキュメントどおりに Key と URL を入れたのに失敗する**場合は、まず次を順に確認してください（curl 自己診断と HTTP コードの読み方は [エンドポイントと API 形式](/docs/getting-started/endpoints-and-api-paths) 第 5 節）。

1. **まず curl を 1 本打つ。** `401` = 鍵の問題、`404` = パスプレフィックス誤、`400` + `model_not_available_on_endpoint` = プロトコル選択の誤（鍵は正常、4 へ）、接続自体が無理 = ネットワーク／プロキシ（6 へ）。
2. **変数の置き場所。** `ANTHROPIC_AUTH_TOKEN` は `Authorization: Bearer` ヘッダー、`ANTHROPIC_API_KEY` は `x-api-key` ヘッダーで送信されます——取り違えるとゲートウェイに認証情報が届きません。**環境に残った旧変数が現行設定を上書きします**：`env | grep -i anthropic` と `env | grep -i openai` を実行し、不要な残りを削除してください。
3. **Base URL の形。** Claude Code 系は `https://api.qcode.cc/api`（**`/v1` を付けない**）、OpenAI SDK／互換クライアントは `https://api.qcode.cc/openai/v1`、Codex CLI は設定ファイルに `https://api.qcode.cc/openai` + `wire_api = "responses"`。一区切り余分でも不足でも 404 になります。
4. **プロトコルとモデルの不一致。** Claude モデルを OpenAI エンドポイントに送ると認証前に `model_not_available_on_endpoint` が返ります——[エンドポイントと API 形式](/docs/getting-started/endpoints-and-api-paths) 第 2 節の表で端点かモデルを修正。
5. **クライアント版の退行（Claude Code）：**
   - **2.1.265–2.1.267**：全リクエストが 400（Artifact ツールのスキーマが拒否）——**2.1.268 以上**へアップグレード、または `CLAUDE_CODE_DISABLE_ARTIFACT=1` で応急回避。
   - **2.1.275**：`ANTHROPIC_BASE_URL` がゲートウェイ向けだと全リクエストが `400 … Input tag 'advisor_20260301'`——**2.1.276 以上**へ。
   - `Unexpected value(s) … anthropic-beta` 系なら `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。
6. **システムプロキシと接続ドメインの衝突。** `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` は経路を書き換えます。`*.qcode.cc` を `NO_PROXY` に足すか、一時的に unset して再試行。
7. **それでも不可**：[probe.qcode.cc](https://probe.qcode.cc) でキーを入力し実際のリクエストを確認したのち、**request id を添えてサポートへ**（オンラインチャットまたは hi@qcode.cc）。

エラーコードの意味は [エラーコードリファレンス](/docs/reference/errors)、「サブスクを API として使えるか」等の概念的な質問は [サブスクリプション・公式 API・QCode Key](/docs/reference/subscription-vs-api-key) へ。

Claude Code の使用中に問題が発生しても慌てないでください。このガイドは「クイック自己診断 → 段階的な切り分け → 解決策」という流れで編成されており、効率的な問題の特定と解決を支援します。

## クイック自己診断

問題が発生したら、まずこの3ステップのクイックチェックを行ってください。80%の問題はこの段階で特定できます。

### 1. Claude Code のバージョンを確認

```bash
claude --version
```

最新バージョンを使用していることをご確認ください。Claude Code は非常に頻繁にアップデートされており、多くの問題は新バージョンで既に修正されています。

**最新版にアップグレード：**

```bash
npm update -g @anthropic-ai/claude-code
```

### 2. 自動診断を実行

```bash
claude /doctor
```

`/doctor` コマンドは自動的に以下をチェックします：
- Node.js バージョンが要件を満たしているか（≥ 18）
- API キーが有効か
- ネットワーク接続が正常か
- 設定ファイルに構文エラーがないか

### 3. Node.js バージョンを確認

Claude Code は Node.js 18 以上が必要です：

```bash
node --version
# v18.x.x 以上が出力されるはず
```

バージョンが低い場合は、アップグレードしてください：

```bash
# nvm で Node.js バージョンを管理（推奨）
nvm install 22
nvm use 22

# または直接ダウンロードしてインストール
# https://nodejs.org/ にアクセスして LTS バージョンをダウンロード
```

## インストール問題

### npm install の権限エラー

**症状：**

```bash
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
```

**解決策 1：sudo を使用（手軽だが、長期使用には推奨されない）**

```bash
sudo npm install -g @anthropic-ai/claude-code
```

**解決策 2：npm のグローバルディレクトリを変更（推奨）**

```bash
# ユーザーレベルのグローバルパッケージディレクトリを作成
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# PATH に追加（~/.bashrc または ~/.zshrc に書き込み）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 再インストール
npm install -g @anthropic-ai/claude-code
```

**解決策 3：nvm で Node.js を管理**

```bash
# nvm をインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# Node.js をインストールして使用
nvm install 22
nvm use 22

# nvm でインストールした Node.js は sudo 不要
npm install -g @anthropic-ai/claude-code
```

### ネットワーク問題によるインストール失敗

**症状：**

```bash
npm ERR! network request to https://registry.npmjs.org/ failed
npm ERR! code ETIMEDOUT
```

**解決策：国内ミラーを使用**

```bash
# 一時的に淘宝ミラーを使用
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# または恒久的にミラーを設定
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
```

プロキシを使用している場合：

```bash
# npm プロキシを設定
npm config set proxy http://プロキシアドレス:ポート
npm config set https-proxy http://プロキシアドレス:ポート

# インストール完了後はプロキシ設定を解除可能
npm config delete proxy
npm config delete https-proxy
```

### Windows PowerShell 実行ポリシー

**症状：**

```bash
claude : File C:\Users\xxx\AppData\Roaming\npm\claude.ps1 cannot be loaded
because running scripts is disabled on this system.
```

**解決策：**

```powershell
# 管理者として PowerShell を開き、実行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 次に claude を再実行
claude
```

または PowerShell の代わりに CMD を使用：

```cmd
# CMD で直接実行
claude
```

## 接続問題

接続問題は中国のユーザーが最もよく遭遇する問題タイプです。

### API キー形式エラー

**QCode.cc の API キー形式：**

```text
cr_xxxxxxxxxxxxxxxx
```

接頭辞は `cr_` であり、Anthropic 公式の `sk-ant-` ではないことに注意してください。

**API キー設定を確認：**

```bash
# 現在の環境変数を表示
echo $ANTHROPIC_AUTH_TOKEN

# 正しく設定（QCode.cc キー）
export ANTHROPIC_AUTH_TOKEN="cr_あなたのキー"
```

**よくあるエラー：**

| エラー | 説明 |
|------|------|
| キーの前後にスペースがある | `cr_ xxx` → `cr_xxx` |
| 公式キー形式を使用している | `sk-ant-xxx` は Anthropic 公式キーであり、QCode.cc キーではない |
| キーが切り詰められている | キー全体をコピーしたか確認 |
| 期限切れのキーを使用 | QCode.cc Dashboard でキーの状態を確認 |

### ANTHROPIC_BASE_URL 設定エラー

QCode.cc サービスを使用する場合は、Base URL を正しく設定する必要があります：

```bash
# QCode.cc の Base URL
export ANTHROPIC_BASE_URL="https://あなたのサービスアドレス"
```

**切り分け手順：**

```bash
# 1. 現在の設定を確認
echo $ANTHROPIC_BASE_URL

# 2. URL 形式が正しいことを確認
#    - https:// で始まる必要がある
#    - 末尾にスラッシュ / をつけない
#    - パスを含めない（/v1/messages など）

# 正しい：Anthropic 側は /api 接頭辞が必要だが、リクエストパスまでは書かない
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"

# 誤り：https 無し / 末尾スラッシュ余計 / パスまで書き込む
export ANTHROPIC_BASE_URL="http://api.qcode.cc/api"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/v1/messages"
```

### プロキシ/VPN による接続失敗

**症状：**

```text
Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.example.com
```

**切り分け手順：**

```bash
# 1. プロキシが正しく設定されているか確認
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# 2. ネットワーク接続をテスト
curl -v https://あなたのサービスアドレス/health

# 3. プロキシを使用する場合、Claude Code が使えるようにする
export HTTP_PROXY="http://プロキシアドレス:ポート"
export HTTPS_PROXY="http://プロキシアドレス:ポート"

# 4. プロキシが不要なのに設定されている場合は、解除
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY
```

**VPN 注意事項：**

- VPN が API リクエストを遮断していないことを確認
- 一部の VPN のスプリットトンネル（ルーティング規則）が API 接続に影響を与える可能性がある
- VPN が問題を引き起こしている場合は、API ドメインを直接接続ルールに追加してみてください

### SSL/TLS 証明書問題

**症状：**

```text
Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
```

**解決策：**

```bash
# 方法 1：システム CA 証明書を更新
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# 方法 2：企業ネットワークの中間者証明書の場合、Node.js に信頼させる
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.crt"

# 方法 3：一時的に証明書検証をスキップ（テスト用のみ、長期使用は推奨されない）
export NODE_TLS_REJECT_UNAUTHORIZED=0
```

### 接続テスト

curl で直接 API 接続をテスト：

```bash
# 基本接続をテスト
curl -s -o /dev/null -w "%{http_code}" \
  https://あなたのサービスアドレス/health

# API 呼び出しをテスト（あなたのキーとアドレスに置き換える）
curl https://あなたのサービスアドレス/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_あなたのキー" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

**期待される結果：**
- ヘルスチェックが `200` を返す
- API 呼び出しが JSON レスポンスを返す

**よくある問題一覧：**

| curl の結果 | 考えられる原因 | 解決策 |
|-----------|---------|---------|
| `connection refused` | サービスアドレスが間違っている、またはサービスが停止している | ANTHROPIC_BASE_URL を確認 |
| `connection timeout` | ネットワークが通らない、またはファイアウォールに遮断されている | ネットワーク/プロキシ設定を確認 |
| `401 Unauthorized` | API キーが無効 | キーが正しいか確認 |
| `403 Forbidden` | キーに権限がない | サービスプロバイダーに連絡 |
| SSL 関連エラー | 証明書問題 | 上記の SSL セクションを参照 |

## 権限問題

### ファイル読み書き権限が不十分

**症状：**

```text
Error: EACCES: permission denied, open '/path/to/file'
```

**解決策：**

```bash
# 1. ファイル権限を確認
ls -la /path/to/file

# 2. 現在のユーザーに読み書き権限があることを確認
chmod u+rw /path/to/file

# 3. ディレクトリ権限を確認（Claude が新規ファイルを作成する際にディレクトリの書き込み権限が必要）
chmod u+w /path/to/directory

# 4. root が作成したファイルの場合、所有者を変更
sudo chown $(whoami) /path/to/file
```

**Claude Code の権限設定：**

Claude Code には、操作の種類を管理するための権限システムがあります。Claude が特定の操作を実行できずブロックされた場合：

```bash
# 現在の権限設定を表示
claude /permissions

# settings.json で許可されたディレクトリを設定
# ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read files in /home/user/projects/**",
      "Write files in /home/user/projects/**",
      "Execute bash commands"
    ]
  }
}
```

### Git 操作が拒否された

**症状：**

```text
fatal: unable to access 'https://github.com/xxx/xxx.git/':
The requested URL returned error: 403
```

**解決策：**

```bash
# 1. Git 設定を確認
git config --list

# 2. SSH キーまたは Token の設定を確認
ssh -T git@github.com          # SSH 接続をテスト
gh auth status                  # GitHub CLI 認証をテスト

# 3. HTTPS の場合、認証情報を確認
git config credential.helper    # 認証情報管理方法を表示

# 4. Claude Code が正しい Git リポジトリにあることを確認
git status                      # リポジトリディレクトリ内であることを確認
```

### Bash コマンド実行失敗

Claude Code が bash コマンドを実行する場合、確認が必要な場合があります。コマンドが繰り返し拒否された場合：

```bash
# 権限設定を表示
claude /permissions

# 信頼できるプロジェクトの場合、CLAUDE.md で許可されたコマンドを設定可能
# CLAUDE.md
## 許可されるコマンド
allowedTools:
  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)
```

## パフォーマンス問題

### レスポンス速度が遅い

**考えられる原因と解決策：**

| 原因 | 診断方法 | 解決策 |
|------|---------|---------|
| ネットワーク遅延 | `ping サービスアドレス` | ネットワーク/プロキシを確認 |
| Opus モデルを使用 | `/model` で確認 | Sonnet に切り替え |
| コンテキストが大きすぎる | `/cost` でトークン数を確認 | `/compact` で圧縮 |
| サーバーサイド負荷が高い | HTTP レスポンス時間を確認 | 時間を置いて再試行 |

**ネットワーク最適化アドバイス（中国ユーザー向け）：**

```bash
# サーバーへの遅延をテスト
ping サービスアドレス

# 遅延が 500ms を超える場合は検討：
# 1. プロキシ設定が最適か確認
# 2. 異なる時間帯に使用してみる（ピーク時間を避ける）
# 3. QCode.cc カスタマーサポートに連絡して最適なノードを取得
```

### コンテキストオーバーフロー

**症状：**
- Claude の回答が、以前話したことを「忘れ始める」
- 回答の品質が著しく低下する
- 重複または矛盾した内容が現れる

**解決策：**

```bash
# 方法 1：コンテキストを圧縮（重要な情報を保持）
/compact

# 方法 2：完全にクリア（最初からやり直せる場合）
/clear

# 方法 3：入力内容を簡潔にする
# 大量ファイル内容を一度に送信しない
# 貼り付けずに @ 引用を使用
# 一度に1つのタスクのみ処理
```

**予防策：**

- 独立したタスクを完了するたびに、 `/compact` を検討
- 異なるテーマに移る場合は、躊躇なく `/clear`
- `.claudeignore` を使用して無関係な大ファイルを排除
- `@` を使用して必要なファイルを正確に引用し、Claude にグローバル検索させない

### メモリ使用量が多すぎる

**症状：**
- システムが重くなる
- Claude Code プロセスが大量のメモリを消費

**解決策：**

```bash
# 1. Node.js のメモリ使用量を確認
node -e "console.log(process.memoryUsage())"

# 2. Node.js を最新版 LTS にアップグレード
nvm install 22
nvm use 22

# 3. 問題が継続する場合は、Node.js の最大メモリを制限
export NODE_OPTIONS="--max-old-space-size=4096"

# 4. Claude Code を再起動
# 現在のセッションを終了して再起動
exit
claude
```

## よくあるエラーコード一覧

| エラーコード | 意味 | 原因 | 解決策 |
|--------|------|------|---------|
| **400** | Bad Request | リクエスト形式エラー | 入力に不正な文字が含まれていないか確認；Claude Code を最新版に更新 |
| **401** | Unauthorized | API キーが無効または期限切れ | `ANTHROPIC_AUTH_TOKEN` の設定を確認；キーが期限切れでないことを確認 |
| **403** | Forbidden | 権限なし | キーに該当モデルへのアクセス権限があることを確認 |
| **404** | Not Found | モデルまたはパスが存在しない | `ANTHROPIC_BASE_URL` とモデル名が正しいか確認 |
| **429** | Too Many Requests | リクエストが多すぎる | 30〜60秒待ってから再試行；同時リクエスト数を減らす |
| **500** | Internal Server Error | サーバー内部エラー | 時間を置いて再試行；継続する場合はカスタマーサポートに連絡 |
| **502** | Bad Gateway | 上流サービスが利用不可 | 時間を置いて再試行；サービス公告があるか確認 |
| **503** | Service Unavailable | サービスが一時的に過負荷 | 数分待ってから再試行 |
| **529** | API Overloaded | Claude API が過負荷 | Anthropic サーバーサイドの負荷が高い状態；待ってから再試行 |

### 429 詳細：レート制限

429 は最もよく遭遇するエラーであり、詳しく説明します：

**トリガー原因：**

1. **リクエスト頻度が高すぎる**：毎秒リクエストが多すぎる
2. **トークン消費が速すぎる**：短時間で大量のトークンを消費
3. **同時セッションが多すぎる**：同時に複数の Claude Code インスタンスを実行
4. **アカウントクォータを使い切った**：当日/当月分のクォータを使い切った

**段階的処理：**

```bash
# たまに 429 が発生する場合
# → 30秒待てば自動再試行、Claude Code には内蔵の再試行ロジックがある

# 頻繁に 429 が発生する場合
# → リクエスト頻度を減らす
# → /compact でコンテキストサイズを減らす
# → 同時に複数の Claude Code インスタンスを実行しない

# 継続的に 429 が発生する場合
# → プランのクォータを使い切ったか確認
# → QCode.cc Dashboard にログインして使用量を確認
# → プランのアップグレードを検討
```

### 529 詳細：API 過負荷

529 は Anthropic 固有のエラーコードであり、Claude API サーバーが過負荷状態であることを示します：

```text
Error: 529 API Overloaded
The API is temporarily overloaded. Please try again later.
```

**対処方法：**

- これはあなたの問題ではなく、Anthropic サーバーサイドの一時的な状況です
- 通常、数分から数十分続きます
- 1〜2分待ってから再試行
- 継続的に発生する場合は、一時的に他のモデル（GPT シリーズなど）に切り替え
- [Anthropic Status](https://status.anthropic.com/) をチェックしてサービス状態を確認

## その他のよくある問題

### Claude Code 起動後に反応がない

```bash
# 1. 正しくインストールされているか確認
which claude
npm list -g @anthropic-ai/claude-code

# 2. 詳細なエラーメッセージを表示
claude --debug

# 3. キャッシュをクリアしてから再起動を試みる
rm -rf ~/.claude/cache
claude
```

### CLAUDE.md が効かない

```bash
# 1. ファイルの場所が正しいか確認
ls -la CLAUDE.md                # プロジェクトルートディレクトリ
ls -la .claude/CLAUDE.md        # プロジェクトプライベート設定
ls -la ~/.claude/CLAUDE.md      # グローバル設定

# 2. ファイルエンコーディングが UTF-8 であることを確認
file CLAUDE.md
# 次のように表示されるはず：CLAUDE.md: UTF-8 Unicode text

# 3. 構文エラーがないことを確認（Markdown ですが、特定の特殊文字が解析の問題を引き起こす可能性があります）
# CLAUDE.md で ``` 以外の特殊マークを使用しないように注意

# 4. Claude Code を再起動して設定を適用
# 終了して再度入り直す
```

### 中国語の表示が文字化けする

```bash
# 1. ターミナルエンコーディング設定を確認
echo $LANG
# UTF-8 を含める必要がある。例えば en_US.UTF-8 や zh_CN.UTF-8

# 2. 正しいエンコーディングを設定
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 3. ターミナルが UTF-8 をサポートしていることを確認
# macOS Terminal / iTerm2 はデフォルトでサポート
# Windows Terminal はデフォルトでサポート
# Windows CMD の場合：chcp 65001 を実行
```

### Git コンフリクトにより Claude の操作が失敗する

```bash
# 1. 先に Git コンフリクトを解決
git status     # コンフリクトファイルを確認
git diff       # コンフリクト内容を表示

# 2. Claude にコンフリクトを解決してもらう
> "現在の git コンフリクトファイルを確認し、これらのコンフリクトを解決してください。両方の変更を保持します。"

# 3. 解決後に続ける
git add .
git commit -m "resolve merge conflicts"
```

### Docker 関連問題（上級ユーザー）

Docker コンテナ内で Claude Code を使用する場合：

```bash
# コンテナ内に Node.js 22+ があることを確認
docker run -it node:22-slim bash

# Claude Code をインストール
npm install -g @anthropic-ai/claude-code

# 必要な環境変数を渡す
docker run -it \
  -e ANTHROPIC_AUTH_TOKEN="cr_あなたのキー" \
  -e ANTHROPIC_BASE_URL="https://あなたのサービスアドレス" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude
```

## トラブルシューティング流れまとめ

問題が発生した場合は、この流れで切り分けてください：

```text
1. クイック自己診断
   ├── claude --version（バージョンが最新か）
   ├── claude /doctor（自動診断）
   └── node --version（Node.js ≥ 18）

2. ネットワーク接続性
   ├── curl で API アドレスをテスト
   ├── プロキシ/VPN 設定を確認
   └── DNS 解決を確認

3. 認証設定
   ├── ANTHROPIC_AUTH_TOKEN の形式が正しいか
   ├── ANTHROPIC_BASE_URL が正しいか
   └── キーが期限切れでないか

4. 権限確認
   ├── ファイルシステム権限
   ├── Git 権限
   └── Claude Code 権限設定

5. パフォーマンス最適化
   ├── /compact でコンテキストを圧縮
   ├── /model で適切なモデルに切り替え
   └── .claudeignore で大ファイルを排除

6. 上記で解決できない場合 → ヘルプを求める
```

## ヘルプを求める

上記の方法で問題を解決できない場合は、以下の窓口からヘルプを得られます：

### QCode.cc オンラインカスタマーサポート

[QCode.cc](https://qcode.cc) ウェブサイトの右下でオンラインカスタマーサポートのアイコンをクリックしてください。稼働時間内なら通常数分で返信が得られます。

**ご質問時には以下を提供してください：**
- Claude Code バージョン（`claude --version` の出力）
- オペレーティングシステムとバージョン
- 完全なエラーメッセージ
- 試した解決策

### GitHub Issues

Claude Code はオープンソースプロジェクトであり、GitHub で issue を提出できます：

- **リポジトリアドレス**：[github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)
- 既存の issue を探して、同じ問題に遭遇した人がいるか確認
- 新規 issue を提出する場合は、英語で記述（より迅速な公式対応を得られる）

### コミュニティリソース

- **Claude Code 公式ドキュメント**：[docs.anthropic.com](https://docs.anthropic.com)
- **Anthropic サービス状態**：[status.anthropic.com](https://status.anthropic.com)
- **QCode.cc ユーザードキュメント**：[docs.qcode.cc](https://docs.qcode.cc)

> 問題が発生しても恐れないでください。大部分の問題にはシンプルな解決策があります。このガイドの流れで切り分ければ、通常数分で解決できます。