# CC Switch 配置

[CC Switch](https://ccswitch.io/) 是跨平台的 AI CLI 配置管理工具，适合在 Codex 官方配置和多个 API 供应商之间可视化切换。本页以 **CC Switch 3.20 及以上版本**为例。

## 配置结果

完成后，CC Switch 会管理 Codex 的 `~/.codex/auth.json` 和 `~/.codex/config.toml`：

| 字段 | 值 |
| --- | --- |
| 供应商名称 | `4AICode` |
| API Key | 仪表盘创建的 `sk-4ai-...` |
| API 端点 | `https://relay.4aicode.net/v1` |
| 默认模型 | `gpt-5.6-terra` |
| 上游格式 | `OpenAI Responses API` |

4AICode 原生支持 Responses API，完整 URL 模式和本地路由映射保持关闭。

## 1. 准备 Token 和客户端

1. 在[仪表盘 → 管理 Tokens](https://4aicode.net/tokens)创建一个 `sk-4ai-...` Token。
2. 从 [CC Switch 官网](https://ccswitch.io/)或 [GitHub Releases](https://github.com/farion1231/cc-switch/releases/latest)安装最新版。
3. 安装 [Codex CLI](https://developers.openai.com/codex/)。

本文配置中的 `sk-4ai-xxxxxxxxxxxxxxxx` 是占位符，填写时替换为仪表盘创建的真实 Token。真实 Token 请勿提交到版本控制或分享给他人。

首次打开 CC Switch 时，可以导入现有 Codex 配置。CC Switch 会在切换供应商时更新 Codex 配置文件。

## 2. 添加 4AICode 供应商

1. 在 CC Switch 顶部选择 **Codex**。
2. 点击右上角 **+**。
3. 保持在 **应用专属供应商**，预设选择 **自定义**。
4. 按下表填写：

| CC Switch 字段 | 填写内容 |
| --- | --- |
| 名称 | `4AICode` |
| API Key | `sk-4ai-xxxxxxxxxxxxxxxx` |
| API 端点 / Base URL | `https://relay.4aicode.net/v1` |
| 默认模型 | `gpt-5.6-terra` |

默认线路按地区区分：中国大陆推荐 `.net`，国际网络推荐 `https://relay.4aicode.com/v1`。本文中文示例使用 `.net`。

## 3. 检查高级选项

展开 **高级选项**，确认：

| 选项 | 设置 |
| --- | --- |
| 上游格式 | `OpenAI Responses API` |
| 完整 URL 模式 | 关闭 |
| 需要本地路由映射 | 关闭；新版 CC Switch 可能按上游格式自动判断，不再显示该开关 |
| 模型映射 | 留空 |

`https://relay.4aicode.net/v1` 是 API 前缀。完整 URL 模式关闭后，Codex 会自行请求 `/responses` 路径。

在页面下方的 **config.toml (TOML)** 编辑器中，把 `model_reasoning_effort` 设置为 `xhigh`。这是本指南推荐的推理强度，CC Switch 会把它写入 Codex 配置。

点击 **添加** 保存供应商。

## 4. 启用并验证

1. 在 4AICode 供应商卡片上点击 **启用**。
2. 完全退出正在运行的 Codex CLI 或 Codex App。
3. 新开终端并运行：

```bash
codex
```

输入一条简单任务，例如“列出当前目录并说明项目结构”。正常返回内容即表示配置成功。

CC Switch 切换 Codex 供应商后需要重启 Codex。后续可以在主界面或系统托盘中快速切换供应商。

## 切换模型

编辑 4AICode 供应商，在 **默认模型** 中填写目标模型。下列模型是 4AICode 当前提供的模型，最终可用范围以仪表盘模型列表和上游服务状态为准：

| 模型 | 推荐用途 |
| --- | --- |
| `gpt-6-astra` | 新一代旗舰，按官方价 1.5 折计费 |
| `gpt-5.6-sol` | 复杂工程、最强推理 |
| `gpt-5.6-terra` | 日常编码，推荐默认值 |
| `gpt-5.6-luna` | 快速、经济型任务 |
| `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex` | 兼容旧工作流 |

`gpt-5.6-sol` 支持 `max` 推理强度；其余模型推荐 `xhigh`。`max` 会使用更多推理计算，响应更慢、费用更高。保存后再次启用该供应商，并重启 Codex。

## 配置对照

CC Switch 的第三方 API Key 模式会把 Token 写入 `auth.json`，其配置语义应与下面内容一致。ChatGPT 官方登录模式使用另一套包含 `tokens` 和 `last_refresh` 的认证结构；CC Switch 会按供应商类型分别管理。CC Switch 还会自动生成供应商 ID，实际段落名称可能不同。

`auth.json`：

```json
{
  "OPENAI_API_KEY": "sk-4ai-xxxxxxxxxxxxxxxx"
}
```

`config.toml`：

```toml
model_provider = "custom"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.custom]
name = "4AICode"
base_url = "https://relay.4aicode.net/v1"
wire_api = "responses"
requires_openai_auth = true
```

`requires_openai_auth = true` 会让该 provider 从 `auth.json` 读取 API Key。

## 常见问题

| 现象 | 处理方式 |
| --- | --- |
| 启用后仍使用旧供应商 | 确认 4AICode 卡片显示“当前启用”，完全退出 Codex，再新开终端或 App |
| 返回 `401` | 检查 API Key 是否完整，并在仪表盘确认 Token 有效 |
| 返回 `404` | 确认 Base URL 以 `/v1` 结尾，完整 URL 模式处于关闭状态 |
| 请求经过 CC Switch 本地代理 | 将上游格式设为 Responses，并关闭本地路由接管 |
| CC Switch 中找不到本文字段 | 升级到最新版本，字段名称以当前界面为准 |

使用自动脚本、Codex App 手机端或 SDK 的配置方式见 [ChatGPT / Codex 配置](/docs/guides/chatgpt)。