常见问题

月卡介绍

月卡特点

月卡会提供额外赠送额度，同时具有有效期。

有效期与续期

月卡仍在有效期内时，再次购买相同月卡会延长有效时间，不会立即把当前周期重置。购买前请先查看当前月卡的剩余有效期。

如何使用月卡分组

购买月卡后，需要把 API Key 切换到对应的月卡分组。

创建新密钥时，在“分组”中选择已经购买的月卡分组，例如“标准月卡”：

已有密钥可以直接点击密钥列表中的分组，在下拉列表中切换：

如何查看模型价格？

打开 模型广场，可以查看各模型的实付价格、官方价格和当前分组的折扣倍率。文本模型按每 1M token 展示输入、输出和缓存价格，图片模型按生成张数计费。

为什么会使用其他模型？

Codex 的部分版本会为自动标题、记忆整理或安全分类等后台任务单独请求辅助模型。仅凭出现不同模型名称，不能判断主任务被替换；如果请求时间与任何操作都对不上，或者消耗持续异常，仍应检查 API Key 和客户端日志。

常见的后台任务包括：

• 自动生成会话标题
• 从单个对话中提取记忆
• 整理和合并全局记忆
• 对特定建议内容进行安全分类

下图可以看到，主任务使用 gpt-5.6-sol，同时出现了用于后台任务的 gpt-5.6-luna 调用：

具体型号、推理档位和任务分工会随 Codex 版本更新。请求时间与新建会话、长会话空闲或记忆整理能够对应时，通常属于可解释的后台调用；时间完全对不上或消耗持续异常时，应停用可能泄露的 Key 并进一步检查。

如何在 Codex 中配置 gpt-6-astra？

在 config.toml 中设置 model = "gpt-6-astra" 只会指定默认模型，不一定会让它出现在 /model 菜单中。Codex 的模型菜单来自独立的模型目录，还需要通过 model_catalog_json 加载包含 gpt-6-astra 的完整目录文件。

先将 Codex 更新到最新版并完全退出旧进程。只更新程序但继续使用升级前启动的会话，仍可能看到以下错误：

The 'gpt-6-astra' model requires a newer version of Codex.

登录 xhyapi 控制台并打开 API Key 页面，在对应密钥的“使用密钥”弹窗中选择 Codex CLI，点击“获取目录”，再下载 codex-models.json。这个目录会按当前 API Key 所属分组生成；下载前请确认该分组已经包含 gpt-6-astra。

复制给 AI 自动配置

把下面的提示词发送给能够操作本机文件的可信 AI 工具：

展开提示词

请帮我在 Codex CLI 中配置 xhyapi 的 gpt-6-astra，并确保它能在 /model 菜单中显示和正常调用。请直接检查和处理，不要只给操作建议。

1. 执行 codex --version，并确认实际生效的 CODEX_HOME 和 config.toml 路径，不要假设一定是 ~/.codex。
2. 不得读取、输出或修改 auth.json、API Key、Bearer Token 和历史会话。修改前备份 config.toml 与要使用的模型目录文件。
3. 检查现有的 model、model_provider、base_url、wire_api 和 requires_openai_auth。保留已经可用的 xhyapi 服务商配置及其他 MCP、插件、权限和项目配置。
4. 在 config.toml 顶层设置 model = "gpt-6-astra"。如果现有服务商配置名称不是 custom，继续使用原来的名称，不要擅自新建重复服务商。
5. 查找从 xhyapi“使用密钥”弹窗下载的 codex-models.json，确认其中有完整的 gpt-6-astra 条目，并且 visibility 为 list、supported_in_api 为 true。不要只手写一个包含模型名的简化对象。
6. 将 codex-models.json 保存到实际 CODEX_HOME；然后在 config.toml 顶层设置 model_catalog_json，使用该文件的绝对路径，并确保配置位于任何 [model_providers.*]、[features] 等配置表之前。
7. 如果没有下载目录，或者目录中没有 gpt-6-astra，不要伪造模型能力字段。请告诉我回到 xhyapi API Key 页面的“使用密钥”弹窗重新获取目录，并检查 API Key 所属分组是否包含 gpt-6-astra。只有本机 models_cache.json 已经包含完整 Astra 条目时，才可以复制其完整 models 数组作为备用目录；不要修改原始 models_cache.json。
8. 启动新的 Codex 进程，执行 codex debug models 并检查 /model，确认可见模型中包含 gpt-6-astra。不要只用 TOML 或 JSON 语法检查代替真实模型列表验证。
9. 条件允许时，可以使用现有认证发送一个最低推理档位、不调用工具、只回复 OK 的最小请求，但不得读取或回显认证内容。确认实际使用的是 gpt-6-astra 和 xhyapi 自定义服务商。
10. 如果提示需要更新 Codex，检查当前进程是否仍是升级前启动的旧版本；如果返回 503，根据错误正文、请求时间和 xhyapi 使用记录判断，再检查上游账号权限、账号模型刷新结果、API Key 所属分组和分组中的模型配置。

