Codex Desktop App 使用教程

当前 Codex CLI 0.144.4 的 codex app --help 将该入口说明为 Codex desktop app：已安装时启动独立应用，缺失时打开安装入口。本页按独立 Codex Desktop App 说明，不再把它描述成 ChatGPT 侧栏功能。

桌面应用的登录入口和字段名称可能随版本调整。下面仅按当前官方说明中的 API Key / Sign in another way 路径说明；请以你当前安装版本显示的界面为准，本页不假定桌面应用会自动复用 Codex CLI 的凭据。

1. 适合谁

如果你希望用图形界面打开本地项目、创建任务和查看变更，可以使用桌面端；只在终端工作则直接使用 Codex CLI。

2. 安装独立桌面端

优先在已安装 Codex CLI 的终端执行：

codex app

也可以从 Codex App 官方说明 获取当前安装方式。应用界面可能随版本调整；安装后在独立 Codex App 中打开本地项目。

在欢迎页选择 **Enter API key**；如果未显示该入口，先选择 **Sign in another way**。

如果应用中已经登录过其他账号或 Provider，先退出旧登录并完全关闭应用，避免旧会话继续覆盖当前配置。

3. 配置 Provider 和应用内认证

按 Codex CLI 教程 中的 Provider 配置示例创建用户目录下的 .codex/config.toml：

model = "YOUR_MODEL_ID"
model_provider = "duckmans"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.duckmans]
name = "DuckMans"
base_url = "https://duckmans.com/v1"
wire_api = "responses"
requires_openai_auth = true

不要把真实 Key 写入 config.toml。

把 YOUR_MODEL_ID 替换为 DuckMans 后台当前可用模型 ID。

首次进入 Codex 时，在桌面应用内选择 API Key；如果先显示其他登录方式，选择 Sign in another way 后再进入 API Key 登录。粘贴 DuckMans API Key 并按当前界面完成登录。不同版本的按钮名称或顺序可能不同，如果 App 已复用 CLI 的认证状态，不需要重复录入；若仍显示登录页，再按当前界面选择 API Key 登录。登录方式及认证存储行为以 OpenAI Codex 官方认证说明 为准。

4. 完全重启并测试

1. 从应用菜单完全退出 Codex Desktop App，而不是只关闭窗口。
2. 运行 codex app 或从“应用程序”重新打开 Codex。
3. 添加一个不含敏感文件的测试文件夹。
4. 新建任务并输入：

请读取当前目录并总结项目结构，不要修改任何文件。

确认返回内容后，再逐步尝试修改任务。

选择测试项目，在任务输入框中发送上方最小测试内容，并检查返回结果。

常见问题

• 仍跳转旧登录：退出应用内旧账号，完全退出后重开，再从 Sign in another way 选择 API Key。
• CLI 正常、桌面端失败：确认两者使用同一系统用户和同一个 CODEX_HOME，并完全重启 App。
• 401：在桌面应用内重新填写 DuckMans API Key，确认没有粘贴兑换码、空格或换行。
• 404：确认 base_url 是 https://duckmans.com/v1。
• 模型不存在：使用 DuckMans 后台当前可用模型 ID，不要照抄旧教程模型名。

恢复原配置

修改前备份 ~/.codex/config.toml。需要回滚时恢复备份并完全重启 Codex App；不要复制或公开认证缓存文件。