Claude Code 配置与 CC Switch 代理接入完全指南

前言

AAAI 参会的过程中有幸跟着 Dizhan 师兄学到了很多，其中一项正是对于 vibe coding（具体而言就是 Claude Code）的技巧探讨。在从古法编程转为付费的 Cursor 后笔者感受到的变化不亚于原始人掌握了工具，所以对于相关的”奇技淫巧”相当痴迷。

在折腾 Claude Code 的过程中，最大的痛点就是网络和 API 接入。由于 Claude Code 期待的是 Anthropic Messages API 行为，而很多第三方只兼容 OpenAI Chat Completions，直接配置往往会遇到各种诡异报错。经过反复踩坑，最终稳定下来的方案是：CC Switch 本地代理 → 第三方 OpenAI-compatible 上游。

本文记录从零配置到稳定使用的完整流程。

1. 为什么直连第三方上游会失败

如果直接把 Claude Code 指到第三方 OpenAI-compatible API，例如：

ANTHROPIC_BASE_URL=https://your-third-party-api
ANTHROPIC_API_KEY=...

即使这个上游本身可用，Claude Code 仍可能报错：

Unable to connect to Anthropic services
ERR_BAD_REQUEST
undefined is not an object (evaluating 'H.slice')
undefined is not an object (evaluating 'H.startsWith')

原因是 Claude Code 期待的是 Anthropic Messages API 行为，而很多第三方只兼容 OpenAI Chat Completions。CC Switch 的本地代理负责把 Claude 的 /v1/messages 请求翻译成上游能理解的 OpenAI Chat 格式。

2. 稳定架构

Claude Code CLI / VS Code 插件 → CC Switch 本地代理 (127.0.0.1:15721) → 第三方 OpenAI-compatible 上游

核心原则：

在 CC Switch 里保存真实上游地址、密钥和模型配置
让 Claude Code 只访问 http://127.0.0.1:15721
让 CC Switch 把 Claude 的 Anthropic 风格请求转换成上游 OpenAI-compatible 请求

3. 安装 CC Switch

# Linux / WSL
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-x64-musl.tar.gz
tar -xzf cc-switch-cli-linux-x64-musl.tar.gz
chmod +x cc-switch
mv cc-switch /usr/local/bin/
cc-switch --version

Windows 用户可以直接下载 GUI 版本：cc-switch releases

说明：新版本不一定有 cc-switch init。默认会使用 ~/.cc-switch/cc-switch.db。

4. 安装 Node.js 与 Claude Code

# 安装 Node.js (v22+)
mkdir -p /usr/local/lib/nodejs
curl -fsSL https://nodejs.org/dist/latest-v22.x/SHASUMS256.txt | grep 'linux-x64.tar.xz$' | awk '{print $2}' > /tmp/node-filename
NODE_FILE=$(cat /tmp/node-filename)
curl -fsSL "https://nodejs.org/dist/latest-v22.x/${NODE_FILE}" -o "/tmp/${NODE_FILE}"
tar -xJf "/tmp/${NODE_FILE}" -C /usr/local/lib/nodejs
NODE_DIR=$(tar -tf "/tmp/${NODE_FILE}" | head -n1 | cut -d/ -f1)
ln -sf "/usr/local/lib/nodejs/${NODE_DIR}/bin/node" /usr/local/bin/node
ln -sf "/usr/local/lib/nodejs/${NODE_DIR}/bin/npm" /usr/local/bin/npm
ln -sf "/usr/local/lib/nodejs/${NODE_DIR}/bin/npx" /usr/local/bin/npx

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code
claude --version

5. 在 CC Switch 中配置 Claude Provider

关键点：

应用选择 claude
Provider 类型选择第三方 / OpenAI-compatible
API 格式必须是 OpenAI Chat Completions 或 openai_chat

不要把它配置成原生 Anthropic 格式，否则代理仍可能去打上游 /v1/messages，这对很多第三方服务是错误路径。

示例模型映射：

Haiku → 轻量模型
Sonnet → 主力模型
Opus → 最强模型
Reasoning → 推理模型

6. 确认代理状态

cc-switch proxy show

重点确认：

proxy 是否已启用 (Running: yes)
Claude takeover 是否开启 (Active routes: Claude=on)
监听地址是否为 127.0.0.1:15721

7. Claude CLI 的本地代理配置

~/.claude/settings.local.json：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "proxy-placeholder",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "your-haiku-model",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-opus-model",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "your-sonnet-model",
    "ANTHROPIC_MODEL": "your-sonnet-model",
    "ANTHROPIC_REASONING_MODEL": "your-reasoning-model"
  },
  "model": "your-sonnet-model"
}

注意：

ANTHROPIC_AUTH_TOKEN 用占位值 proxy-placeholder，不要在这里放真实第三方 API Key
真实上游 Key 只保留在 CC Switch 的 provider 配置里
不要同时设置 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY，两者并存会导致认证冲突

8. 启用代理

持久启用：

cc-switch proxy enable --app claude

前台调试（可以看到实时日志）：

cc-switch proxy serve --takeover claude --listen-address 127.0.0.1 --listen-port 15721

9. 验证本地代理是否完成协议转换

