CCTQ-Doc

简体中文

English

简体中文

English

主题

Claude Code 专项问题 ​

首次启动即报 Unable to connect to Anthropic services ​

现象：Claude Code 安装后第一次执行 claude，终端打印以下错误并退出：

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Please check your internet connection and network settings.

修复：按你的系统打开配置文件 ~/.claude.json：

text
按下键盘 Win + R，输入以下内容后回车（用记事本打开）：

notepad %userprofile%\.claude.json
bash
# 用默认文本编辑器打开
open -e ~/.claude.json
bash
# 用终端编辑器打开
nano ~/.claude.json

在最外层 JSON 对象中添加：

json
"hasCompletedOnboarding": true

完整写法参考：

json
{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "...",
  "projects": { },
  "hasCompletedOnboarding": true
}

注意 projects 字段末尾的 } 后面要加英文逗号 ,，否则 JSON 格式非法。保存后可用以下命令验证格式：

powershell
Get-Content $env:USERPROFILE\.claude.json -Raw | ConvertFrom-Json
bash
cat ~/.claude.json | python3 -m json.tool

无报错即格式正确，重新执行 claude 进入交互界面。

401 Invalid API Key / 无效令牌 ​

终端返回 401 invalid x-api-key，通常由以下情况之一导致，按场景逐一排查。

情况一：Base URL 未配置或配置错误 ​

原因：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 后缀。

情况二：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。

原因：旧服务遗留了系统环境变量（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 残留。

Claude Code 切回 200K 上下文 ​

如需关闭 1M 上下文、切回 200K，在 ~/.claude/settings.json（Windows 为 C:\Users\用户名\.claude\settings.json）的 env 中添加以下字段。Windows / macOS / Linux 配置一致：

json
{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

保存后重启终端生效。

WebFetch 联网功能失效 ​

现象：调用 WebFetch 工具抓取网页时报错，目标网站手动用浏览器访问完全正常，代理已开启全局模式。

原因：Claude Code 在抓取目标页面前会先向 https://claude.ai/api/web/domain_info 发预检请求，国内网络 / 企业防火墙拦截 claude.ai 导致预检失败，WebFetch 整体报错。

修复：在 ~/.claude/settings.json（Windows 为 C:\Users\用户名\.claude\settings.json）中添加：

json
"skipWebFetchPreflight": true

若已有其他配置，合并写入：

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

保存后重启 Claude Code 即可跳过预检直接请求目标页面。

Permission denied — 文件读写被拒绝 ​

三种独立原因，需分别判断：

  • 原因 A — 系统层权限不足：执行 ls -la /path/to/file 查看权限位，用 chmod 644（文件）或 chmod 755（目录）修复
  • 原因 B — Claude Code 权限设置：用户曾选择「总是拒绝」该类操作，按 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Windows/Linux）搜索 Claude: Manage Permissions，将对应规则改为「询问」或「允许」
  • 原因 C — .claudeignore 规则误匹配：执行 cat .claudeignore 检查是否有 glob 规则误匹配到目标文件，删除或精确化有问题的规则

预防：.claudeignore 使用精确路径而非宽泛通配符，定期检查 Permission 设置中的「总是拒绝」规则，项目目录权限保持 644（文件）/ 755（目录）。

skipAutoPermissionPrompt 导致 Plan 模式失效 ​

现象：在 settings.json 中加入 "skipAutoPermissionPrompt": true 后 Plan 模式无法执行，移除该字段后恢复。

修复：打开 ~/.claude/settings.json，删除 skipAutoPermissionPrompt 整行，保存后重启终端。

预防：仅添加文档中明确标注用途的配置项，调整权限相关配置后先做一次基础功能验证。

如何理解 Claude Code 的 Permission 机制？ ​

Claude Code 对文件操作、shell 命令执行等动作有权限确认机制。首次触发时会弹出询问，可选择「允许一次」「总是允许」「总是拒绝」。如果误选了「总是拒绝」，后续该类操作会直接被阻断，需要到 Permission 管理界面手动修改。

如何启用 1 小时上下文缓存？ ​

适用于支持长缓存的专用分组，在 ~/.claude/settings.json 的 env 中添加：

json
"ENABLE_PROMPT_CACHING_1H": "1"

注意取舍：1 小时缓存的重建成本更高，高频使用场景通常建议保持默认短缓存。只有长链路任务才建议开启。

为什么选了大模型，日志里却出现了 mini / Haiku 小模型的调用？ ​

现象：明明选用了主力大模型（如 gpt-5.6-sol / Claude Opus），但请求日志里混着一些小模型的调用。Claude Code 和 Codex 都会出现这种情况：

  • Claude Code → 后台杂活用 Haiku 小模型
  • Codex → 后台杂活用 gpt-5-mini 这类小模型

这通常是正常现象，不是降级或偷换。两个工具都把「主对话」和「后台辅助小任务」分开用不同模型，以省钱提速：

  • 主模型：只用来回答你真正的问题
  • 小模型（mini / Haiku）：自动处理不值得用贵模型的杂活，例如：
    • 生成对话标题 / 小标题
    • 自动总结、会话摘要、/compact 压缩历史记录
    • 意图识别、工具路由判断
    • Agent 内部的中间规划步骤、自动补全

如何确认是否正常：

  1. 查看那条 mini 请求的内容——若 prompt 是「起个标题」「总结一下」这类，即辅助任务，完全正常
  2. 查看你真正的提问那条请求命中的模型——只要主回答走的是你选的大模型即可

重复创建缓存导致单场重复收费 ​

现象：同一场请求过程中出现重复创建缓存，被重复计费。首字时间超过 30 秒可优先怀疑此问题。

原因：备用负载切号后二次转发携带相关请求头，导致请求被误路由并重复创建缓存。

修复步骤：

  1. 确认现象是否匹配：回看请求链路，确认是否存在同一场请求重复创建缓存以及首字时间明显超过 30 秒
  2. 取消 ccs 代理，避免请求经过会触发备用负载切号的中间层
  3. 如需保留转发链路，逐项检查二次转发时透传的请求头，去掉导致误路由的请求头
  4. 重新发起一场独立请求验证

预防：保持请求链路单一稳定，二次转发时只保留必需请求头。

如何查看当前令牌用量？ ​

在 Claude Code 交互界面输入 /cost 查看当前会话的令牌用量。

Copyright © 2026 CCTQ-Doc