CCSwitch 详细教程

CCSwitch 详细教程

更新时间：2026-04-24

这份文档面向刚接触 CCSwitch、Claude Code、Codex 的用户，目标是把下面几件事一次说清楚：

1. 先说清楚：CCSwitch 是干什么的

CCSwitch 本质上是一个给 Claude Code 做“账号 / 提供商 / 模型切换”的桌面工具。它的主要价值不是替代 Claude Code，而是帮你把下面这些麻烦操作图形化：

• 在多个账号之间切换
• 在官方账号模式和 API 模式之间切换
• 在不同模型服务商之间切换
• 为 Claude Code 配置环境变量和连接参数
• 在需要时切回官方登录

如果你经常在下面这些情况里切换，CCSwitch 会明显省事：

• 官方 Anthropic 账号 和 API Key 模式来回切
• 国外模型 和 国产模型来回切
• 不同项目想用不同模型
• 不想手改一堆环境变量

2. 下载地址

2.1 CCSwitch 下载地址

• 官方主页：https://ccswitch.ai/
• GitHub 仓库：https://github.com/farion1231/cc-switch
• Releases 下载页：https://github.com/farion1231/cc-switch/releases

你当前目录里已经有这个文件：

• CC-Switch-v3.14.1-Linux-x86_64.AppImage

这说明你在 Linux 上已经拿到了一个可直接运行的版本。

2.2 Claude Code 下载 / 安装地址

• 官方文档：https://docs.anthropic.com/en/docs/claude-code/overview
• 常见安装方式：

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

2.3 Codex 下载 / 安装地址

• OpenAI Codex 文档入口：https://developers.openai.com/codex/
• GitHub 仓库：https://github.com/openai/codex
• 常见安装方式：

npm install -g @openai/codex
codex –version

3. 安装 CCSwitch

3.1 Linux 安装与运行

如果你使用的是 AppImage，最常见的做法是：

chmod +x ./CC-Switch-v3.14.1-Linux-x86_64.AppImage
./CC-Switch-v3.14.1-Linux-x86_64.AppImage

如果系统提示没有执行权限，通常就是没有执行位；如果提示缺少 FUSE，可以按你的发行版安装 FUSE 支持，或者查阅 GitHub Release 页的说明。

3.2 Windows / macOS

直接去 Releases 页面下载对应平台版本即可：

• Windows：通常下载 .exe
• macOS：通常下载 .dmg 或对应压缩包

4. 使用前准备

不管你是切 Claude Code 还是切 Codex，都先准备好这几样：

4.1 Node.js

建议 Node.js >= 18。

4.2 对应工具先装好

至少装一个：

• Claude Code
• Codex

4.3 你要明确自己走哪条路线

你实际上有三种路线：

建议你先决定目标：

• 只是想稳定使用 Claude Code：优先官方或 Anthropic 兼容服务
• 想把 Codex 切到自定义模型：优先改 ~/.codex/config.toml
• 想统一管理 Claude Code 的切换：优先用 CCSwitch

5. CCSwitch 最常见的用法

5.1 典型工作流

通常你会按这个顺序操作：

很多人以为切完立刻生效，但 CCSwitch 官方说明里明确提到，切换后通常需要重开终端，才能让新的环境变量生效。

5.2 适合新手的理解方式

你可以把 CCSwitch 理解成一个“Claude Code 的配置面板”：

• 左边是不同服务商 / 账号
• 中间是模型选择
• 应用后它会帮你把 Claude Code 对应配置切到目标服务

5.3 切换后怎么验证

切完后打开项目目录：

claude

进入 Claude Code 后执行：

/status

如果状态页显示：

• 当前模型名正确
• 当前提供商正确
• 没有认证错误

那就说明切换成功了。

6. 怎么在 CCSwitch 里切换 Claude Code

这部分是 CCSwitch 的主战场。

6.1 切换到官方 Anthropic

适合这种情况：

• 你有官方 Claude Pro / Max / API
• 你想用 Claude Code 的官方体验
• 你不需要国产兼容服务

大致流程：

6.2 切换到 API Provider

适合这种情况：

• 你有第三方兼容 API
• 你想让 Claude Code 走 API，不走官方账号

这时 CCSwitch 一般会让你填写这些内容：

• Provider 名称
• Base URL
• API Key / Auth Token
• 默认模型

Claude Code 本质上认的是 Anthropic 兼容配置，所以常见关键变量是：

• ANTHROPIC_BASE_URL
• ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN
• ANTHROPIC_MODEL

6.3 在 Claude Code 里临时切模型

如果服务端支持多模型，很多场景不需要回到 CCSwitch 再切一次，可以直接在 Claude Code 里切：

/model 模型名

例如：

/model kimi-k2.5

但要注意：