完成后告诉我：Codex 版本、实际 CODEX_HOME、修改和生成的文件路径、最终 model 与 model_provider、/model 是否显示 gpt-6-astra、最小请求是否成功。不要在回复中展示任何密钥。

配置完成后需要完全退出并重新启动 Codex。若 /model 已经能看到 gpt-6-astra，但调用返回 503，说明本地模型目录已经生效；请根据错误正文和 xhyapi 使用记录继续判断上游账号权限、分组路由或临时服务故障，不必反复修改本地目录。

Codex 配置后提示 401 怎么办？

先看报错里的 url 字段，它是 Codex 实际请求的地址。两类原因的处理方式不同：

请求发到 api.openai.com

如果 url 是 https://api.openai.com/v1/responses，并伴随 Incorrect API key provided 或 auth error code: invalid_api_key，说明请求实际发给了 OpenAI 官方地址，而不是 xhyapi。这通常表示自定义服务商没有生效，请依次检查：

1. 确认 config.toml 顶层设置了 model_provider，并且存在同名的服务商配置段。只把 API Key 写进 auth.json、没有配置服务商时，Codex 会使用默认的 openai 服务商，请求就会发往官方地址。

   model_provider = "xhyapi"
   
   [model_providers.xhyapi]
   name = "xhyapi"
   base_url = "https://xhyapi.com"
   wire_api = "responses"

   服务商名称可以自定义，但 model_provider 的值必须与 [model_providers.<名称>] 完全一致。请以控制台“使用密钥”弹窗生成的配置为准。

2. 确认修改的是 Codex 实际读取的文件。新版 Codex 可以执行 codex doctor，在 Configuration 中查看当前生效的模型与服务商（格式为 模型名 · 服务商）以及 config.toml 路径。Windows 下使用 WSL 时，WSL 内的 ~/.codex 与 %USERPROFILE%\.codex 是两份不同的配置。

3. 如果使用 CC Switch 等工具切换过服务商，工具可能会重写 config.toml，把它切回官方 OpenAI。需要重新切换到 xhyapi，或手动改回正确配置。

4. 最稳妥的方式是回到控制台的 API Key 页面，在“使用密钥”弹窗中重新复制整份 Codex 配置（不要只替换 API Key），保存后完全退出并重新启动 Codex。

请求已发到 xhyapi，提示 API_KEY_REQUIRED

如果 url 是 xhyapi 的地址，并显示 API_KEY_REQUIRED，说明请求已经到达中转站，但 Codex 没有携带鉴权信息。Codex 0.149.0 及之后版本不再允许自定义 Provider 在 requires_openai_auth = false 时自动继承 auth.json 中的鉴权信息。

手动修改配置文件即可恢复：

• macOS：~/.codex/config.toml
• Windows：%USERPROFILE%\.codex\config.toml

找到这一行：

requires_openai_auth = false

改为：

requires_openai_auth = true

保存后完全退出并重新启动 Codex，即可正常使用。如果配置中同时使用了 env_key，请先确认对应的环境变量已经生效。

Codex 提示 Work browser 需要登录怎么办？

