OpenAI Codex安装配置中转API超详细教程 AI编程工具Codex实战配置文件常见错误总结

Wed, 17 Jun 2026 15:30:00 +0800

在现代软件开发中，代码规模越来越大、技术栈越来越复杂，开发者花在“理解代码、改动代码、反复验证”的时间，往往远多于真正写新功能的时间。为了解决这一问题，Codex 应运而生。

Codex（Codex CLI） 是一个运行在终端中的 AI 编程助手。与普通聊天式 AI 不同，它可以直接读取你的项目代码、理解文件结构，在你的确认下修改源码、执行命令，并一步步完成真实的开发任务。你可以把它理解为一个“懂代码、会动手、但始终受你控制的编程搭档”。

在本文中，你将从零开始学习 Codex 的安装、配置与实际使用方法，包括如何接入第三方 API、如何在终端和 VS Code 中高效使用，以及遇到常见问题时如何快速排查。即使你从未使用过类似工具，也可以按照本文一步步完成配置，并真正把 Codex 用到你的日常开发中。

安装前准备（所有系统通用）

Node.js 22+
npm 10+
稳定网络连接

Windows 额外注意：OpenAI 官方也提到 Windows 支持偏“实验性”，更稳的方式是用 WSL 环境；

安装 Codex CLI

Windows

安装 Git Bash（按安装向导一直下一步即可）。
安装 Node.js（建议装最新 LTS）。
安装 Codex CLI（在 CMD / PowerShell 里执行）：

npm install -g @openai/codex

验证：

codex --version

macOS

npm install -g @openai/codex
codex --version

必要时加 sudo。

OpenAI 官方也提供了 Homebrew 安装方式（可选）：brew install codex。

Linux

1）先装 Node.js / npm（不同发行版命令不同）。

2）安装与验证：

sudo npm install -g @openai/codex
codex --version

配置中转API作为第三方API

Codex CLI 会读取你的配置文件：一般在 ~/.codex/（Windows 也是用户目录下的 .codex）。创建两份文件：

auth.json：放密钥
config.toml：放模型与网关配置

Windows 配置路径与文件

1）进入用户目录的 .codex（示例：C:\Users\Administrator.codex）。如果看不到，先在资源管理器开启“显示隐藏项目”。

2）没有就手动创建 .codex 文件夹，并创建：

auth.json
config.toml

auth.json（把 sk-xxx 换成你的中转API Key）

{"OPENAI_API_KEY": "sk-xxx"}

config.toml（把 base_url 换成你的中转地址）

model_provider = "whatai"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.whatai]
name = "whatai"
base_url = "https://api.whatai.cc/v1"
wire_api = "responses"

macOS / Linux 配置命令

创建文件：

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

编辑 auth.json（粘贴同样的 JSON）与 config.toml。要保证上下一致：model_provider = “xxx” 要和 [model_providers.xxx] 的段名一致。

配置改完一定要“重启终端”

关闭终端/重启终端后再启动 codex，让配置生效。

启动与基本使用（终端）

进入你的项目目录：

cd your-project-folder
codex

你也可以直接在命令后跟一个初始任务，例如让它先解释仓库结构：

codex "Explain this codebase to me"

交互技巧：Slash 命令与快捷操作

在 Codex 交互界面里，输入 / 可以打开 slash 命令菜单，用来切换模型、调整权限、总结对话等。

一些常见命令（示例来源于体验分享与官方说明思路一致）：

/status：查看当前会话配置/状态
/new：开新会话（清空上下文）
/model：切换模型
/init：初始化一些模板/设置（视版本而定）

另外，很多版本支持用 ! 直接跑终端命令（例如 !git status / !ls），能减少你“让模型代跑命令”的成本。

VS Code插件Codex

流程是：完成上述 .codex 配置后，在 VS Code 扩展商店搜索并安装 codex，安装后会出现在侧边栏。

OpenAI 官方 quickstart 也提到：安装后 Codex 面板会出现在侧边栏（有时在折叠区）。

常见问题（FAQ）与排查清单

Q1：codex: command not found 找不到命令

原因常见是 npm 全局安装路径没加入 PATH，或安装没成功。

先运行 codex –version 验证是否安装成功。
重新安装：npm install -g @openai/codex

Q2：Linux/macOS 安装时报权限错误（EACCES）

用 sudo npm install -g @openai/codex（Linux 写法）。

（更长期的做法是把 npm 全局目录改到用户目录，但这属于通用 Node/npm 运维，不是 Codex 专属。）

Q3：Windows 找不到 .codex文件夹

提醒：需要在资源管理器里打开“显示隐藏的项目”，因为 .codex 是隐藏目录风格。

Q4：配置了 Key 但仍提示未认证 / 401

确认两点：

1）auth.json 内容必须是：

{"OPENAI_API_KEY": "sk-xxx"}

2）重启终端后再运行 codex。

Q5：一直连不上 / 超时 / 网络错误

检查 base_url 是否完全一致
公司/校园网络可能需要代理或放行相关域名（这是网络环境问题，不是 Codex 本身）。

Q6：模型不可用 / 报 model not found

先用提供的模型名：gpt-5.2-codex。

如果你在中转API模型列表看到的名称不同，就要以实际可用模型为准（模型名不匹配会直接失败）。

Q7：config.toml写了但好像没生效

最常见原因：

model_provider = “X” 和 [model_providers.X] 名字不一致（比如一个写 whatai，另一个写 api111）。whatai的不同系统示例里名字确实不一样，所以你改的时候要保持一致。
忘记重启终端。

Q8：怎么升级 / 更新 Codex CLI？

OpenAI 官方给的升级方式是：

npm i -g @openai/codex@latest

Q9：有哪些命令行参数/高级配置可以查？

命令与 flag 参考：官方提供了“command line options”参考页，并说明 CLI 默认从 ~/.codex/config.toml 读取配置，也支持用 -c key=value 临时覆盖。
配置字段的完整参考：官方也有 config reference 页面。

OpenAI on Leuの小站