Beginner Guide // CC Switch

把 ZPIKA 密钥接入 Codex 或 Claude Code

不需要手动改配置文件。安装好常用的 AI 编程工具后，在本站创建密钥并用 CC Switch 导入配置，重启工具即可开始使用。

CODEX CLAUDE CODE CC SWITCH

开始前，先理解这三样东西

API Key 等同于你的账户密码只在自己的电脑和受信任的软件中使用。不要把 Key 发到群聊、截图、工单或聊天窗口；怀疑泄露时，立即在本站控制台删除该 Key 并重新创建。

Codex / Claude Code

你真正用来写代码、问问题的 AI 工具。二选一安装即可，也可以两个都装。

CC Switch

一个本地配置管理工具，负责把本站的连接信息写入 Codex 或 Claude Code，省去手动修改文件。

Codex App 和 Claude Code 怎么用

两者都是让 AI 帮你理解和修改代码的工具。先选一个熟悉即可，不需要同时学会两个。

Codex App

打开官方 Codex 桌面应用，选择要处理的本地项目文件夹，然后在对话框直接说清楚任务，例如“帮我修复登录按钮”或“解释这个报错”。它会读取项目并给出修改建议或代码变更，确认后再应用。

Claude Code

它主要在终端中使用。打开终端，先进入项目目录，再运行 claude。首次使用按提示登录；进入对话后直接描述要做的事。它执行文件修改或命令前会请求许可，新手先阅读提示并确认操作范围即可。

Claude Code 最短使用流程

cd 你的项目文件夹
claude

> 请先解释这个项目的目录结构，再告诉我入口文件在哪里

启动后，直接在 > 后输入自然语言任务即可。需要帮助时输入 /help；结束本次会话可输入 /exit，或直接关闭终端。

第一次建议从小任务开始例如解释一个文件、改一段文案或修复单个报错。无论使用哪个工具，涉及删除文件、安装软件或提交代码时，都先看清它准备执行的操作。

第一步：安装 AI 编程工具和 CC Switch

  1. 先选一个工具安装并至少成功打开一次 Codex 或 Claude Code。已经装好的用户可以跳过。
  2. 安装 CC Switch前往 CC Switch 官网 或 GitHub Releases，下载与你的 Windows、macOS 或 Linux 系统匹配的安装包。
  3. 打开一次 CC Switch首次打开时，按界面提示允许它识别本机已安装的 Codex 或 Claude Code。这里不需要填写本站 Key。

第二步：在本站创建个人密钥

  1. 登录 ZPIKA 控制台进入密钥管理页面，点击新建密钥。
  2. 给密钥取一个容易识别的名字例如 我的电脑-CCS。一个设备或一种用途使用一把 Key，日后停用或排错会更方便。
  3. 默认使用 Codex 分组新建令牌默认属于 Codex 分组，用于 Codex 接入时通常无需额外调整。
  4. 需要其它模型时，先看模型广场打开模型广场查看每个可选分组包含哪些模型、对应什么用途以及调用倍率。确认需要的模型后，再把密钥调整到匹配的分组。
  5. 在密钥选项中选择 CC Switch创建后，在该 Key 的选项里选择 CCS / CC Switch。页面会弹出或提供一键配置入口。

不同分组的可用模型和调用倍率不同，先在模型广场确认再调整。不要把 Key 复制到公开位置；正常情况下，你只需要通过一键配置入口把它交给本机的 CC Switch。

第三步：导入到 CC Switch

  1. 点击本站弹窗中的导入按钮浏览器可能会询问是否允许打开 CC Switch；请选择允许 / 打开。
  2. 在 CC Switch 中确认保存它会带入本站的连接信息和你的 Key。确认目标工具是 Codex 或 Claude Code，然后保存为当前配置。
  3. 完全退出正在运行的工具关闭当前终端、Codex 或 Claude Code 会话，再重新打开。多数命令行工具会在启动时读取新配置。
推荐顺序
1. 先安装 Codex 或 Claude Code
2. 再安装并打开 CC Switch
3. 在本站新建 Key，选择 CCS
4. 允许浏览器唤起 CC Switch 并保存
5. 重启 Codex 或 Claude Code

