添加 ZiAI 并切换

本页是 CC-Switch 接入 ZiAI 的核心操作页。ZiAI 不在 CC-Switch 的内置预设列表中， 因此需要走「自定义」路径手动填写配置 —— 下面给出可直接粘贴的完整配置。

前提

• 已安装 CC-Switch v3.20.1 及以上（安装指引）
• 已有 ZiAI API 密钥（获取方式）
• 已知晓 ZiAI 的模型 ID（用操练场或 /v1/models 查询）

图片来源：CC-Switch 官方仓库（MIT 许可）

第一步：选对 Tab

点击右上角 + 打开添加供应商面板，有两个 Tab：

Tab	适用情况
应用专属供应商	只给某一个应用用（例如只想给 Claude Code 接 ZiAI）。新手推荐从这里开始
统一供应商	一份配置同时同步到 Claude Code / Codex / Gemini，适合中转站这类多协议服务

ZiAI 建议用「统一供应商」

ZiAI 同时提供 Anthropic Messages 与 OpenAI 端点，正好符合「统一供应商」的适用场景： 填一次名称、密钥、端点，勾选 Claude Code 与 Codex 两个应用即可同时生成配置。 若你只需要其中一个工具，用「应用专属供应商」更简单直接。

第二步：添加供应商

1. 在左侧应用切换器选择 Claude Code 或 Codex

2. 点击右上角 +，在「预设」下拉框中选择 自定义

3. 填写名称，例如 ZiAI

4. 按下面对应场景粘贴 JSON / TOML 配置

5. 填写 API Key：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

6. 点击模型输入框旁的 获取模型（下载图标）自动拉取模型列表

   CC-Switch 会用你填的密钥调用 ZiAI 的 /v1/models 端点。 ZiAI 支持该端点，因此这里通常能直接列出全部可用模型，无需手打 ID。

   若报错：401/403 说明密钥错；404/405 说明端点填错（检查 /v1）；超时则稍后重试或手动填写模型 ID。

7. 点击「添加」保存

场景 A：给 Claude Code 接 ZiAI

CC-Switch 自定义 JSON（推荐）

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.ziai.lol",
    "ANTHROPIC_MODEL": "你的模型ID"
  }
}

字段	必填	填什么
ANTHROPIC_AUTH_TOKEN	是	ZiAI 密钥。发出 Authorization: Bearer 头，网关认这个
ANTHROPIC_API_KEY	二选一	发出 x-api-key 头。ZiAI 也接受，但接中转站统一推荐用 AUTH_TOKEN
ANTHROPIC_BASE_URL	是	站点根域名，不带 /v1
ANTHROPIC_MODEL	否	默认模型 ID；不填则由 Claude Code 的角色映射决定

等价的 settings.json（对照用）

CC-Switch 实际写入的是 ~/.claude/settings.json 的 env 块，内容与上面等价：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.ziai.lol",
    "ANTHROPIC_MODEL": "你的模型ID"
  }
}

想看 CC-Switch 到底改了什么，直接打开这个文件对照即可。 手动配置（不用 CC-Switch）的完整步骤见接入 Claude Code。

Base URL 千万别带 /v1

Anthropic 协议下客户端会自己拼接 /v1/messages。 填 https://api.ziai.lol/v1 会导致实际请求变成 /v1/v1/messages → 404。

API 格式（高级选项）

编辑 Claude 供应商时，高级选项里有 API 格式 下拉框：

格式	什么时候选
Anthropic Messages（默认）	✅ ZiAI 选这个 —— ZiAI 原生提供 /v1/messages
OpenAI Chat Completions	仅当供应商只有 Chat 端点时选，需开启代理接管做转换
OpenAI Responses API	仅当供应商只有 Responses 端点时选，需开启代理接管做转换

ZiAI 原生支持 Anthropic Messages，保持默认即可，不需要开代理。

Claude 快捷开关

JSON 编辑器上方有一组快捷开关，勾选后会实时写入 JSON。对接中转站时最可能用到最后一个：

