Claude Code 国内接入教程：cc-switch 一键切换 API 配置（2026最新）

三步完成 Claude Code 国内直连配置 | 无需代理 | 延迟 < 200ms | 支持支付宝/微信充值

看完本文你将学会

• ✅ 为什么国内直连 Claude Code 会失败，以及根本解决方案
• ✅ 如何安装并使用 cc-switch 管理多套 Claude API 配置
• ✅ 如何通过 ClaudeAPI.com 实现国内直连，无需代理
• ✅ 如何一条命令在「国内直连」和「官方 API」之间自由切换
• ✅ 如何用 cc-switch test 验证 API 连通性，快速排查故障
• ✅ 如何通过 cc-switch Web 界面可视化管理所有配置

前言：为什么国内开发者需要 cc-switch？

Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI，国内开发者使用时面临两个核心痛点：

1. 直连 api.anthropic.com 超时或失败（GFW 拦截）
2. 切换不同 API 配置（比如官方 Key 和中转 Key）时需要手动修改 settings.json，操作繁琐

cc-switch 完美解决上述问题：它是专为 Claude Code 设计的配置管理工具，支持保存多套 API 配置，一条命令即可切换，立即生效，无需重启。

配合 ClaudeAPI.com 国内直连接入点，彻底告别代理依赖。

前置条件：Node.js 18+ 已安装。 如果你还没有 ClaudeAPI.com 的 API Key，访问 claudeapi.com 扫码联系微信客服，几分钟即可获取。

三步概览

Step 1：安装工具

安装 cc-switch

cc-switch 是 npm 包，全局安装后可在任意目录使用：

npm install -g @hobeeliu/cc-switch
cc-switch --version   # 应输出: cc-switch version 1.1.1

npm install -g @hobeeliu/cc-switch
cc-switch --version   # 应输出: cc-switch version 1.1.1

[图1：npm install -g @hobeeliu/cc-switch 安装成功，版本 1.1.1]

安装 Claude Code

如果你还没有安装 Claude Code，同样通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code
claude --version   # 应输出: 2.1.89 (Claude Code)

npm install -g @anthropic-ai/claude-code
claude --version   # 应输出: 2.1.89 (Claude Code)

[图2：npm install -g @anthropic-ai/claude-code 安装成功，版本 2.1.89]

提示：Claude Code 本身免费安装，调用 API 时按 Token 计费。使用 ClaudeAPI.com 支持支付宝/微信/人民币充值，无需境外信用卡。

Step 2：初始化 ClaudeAPI.com 配置

cc-switch init 会引导你创建第一个配置文件（默认名为 default），并写入 Claude Code 的配置目录。

cc-switch init

cc-switch init

依次输入以下信息：

[图3：cc-switch init 初始化过程，配置 ClaudeAPI.com 接入点]

cc-switch 将配置写入 ~/.claude/profiles/ 目录（如 ~/.claude/profiles/default.json），并在切换时自动覆盖 ~/.claude/settings.json。你不需要手动修改任何配置文件。

验证初始化结果

初始化完成后，用以下命令确认配置已生效：

cc-switch list      # 查看所有配置
cc-switch current   # 查看当前激活的配置
cc-switch view default  # 查看 default 配置的详细内容

cc-switch list      # 查看所有配置
cc-switch current   # 查看当前激活的配置
cc-switch view default  # 查看 default 配置的详细内容

[图4：cc-switch list / current / view — 确认 default 配置已创建并激活]

Step 3：切换配置并启动 Claude Code

cc-switch use default
claude

cc-switch use default
claude

[图5：cc-switch use default 切换成功，claude 命令启动并验证 API 连接正常]

启动后可以看到 Claude Code 使用的 API 地址是 api.claudeapi.com，响应时间 < 200ms，无需代理。

原理解析：cc-switch 做了什么？

Claude Code 通过读取 ~/.claude/settings.json 里的 env 字段来获取 API 配置：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的Key",
    "ANTHROPIC_BASE_URL": "https://api.claudeapi.com"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的Key",
    "ANTHROPIC_BASE_URL": "https://api.claudeapi.com"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

cc-switch 在你执行 use 命令时，自动将对应配置写入这个文件，实现即时切换，无需重启 Claude Code。

[图6：settings.json 切换前后对比 — 官方地址 vs ClaudeAPI.com 国内直连地址]

进阶：多配置管理

实际使用中，你可能需要维护多套配置：

• default：ClaudeAPI.com 日常开发（低延迟，无需代理）
• official：官方 API 备用（海外环境或官方 API 测试）

新建官方 API 备用配置

cc-switch new official -i

cc-switch new official -i

交互式输入：

[图7：cc-switch new official -i — 新建官方 API 备用配置]

一键切换

cc-switch use official   # 切换到官方 API
cc-switch use default    # 切回 ClaudeAPI.com 国内直连

cc-switch use official   # 切换到官方 API
cc-switch use default    # 切回 ClaudeAPI.com 国内直连

[图8：cc-switch use 一键切换 — 在 ClaudeAPI.com 和官方 API 之间自由切换]