第四步：确认已经连通

重新打开你使用的工具，创建一个新会话，输入一个简单任务，例如“请用一句话说明这个项目的作用”。能正常收到回复，就表示配置已生效。

  • 新终端或新会话里能正常发起请求。
  • CC Switch 中当前选中的配置是刚刚导入的 ZPIKA 配置。
  • 没有把 API Key 粘贴到对话内容、代码仓库或截图中。

可选：在 Codex App 里调用外部生图

同一把 Key 暂不支持同时用于 Codex 推理和生图模型需要在 Codex App 内测试生图时，请另建或调整一把属于图片模型分组的 Key。不要拿当前 Codex 推理 Key 直接调用 gpt-image-2。

下面是一种让 Codex App 帮你在本机项目目录里测试生图的办法。它不是 Codex 内建的图片按钮，而是由 Codex 根据配置文件生成并运行一个调用图片接口的小工具。

  1. 准备图片模型 Key在模型广场确认 gpt-image-2 所属的图片分组与倍率，再创建或调整一把图片模型 Key。
  2. 在项目根目录新建配置文件创建 image-gen-env.txt，仅保存在自己的电脑中，并将它加入 .gitignore，避免 Key 被提交到仓库。
# image-gen-env.txt
base_url=https://aivideo.zpika.com
api_key=sk-你的图片模型Key
image_model=gpt-image-2
out_path=/你的图片输出文件夹
  1. 让 Codex 写一个首次测试工具在 Codex App 中告诉当前可用的推理模型（例如 gpt-5.5）：“读取 image-gen-env.txt，按 ZPIKA 的 gpt-image-2 图片接口文档写一个生图测试工具。只读取文件中的 api_key，不要依赖 OPENAI_API_KEY，不要把 Key 写入日志；将生成结果下载到 out_path。”
  2. 先完成一次小测试让它生成一张简单图片并保存到输出目录。首次运行可能需要安装项目依赖；确认它准备执行的命令和改动后再允许。
  3. 成功后做成可复用 skill继续让 Codex 在当前项目中创建名为 imagegen-preview 的 skill：以后读取同一份 image-gen-env.txt，接收提示词，调用图片接口，并输出或展示保存后的图片路径。

gpt-image-2

适合先跑通上面的流程。接口是 OpenAI 兼容的图片生成格式，详情见 gpt-image-2 文档。

banana / Gemini 生图

需要对应的图片分组 Key。把 Gemini 生图文档链接交给 Codex，让它按 Gemini 原生请求规则另建或调整 skill；不要只把 gpt-image-2 改成 banana 模型名。

可选增强：Codex++

如果你使用的是官方 Codex 桌面应用，并希望增加供应商管理、会话管理或界面增强等能力，可以在官方应用安装并能正常启动后，再考虑安装开源项目 Codex++。

它是可选增强工具，不是接入本站的前提先用 CC Switch 跑通 Codex 或 Claude Code，再安装 Codex++。安装后请从 Codex++ 的入口启动官方 Codex，并按该项目的说明完成设置。
打开 Codex++ Releases → 查看项目说明

常见问题

点了 CCS 后没有弹出 CC Switch？

先确认 CC Switch 已安装并至少打开过一次；然后在浏览器地址栏附近查看是否拦截了“打开外部应用”的请求，选择允许后再试。仍无效时，回到密钥选项重新生成一键配置入口。

导入成功后，Codex / Claude Code 还是走旧配置？

请完全退出工具和终端后重新打开，并在 CC Switch 确认刚导入的配置处于当前启用状态。不要同时手动编辑同一份配置文件，以免被工具覆盖。

我可以把同一把 Key 发给朋友吗？

不建议。Key 会计入你的账户用量，也难以追踪问题。请让每位使用者在自己的账户中创建并管理自己的 Key。

想恢复官方登录怎么办？

在 CC Switch 中切换回官方配置，再按 Codex 或 Claude Code 的官方登录流程登录即可。保留不同配置，日后可以随时切回 ZPIKA。