> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CC Switch 接入老张API：配置 Claude Code、Codex、Gemini CLI

> 在 CC Switch 中添加老张API：Claude Code 用 Claude Code 分组的令牌单独添加，Codex 和 Gemini CLI 用统一供应商一次配好，写好请求地址与模型后在供应商之间一键切换。

CC Switch 是管理 Claude Code、Codex、Gemini CLI 等工具供应商的桌面应用。老张API支持这三个工具各自的原生请求格式，按下文填写即可使用，不需要开启路由模式。

| 项目 | 内容 |
| - | - |
| 推荐入口 | Claude Code 用自定义配置单独添加；Codex、Gemini CLI 用统一供应商的预设「自定义网关」 |
| API 地址 | `https://api.laozhang.ai` |
| 令牌 | Claude Code 用 `Claude Code` 分组，Codex、Gemini CLI 用 `default` 分组，计费模式都选按量优先 |
| 推荐模型 | Claude Code 用 `claude-sonnet-5-5`，Codex 用 `gpt-6.1-sol`，Gemini CLI 用 `gemini-3.8-flash` |
| 最后核对 | 2026 年 11 月 4 日，CC Switch v4.0.25 |

## 安装 CC Switch

* **macOS 12 及以上**：运行 `brew install --cask cc-switch`，或从 GitHub Releases 下载 `.dmg` 安装包。
* **Windows**：下载 MSI 安装包或便携版。
* **Linux**：提供 deb、rpm 和 AppImage，需要 glibc 2.35 及以上和 WebKitGTK 4.1。

## 准备两个令牌

