Codex 安装并不难，真正容易卡住的是接入：API Key 放在哪里、config.toml 怎么写、Windows 和 macOS 有什么区别、VS Code 为什么读不到终端里的变量、模型要不要固定……

如果你只想尽快把 Codex 跑起来，可以把配置收敛为三个值：

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

完成后，Codex CLI、Desktop 和 VS Code 扩展可以共享 ~/.codex/config.toml，模型则在启动后直接选择，不需要为了换模型不断改接入配置。

下面从零开始完成一次配置。

准备工作

开始前请确认：

  • 已注册并登录 Ace Data Cloud
  • 已创建或拥有一个可用应用
  • 本机已安装 Node.js 与 npm
  • 能够使用终端或 PowerShell
  • 准备使用 Codex CLI、Codex Desktop 或 VS Code 扩展中的至少一种

第一步：获取 Ace Data Cloud API Key

打开 Ace Data Cloud 应用列表，进入可用应用并复制 API Key。

请注意：

  • API Key 属于敏感凭证，不要写进公开仓库
  • 不要把真实 Key 放入教程截图
  • 建议按环境或用途分别创建和管理凭证
  • 怀疑泄露时，应及时轮换或撤销

本文统一使用环境变量 ACEDATACLOUD_API_KEY，避免将明文凭证直接写入 Codex 配置文件。

第二步：安装 Codex CLI

使用 npm 全局安装 Codex：

npm install -g @openai/codex

安装后验证：

codex --version

如果提示找不到命令，先确认 npm 全局可执行目录已加入 PATH，再重新打开终端。

如果你主要使用 VS Code，也可以安装 OpenAI 发布的 Codex 扩展：

code --install-extension openai.chatgpt

CLI 与 VS Code 扩展共享配置文件，因此建议先把 Provider 和环境变量配置好，再启动编辑器验证。

第三步：设置 API Key 环境变量

macOS / Linux：当前终端会话

export ACEDATACLOUD_API_KEY="你的 API Key"

该命令只对当前 Shell 及其子进程生效。关闭终端后变量会消失。

macOS / Linux：长期生效

如果使用 Zsh：

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

如果使用 Bash：

echo 'export ACEDATACLOUD_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

不要在共享电脑上盲目复制包含真实 Key 的 Shell 配置；团队环境应结合凭证管理工具和最小权限策略。

Windows PowerShell

setx ACEDATACLOUD_API_KEY "你的 API Key"

执行后关闭并重新打开 PowerShell。setx 不会自动更新当前已打开的进程，因此原有终端和 VS Code 可能仍然读取不到新值。

如需只在当前 PowerShell 会话临时设置：

$env:ACEDATACLOUD_API_KEY="你的 API Key"

第四步：创建或编辑 config.toml

Codex CLI、Desktop 和 VS Code 扩展共享以下配置文件：

  • macOS / Linux：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml

如果目录不存在，先创建。

macOS / Linux：

mkdir -p ~/.codex

然后写入：

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows 使用相同的 Provider 和 Base URL，但认证命令改为 PowerShell：

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

配置中的三个名称要严格保持一致：

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Base URL 也要完整包含 /v1。

第五步：启动 Codex 并选择模型

保存配置后，重新打开终端并运行：

codex

进入 Codex 后运行：

/model

确认当前 Provider 为 acedatacloud，然后从可用列表选择模型。

接入配置里不必固定 model。把 Provider 与模型选择分开，可以减少切换模型时反复编辑 TOML 的成本。实际型号与可用范围会更新，应以 /model 和平台实时目录为准。

第六步：用最小请求验证

不要一开始就要求 Codex 重构整个仓库。先发送一个简单、可快速判断结果的请求，例如：

请概括当前项目的目录结构，不要修改任何文件。

随后打开 Ace Data Cloud Usage History，确认请求已经到达，并查看状态与消耗。

如果最小请求成功，再逐步尝试读取文件、生成修改方案、编辑代码和运行测试。

VS Code 配置要点

