历史实验：Codex App 加入 GPT-5.3-Codex-Spark 菜单

一句话结论

当前日常配置使用 `gpt-5.6-sol`，实际可用模型以 Key 分组和 `/v1/models` 返回为准；Spark 菜单修改仅作为历史高级实验保留。

适用场景

• 你在 Codex App 或 Codex Desktop 的模型下拉菜单里看不到 GPT-5.3-Codex-Spark
• 你的账号、网关或本地模型目录已经能识别 gpt-5.3-codex-spark，但桌面菜单没有列出来
• 你在维护 2026 年 6 月创建的 Spark 实验配置，需要判断它是否仍适用
• 你已经有 `~/.codex/model-catalogs/spark-enabled.json`，想保留为独立实验 profile
• 你想用 1A1API 或其他中转的 Responses API provider 验证一个历史 Spark 配置
• 你理解本页不是当前默认接入教程，并愿意先按 Key 分组确认模型权限

常见现象

• 命令行里想指定 `--model gpt-5.3-codex-spark`，但不知道是否可用
• Codex CLI 能跑，Codex App 的模型下拉菜单仍然没有 GPT-5.3-Codex-Spark
• 写了 `model = "gpt-5.3-codex-spark"` 后，重开 App 仍然显示旧模型
• 看到了 `model_catalog_json`、`spark-enabled.json`、`profile`、`app.asar` 这些词，但不知道从哪一步开始
• 菜单里有 Spark，但一调用就 401、404 或模型不存在

原因解释

• Codex 的默认模型可以写在 `~/.codex/config.toml` 里；官方手册里也有 `model_catalog_json` 这种启动时读取的模型目录覆盖项。
• 如果当前模型目录里已经包含 `gpt-5.3-codex-spark`，新增菜单这件事其实已经完成，下一步是选择默认模型或 profile。
• 当前日常示例使用 `gpt-5.6-sol`；模型会持续更新，最终以你的 Key 分组和 `/v1/models` 返回为准。
• CLI 指定模型能跑，只说明后端或账号能识别这个模型，不一定代表桌面版模型选择器会把它展示出来。
• 本地配置只能让 Codex App 知道有这个模型，不能绕过 1A1API、账号分组或上游模型权限。
• 模型菜单通常还会经过前端过滤：例如只展示 `visibility=list`、支持当前 host、支持当前输入类型的模型。
• Spark 不要当视觉模型使用：这篇教程里的 `input_modalities` 必须只写 `["text"]`，不要标成 image 或多模态。

解决步骤

1. 第一步先打开 1A1API Key 分组或请求 `/v1/models`，确认当前 Key 是否仍能使用 `gpt-5.3-codex-spark`；查不到就停止，不要修改本地 App。
2. 第二步检查 `~/.codex/config.toml`：如果你走 1A1API Codex / Responses 入口，使用 `model_provider = "custom"`、`wire_api = "responses"`、`base_url = "https://1a1api.top"`。
3. 第三步检查 `spark-enabled.json`：确认里面有 `slug = gpt-5.3-codex-spark`、显示名 GPT-5.3-Codex-Spark、`visibility=list`、`supported_in_api=true`，输入类型只允许 text。
4. 第四步保留 `gpt-5.6-sol` 作为当前日常示例；若 Spark 仍在 Key 分组内，只把它放进独立实验 profile，不设成全局默认。
5. 第五步完全退出 Codex App 再重新打开；只关窗口不算，必须 Cmd+Q 或从菜单 Quit。
6. 第六步如果模型能从 CLI 调用但桌面菜单不显示，优先临时用 `--model` 或等待客户端目录更新，不建议小白修改 `app.asar`。
7. 第七步只有能自行审查、签名和回滚 Electron 应用的高级用户，才把后文 `app.asar` 内容当作历史研究线索。

可复制命令

# 1. 先测试模型是否真的可用。能稳定返回 SPARK_OK，再继续后面的配置
/Applications/Codex.app/Contents/Resources/codex exec \
  --skip-git-repo-check \
  --model gpt-5.3-codex-spark \
  "Reply exactly SPARK_OK"

# 2. 备份配置并创建模型目录
mkdir -p ~/.codex/model-catalogs
cp ~/.codex/config.toml ~/.codex/config.toml.bak-$(date +%Y%m%d-%H%M%S) 2>/dev/null || true

# 3A. 当前日常示例：模型仍要以你的 Key 分组为准
model_provider = "custom"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"

