Claude Code 手动配置与排错

安装与基础配置走控制台一键配置；本页只说明需要手改的补充项、环境变量与排错。

基础配置由控制台生成

~/.claude/settings.json 里的 Base URL、API Key 与模型别名不用手写：登录控制台 → API 密钥 页 → 某把 key 右侧点 ⋮ → ★ 一键配置 → 选 Claude Code 与你的系统，第 ③ 步的「配置文件」就是可以直接落盘的完整内容（模型映射、默认档、思考档、上下文窗口按你在第 ② 步的选择生成）。

Claude Code 的 Base URL 不需要 /v1 后缀（Codex 相反，需要 /v1）。

下面几节只处理基础配置之外还要补的东西。

AWS 分组出现 400 时的补充项

如果使用 AWS 分组时出现 400，且报错与请求内容无关，可在 settings.json 的 env 中一并加入：

json

{
"env": {
"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
}
}

保存 ~/.claude/settings.json 后，重新打开终端再启动 claude 生效。

完整排障说明见请求返回 400，含实验性 Beta 参数。

系统环境变量（配置不生效时先查这里）

ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 这类系统环境变量的优先级高于 settings.json。一键配置只写 settings.json，不碰环境变量 —— 所以「明明一键配置过却没生效」基本都在这里：如果曾为别的地方手写过（Windows 的「用户变量」、macOS / Linux 的 ~/.zshrc / ~/.bashrc），旧地址或旧 key 会盖掉新值，典型症状是启动后仍连旧地址、报 401 或反复要求认证。早前教程里写的 ANTHROPIC_API_KEY 也要一并清掉：它走 x-api-key 头，会触发 Claude Code 的「Detected a custom API key」批准弹窗，选 No 之后每次发消息都报 Not logged in（控制台现在只写走 Authorization: Bearer 的 ANTHROPIC_AUTH_TOKEN）。

排错三步：

查当前会话里有没有这些变量：Linux / macOS env | grep -i anthropic，PowerShell Get-ChildItem env: | Where-Object Name -like 'ANTHROPIC*'
有就核对值是否与控制台的 Base URL、当前 key 一致；不一致就删掉，或改成正确值
重启终端（Windows 要重启所有终端窗口）再启动 claude

同样的道理适用于 CC Switch：它写的是配置文件，系统环境变量仍然盖在上面。

常见问题

启动时要求认证？

确认 settings.json 里的 Base URL 与 API Key 是控制台当前的值（最省事的做法：重新点一次「★ 一键配置」覆盖），并重启终端；如果上一节查到了旧的同名系统环境变量，一并清掉。

CC Switch 切换后不生效？

重启 Claude Code
检查系统环境变量是否覆盖了 CC Switch 写入的配置（环境变量优先级更高）
必要时删除 ~/.claude 目录后重新配置

API 连接错误？

检查 Base URL 格式（Claude Code 不需要 /v1 后缀）
验证 Token 有效性（未过期、有余额）
尝试切换其他 API 线路

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

如果你当前使用的是支持长缓存的 enterprise / 专用分组，可在 CC Switch 的自定义环境变量，或 ~/.claude/settings.json 的 env 中追加：

json

{
"env": {
"ENABLE_PROMPT_CACHING_1H": "1"
}
}

建议理解这两个取舍：

配置	适用场景
默认短缓存	高频、重建频繁、成本敏感的日常使用
`ENABLE_PROMPT_CACHING_1H=1`	需要更长缓存保留时间的长链路任务

如果你的使用强度很高，通常仍建议优先选择更短缓存策略；1 小时缓存的重建成本更高。

如何切回官方渠道并重新 OAuth？

适用于：

个人用户切到官方 Claude Code 渠道
旧中转配置残留导致官方登录状态混乱
想彻底清理本地旧环境后重新登录

建议流程如下：

先备份 ~/.claude 与 ~/.claude.json
清理旧会话、历史与认证残留
在 CC Switch 中切换到官方渠道
重新执行 claude，按 OAuth 流程登录

macOS / Linux

bash

mkdir -p ~/claude_backup_$(date +%Y%m%d)
cp -r ~/.claude ~/claude_backup_$(date +%Y%m%d)/
cp ~/.claude.json ~/claude_backup_$(date +%Y%m%d)/ 2>/dev/null || true
rm -rf ~/.claude/backup ~/.claude/history.jsonl ~/.claude/plans \\
~/.claude/projects ~/.claude/session-env ~/.claude/sessions \\
~/.claude/telemetry
rm -f ~/.claude.json
ccswitch
claude

Windows PowerShell

powershell

$backup = "$env:USERPROFILE\\\\claude_backup_$(Get-Date -Format yyyyMMdd)"
New-Item -ItemType Directory -Force $backup | Out-Null
if (Test-Path "$env:USERPROFILE\\\\.claude") { Copy-Item "$env:USERPROFILE\\\\.claude" $backup -Recurse }
if (Test-Path "$env:USERPROFILE\\\\.claude.json") { Copy-Item "$env:USERPROFILE\\\\.claude.json" $backup }
Remove-Item "$env:USERPROFILE\\\\.claude\\\\backup" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude\\\\history.jsonl" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude\\\\plans" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude\\\\projects" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude\\\\session-env" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude\\\\sessions" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude\\\\telemetry" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\\\\.claude.json" -Force -ErrorAction SilentlyContinue
ccswitch
claude

如果只是从“官方 OAuth”切回“中转 API”，不需要整套清理流程，优先看 OAuth 登录冲突导致 API Key 失效。

如何节省 Token？

创建 Token 时启用上下文缓存（缓存倍率低至 0.12，最多节省 90%）
对话中使用 /compact 压缩上下文
在 CLAUDE.md 中提供项目上下文，减少重复描述

国内网络：这几项一键配置已经写好

国内网络下 skipWebFetchPreflight 与 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 必须设置 ，否则会导致联网搜索功能异常或产生额外 Token 泄漏 —— 这两项一键配置会直接写进 settings.json，不需要另外手改。只有手工维护配置时才需要自己补：

字段	说明
`skipWebFetchPreflight`（顶层）	跳过向 `claude.ai` 发起的预检请求，不设置会导致联网/WebFetch 功能完全失效
`env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	关闭遥测、更新检查等非必要流量
`env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`	AWS 分组返回 400 时，关闭实验性 Beta 参数注入
`ENABLE_TOOL_SEARCH`（顶层，可选）	减少工具调用时的 Token 泄漏

skipWebFetchPreflight 问题的完整说明见 WebFetch 报错。

Claude Code 手动配置与排错 ​

基础配置由控制台生成 ​

AWS 分组出现 400 时的补充项 ​

系统环境变量（配置不生效时先查这里） ​

常见问题 ​

启动时要求认证？ ​

CC Switch 切换后不生效？ ​

API 连接错误？ ​

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

如何切回官方渠道并重新 OAuth？ ​

macOS / Linux ​

Windows PowerShell ​

如何节省 Token？ ​

国内网络：这几项一键配置已经写好 ​