基于 ChatGPT 订阅的 OpenAI Codex

在 openai 槽位上运行智能体，通过 ChatGPT 订阅付费，而非按量计费的 OPENAI_API_KEY 计费方式。该智能体是一个驱动 ZeroClaw 工具的 GPT-5.x Codex 模型，使用你的 Codex 登录凭据进行身份验证，而非 API 密钥。计费遵循你的 ChatGPT 套餐：首先消耗订阅所含的用量，超出所含额度的 Codex 用量则按 OpenAI 各模型的按 token 费率从你账户的弹性额度中扣除。一旦超出所含额度，便不再是每次调用统一 $0 的方式。

本页面介绍 slot 配置、served model 字符串、成本与路由的影响，以及 OAuth 接线。有关通用 provider 字段，请参阅 Configuration；有关单行目录条目，请参阅 Provider Catalog。

配置

Codex 订阅认证位于 openai 插槽。将 wire_api = "responses" 设置为通过 POST /v1/responses 路由（Codex 后端，而不是聊天补全 API），并将 requires_openai_auth = true 设置为从 ZeroClaw 存储的 openai-codex 认证配置文件中提取凭据，而不是从 api_key 字段：

# 复用现有的 Codex CLI 登录：
zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json

# 或启动 ZeroClaw 自己的 OpenAI Codex 登录流程：
zeroclaw auth login --model-provider openai-codex

Quickstart 可以为你写入 provider 条目：

zeroclaw quickstart --model-provider openai-codex --model gpt-5.4

手动配置使用相同的规范 OpenAI 插槽：

[providers.models.openai.coding]
model                = "gpt-5.4"
wire_api             = "responses"
requires_openai_auth = true

[providers.models.openai.review]
model                = "codex-auto-review"
wire_api             = "responses"
requires_openai_auth = true

没有 api_key 字段；requires_openai_auth = true 是用于读取已存储的 Codex 登录信息（而非条目中的密钥）的开关。请参阅 配置 → OAuth 和订阅认证。

别名部分（coding、review）由操作者自行选择，挑选适合的即可。在 agent 中通过 model_provider = "openai.coding" 来引用它。

模型

responses 线路 API 直接访问 Codex 后端，因此 model 值必须是精确的服务端 ID：Codex CLI 的客户端别名（gpt-5、gpt-5.3、instant、gpt-5.5-instant）在此不会被解析，并会以 400 错误失败。

将提供的目录视为易变内容。请通过查询获取，而不要依赖任何硬编码列表，包括本列表在内：

# 字段名称与实时的 ~/.codex/auth.json 匹配（请对照文件本身进行验证；
# the layout has shifted across Codex versions).
AT=$(jq -r .tokens.access_token ~/.codex/auth.json)
# account_id 在 auth.json 中为可选项；当未设置时，ZeroClaw 会回退到使用 OAuth JWT
# it is absent. `// empty` keeps jq from emitting the literal string "null", and
# 仅当字段实际存在时才发送该标头。导入后，您
# can also read the resolved id from `zeroclaw auth status`.
ACC=$(jq -r '.tokens.account_id // empty' ~/.codex/auth.json)
curl -s https://chatgpt.com/backend-api/codex/models?client_version=1.0.0 \
  -H "Authorization: Bearer ${AT}" \
  ${ACC:+-H "chatgpt-account-id: ${ACC}"} \
  -H "originator: pi" | jq -r '.models[].slug'

client_version 是必填项且受版本限制：过旧或过低的值会返回空的 {"models": []} 且不报错。如果返回的列表为空，请使用当前的客户端版本（例如 1.0.0）。

已服务的目录（2026-06-02；固定前请对照端点进行核实）：

GPT-5.5 Instant 和 GPT-5.3 是 ChatGPT-app 模型，属于不同的命名空间，不在 Codex 后端提供服务，因此无法从此插槽使用。

