Skip to main content
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 教程，则应由 CC Switch 统一管理 requires_openai_auth = true 和 ~/.codex/auth.json；不要同时保留 env_key。混合两套配置可能让 Codex 读取错误或过期的 Token，最终返回 401。

​
申请流程

要使用 Codex CLI，首先可以到 Ace Data Cloud 控制台，获取您的 API Token，留作备用。 如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。 在首次申请时会有免费额度赠送，可以免费体验 Codex CLI 服务。

​
安装 Codex CLI

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

​
npm 安装（推荐）

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

​
Homebrew 安装（macOS）

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

​
检查安装

安装完成后，重新打开终端，然后检查命令是否可用：
如果提示 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：
其中 {token} 替换为您在 Ace Data Cloud 控制台复制的 API Token。 配置后重新打开终端，或执行对应的 source 命令让配置立即生效：

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

Codex CLI 使用 ~/.codex/config.toml 作为全局配置文件。如果该文件不存在，可以新建它：
把以下内容写入 ~/.codex/config.toml：
各字段说明如下：

​
清理已缓存的 OpenAI 登录

如果你之前已经用 OpenAI 官方账号登录过 Codex CLI，本地可能缓存了官方登录状态（通常保存在 ~/.codex/auth.json）。切换到 Ace Data Cloud 代理前，建议先清理一次旧登录：
如果 codex logout 命令不可用，也可以手动删除缓存文件：
如果你从未登录过 OpenAI 官方账号，可以跳过这一步。

​
启动会话

进入你的项目目录，然后启动 Codex CLI：
看到 Codex 的交互界面后，就可以直接输入需求，例如：

​
验证配置

进入 Codex CLI 后，可以在交互界面查看当前模型和模型提供方：
你应该能看到当前模型来自 acedatacloud 这个模型提供方，例如：
如果显示的模型提供方不是 acedatacloud，说明配置没有生效。请按下面顺序排查：
  1. 打开实际生效的 ~/.codex/config.toml，确认 model_provider = "acedatacloud" 与 [model_providers.acedatacloud] 逐字匹配；大小写也必须一致。
  2. 确认当前进程可以读取环境变量，但不要把 Token 打印到终端：
  3. 此方案不使用 ~/.codex/auth.json。如果该文件来自旧的官方登录或 CC Switch，先运行 codex logout，确认不再混用另一套认证来源。
  4. 完全退出并重新打开 Codex 和终端；VS Code 用户还需要执行 Developer: Reload Window 或完全重启 VS Code。
  5. 运行最小验证：
若仍返回 401，先核对 Token 是否复制完整；不要添加 X-Provider 等非标准 Header 覆盖。它们不是 Codex 自定义 provider 的通用必填配置，可能改变外部配置工具的路由行为。 你也可以通过 Ace Data Cloud 控制台 - 使用历史 查看请求记录和扣费详情，通过 Ace Data Cloud 控制台 - 应用列表 查看剩余额度。

​
工作原理

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 服务支持多种模型，常用包括： 如果想临时切换模型，可以在启动 Codex 时通过命令行参数指定：
也可以直接修改 ~/.codex/config.toml 中的 model 字段后重新启动。完整的模型列表可以参考 Ace Data Cloud OpenAI 服务文档。

​
输入图片

Codex 会根据实时 /v1/models 元数据判断当前模型能否接收图片。当前已经通过真实 Responses 请求验证图片输入的模型包括 gpt-5.4、gpt-5.5、gpt-5.6-luna、gpt-5.6-terra 和 gpt-5.6-sol。 使用 --image 可以在启动任务时附加本地图片：
如果 Codex 提示当前模型不支持图片，请先确认使用的是上面的已验证模型，再重新启动 Codex 以刷新模型元数据。图片能力会随模型更新，以实时模型列表为准。

​
项目信任级别

Codex CLI 支持为不同项目设置不同的信任级别，控制 Agent 可以执行哪些操作。可以在 ~/.codex/config.toml 末尾追加：
其中：
  • trusted：Agent 拥有完整权限，可以执行命令、修改文件。
  • untrusted：Agent 仅有受限权限，更适合不熟悉的项目。

​
了解更多