• 不是所有 Provider 都支持对话内切模型
• 有些服务商建议把模型固定在配置里
• 有些“latest”别名需要在服务商控制台切换，而不是本地切

7. Claude Code 怎么更换模型

这里分成两种方式：用 CCSwitch 切 和 手动切。

7.1 用 CCSwitch 切

这是最省事的方式：

7.2 手动切 Claude Code 模型

Claude Code 常见配置文件位置：

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

常见写法类似这样：

{
"env": {
"ANTHROPIC_AUTH_TOKEN": "你的Key",
"ANTHROPIC_BASE_URL": "你的BaseURL",
"ANTHROPIC_MODEL": "你的模型名"
}
}

如果你是第一次在兼容服务上跑 Claude Code，还经常需要补一个文件：

• ~/.claude.json

内容通常至少包含：

{
"hasCompletedOnboarding": true
}

这个做法在阿里云百炼的官方文档里被明确提到，主要是为了绕过首次连接官方服务时的初始化问题。

7.3 Claude Code 常见模型切换方式

常见有三种：

例如某些国产服务会提供：

• 固定模型名：如 qwen3.6-plus、kimi-k2.5
• 路由别名：如 ark-code-latest

如果你使用的是“别名模型”，通常代表：

• 本地配置不用改
• 模型真正切换在服务商控制台完成
• 生效可能有几分钟延迟

8. Codex 怎么更换模型

Codex 不靠 CCSwitch 做主配置，核心是它自己的配置文件：

• ~/.codex/config.toml

8.1 最基本的切换方式

OpenAI 官方文档把 ~/.codex/config.toml 作为用户级配置入口。最核心的两个字段通常是：

• model_provider
• model

例如：

model_provider = "openai"
model = "gpt-5"

如果你想切回 OpenAI 官方，只要把 Provider 指向官方，并确保认证正确即可。

8.2 自定义 Provider 的思路

Codex 官方配置参考支持自定义 model_providers。常见形式类似：

model_provider = "my_provider"
model = "qwen3.6-plus"

[model_providers.my_provider]
name = "My Provider"
base_url = "https://example.com/v1"
env_key = "MY_PROVIDER_API_KEY"
wire_api = "chat"

上面这个示例写法是按照 OpenAI Codex 当前公开配置结构整理出来的通用形式，关键点是：

• base_url：填服务商 OpenAI 兼容地址
• env_key：填你准备好的环境变量名
• wire_api：很多国产兼容服务仍然是 chat

8.3 切换完成后怎么验证

codex

进入后检查：

• 当前模型是否正确
• 是否能正常发起请求
• 是否还有鉴权报错

如果服务商不支持 Responses API，而你又在用 Codex 新版，就可能出现兼容问题。

这点非常重要：

• OpenAI 新版 Codex 已转向 Responses API
• 部分国产服务只兼容 Chat/Completions
• 这时你要么换支持新版协议的服务，要么按服务商文档使用特定版本的 Codex

9. 怎么把 Claude Code 更换成国产模型

这是很多人最关心的部分。核心结论先说：

• Claude Code 能不能接国产，关键不在名字，而在对方是否提供 Anthropic 兼容接口
• CCSwitch 适合做 Claude Code 的国产切换
• 如果国产厂商只提供 OpenAI 兼容接口，不一定适合直接给 Claude Code 用

下面给你三种最实用的路线。

9.1 路线 A：用阿里云百炼接 Claude Code

阿里云百炼官方已经给了 Claude Code 接入文档。

按量付费模式

官方文档给出的 Anthropic 兼容端点是：

• https://dashscope.aliyuncs.com/apps/anthropic

常见变量：

• ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic
• ANTHROPIC_AUTH_TOKEN=你的百炼APIKey
• ANTHROPIC_MODEL=模型名

支持思路：

• 用 CCSwitch 新增一个自定义 Anthropic Provider
• Base URL 填上面的地址
• Key 填百炼 Key
• 模型填百炼支持的模型名，比如 qwen3.6-plus

Coding Plan 模式

阿里云百炼对 Claude Code 还提供了专门的 Coding Plan 文档，Base URL 是：

• https://coding.dashscope.aliyuncs.com/apps/anthropic

如果你走 Coding Plan，建议完全按它的专属地址和专属 Key 来，不要混用普通百炼地址。

额外注意

阿里云文档明确提到：

• ~/.claude.json 里要加 hasCompletedOnboarding: true
• 否则第一次可能因为连接官方初始化失败而报错

9.2 路线 B：用火山方舟接 Claude Code

火山方舟官方也已经给了 Claude Code 文档。

Claude Code 使用的 Anthropic 兼容地址是：

• https://ark.cn-beijing.volces.com/api/coding

常见变量：

• ANTHROPIC_BASE_URL=https://ark.cn-beijing.volces.com/api/coding
• ANTHROPIC_AUTH_TOKEN=你的方舟API Key
• ANTHROPIC_MODEL=具体模型名 或 ark-code-latest

