Codex CLI

Codex CLI 使用 OpenAI Responses API。AIOHub 接入 Codex CLI 时，推荐配置一个独立的 aiohub provider，并让 Codex CLI 通过环境变量读取 AIOHub API 令牌。

前置条件

已安装 Codex CLI
已创建 AIOHub API 令牌
API 令牌的分组包含你要使用的 Codex / GPT 模型
账户有充足余额

可以先确认 Codex CLI 已安装：

codex --version
codex --help

配置方法

1. 设置 API 令牌

export AIOHUB_API_KEY="sk-你的API令牌"

如果需要长期生效，可以把这一行写入 ~/.zshrc、~/.bashrc 或你的 shell profile。

2. 配置 AIOHub provider

编辑 ~/.codex/config.toml。不要覆盖内置 openai provider；使用独立的 aiohub 名称，便于和 OpenAI 官方登录隔离。配置文件位置：

系统	路径
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

model_provider = "aiohub"
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
model_verbosity = "high"
disable_response_storage = true

[model_providers.aiohub]
name = "AIOHub"
base_url = "https://api.aiohub.org/v1"
env_key = "AIOHUB_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Codex 的 base_url 填到 /v1 即可，不要填 /v1/responses。supports_websockets = false 会让 Codex 通过 HTTP/SSE 调用 Responses API，适合当前 AIOHub 网关配置。

可选：同步 Codex App 会话

如果你希望在手机和电脑的 Codex App 之间同步会话，可以让 AIOHub provider 依赖 OpenAI 官方账号登录。关键配置是 requires_openai_auth = true。先在手机和电脑的 Codex App 中登录同一个 ChatGPT 账号，然后在 ~/.codex/config.toml 中使用以下配置：

model_provider = "aiohub"

[model_providers.aiohub]
name = "OpenAI"
base_url = "https://api.aiohub.org/v1"
experimental_bearer_token = "sk-你的API令牌"
wire_api = "responses"
requires_openai_auth = true

这个配置用于需要 OpenAI 账号会话同步的 Codex App 场景。若只在 Codex CLI 中使用 AIOHub，推荐继续使用上面的 env_key 配置，并保持 requires_openai_auth = false。

验证配置

先确认环境变量存在，不要把 API 令牌值打印到终端：

test -n "$AIOHUB_API_KEY" && echo "api key configured"

再启动 Codex CLI 并发送一条短消息：

codex

常用命令：

命令	用途
`codex`	进入交互模式
`codex "解释这个项目"`	带初始提示进入交互模式
`codex exec "统计当前目录文件"`	非交互执行一次任务

正常回复即表示配置成功。若要先用 HTTP 验证网关，可以请求 Responses API：

curl https://api.aiohub.org/v1/responses \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "input": "Reply with one short sentence."
  }'

配置说明

参数	说明
`model_provider`	使用自定义 provider
`base_url`	AIOHub OpenAI 兼容根地址，包含 `/v1`
`env_key`	Codex CLI 从该环境变量读取 AIOHub API 令牌
`experimental_bearer_token`	直接在配置文件中写入 AIOHub API 令牌；仅在需要 Codex App 会话同步时使用
`wire_api`	Codex CLI 使用 `responses`
`requires_openai_auth`	CLI 独立鉴权时设为 `false`；需要 Codex App 通过同一个 ChatGPT 账号同步会话时设为 `true`
`supports_websockets`	设为 `false`，使用 HTTP/SSE Responses
`model`	模型名称，按 API 令牌的分组可用模型修改
`model_reasoning_effort`	推理强度：`low` / `medium` / `high` / `xhigh`
`disable_response_storage`	向上游请求关闭 Responses 内容存储；实际用量和费用以 AIOHub 控制台记录为准

常见问题

连接失败

检查 base_url 是否是 https://api.aiohub.org/v1，AIOHUB_API_KEY 是否存在，以及本机代理是否能访问 api.aiohub.org。

模型不可用

确认 API 令牌的分组包含所请求的模型，在控制台查看可用模型列表。

请求走到了 OpenAI 官方账号

确认 model_provider = "aiohub"，不要把 AIOHub 配置写进内置 openai provider。requires_openai_auth = false 后，Codex CLI 会使用 env_key 指定的 API 令牌。

WebSocket 或 Realtime 相关报错

保持 supports_websockets = false。Codex CLI 会使用 Responses HTTP/SSE 传输，不要求网关支持 Responses WebSocket。

Responses Compact 相关报错

/v1/responses/compact 只适用于支持 compact 的模型或路由。普通 Codex CLI 会话保持 wire_api = "responses"，不要把 base_url 写成 /v1/responses/compact。

官方参考

Codex configuration reference

选择客户端

AI 编程工具

OpenAI 兼容应用

图片客户端

聊天客户端

前置条件

配置方法

1. 设置 API 令牌

2. 配置 AIOHub provider

可选：同步 Codex App 会话

验证配置

配置说明

常见问题

官方参考

​前置条件

​配置方法

​1. 设置 API 令牌

​2. 配置 AIOHub provider

​可选：同步 Codex App 会话

​验证配置

​配置说明

​常见问题

​官方参考

前置条件

配置方法

1. 设置 API 令牌

2. 配置 AIOHub provider

可选：同步 Codex App 会话

验证配置

配置说明

常见问题

官方参考