为避免每次模型升级都要修改配置，应动态地将角色解析为当前提供的 ID（枚举 codex/models，为每个角色选取最新的匹配项），而不是固定某个版本。

成本与路由

OpenAI 如何对此路径计费（请遵循 OpenAI 当前的 Codex / ChatGPT 套餐计费文档，该文档优先于此处固定的任何数据）：

1. 优先使用套餐包含的额度。 每个 ChatGPT 套餐都包含 Codex 使用额度，并按滚动时间窗口刷新。在额度范围内使用时，Codex 请求不会产生额外费用。
2. 包含额度用尽后可使用灵活积分。 当包含的用量耗尽后，在套餐支持的情况下，Codex 用量将从你账户的积分余额中扣除。输入、缓存输入和输出均按每 100 万 token 的积分计价，因此一项任务消耗多少取决于其 token 构成和所用的模型。
3. 超额选项。 当包含的额度和所有积分用尽后，OpenAI 提供的方案是添加积分、升级套餐或等待时间窗口重置。

因此，下面的套餐等级是用量额度倍数，而非保证每次调用零成本。

ZeroClaw 成本跟踪

ZeroClaw 将此槽位记录为每次调用 $0。这是本地计费的局限，而非 OpenAI 实际的计费情况： ZeroClaw 无法查看你的 ChatGPT 套餐所含用量计量或额度余额，因此无法将单次调用的 token 费用归属到订阅请求。请将 $0 理解为“ZeroClaw 未计量”，并在你的 OpenAI 账户中查看真实的额度/信用状态。在计费中请将订阅类和计量（api-key）类分开统计；参见 成本追踪。

因此，路由的核心在于审慎地使用包含的额度，并在超出额度后保留一个回退方案，这既是为了避免按各模型 token 费率消耗信用额度，也是为了在遇到硬性中断时仍能继续运行。一旦超出包含的使用量，就不再是“按 token 免费“了。

路由是基于每个 agent 的（参见 Routing）：为每个角色定义一个 agent 别名，每个别名指向一个 openai Codex 条目，并让频道指向应处理其流量的 agent。

为订阅无法提供服务的情况保留一个计量计费的回退方案：额度耗尽（429）、令牌刷新处于退避状态（见下文）或模型字符串不可用。该回退是按令牌级别的，因此它应当是例外情况。哪些提供商属于该回退集合取决于具体环境；请在你自己的路由配置中进行设置，而非在此处。

订阅层级和限制

与此名额相关的 ChatGPT 套餐（截至 2026-06）。“allowance”一列表示包含用量乘数，而非免费调用上限：超出包含的名额后，所有套餐都将按 OpenAI 公布的 Codex 费率回退至按 token 计费的弹性额度。更高的套餐会提高包含用量乘数；但并不会让用量免费。

两种 Pro 套餐提供相同的模型套件和功能；它们的区别仅在于所含额度的多少。

$100 套餐已于 2026-06-01 下调。 在 2026-05-31 之前，它以 10× Plus 的额度进行限时促销，之后恢复为标准的 5×。该日期之前记录的各模型消息数量包含临时的 2× 提升，现已不再准确。

OpenAI 未公布各档位 Codex 的硬性消息数量限制，也未将“无限制“绑定到特定的模型名称；其公开定价页面仅显示一张“Pro“卡片（“起价 $100”，标题为“用量提升 5 倍或 20 倍“），并附有概括性说明“无限制，但受滥用防护机制约束“。请将来自旧文档或其他来源的任何特定的单模型数量限制视为非权威信息。Pro 推理旗舰模型为 GPT-5.5 Pro。

定价页面中的 128K / 400K 上下文窗口和 ~680 pages 数字描述的是 ChatGPT 应用的 GPT Instant / GPT Reasoning 模型，与此插槽使用的 Codex responses 后端属于不同的命名空间。请勿将其视为 Codex 后端的限制。

导入令牌

非交互式导入现有的 Codex-CLI 令牌，而不是启动浏览器流程：

zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json
zeroclaw auth status   # openai-codex:default kind=OAuth account=... expires=...