这条路线的优点是：

• 文档完整
• 明确支持 Claude Code
• 可以用 ark-code-latest 在控制台切模型

如果你想在 CCSwitch 里接入火山方舟，思路也是一样：

模型怎么切

有两种：

第二种更适合长期使用，因为以后换模型时不必再改本地配置。

9.3 路线 C：其他国产服务

只要满足这几个条件，也可以尝试：

如果只提供 OpenAI 兼容接口，那更适合 Codex、OpenCode、OpenAI SDK 类工具，不一定适合 Claude Code。

10. 怎么把 Codex 更换成国产模型

这里的关键和 Claude Code 完全不同。

核心原则：

• Codex 更看重 OpenAI 兼容 或 Responses API 兼容
• 不是所有国产服务都能直接喂给最新版 Codex
• 有的厂商已经提供了专门的 Codex 文档，优先按它来

10.1 路线 A：阿里云百炼接 Codex

阿里云百炼已经给了 Codex 文档，但要注意区分：

Token Plan 团队版

官方文档给出的示例是把 ~/.codex/config.toml 配成自定义 Provider。

文档里给出的关键地址：

• https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

思路是：

model_provider = "Model_Studio_Token_Plan"
model = "qwen3.6-plus"

[model_providers.Model_Studio_Token_Plan]
name = "Model_Studio_Token_Plan"
base_url = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"
wire_api = "chat"

然后在 shell 里配置：

export DASHSCOPE_API_KEY="你的阿里云Key"

Coding Plan

阿里云文档明确写了一个重要限制：

• 新版本 Codex 使用 Responses API
• 百炼 Coding Plan 目前文档适配的是旧版 Codex
• 如果你要接入 Coding Plan，需要按文档安装旧版 @openai/codex@0.80.0

这意味着：

• 如果你坚持用 Codex 最新版，不一定能直接接 Coding Plan
• 如果你按阿里云 Coding Plan 方案走，要接受“旧版 Codex”的限制

这是当前最容易踩坑的点之一。

10.2 路线 B：火山方舟接 Codex

火山方舟文档里明确区分了两类地址：

• Anthropic 兼容：https://ark.cn-beijing.volces.com/api/coding
• OpenAI 兼容：https://ark.cn-beijing.volces.com/api/coding/v3

因为 Codex 更适合接 OpenAI 兼容，所以你给 Codex 配方舟时，一般优先看 /v3 这个地址。

一个通用示例可以写成：

model_provider = "ark"
model = "doubao-seed-2.0-code"

[model_providers.ark]
name = "Volcengine Ark"
base_url = "https://ark.cn-beijing.volces.com/api/coding/v3"
env_key = "ARK_API_KEY"
wire_api = "chat"

然后：

export ARK_API_KEY="你的方舟Key"

如果你碰到新版 Codex 协议不兼容的问题，要优先看火山方舟后续是否提供针对 Responses API 的专门适配说明。

10.3 路线 C：OpenAI 兼容国产平台

一些国产平台更适合直接给 Codex 用，只要它满足下面条件：

常见思路是直接在 ~/.codex/config.toml 加自定义 Provider，而不是通过 CCSwitch。

11. 推荐的实际配置方案

如果你现在就要落地，我建议你按下面方式选。

11.1 你主要用 Claude Code

优先级建议：

原因很简单：

• Claude Code 原生就是 Anthropic 体系
• 兼容 Anthropic 的服务接入最顺
• CCSwitch 也更适合这一类切换

11.2 你主要用 Codex

优先级建议：

原因：

• Codex 配置核心在 ~/.codex/config.toml
• 它不靠 CCSwitch 管理主配置
• 新版 Codex 的协议要求比很多第三方服务更严格

11.3 你想“一套图形界面全搞定”

现实一点说：

• CCSwitch 更像是 Claude Code 的切换器
• Codex 还是建议手改 ~/.codex/config.toml

也就是说：

• Claude Code 用 CCSwitch
• Codex 用配置文件

这是目前最稳的组合。

12. CCSwitch 怎么用：一份从零开始的实操版

下面给你一份最容易照着做的流程。

12.1 场景一：切回官方 Claude Code

12.2 场景二：切到火山方舟

12.3 场景三：切到阿里云百炼

12.4 场景四：Codex 切到国产

这个场景一般不建议用 CCSwitch，而是直接改 ~/.codex/config.toml：

13. 常见问题

13.1 为什么我在 CCSwitch 里切完了，终端里还是旧模型

最常见原因：

• 终端没重开
• 老的 shell 环境变量还在
• Claude Code 进程还没退出

优先做法：

13.2 Claude Code 报 Unable to connect to Anthropic services

常见原因：

