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，点击"添加配置"
2. 在预设供应商列表中点击 Micu（Base URL 已自动填入）
3. 填写 API Key（sk-xxx）
4. 点击添加，应用后重启终端

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

---

配置方式二：配置文件

手动编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.micuapi.ai",
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}

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

AWS 分组出现 400 时的补充项

如果使用 AWS 分组时出现 400，且报错与请求内容无关，可在全局配置文件中一并加入：

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

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

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

---

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

Windows

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

变量名：ANTHROPIC_BASE_URL
变量值：https://www.micuapi.ai

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

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

PowerShell 一键写入：

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

macOS / Linux

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

export ANTHROPIC_BASE_URL=https://www.micuapi.ai
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. 验证 Token 有效性（未过期、有余额）
3. 尝试切换其他 API 线路

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

如果你当前使用的是支持长缓存的 enterprise / 专用分组，可在 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. 创建 Token 时启用上下文缓存（缓存倍率低至 0.12，最多节省 90%）
2. 对话中使用 /compact 压缩上下文
3. 在 CLAUDE.md 中提供项目上下文，减少重复描述

---

国内网络必做配置

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

写入 ~/.claude/settings.json：

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

如果你使用 AWS 分组且遇到 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	AWS 分组返回 400 时，关闭实验性 Beta 参数注入

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

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