公告: 可灵 Kling 4.0 上新，文生视频与图生视频限时 8 折，立即体验
HiAPI
Zh
教程目录
Agent 工具接入

快速接入

API Key 配置MCP 一键接入

准备

获取 API KeyBase URL 与协议Node.js 环境CC Switch 安装与一键导入通用报错

命令行

Claude CodeCodex CLIOpenCodeOpenClawHermesPi

桌面端 / 客户端

Claude 桌面端Codex 桌面端Cherry StudioTraeWorkBuddyDeepSeek Harness
本页内容

Codex 桌面端

全程图形界面，用 CC Switch 一键导入，通过 HiAPI 在 Codex 桌面端使用 GPT 模型。

Codex 桌面端可以通过 CC Switch 一键导入接入 HiAPI。下面以 gpt-6-astra 为例，HiAPI 走 OpenAI Responses 协议。全程使用图形界面，不需要安装 Node.js、运行命令或编辑配置文件。

1. 安装 Codex 桌面端

  1. 打开 OpenAI 官方桌面入门页，选择 Desktop app 下载入口。Mac 使用官方 Codex.dmg，以官方页面的系统与芯片要求为准。

  2. 打开 Finder → 下载，双击 .dmg，把应用拖到「应用程序」。复制完成后从「应用程序」打开，系统询问时核对是官方来源再点 打开。

  3. 第一次打开停在登录页时，先留在这一页，继续安装 CC Switch、导入并启用 HiAPI。不用先登录一次 ChatGPT 再退出。

Windows：在官方页面选 Windows 安装包，按安装向导完成后从「开始」打开，不要用 Mac 的 DMG。

2. 安装并打开 CC Switch

按 CC Switch 安装与一键导入 下载、安装并打开 CC Switch，已有的直接打开。

已有供应商的，先记下 Codex 页标着「使用中」的卡片名称，需要时按 备份现有配置 导出 SQL 备份。

3. 选定 HiAPI API Key

按 获取 API Key 选定或新建一个 Key，记下它的名称。这一步不用复制 Key，导入时会自动带上。

4. 在网页准备一键导入

  1. 打开 HiAPI Codex 接入页，选择 API Key 配置 → Codex → 桌面端 → gpt-6-astra → macOS。Windows 系统选 Windows。

接入页导入入口

①选 API Key 配置；②选 Codex；③选桌面端；④选 gpt-6-astra；⑤系统选 macOS（Windows 改选 Windows）；⑥点导入 CC Switch。

  1. 点 导入 CC Switch，在弹窗的 API Key 下拉框选前面记下的 Key 名称，底部应为 Responses API · https://api.hiapi.ai/v1。
  2. 点 准备导入，再点 打开 CC Switch；浏览器询问时允许本次打开。

每一步的截图见 在接入页准备导入。

5. 在 CC Switch 确认导入

在「确认导入供应商配置」窗口核对下面几项，将 导入后立即切换到这个供应商 保持关闭，再点 导入：

项目应为
应用类型Codex
供应商名称HiAPI - gpt-6-astra
API 端点https://api.hiapi.ai/v1
模型gpt-6-astra
API 密钥有值且保持隐藏

回到 CC Switch 的 Codex 页能看到 HiAPI - gpt-6-astra 卡片，就表示已经导入（还没启用）。截图见 在 CC Switch 确认导入。

6. 启用 HiAPI

  1. 先等 Codex 正在跑的任务结束。在 CC Switch 的 Codex → 直连 页，点 HiAPI - gpt-6-astra 卡片的 切换 / 启用 按钮，看到卡片标为「使用中」才算启用。截图见 启用 HiAPI。
  2. 完全退出并重开 Codex，让新配置生效。CLI 和桌面端可能共用本机 Codex 配置；日后想换回原供应商，在这里切回原卡片并重开客户端即可。

7. 重开客户端，按需登录

  1. 等正在跑的任务结束，Mac 在应用菜单点 退出 或按 ⌘Q，再从「应用程序」打开。只关窗口不算退出；Windows 也先从应用菜单退出，再从「开始」打开。

  2. 直接进入主界面的，继续下一步。出现 API Key 登录入口的，点 Sign in another way，再到 HiAPI 控制台 → API 密钥 找到前面选定的 Key，点旁边的复制图标，复制完整的 HiAPI API Key。

  3. 回到客户端，把 HiAPI API Key 粘贴到 API Key 输入框，点 Continue。不要粘到聊天输入框，也不要复制名称或带星号的显示值。不同版本文案可能不同，以 API Key 登录入口为准，不用去改配置文件。

8. 打开本地文件夹，选择模型开始用

  1. Mac 在 Finder 菜单点 前往 → 个人，按 ⌘⇧N 新建 hiapi-project 文件夹并回车确认，也可以直接用已有的项目文件夹。

    Windows 用资源管理器打开用户目录，空白处右键 新建 → 文件夹，命名为 hiapi-project。

  2. 在客户端点 新聊天 / 新建任务，进入 Codex，选择 本地 工作方式。点 打开 / 添加文件夹，Mac 文件选择器里可按 ⌘⇧G 输入 ~/hiapi-project，回车后点 打开 / 选择文件夹；Windows 选刚建的文件夹。

  3. 在这个文件夹里新建聊天，打开输入框旁的模型选择器，选 GPT-6 Astra / gpt-6-astra。不同版本可能把 Codex 放在产品菜单或单独的项目区域，只要是本地方式、目标文件夹和模型都对就行。

  4. 权限保持默认的按需审批。发送「你好，用一句话介绍你自己。」，能正常回复就说明接入成功。在 HiAPI 控制台的 调用记录 里能看到这次请求，就说明走的是 HiAPI。之后写下要完成的任务即可。

常见问题

下面只列 Codex 桌面端特有的问题，401、404、429 等通用报错见 通用报错。

现象原因处理
重开后仍停在 ChatGPT 登录页桌面端要求用 API Key 登录点 Sign in another way，粘贴 HiAPI API Key，见第 7 步
模型选择器里没有 gpt-6-astraHiAPI 卡片没启用，或客户端没完全退出在 CC Switch 的 Codex 页确认 HiAPI 卡片标为「使用中」，再按 ⌘Q 完全退出并重开
命令行版的 Codex 也跟着变了两者共用本机的 Codex 配置正常现象；想换回原供应商，在 CC Switch 里切回原卡片