• 你在国内网络环境下首次初始化失败
• 没设置 ~/.claude.json 的 hasCompletedOnboarding
• Base URL 填错
• Key 填错

优先排查：

13.3 Codex 接国产为什么不稳定

最常见原因：

• 你用的是最新版 Codex，但服务商只兼容 Chat/Completions
• 你的 wire_api 配错了
• base_url 不是服务商给 Codex 的专用地址

13.4 为什么 Claude Code 能接，Codex 却不能接

因为它们要求的兼容协议不完全一样：

• Claude Code 更偏 Anthropic 兼容
• Codex 更偏 OpenAI / Responses API 兼容

同一家国产厂商可能只把其中一种做好了。

14. 一套可以直接照抄的配置模板

14.1 Claude Code 接火山方舟

~/.claude/settings.json

{
"env": {
"ANTHROPIC_AUTH_TOKEN": "YOUR_ARK_KEY",
"ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding",
"ANTHROPIC_MODEL": "ark-code-latest"
}
}

~/.claude.json

{
"hasCompletedOnboarding": true
}

14.2 Claude Code 接阿里云百炼

~/.claude/settings.json

{
"env": {
"ANTHROPIC_AUTH_TOKEN": "YOUR_DASHSCOPE_KEY",
"ANTHROPIC_BASE_URL": "https://dashscope.aliyuncs.com/apps/anthropic",
"ANTHROPIC_MODEL": "qwen3.6-plus"
}
}

~/.claude.json

{
"hasCompletedOnboarding": true
}

14.3 Codex 接火山方舟

~/.codex/config.toml

model_provider = "ark"
model = "doubao-seed-2.0-code"

[model_providers.ark]
name = "Volcengine Ark"
base_url = "https://ark.cn-beijing.volces.com/api/coding/v3"
env_key = "ARK_API_KEY"
wire_api = "chat"

shell 环境变量：

export ARK_API_KEY="YOUR_ARK_KEY"

14.4 Codex 接阿里云百炼 Token Plan

~/.codex/config.toml

model_provider = "Model_Studio_Token_Plan"
model = "qwen3.6-plus"

[model_providers.Model_Studio_Token_Plan]
name = "Model_Studio_Token_Plan"
base_url = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"
wire_api = "chat"

shell 环境变量：

export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_KEY"

15. 最后给你的结论

如果你只想一句话理解整件事，可以记这三条：

如果你准备实际落地，最稳的组合是：

• Claude Code：用 CCSwitch 管理
• Codex：手改 ~/.codex/config.toml

16. 参考链接

CCSwitch

• CCSwitch 官网：https://ccswitch.ai/
• GitHub：https://github.com/farion1231/cc-switch
• Releases：https://github.com/farion1231/cc-switch/releases

Claude Code 官方

• Claude Code 概览：https://docs.anthropic.com/en/docs/claude-code/overview
• Claude Code 第三方模型提供商：https://docs.anthropic.com/en/docs/claude-code/third-party-model-providers

Codex 官方

• Codex 文档入口：https://developers.openai.com/codex/
• Codex Config Basics：https://developers.openai.com/codex/config-basic
• Codex Config Reference：https://developers.openai.com/codex/config-reference
• Codex GitHub：https://github.com/openai/codex
• Codex 配置文档：https://github.com/openai/codex/blob/main/docs/config.md

国产方案官方文档

• 阿里云百炼 Claude Code：https://help.aliyun.com/zh/model-studio/claude-code
• 阿里云百炼 Claude Code Coding Plan：https://help.aliyun.com/zh/model-studio/claude-code-coding-plan
• 阿里云百炼 Claude Code Token Plan：https://help.aliyun.com/zh/model-studio/claude-code-token-plan
• 阿里云百炼 Codex Token Plan：https://help.aliyun.com/zh/model-studio/codex-token-plan
• 阿里云百炼 Codex Coding Plan：https://help.aliyun.com/zh/model-studio/codex-coding-plan
• 阿里云百炼 Anthropic API 兼容：https://help.aliyun.com/zh/model-studio/anthropic-api-messages
• 火山方舟 Claude Code：https://www.volcengine.com/docs/82379/1928262
• 火山方舟文档入口：https://www.volcengine.com/docs/82379

17. 本文中最重要的时效性说明

下面这些信息是会变的，后续如果你发现不一致，优先以官方文档为准：

• CCSwitch 的最新版本号
• Claude Code / Codex 的安装方式
• Codex 对第三方协议的兼容范围
• 阿里云百炼 / 火山方舟提供的专属 Base URL
• 服务商支持的具体模型名单

尤其是 Codex：

• 截至 2026-04-24，阿里云百炼官方文档明确写了：Coding Plan 对接 Codex 时，新版 Codex 不一定适用，可能需要旧版 @openai/codex@0.80.0

这个限制很关键，部署前一定先看一眼最新官方文档。