[图9：多配置最终状态 — default（日常）和 official（备用）两套配置并存]

连通性测试：cc-switch test

切换配置后，可以用 cc-switch test 快速验证当前 API 是否可以正常连接：

cc-switch test -c          # 测试当前激活的配置（最常用）
cc-switch test default     # 测试指定名称的配置
cc-switch test --all       # 测试所有配置

cc-switch test -c          # 测试当前激活的配置（最常用）
cc-switch test default     # 测试指定名称的配置
cc-switch test --all       # 测试所有配置

[图10：cc-switch test -c — 测试当前配置，三步验证（连通/鉴权/Chat API）全部通过，响应 187ms]

测试过程包含三步验证：

1. 基础连通性
2. API 鉴权
3. Chat 实际调用

推荐每次切换配置后都运行 cc-switch test -c，这是排查连接问题的第一步。

cc-switch 常用命令速查

使用 Web 界面管理配置（推荐新手）

cc-switch 提供可视化 Web 管理界面，比命令行更直观，尤其适合首次添加配置或更换 API Key 时使用。

启动 Web 界面

cc-switch web

cc-switch web

执行后自动在浏览器打开 CC Switch 可视化界面，主页显示当前所有配置及状态。

[图11：cc-switch web 主界面 — 显示当前激活的配置（使用中标记），右上角"+"添加新配置]

添加 ClaudeAPI.com 配置

点击右上角橙色"+"按钮，进入"添加新供应商"页面：

[图12：添加新供应商 — 选择"自定义配置"，或直接选预设供应商模板]

选择"自定义配置"，填写以下字段：

[图13：填写供应商名称和 API Key — API Key 填写后下方配置会自动填充]

[图14：填写请求地址 https://api.claudeapi.com — 注意提示"不要以斜杠结尾"]

[图15：配置 JSON 预览及高级选项 — 勾选"写入通用配置"可同步到全局 settings.json]

[图16：高级选项区域 — 模型测试、代理、计费配置，保持默认即可]

更换已有配置的 API Key

如果 Key 到期或充值了新 Key，点击主界面对应配置右侧的编辑图标（铅笔图标）修改即可。

也可以用命令行快速更换：

cc-switch edit default --field env.ANTHROPIC_AUTH_TOKEN
# 输入新 Key 回车，自动保存并验证 JSON

cc-switch edit default --field env.ANTHROPIC_AUTH_TOKEN
# 输入新 Key 回车，自动保存并验证 JSON

修改后验证是否生效：

cc-switch test -c   # 用新 Key 发实际请求验证连通性

cc-switch test -c   # 用新 Key 发实际请求验证连通性

常见问题

Q：cc-switch use 之后 Claude Code 需要重启吗？

不需要。cc-switch use 直接修改 settings.json，Claude Code 下次 API 调用时自动读取新配置，无需重启。

Q：settings.json 在哪里？

Windows:      C:\Users\<你的用户名>\.claude\settings.json
macOS/Linux:  ~/.claude/settings.json

Windows:      C:\Users\<你的用户名>\.claude\settings.json
macOS/Linux:  ~/.claude/settings.json

Q：cc-switch 支持 OpenAI 格式吗？

cc-switch 专为 Claude Code 设计，管理的是 Claude Code 的 settings.json。如果你需要 OpenAI 兼容格式，ClaudeAPI.com 同时支持，基础 URL 为 https://api.claudeapi.com/v1（兼容 OpenAI SDK）。

Q：如何确认当前在用哪个配置？

cc-switch current
# 输出示例：Current configuration: default

cc-switch current
# 输出示例：Current configuration: default

国内用户专属推荐

在中国大陆使用 Claude Code，��本解决方案只有一个：使用 ClaudeAPI.com 国内直连接入点。

三步完成配置

第一步：访问 claudeapi.com，扫码添加微信顾问，获取专属 API Key。

第二步：安装并初始化

npm install -g @hobeeliu/cc-switch
cc-switch init
# 填入 ClaudeAPI.com Key 和 https://api.claudeapi.com

npm install -g @hobeeliu/cc-switch
cc-switch init
# 填入 ClaudeAPI.com Key 和 https://api.claudeapi.com

第三步：启动 Claude Code

cc-switch use default && claude

cc-switch use default && claude

完成。你现在拥有的是国内直连、无需代理、支持人民币充值的 Claude Code 环境。

总结

cc-switch 是 Claude Code 多配置管理的利器，配合 ClaudeAPI.com 国内直连，让 Claude Code 在国内开发环境下开箱即用：

• 一次初始化，永久生效
• 多配置并存，一条命令切换
• settings.json 自动管理，无需手动修改
• cc-switch test 一键验证连通性

相关文章

• Cherry Studio 接入 Claude API 完整教程 →
• Claude API 报错完全手册：401/429/529 解决方案（2026）→
• Claude API 价格详解：2026最新定价 →
• Python 调用 Claude API 完整示例 →

本文由 ClaudeAPI.com 团队撰写，持续更新维护。最后更新：2026-04