CCTQ-Doc

简体中文

English

简体中文

English

主题

认证与 API Key 类问题 ​

401 Invalid API Key / 无效令牌 ​

现象：终端返回 401 invalid x-api-key。

原因：ANTHROPIC_BASE_URL 未配置或配置错误，请求打到了官方端点。

修复：确认 ~/.claude/settings.json 中正确配置了 Base URL 和 API Key：

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的请求地址",
    "ANTHROPIC_API_KEY": "sk-***"
  }
}

注意：Claude Code 的 Base URL 不需要 /v1 后缀。

401 无效令牌 — IDE 或 MCP 覆盖了配置 ​

现象：API Key 填写正确，但持续 401。常见于安装了 Cursor、Continue 等 IDE 插件后。

原因：IDE 插件或 MCP 服务器覆盖了 settings.json 中的 apiKey / baseURL 字段。

修复方案（三选一）：

  • 推荐：用 CC Switch 重新配置，一键覆盖被修改的配置
  • 手动修复：检查并修正 ~/.claude/settings.json 中被覆盖的字段
  • 环境变量：通过系统环境变量设置 API Key 和 Base URL（优先级高于配置文件，不易被覆盖）

预防：安装新 IDE 插件或 MCP 后，重新验证 Claude Code 连通性。

切换服务后 401 无效令牌 ​

现象：曾使用其他中转服务，切换后新配置已填写正确但仍报 401。

原因：旧服务遗留了系统环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_API_TOKEN），环境变量优先级高于配置文件。

Windows 修复：按 Win + R → 输入 sysdm.cpl → 高级 → 环境变量，在「用户变量」和「系统变量」中分别删除 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_API_TOKEN。保存后重新打开终端。如仍报错，删除以下配置文件后用 CC Switch 重新配置：

C:\Users\用户名\.claude\claude.json
C:\Users\用户名\.claude\claude.json.backup

Mac / Linux 修复：编辑 ~/.zshrc 或 ~/.bashrc，找到并删除以 export ANTHROPIC_ 开头的旧行，执行 source ~/.zshrc 后重启终端。

OAuth 登录冲突导致 API Key 失效 ​

现象：曾在终端通过 claude 完成官网 OAuth 登录，切换到中转 API 后，配置被忽略，请求直连 api.anthropic.com，在服务器环境（CentOS / Ubuntu）尤为常见。

原因：~/.claude.json 中写入了 OAuth 令牌（primaryApiKey / oauthToken），优先级高于 settings.json 中的 API Key。

修复步骤：

bash
# 第一步：退出 OAuth 登录
claude auth logout

# 第二步：写入中转 API 配置
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-你的API密钥",
    "ANTHROPIC_BASE_URL": "https://你的请求地址"
  }
}
EOF

# 第三步：验证配置写入成功
cat ~/.claude/settings.json

# 第四步：重新启动
claude

预防：服务器环境初次运行 claude 前先写好 settings.json，避免触发 OAuth 流程。

401 Invalid API Key format — Key 含不可见字符 ​

现象：Key 目视正确但仍报 401 或 Invalid format。

原因：从 PDF / 网页 / 截图复制 Key 时混入零宽空格、不换行空格、\r 等不可见字符，或 OCR 将相似字符误读（0/O、1/l/I）。

检测方法：

bash
echo "$ANTHROPIC_API_KEY" | cat -A
# 正常：行尾只有 $
# 异常：出现 ^M$ 或其他多余字符

修复：从控制台的「复制」按钮重新获取 Key，不要手动输入或经由 PDF / 截图中转。环境变量赋值不加引号：

bash
export ANTHROPIC_API_KEY=sk-ant-api03-你的key

403 Missing API Key / 配置冲突 ​

原因：配置文件被意外修改或多处配置冲突。

修复：推荐用 CC Switch 重新写入配置，覆盖被修改的文件。

启动时要求认证 / 弹出登录提示 ​

确保已配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，并重启终端（关闭整个终端窗口重新打开，不是新建标签页）。

环境变量优先级说明 ​

优先级从高到低：系统环境变量 > ~/.claude.json（OAuth 令牌）> ~/.claude/settings.json（CC Switch 写入）。

排障时如果修改 settings.json 不生效，优先检查是否存在更高优先级的环境变量或 OAuth 残留。

Copyright © 2026 CCTQ-Doc