cc-switch

设置-通用

显示项目切换

把当前的 供应商、MCP、Skills、记忆文件 保存成一个命名项目，然后在主页顶部或者托盘里一键切换
Project = 一整套供应商 + MCP + Skills + Memory 配置快照。

Skills 存储位置

Skill 可以来自多种来源，例如你在 CC Switch 里从公共 Registry 搜索安装、从 Skill 仓库获取，或者把已有 Skill 纳入 CC Switch 管理；并不是说 Skill 文件“只能从 CC Switch 官方服务器下载”
然后 CC Switch 再把这些 Skill 分发给不同工具

codex 应用增强

不只是 Codex 桌面端，Codex CLI 也可以用

非接管切换时保留官方登录

我从 OpenAI 官方切换到第三方供应商后，还想让 Codex 保留原来的 ChatGPT 官方登录状态
想用第三方 API 跑 Codex，但又不想丢掉 Codex 官方账号的登录状态

统一 Codex 会话历史

我切换供应商以后，还想看到以前的聊天记录。

设置-路由

在你的电脑上启动一个“小型 AI API 中转站”，让 Claude Code、Codex、Gemini CLI 等程序先把请求发给 CC
Switch，再由 CC Switch 转发给你选择的供应商。
CC Switch 官方文档明确说明，本地路由默认运行在 127.0.0.1:15721，并可以分别接管 Claude、Codex、Gemini 等应用
最重要的是解决一个问题：
不同供应商的 API 协议不一样。
本地路由开关 ≈
“我要不要让 CC Switch 在我电脑上运行这个中转服务器？”

Agent 本身固定使用自己的 API 协议，而你想接入的模型/供应商可能使用另一种协议，所以 CC Switch 在中间做协议转换。
CC Switch 本地路由非常简单地记成：
“AI Agent 和模型供应商之间的翻译官 + 中转站。
如果 Agent 和供应商本来就使用同一种协议，就不需要转换。**例如供应商原生支持 Codex 所需的 Responses API，那么请求可以直接转发，本地路由甚至可以不参与协议转换。

全局出站代理

CC Switch 自己访问互联网时，应该通过什么网络通道出去

本地路由负责接收本机 AI 工具请求，而全局出站代理负责 CC Switch 向外发送请求时使用的网络通道

codex 桌面端和cli

添加新的供应商

称作“供应商”，主要有以下几个原因：
1.它们是提供 AI 算力/服务的“供应方”
在软件架构中，模型本身（如 Claude 3.5 Sonnet、GPT-4o）只是算法，要运行它们需要极大的 GPU 算力。

统一供应商

一次配置，同步应用到多个 AI 工具（Claude Code、Codex、Gemini、OpenCode 等）。
如果你使用的是 同一个 API 中转服务商/聚合平台（很多第三方平台的一个 API Key 可以同时调用 Claude、GPT-4/Codex、Gemini 等所有模型），用这个选项最方便。
在这里填入 API 地址和 Key，并勾选你想绑定的工具，cc-switch 就会自动把这个配置写入各个 AI 工具各自的配置文件中。以后在托盘一键切换时，多个 AI 工具的节点会同步切换。

目前市场上绝大多数 API 中转商/第三方代充平台，后台都是基于开源的 NewAPI（或 OneAPI）系统搭建的。
如果你是在第三方中转网站买的额度/Key，直接选默认的 NewAPI 填入网站地址和 Key 即可；如果连接报错或使用的是自定义转发脚本，再切换为 自定义网关

claude 供应商

请求地址

关闭“完整 URL”： 你填写的是 Base URL（基础域名/根路径），cc-switch 会根据当前 AI 工具（如 Claude
Code 或 Codex）所需的标准 API 协议，自动在末尾拼接 对应的 Endpoint（如 /v1/messages）。

“完整 URL”，必须同时开启 cc-switch 的“路由”功能，否则这个配置是无法生效或无法使用的。

上游格式

上游”（Upstream）指的是你配置的远端 API 服务提供商

在绝大多数软件架构和 API 调用场景中：

上游（Upstream） = 服务器 / 数据与算力的生产者（如 OpenAI、Anthropic、DeepSeek 或你的第三方 API
中转站）。

下游（Downstream） = 客户端 / 数据的消费者（如 Claude Code、Cursor、VS Code 插件等终端工具）。

认证字段

认证字段”，说白了就是给服务器看钥匙的方式。 你手里的 API Key（比如 sk-xxxxxx）就是钥匙，但去门卫那里报钥匙时，对方要求的暗号格式可能不一样：

模型映射

Subagent
Subagent 对应 CLAUDE_CODE_SUBAGENT_MODEL
专门指定 Claude Code 创建出来的子代理使用哪个模型。

不是每次随随便便“现造一个没有定义的 Subagent”。Claude Code 的 Subagent 更准确地说是：先有“Subagent 类型/定义”，需要委派任务时，主 Agent 选择合适的类型并启动一个实例。