[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://1a1api.top"

# 完整当前配置：https://help.1a1api.top/codex

# 3B. 2026 年 6 月历史实验：仅当 Key 分组仍返回该模型时使用
# 把 YOUR_USERNAME 替换成当前 macOS 用户名；这里必须是绝对路径
model_provider = "custom"
model = "gpt-5.3-codex-spark"
model_catalog_json = "/Users/YOUR_USERNAME/.codex/model-catalogs/spark-enabled.json"
model_reasoning_effort = "high"

[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://1a1api.top"

# 3C. 更推荐的实验方式：新建 ~/.codex/spark.config.toml
# 把 YOUR_USERNAME 替换成当前 macOS 用户名；这里必须是绝对路径
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"
model_catalog_json = "/Users/YOUR_USERNAME/.codex/model-catalogs/spark-enabled.json"

# 使用时从 CLI 启动
# codex --profile spark
# 或临时指定：codex --model gpt-5.3-codex-spark

{
  "models": [
    {
      "slug": "gpt-5.3-codex-spark",
      "display_name": "GPT-5.3-Codex-Spark",
      "description": "Ultra-fast coding model.",
      "default_reasoning_level": "high",
      "supported_reasoning_levels": [
        { "effort": "low", "description": "Fast responses with lighter reasoning" },
        { "effort": "medium", "description": "Balances speed and reasoning depth" },
        { "effort": "high", "description": "Greater reasoning depth" },
        { "effort": "xhigh", "description": "Extra high reasoning depth" }
      ],
      "visibility": "list",
      "supported_in_api": true,
      "input_modalities": ["text"]
    }
  ]
}

# 4. 检查 Codex 看到的模型目录
/Applications/Codex.app/Contents/Resources/codex debug models | rg "gpt-5.3-codex-spark|GPT-5.3-Codex-Spark"

仍然不行怎么办

• Key 分组或 `/v1/models` 查不到 `gpt-5.3-codex-spark`：停止复现实验，改用当前可用模型，不要修改菜单。
• `config.toml` 写完后没效果：检查 `model_catalog_json` 是否是绝对路径，JSON 是否合法，Codex App 是否已经完全退出再打开。
• `codex debug models` 查不到 Spark：说明模型目录没有被读取，先修 `config.toml` 路径，不要急着拆 `app.asar`。
• 菜单里有 Spark 但调用失败：重点查 1A1API 分组、上游权限、base URL、Responses API 映射和模型名，不要继续改本地菜单。
• 复杂任务质量不稳：恢复当前日常模型，例如 `gpt-5.6-sol`；实际模型仍以 Key 分组为准。
• CLI 能用但菜单不显示：先临时用 `--model` 或等待客户端目录更新；小白到此停止，不修改 `app.asar`。
• 历史上改过 `app.asar` 且 App 打不开：使用修改前备份恢复；没有可靠备份时重新安装官方客户端。
• 看到图片、截图、视觉输入相关任务：不要选 Spark。Spark 在这篇教程里按文本模型处理，不支持图片输入。

小白安全顺序

1. 先看目录：如果 `spark-enabled.json` 已经有 Spark，就不需要重复新增模型对象。
2. 再测 CLI：模型本身不通，菜单显示也没有意义。
3. 再改 config：这是 Codex 支持的正常配置路径，风险最低。优先保留 `model_catalog_json`。
4. 再查 debug models：确认 Codex 是否真的读到了你的模型目录。
5. 菜单仍不显示时，小白到此停止：使用 CLI 临时指定或等待客户端更新，不拆 `app.asar`。

当前配置怎么判断

• 当前推荐结构是：`model_provider = "custom"`，provider 使用 `wire_api = "responses"`，`base_url = "https://1a1api.top"`。
• 模型目录可以放在 `~/.codex/model-catalogs/spark-enabled.json`，但 `model_catalog_json` 配置值必须写展开后的绝对路径，例如 `/Users/你的用户名/.codex/model-catalogs/spark-enabled.json`。
• 如果目录里已经有 `slug: gpt-5.3-codex-spark` 和 `display_name: GPT-5.3-Codex-Spark`，说明“加入模型目录”这一步已经完成。
• 日常示例使用 `gpt-5.6-sol`；如果 Key 分组仍开放 Spark，只把它留在独立实验 profile。
• 模型和分组会变化，复制配置前先查看 https://help.1a1api.top/codex 和当前 Key 分组。

当前配置与历史实验怎么选

• 日常使用：从当前 Key 分组选择模型；本文示例使用 `gpt-5.6-sol`，并以 Help 当前配置为准。
• 历史复现：只有 `/v1/models` 仍返回 `gpt-5.3-codex-spark` 时，才创建独立 Spark profile。
• 菜单没有 Spark：使用 CLI 临时指定或等待客户端更新，不要为了显示一项就修改 App 安装包。
• 不建议小白全局切 Spark，也不建议小白 patch `app.asar`。

spark-enabled.json 不要误覆盖

• 如果你的 `spark-enabled.json` 原来已经有很多模型，不要只保留教程里的一个对象。
• 正确做法是把 gpt-5.3-codex-spark 这一项加入现有 `models` 数组，或插到 `gpt-5.2` 前面。
• `slug` 是真正调用用的模型名，建议写 `gpt-5.3-codex-spark`。
• `display_name` 是菜单里给人看的名字，写 `GPT-5.3-Codex-Spark`。
• `visibility=list` 的意思是允许出现在列表里；如果写成隐藏状态，菜单可能不会显示。
• `default_reasoning_level` 建议写 `high`；支持项可包含 `low`、`medium`、`high`、`xhigh`。
• `input_modalities` 必须只写 `["text"]`，不要为了“看起来高级”写 image。

为什么 CLI 能用，菜单还是没有

• CLI 的 `--model` 更像是强制指定模型；菜单则要先拿到模型目录，再经过前端筛选。
• 前端可能按 host、API 支持情况、可见性、推理努力级别、输入类型等条件过滤。
• 所以排查时要分清三层：模型后端是否可用、Codex 配置是否读到、桌面菜单是否展示。
• 只要前两层没有确认，就不要急着改 `app.asar`。

为什么不再提供 app.asar 复制命令

• `app.asar` 是客户端内部文件，结构会随版本变化；旧命令可能改错文件或破坏签名。
• 客户端更新通常会覆盖 patch，菜单显示也不能替代 Key 分组和后端权限。
• 小白直接使用当前模型即可；高级用户如需研究，应针对当前客户端版本自行审查并准备完整回滚。
• 本页保留这段边界说明，是为了识别旧配置，不代表建议继续 patch。

1A1API 后端权限边界

• 本地菜单显示，只代表 Codex App 能看到这个模型名，不代表 1A1API 或上游一定允许调用。
• 如果菜单出现但调用失败，优先检查账号分组是否开放 Spark、模型 slug 是否映射、Responses API 是否兼容。
• 如果返回 401，多半是 Key 或认证问题；如果返回 404 或 model not found，多半是模型名或分组权限问题。
• 不要把 `gpt-5.3-codex` 和 `gpt-5.3-codex-spark` 混用；前者不是这篇教程要接入的 Spark。

最后一步：必须完全退出再打开

• 改完 `config.toml` 或 `spark-enabled.json` 后，不要只关窗口。
• 在 macOS 菜单栏里选择 Quit Codex，或用 Cmd+Q 完全退出。
• 重新打开后再检查模型下拉菜单。
• 如果还没有，再运行 `codex debug models` 确认目录是否已读到 Spark。

参考依据

• Codex 手册：`config.toml` 可以设置默认 `model`。
• Codex 手册：高级配置示例里包含 `model_catalog_json`，用于指定启动时读取的模型目录 JSON。
• 1A1API 当前 Codex 配置：https://help.1a1api.top/codex
• 1A1API 当前模型与可用范围：https://help.1a1api.top/models
• GPT-5.3-Codex-Spark 内容来自 2026 年 6 月实验快照；是否仍可用以当前 Key 分组和 `/v1/models` 为准。
• Codex 手册：`codex debug models` 可以打印 Codex 看到的原始模型目录。
• 本教程把 gpt-5.3-codex-spark 当作文本代码模型使用；不要把它配置成支持 image 的视觉模型。

相关问题

• Codex 官方 Plugins 与 Codex++ 有什么区别

  要复用工作流、连接服务或分发 Skills，先选官方 Plugins；要改 Codex 桌面 UI 才考虑 Codex++，并接受 patch、签名和更新失效风险。

• Windows 下 ChatGPT 桌面应用中的 Codex / CLI / Computer Use 与 Claude Code CLI 指南

  Computer Use 是 ChatGPT Windows 桌面应用中 Work / Codex 的图形界面能力；命令行任务仍用 Codex CLI，Linux 项目仍建议放 WSL2。

• Codex 登录失败 account/read failed 怎么办

  先用 `codex login status` 确认状态，再用 `codex logout` 安全清理当前凭据并重登；浏览器回调受阻时优先试设备码登录。

• Claude Code 和 Codex 有什么区别

  不要按旧模型名、跑分或固定价格选工具；拿同一个真实任务比较交互、改动范围、验证结果和成本。

• Claude Code 与 Codex 如何协同完成项目

  不要按产品名称固定分配长短任务；根据当前客户端、项目环境和实测结果选一个主执行者，另一个独立复核，中间用任务卡交接。

还卡着？

仅把删除凭证、客户数据和环境变量值后的必要截图、日志片段、需求说明或当前页面链接发到 zhemuy@gmail.com。

• Agent 定制服务 — 看定制流程
• 1A1API 帮助中心 — 打开帮助中心
• 排错协助 — 联系处理