VS Code 扩展会读取同一份 ~/.codex/config.toml，但它能否看到 API Key 取决于扩展运行进程的环境。

配置后请完全退出并重新打开 VS Code。macOS / Linux 上，如果从图形界面启动后仍读取不到变量，可以从已经设置 Key 的终端运行：

code .

使用以下环境时，应在扩展实际运行的一侧配置变量：

  • Remote SSH：远程主机
  • WSL：WSL Linux 环境
  • Dev Container：容器环境
  • Codespaces 或类似远程环境：对应远端会话

只在本机 Shell 设置变量，不能保证远程扩展自动获得它。

Codex Desktop 配置要点

Desktop 与 CLI 共享配置文件，但图形应用不一定继承终端里临时执行的 export。

如果 Desktop 读取不到 Key：

  1. 将环境变量设置为长期或系统级
  2. 完全退出 Desktop
  3. 重新启动应用
  4. 再检查 Provider 和模型

常见报错排查

1. 401、Unauthorized 或 Incorrect API Key

检查顺序：

  1. API Key 是否复制完整
  2. 环境变量名是否为 ACEDATACLOUD_API_KEY
  3. 当前进程是否在设置变量之后启动
  4. auth.command 是否符合当前操作系统
  5. 凭证是否仍有效

不要把完整 Key 输出到日志或聊天中。可以用仅判断“是否存在”的方式检查变量。

macOS / Linux：

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell：

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Provider 没有变成 acedatacloud

确认配置文件路径和 TOML 层级。常见错误包括：

  • 文件名写成 config.toml.txt
  • 编辑了另一个用户目录
  • 表名拼写不一致
  • 引号或数组格式错误
  • 保存后没有重启客户端

3. Base URL 请求失败

确认地址是：

https://api.acedata.cloud/v1

不要漏掉 https:// 或末尾 /v1，也不要误用控制台页面地址。

4. CLI 能用，VS Code 不能用

这通常不是 Provider 配置问题，而是 VS Code 进程没有读取到环境变量。从已设置变量的终端启动 code .，或配置系统级变量后完全重启 VS Code。

5. WSL、SSH 或容器里读取不到 Key

环境变量需要设置在 Codex 或扩展真正运行的环境。Windows 主机上的 setx 不会自动写入 WSL；本机变量也不会自动传给远程 SSH 主机或容器。

6. 找不到想用的模型

不要手动猜测旧模型 ID。运行 /model 查看实时可选项，并检查应用权限、余额和当前 Provider。

7. 请求到达但无法完成复杂任务

先缩小任务范围：让 Codex只读分析、列计划，再逐步允许修改和测试。模型接入成功不代表所有仓库任务都应一次性完成；复杂变更仍需要明确的验收标准、测试和人工审查。

推荐的配置检查清单

在提交第一个正式任务前，逐项确认：

  • 已从应用列表获取有效 API Key
  • Key 保存在 ACEDATACLOUD_API_KEY
  • 没有把 Key 写入 Git 仓库
  • model_provider 为 acedatacloud
  • Base URL 为 https://api.acedata.cloud/v1
  • auth.command 与操作系统一致
  • 已完全重启 Codex 或 VS Code
  • /model 能看到 Provider 和模型
  • 最小测试请求成功
  • Usage History 中能看到对应调用记录

一个 Provider，减少重复配置

这套接入方式的重点并不是多写一段 TOML，而是建立稳定边界：

  • API Key 由环境变量管理
  • Provider 连接由 config.toml 管理
  • 模型在 Codex 内按任务选择
  • 调用记录和消耗在 Ace Data Cloud 控制台统一查看
  • CLI、Desktop 与 VS Code 共用一份配置

当认证、Provider 与模型选择被拆分清楚，许多“Codex 为什么又不能用”的问题就能快速定位，而不必反复登录、重装或复制多份配置。

打开 Codex 配置中心 查看不同客户端的官方指南，或前往 应用列表 获取 API Key。

参考资料