# 故障排查指南

## 配置好 Key 还是请求失败？按这个顺序查

页面其他部分按错误码组织；如果你**已经按文档把 Key 和地址都填了、请求还是失败**，先按下面的顺序自查（curl 自测与 HTTP 码判读见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) 第 5 节）：

1. **先跑一条 curl 自测**。拿到 HTTP 码再判断：`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 工具 schema 被拒）——升级到 **≥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 过程中遇到问题别慌。本指南按照「快速自检 → 逐步排查 → 解决方案」的流程组织，帮你高效定位和解决问题。

## 快速自检

遇到问题时，先做这三步快速检查，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 Key 是否有效
- 网络连接是否正常
- 配置文件是否有语法错误

### 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
```

或者使用 CMD 代替 PowerShell：

```cmd
# 在 CMD 中直接运行
claude
```

## 连接问题

连接问题是中国用户最常遇到的问题类型。

### API Key 格式错误

**QCode.cc 的 API Key 格式：**

```text
cr_xxxxxxxxxxxxxxxx
```

注意前缀是 `cr_`，不是 Anthropic 官方的 `sk-ant-`。

**检查 API Key 配置：**

```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 Key 无效 | 检查密钥是否正确 |
| `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` 查看 token 数 | `/compact` 压缩 |
| 服务端负载高 | 检查 HTTP 响应时间 | 稍后重试 |

**网络优化建议（中国用户）：**

```bash
# 测试到服务器的延迟
ping 服务地址

# 如果延迟超过 500ms，考虑：
# 1. 检查代理配置是否最优
# 2. 尝试不同时段使用（避开高峰）
# 3. 联系 QCode.cc 客服获取最优节点
```

### 上下文溢出

**症状：**
- Claude 的回复开始「忘记」之前说过的话
- 回复质量明显下降
- 出现重复或矛盾的内容

**解决方案：**

```bash
# 方案 1：压缩上下文（保留关键信息）
/compact

# 方案 2：彻底清空（如果可以从头开始）
/clear

# 方案 3：精简每次输入
# 不要一次性发送大量文件内容
# 用 @ 引用代替粘贴
# 一次只处理一个任务
```

**预防措施：**

- 每完成一个独立任务后，考虑 `/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 Key 无效或过期 | 检查 `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. **Token 消耗过快**：短时间内消耗大量 token
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)

> 遇到问题不要怕，大部分问题都有简单的解决方案。按照本指南的流程排查，通常几分钟就能搞定。