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

# Codex CLI

> 在 macOS、Windows 原生环境与 WSL 2 中配置 OpenAI Codex CLI，通过 Responses API 使用 Yelu AI API。

Codex CLI 支持自定义模型供应商。配置用户级 `yelu` Provider 后，Codex 会携带 Yelu API Key，把 Responses API 请求发送至 `https://api.yelu.ai/v1`。

<Info>
  以下配置使用 Yelu 网关已识别的代码模型 `gpt-5.4`。模型权限取决于账号，请通过 [`GET /v1/models`](/zh/api-reference/models) 确认可用性。
</Info>

## 配置速览

| 配置项         | 值                                                  |
| ----------- | -------------------------------------------------- |
| Provider ID | `yelu`                                             |
| Base URL    | `https://api.yelu.ai/v1`                           |
| Key 环境变量    | `YELU_API_KEY`                                     |
| Wire API    | `responses`                                        |
| 示例模型        | `gpt-5.4`                                          |
| 用户配置文件      | `$CODEX_HOME/config.toml` 或 `~/.codex/config.toml` |

Codex 与 Claude Code 的 Base URL 不同：Codex 的 OpenAI Compatible API 根地址必须包含 `/v1`。

## macOS

### 1. 安装 Codex

使用官方原生安装器：

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
```

也可以使用 Homebrew 或 npm：

<CodeGroup>
  ```bash Homebrew theme={"theme":{"light":"github-light","dark":"github-dark"}}
  brew install --cask codex
  ```

  ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
  npm install -g @openai/codex
  ```
</CodeGroup>

### 2. 设置 Key

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
read -s "YELU_API_KEY?Yelu API key: "
echo
export YELU_API_KEY
```

Key 不会写入 Shell History，并会提供给从当前终端启动的进程。需要持久使用时，请在 Shell 启动时从 macOS Keychain 或其他 Secret Manager 加载。

### 3. 创建 Provider 配置

创建 `~/.codex/config.toml` 并写入：

```toml ~/.codex/config.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
model = "gpt-5.4"
model_provider = "yelu"
model_reasoning_effort = "medium"

[model_providers.yelu]
name = "Yelu AI API"
base_url = "https://api.yelu.ai/v1"
env_key = "YELU_API_KEY"
wire_api = "responses"
```

Provider 必须配置在用户级文件中。出于安全考虑，Codex 会忽略项目 `.codex/config.toml` 内的 `model_provider` 与 `model_providers`。

## Windows

### 原生 PowerShell

使用官方 Windows 安装器：

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --version
```

设置当前 Session 的 Key，输入时不回显：

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$secret = Read-Host "Yelu API key" -AsSecureString
$env:YELU_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
```

创建 `%USERPROFILE%\.codex\config.toml`：

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
@'
model = "gpt-5.4"
model_provider = "yelu"
model_reasoning_effort = "medium"

[model_providers.yelu]
name = "Yelu AI API"
base_url = "https://api.yelu.ai/v1"
env_key = "YELU_API_KEY"
wire_api = "responses"
'@ | Set-Content -Encoding utf8 "$HOME\.codex\config.toml"
```

如需在新终端自动加载 Key，请使用 Windows Secret Manager。也可以为了便利使用用户环境变量，但它并不是专用的 Secret Vault。

Windows 原生 Codex 使用 Windows Sandbox。大多数项目保留默认设置即可，不要为了绕过普通权限问题直接切换到无限制执行。

### WSL 2

如果仓库和工具位于 Linux 环境，请选择 WSL 2：

```powershell 管理员 PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
wsl --install
wsl
```

随后在 WSL 内安装并配置：

```bash WSL 2 theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
read -rsp "Yelu API key: " YELU_API_KEY; echo
export YELU_API_KEY
mkdir -p ~/.codex
codex --version
```

把同一段 TOML Provider 配置写入 WSL 的 `~/.codex/config.toml`。Windows 与 WSL 的 Codex 使用各自独立的 Home、Key 和配置文件。建议将 WSL 项目放在 `~/code`，不要放在 `/mnt/c`，以获得更好的文件系统性能。

## 验证 API 与配置

先确认 Key 可以访问模型：

<CodeGroup>
  ```bash macOS / WSL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY"
  ```

  ```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
  Invoke-RestMethod `
    -Uri "https://api.yelu.ai/v1/models" `
    -Headers @{ Authorization = "Bearer $env:YELU_API_KEY" }
  ```
</CodeGroup>

在 Git 仓库中校验本地配置，并运行只读 Smoke Test：

```bash Terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
codex --strict-config --version
codex exec --strict-config --ephemeral --sandbox read-only \
  "Reply with exactly: Yelu Codex is ready"
```

进入交互 Session 后执行 `/status`，确认 Provider 为 `yelu`、模型为 `gpt-5.4`，并检查工作目录是否正确。

## 安全默认值

* 只在环境变量或 Secret Manager 中保存 `YELU_API_KEY`，不要把 Key 直接写入 TOML。
* 首次处理陌生仓库时使用 `--sandbox read-only`，或先通过 `/permissions` 检查权限。
* 只有任务确实需要修改当前 Workspace 时才使用 `workspace-write`。
* 接受改动前检查 Diff 并运行测试。
* 不要在普通工作站上使用 `--dangerously-bypass-approvals-and-sandbox`。

## 故障排查

| 现象                    | 解决方法                                                                            |
| --------------------- | ------------------------------------------------------------------------------- |
| 缺少 `YELU_API_KEY`     | 在启动 Codex 的同一个终端中设置，然后重启 Codex。                                                 |
| 请求仍发往 OpenAI          | 确认用户级 `config.toml` 中存在 `model_provider = "yelu"`。                              |
| `404` 或 URL 错误        | 使用完整的 `base_url = "https://api.yelu.ai/v1"`。                                    |
| Unknown model         | 查询 [`GET /v1/models`](/zh/api-reference/models)，选择当前 Key 可用且兼容 Responses 的代码模型。 |
| 配置项被拒绝                | 更新 Codex，并用 `--strict-config` 定位不支持的字段。                                         |
| WSL 看不到 Windows Key   | 在 WSL 内单独导出 `YELU_API_KEY`。                                                     |
| Windows 原生 Sandbox 失败 | 执行 `codex doctor`；若工作站策略不兼容，可改用 WSL 2。                                          |

## 下一步

继续查看 [Codex CLI 示例](/zh/examples/codex-cli)，完成仓库分析、实现、审查、图片输入和自动化任务。

## 官方参考

* [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
* [Codex 配置基础](https://learn.chatgpt.com/docs/config-file/config-basic)
* [Codex 配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)
* [在 WSL 中使用 Codex](https://learn.chatgpt.com/docs/windows/wsl)