Codex CLI

TIP

用 skill 自动配置

安装 ModelFold skill 后，可以直接对 Agent 说“把 Codex 配置成使用 ModelFold”，由它按本页步骤完成配置；也可以照本页手动配置。

npx skills add https://ai.modelfold.online/

Codex 说的是 OpenAI Responses 协议,ModelFold 的 Codex 模型正是按这个协议提供的。Codex 通过 config.toml 里定义的一个自定义 provider 连过来。

重要规则

1. 通过 GET https://ai.modelfold.online/openai/v1/models 发现模型,不要凭记忆或训练数据写模型名。 这个接口给出的才是 Codex 真正能跑的那份列表。
2. 用 Authorization: Bearer 认证。 ModelFold 的所有接口都靠这一个请求头携带 API key,列模型接口也一样。名字就叫 apikey 的请求头会被 401 拒掉。
3. 必须显式设 model。 Codex 内置的默认模型名不是 ModelFold 提供的名字,所以 provider 哪怕其余都对,在 model 写成列表里的 slug 之前,每一次请求都会失败。
4. provider 要写进用户级配置。 项目级 .codex/config.toml 里的 model_provider 和 model_providers 会被 Codex 忽略。

列出可用模型

curl -s -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  https://ai.modelfold.online/openai/v1/models |
  jq -r '.models[] | [.slug, .display_name, (.context_window | tostring),
                      .default_reasoning_level,
                      ([.supported_reasoning_levels[].effort] | join(","))] | @tsv'

Windows(PowerShell)下用 curl.exe 发同样的请求:

curl.exe -s -H "Authorization: Bearer $env:MODELFOLD_API_KEY" `
  https://ai.modelfold.online/openai/v1/models | jq -r '.models[].slug'

同一份模型在响应里出现两次。.data[] 是 OpenAI 兼容的形状,其中只有 id 能标识模型,其余(created、object、owned_by)是样板字段。.models[] 是信息更全的那份,要读的是它:slug 就是填进 model 的值,context_window、default_reasoning_level、supported_reasoning_levels 说明这个模型接受什么。

把 slug 列给用户去选。每次都重新跑这个列表,不要复用之前的答案——模型集合会变。

写配置

Codex 通过 config.toml 里的一张表配置自定义 provider,模型写在顶层:

model = "gpt-5.5"
model_provider = "ModelFold"

[model_providers.ModelFold]
name = "ModelFold"
base_url = "https://ai.modelfold.online/openai/v1"
env_key = "MODELFOLD_API_KEY"
wire_api = "responses"

base_url 是发请求的根路径,Codex 会自己往后面拼 /responses,所以这里配的是 https://ai.modelfold.online/openai/v1,不是完整的请求 URL https://ai.modelfold.online/openai/v1/responses。

env_key 指的是 Codex 从哪个环境变量里读凭证并作为 bearer token 发出去,它本身不存放密钥。

wire_api = "responses" 对应的正是 ModelFold 提供的协议。它同时也是 Codex 的默认值,可以省略——写出来是为了让这张表自己讲清楚。

provider 的 id——这里的 ModelFold——由你自己取,但 openai、ollama、lmstudio 是保留的,覆盖不了。

macOS 与 Linux

文件是 ~/.codex/config.toml。在启动 codex 的同一个 shell 里导出凭证,或者写进 shell profile:

export MODELFOLD_API_KEY=…

设 CODEX_HOME 可以把配置放到 ~/.codex 以外的地方。

Windows(PowerShell)

文件是 %USERPROFILE%\.codex\config.toml,内容完全一致。

$env:MODELFOLD_API_KEY = "…"
setx MODELFOLD_API_KEY "…"

推理强度

model_reasoning_effort 决定模型投入多少推理:

model_reasoning_effort = "high"

Codex 接受 low、medium、high、xhigh,以及从 Codex 0.154 起支持的 max——max 会原样透传给后端(已在 gpt-6-astra 上实测通过)。从该模型 supported_reasoning_levels 里挑一个,或者干脆不写这个键,走模型的 default_reasoning_level。Codex 0.153 及更早版本会把 max 判为未知值拒掉——要用先升级 Codex。

确认配置生效

codex doctor 会报告 Codex 加载到了什么、以及能不能连上 provider。auth 那一节应该显示 provider 的环境变量已存在。reachability 那一节探测的是 base_url 拼上 /models,配对了就会报可达。

provider 是否可用由一次真实请求确认:在设好 MODELFOLD_API_KEY 的 shell 里启动 codex,发一条消息。

Codex 启动时可能打印 Model metadata for '…' not found. Defaulting to fallback metadata.。那是 Codex 在说这个 slug 不在它自带的模型表里——ModelFold 的每个 slug 都不在;会话照常运行。

常见坑

1. 名字就叫 apikey 的请求头。 ModelFold 会返回 401。key 要放进 Authorization: Bearer。
2. 把完整请求 URL 写进 base_url。 Codex 自己会拼 /responses,所以 base_url 以 /responses 结尾会拼成 /responses/responses。
3. 没换掉 Codex 内置的默认模型名。 即使凭证和 base URL 都对,model 也必须是列表里的某个 slug。
4. provider 配置写进了项目级文件。 Codex 会忽略用户级配置以外的 model_provider 和 model_providers,写在项目 .codex/config.toml 里的 provider 是被静默跳过的。
5. 用了保留的 provider id。 openai、ollama、lmstudio 覆盖不了,表名要换一个。
6. 把密钥直接写进 env_key。 它填的是环境变量名,密钥本身在那个变量里,不在配置文件里。
7. setx 不影响当前窗口。 它对此后新开的窗口生效。想立刻用上,同时设 $env:。
8. PowerShell 的 curl。 它是 Invoke-WebRequest 的别名,不接受这些参数。用 curl.exe。

要用不是本协议的 listing 里的模型,见「安装 modelfold-chat-agents」页的「协议不一致时」一节。