𝐘𝐀𝐈

在 Codex 中启用 GPT-5.5：通过 XAI Router 临时切换与默认配置

Posted April 24, 2026 by XAI 技术团队 ‐ 7 min read

Codex CLI 的模型选择非常灵活：你可以在某一次会话里临时指定模型，也可以把常用模型写进 ~/.codex/config.toml 作为默认值。

如果你希望通过 XAI Router 使用 gpt-5.5，推荐采用下面这套配置方式：先让 Codex 请求发往 https://api.xairouter.com，再把默认模型切到 gpt-5.5。对于尚未内置 gpt-5.5 元数据的 Codex 版本，还可以补充一个本地 model-catalog.json，让它不再走保守 fallback。

适用场景

这篇文章适合以下情况：

  1. 你已经安装了 Codex CLI。
  2. 你已经有可用的 XAI_API_KEY。
  3. 你希望在 Codex 中测试或默认使用 gpt-5.5。
  4. 你希望 Codex 本地把 gpt-5.5 当作已知模型，而不是未知模型 fallback。

先设置环境变量：

export XAI_API_KEY="你的 XAI API Key"

如果希望长期生效，可以把它写入 ~/.bashrc、~/.zshrc 或你的系统环境变量管理工具。

方式一：只在本次会话临时使用 GPT-5.5

如果只是想临时测试，不必修改配置文件，启动时直接指定模型即可：

codex -m gpt-5.5

非交互模式也可以这样验证：

codex exec -m gpt-5.5 "用一句话介绍你正在使用的模型配置"

这种方式最适合快速试用。它不会改变 ~/.codex/config.toml，下次启动仍会回到原来的默认模型。

方式二：把 GPT-5.5 设为 Codex 默认模型

编辑 ~/.codex/config.toml：

model_provider = "xai"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "none"
model_context_window = 1050000
model_auto_compact_token_limit = 945000
tool_output_token_limit = 6000
approval_policy = "never"
sandbox_mode = "danger-full-access"
suppress_unstable_features_warning = true
model_catalog_json = "model-catalog.json"

[model_providers.xai]
name = "OpenAI"
base_url = "https://api.xairouter.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

[features]
multi_agent = true
remote_connections = true

[agents]
max_threads = 4
max_depth = 1
job_max_runtime_seconds = 1800

这份配置做了三件事：

  1. model_provider = "xai"：让 Codex 使用下面定义的 XAI Router Provider。
  2. model = "gpt-5.5"：把默认模型切换为 gpt-5.5。
  3. base_url = "https://api.xairouter.com"：把 OpenAI Responses 请求发送到 XAI Router。

model_catalog_json = "model-catalog.json" 是可选但推荐的增强项。它用于给 Codex 本地补充模型元数据，让尚未内置 gpt-5.5 的版本也能把它识别为已知模型。

让 Codex 本地识别 GPT-5.5

部分 Codex CLI 版本的内置模型表里可能还没有 gpt-5.5。这时即使请求模型名是 gpt-5.5，Codex 本地也可能使用 fallback metadata，例如显示较小的有效上下文窗口。

推荐直接下载准备好的模型目录文件：

mkdir -p ~/.codex
curl -L "https://filelist.cn/disk/0/model-catalog.json" -o ~/.codex/model-catalog.json

如果本地没有 curl，也可以在浏览器打开下面的地址，把文件保存为 ~/.codex/model-catalog.json：

https://filelist.cn/disk/0/model-catalog.json

如果你更希望自己生成，也可以使用下面的脚本：它会读取 Codex 内置模型目录，复制 gpt-5.4 的能力元数据，再新增一条 gpt-5.5。

mkdir -p ~/.codex

python3 - <<'PY'
import json
import subprocess
from pathlib import Path

codex_home = Path.home() / ".codex"
catalog_path = codex_home / "model-catalog.json"

raw = subprocess.check_output(["codex", "debug", "models", "--bundled"], text=True)
catalog = json.loads(raw)

