Codex CLI

概览

Codex CLI 是 OpenAI 官方推出的命令行工具，专为终端中的代码任务设计。与通用聊天工具相比，它更侧重于工程化的输出，能生成更清晰、可直接落地的代码改动。通过将 Codex CLI 与 Z-Mint AI API 集成，你可以借助一个统一的 OpenAI 兼容接口，仅需一个 Key 与一个 base URL，即可访问 Z-Mint AI 提供的各类模型（如 GPT 系列）。

前置条件

在开始配置之前，请确保你已准备好：

1. 安装 Node.js 和 npm

为什么需要？ Node.js 是 CLI 工具的运行环境（就像在手机上安装微信才能聊天一样，你需要在电脑上安装 Node.js 才能运行 CLI 工具）。如果已安装： 运行 node -v 与 npm -v 查看版本，若为 v20+ 则可跳过此步骤。首次安装：

• 前往 Node.js 官方网站 下载并安装（推荐 LTS 版本）
• 如果你不熟悉安装流程，可参考 菜鸟教程 - Node.js 安装指南
• 推荐使用 Node.js v20 或更高版本
• 验证安装：

node -v
npm -v

2. 获取 Z-Mint AI API Key

• 登录 Z-Mint AI 控制台
• 在控制台找到 API Keys，点击「创建新 Key」按钮，然后复制生成的 Key
• API Key 通常以 sk- 开头

第 1 步：安装 Codex CLI

提示： 如果你不知道如何打开命令行终端，请参考 常见问题 - 如何打开命令行终端

1. 全局安装

npm install -g @openai/codex

预期结果： 终端滚动显示下载信息，最后输出 added XX packages（耗时约 1–3 分钟）。如果出现错误： 提示 permission denied 时，Windows 需以「管理员身份运行」PowerShell，macOS/Linux 则在命令前加上 sudo。

2. 验证安装

codex --version

成功标志： 显示版本号（如 1.x.x）。

第 2 步：配置 Z-Mint AI API

Codex CLI 支持通过配置文件自定义 Provider，无需修改源代码。

• 方法一：图形界面操作
• 方法二：一条命令快速创建

1. 打开配置目录

• Windows
• macOS
• Linux

按下 Win + R，粘贴以下内容后回车，即可打开 Codex 的配置目录：

%userprofile%\.codex

在 Finder 中按下 Command + Shift + G，粘贴以下路径后回车：

~/.codex

在文件管理器中访问配置目录：

~/.codex

2. 编辑 config.toml

在配置目录中找到 config.toml 文件，并写入以下内容：

model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "zmint"

[model_providers.zmint]
name = "Z-Mint AI API"
base_url = "https://aigc.zhengmi.org/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

⚠️ 注意事项：

• 完整复制，不要遗漏任何符号
• 将 "your-zmint-api-key" 替换为实际的 API Key
• TOML 格式对缩进和符号非常敏感

<!--THE END-->

• Windows PowerShell
• macOS / Linux

@"
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "zmint"

[model_providers.zmint]
name = "Z-Mint AI API"
base_url = "https://aigc.zhengmi.org/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
"@ | Out-File -FilePath "$env:USERPROFILE\.codex\config.toml" -Encoding utf8

cat > ~/.codex/config.toml << 'EOF'
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "zmint"

[model_providers.zmint]
name = "Z-Mint AI API"
base_url = "https://aigc.zhengmi.org/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
EOF

执行命令后，配置文件会被自动创建并写入内容。

model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "zmint"

[model_providers.zmint]
name = "Z-Mint AI API"
base_url = "https://aigc.zhengmi.org/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

配置字段说明：

• model：默认使用的模型名称
• model_reasoning_effort：推理深度（可按需调整）
• model_provider：服务商名称，需与下方 section 保持一致
• base_url：Z-Mint AI API 接入地址
• env_key：用于存放 API Key 的环境变量名
• wire_api：必须设置为 responses

2. 配置 API Key

• Windows PowerShell
• macOS / Linux

临时生效（仅当前会话）

$env:OPENAI_API_KEY = "your-zmint-api-key"

永久生效

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-zmint-api-key", "User")

重启终端后生效。验证配置

echo $env:OPENAI_API_KEY

如果输出的是你的 API Key，则说明配置成功。

临时生效（仅当前会话）

export OPENAI_API_KEY="your-zmint-api-key"

永久生效 编辑 ~/.bashrc 或 ~/.zshrc，添加：

