Claude Code 配置

特别说明： AI 工具迭代速度极快。遇到报错时，建议先将 Claude Code、Codex CLI、CC-Switch 等工具更新到最新版本，新版通常已修复已知问题，也能避免旧版本特有的奇怪报错。

安装

npm（全平台）：

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

macOS（Homebrew）：

brew install --cask claude-code

Windows（WinGet）：

winget install Anthropic.ClaudeCode

原生安装脚本：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

验证：claude --version

安装排障

permission denied / EACCES（Mac/Linux）： 不要使用 sudo，把 npm 全局目录改到用户目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc  # zsh 改为 ~/.zshrc
source ~/.bashrc

Windows PowerShell：

npm config set prefix "$env:APPDATA\npm"
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

command not found: claude： 执行 npm config get prefix 查看路径，将对应的 bin 目录追加到系统 PATH。

配置 API Key

方式一：CC-Switch（推荐）

一键配置，无需手动编辑文件。RovoAPI 官网 API Key 页面提供「接入 CC-Switch」按钮，点击即自动写入配置。

使用指南见 CC-Switch 配置指南。

方式二：settings.json

编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.rovoapi.com",
    "ANTHROPIC_API_KEY": "sk-rovo-你的Key"
  }
}

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

方式三：系统环境变量

Windows（PowerShell 管理员）：

setx ANTHROPIC_BASE_URL "https://api.rovoapi.com"
setx ANTHROPIC_API_KEY "sk-rovo-你的Key"

macOS / Linux：

echo 'export ANTHROPIC_BASE_URL="https://api.rovoapi.com"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-rovo-你的Key"' >> ~/.zshrc
source ~/.zshrc

首次启动排障

Unable to connect to Anthropic services

首次执行 claude 报无法连接 Anthropic services。

修复： 用文本编辑器打开 ~/.claude.json（Windows 为 C:\Users\用户名\.claude.json），在最外层 JSON 中添加：

"hasCompletedOnboarding": true

完整示例：

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

验证格式：

cat ~/.claude.json | python3 -m json.tool

OAuth 登录冲突

登录过官方账号后，OAuth 令牌会写入 ~/.claude.json，优先级高于 settings.json 中的 API Key。

修复：

# 退出 OAuth 登录
claude auth logout

# 写入中转 API 配置
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-rovo-你的Key",
    "ANTHROPIC_BASE_URL": "https://api.rovoapi.com"
  }
}
EOF

# 重新启动 claude

环境变量优先级

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

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

常用命令

| 命令 | 作用 | |------|------| | /model | 切换模型 | | /model sonnet[1m] | 切换 1M 超长上下文版本 | | /cost | 查看当前令牌用量 | | /compact | 压缩上下文，释放空间 | | /resume | 恢复历史对话 | | /clear | 清空当前对话 | | /help | 查看所有命令 | | /hint | 显示随机使用技巧 / 提示 | | /exit 或 Ctrl+C x2 | 退出 |

settings.json 完整参考

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.rovoapi.com",
    "ANTHROPIC_API_KEY": "sk-rovo-你的Key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"
  },
  "skipWebFetchPreflight": true,
  "ENABLE_TOOL_SEARCH": true
}

| 配置项 | 说明 | |--------|------| | CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS | 关闭实验性 Beta 请求头（AWS 分组返回 400 时启用） | | CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | 关闭遥测、更新检查等非必要流量 | | ENABLE_PROMPT_CACHING_1H | 启用 1 小时上下文缓存（长链路任务建议开启） | | CLAUDE_CODE_MAX_OUTPUT_TOKENS | 调高单次回复上限（默认 32000） | | skipWebFetchPreflight | 跳过向 claude.ai 的预检请求（国内网络必开） | | ENABLE_TOOL_SEARCH | 减少工具调用时的 Token 泄漏 |