CC-Switch 接入 kukuai.fyi

CC-Switch 是一个桌面端 AI 编程 CLI 统一管理工具，可集中管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes Agent 的供应商配置、本地路由、MCP、Skills、Prompts、会话和用量统计。

这一页把 CC Switch 官方文档 的核心流程压缩成一个 kukuai.fyi 接入菜单：先安装 CC-Switch，再添加 kukuai.fyi 供应商，最后按目标工具启用路由并验证。

适用场景

• 你同时使用 Claude Code、Codex CLI、Gemini CLI、OpenCode、OpenClaw 或 Hermes，希望统一切换模型供应商。
• 你想把 kukuai.fyi 作为 OpenAI 兼容、Claude 兼容或 Gemini 兼容工具的统一中转站。
• 你需要本地路由、格式转换、自动故障转移、用量统计和请求日志。
• 你需要在 API Key 模型调用和 OAuth 账号能力之间明确分开管理。

准备工作

checklisttext

1. 已安装 Node.js 18 LTS 或更高版本
2. 已安装目标 CLI，例如 Claude Code / Codex CLI / Gemini CLI
3. 已安装 CC-Switch
4. 已准备 kukuai.fyi API Key
5. 已确认目标工具使用 OpenAI 兼容、Claude 兼容还是 Gemini 原生协议

常用 CLI 安装命令：

install-cli.shbash

# Claude Code
npm install -g @anthropic-ai/claude-code

# Codex CLI
npm install -g @openai/codex

# Gemini CLI
npm install -g @google/gemini-cli

安装 CC-Switch

只从官方渠道获取 CC-Switch：

• 官方网站：https://ccswitch.io
• GitHub Releases：https://github.com/farion1231/cc-switch/releases
• 官方仓库：https://github.com/farion1231/cc-switch

macOS 推荐使用 Homebrew：

install-ccswitch-macos.shbash

brew install --cask cc-switch

# 更新
brew upgrade --cask cc-switch

Windows 下载 CC-Switch-v{version}-Windows.msi 或便携版 ZIP。Linux 按发行版下载 .deb、.rpm 或 .AppImage，Arch 用户可使用 cc-switch-bin。

kukuai.fyi 路由怎么填

CC-Switch 管理的是“供应商”。给 kukuai.fyi 建议拆成两类供应商，不要把所有工具混用同一个 Base URL。

routestext

OpenAI 兼容供应商
Name: kukuai-openai
Base URL: https://www.kukuai.fyi/api-proxy/china/v1
API Key: sk-你的-kukuai-api-key
Default Model: gpt-5-2-chat-latest

Claude 兼容供应商
Name: kukuai-claude
Base URL: https://www.kukuai.fyi/api-proxy/china
API Key: sk-你的-kukuai-api-key
Default Model: claude-sonnet-4-6

Gemini 兼容供应商
Name: kukuai-gemini
Base URL: https://www.kukuai.fyi/api-proxy/china
API Key: sk-你的-kukuai-api-key
Default Model: gemini-3-pro-image-preview

如果客户端要求填写完整 Endpoint，OpenAI Chat Completions 使用：

endpointtext

https://www.kukuai.fyi/api-proxy/china/v1/chat/completions

如果客户端只要求填写 Base URL，则不要再追加 /chat/completions。

添加供应商

在 CC-Switch 主界面右上角点击 +，进入添加供应商面板。官方手册把供应商分为“应用专属供应商”和“统一供应商”两类。

应用专属供应商

适合只给某一个工具配置 kukuai.fyi，例如只配置 Codex CLI。

add-providertext

1. 在左侧选择目标应用，例如 Codex 或 Claude
2. 点击右上角 +
3. 选择 OpenAI Compatible / 自定义 / 对应协议预设
4. 名称填写 kukuai-openai 或 kukuai-claude
5. 填入 Base URL、API Key 和默认模型
6. 保存
7. 在供应商卡片上点击启用
8. 重启目标 CLI 或终端

统一供应商

适合一个 kukuai.fyi API Key 同时同步到 Claude Code、Codex、Gemini 等工具。

universal-providertext

1. 打开添加供应商面板
2. 切换到统一供应商 Tab
3. 点击添加统一供应商
4. 填写名称、API Key、端点地址
5. 勾选要同步的应用
6. 保存并同步
7. 分别检查每个应用生成的协议配置是否正确

统一供应商会把配置写入关联应用。修改统一供应商后，可选择“保存并同步”覆盖相关应用配置。

按工具选择协议

工具	建议协议	Base URL
Codex CLI	OpenAI Compatible	https://www.kukuai.fyi/api-proxy/china/v1
Cursor	OpenAI Compatible	https://www.kukuai.fyi/api-proxy/china/v1
Cline	OpenAI Compatible	https://www.kukuai.fyi/api-proxy/china/v1
ChatBox	OpenAI Compatible	https://www.kukuai.fyi/api-proxy/china/v1
Cherry Studio	OpenAI Compatible	https://www.kukuai.fyi/api-proxy/china/v1
Claude Code	Claude Compatible	https://www.kukuai.fyi/api-proxy/china
Gemini CLI	Gemini 原生接口	https://www.kukuai.fyi/api-proxy/china

模型 ID 要完整复制，不要把展示名称、中文说明或供应商名称填进 model 字段。更多可用模型见 模型导航。

Codex 本地路由与模型映射

Codex 原生更偏向 OpenAI Responses API。部分上游只支持 Chat Completions，或使用 DeepSeek、Kimi、MiniMax 等非 GPT 模型名时，需要 CC-Switch 本地路由做协议和模型转换。

codex-routingtext

