Claude Code 配置参考

本页用于手动配置、环境变量排查和高级自定义。日常使用默认推荐先看 CC Switch 统一配置。

安装方式

原生安装脚本

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

包管理器

Homebrew (macOS)

brew install --cask claude-code

WinGet (Windows)

winget install Anthropic.ClaudeCode

npm

全平台通用，安装后命令名为 claude：

npm install -g @anthropic-ai/claude-code

官方当前推荐优先使用原生安装脚本；原生安装支持后台自动更新。brew、winget、npm 适合已有对应工具链的环境，但需要手动升级。

Windows 原生环境需要先安装 Git for Windows；WSL 环境不需要。

配置方式一：CC Switch（默认推荐）

CC Switch 是最简单的配置方式，可视化操作，无需手动编辑任何文件。完整步骤见 CC Switch 统一配置。

配置步骤：

1. 打开 CC Switch，点击「添加配置」，框架选 Claude Code。
2. 预设供应商选 「自定义配置」，请求地址填 https://www.vmvia.com。
3. 填写 API Key（sk-xxx），模型留空。
4. 点击添加，启用后重启终端。

CC Switch 会自动将配置写入 ~/.claude/settings.json。如果只是日常使用，到这里即可。

配置方式二：配置文件

手动编辑 ~/.claude/settings.json（Windows 为 %USERPROFILE%\.claude\settings.json）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.vmvia.com",
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}

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

出现与内容无关的 400 时的补充项

如果请求返回 400 且报错与内容无关，可在全局配置文件中一并加入：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.vmvia.com",
    "ANTHROPIC_API_KEY": "sk-xxx",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

保存后，重新打开终端再启动 claude 生效。完整排障说明见 CC-006：请求返回 400，含实验性 Beta 参数。

配置方式三：系统环境变量

Windows

1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 在用户变量中分别新建：

变量名：ANTHROPIC_BASE_URL
变量值：https://www.vmvia.com

变量名：ANTHROPIC_API_KEY
变量值：sk-xxx

3. 保存后重启所有终端窗口

PowerShell 一键写入：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://www.vmvia.com", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-xxx", "User")

macOS / Linux

在 ~/.zshrc 或 ~/.bashrc 中添加：

export ANTHROPIC_BASE_URL=https://www.vmvia.com
export ANTHROPIC_API_KEY=sk-xxx

执行 source ~/.zshrc 或重启终端生效。

注意：系统环境变量的优先级高于 settings.json 和 CC Switch 的配置。若 CC Switch 切换后不生效，优先检查是否存在同名环境变量覆盖。

常见问题

启动时要求认证？

确保已配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，并重启终端。

CC Switch 切换后不生效？

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

API 连接错误？

1. 检查 Base URL 格式（Claude Code 不需要 /v1 后缀）
2. 验证令牌有效性（未过期、有余额、分组为 cc_max）
3. 主站不通时改用国内优化线路 https://api.vmvia.com

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

可在 CC Switch 的自定义环境变量，或 ~/.claude/settings.json 的 env 中追加：

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

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

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

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

适用于：

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

建议流程如下：

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

macOS / Linux

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

$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」，不需要整套清理流程，优先看 CC-018：OAuth 登录冲突导致 API Key 失效。

如何节省 Token？

1. 上下文缓存命中的部分按缓存价计费（cc_max 下约为输入价的 1/10），长会话收益明显
2. 对话中使用 /compact 压缩上下文
3. 在 CLAUDE.md 中提供项目上下文，减少重复描述

国内网络必做配置

以下配置在国内网络环境下建议设置，否则可能导致联网搜索功能异常或产生额外 Token 泄漏。

写入 ~/.claude/settings.json：

{
  "ENABLE_TOOL_SEARCH": true,
  "skipWebFetchPreflight": true,
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.vmvia.com",
    "ANTHROPIC_API_KEY": "sk-xxx",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

如果遇到与内容无关的 400，可在同一处继续追加：

"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"

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

skipWebFetchPreflight 问题的完整说明见 CC-017。

不要额外加入 "skipAutoPermissionPrompt": true。该字段会导致 Plan 模式无法执行，见 CC-023。