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

# Codex 接入

> 通过 Codex 自定义 provider 使用晨羽智云大模型网关

# Codex 接入

Codex 使用自定义 provider 接入。晨羽智云网关为 Codex 单独提供 `/codex/v1/*` 路径，用于返回 Codex 模型目录并转发 Responses 请求。

Codex 桌面 App、CLI 和 IDE 插件会共享用户级配置：

```text theme={null}
~/.codex/config.toml
```

<Warning>
  provider 和认证配置必须写在用户级 `~/.codex/config.toml`。不要写到项目里的 `.codex/config.toml`，Codex 会忽略项目级 provider/auth 配置。
</Warning>

## 一键配置

推荐直接运行晨羽智云提供的配置脚本：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/cgf120/mintlify-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
```

脚本会提示输入 API Key，并自动完成：

* 创建 `~/.codex/chenyu-codex-key`，用于保存 API Key
* 备份并更新 `~/.codex/config.toml`
* 配置 `chenyu-codex` provider
* 设置 `base_url = "https://api.chenyu.cn/codex/v1"`
* 设置 `wire_api = "responses"`
* 设置默认模型 `doubao-seed-2-0-lite-260428`

如果当前终端不能交互输入，可以先设置环境变量：

```bash theme={null}
export CHENYU_LLM_API_KEY="YOUR_API_KEY"
curl -fsSL https://raw.githubusercontent.com/cgf120/mintlify-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
```

<Note>
  这个脚本只管理 `chenyu-codex` provider 和顶层 `model`、`model_provider` 配置，会保留已有的 MCP、sandbox、skills 等其它 Codex 配置。
</Note>

<Warning>
  不要直接使用通用 OpenAI 兼容 `/v1` 配置脚本配置 Codex。Codex 需要使用晨羽智云专用地址 `https://api.chenyu.cn/codex/v1`，不能写成 `https://api.chenyu.cn/v1`。
</Warning>

## 安装 Codex

如果已安装 Codex，可以跳过本节。

<Tabs>
  <Tab title="桌面 App">
    下载并安装 Codex 桌面客户端。安装后先不要急着发送消息，先完成下面的 provider 配置。
  </Tab>

  <Tab title="CLI">
    安装完成后确认命令可用：

    ```bash theme={null}
    codex --version
    ```
  </Tab>
</Tabs>

## 验证配置

### 验证模型列表

```bash theme={null}
codex debug models
```

正常情况下会看到晨羽智云模型，例如：

```text theme={null}
doubao-seed-2-0-lite-260428
doubao-seed-2-0-mini-260428
doubao-seed-2-0-pro-260215
```

### 验证对话调用

```bash theme={null}
codex exec --skip-git-repo-check --ephemeral --sandbox read-only "只回复 OK"
```

如果最终输出 `OK`，说明模型列表和实际调用都已接入成功。

## 启动桌面 App

配置完成后，完整退出并重新打开 Codex 桌面 App，让它重新加载 `~/.codex/config.toml`：

```bash theme={null}
osascript -e 'tell application "Codex" to quit'
open -a Codex
```

进入桌面 App 后，选择项目目录，确认使用本地执行模式，然后发送消息即可。

## 模型选择

Codex 中使用 `/model` 查看和切换模型。Codex 路径使用真实模型 ID，不使用 `claude-` 前缀：

```text theme={null}
doubao-seed-2-0-lite-260428
```

`/codex/v1/models` 只返回适合 Codex 使用的文本类模型，会过滤图片、视频和 3D 模型。

## 为什么使用独立 Codex 路径

Codex 的模型目录不是标准 OpenAI `/v1/models` 格式。它需要专用 catalog 字段来驱动 `/model` 模型选择器。

因此推荐：

| 客户端         | 路径           |
| ----------- | ------------ |
| OpenAI SDK  | `/v1`        |
| Claude Code | `/anthropic` |
| Codex       | `/codex/v1`  |

这样可以同时保持 OpenAI SDK 的真实模型列表，以及 Codex 的模型选择体验。

## 兼容说明

Codex 会发送一些 OpenAI Responses 专属字段。网关会自动处理常见兼容问题，包括：

* 清理上游不支持的 Codex 元数据字段
* 为多轮对话历史补充必要状态
* 过滤上游不支持的工具类型
* 隐藏 Codex 内置的官方默认模型

如果第二轮对话出现上游参数错误，请重新运行一键配置脚本，确认 Codex 使用的是 `https://api.chenyu.cn/codex/v1`。

## 常见问题

### `codex` 命令不存在

确认 Codex CLI 已安装，并检查常见安装路径是否在 `PATH` 中：

```bash theme={null}
command -v codex
```

如果桌面 App 已安装，但终端中没有 `codex` 命令，可以尝试直接使用桌面 App 内置命令：

```bash theme={null}
/Applications/Codex.app/Contents/Resources/codex --version
```

### 401 Unauthorized

通常是 API Key 无效或 key 文件内容格式不正确。请确认：

* `~/.codex/chenyu-codex-key` 中只包含 API Key
* 没有写入 `Bearer `
* 没有写入额外的 `sk ` 前缀
* API Key 未被禁用，并且账户可用

### 桌面 App 没有读取新配置

完整退出并重新打开桌面 App：

```bash theme={null}
osascript -e 'tell application "Codex" to quit'
open -a Codex
```

### 桌面 App 可以打开，但回复显示异常

先用 CLI 验证：

```bash theme={null}
codex debug models
codex exec --skip-git-repo-check --ephemeral --sandbox read-only "只回复 OK"
```

如果 CLI 正常但桌面 App 显示异常，请联系技术支持，并提供 Codex 日志中的错误信息。常见相关日志包括：

```text theme={null}
OutputTextDelta without active item
ReasoningSummaryDelta without active item
```