1. 编辑 Codex 供应商
2. 如果上游是 Chat Completions，打开“需要本地路由映射”
3. 在模型映射表添加上游真实模型 ID
4. 启动本地代理服务
5. 启用 Codex 应用接管
6. 重启 Codex CLI
7. 用 /model 或最小任务确认模型列表和调用正常

如果你用的是 kukuai.fyi 的 OpenAI 兼容 /v1 路由，优先按真实模型能力选择模型；只有在 Codex 无法识别模型或协议不匹配时，再打开本地路由映射。

启用本地代理

CC-Switch 的本地代理默认监听：

proxy-addresstext

http://127.0.0.1:15721

代理用途：

• 记录请求日志和用量。
• 给不同应用做独立接管。
• 在 Claude、Codex、Gemini 等协议之间做必要转换。
• 支持故障转移队列、健康状态和自动切换。

enable-proxytext

1. 打开 CC-Switch 主界面
2. 点击顶部代理开关，或进入设置 → 高级 → 代理服务
3. 确认监听地址为 127.0.0.1
4. 确认监听端口为 15721
5. 启动代理
6. 在应用接管里启用目标工具
7. 重启目标 CLI

应用接管后，CC-Switch 会把目标工具指向本地代理。例如 Codex 会写入类似：

codex-proxy.toml

base_url = "http://127.0.0.1:15721/v1"

Claude Code 会写入类似：

claude-proxy.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
  }
}

停止代理时，CC-Switch 会恢复应用配置并保存请求日志。

OAuth 场景

API Key 模式用于普通模型调用。OAuth 模式用于 ChatGPT / Codex 账号能力、插件能力或官方账号额度。两者不要混在同一个终端会话里排查。

oauth-flowtext

1. 如果目标是模型调用，使用 kukuai.fyi API Key
2. 如果目标是账号权益或插件能力，退出 API Key 模式
3. 清理 OPENAI_API_KEY / OPENAI_BASE_URL 等环境变量
4. 在 CC-Switch 或目标工具里重新走 OAuth 登录
5. 启用对应官方或 OAuth 供应商
6. 重新打开一个干净终端测试

CC-Switch 官方文档提到 Codex OAuth 反向代理可用 ChatGPT 账号在 Claude Code 中复用 Codex 服务。这个功能依赖逆向 OAuth 流程，存在服务条款、账号风控和长期可用性风险。生产环境和团队共享环境建议优先使用 API Key 中转。

验证路由

先直接验证 kukuai.fyi，再验证 CC-Switch 和目标 CLI。

smoke-test.shbash

curl https://www.kukuai.fyi/api-proxy/china/v1/chat/completions \
  -H "Authorization: Bearer $KUKUAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-2-chat-latest",
    "messages": [{"role": "user", "content": "测试 CC-Switch 路由"}]
  }'

验证顺序：

1. 直接 curl 请求 kukuai.fyi 成功。
2. CC-Switch 供应商卡片启用成功。
3. 如果开启本地代理，代理面板显示运行中。
4. 目标 CLI 重启后执行一条最小任务。
5. 在 CC-Switch 用量或请求日志里能看到请求记录。

MCP、Prompts、Skills 和会话

CC-Switch 不只管理 API Key。官方手册还提供以下集中管理能力：

功能	用途
MCP	统一管理 Claude、Codex、Gemini、OpenCode、OpenClaw、Hermes 的 MCP 服务器配置
Prompts	管理 CLAUDE.md、AGENTS.md、GEMINI.md 等提示词预设
Skills	从 GitHub 仓库或 ZIP 安装技能，并同步到支持的应用
Sessions	浏览、搜索和恢复不同工具的会话历史
用量统计	查看请求、Token、模型、供应商和成本趋势

这些能力和 kukuai.fyi 供应商配置互不冲突。建议先把模型路由验证通，再配置 MCP、Skills 和 Prompts。

数据目录与备份

CC-Switch 默认数据目录：

config-dirtext

~/.cc-switch/
├── cc-switch.db
├── settings.json
├── skills/
├── skill-backups/
└── backups/

其中 cc-switch.db 是供应商、MCP、Prompts、Skills、代理日志、健康状态和模型定价的单一事实源。settings.json 是设备级设置，通常不跨设备同步。

配置建议：

• 不要手动编辑 cc-switch.db。
• 迁移设备前使用“设置 → 高级 → 数据管理 → 导出”。
• 启用云同步时，优先同步 CC-Switch 自身数据目录，而不是手动复制各 CLI 配置文件。
• 每次大量导入或切换前保留备份。

常见问题

troubleshootingtext

1. 工具仍然走旧地址
   - 确认供应商卡片已启用
   - 如果用了本地代理，确认应用接管已启用
   - 重启终端和目标 CLI

2. 返回 401
   - API Key 不正确
   - 当前供应商不是 kukuai.fyi 的 Key
   - OAuth 和 API Key 环境变量混在一起

3. 返回 404
   - OpenAI 兼容 Base URL 应带 /v1
   - Claude 兼容 Base URL 通常不带 /v1
   - 客户端要求 Base URL 时不要填完整 /chat/completions

4. Codex 看不到第三方模型
   - 检查是否需要本地路由映射
   - 检查模型映射表
   - 修改后重启 Codex

5. 本地代理启动失败
   - 默认端口 15721 可能被占用
   - 停止代理后修改端口
   - 检查系统防火墙或权限

6. 插件不可用
   - 如果你在 API Key 模式，这是正常限制
   - 退出 API Key 模式，清理环境变量后改用 OAuth

下一步

• 查看 Codex CLI 接入教程
• 查看 Claude Code 接入教程
• 查看插件 OAuth 教程
• 返回集成总览