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

# Codex CLI 终端使用教程

> Codex 集成指南 - Ace Data Cloud

Codex CLI 是 OpenAI 推出的开源本地编程 Agent，运行在你的终端里。它可以阅读代码、修改文件、执行命令、解释错误，并协助完成日常开发任务。

Codex CLI 支持自定义模型模型提供方，你可以通过 Ace Data Cloud 提供的 OpenAI Responses 兼容代理来使用它，无需单独订阅 OpenAI 官方账号。配置完成后，Codex CLI 会把请求发送到 `https://api.acedata.cloud/v1`。

> **先选一种认证方式，不要混用。** 本文使用 `env_key = "ACEDATACLOUD_API_KEY"`，Token 只从环境变量读取。如果你改用 [CC Switch 教程](https://platform.acedata.cloud/documents/codex-cc-switch-integration)，则应由 CC Switch 统一管理 `requires_openai_auth = true` 和 `~/.codex/auth.json`；不要同时保留 `env_key`。混合两套配置可能让 Codex 读取错误或过期的 Token，最终返回 401。

## 申请流程

要使用 Codex CLI，首先可以到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)，获取您的 API Token，留作备用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费体验 Codex CLI 服务。

## 安装 Codex CLI

Codex CLI 支持 macOS、Linux、Windows 和 WSL。你可以通过 npm 安装，也可以使用 Homebrew（仅 macOS）。

### npm 安装（推荐）

如果你已经安装了 Node.js，可以直接通过 npm 安装。该方式要求 Node.js 18 或更高版本。

```bash theme={null}
npm install -g @openai/codex
```

### Homebrew 安装（macOS）

macOS 用户也可以使用 Homebrew 安装：

```bash theme={null}
brew install --cask codex
```

### 检查安装

安装完成后，重新打开终端，然后检查命令是否可用：

```bash theme={null}
codex --version
```

如果提示 `command not found`，通常是当前终端还没有加载新的 PATH。请关闭并重新打开终端，或检查安装脚本输出中提示的 PATH 配置。

## 配置 Codex CLI

安装完成后，Codex CLI 默认会尝试连接 OpenAI 官方服务。要改用 Ace Data Cloud，需要在 Codex 的配置文件中声明一个自定义的 `model_provider`，并把 API Token 放到对应的环境变量里。

### 第一步：设置环境变量

推荐把 API Token 写入 Shell 配置文件，例如 `~/.zshrc`、`~/.bashrc` 或 `~/.bash_profile`：

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

其中 `{token}` 替换为您在 Ace Data Cloud 控制台复制的 API Token。

配置后重新打开终端，或执行对应的 `source` 命令让配置立即生效：

```bash theme={null}
source ~/.zshrc
```

### 第二步：编辑 Codex 配置文件

Codex CLI 使用 `~/.codex/config.toml` 作为全局配置文件。如果该文件不存在，可以新建它：

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

把以下内容写入 `~/.codex/config.toml`：

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

各字段说明如下：

| 字段                                        | 说明                                                 |
| ----------------------------------------- | -------------------------------------------------- |
| `model_provider`                          | 默认使用的模型提供方名称，对应下方 `[model_providers.<name>]` 的 key |
| `model`                                   | 默认使用的模型 ID                                         |
| `model_reasoning_effort`                  | 推理强度，常用值为 `low`、`medium`、`high`                    |
| `[model_providers.acedatacloud].base_url` | Ace Data Cloud 的 OpenAI Responses 代理地址             |
| `[model_providers.acedatacloud].env_key`  | Codex CLI 读取 API Token 的环境变量名称                     |
| `[model_providers.acedatacloud].wire_api` | 协议类型，使用 OpenAI Responses API 必须为 `responses`       |

### 清理已缓存的 OpenAI 登录

如果你之前已经用 OpenAI 官方账号登录过 Codex CLI，本地可能缓存了官方登录状态（通常保存在 `~/.codex/auth.json`）。切换到 Ace Data Cloud 代理前，建议先清理一次旧登录：

```bash theme={null}
codex logout
```

如果 `codex logout` 命令不可用，也可以手动删除缓存文件：

```bash theme={null}
rm -f ~/.codex/auth.json
```

如果你从未登录过 OpenAI 官方账号，可以跳过这一步。

### 启动会话

进入你的项目目录，然后启动 Codex CLI：

```bash theme={null}
cd /path/to/your/project
codex
```

看到 Codex 的交互界面后，就可以直接输入需求，例如：

```text theme={null}
解释这个项目的目录结构
```

### 验证配置

进入 Codex CLI 后，可以在交互界面查看当前模型和模型提供方：

```text theme={null}
/model
```

你应该能看到当前模型来自 `acedatacloud` 这个模型提供方，例如：

```text theme={null}
Model: gpt-5
Provider: acedatacloud
```

如果显示的模型提供方不是 `acedatacloud`，说明配置没有生效。请按下面顺序排查：

1. 打开实际生效的 `~/.codex/config.toml`，确认 `model_provider = "acedatacloud"` 与 `[model_providers.acedatacloud]` 逐字匹配；大小写也必须一致。

