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

# Codex Desktop

> Codex 桌面版接入指南：通过 GravitexAI 配置 GPT 模型、验证连接与工具调用

## 一、准备工作

本指南介绍在 **macOS 和 Windows** 的 Codex 桌面界面中接入 GravitexAI。请先安装对应系统的客户端，并确认能正常打开 Codex 界面；不同发行版的安装位置和界面可能不同。终端使用方式请参阅 [Codex CLI 接入指南](https://docs.gravitex.ai/cn/integrations/codex.md)。

* 已安装并能正常打开 Codex 桌面界面。
* 已注册 [GravitexAI 控制台](https://maas.gravitex.ai)，账号余额充足。
* 已在 [密钥管理](https://maas.gravitex.ai/#/keys) 创建 API Key，所属分组支持目标 GPT 模型及 Responses API。

### 确认客户端版本（可选）

对于安装在 `/Applications/ChatGPT.app` 且包含以下内核路径的版本，可在终端执行：

```bash theme={null}
ls /Applications/ChatGPT.app
/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex --version
```

若路径不存在，请按实际安装位置确认版本，不要直接套用其他发行版的内部路径。

Windows 用户可在应用的“关于”或设置页面查看版本，无需执行上面的 macOS 命令。

## 二、验证 API Key 和模型权限

创建密钥后，先测试目标模型能否通过 Responses API 调用。以下以 `gpt-6.1-sol` 为例；实际模型 ID 以 [模型广场](https://maas.gravitex.ai/#/models) 和密钥所属分组权限为准。

> [tab] macOS
>
> ```bash theme={null}
> curl https://api.gravitex.ai/v1/responses \
>   -H "Authorization: Bearer sk-你的密钥" \
>   -H "Content-Type: application/json" \
>   -d '{"model":"gpt-6.1-sol","input":"say ok"}'
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $headers = @{ Authorization = "Bearer sk-your-gravitex-key" }
> $body = @{ model = "gpt-6.1-sol"; input = "say ok" } | ConvertTo-Json
> Invoke-RestMethod -Uri "https://api.gravitex.ai/v1/responses" -Method Post -Headers $headers -ContentType "application/json" -Body $body
> ```

| 返回内容 | 处理方式 |
| - | - |
| `"status": "completed"` | 基础调用成功，可以继续配置 |
| `503` / `No available channel` | 检查分组是否支持该 GPT 模型，也可能是通道暂不可用 |
| `404` / `endpoint_not_found` | 检查地址及分组的 Responses API 支持情况 |
| `401` / `invalid api key` | 检查密钥是否有效，是否带有多余空格或换行 |

> [!NOTE]
>
> 此测试会产生少量 API 用量。成功返回仅验证基础调用；桌面端的工具调用还需在后续步骤中单独验证。

## 三、编辑配置文件

默认用户配置路径如下，两个系统使用相同的 TOML 内容：

| 系统 | 默认路径 |
| - | - |
| macOS | `~/.codex/config.toml` |
| Windows 原生客户端 | `%USERPROFILE%\.codex\config.toml`（通常为 `C:\Users\你的用户名\.codex\config.toml`） |

若设置了 `CODEX_HOME`，请编辑该目录下的 `config.toml`。Windows 下可按 **Win + R** 输入 `%USERPROFILE%\.codex` 打开默认目录。这里配置的是 Windows 原生客户端；WSL 内的 `~/.codex` 通常是另一份目录，不要混用。

**1. 备份并打开配置**

在终端执行：

> [tab] macOS
>
> ```bash theme={null}
> mkdir -p ~/.codex
> # 已有文件时先备份
> if [ -f ~/.codex/config.toml ]; then
>   cp ~/.codex/config.toml ~/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)
> fi
> nano ~/.codex/config.toml
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $codexConfigDir = Join-Path $env:USERPROFILE ".codex"
> if ($env:CODEX_HOME) { $codexConfigDir = $env:CODEX_HOME }
> New-Item -ItemType Directory -Path $codexConfigDir -Force | Out-Null
> $codexConfigPath = Join-Path $codexConfigDir "config.toml"
> if (Test-Path $codexConfigPath) {
>   Copy-Item $codexConfigPath "$codexConfigPath.backup-$(Get-Date -Format yyyyMMdd-HHmmss)"
> } else {
>   New-Item -ItemType File -Path $codexConfigPath | Out-Null
> }
> notepad $codexConfigPath
> ```

**2. 合并以下配置**

将占位密钥替换为自己的 GravitexAI API Key。已有同名字段或表时，修改原位置，避免重复定义。

```toml theme={null}
model = "gpt-6.1-sol"
model_provider = "gravitex"
model_reasoning_effort = "medium"

[model_providers.gravitex]
name = "GravitexAI"
base_url = "https://api.gravitex.ai/v1"
wire_api = "responses"

[model_providers.gravitex.http_headers]
Authorization = "Bearer sk-你的密钥"
Content-Type = "application/json"
```

顶层的 `model`、`model_provider` 和 `model_reasoning_effort` 应放在第一个 `[表名]` 之前。`Authorization` 应位于 `http_headers` 表内，不要放入其他配置表。

**3. 完全退出并重新打开**

保存文件后，按系统完全退出承载 Codex 的应用，再重新打开并创建本地聊天：

* **macOS**：使用 **Command + Q** 退出。
* **Windows**：使用应用菜单中的“退出”；如仍在系统托盘运行，从托盘菜单退出。若无退出入口或仍未生效，先保存任务，再在任务管理器中结束对应应用及其残留 Codex 进程，然后从开始菜单重新打开。

仅关闭窗口可能保留后台进程。

| 字段 | 填写规则 |
| - | - |
| `model` | 填写当前分组实际可用的 GPT 模型 ID，与上一步测试保持一致 |
| `model_provider` | 必须与供应商表名中的 `gravitex` 一致 |
| `base_url` | 使用 `https://api.gravitex.ai/v1`，不要再追加 `/responses` |
| `wire_api` | 使用 `responses` |
| `Authorization` | `Bearer` 后有一个空格，密钥保持在同一行 |

> [!TIP]
>
> `http_headers` 不要求位于文件末尾；关键是 TOML 的表归属正确。新的 `[表名]` 会开始另一张表，后续字段归入该表。

> [!NOTE]
>
> 本示例使用静态请求头，密钥会明文保存在本机配置文件中。也可以通过供应商的 `env_key` 配置环境变量，但从访达或启动台启动的应用通常不会继承终端中临时 `export` 的变量；使用该方式前，应确认应用进程能读取它。 Windows 的 `$env:变量名` 也只影响当前 PowerShell 及其子进程，从开始菜单打开的应用不会自动继承该会话中的临时变量。

## 四、通过 CC Switch 接入

适用于 macOS 和 Windows。先按上文验证 API Key，并备份 Codex 配置；选择此方式后，由 CC Switch 管理供应商配置。

1. 按 [CC Switch 安装指南](https://docs.gravitex.ai/cn/integrations/cc-switch.md) 安装并打开工具，进入 **Codex** 页面。

2. 添加 GravitexAI 供应商：名称填 `GravitexAI`，API Key 填控制台密钥，Base URL 填 `https://api.gravitex.ai/v1`，模型填已验证可用的 GPT 模型 ID（如 `gpt-6.1-sol`）。若有协议选项，选择 **Responses**。

   ![CC Switch 的 Codex 供应商配置：API 请求地址与模型列表](https://mintcdn.com/gravitexai/r6k6xZ-OnsQI5bKV/images/codex-desktop-cc-switch.png?fit=max\&auto=format\&n=r6k6xZ-OnsQI5bKV\&q=85\&s=d2d0ec20ceecb5c4c3c1bcfd0ad63e16)

3. 保存后将该供应商切换为当前使用项。检查写入的是上文对应系统的 Codex 用户配置目录；自定义 `CODEX_HOME` 时尤其要确认路径一致。

4. 完全退出 Codex 桌面应用，再重新打开。macOS 使用 **Command + Q**；Windows 从应用或托盘菜单退出，必要时保存任务后通过任务管理器结束对应残留进程。

5. 按下文验证对话、文件工具调用和控制台记录。

> [!NOTE]
>
> 本节使用供应商切换方式。若另行启用 CC Switch 的本地路由或聚合模式，请按该模式要求保持服务运行；聚合模型列表变化后也需要完全重启 Codex。回退时，在 CC Switch 中切回原供应商，或退出客户端后恢复备份。

## 五、通过 Magpie 接入

此方式的请求链路为 **Codex Desktop → 本机 Magpie → GravitexAI**，macOS 和 Windows 均需保持 Magpie 网关运行。

1. 按 [Magpie 安装与供应商配置指南](https://docs.gravitex.ai/cn/integrations/magpie.md) 安装工具。添加 `gravitex` 提供方，填入 GravitexAI 密钥，并确保 **Responses** 基础地址为 `https://api.gravitex.ai/v1`；已有提供方可直接补充该端点。

   ![Magpie 的 GravitexAI 供应商配置：OpenAI Responses 地址](https://mintcdn.com/gravitexai/r6k6xZ-OnsQI5bKV/images/codex-desktop-magpie.png?fit=max\&auto=format\&n=r6k6xZ-OnsQI5bKV\&q=85\&s=556bf6b7a49daa3cfbd4c5d7e92df96b)

   截图中的供应商 ID 为 `gravitexai`，下文命令示例使用 `gravitex`。若按截图设置，请将命令中的提供方 ID 改为 `gravitexai`，例如 `magpie codex gravitexai/gpt-6.1-sol`。

2. 完全退出 Codex 桌面应用，并按上文备份配置。

3. 在终端执行以下命令。模型 ID 以当前分组实际可用列表为准，`gravitex` 必须与自己的提供方 ID 一致。

> [tab] macOS
>
> ```bash theme={null}
> magpie ls
> magpie provider set gravitex responses=https://api.gravitex.ai/v1
> magpie codex gravitex/gpt-6.1-sol
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> magpie.exe ls
> magpie.exe provider set gravitex responses=https://api.gravitex.ai/v1
> magpie.exe codex gravitex/gpt-6.1-sol
> ```
>
> 未加入 PATH 时，请使用实际程序路径；带空格的路径用 `& "C:\实际路径\magpie.exe"` 调用。

4. 也可在 Magpie 的 **Agent** 页面找到 **Codex**，启用接入并选择 GravitexAI 下的目标模型。确认它管理的目录与桌面端实际使用的 Codex 目录一致。
5. 保持 Magpie 运行，重新打开 Codex Desktop，按下文验证对话和工具调用。若连接失败，检查本地网关端口（默认 `3425`）、代理对 `127.0.0.1` 的处理，以及上游密钥和模型权限。

> [!TIP]
>
> 切回直连时，先在 Magpie 的 Codex 项中断开接入，再恢复之前的配置或通过 CC Switch 切回目标供应商，最后完全重启 Codex。不要同时让 CC Switch 和 Magpie 接管同一份 Codex 配置，以免后一次写入覆盖前一次设置。Magpie 生成的本地网关凭据与 GravitexAI 上游密钥用途不同，不要混填。

## 六、验证桌面端接入

1. 打开一个本地项目文件夹，新建聊天，检查所选模型或供应商。不同版本可能显示模型 ID 或 `Custom`，不要仅凭标签判断请求是否成功。
2. 发送 `hello`，确认能正常收到回复。
3. 发送“看看当前目录有哪些文件”，确认能调用文件或终端工具，并根据结果继续回答；按应用提示授予所需的本地权限。
4. 在 GravitexAI 控制台查看对应调用记录，核对模型和用量。

## 七、常见问题排查

| 现象 | 排查与处理 |
| - | - |
| 仍提示登录官方账号 | 检查实际配置目录、供应商名称及是否完全重启；部分桌面功能仍可能要求官方账号登录 |
| `401` 认证失败 | 检查密钥状态、`Bearer` 后的空格和请求头所属的 TOML 表 |
| `404` 或端点不存在 | 检查 `base_url`，并确认分组支持 Responses API |
| 模型不存在或无可用通道 | 核对模型 ID、密钥分组及通道状态，先用上面的 curl 命令定位 |
| `400` 参数错误 | 根据错误详情检查不受支持的参数；若提示 `service_tier` 不受支持，移除该字段后重试 |
| 修改后没有变化 | 完全退出后重开，检查项目级配置或配置档是否覆盖了用户配置 |
| 能聊天但工具调用失败 | 检查本地权限、客户端版本以及模型和通道的工具调用兼容性 |
| Windows 提示命令不存在或参数错误 | 在 PowerShell 中执行 Windows 标签页的命令，不要直接粘贴 Bash 的反斜杠续行命令 |
| Windows 找不到配置或修改无效 | 确认文件名为 `config.toml` 而非 `config.toml.txt`，并检查 `CODEX_HOME` 及是否误改了 WSL 的配置 |

## 八、可选调整与注意事项

* **更换模型**：修改顶层 `model`，先确认该模型在当前分组可用，再重启应用。
* **调整推理强度**：按模型支持情况选择 `low`、`medium` 或 `high`；更高强度通常消耗更多时间和 token，不保证所有任务效果更好。
* **恢复原配置**：使用备份恢复；如切回官方供应商，可将顶层 `model_provider` 改为 `openai`，并选择官方账号可用的模型，重启后按提示登录。
* **保护密钥**：不要把含密钥的配置提交到仓库或公开截图；泄露后立即作废并重新生成。
* **功能范围**：本指南验证本地聊天和文件工具接入；云端任务、插件等功能的可用性取决于客户端版本、账号及供应商支持情况。

## 九、参考资料

* [Codex CLI 接入指南](https://docs.gravitex.ai/cn/integrations/codex.md)

* [GravitexAI 密钥管理](https://maas.gravitex.ai/#/keys)

* [GravitexAI 模型广场](https://maas.gravitex.ai/#/models)

* [OpenAI 配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)

* [Windows desktop configuration](https://learn.chatgpt.com/docs/windows/windows-app)

* [CC Switch documentation](https://github.com/farion1231/cc-switch)

* [Magpie reference](https://github.com/yetone/magpie/blob/main/docs/reference.md)


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