​
使用 AIMax 配置 Codex CLI

本页说明如何让 Codex CLI 使用 AIMax 的 OpenAI Responses 接口。已完成只读最小文本验证；具体可用模型以当前 API Key 的模型列表和实际协议探测结果为准。
本页只验证文本推理任务。Codex 的文件修改、MCP、联网搜索、图片输入和其他工具能力需要按模型及场景单独验证，不因本页验证自动视为可用。

​
准备工作

  1. 安装 Codex CLI。排查问题时，可以额外记录本地 CLI 版本：
  1. 获取 AIMax API Key。
  2. 调用 GET /v1/models，选择当前 API Key 可见且支持 Responses 协议的模型名称，记为 MODEL_FROM_MODELS。

​
配置文件

Codex 使用 CODEX_HOME 指定配置目录；未设置时默认使用用户目录下的 .codex。 在 CODEX_HOME/config.toml 写入：
在同一目录的 auth.json 写入 API Key：
wire_api 必须为 responses，对应 AIMax 的 POST /v1/responses。不要将 Chat Completions 路径或 Anthropic/Gemini 请求头写入这份 Codex 提供商配置。

​
最小验证

建议先在临时目录中验证，避免覆盖现有 Codex 配置：
成功后，终端会显示当前模型和 provider，并返回 OK。--ephemeral 用于不持久化本次会话；验证完临时目录可自行删除。

​
常见问题

​
提示认证失败

  1. 确认 auth.json 位于 CODEX_HOME 下，字段名是 OPENAI_API_KEY。
  2. 检查 preferred_auth_method = "apikey" 与 requires_openai_auth = true 是否同时存在。
  3. 确认 Key 没有前后空格，且当前 Key 可以从 GET /v1/models 获取模型列表。

​
提示接口或模型不可用

  1. 确认 base_url 是 https://your-domain/v1，不要重复追加 /v1。
  2. 确认 wire_api = "responses"，不要写为 chat_completions。
  3. 先将模型改为当前 API Key 可见的模型名称，再重新执行只读最小验证。

​
Agent 工具回合失败

本页没有验证工具调用。先使用只读文本任务确认协议和认证正确；若问题只在文件修改、MCP 或联网场景出现，请保留 Codex CLI 版本、模型名称、请求时间和脱敏错误信息后再排查。

​
协议参考