Codex 多开助手

图文用户手册

从安装到创建第一个 Codex 多开窗口。

Codex 多开助手用于创建多个相互隔离的 Codex 桌面窗口。每个窗口都可以拥有独立的工作区、配置文件、API Key、Base URL 和模型。

适合这些场景
  • 一个 Codex 窗口不够用，需要同时开启多个窗口处理不同项目。
  • 希望一个窗口使用官方 OpenAI API Key，另一个窗口使用第三方 Responses 兼容接口。
  • 不想手动修改 `config.toml`、启动脚本或命令行参数。

1. 安装与打开

  1. 解压 `Codex 多开助手-版本号-arm64-mac.zip`。
  2. 将 `Codex 多开助手.app` 拖到 `Applications`，或直接双击打开。
  3. 如果 macOS 提示无法打开，说明这是未签名测试版，可以在终端执行下面的命令。
xattr -dr com.apple.quarantine "/Applications/Codex 多开助手.app"

当前测试版主要面向 macOS Apple Silicon。正式公开分发前需要签名和 notarization。

2. 主界面说明

Codex 多开助手主界面，展示 Profile 列表和选中 Profile 的详细信息。
左侧是 Profile 列表，右侧是当前选中 Profile 的路径、Provider、运行状态和操作按钮。

一个 Profile 就是一套独立 Codex 工作区配置。主界面会显示：

  • `CODEX_HOME`：该 Codex 窗口使用的配置目录。
  • `user-data-dir`：该 Codex 桌面窗口自己的应用数据目录。
  • `Launcher`：生成的双击启动器 App。
  • `Provider`：当前使用的 API 服务商。
  • `Base URL`：第三方接口地址。
  • `Env key`：启动器内部使用的环境变量名。

3. 创建新的 Codex 多开窗口

点击左侧 `创建 Profile` 后，会打开创建向导。

创建 Profile 第一步，填写名称并选择是否继承默认 Codex 配置。
建议保持“继承默认 Codex 配置”开启，以保留已有插件、MCP 服务、可信项目和功能开关。
  • `Profile 名称`：建议使用容易识别的名字，例如 `Su8 工作区`、`官方账号`、`项目 A`。
  • `继承默认 Codex 配置`：建议保持开启。

4. 配置 Provider

Provider 配置步骤，包含 Provider 类型、Base URL、模型和 API Key。
第三方中转站一般选择“第三方 Responses 兼容接口”，并填写 Base URL、模型和 API Key。

如果使用第三方中转站，按下面填写：

  • `Provider 类型`：选择 `第三方 Responses 兼容接口`。
  • `Provider 名称`：填写便于识别的名称，例如 `Su8`、`公司代理`。
  • `Base URL`：填写第三方提供的 OpenAI 兼容地址，通常以 `/v1` 结尾。
  • `模型`：填写模型 ID，例如 `gpt-5.2`。如果服务商支持 `/models`，可以点击 `获取模型` 后从列表中选择。
  • `API Key`：填写第三方服务商提供的 API Key。

如果使用官方 OpenAI API Key，`Provider 类型` 选择 `官方 OpenAI API Key`，填写模型和 API Key 即可。

API Key 会保存在本地加密文件中，不会写入 `config.toml`，也不会出现在诊断报告中。

5. 测试、选择启动器位置并生成

进入 `测试` 步骤后，点击 `测试 Provider`。测试会检查 Base URL 是否可访问、API Key 是否能通过认证、Provider 是否支持 Responses API。

进入 `启动器` 步骤后，可以选择生成的 `.app` 启动器保存位置。默认位置：

~/Applications/Codex Profiles/

最后一步确认信息后点击 `生成`。生成完成后，在主界面选择 Profile 并点击 `打开`，Codex 会使用对应 API Key 和 Base URL 配置。

6. 修改已有 Provider 和恢复备份

在主界面下方可以编辑当前 Profile 的 Provider：

  • 修改 `Provider 名称`、`Base URL` 或 `模型`。
  • 如果不想更换 API Key，`新的 API Key` 保持空白。
  • 点击 `测试` 可以复用已保存的 API Key 进行测试。
  • 点击 `保存 Provider` 会同步更新 Profile 的 `config.toml` 和启动器。

每次保存前，App 会自动创建配置备份。你可以在 `最近配置备份` 中恢复旧配置。

7. 查看环境检查

点击顶部环境状态按钮，例如 `1 warning`，可以查看本机环境。

环境检查弹窗，展示 Codex App、Node runtime 和目录权限检查。
如果只有 Codex CLI 是 warning，一般仍可继续使用桌面多开功能。

8. 移除、恢复和彻底删除

`移除` 只是把 Profile 从常用列表里隐藏，配置文件和启动器仍保留。

如需查看已移除的 Profile，勾选左侧 `显示已移除`。选择已移除 Profile 后，可以点击 `恢复` 重新启用。

`彻底删除` 会删除该 Profile 的 `CODEX_HOME`、`user-data-dir`、生成的启动器 App 和本地加密保存的 API Key。彻底删除无法恢复，请谨慎操作。

9. 常见问题

打开生成的 Codex 后还是进入登录页

通常说明 Profile 配置或 `auth.json` 没有正确生成。请回到 Codex 多开助手，选择该 Profile，点击 `保存 Provider` 后再点击 `打开`。

对话请求走了官方 Base URL

请检查当前 Profile 的 `Provider` 和 `Base URL` 是否正确。修改后点击 `保存 Provider`，再重新打开该 Profile。

获取模型失败

部分第三方服务商不提供 `/models`，或者返回格式不兼容。此时可以继续手动填写模型 ID。

测试 Provider 报 401 或 403

通常是 API Key 不正确、额度不足，或服务商要求使用不同的 Key 格式。请在服务商后台确认 Key 可用。

10. 安全说明

  • API Key 只保存在本机。
  • API Key 使用本地加密文件保存。
  • 诊断报告不会包含 API Key。
  • `config.toml` 和启动器脚本不会写入明文 API Key。
  • 反馈问题时优先使用 `复制诊断`，不要直接发送自己的 API Key。