接入 OpenAI Codex CLI

OpenAI Codex CLI 是 OpenAI 官方的终端 coding agent。它读取 ~/.codex/config.toml，支持自定义 model_providers，只需几行 TOML 和一个环境变量即可指向 xmAI。

前置要求

• 已在 XmAI 控制台 注册账号并充值 / 拥有免费额度
• 已在 API Keys 页面创建一把 API Key（形如 sk-xxx...）
• 已安装 OpenAI Codex CLI：

  npm install -g @openai/codex
  # 或：brew install codex

协议选择说明

Codex CLI 默认使用 OpenAI Responses API（wire_api = "responses"）。xmAI 当前仅暴露 Chat Completions（/v1/chat/completions）与 Anthropic Messages API，尚未上线 Responses API。因此在 provider 块中 必须 设置 wire_api = "chat"。

若你本地的 Codex CLI 版本已硬性要求 Responses API（不再支持 wire_api = "chat"），你需要等待 xmAI 的 Responses API 里程碑（后续独立 Story），或将 Codex CLI 降级到老版本。Responses API 上线后本页会同步更新。

配置步骤

步骤 1 — 在 ~/.codex/config.toml 中添加 provider

若文件不存在则新建，并写入：

model_provider = "xmai"
model = "gpt-4o"

[model_providers.xmai]
name = "xmAI"
base_url = "https://api.xmai.sg/v1"
wire_api = "chat"
env_key = "XMAI_API_KEY"

TOML 作用域

顶层的 model_provider 与 model 必须出现在 [model_providers.xmai] 表头之前。若放在表头之后，按 TOML 规范它们会被视为该表的子字段（model_providers.xmai.model = ...），Codex 将忽略顶层意图并回退到内置的默认 OpenAI provider。

关键字段说明：

字段	值	用途
base_url	https://api.xmai.sg/v1	xmAI 的 OpenAI 兼容端点（包含 /v1 — Codex 不会 自动拼接）
wire_api	"chat"	使用 Chat Completions 协议（非 Responses API）
env_key	XMAI_API_KEY	存放 API Key 的环境变量名
model_provider	"xmai"	告知 Codex 默认使用上面定义的 provider
model	"gpt-4o"	启动时的默认模型（xmAI 上任意可用 ID 均可，见下方）

步骤 2 — 导出 API Key

macOS / Linux / Git Bash

export XMAI_API_KEY="sk-your-xmai-key"

Windows PowerShell

$env:XMAI_API_KEY = "sk-your-xmai-key"

Windows CMD

set XMAI_API_KEY=sk-your-xmai-key
:: 仅当前会话。持久化请使用：setx XMAI_API_KEY "sk-your-xmai-key"

建议写入 Shell 配置（~/.zshrc / ~/.bashrc），或 —— Windows 上 —— 使用 setx XMAI_API_KEY "..." 或在系统属性 → 环境变量面板中设置用户变量，以便每次启动 Codex 时自动加载。

步骤 3 — 启动 Codex

codex

状态栏应显示 xmai / gpt-4o。在 Codex 中使用 /model <id> 即可即时切换模型。

可选 — 使用命名 Profile

若想保留默认 OpenAI provider，仅按需切到 xmAI，可以把顶层两字段包到 profile 下：

[model_providers.xmai]
name = "xmAI"
base_url = "https://api.xmai.sg/v1"
wire_api = "chat"
env_key = "XMAI_API_KEY"

[profiles.xmai]
model_provider = "xmai"
model = "gpt-4o"

然后：

codex --profile xmai

模型路由

xmAI 在一把 Key 下统一暴露所有供应商的模型目录。/v1/models 返回的任一 model ID 都可作为 model 字段值。

推荐默认	说明
gpt-4o	OpenAI 旗舰多模态模型
gpt-4o-mini	快速 / 低成本备用
claude-sonnet-4-6	通过 Chat Completions 访问 Claude（xmAI 自动映射 tools / system 段）
gemini-2.5-pro	长上下文 Gemini Pro

跨供应商说明

与直连 OpenAI 的 Codex CLI 不同，指向 xmAI 后可通过 Chat Completions 使用 非 OpenAI 模型 ID（如 claude-sonnet-4-6），xmAI 网关会内部转译到 Anthropic / Google 协议。Tool use、流式、温度参数均可用；如遇 400 报错请对照 错误码。

模型与定价详见 模型列表。

验证接入

在 Codex 中发任意消息，然后：

1. 登录 XmAI 控制台 → 请求日志，查看是否有新记录
2. 或在 Dashboard 的 本日消费 卡片观察 credits 变化

看到新请求即接入成功。

常见问题

404 / model not found

• 对照 /v1/models（或 模型列表 页面）确认模型 ID 正确，Codex 原样透传 model 字段
• 确认 wire_api = "chat" — 若误写为 "responses"，xmAI 会对 /v1/responses 返回 404 Not Found（未实现）
• 确认 base_url 精确为 https://api.xmai.sg/v1（含 /v1，无尾斜杠）

401 / 认证失败

• API Keys 页面确认 Key 未禁用 / 未过期
• 在启动 Codex 的 Shell 中确认 echo $XMAI_API_KEY 能打印 sk-...
• 确认 env_key = "XMAI_API_KEY" 与导出的变量名大小写一致

402 余额不足

xmAI 按 token 实时扣费，余额不足会返回 402 或 insufficient_balance。前往 钱包页面 补充额度，或开启自动充值。

429 频率限制

可能是 xmAI 用户级限流，也可能是上游 429。请实现退避重试；retry-after 头约定见 错误码。

连接失败 / 证书错误

系统代理干扰： 若设置了 http_proxy / https_proxy，可能拦截 xmAI 流量：

export NO_PROXY="api.xmai.sg"

自签名证书： 企业内网若走了自有证书链：

export NODE_EXTRA_CA_CERTS=/path/to/your-ca-chain.pem

切回 OpenAI 原始上游

在 config.toml 中注释掉 model_provider = "xmai"（Codex 回退到默认 OpenAI 认证），或使用 profile 模式后去掉 --profile xmai 参数即可。

相关链接

• Chat Completions API — Codex 调用的底层 API
• 模型列表 — 所有可用模型与价格
• 错误码 — 错误处理指南
• OpenCode — 另一款开源 agent
• OpenAI 兼容工具 — 其他 OpenAI 兼容 CLI / SDK 的通用指南