开关	效果	写入的配置
隐藏署名	清除提交 / PR 的署名元数据	attribution: {commit: "", pr: ""}
启用 Teammates	启用 Agent 团队功能	env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"
启用工具搜索	启用工具搜索	env.ENABLE_TOOL_SEARCH = "true"
最大强度思考	effort 设为 max	env.CLAUDE_CODE_EFFORT_LEVEL = "max"
禁用自动更新	阻止 Claude Code 自动更新	env.DISABLE_AUTOUPDATER = "1"
禁用 Artifact 工具	把 Artifact 工具从请求的 tools 数组中排除	env.CLAUDE_CODE_DISABLE_ARTIFACT = "1"

每个请求都 400 Invalid schema for function 'Artifact'

部分第三方 Anthropic 兼容网关会用严格正则校验工具的 JSON Schema， 而 Claude Code 的 Artifact 工具带有 Unicode 属性转义（如 \p{Cc}、\p{Cf}），会被这类网关拒收 —— 表现为换任何模型都报同一个 400 错误。

勾上「禁用 Artifact 工具」即可解决。取消勾选时该配置项会被完全移除。

场景 B：给 Codex 接 ZiAI

Codex 的配置由 CC-Switch 生成到两个文件：~/.codex/auth.json（密钥）与 ~/.codex/config.toml（端点与模型）。

等价的 config.toml（对照用）

model = "你的模型ID"
model_provider = "custom"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "custom"
base_url = "https://api.ziai.lol/v1"
wire_api = "responses"
requires_openai_auth = true

字段	填什么
model_provider	必须与 [model_providers.xxx] 的 xxx 一致
base_url	带 /v1（与 Claude 相反）
wire_api	只能是 responses，chat 已从 Codex 移除
disable_response_storage	中转站建议 true，避免依赖响应存储
model_reasoning_effort	low / medium / high，按模型支持情况选

~/.codex/auth.json：

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

CC-Switch 里怎么填

在 Codex 的「自定义」供应商表单中：

• 端点地址：https://api.ziai.lol/v1
• API Key：你的 ZiAI 密钥
• 模型：点「获取模型」自动拉取，或手填模型 ID
• 需要本地路由映射：见下方说明

CC-Switch 会自动生成上面那份 config.toml 与 auth.json，不需要你手写。

v3.20.1 起密钥存放方式变了

Codex CLI ≥ 0.149 不再从 auth.json 继承环境凭据，导致旧方式切换后一律 401「Missing API key」。 CC-Switch v3.20.1 已把切换改为 config-only：密钥随供应商表写入配置，不再依赖 auth.json。

所以请保持 CC-Switch ≥ v3.20.1，并且不要手动编辑这两个文件 —— 手改容易和 CC-Switch 的状态不一致。

Codex 的「上游格式」怎么选

这是 Codex 接入 ZiAI 唯一的判断点：

ZiAI 的实际情况	「需要本地路由映射」	说明
目标模型支持 /v1/responses	关闭	Codex 直连 ZiAI，最简单、延迟最低。用这条命令可验证
目标模型只有 /v1/chat/completions	打开	CC-Switch 本地代理把 Responses 请求转成 Chat，再把流式响应转回来
模型名不是 GPT 系列	打开	Codex 原生只认 GPT 系列模型名，需要映射

打开本地路由映射后：

1. 必须先开启本地路由服务并启用 Codex 接管，否则转换不生效（见进阶：本地代理）

2. 填写「模型映射」表

   字段	说明
   模型 ID	ZiAI 上的真实模型名，从 /v1/models 复制
   显示名称	可选，在 Codex 的 /model 命令中显示
   上下文窗口	可选，模型的上下文长度

   这张表会生成 Codex 的 model_catalog_json，是 /model 列表的唯一来源。

3. 修改映射表后重启 Codex

   model_catalog_json 只在 Codex 启动时加载，不重启看不到新模型。

4. 使用过程中保持本地路由开启

   关掉代理会立刻导致请求失败。

思考强度可能无效

开启本地路由后，CC-Switch 会按供应商名称、端点与模型名自动识别「思考」接口并转换参数，无需手动配置。 但部分上游只支持思考开关、不支持思考等级 —— 此时在 Codex 里调 model_reasoning_effort 的 low/medium/high 不会有任何效果（CC-Switch 不会硬传给不接受该参数的上游，否则请求会被拒）。

「完整 URL 模式」这个开关

