当前位置：首页 > news >正文

手把手教你配置 OpenAI Codex CLI：API Key 获取 + 自定义 base_url 保姆级指南

news 2026/6/2 1:07:19

OpenAI Codex CLI 是官方推出的本地编码代理工具，能在你当前目录里读取代码、修改文件、执行命令，还支持子代理并行处理复杂任务。它开源、基于 Rust 实现，性能出色，已成为很多开发者终端里的 AI 编程主力。

Codex 目前主要有 CLI、IDE 扩展、App 三种形态，其中 CLI 是终端用户最常用的形态。本文按官方最新文档整理，带你从零完成安装、登录、基础使用，并重点解决自定义 API 配置难题（包括中转代理、Azure OpenAI 等）。所有命令和配置均可直接复制粘贴。

一、Codex CLI 是什么

Codex CLI 支持两种登录方式：

ChatGPT 账号登录：直接使用你的 ChatGPT 订阅权益，适合日常交互。
OpenAI API Key 登录：按量计费，适合自动化、CI/CD 或自定义 API 网关场景。

官方明确说明，CLI 和 IDE 扩展都支持这两种方式。使用 API Key 时，按 OpenAI Platform 标准计费。

二、下载安装

系统支持情况

macOS、Linux：官方主流支持，体验最佳。
Windows：目前为实验性支持。建议优先使用 WSL 或直接安装 Codex App / VS Code 扩展。

Windows 用户推荐方案：

方案 A：直接安装 Codex App（最稳）。
方案 B：在 WSL 中安装 Node.js + npm 后再装 CLI。
方案 C：在 VS Code 中安装 Codex 扩展。

三、首次登录

方式 1：ChatGPT 登录（推荐普通用户）

直接运行codex，CLI 会自动打开浏览器完成 OAuth 授权。登录成功后凭据会被缓存，下次启动无需重复操作。

方式 2：OpenAI API Key 登录（推荐自动化场景）

先设置环境变量：

macOS / Linux：

exportOPENAI_API_KEY="sk-你的OpenAI_API_Key"

Windows PowerShell：

$env:OPENAI_API_KEY="sk-你的OpenAI_API_Key"

然后运行codex即可。也可使用codex login命令显式登录，支持 device auth 或通过 stdin 传入 Key。

四、基础使用

最简单启动方式：

codex

或直接带初始任务：

codex"帮我分析这个项目结构"

Codex 核心能力包括：

读取并解释整个代码库
自动修改文件
执行 shell 命令
代码审查与重构
子代理并行处理
Web 搜索、MCP 连接等

常用命令快速上手：

codex—— 进入交互模式
codex "你的指令"—— 一次性任务
codex login/codex logout—— 管理登录

更多参数可在官方 CLI reference 中查看（如审批策略、目录切换、profile 等）。

五、配置文件详解

Codex 用户级配置文件默认位于：

~/.codex/config.toml

项目级配置放在当前目录下的.codex/config.toml，优先级更高。

配置文件优先级（从高到低）：

命令行 flags / --config
profile
项目级 .codex/config.toml
用户级 ~/.codex/config.toml
系统级配置
内置默认值

CLI 与 IDE 扩展共用同一套配置体系。

六、自定义 API 配置（最实用部分）

官方已完整支持自定义 provider 和 base_url，你可以轻松接入自建网关、第三方中转（uiuiAPI）、Azure OpenAI或企业内部代理。

方案 A：仅修改 OpenAI 内置 base_url（简单直连）

model = "gpt-5.4" model_provider = "openai" openai_base_url = "https://uiuiapi.com/v1"

再设置环境变量OPENAI_API_KEY即可。

API_KEY 配置

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

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

2.运行环境：

exportOPENAI_API_KEY="你的代理网关Key"codex

方案 B：自定义 Provider（推荐，切换更灵活）

model = "gpt-5.4" model_provider = "myproxy" [model_providers.myproxy] name = "My Proxy" base_url = "https://uiuiapi.com/v1" wire_api = "responses" env_key = "MY_PROXY_API_KEY" env_key_instructions = "请先设置环境变量 MY_PROXY_API_KEY"

环境变量设置：

macOS / Linux：

exportMY_PROXY_API_KEY="sk-你的Key"

Windows PowerShell：

$env:MY_PROXY_API_KEY="sk-你的Key"

方案 C：Azure OpenAI 示例

[model_providers.azure] name = "Azure" base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai" wire_api = "responses" query_params = { api-version = "2025-04-01-preview" } env_key = "AZURE_OPENAI_API_KEY"

方案 D：通过 OpenAI 认证走代理

[model_providers.mygateway] name = "My Gateway" base_url = "https://uiuiapi.com/v1" wire_api = "responses" requires_openai_auth = true

此时忽略 env_key，仍使用 OpenAI 认证，非常适合“后端仍是 OpenAI 但走代理”的场景。

七、Windows 用户特别注意

Windows 原生支持已逐步完善，可在 config.toml 中开启沙箱模式：

[windows] sandbox = "elevated"

若 CLI 不稳定，仍推荐优先使用 Codex App 或 WSL。

八、常见问题排查

codex 命令不存在：检查 Node.js / npm 版本，并确认全局安装目录已加入 PATH。
自定义配置不生效：确认 config.toml 路径正确、model_provider 名称匹配、base_url 完整、环境变量名与 env_key 一致，且服务兼容responses协议。
登录方式区别：ChatGPT 登录走订阅体系，API Key 走按量计费；部分依赖 ChatGPT credits 的功能仅 ChatGPT 登录可用。
认证凭据位置：缓存在~/.codex/auth.json或系统凭据存储，可通过配置控制。

九、实用建议

如果你主要使用自定义中转 API，强烈推荐方案 B（自定义 Provider），配置清晰，后续切换官方也只需改一行。

最简可直接抄配置（自定义中转示例）：

model = "gpt-5.4" model_provider = "myproxy" [model_providers.myproxy] name = "My Proxy" base_url = "https://uiuiapi.com/v1" wire_api = "responses" env_key = "MY_PROXY_API_KEY"

设置环境变量后运行codex即可。

掌握以上内容，你已经可以把 Codex CLI 变成自己专属的高效 AI 编码助手。实际使用中建议先在测试项目里多尝试，熟悉审批流程后再用于生产代码。