curl -sS -D - http://127.0.0.1:15721/v1/messages \
  -H 'content-type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'x-api-key: proxy-placeholder' \
  -d '{"model":"your-sonnet-model","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

如果代理正常，应返回 Anthropic 风格结构（type: "message", role: "assistant", content: [...]），且 HTTP 状态码为 200。

10. 给 claude 加自动拉起代理的包装脚本

建议创建一个包装脚本，在调用 Claude 时自动检测并拉起代理：

读取 ~/.claude/settings.local.json
导出其中的 env
如果 ANTHROPIC_BASE_URL=http://127.0.0.1:15721 且本地端口未监听
自动后台启动 cc-switch proxy serve --takeover claude
再调用真实 Claude 二进制

约定路径示例：

包装脚本：/usr/local/bin/claude
真实二进制：/usr/local/bin/claude.real
代理日志：~/.cc-switch/logs/claude-proxy.log

这样日常只需要执行 claude 即可。

11. VS Code 插件配置

11.1 本地

VS Code settings.json：

{
  "claudeCode.environmentVariables": [
    { "name": "DISABLE_TELEMETRY", "value": "1" },
    { "name": "DO_NOT_TRACK", "value": "1" },
    { "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "value": "1" },
    { "name": "OTEL_TRACES_EXPORTER", "value": "none" },
    { "name": "OTEL_METRICS_EXPORTER", "value": "none" },
    { "name": "OTEL_LOGS_EXPORTER", "value": "none" },
    { "name": "IS_SANDBOX", "value": "1" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "proxy-placeholder" },
    { "name": "ANTHROPIC_BASE_URL", "value": "http://127.0.0.1:15721" },
    { "name": "ANTHROPIC_MODEL", "value": "your-sonnet-model" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "your-sonnet-model" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "your-haiku-model" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "your-opus-model" },
    { "name": "ANTHROPIC_REASONING_MODEL", "value": "your-reasoning-model" }
  ],
  "claudeCode.claudeProcessWrapper": "/usr/local/bin/claude",
  "claudeCode.disableLoginPrompt": true,
  "claudeCode.allowDangerouslySkipPermissions": true
}

关键设置：

claudeCode.claudeProcessWrapper — 指向包装脚本，让插件也走 CC Switch 代理
claudeCode.disableLoginPrompt — 设为 true 跳过登录
注意是 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY

11.2 SSH 服务器

连接远程服务器时，需要配置网络代理。完整方案见远程连接服务器时的 AI 编程工具实践。简要来说：

{
  "claudeCode.environmentVariables": [
    { "name": "HTTP_PROXY", "value": "http://127.0.0.1:7898" },
    { "name": "HTTPS_PROXY", "value": "http://127.0.0.1:7898" },
    { "name": "ANTHROPIC_BASE_URL", "value": "http://127.0.0.1:15721" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "proxy-placeholder" }
  ],
  "claudeCode.disableLoginPrompt": true
}

12. VS Code 插件改完后的操作

修改完 VS Code 设置后，执行：

Developer: Reload Window（Ctrl+Shift+P 搜索）
重新打开 Claude Code 插件面板
发送一条消息做验证

如果 VS Code 插件仍未走代理

优先检查 Claude VSCode.log，重点看：

Claude 启动路径是否已切换到 claudeProcessWrapper
日志里是否还残留直连上游的痕迹

常见报错及含义：

spawn /usr/local/bin/claude ENOENT — 包装脚本路径在设置里存在，但磁盘上没有这个文件或不可执行
401 {"error":{"message":"Invalid Token"...}} — 已经走到本地代理，但 CC Switch 里保存的真实上游 key 错了（不是插件需要重新登录，而是上游鉴权失败）

13. 常用排查命令

cc-switch --version
claude --version
cc-switch --app claude provider current
cc-switch proxy show
tail -n 50 ~/.cc-switch/logs/claude-proxy.log
cc-switch env check --app claude
cc-switch env list --app claude
env | grep '^ANTHROPIC_' | sort
sqlite3 ~/.cc-switch/cc-switch.db "select id,is_current,meta,settings_config from providers where app_type='claude';"

如果代理卡住：

pkill -f 'cc-switch proxy serve --takeover claude'
claude

14. 额外注意：HTTP 代理变量

如果机器上还有：

HTTP_PROXY=http://127.0.0.1:7898
HTTPS_PROXY=http://127.0.0.1:7898

它会影响 curl 等直连测试，但不一定和 Claude Code / CC Switch 的表现完全一致。排查时不要只看上游直连测试，要同时确认：

cc-switch proxy show 的状态
http://127.0.0.1:15721/v1/messages 的本地代理响应

15. 关键文件

文件	用途
`~/.cc-switch/cc-switch.db`	CC Switch 状态库
`~/.claude/settings.local.json`	Claude 本地代理配置
`~/.claude/settings.json`	Claude 用户配置
`~/.claude.json`	Claude 运行元数据
`/usr/local/bin/claude`	包装脚本
`~/.cc-switch/logs/claude-proxy.log`	代理日志

16. 新服务器迁移顺序

安装 CC Switch
安装 Node.js
安装 Claude Code
在 CC Switch 中添加 Claude provider
确保 provider 是 OpenAI-compatible 且 API 格式为 openai_chat
把 ~/.claude/settings.local.json 改成本地代理模式
启用 CC Switch 代理
配置 claude 包装脚本自动拉起代理
在 VS Code 中设置 claudeCode.claudeProcessWrapper
在 VS Code 中注入代理模式环境变量
Developer: Reload Window
分别验证 CLI 和插件

最终规则

如果 Claude Code 需要使用第三方 OpenAI-compatible 上游，不要采用直连模式。

始终使用：Claude Code CLI / VS Code 插件 → CC Switch 本地代理 → 第三方上游

真实 API Key 只保留在 CC Switch 的 provider 配置中，不要在 Claude Code 的任何配置文件里写入真实密钥。