> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiohub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> 将 AIOHub 配置为 Codex CLI 的模型服务商。

[Codex CLI](https://github.com/openai/codex) 使用 OpenAI Responses API。AIOHub 接入 Codex CLI 时，推荐配置一个独立的 `aiohub` provider，并让 Codex CLI 通过环境变量读取 AIOHub API 令牌。

## 前置条件

* 已安装 Codex CLI
* 已 [创建 AIOHub API 令牌](/cn/account/create-token)
* API 令牌的分组包含你要使用的 Codex / GPT 模型
* 账户有充足余额

可以先确认 Codex CLI 已安装：

```bash theme={"system"}
codex --version
codex --help
```

## 配置方法

### 1. 设置 API 令牌

```bash theme={"system"}
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` |

```toml theme={"system"}
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
```

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

### 可选：同步 Codex App 会话

如果你希望在手机和电脑的 Codex App 之间同步会话，可以让 AIOHub provider 依赖 OpenAI 官方账号登录。关键配置是 `requires_openai_auth = true`。

先在手机和电脑的 Codex App 中登录同一个 ChatGPT 账号，然后在 `~/.codex/config.toml` 中使用以下配置：

```toml theme={"system"}
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
```

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

## 验证配置

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

```bash theme={"system"}
test -n "$AIOHUB_API_KEY" && echo "api key configured"
```

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

```bash theme={"system"}
codex
```

常用命令：

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

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

```bash theme={"system"}
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 控制台记录为准                  |

## 常见问题

<AccordionGroup>
  <Accordion title="连接失败">
    检查 `base_url` 是否是 `https://api.aiohub.org/v1`，`AIOHUB_API_KEY` 是否存在，以及本机代理是否能访问 `api.aiohub.org`。
  </Accordion>

  <Accordion title="模型不可用">
    确认 API 令牌的分组包含所请求的模型，在控制台查看可用模型列表。
  </Accordion>

  <Accordion title="请求走到了 OpenAI 官方账号">
    确认 `model_provider = "aiohub"`，不要把 AIOHub 配置写进内置 `openai` provider。`requires_openai_auth = false` 后，Codex CLI 会使用 `env_key` 指定的 API 令牌。
  </Accordion>

  <Accordion title="WebSocket 或 Realtime 相关报错">
    保持 `supports_websockets = false`。Codex CLI 会使用 Responses HTTP/SSE 传输，不要求网关支持 Responses WebSocket。
  </Accordion>

  <Accordion title="Responses Compact 相关报错">
    `/v1/responses/compact` 只适用于支持 compact 的模型或路由。普通 Codex CLI 会话保持 `wire_api = "responses"`，不要把 `base_url` 写成 `/v1/responses/compact`。
  </Accordion>
</AccordionGroup>

## 官方参考

* [Codex configuration reference](https://www.mintlify.com/openai/codex/configuration/reference)