（交互式替代方式：使用不带 --import 的 zeroclaw auth login，或使用 --device-code。）

从默认配置目录（~/.zeroclaw）运行守护进程。身份验证配置文件原生存储在该目录中，zeroclaw auth 命令也默认使用此目录；若将守护进程指向自定义目录，则配置文件也必须放置在该目录中，而由于它是按配置目录加密的（见下文），痛苦就此开始。

两个棘手之处

身份验证配置文件不可移植。 auth-profiles.json 使用配置目录的 .secret_key 进行加密（enc2:）。你无法将一台主机的配置文件复制到另一台主机，因为目标主机无法解密；运行时会记录 enc2: decryption failed (wrong `.secret_key` or tampered ciphertext)（or tampered ciphertext 这一从句共用同一错误路径，因此仅凭该消息无法区分是外来配置文件还是损坏的数据块）。每台主机都从原始的 ~/.codex/auth.json 导入自己的配置文件。如果已存在外来的 auth-profiles.json，请先将其移走，否则导入会在尝试加载它时失败：

mv ~/.zeroclaw/auth-profiles.json ~/.zeroclaw/auth-profiles.json.foreign 2>/dev/null
zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json

刷新令牌会轮换，且只能有一个所有者。 每次成功刷新都会使上一个刷新令牌失效。如果两台主机各自独立地刷新同一个账户，它们就会使彼此失效：

error=OpenAI token refresh is in backoff for 9s due to previous failures

在多台主机上均可使用的模式，仅严格限于你在同一 OpenAI 账户下拥有的机器：

⚠️ 凭据边界。 ~/.codex/auth.json 保存着你 OpenAI 账户的有效 bearer 和 refresh 凭据。仅通过私密、加密的通道将其分发到你自己的主机：密钥管理器、加密传输或仅限 SSH 的拉取。切勿将其提交到代码仓库、公开发布、粘贴到聊天或工单中，或与其他用户或团队共享。OpenAI 的条款禁止共享账户凭据或将账户提供给他人使用，而原始的 auth.json 拉取点本身就是高价值的机密。这是面向操作者的凭据处理指南；运行时代码不会改变它。

1. 一台主机负责管理刷新（例如运行 Codex CLI 后台刷新的那台），并保持 ~/.codex/auth.json 处于最新状态。
2. 该主机将原始的 ~/.codex/auth.json 发布到一个私有拉取端点（密钥管理器或加密/仅 SSH 通道），仅可由你自己的主机访问。
3. 每隔一个主机都会拉取原始的 auth.json（可移植，它只是令牌），并在本地重新导入，从而使用该主机自己的 .secret_key 对其重新加密。
4. 其他主机不会独立刷新。

你分发的工件是原始的 ~/.codex/auth.json，绝不是加密的 auth-profiles.json，并且只能通过私有的加密通道分发到你自己的机器上。

验证中

zeroclaw auth status   # 当前且未过期
# then drive the agent once against the local gateway

运行正常时会返回模型输出且 exit_code=0。两种失败特征：

• ... token refresh in backoff：令牌已过期或已轮换；请重新拉取原始 auth.json 并重新导入。
• model=<x> ... 400：不支持的模型字符串；请使用准确的已部署 ID。

新主机检查清单

1. ~/.codex/auth.json 已存在且为最新（从刷新所有者拉取）。
2. zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json（请先移开任何外部的 auth-profiles.json）。
3. zeroclaw auth status 显示 openai-codex:default ... kind=OAuth ... expires=<future>。
4. 一个 openai 条目，包含 wire_api = "responses"、requires_openai_auth = true 以及一个确切的服务模型 ID。
5. 守护进程位于 --config-dir ~/.zeroclaw（默认值）。
6. 驱动代理执行一次 → exit_code=0 并返回真实输出。
7. 路由器将角色映射到当前提供服务的 ID（不要固定某个版本，否则你将不得不一直追踪它）。