Codex 桌面版无法开始或继续会话，并显示以下提示时，先检查客户端是否保留了 ChatGPT 账号登录状态：

Failed to resume chat
Work browser access requires an authenticated account

据 CC Switch 维护者的说明，Codex 桌面版从 26.1013 起增加了相关账号认证检查：客户端没有识别到 ChatGPT 登录状态时，可能无法继续会话。这条提示本身不表示 xhyapi 的 API Key 失效；使用 CC Switch 切换服务商时，也需要确认官方登录状态是否被保留。

完全退出后再操作

下文提到的“关闭”或“重启 Codex”均指保存工作后彻底退出后台进程，不是只关闭窗口。可在客户端的“文件 / File”菜单中选择“退出 / Exit”；如果系统托盘中仍有应用图标，也可以右键选择“退出 / Exit”。菜单名称以当前客户端为准。

临时排查方式

如果暂时不便登录 ChatGPT 账号，可以按实际情况尝试以下方式。这些方式不保证有效；如果都无法恢复，仍需按下一节检查官方账号登录状态。

1. 暂时使用旧版桌面客户端。 如果已经具备回退条件，并能接受旧版功能，可以暂时停留在 26.1007。这是 CC Switch 维护者针对该认证检查给出的临时建议。
2. 重新导入密钥并切换到 Codex 模式。 完全退出 Codex 客户端后，在xhyapi新建密钥，导入 CC Switch 并启用。重新打开客户端，在左上方将 ChatGPT Work 切换为 Codex，再新建会话测试。此方式仅适用于 Codex 模式， ChatGPT Work 模式可能依旧无法正常使用，两种模式核心功能基本一致。
3. 排查网络代理影响。 完全退出 Codex 后，在关闭网络代理，再打开客户端测试。如果网络裸连可以满足使用xhyapi服务的同时连接不到Openai官方，可能就不会要求登录账户。

保留官方登录后启用 xhyapi

参考 CC Switch 维护者的说明，先保留官方账号登录，再切换回 xhyapi：

1. 在 CC Switch 的“设置 → 应用配置 → Codex”中，开启“非接管切换时保留官方登录”。

   

2. 将 CC Switch 中 Codex 的供应商切换为 OpenAI Official。

3. 完全退出并重新打开 Codex，登录自己的 ChatGPT 账号。在这里可以选择手机号验证，按页面提示完成，如果没有可用手机号可以通过接码网站进行验证。也可以选择客户端提供的官方 API Key 认证入口：打开 OpenAI 官方 API 平台，按平台导航进入 API Keys 页面创建自己的官方 API Key，再在客户端填写。此认证流程可能无需手机号验证，是否需要验证以实际页面提示为准。。

4. 确认官方账号已成功登录后，再次完全退出 Codex，在 CC Switch 中选择并启用 xhyapi 供应商。使用直连模式时，保持“非接管切换时保留官方登录”开启；如果使用路由模式，则在路由页面选择 xhyapi；选择聚合模式则只能选择管号为默认供应商，需要打开Codex后手动选择所需模型。

5. 重新打开 Codex 测试，并在 xhyapi 的 使用记录 中核对模型请求。

CC Switch 建议使用 v4.0.16 或之后版本。该版本修复了退出和重新连接路由时，官方登录状态未正确保留或恢复的问题。旧版本可能导致重启后反复要求登录；升级后仍报错时，继续核对当前账号登录状态、客户端模式和实际启用的供应商。

如何同步 API Key 与账号会话？

API Key 方式和官方账号方式默认不会自动显示同一份会话历史。使用 CC Switch 时，可以进入设置中的“Codex 应用增强”，开启“统一 Codex 会话历史”。

非 Codex 中使用需要注意事项

需要注意上下文管理。Codex 会自动维护上下文，其他 Agent 工具可能不会，因此在持续使用过程中可能因上下文超限而报错。

使用协议与政策在哪里？

帮助中心已提供以下协议与政策页面：

• 服务条款
• 使用政策
• 服务特定条款

建议在注册、充值、购买、创建 API Key 或持续调用服务前阅读相关内容。