2. 确认当前进程可以读取环境变量，但不要把 Token 打印到终端：

   ```bash theme={null}
   test -n "$ACEDATACLOUD_API_KEY" && echo "ACEDATACLOUD_API_KEY is set" || echo "ACEDATACLOUD_API_KEY is missing"
   ```

3. 此方案不使用 `~/.codex/auth.json`。如果该文件来自旧的官方登录或 CC Switch，先运行 `codex logout`，确认不再混用另一套认证来源。

4. 完全退出并重新打开 Codex 和终端；VS Code 用户还需要执行 **Developer: Reload Window** 或完全重启 VS Code。

5. 运行最小验证：

   ```bash theme={null}
   codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK" &lt; /dev/null
   ```

若仍返回 401，先核对 Token 是否复制完整；不要添加 `X-Provider` 等非标准 Header 覆盖。它们不是 Codex 自定义 provider 的通用必填配置，可能改变外部配置工具的路由行为。

你也可以通过 [Ace Data Cloud 控制台 - 使用历史](https://platform.acedata.cloud/console/usages) 查看请求记录和扣费详情，通过 [Ace Data Cloud 控制台 - 应用列表](https://platform.acedata.cloud/console/applications) 查看剩余额度。

## 工作原理

Codex CLI 原生使用 OpenAI Responses API 协议。Ace Data Cloud 在 `https://api.acedata.cloud/v1/responses` 提供兼容 OpenAI Responses API 的代理服务，因此 Codex CLI 不需要本地代理程序，也不需要额外插件。

工作流程如下：

1. Codex CLI 从 `~/.codex/config.toml` 读取 `model_provider`，并加载对应的 `[model_providers.acedatacloud]` 配置块。
2. Codex CLI 从 `env_key` 指定的环境变量（`ACEDATACLOUD_API_KEY`）读取 API Token。
3. 请求通过 `wire_api = "responses"` 协议，发送到 `base_url + /responses`，即 `https://api.acedata.cloud/v1/responses`。
4. Ace Data Cloud 使用您的 API Token 验证身份、检查额度，并把请求转发到可用的目标模型服务。
5. 请求完成后，平台根据实际使用量记录用量并扣减额度。

这意味着你仍然使用原版 `codex` 命令和 Codex CLI 的原生交互体验，只是把底层模型服务切换为 Ace Data Cloud。

## 配置模型

`~/.codex/config.toml` 中的 `model` 字段决定 Codex 默认使用的模型。Ace Data Cloud 的 OpenAI Responses 服务支持多种模型，常用包括：

| 模型              | 说明                 |
| --------------- | ------------------ |
| `gpt-5`         | 推荐默认模型，适合大多数编码任务   |
| `gpt-5-mini`    | 更轻量、响应更快，适合简单任务    |
| `gpt-5.6-sol`   | 最新旗舰，复杂推理与编程首选     |
| `gpt-5.6-terra` | 均衡档，性价比高           |
| `gpt-5.6-luna`  | 轻量档，速度快、成本低        |
| `gpt-5.5`       | 更新版本，能力更强          |
| `gpt-5.5-pro`   | 增强版本，适合复杂推理任务      |
| `gpt-4.1`       | 上一代主力模型            |
| `o3`            | 推理增强模型，适合需要深度推理的任务 |
| `o4-mini`       | 轻量推理模型             |

如果想临时切换模型，可以在启动 Codex 时通过命令行参数指定：

```bash theme={null}
codex --model gpt-5-mini
```

也可以直接修改 `~/.codex/config.toml` 中的 `model` 字段后重新启动。完整的模型列表可以参考 [Ace Data Cloud OpenAI 服务文档](https://platform.acedata.cloud/documents/openai)。

## 输入图片

Codex 会根据实时 `/v1/models` 元数据判断当前模型能否接收图片。当前已经通过真实 Responses 请求验证图片输入的模型包括 `gpt-5.4`、`gpt-5.5`、`gpt-5.6-luna`、`gpt-5.6-terra` 和 `gpt-5.6-sol`。

使用 `--image` 可以在启动任务时附加本地图片：

```bash theme={null}
codex --model gpt-5.6-sol --image ./screenshot.png "读取图片中的报错并修复问题"
```

如果 Codex 提示当前模型不支持图片，请先确认使用的是上面的已验证模型，再重新启动 Codex 以刷新模型元数据。图片能力会随模型更新，以实时模型列表为准。

## 项目信任级别

Codex CLI 支持为不同项目设置不同的信任级别，控制 Agent 可以执行哪些操作。可以在 `~/.codex/config.toml` 末尾追加：

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

其中：

* `trusted`：Agent 拥有完整权限，可以执行命令、修改文件。
* `untrusted`：Agent 仅有受限权限，更适合不熟悉的项目。

## 了解更多

* [Codex CLI 官方仓库](https://github.com/openai/codex)
* [Ace Data Cloud OpenAI 服务文档](https://platform.acedata.cloud/documents/openai)
* [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)