玩转 AI 编程：OpenAI Codex CLI 安装教程与自定义 API Key 配置全指南

OpenAI Codex 作为当前极具生产力的 AI 编程助手，目前官方主推 CLI（命令行界面）、IDE 扩展、App 三种交互形态。对于习惯在终端中沉浸式开发的工程师而言，Codex CLI 无疑是最顺手的工具。

本文将基于最新的官方文档，带你从零完成 Codex CLI 的安装，并重点梳理如何配置自定义 API 网关，让工具完美契合你的本地开发环境。

一、 认识 Codex CLI

Codex CLI 是 OpenAI 官方推出的开源本地编码代理，底层基于 Rust 构建。它能够直接在当前目录下读取代码上下文、修改文件甚至执行终端命令。

在身份认证方面，Codex 提供了极大的灵活性，支持两种登录方式：

1. ChatGPT 账号登录：适合普通用户，直接调用订阅权益。
2. OpenAI API Key 登录：适合企业级 CI/CD 集成、按量计费开发者，以及需要接入自定义 API 网关的进阶玩家（按 OpenAI Platform 标准 API 计费）。

二、 下载与环境安装

1. 推荐安装方式 (Node.js 环境)

官方首推使用 npm 全局安装，确保你的设备上已安装 Node.js：

npm i -g @openai/codex

如果是 macOS 用户，也可以直接使用 Homebrew 一键安装：

brew install --cask codex

提示： GitHub 官方仓库的 Release 页面也提供了各平台的二进制包，可根据需要手动下载配置环境变量。

2. 系统兼容性说明

• macOS / Linux：官方提供主流且稳定的支持。
• Windows：目前仍处于实验性阶段。强烈建议在 WSL (Windows Subsystem for Linux) 中安装 Node.js + npm 后再运行 CLI，或者直接使用原生 Codex App / VS Code 扩展。

三、 首次登录与认证

安装完成后，在终端输入 codex 即可启动。首次运行需要进行身份验证。

方式 1：ChatGPT 网页授权（默认）

直接运行 codex，CLI 默认会唤起浏览器进入 ChatGPT 登录流程。授权成功后，凭据会缓存在本地（~/.codex/auth.json），后续使用无需重复登录。

方式 2：API Key 环境变量注入（推荐开发者使用）

针对程序化工作流，提前注入 API Key 是更高效的做法。

Windows PowerShell 侧：

$env:OPENAI_API_KEY="你的OpenAI_API_Key"
codex

macOS / Linux 侧：

export OPENAI_API_KEY="你的OpenAI_API_Key"
codex

(注：你也可以随时使用 codex login 命令，通过管道传入 API Key 或切换设备授权模式。)

四、 基础命令与开发场景

Codex CLI 并非只能单纯对话，它的核心价值在于“动作执行”。

最简启动与任务下发：
你可以直接进入交互模式，或者在启动时直接带上指令：

codex "Explain this codebase to me"
codex "帮我分析当前项目的目录结构"

核心能力清单：

• 📁 读取并解析复杂项目代码
• 📝 自动化修改并保存文件
• 💻 执行终端命令与脚本化工作流 (codex exec)
• 🔍 代码审查与 Web 搜索补全上下文
• ⚡ 连接 MCP（Model Context Protocol）

五、 进阶：配置文件与自定义 API 接入

这是国内开发者和企业用户最关心的部分。Codex 的核心配置文件位于：~/.codex/config.toml。CLI 和 IDE 扩展共用这一套配置。

如果你需要将 Codex 接入自建网关、第三方聚合 API（如 uiuiAPI），可以通过修改该文件实现。官方支持配置 base_url、env_key、http_headers 等关键字段。

以下提供三种最常见的直连与中转配置方案，可直接复制使用：

方案 A：极简模式 —— 仅覆盖默认 Base URL

如果你只是想把官方 OpenAI 的请求代理到自定义地址，可以直接覆盖内置的 openai_base_url。

~/.codex/config.toml 配置：

model = "gpt-5.4"
model_provider = "openai"

openai_base_url = "https://sg.uiuiapi.com/v1"

API_KEY 配置

1.文件配置~/.codex/auth.json 配置示例：

{
  "OPENAI_API_KEY": "输入在uiuiapi获取的sk-dxxxxxxxxxxxxxxxx"
}

2.运行环境：

export OPENAI_API_KEY="你的代理网关Key"
codex

方案 B：专业模式 —— 自定义 Provider（强烈推荐）

为了配置的清晰和后续切换的便利，官方更推荐新建一个独立的 Provider 节点。

~/.codex/config.toml 配置：

model = "gpt-5.4"
model_provider = "myproxy"

[model_providers.myproxy]
name = "My Proxy"
base_url = "https://sg.uiuiapi.com/v1"
wire_api = "responses"
env_key = "MY_PROXY_API_KEY"
env_key_instructions = "启动前请先设置环境变量 MY_PROXY_API_KEY"

运行环境：

export MY_PROXY_API_KEY="你的代理网关Key"
codex

六、 Windows 环境特殊避坑指南

如前所述，Windows 原生环境目前在支持上仍有局限。但官方已在 CLI 中加入了 Windows 沙箱模式（分 elevated 提权和 unelevated 非提权两种）。

如果你坚持在原生 Windows（非 WSL）下使用，建议在 config.toml 中强制开启提权沙箱模式以提升文件操作的稳定性：

[windows]
sandbox = "elevated"

七、 常见问题排查 (FAQ)

Q1：安装完成后提示 codex: command not found？

• 排查： 通常是因为 npm 全局安装的 bin 目录没有加入到系统的环境变量 PATH 中。可通过 npm config get prefix 查找路径并手动配置。

Q2：自定义 API 配置后不生效或请求报错？

1. 检查 config.toml 路径是否正确（用户级为 ~/.codex/config.toml，项目级为项目根目录下的 .codex/config.toml）。
2. 确认网关服务是否完全兼容 OpenAI 协议规范（目前官方 wire_api 要求支持 responses）。
3. 核对环境变量名是否与 config.toml 中的 env_key 字段完全一致。

Q3：ChatGPT 登录与 API Key 登录有何本质区别？

• ChatGPT 登录消耗的是你网页版账号的订阅额度与调用次数。
• API Key 登录则严格走 Developer Platform 的 API 计费体系，两者账单和配额独立计算。

八、 总结

OpenAI Codex 正在重塑开发者的工作流。通过合理配置 config.toml 和环境变量，我们完全可以打造一个兼顾网络稳定性与数据隐私的个人 AI 编程环境。建议优先采用自定义 Provider (方案 B) 的形式接入 API，这不仅能让配置文件更加语义化，也能在多个服务商之间实现秒级切换。