macOS：Codex 桌面版

Codex 桌面体验位于 ChatGPT 桌面应用中。由于图形应用不会读取 ~/.zshrc，本页使用 macOS 钥匙串保存悠然 AI API Key。

在 macOS 上使用 Codex 桌面版

Codex 桌面体验位于 ChatGPT 桌面应用中，与终端版共享用户级配置，但安装、启动和密钥读取方式不同。

1. 安装 ChatGPT 桌面应用

   安装适用于 macOS 的 ChatGPT 桌面应用，打开后从产品选择器进入 Codex。

   打开 ChatGPT 官方下载页面

2. 登录桌面应用

   使用 ChatGPT 账号登录桌面应用。不要把悠然 AI API Key 填入“Sign in another way”或 OpenAI API Key 登录框；该入口只验证 OpenAI Platform Key。

3. 创建悠然 AI API Key

   在控制台为桌面应用创建独立 Key，便于单独查看请求和撤销权限。

   打开访问密钥页面

4. 查询可用模型

   从实时返回的 data[].id 中选择模型 ID。

   终端复制

   curl -sS https://youran-ai.du-fu.com/api/models \\
     -H "Authorization: Bearer <YOURAN_API_KEY>"

5. 为桌面应用保存 API Key

   macOS 图形应用不会读取 ~/.zshrc，因此将 Key 保存到当前用户的系统钥匙串。

   终端复制

   read -s "YOURAN_API_KEY?请输入悠然 AI API Key："
   echo
   security add-generic-password -a "$USER" -s "youran-ai-codex" -w "$YOURAN_API_KEY" -U
   unset YOURAN_API_KEY

6. 打开并写入桌面配置

   在桌面应用中打开 Settings → Configuration → Open config.toml。终端、IDE 与桌面应用共享此用户级配置文件。

   将模型 ID 替换为实时查询结果。桌面版通过系统钥匙串读取 Key，不需要在配置文件中写入 Key。

   TOML复制

   model = "<MODEL_ID>"
   model_provider = "youran"
   
   [model_providers.youran]
   name = "悠然 AI"
   base_url = "https://youran-ai.du-fu.com/api"
   wire_api = "responses"
   
   [model_providers.youran.auth]
   command = "/bin/zsh"
   args = ["-lc", '/usr/bin/security find-generic-password -a "$USER" -s "youran-ai-codex" -w']
   refresh_interval_ms = 0

7. 重新打开应用并发起请求

   完全退出 ChatGPT 桌面应用后重新打开，选择一个本地文件夹，从产品选择器进入 Codex 并发送“请只回复：连接成功”。

8. 桌面版功能边界

   悠然 AI Key 只负责自定义模型请求。依赖 ChatGPT 工作区或云端服务的功能仍需要相应的 ChatGPT 账号权限，并不由悠然 AI API Key 解锁。

   查看 Codex 官方配置说明