> ## 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 for VS Code 使用教程

> Codex 集成指南 - Ace Data Cloud

Codex 是 OpenAI 推出的编程 Agent。除了终端 CLI，它也提供了 VS Code 扩展，可以在编辑器侧边栏里聊天、阅读文件、引用上下文、生成修改并预览变更。

本文介绍如何通过 Ace Data Cloud 的 OpenAI Responses 兼容代理，在 VS Code 中配置和使用 Codex 扩展。Codex VS Code 扩展和 Codex CLI 使用同一个本地配置体系，因此只要把 `~/.codex/config.toml` 指向 Ace Data Cloud，即可让 VS Code 中的 Codex 走 `https://api.acedata.cloud/v1`。

> **先选一种认证方式，不要混用。** 本文使用 `env_key = "ACEDATACLOUD_API_KEY"`。如果你使用 [CC Switch 教程](https://platform.acedata.cloud/documents/codex-cc-switch-integration)，则应让 CC Switch 统一写入 `requires_openai_auth = true` 和 `~/.codex/auth.json`，不要再保留 `env_key`。两套配置混在一起是 Codex 401 的常见原因。

## 申请流程

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

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

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

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

## 安装 Codex 扩展

在 VS Code 的扩展市场中搜索 `Codex`，安装 OpenAI 发布的 **Codex - OpenAI's coding agent** 扩展。它的 Marketplace ID 是：

```text theme={null}
openai.chatgpt
```

也可以在命令行中安装：

```bash theme={null}
code --install-extension openai.chatgpt
```

安装完成后，重启或重新加载 VS Code。如果没有看到 Codex 入口，可以打开命令面板（macOS：`Cmd+Shift+P`，Windows/Linux：`Ctrl+Shift+P`），搜索并运行：

```text theme={null}
Codex: Open Codex Sidebar
```

Codex 默认会出现在 VS Code 右侧侧边栏。你也可以把它拖回左侧 Activity Bar。

## 安装 Codex CLI（用于验证）

官方文档说明 Codex VS Code 扩展和 Codex CLI 使用同一套配置层。为了在配置 VS Code 前先验证 API Token 和模型是否可用，建议同时安装 Codex CLI。

官方推荐方式之一是通过 npm 安装，要求 Node.js 18 或更高版本：

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

macOS 用户也可以通过 Homebrew 安装：

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

安装完成后，在终端检查命令是否可用：

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

如果你只想使用 VS Code 扩展，也可以跳过 CLI 验证步骤；后续仍然使用同一份 `~/.codex/config.toml` 配置。

## 配置 Ace Data Cloud API

Codex VS Code 扩展和 Codex CLI 共享配置文件。默认情况下，Codex 会提示登录 OpenAI 官方账号或配置官方 API Key。要改用 Ace Data Cloud，需要配置 API Token 和 `~/.codex/config.toml`。

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

推荐把 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
```

如果 VS Code 已经打开，请重启或重新加载 VS Code，让扩展读取到新的环境变量。

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

Codex 的用户级配置文件位于 `~/.codex/config.toml`。如果该文件不存在，可以新建：

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

写入以下配置：

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[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.acedatacloud]` |
| `model`                  | 默认使用的模型 ID                                         |
| `model_reasoning_effort` | 推理强度，常用值为 `low`、`medium`、`high`                    |
| `approval_policy`        | 命令执行前的确认策略，日常使用推荐 `on-request`                     |
| `sandbox_mode`           | Codex 执行命令时的沙箱权限，日常开发推荐 `workspace-write`          |
| `base_url`               | Ace Data Cloud 的 OpenAI 兼容 API 地址                  |
| `env_key`                | Codex 读取 API Token 的环境变量名称                         |
| `wire_api`               | 协议类型，使用 OpenAI Responses API 必须为 `responses`       |

也可以在 Codex 扩展右上角点击齿轮图标，选择 **Codex Settings > Open config.toml**，直接从 VS Code 打开这份配置文件。

### 项目级配置

如果你只想让某个项目使用不同配置，可以在项目根目录创建 `.codex/config.toml`。Codex 会优先读取项目级配置，但项目需要被标记为 trusted 才会加载 `.codex/` 下的配置。

示例：

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

建议把包含个人 Token 的配置放在环境变量里，不要写进项目仓库。项目级 `.codex/config.toml` 也建议按团队情况决定是否提交。

## 清理已缓存的 OpenAI 登录

如果你之前已经在 Codex 扩展中登录过 OpenAI 官方账号，本地可能仍然保留官方登录状态。切换到 Ace Data Cloud 代理前，可以先在终端运行：

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

如果命令不可用，也可以删除本地缓存文件：

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

然后重启或重新加载 VS Code。

## 基本使用

配置完成后，打开 VS Code 左侧或右侧的 Codex 面板，直接输入需求即可。例如：

```text theme={null}
解释当前项目的目录结构，并指出主要入口文件。
```

Codex 扩展可以结合编辑器中的文件和选中代码作为上下文。你也可以在输入框中用 `@` 引用文件，例如：

```text theme={null}
参考 @src/App.vue，帮我把这个页面拆成更清晰的组件。
```

如果选中一段代码，可以通过命令面板运行：

```text theme={null}
Codex: Add to Codex Thread
```

也可以运行：

```text theme={null}
Codex: Add File to Codex Thread
```

把整个当前文件加入上下文。

## 切换模型和推理强度

Codex VS Code 扩展支持在输入框下方的模型切换器中切换模型，也可以调整 reasoning effort。使用 Ace Data Cloud 自定义模型提供方时，最稳妥的方式是先在 `~/.codex/config.toml` 中写好默认 `model`，再按需在界面里切换。推荐默认使用：

| 场景         | 推荐模型                      | 推理强度     |
| ---------- | ------------------------- | -------- |
| 日常代码阅读和小修改 | `gpt-5-mini`              | `medium` |
| 常规开发任务     | `gpt-5`                   | `high`   |
| 复杂重构和深度推理  | `gpt-5.5` 或 `gpt-5.5-pro` | `high`   |
| 推理增强任务     | `o3`                      | `high`   |

如果界面里没有显示你想要的模型，可以直接修改 `~/.codex/config.toml` 中的 `model` 字段，然后重启或重新加载 VS Code。完整模型列表可参考 [Ace Data Cloud OpenAI 服务文档](https://platform.acedata.cloud/documents/openai)。

## 选择工作模式

Codex 扩展支持不同工作模式。常见模式如下：

| 模式                    | 适用场景                            |
| --------------------- | ------------------------------- |
| `Chat`                | 只想讨论、解释代码、先做计划，不希望 Codex 直接改文件  |
| `Agent`               | 让 Codex 阅读文件、修改代码、运行必要命令，日常开发推荐 |
| `Agent (Full Access)` | 允许更高权限和网络访问，适合你明确知道风险的场景        |

日常建议使用 `Agent`，并保留 `approval_policy = "on-request"`。这样 Codex 在需要执行敏感命令、访问工作区外路径或网络时，会先询问确认。

## 验证配置

可以先在终端用同一套配置验证 Codex 是否能通过 Ace Data Cloud 工作：

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

如果配置正确，应能看到类似回复：

```text theme={null}
ADC_Codex_OK
```

如果这里返回 401，请先确认：`model_provider` 与 `[model_providers.&lt;名称>]` 逐字匹配；VS Code 是从带有 `ACEDATACLOUD_API_KEY` 的父进程启动；`~/.codex/auth.json` 没有与本教程的 `env_key` 方案混用。不要添加 `X-Provider` 等非标准 Header 覆盖。修正后要完全退出并重启 VS Code，仅关闭面板不一定会刷新进程环境。

然后回到 VS Code，打开 Codex 面板，输入一个简单问题：

```text theme={null}
用一句话说明当前工作区的用途。
```

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

## 工作原理

Codex VS Code 扩展并不是独立的一套模型配置。它使用本机 Codex CLI，并共享 Codex 的配置层：

1. VS Code 扩展启动 Codex，并读取用户级 `~/.codex/config.toml`。
2. 如果当前项目被信任，并且项目里存在 `.codex/config.toml`，Codex 会再加载项目级配置。
3. 当 `model_provider` 指向 `acedatacloud` 时，Codex 从 `ACEDATACLOUD_API_KEY` 读取 API Token。
4. 请求通过 OpenAI Responses 协议发送到 `https://api.acedata.cloud/v1/responses`。
5. Ace Data Cloud 验证身份、检查额度、转发请求，并记录用量。

因此，终端 CLI 和 VS Code 扩展通常只需要配置一次。你在终端验证通过后，VS Code 扩展也会使用同一份配置。

## 了解更多

* [Codex IDE extension 官方文档](https://developers.openai.com/codex/ide)
* [Codex IDE extension 设置参考](https://developers.openai.com/codex/ide/settings)
* [Codex CLI 配置基础](https://developers.openai.com/codex/config-basic)
* [Ace Data Cloud OpenAI 服务文档](https://platform.acedata.cloud/documents/openai)