Zivv Docs

主题

Codex 桌面端配置指南 ​

OpenAI 已将 Codex 工作流整合进 ChatGPT 桌面应用。Zivv 通过 Codex 自定义 Model Provider 接入，核心配置与 Codex CLI 相同。

最近核验：2026-07-24。桌面界面可能随 ChatGPT 更新变化；配置字段以 OpenAI 官方 Codex 配置参考为准。

共享配置

Codex CLI、IDE 扩展和桌面端通常使用用户级 ~/.codex/config.toml。如果 CLI 已配置 Zivv，一般不需要再维护第二份 Provider 配置。

准备工作 ​

1. 配置 Provider ​

配置文件位置：

  • Windows：%USERPROFILE%\.codex\config.toml
  • macOS：~/.codex/config.toml
  • 设置了 CODEX_HOME 时：$CODEX_HOME/config.toml

可从 Codex 设置中选择 Open config.toml，也可以直接编辑文件。已有配置时只合并下面内容：

toml
model_provider = "zivv"
model = "模型广场中的模型 ID"

[model_providers.zivv]
name = "Zivv"
base_url = "https://zivv.pro/v1"
env_key = "ZIVV_API_KEY"
wire_api = "responses"

不要把 Key 直接写进 config.toml，也不要删除已有 MCP、项目权限、功能开关和其他 Provider。

2. 让桌面应用读取 API Key ​

图形应用不一定继承终端环境变量。先设置用户环境变量：

powershell
[Environment]::SetEnvironmentVariable("ZIVV_API_KEY", "sk-你的Key", "User")
bash
echo 'export ZIVV_API_KEY="sk-你的Key"' >> ~/.zshrc
source ~/.zshrc

如果 macOS 桌面端仍读不到变量，可按 OpenAI 对桌面客户端的建议，在 ~/.codex/.env 中写入所需变量：

dotenv
ZIVV_API_KEY=sk-你的Key

.codex/.env 包含密钥，不要同步到云盘、公开仓库或截图。

完全重启应用

修改环境变量或 .codex/.env 后，从系统托盘或菜单栏完全退出 ChatGPT，再重新打开。只关闭窗口可能仍保留后台进程。

3. 验证 ​

  1. 保存 config.toml。
  2. 完全退出并重新打开 ChatGPT 桌面应用。
  3. 进入 Codex 工作区并选择本地项目。
  4. 发送“只回复 pong”。

如果同时安装了 Codex CLI，建议先用相同配置测试：

bash
codex exec "只回复 pong"

CLI 成功而桌面端失败时，问题通常在桌面进程没有读取密钥，而不是 Provider 配置。

常见问题 ​

桌面端提示未认证 ​

  • 确认 ZIVV_API_KEY 拼写与 env_key 一致
  • 完全退出应用，而不是只关闭窗口
  • 检查 ~/.codex/.env 是否位于当前用户的 CODEX_HOME
  • Key 轮换后删除旧值并重启应用

CLI 和桌面端使用了不同配置 ​

检查两边的 CODEX_HOME 是否一致。Provider 应写在用户级配置中，不要只写在某个项目的 .codex/config.toml。

返回 404 或协议不兼容 ​

必须使用：

toml
base_url = "https://zivv.pro/v1"
wire_api = "responses"

不要把 base_url 写成完整的 /v1/responses 地址。

模型不可用或请求被限制 ​

从 模型广场 复制准确模型 ID，并检查 Responses API 支持、Key 分组、余额、额度和团队预算。

官方资料 ​

Zivv — OpenAI / Anthropic / Gemini 多协议 AI Gateway

© 2026 Zivv