Claude Code 和另外两个工具要用不同分组的令牌。在[令牌管理](https://api2.laozhang.ai/token)新建两个令牌，计费模式都选按量优先，分别复制完整密钥：

* `Claude Code` 分组：给 Claude Code 用。
* `default` 分组：给 Codex 和 Gemini CLI 用。

统一供应商只能填一个 API Key，所以下文先单独添加 Claude Code，再用统一供应商添加 Codex 和 Gemini CLI。

## 添加 Claude Code

**1. 新建自定义配置**

在 CC Switch 中选中 Claude Code，点击右上角的 **添加供应商**（+），选择 **自定义配置**。

**2. 填写地址和密钥**

* **名称**：老张API
* **请求地址**：`https://api.laozhang.ai`，结尾不带 `/`
* **认证字段**：保持默认的 `ANTHROPIC_AUTH_TOKEN`，填入 `Claude Code` 分组的令牌
* **上游格式**：保持默认的 Anthropic Messages（原生）

**3. 填写模型映射**

模型映射的每一档都填老张API有的模型，可以点 **获取模型列表**，从老张API返回的模型中选择。

Haiku 一档一定要填：用 Claude 时填 `claude-haiku-5-5`，不用 Claude 时可填 `deepseek-v4-flash`。留空或保留 `claude-haiku-4-5-20251001` 时，Claude Code 跑后台任务会请求老张API没有的模型，报 503。

| 档位 | 写入的变量 | 用 Claude 模型 | 用 GLM / DeepSeek |
| - | - | - | - |
| Sonnet | `ANTHROPIC_DEFAULT_SONNET_MODEL` | `claude-sonnet-5-5` | `glm-5.2` |
| Opus | `ANTHROPIC_DEFAULT_OPUS_MODEL` | `claude-opus-5-5` | `glm-5.2` |
| Fable | Fable 档对应的变量 | `claude-fable-5-1` | `glm-5.2` |
| Haiku | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `claude-haiku-5-5` | `deepseek-v4-flash` |
| Subagent | `CLAUDE_CODE_SUBAGENT_MODEL` | `claude-sonnet-5-5` | `glm-5.2` |
| 默认兜底模型 | `ANTHROPIC_MODEL` | `claude-sonnet-5-5` | `glm-5.2` |

想用 DeepSeek 做主模型时，把上表中的 `glm-5.2` 换成 `deepseek-v4-pro`。Claude 模型的单次输出上限等使用说明见 [Claude Code 接入老张API](https://docs.laozhang.ai/scenarios/programming/claude-code.md#使用-claude-模型)。

**4. 保存并切换**

点击 **添加** 保存，再在 Claude Code 的供应商列表里点这个供应商卡片上的 **切换**，显示 **使用中** 即已启用，立即生效。

**切换会改写对应工具的配置文件，原来的配置可以随时恢复：**

* 第一次启动时，CC Switch 已把本机现有的配置导入为 `default` 供应商，并标为使用中。
* 第一次改写前，原文件会备份到 `~/.cc-switch/backups/live-first-write/`。
* 想恢复原来的配置，在 CC Switch 中切回 `default` 供应商。

这里的 `default` 是 CC Switch 的供应商名，和老张API的令牌分组无关。

**5. 发一条测试请求**

```bash theme={null}
claude -p "Reply with exactly one word: connected"
```

输出 `connected` 说明 Claude Code 已经通过老张API请求。

## 用统一供应商添加 Codex 和 Gemini CLI

统一供应商只需填一次 API 地址，CC Switch 会按各工具的格式分别写入。

**1. 新建统一供应商**

在 CC Switch 任一工具页（例如 Codex）点击右上角的 **添加供应商**，在左侧选择 **跨应用** 下的 **统一供应商**，再点预设 **自定义网关**。

![CC Switch 添加供应商页面，左侧选中统一供应商，右侧是 NewAPI 和自定义网关两个预设](https://mintcdn.com/laozhangai-edd05f2c/UAs8cbdK9dUwAUFr/images/scenarios/cc-switch-zh-universal-presets.jpg?fit=max\&auto=format\&n=UAs8cbdK9dUwAUFr\&q=85\&s=93b838041c3ef79eb0b6ae396c38071b)

添加供应商 → 统一供应商 → 自定义网关（CC Switch 4.0.25）

**2. 填写地址和密钥**

* **名称**：老张API
* **API 地址**：`https://api.laozhang.ai`，不要加 `/v1`，结尾不要带 `/`
* **API Key**：粘贴 `default` 分组的令牌
* **启用的应用**：关掉 Claude Code，只保留 OpenAI Codex 和 Gemini CLI

Claude Code 已在上一节单独添加，关掉它可以避免把 Claude Code 误切到 `default` 令牌上。Codex 需要的 `/v1` 由 CC Switch 自动补上。官网地址和备注可以不填。

![CC Switch 添加统一供应商表单，名称为老张API，API 地址为 https://api.laozhang.ai](https://mintcdn.com/laozhangai-edd05f2c/UAs8cbdK9dUwAUFr/images/scenarios/cc-switch-zh-universal-form.jpg?fit=max\&auto=format\&n=UAs8cbdK9dUwAUFr\&q=85\&s=ed4595f9a0d39258ba4bd32b05be1fc9)

自定义网关表单：名称、API 地址和 API Key

**3. 填写模型**

表单下方的 **模型配置** 按工具分组，模型 ID 要与[模型与价格总表](https://docs.laozhang.ai/models.md)完全一致：

* **Codex**：模型填 `gpt-6.1-sol`，Reasoning Effort 保持 `high` 即可
* **Gemini**：模型填 `gemini-3.8-flash`

Claude 一组不会用到，可以不改。

![CC Switch 统一供应商的模型配置，Claude、Codex、Gemini 三组模型已填写](https://mintcdn.com/laozhangai-edd05f2c/UAs8cbdK9dUwAUFr/images/scenarios/cc-switch-zh-universal-models.jpg?fit=max\&auto=format\&n=UAs8cbdK9dUwAUFr\&q=85\&s=13667be86cfe9a3478628a6817960c61)

模型配置：Codex 与 Gemini 换成老张API的模型

**4. 保存并切换**

点击 **添加** 保存。之后在 Codex、Gemini CLI 各自的供应商列表里找到这个供应商，点卡片上的 **切换**，显示 **使用中** 即已启用。Codex 和 Gemini CLI 要退出后重新启动才会使用新配置。原配置的备份与恢复方法同上一节。

**5. 发一条测试请求**

在终端分别运行：

```bash theme={null}
codex exec --skip-git-repo-check "Reply with exactly one word: connected"
gemini -m gemini-3.8-flash -p "Reply with exactly one word: connected"
```

输出 `connected` 说明该工具已经通过老张API请求。Gemini CLI 的非交互模式要求当前目录已被信任，首次在新目录运行时先在交互模式中确认。

切换后，三个工具最终写入的请求地址如下：

| 工具 | 写入位置 | 请求地址 |
| - | - | - |
| Claude Code | `ANTHROPIC_BASE_URL` | `https://api.laozhang.ai` |
| Codex | `~/.codex/config.toml` 的 `base_url` | `https://api.laozhang.ai/v1` |
| Gemini CLI | `~/.gemini/.env` 的 `GOOGLE_GEMINI_BASE_URL` | `https://api.laozhang.ai` |

## 按单个工具添加

不想用统一供应商，或者要给 Codex、Gemini CLI 分别指定模型时，也可以像 Claude Code 一样单独添加：在 CC Switch 中先选中这个工具，点 **添加供应商**（+）→ **自定义配置**，填写后点 **添加**，再在卡片上点 **切换**。这两个工具都填 `default` 分组的令牌。

填写模型时可以点 **获取模型列表**，从老张API返回的模型中选择。

### Codex

* **API 请求地址**：`https://api.laozhang.ai/v1`
* **API Key**：`default` 分组的令牌

CC Switch 会把 `model_provider` 改成 `custom`，并在 `~/.codex/config.toml` 中写入以下几项：

```toml theme={null}
model_provider = "custom"

[model_providers.custom]
base_url = "https://api.laozhang.ai/v1"
experimental_bearer_token = "你的老张API密钥"
wire_api = "responses"
```

* 密钥直接写在 `config.toml` 里，不写 `auth.json`。这个文件不要提交到代码仓库或截图外发。
* 需要换模型时，启动时用 `-m` 指定，例如 `codex -m gpt-6-sol`。
* 切换后重启 Codex 才会生效。

### Gemini CLI

* **请求地址**：`https://api.laozhang.ai`，不要加 `/v1` 或 `/v1beta`
* **API Key**：`default` 分组的令牌
* **模型**：`gemini-3.8-flash`，复杂任务可用 `gemini-3.1-pro-preview`

切换后 CC Switch 写入两个文件：

* `~/.gemini/.env`：`GOOGLE_GEMINI_BASE_URL`、`GEMINI_API_KEY`、`GEMINI_MODEL`
* `~/.gemini/settings.json`：认证方式 `gemini-api-key` 和模型名

切换后重启 Gemini CLI 才会生效。

## 常见问题

### 报 503 no available channels？

最常见的原因是 Haiku 一档还是默认的 `claude-haiku-4-5-20251001`，老张API没有这个模型。按上文改成 `claude-haiku-5-5` 等模型后重新切换一次。

Codex 或 Gemini CLI 报 `Current group claude_code has no available channels`，说明它用的是 `Claude Code` 分组的令牌，换成 `default` 分组的令牌。

其他情况检查令牌分组（Claude Code 用 `Claude Code`，Codex、Gemini CLI 用 `default`），以及模型 ID 是否与[模型与价格总表](https://docs.laozhang.ai/models.md)一致，排查方法见[如何确认模型是否可用](https://docs.laozhang.ai/faq/model-availability.md)。

### 切换后请求没有发到老张API？

先确认 Codex、Gemini CLI 已经重启。仍然不对时，按工具检查冲突的设置。CC Switch 检测到冲突的环境变量时，会在界面显示提示横幅。

**Claude Code**：终端里的同名变量一般不会盖过 CC Switch 写入的设置。真正会冲突的是以下两种情况：

* 终端或 shell 配置文件里设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`。执行 `unset` 并从 shell 配置文件中删除这几行。
* 项目目录的 `.claude/settings.json` 或 `.claude/settings.local.json` 另设了请求地址或密钥。项目级配置优先，删掉这两项。

**Gemini CLI**：终端里设置的 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_API_KEY` 会盖过 CC Switch 写入的 `~/.gemini/.env`。按 [Gemini CLI 页](https://docs.laozhang.ai/scenarios/programming/gemini-cli.md)在 shell 配置文件里写过这两行的，删掉后重新打开终端，改由 CC Switch 管理。

### Codex 配置和 Codex 页写法不同？

两种写法都可以使用老张API：

* [Codex CLI 页](https://docs.laozhang.ai/scenarios/programming/codex-cli.md)的手动写法：provider 名为 `laozhang`，密钥从 `env_key` 指定的环境变量读取。
* CC Switch 的写法：provider 名为 `custom`，密钥写在 `experimental_bearer_token`。

用 CC Switch 管理后，切换供应商会改写 `model_provider`。想回到手动写法，在 CC Switch 中切回 `default` 供应商，或把 `model_provider` 改回 `laozhang`。

### 需要开启路由模式吗？

不需要。路由模式只在需要转换请求格式或故障转移时使用。老张API原生支持 Anthropic Messages、OpenAI Responses 和 Gemini 三种格式，Claude Code、Codex、Gemini CLI 都可以按本页配置直接请求 `https://api.laozhang.ai`。

### 检测连通通过，仍然报 401？

请求地址旁 **管理与测速** 里的 **检测连通** 只检查地址能否返回 HTTP 响应，不校验密钥。报 401 时重新复制完整密钥，并在[令牌管理](https://api2.laozhang.ai/token)确认令牌已启用，更多排查见 [API Key 无效与 Base URL](https://docs.laozhang.ai/faq/invalid-api-key.md)。

### 报 404？

通常是地址里的 `/v1` 重复或缺失。Claude Code 和 Gemini CLI 的地址只填域名，Codex 填 `https://api.laozhang.ai/v1`，用统一供应商时只填 `https://api.laozhang.ai`。

### 在工具里用 /model 换的模型没保存？

在 Claude Code 等工具里用 `/model` 临时换模型，不会写回 CC Switch。下次切换供应商时，仍然使用 CC Switch 里保存的模型。想长期更换，在 CC Switch 中编辑这个供应商的模型设置。

### 提示余额不足？

余额不足或报 `insufficient_user_quota` 时，按[还有余额但调用失败的排查](https://docs.laozhang.ai/faq/balance-insufficient.md)逐项检查。每次请求的模型和用量可以在[调用日志](https://api2.laozhang.ai/log)中查看。

## 相关文档

* [工具接入总览](https://docs.laozhang.ai/scenarios.md)
* [Claude Code 接入老张API](https://docs.laozhang.ai/scenarios/programming/claude-code.md)
* [Codex CLI 接入老张API](https://docs.laozhang.ai/scenarios/programming/codex-cli.md)
* [Gemini CLI 接入老张API](https://docs.laozhang.ai/scenarios/programming/gemini-cli.md)
* [CC Switch 官网](https://ccswitch.io)
* [CC Switch GitHub 仓库](https://github.com/farion1231/cc-switch)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.