主 Claude 可以看到当前可用的 Subagent 定义(内置和新增)，然后根据每个 Agent 的 description 等信息判断该不该委派、委派给谁。Claude 的新模型也支持主动判断任务是否值得交给专门的 Subagent。

1M 只是给 Claude Code 的上下文能力声明。
Claude Code 自己需要知道“当前模型的上下文上限是多少
Claude Code 内部有一套 context window / auto-compaction 管理逻辑。它会根据当前模型判断“这个模型的上下文窗口是多少”，然后决定什么时候自动压缩对话。

Claude Code 实际需要这个值，是为了类似下面这个过程：
当前会话 token 数
↓
Claude Code 知道模型窗口大小
↓
例如认为窗口 = 200K
↓
快到 200K
↓
触发 auto-compaction
↓
把较早的聊天总结/压缩
例如原生 Claude 模型：
claude-sonnet-5
Claude Code自己认识它，就知道当前官方配置下它是 1M context；官方文档明确说 Sonnet 5 在 Anthropic API 上原生就是 1M
在 Claude Code体系里，[1m] 是官方支持的模型能力标记，例如官方允许：
/model opus[1m]
/model sonnet[1m]
并明确规定：对于它无法识别的自定义模型 ID，如果 ID 带 [1m]，Claude Code会假定它有 1M context window。

[1m] 是 Claude Code 专门认识的“这个模型是 1M”特殊标签；CLAUDE_CODE_MAX_CONTEXT_TOKENS
才是通用的精确窗口大小配置。[1m] 不是 [数字+单位] 的通用语法，因此不能自己造 [5b]

默认兜底模型

ANTHROPIC_MODEL 的官方作用可以直接理解成：

指定 Claude Code 当前默认使用哪个模型。

Claude Code 官方环境变量文档对它的定义就是：ANTHROPIC_MODEL = “要使用的模型设置名称”
例如你设置：
ANTHROPIC_MODEL=claude-sonnet-4-6
那 Claude Code 启动时，默认主会话就会用这个模型

“默认兜底模型”

因为它底层对应的是 Claude Code 官方变量：

ANTHROPIC_MODEL

cc switch 不开启路由时，C会把供应商配置直接写给 Claude Code；这时 ANTHROPIC_MODEL 会被
Claude Code 自己读取，作用是指定当前/默认模型
开启路由：真实模型映射主要由 CC Switch保存和执行；ANTHROPIC_MODEL 变成 CC Switch 的默认兜底值，补缺失的 Sonnet/Opus/Haiku 映射

自定义user-agent

当 CC Switch 开启本地路由/代理接管后，它替你把请求转发给供应商 API 时，可以把 HTTP 请求里的 User-Agent
请求头改成你指定的值。 User-Agent 本身是什么？ 它只是 HTTP 请求头中的一项，用来告诉服务器：
“这个请求大概是什么客户端发出来的。”
“预设”，通常就是一些常见客户端 UA，让你不用自己手写

本地代理请求覆盖

CC Switch 在把请求转发给供应商之前，最后再帮你改一下“请求头”和“请求正文”。
而且只在你开启 本地路由/代理接管 时生效，因为只有这时请求真正经过 CC Switch。
Header：原则上任意合法 HTTP Header 都能写，但有一批被 CC Switch 保护，不能覆盖
Body：原则上任意 JSON 字段都能写，目前明确禁止覆盖的是顶层 stream

编辑通用配置

编辑通用配置 = 定义“所有供应商都可以复用的一段公共配置”
应用通用配置 = 当前这个供应商要不要把那段公共配置合并进来
Claude Code
└─ Claude自己的“通用配置”
├─ Claude供应商A
├─ Claude供应商B
└─ Claude供应商C
Codex
└─ Codex自己的“通用配置”
├─ Codex供应商A
├─ Codex供应商B
└─ Codex供应商C
Gemini
└─ Gemini自己的“通用配置”
├─ Gemini供应商A
├─ Gemini供应商B
└─ Gemini供应商C
不是：
一份全局通用配置
↓
同时塞给 Claude / Codex / Gemini / OpenCode / …
因为三者配置格式本来就不一样：
Claude → JSON / settings.json 风格
Codex → TOML / config.toml 风格
Gemini → 自己的 env / 配置结构

通常你只填 Base URL；具体 endpoint 由 Agent/SDK 自动拼

一般是 Agent 根据自己的协议拼接端点，不是你针对每个模型手工复制不同 URL /v1/messages 告诉 NewAPI：这是
Claude/Anthropic 协议 model = claude-sonnet-4-5 告诉 NewAPI：我要哪个模型
不是模型名决定： 我要使用 /v1/messages

而是客户端所用协议/端点决定请求格式，模型名决定具体路由到哪个模型。 URL 路径 → 你说的是什么“语言/协议”

model → 你想找哪个“模型”

你配置：
Base URL = https://openrouter.ai/api/v1
Agent自己决定：
我要用 /chat/completions
还是 /responses
还是 /messages
最后自动拼：
Base URL + endpoint
endpoint
→ 客户端决定“用哪种 API 协议”
model
→ OpenRouter决定“调用哪个模型”