# Codex

OpenAI 的终端编程助手,擅长执行任务、排查问题、动手解决。

---

## 一、安装 Codex

### 方式 A:镜像一键安装(推荐,无需 Node.js)

```bash
curl -fsSL https://help.clomio.ai/codex/install.sh | bash
```

Windows PowerShell:

```powershell
irm https://help.clomio.ai/codex/install.ps1 | iex
```

### 方式 B:npm 全局安装

需要先装好 [Node.js 环境](#/nodejs)。

```bash
npm install -g @openai/codex@latest
```

macOS / Linux 遇权限问题加 `sudo`。

### 验证

```bash
codex --version
```

输出版本号即安装成功。

### 更新到最新版

```bash
# 镜像安装的:重跑一次安装命令即更新
curl -fsSL https://help.clomio.ai/codex/install.sh | bash

# npm 安装的:重装 @latest
npm install -g @openai/codex@latest
```

Windows 镜像安装的更新命令:

```powershell
irm https://help.clomio.ai/codex/install.ps1 | iex
```

---

## 二、获取密钥

在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个 **Codex / GPT 分组** 的密钥,详见 [创建 API 密钥](#/api-key)。

---

## 三、接上 Clomio

Codex 推荐用 `~/.codex/config.toml` 指向网关,密钥放在本机环境变量里。配置目录在 `~/.codex/`(Windows 为 `%USERPROFILE%\.codex\`)。

### `~/.codex/config.toml`

```toml
model_provider = "clomio"
model = "gpt-5.4"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

[model_providers.clomio]
name = "clomio"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
```

> `model` 填你的分组实际开放的模型名,以控制台显示为准。`base_url` 需要带 `/v1`;`wire_api = "responses"` 是 Codex 接入网关的关键项,不要改。

> `base_url` 也可换成另外两条线路(`https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1`),国内通常更稳。见 [网关线路](#/gateway-lines)。

> 如果 Codex 出现 `Reconnecting...`、企业代理拦截 WebSocket Upgrade、或 WS 不稳定，先加 `supports_websockets = false` 回落 HTTP/SSE 验证；不要把 `base_url` 改成 `/v1/responses`。

> 如果你把 provider/base URL 复制到项目里的 `.codex/config.toml` 后不生效,请先移到用户级 `~/.codex/config.toml` 或 profile 文件；Codex 会忽略 project config 里的 provider/auth 类键。详见 [Codex 配置详解](#/codex-config)。

> 控制台「使用 Key」弹窗为了复制即用,可能给出 `experimental_bearer_token` + `requires_openai_auth = true` 的自包含模板。长期推荐仍是本页的 `env_key = "CLOMIO_API_KEY"` 环境变量写法。两种认证方式不要混用:如果从弹窗模板切到环境变量,请删除 `experimental_bearer_token` 和 `requires_openai_auth`。

### 设置密钥环境变量

把 `你的密钥` 换成控制台复制的密钥。Codex 会按上面配置的 `env_key = "CLOMIO_API_KEY"` 读取这个变量。

**macOS / Linux:**

```bash
export CLOMIO_API_KEY="你的密钥"
# 想长期生效可写入 ~/.zshrc 或 ~/.bashrc
```

**Windows(PowerShell):**

```powershell
$env:CLOMIO_API_KEY = "你的密钥"
# 想长期生效:
[Environment]::SetEnvironmentVariable("CLOMIO_API_KEY", "你的密钥", "User")
```

### 用命令快速创建配置目录

**macOS / Linux:**

```bash
mkdir -p ~/.codex
```

**Windows(PowerShell):**

```powershell
mkdir "$env:USERPROFILE\.codex" -Force
```

然后用编辑器把上面的 `config.toml` 放进去,并设置好 `CLOMIO_API_KEY` 环境变量即可。

### 先用 curl 验证 Responses

在打开 Codex 前,先用同一把 key 和同一个模型测网关。这样可以把“网关/key/model 问题”和“Codex 配置读取问题”分开:

```bash
curl https://api.clomio.ai/v1/responses   -H "Authorization: Bearer $CLOMIO_API_KEY"   -H "content-type: application/json"   -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}'
```

看到 `id`、`output` 或流式事件结构,说明网关和 Key 可用;如果这里已经 401/404/`model_not_found`,先改 Key 分组、模型名或 Base URL,不要继续排 Codex 本地配置。

如果要确认 `GET /v1/responses` 不是 REST 查询接口,可以普通 GET 一次。支持 Responses WebSocket 的 OpenAI/Grok 分组预期结果是 426,表示“必须 WebSocket Upgrade”;未开放该能力的分组才会返回 404:

```bash
curl -i https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer $CLOMIO_API_KEY"
# OpenAI/Codex 分组预期: 426 WebSocket upgrade required
# 未开放 WS 的分组预期: 404 Responses WebSocket API is not supported for this platform
```

### 或者:CC Switch 图形化

和 Claude Code 一样,[CC Switch](https://github.com/farion1231/cc-switch) 也能一键管理 Codex 的配置,把请求地址设为 `https://api.clomio.ai/v1`、填入密钥并启用即可。

---

## 四、开始使用

进入任意项目目录,运行:

```bash
codex
```

第一次有初始化引导,一路回车用默认即可。进去后试几句:

```text
你现在用的是什么模型?
```

```text
帮我看看当前文件夹里有什么
```

能正常进入交互界面、没有报错,就说明可以用了。

---

## Codex 在 Clomio 上实际打哪些路径

Codex/OpenAI-compatible 接入的 base URL 必须是 `https://api.clomio.ai/v1`。Codex CLI 使用 Responses wire API,主请求是 `POST /v1/responses`;流式可以是 SSE,支持 WebSocket 的 provider 也可能升级到 `GET /v1/responses` 的 WS 入口。不要把 base URL 写成 `/v1/responses`,也不要写“按 response id 发 GET 查询历史”的路径。

如果你同时在用 Claude Code,注意两者不同:

| 工具 | Base URL | 主路径 |
|------|----------|--------|
| Claude Code | `https://api.clomio.ai` | `POST /v1/messages` |
| Codex | `https://api.clomio.ai/v1` | `POST /v1/responses` |

### 启用 Codex WS profile

只有确认客户端版本和当前网络都支持 Responses WebSocket v2 时才启用。控制台「Codex WS」模板会同时写两处开关:provider 下的 `supports_websockets = true`,以及 `[features].responses_websockets_v2 = true`。只写其中一个时,客户端可能仍走 HTTP/SSE。

```toml
model_provider = "clomio_ws"
model = "gpt-5.4"
preferred_auth_method = "apikey"

[model_providers.clomio_ws]
name = "clomio_ws"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
supports_websockets = true

[features]
responses_websockets_v2 = true
```

### WS 不稳定时的 HTTP/SSE 回落 profile

如果终端反复 `Reconnecting...`，或公司网络/代理不允许 WebSocket Upgrade，先用这个配置确认普通 Responses/SSE 链路是否正常：

```toml
model_provider = "clomio"
model = "gpt-5.4"
preferred_auth_method = "apikey"

[model_providers.clomio]
name = "clomio"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
supports_websockets = false
```

确认 HTTP/SSE 正常后，再按网络环境决定是否恢复 WebSocket。无论是否启用 WS，`base_url` 都只写到 `/v1`。

## 常见问题

**`codex` 提示命令找不到?** 见 [故障排查](#/troubleshooting)。

**连接失败 / 401?** 检查 `config.toml` 里 `base_url` 是否为 `https://api.clomio.ai/v1`、`CLOMIO_API_KEY` 环境变量里的密钥是否正确未过期、分组是否为 Codex/GPT。

**提示模型不存在?** `config.toml` 里的 `model` 必须是该分组实际开放的模型名,以控制台为准。

**改了配置但 Codex 还连旧地址?** 命令行 `-c key=value` / `--config`、`--profile`、受信任项目里的 `.codex/config.toml`、旧 `OPENAI_API_KEY` / `auth.json` 都可能覆盖你的用户级配置。按下面查:

```bash
codex -c model_provider=clomio
env | grep -E 'CLOMIO|OPENAI'
find . -path '*/.codex/config.toml' -print
grep -R "base_url\|model_provider\|env_key\|requires_openai_auth" ~/.codex ./.codex 2>/dev/null
```

Clomio 推荐 `env_key = "CLOMIO_API_KEY"`。如果用了 `requires_openai_auth = true`,Codex 可能改走 OpenAI 认证链路或旧 `auth.json`;不要和 `env_key` 长期混用。

**能否把 Grok/Claude 当 fallback 写进同一个 Codex provider?** 不建议。Codex provider 走 OpenAI-compatible Responses wire API;Claude/Anthropic Messages 是另一套协议。fallback 只在同协议、同 base URL 规则内切换,跨协议请新建对应工具配置。

**控制台里 OpenAI Key 出现 Claude Code tab 是不是 Codex fallback?** 不是。那表示该 OpenAI/Codex 分组额外开放 Claude Code 风格 `/v1/messages` 兼容入口。Codex CLI 自身仍应走 `/v1/responses`。

---

## 官方参考资料

- [OpenAI Codex Config basics](https://developers.openai.com/codex/config-basic):用户级与受信任项目级配置、默认模型/provider 的基础写法。
- [OpenAI Codex Configuration reference](https://developers.openai.com/codex/config-reference):`model_provider`、`model_providers.*`、`env_key`、`wire_api` 等字段以这里为准。
- [OpenAI Codex Advanced config](https://developers.openai.com/codex/config-advanced):profile 文件和一次性 CLI 覆盖的推荐方式。
- [OpenAI Codex CLI reference](https://developers.openai.com/codex/cli/reference):命令行 `-c` 覆盖优先级和运行参数。
- [Codex 社区配置经验(X)](https://x.com/canghe/article/2060376680896799094):中转站/代理接入时,`base_url` 写到 `/v1` 即止,不要写成 `/v1/responses`。
- [Codex WS 排障经验(X)](https://x.com/mylifcc/status/2057308552738505031):出现 `Reconnecting...` 一类症状时,社区常用 `supports_websockets = false` 回落 HTTP/SSE;Clomio 上是否启用 WS 以 provider 配置和当前分组能力为准。