export OPENAI_API_KEY="your-zmint-api-key"

然后执行 source ~/.bashrc 或 source ~/.zshrc 让其生效，或直接重启终端。验证配置

echo $OPENAI_API_KEY

如果输出的是你的 API Key，则说明配置成功。

第 3 步：开始使用 Codex CLI

1. 进入工作目录

cd your-working-directory

注意： 请将 your-working-directory 替换为实际的路径

2. 交互模式

codex

3. 验证配置

codex "Who are you"

成功标志：

• 看到 AI 返回的回复文本（数行内容）
• 没有 401、403、API Key invalid 等错误

如果出现错误：

• 401 Unauthorized：API Key 未设置或无效 → 检查环境变量
• 403 Forbidden：API Key 权限不足 → 核对 API Key
• Network error：网络异常 → 检查网络连接

常见问题

1. Codex CLI 是什么？能做什么？

Codex CLI 是 OpenAI 官方推出的命令行工具，专注于代码相关任务。它强调工程化输出，能生成更清晰、可直接落地的代码改动。

2. 第一次使用时如何验证安装和配置？

请依次执行以下命令：

• node -v 与 npm -v：确认 Node.js 和 npm 已安装
• codex --version：确认 Codex CLI 已安装
• codex "Who are you"：确认 API 配置正确

3. 交互模式与单条命令模式有什么区别？

• 交互模式：执行 codex 进入连续对话，可进行多轮交互
• 单条命令模式：执行 codex "问题内容"，获得一次响应后直接退出

4. Codex CLI 会自动读取或上传我本地的文件和代码吗？

不会。Codex CLI 只在你明确引用或授权时才会读取文件内容。建议在专门的项目文件夹中使用。

5. 如何使用 Codex CLI 分析本地文件内容？

在交互模式下，可以通过以下方式引用文件：

• 输入文件路径，让 Codex 读取
• 将文件拖入终端窗口
• 直接复制粘贴文件内容

6. Codex CLI 支持中文输入和输出吗？

支持，完全可用。

7. 执行后没有任何输出，可能是什么原因？

常见原因包括：

• 网络连接异常
• API Key 无效或余额不足
• base_url 配置不正确
• 防火墙或代理拦截了请求

8. 为什么我的配置修改没有生效？

• 重启终端

• 检查 config.toml 语法（TOML 格式）

• 确认配置文件路径：

  • Windows：C:\Users\{username}\.codex\config.toml
  • macOS / Linux：~/.codex/config.toml

9. 401/403 错误是什么原因？

• 401 错误：OPENAI_API_KEY 未设置或无效
• 403 错误：权限不足或 Key 已过期
• 检查 env_key 是否与你的环境变量名一致

10. Codex CLI 适合哪些使用场景？

适合：

• 代码编写、调试与重构
• 命令行环境下的快速问答
• 文件内容分析

不适合：

• 复杂的图形界面交互
• 实时协同编辑

11. 如何切换模型？

打开配置文件 config.toml（位于 ~/.codex/config.toml 或 C:\Users\{username}\.codex\config.toml），修改 model 字段：

model = "gpt-5.2"  # 改为你希望使用的模型名称

保存文件后重启 Codex CLI 即可生效。

12. 如何上传图片？

• 方式一：引用图片路径
• 方式二：将图片拖入终端
• 方式三：直接粘贴图片

以上方式均需用户主动操作，Codex CLI 不会自动读取或上传本地图片。

13. 如何打开命令行终端？

• Windows
• macOS
• Linux

<!--THE END-->

• 方式一：按 Win + R，输入 cmd 或 powershell 后回车
• 方式二：在开始菜单中搜索「命令提示符」或「PowerShell」
• 方式三：在文件夹中按住 Shift 并右键，选择「在此处打开 PowerShell 窗口」

<!--THE END-->

• 方式一：按 Command + Space 打开 Spotlight，输入 Terminal 后回车
• 方式二：进入「应用程序」→「实用工具」→「终端」

<!--THE END-->

• 方式一：按下 Ctrl + Alt + T 快捷键
• 方式二：在应用菜单中搜索「终端」

注意事项

请在专门的项目文件夹中运行 Codex CLI，避免在敏感目录（如系统目录或包含凭据的目录）中运行。Codex CLI 会基于当前工作目录进行操作。

配置中的 wire_api 必须设置为 "responses"，"chat" 已被弃用。