Codex Desktop

​

一、准备工作

• 已安装并能正常打开 Codex 桌面界面。
• 已注册 GravitexAI 控制台，账号余额充足。
• 已在 密钥管理 创建 API Key，所属分组支持目标 GPT 模型及 Responses API。

​

确认客户端版本（可选）

ls /Applications/ChatGPT.app
/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex --version

​

二、验证 API Key 和模型权限

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"}'

$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

​

三、编辑配置文件

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

$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

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"

​

四、通过 CC Switch 接入

1. 按 CC Switch 安装指南 安装并打开工具，进入 Codex 页面。
2. 添加 GravitexAI 供应商：名称填 GravitexAI，API Key 填控制台密钥，Base URL 填 https://api.gravitex.ai/v1，模型填已验证可用的 GPT 模型 ID（如 gpt-6.1-sol）。若有协议选项，选择 Responses。
3. 保存后将该供应商切换为当前使用项。检查写入的是上文对应系统的 Codex 用户配置目录；自定义 CODEX_HOME 时尤其要确认路径一致。
4. 完全退出 Codex 桌面应用，再重新打开。macOS 使用 Command + Q；Windows 从应用或托盘菜单退出，必要时保存任务后通过任务管理器结束对应残留进程。
5. 按下文验证对话、文件工具调用和控制台记录。

​

五、通过 Magpie 接入

1. 按 Magpie 安装与供应商配置指南 安装工具。添加 gravitex 提供方，填入 GravitexAI 密钥，并确保 Responses 基础地址为 https://api.gravitex.ai/v1；已有提供方可直接补充该端点。 截图中的供应商 ID 为 gravitexai，下文命令示例使用 gravitex。若按截图设置，请将命令中的提供方 ID 改为 gravitexai，例如 magpie codex gravitexai/gpt-6.1-sol。
2. 完全退出 Codex 桌面应用，并按上文备份配置。
3. 在终端执行以下命令。模型 ID 以当前分组实际可用列表为准，gravitex 必须与自己的提供方 ID 一致。

magpie ls
magpie provider set gravitex responses=https://api.gravitex.ai/v1
magpie codex gravitex/gpt-6.1-sol

magpie.exe ls
magpie.exe provider set gravitex responses=https://api.gravitex.ai/v1
magpie.exe codex gravitex/gpt-6.1-sol

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

​

六、验证桌面端接入

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

​

七、常见问题排查

​

八、可选调整与注意事项

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

​

九、参考资料

• Codex CLI 接入指南
• GravitexAI 密钥管理
• GravitexAI 模型广场
• OpenAI 配置参考
• Windows desktop configuration
• CC Switch documentation
• Magpie reference