models = [model for model in catalog["models"] if model.get("slug") != "gpt-5.5"]
base = next(model for model in models if model.get("slug") == "gpt-5.4")

gpt55 = dict(base)
gpt55["slug"] = "gpt-5.5"
gpt55["display_name"] = "gpt-5.5"
gpt55["description"] = "Custom local metadata for gpt-5.5 via XAI Router."
gpt55["context_window"] = 1050000
gpt55["max_context_window"] = 1050000

catalog["models"] = [gpt55] + models
catalog_path.write_text(json.dumps(catalog, indent=2, ensure_ascii=False) + "\n")
print(catalog_path)
PY

然后确认 ~/.codex/config.toml 中有这一行：

model_catalog_json = "model-catalog.json"

如果你的 Codex 版本要求绝对路径，也可以写成：

model_catalog_json = "/home/your-user/.codex/model-catalog.json"

修改后重启 Codex。model_catalog_json 会在启动时加载，已经运行中的会话不会自动热更新。

XAI 系统中的模型映射也要更新

本地 Codex 配置完成后，还需要确认 XAI 系统里的模型映射已经支持 gpt-5.5。如果你的账户仍使用较早的映射规则，即使 Codex 本地请求的是 gpt-5.5，也可能被通配规则映射回 gpt-5.4。

较早的默认映射通常类似：

*=gpt-5.4,
gpt-5.4-nano=gpt-5.4-mini,
gpt-5.3-codex-spark*=gpt-5.3-codex-spark,
gpt-5.3-codex*=gpt-5.3-codex,
gpt-*-mini*=gpt-5.4-mini,
claude-haiku*=gpt-5.4-mini

支持 gpt-5.5 的新映射会增加一条显式规则：

*=gpt-5.4,
gpt-5.5*=gpt-5.5,
gpt-5.4-nano=gpt-5.4-mini,
gpt-5.3-codex-spark*=gpt-5.3-codex-spark,
gpt-5.3-codex*=gpt-5.3-codex,
gpt-*-mini*=gpt-5.4-mini,
claude-haiku*=gpt-5.4-mini

因此，如果你希望实际路由到 gpt-5.5，请在 XAI 系统中完成续费或套餐更新，以获得包含 gpt-5.5*=gpt-5.5 的最新模型映射配置。

这里没有对历史用户自动改写映射，是为了保证已有生产配置稳定。模型映射属于账户级路由策略，平台不能随意修改老用户的既有规则，否则可能改变原有调用成本、模型行为或业务兼容性。

如何确认已经生效

最简单的验证方式是新开一个 Codex 会话：

codex -m gpt-5.5

或者用非交互命令快速检查：

codex exec -m gpt-5.5 "只输出一行：GPT-5.5 OK"

如果你同时配置了 model-catalog.json，新的会话应当不再把 gpt-5.5 当作未知模型 fallback。按照上面的示例窗口配置，Codex 本地展示的有效上下文窗口会接近：

1050000 * 95% = 997500

需要注意的是，这个数值代表 Codex 本地的模型元数据与截断策略，不等于服务端一定承诺可处理这么长的上下文。实际可用上限仍取决于后端模型与路由策略。

推荐配置小结

日常使用时，建议采用下面的组合：

  1. 用 XAI_API_KEY 管理访问凭证。
  2. 用 model_provider = "xai" 统一接入 XAI Router。
  3. 用 model = "gpt-5.5" 设为默认模型。
  4. 用 model_catalog_json 补齐本地模型元数据。
  5. 临时测试时优先使用 codex -m gpt-5.5，确认稳定后再写入默认配置。

这样配置后，Codex 会以 OpenAI Responses 协议请求 XAI Router，并在本地按 gpt-5.5 的自定义模型元数据运行。对于需要频繁切换模型的开发者，也可以保留默认模型不变，只在特定任务中使用 -m gpt-5.5 临时切换。