代理模式下的 /v1 规则与直连相反

CC-Switch 默认把 base_url 当作前缀，由本地代理在其后拼接 /v1/chat/completions。

模式	base_url 填写	实际请求目标
默认（前缀拼接）	https://api.ziai.lol	https://api.ziai.lol/v1/chat/completions
完整 URL 模式	https://api.ziai.lol/custom/path/messages	原样请求该地址

ZiAI 路径规范，保持默认、不要开完整 URL 模式。 只有在供应商使用非标准路径时才需要开启。

注意这与「直连」时 Codex 自己拼路径的规则不同：直连时 base_url 要带 /v1， 走 CC-Switch 代理接管时填根域名。搞混就会得到 /v1/v1/... 的 404。

第三步：启用与切换

1. 主界面启用：在供应商卡片上点击「启用」按钮

   CC-Switch 更新配置文件 → 卡片变为「当前启用」（蓝色边框）。 代理模式下实际使用的供应商显示绿色边框。

2. 或托盘快速切换：右键系统托盘的 CC-Switch 图标 → 悬停到 Claude 或 Codex 子菜单 → 点击目标供应商名

   子菜单标题会显示当前激活的供应商与用量摘要，无需展开即可确认。

3. 等待生效

   应用	生效方式
   Claude Code	即时生效，支持热重载，无需重启
   Codex	需重启终端（关闭并重开终端窗口）

第四步：验证

Claude Code

# 确认环境变量已生效
echo $ANTHROPIC_BASE_URL        # macOS / Linux / Git Bash
echo $env:ANTHROPIC_BASE_URL    # Windows PowerShell

# 启动并确认能对话
claude

进入后可用 /status 查看当前接入点，用 /model 切换模型。 发一句「你好」能收到回复即成功。

Codex

codex --version
codex            # 交互式启动

或非交互式跑一个端到端任务：

codex exec "输出当前目录的文件列表"

进入后用 /model 确认模型列表包含你在映射表里填的模型。

待补插图CC-Switch 启用 ZiAI 后的供应商卡片状态

展示卡片蓝色边框与「当前启用」标签；若开了代理则展示绿色边框；宽 1280，PNG

回滚与备份

需求	做法
切回官方登录	添加一个「官方」预设供应商，切换过去后执行一遍 Log out / Log in 流程
恢复到之前的配置	~/.cc-switch/backups/ 自动保留最近 10 份备份
导出 / 导入全部配置	设置 → 高级 → 数据管理，导出为 cc-switch-export-{时间戳}.sql
换机迁移	直接打包整个 ~/.cc-switch/ 目录
卸载 CC-Switch	不影响 CLI 继续使用 —— 设计原则是最小侵入，配置文件保持最后启用的状态

为什么总有一个供应商删不掉

CC-Switch 始终保留一个「正在激活中」的配置 —— 如果全部删光，对应应用就无法使用了。 不常用某个应用时，可以在设置里关闭该应用的显示。

切换失败怎么办

现象	原因	解决
切换报错、文件未更新	配置文件被占用	关闭正在运行的 Claude Code / Codex，再切换
提示权限不足	配置目录无写权限	检查 ~/.claude、~/.codex 的权限
保存失败	自定义 JSON 格式错误	编辑供应商，检查括号与引号
切换成功但 CLI 仍用旧供应商	Codex 未重启终端	关闭终端重开；Claude Code 一般即时生效
Codex 报 401 Missing API key	CC-Switch 版本低于 v3.20.1	升级到 v3.20.1 及以上后重新切换

两个容易搞混的预设

不要用「Codex (ChatGPT Plus/Pro)」预设接 ZiAI

CC-Switch 的 Claude 供应商列表里有一个 Codex OAuth 反向代理 预设， 它通过逆向工程的 OAuth 流程用 ChatGPT 账号在 Claude Code 里复用 Codex 服务。

这条路径与 ZiAI 无关，且官方明确提示存在违反 OpenAI 服务条款、账号被限制、未来可能失效的风险。 接 ZiAI 请使用「自定义」预设。

下一步

• 进阶：本地代理、统一供应商与用量统计
• 不用 CC-Switch？手动配置见 Claude Code 与 Codex
• 出问题查常见报错速查