Codex CLI 终端使用教程

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

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

本文使用 env_key = "ACEDATACLOUD_API_KEY"，Token 只从环境变量读取。不要同时启用 requires_openai_auth 或保留 ~/.codex/auth.json 中的旧登录凭据，否则 Codex 可能读取错误或过期的 Token 并返回 401。

申请流程

要使用 Codex CLI，首先可以到 Fishapi Cloud 控制台，获取您的 API Token，留作备用。

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

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

安装 Codex CLI

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

npm 安装（推荐）

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

npm install -g @openai/codex

Homebrew 安装（macOS）

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

brew install --cask codex

检查安装

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

codex --version

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

配置 Codex CLI

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

第一步：设置环境变量

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

export ACEDATACLOUD_API_KEY="{token}"

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

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

source ~/.zshrc

第二步：编辑 Codex 配置文件

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

mkdir -p ~/.codex
touch ~/.codex/config.toml

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

model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.fishapi.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 Fishapi 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）。切换到 Fishapi Cloud 代理前，建议先清理一次旧登录：

codex logout

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

rm -f ~/.codex/auth.json

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

启动会话

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

cd /path/to/your/project
codex

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

解释这个项目的目录结构

验证配置

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

/model

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

Model: gpt-5
Provider: acedatacloud

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

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

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

    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. 运行最小验证：

    codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK" < /dev/null

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

你也可以通过 Fishapi Cloud 控制台 - 使用历史 查看请求记录和扣费详情，通过 Fishapi Cloud 控制台 - 应用列表 查看剩余额度。

工作原理

Codex CLI 原生使用 OpenAI Responses API 协议。Fishapi Cloud 在 https://api.fishapi.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.fishapi.cloud/v1/responses。
  4. Fishapi Cloud 使用您的 API Token 验证身份、检查额度，并把请求转发到可用的目标模型服务。
  5. 请求完成后，平台根据实际使用量记录用量并扣减额度。

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

配置模型

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

模型 说明
gpt-5 推荐默认模型，适合大多数编码任务
gpt-5-mini 更轻量、响应更快，适合简单任务
gpt-6-astra 最新旗舰，最复杂的端到端推理与编程任务首选
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 时通过命令行参数指定：

codex --model gpt-5-mini

也可以直接修改 ~/.codex/config.toml 中的 model 字段后重新启动。完整的模型列表可以参考 Fishapi 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 --model gpt-6-astra --image ./screenshot.png "读取图片中的报错并修复问题"

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

项目信任级别

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

[projects."/path/to/trusted/project"]
trust_level = "trusted"

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

其中：

  • trusted：Agent 拥有完整权限，可以执行命令、修改文件。
  • untrusted：Agent 仅允许读取和分析，更适合不熟悉的项目。

了解更多