故障排查

一键诊断

claude doctor

会一次性检查：环境变量、Key、节点延迟、CLI 版本、依赖工具（git/rg）等。遇到问题先跑这个。

401 Unauthorized

症状：401 Unauthorized / Invalid API key

排查清单：

1. 检查 ANTHROPIC_AUTH_TOKEN（或 ANTHROPIC_API_KEY）是否完整复制（注意首尾空格、换行）
2. 控制台确认 Key 状态是「启用」
3. Key 是否被吊销或过期
4. 是否设了 IP 白名单但当前 IP 不在
5. 检查环境变量是否真生效：

echo $ANTHROPIC_BASE_URL          # macOS/Linux
echo $env:ANTHROPIC_BASE_URL      # PowerShell
echo %ANTHROPIC_BASE_URL%         # Windows CMD

直接 curl 验证：

curl https://nexor.nexoraivision.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

429 Too Many Requests

症状：429 rate limit exceeded

原因：触发了 QPM/并发上限或日额度上限。

解决：

• 降低并发（CLI 单进程足够）
• 客户端指数退避：sleep 2^n + random()
• 检查 Key 是否设了「日用量上限」（控制台 → API Keys → 编辑 Key）
• 联系客服上调速率限制

模型不存在

症状：model claude-3-opus not found / Unknown model

最常见：模型 ID 写错了。我们当前支持的 6 个 Claude 模型 ID：

claude-opus-4-7
claude-opus-4-6
claude-opus-4-5-20251101
claude-sonnet-4-6
claude-sonnet-4-5-20250929
claude-haiku-4-5-20251001

注意：

• 是 claude-opus-4-7（连字符），不是 claude-opus-4.7（点）
• Haiku 只有快照版：必须写 claude-haiku-4-5-20251001，不是 claude-haiku-4-5
• 不是 claude-3-opus / claude-3-opus-20240229 / claude-3.5-sonnet 等老 ID

列出实际可用模型：

curl https://nexor.nexoraivision.com/v1/models \
  -H "x-api-key: YOUR_API_KEY"

settings.json 改了不生效

症状：你改了 ~/.claude/settings.json，但 Claude 还是用老配置

排查：

1. VSCode 插件：必须重启 VSCode，热加载不行
2. 路径对不对？应该是 ~/.claude/settings.json（不是 .vscode/settings.json，不是 Claude Code 项目目录里的）
3. JSON 语法对不对？用 jsonlint.com 校验
4. 环境变量优先级更高：检查是不是 shell 里设了 ANTHROPIC_BASE_URL 覆盖了 settings.json

# 看 CLI 实际用什么配置
claude doctor

claude 找不到命令

症状：claude: command not found / 'claude' is not recognized

# 检查是否安装
which claude          # macOS/Linux
where claude          # Windows
npm list -g | grep claude-code

# 没有则安装
npm install -g @anthropic-ai/claude-code

PATH 没生效：

# macOS/Linux
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
$env:PATH += ";$(npm config get prefix)"

npm 全局安装 EACCES 权限错误

症状：EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

不要用 sudo。正确做法：让 npm 全局目录指向用户目录：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 加入 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 再装
npm install -g @anthropic-ai/claude-code

超时 / 卡死

症状：请求长时间无响应

curl -v https://nexor.nexoraivision.com/v1/models

unset HTTPS_PROXY HTTP_PROXY    # macOS/Linux
$env:HTTPS_PROXY=$null          # PowerShell

claude "test"

claude --model claude-sonnet-4-6 "..."

SSL 证书错误

症状：SSL_ERROR / unable to get local issuer certificate

临时绕过（不推荐生产）：

export NODE_TLS_REJECT_UNAUTHORIZED=0

正确做法：升级 Node.js / 重装 CA 证书：

# macOS
brew install ca-certificates

# Ubuntu / Debian
sudo apt update && sudo apt install -y ca-certificates && sudo update-ca-certificates

# CentOS / RHEL
sudo yum install -y ca-certificates

Windows 中文乱码

症状：终端中文显示成 ??? 或方块

临时：

chcp 65001
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

永久（写入 $PROFILE）：

notepad $PROFILE

末尾追加：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8

Windows 路径找不到 .claude 目录

症状：CC-Switch 应用后没效果，或手改 settings.json 没反应

按 Win+R → %userprofile%\.claude 直接打开。如果目录不存在，先在资源管理器手动创建一个 .claude 文件夹。

settings.json 完整路径：C:\Users\你的用户名\.claude\settings.json

VSCode 插件不识别配置

症状：终端 claude 命令能用，但 VSCode 插件提示需要登录

原因：VSCode 插件只读 ~/.claude/settings.json，不读你的 shell 环境变量。

解决：把环境变量写到 settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://nexor.nexoraivision.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

重启 VSCode 后生效。

ANTHROPIC_BASE_URL 配错（带 /v1 vs 不带）

症状：404 Not Found 或 Unknown endpoint

记住：

弄反就 404。

OpenCode 启动报错或看不到 Claude 模型

症状：opencode 启动后 anthropic provider 不显示

排查：

# macOS/Linux
cat ~/.config/opencode/opencode.json

# Windows
type %APPDATA%\opencode\opencode.json

确认：

• JSON 语法正确（jsonlint.com 校验）
• baseURL 带 /v1
• 有 "npm": "@ai-sdk/anthropic"（缺这个 OpenCode 不会加载 Anthropic SDK）

完整配置见 OpenCode 配置。

流式响应中断

症状：长回答输出到一半就停了

解决：

• 关闭中间代理 / VPN
• 切换网络（移动热点切到 WiFi）
• 降低 max_tokens（默认 4096，超长输出更易中断）
• 换更快的模型（Haiku/Sonnet）

CC-Switch 启动失败 / 闪退

症状：macOS「无法验证开发者」；Windows「保护你的电脑」

• macOS：系统设置 → 隐私与安全性 → 允许从以下位置下载的 App → 仍要打开
• Windows：「更多信息」→「仍要运行」

或在终端跑 CC-Switch（绕过 GUI 保护）看错误日志。

thinking 没生效 / Opus 不思考

症状：用 Opus 但回答跟 Sonnet 一样快、感觉没思考

排查：

• CLI 默认开 thinking，无需手动配
• 如果是用 SDK 自己写代码：检查是否传了 thinking={"type":"enabled","budget_tokens":4096}
• VSCode 插件：在 settings.json 加：

{
  "env": {
    "...": "...",
    "ANTHROPIC_THINKING_ENABLED": "true",
    "ANTHROPIC_THINKING_BUDGET": "8000"
  }
}

还没解决？