AI 编程 Agent Codex 完全入门指南：安装、配置 API Key 与上手实战

2026 年，AI 编程已经不是”能不能用”的问题，而是”怎么用好”的问题。

如果说 ChatGPT 是”代码顾问”，那么 OpenAI 发布的 Codex 就是”能进项目里干活的 AI 程序员”——它能读取你的项目文件、理解代码结构、自己修改代码、运行命令、排查报错，甚至生成测试和部署文档。很多开发者已经在用 Codex 把重复劳动交给 AI，自己专注在架构和业务上。

不过 Codex 的上手门槛比聊天式 AI 高一点：它需要安装、配置 API Key、接入模型服务，新手容易卡在前几步。这篇文章就是一份 Codex 完全入门指南：从 Codex 是什么、三种使用方式怎么选，到 Git/Node 准备、npm 安装、API Key 配置，再到新手最常见的五个坑，一次讲清楚。

Codex 是什么？和 ChatGPT、Cursor 有什么不一样？

Codex 是 OpenAI 推出的 AI 编程 Agent（代理）。官方的定位是：它可以在你指定的目录中读取、修改并运行代码。

跟普通聊天式 AI 的区别在于，Codex 不是”回答你的代码问题”，而是真正进入项目干活：读懂项目结构、定位问题、改代码、跑命令验证、把活干完再向你汇报。

它适合这些典型场景：新手快速看懂陌生项目、自动排查启动报错、修复 Bug、写前端页面和后端接口、检查代码质量与安全问题、生成 README/测试用例/部署文档、做项目重构与功能优化。对个人开发者和老牌站长来说，Codex 就是把”脏活累活”外包给 AI 的入口。

Codex 的四种使用方式：先选对再动手

Codex 目前主要有四种形态，功能侧重点不同，先想清楚自己要用哪种，再安装对应的那一种：

• Codex CLI：终端里进入项目目录运行 codex，最适合开发者与站长，能读当前项目并直接修改、运行代码；
• Codex App：桌面客户端，适合不喜欢命令行的新手，支持并行任务、worktree、自动化与 Git 集成；
• Codex IDE 插件：装在 VS Code / Cursor / Windsurf 里，融入日常写代码流程，边写边问；
• Codex Web：处理 GitHub 仓库任务，适合云端托管项目。

新手建议：想最快上手用 Codex App；想真实改项目用 Codex CLI；想处理 GitHub 仓库用 Codex Web；想日常写代码用 Codex IDE 插件。本文后面以最有代表性的 CLI 为例演示完整流程。

安装前准备：Git 和 Node.js 两个基础环境

在安装 Codex 之前，建议先准备好两个基础环境：Git 和 Node.js。Codex 处理项目、查看修改、配合 GitHub 或生成 diff 时经常会用到 Git；而 Codex CLI 通过 npm 安装，Node.js（v18.0 或更高版本）是运行前提。如果你的电脑已经装过这两个，可以直接跳到下一步。

新手建议：安装时一路 Next 保持默认路径，不要随便修改高级选项，避免后续环境变量出问题。

步骤 1：安装 Git

Windows 用户：访问 Git 官方下载页面，下载 Windows 版本安装包，安装时一路 Next、保持默认路径，不要修改高级选项。安装完成后打开 CMD 或 PowerShell，输入下面的命令验证：

git --version

如果能看到版本号，说明 Git 安装成功。

macOS 用户：macOS 通常自带 Git，也可以通过 Homebrew 安装：

brew install git

安装后同样运行 git --version 检查。

步骤 2：安装 Node.js

Codex CLI 通过 npm 安装，因此需要先安装 Node.js，建议安装 LTS 长期支持版本。Windows 上安装 Node.js 时同样不建议修改安装路径，默认路径最省心。

安装完成后，打开 CMD、PowerShell 或终端，输入：

node -v　npm -v

如果两个命令都能正常显示版本号，说明 Node.js 和 npm 已经安装成功。

安装 Codex CLI：一条 npm 命令

步骤 3：npm 全局安装 Codex

环境准备好以后，打开 CMD、PowerShell 或终端，执行：

npm install -g @openai/codex@latest

Windows 用户建议以管理员身份运行终端；macOS / Linux 用户如果遇到权限问题，可以尝试：

sudo npm install -g @openai/codex@latest

安装完成后，输入 codex --version，能看到版本号就说明 Codex CLI 安装成功。OpenAI 官方 GitHub 仓库也说明：Codex CLI 可以通过 npm 全局安装，安装后直接运行 codex 启动。

步骤 4：Windows 提示”找不到 codex 命令”怎么办？

这是新手最常见的问题。如果安装完成后输入 codex，提示 codex 不是内部或外部命令 或 command not found，可以依次尝试下面几个方法：

1. 重新打开终端：安装完成后关闭当前 CMD 或 PowerShell，重新打开一个新的终端窗口，再输入 codex --version；
2. 用 npx 临时启动：如果环境变量还没配置好，可以先用 npx @openai/codex 启动。这种方式不依赖全局命令，适合临时使用；
3. 检查 npm 全局路径：输入 npm config get prefix，检查 npm 全局安装路径是否已经加入 Windows 环境变量。如果你是新手，最简单的方法是重新安装 Node.js 并保持默认路径安装。

步骤 5：创建 .codex 配置目录

Codex 的配置文件放在用户主目录下的 .codex 文件夹中：

• Windows 路径：%USERPROFILE%\.codex，实际路径类似 C:\Users\你的用户名\.codex；
• macOS / Linux 路径：~/.codex。

如果没有 .codex 文件夹，就手动新建一个。Windows 用户可以在文件资源管理器里进入 C:\Users\你的用户名 新建文件夹 .codex；如果 Windows 提示”必须键入文件名”，可以用命令创建：

mkdir $env:USERPROFILE\.codex

步骤 6：配置 API Key 环境变量

Codex 的核心配置涉及两个文件：config.toml 和 auth.json，通过它们把请求地址和鉴权信息指向你的模型服务。接入需要编辑 ~/.codex/config.toml 并配置环境变量 OPENAI_API_KEY，请根据你的接入方式选择对应配置。

macOS：先在终端执行 echo $SHELL 查看默认 Shell 类型，然后按类型写入环境变量：

Zsh：
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc

Bash：
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile

接着执行 source ~/.zshrc（或 source ~/.bash_profile）使环境变量生效。

Windows CMD：运行以下命令设置环境变量：

setx OPENAI_API_KEY "YOUR_API_KEY"

打开一个新的 CMD 窗口，运行 echo %OPENAI_API_KEY% 检查环境变量是否生效。

Windows PowerShell：运行：

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", [EnvironmentVariableTarget]::User)

打开一个新的 PowerShell 窗口，运行 echo $env:OPENAI_API_KEY 检查环境变量是否生效。

步骤 7：编辑 config.toml（两种接入方式）

在 .codex 文件夹里新建 config.toml，写入对应接入方式的配置。

接入方式一：OpenAI 官方订阅 / Token Plan 个人版（模型支持 OpenAI Responses API 时，可使用最新版 Codex）。在 config.toml 中写入：

model_provider = "Model_Studio_Token_Plan_Personal"
model = "auto"
[model_providers.Model_Studio_Token_Plan_Personal]
name = "Model_Studio_Token_Plan_Personal"
base_url = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

然后配置模型元数据，以便在模型间切换：新建 ~/.codex/model-catalog.local.json，写入该套餐支持的模型列表。

接入方式二：通用聚合 / 平台接入点（使用自己平台的 API Key 和接口地址）。在 config.toml 中写入：

disable_response_storage = true
model = "你平台支持的模型名"
model_provider = "your_provider"
[model_providers.your_provider]
name = "你的平台名称"
base_url = "https://你的接口地址/v1"
wire_api = "responses"
requires_openai_auth = true

这里需要重点注意：base_url 必须替换成你自己的接口地址且结尾必须带 /v1；model 必须填写你平台支持的模型名称；model_provider 要和下方 [model_providers.xxx] 的名称一一对应。

几个核心参数的含义：disable_response_storage = true 表示尽量关闭响应存储，适合更注重隐私和业务安全的用户；model = "xxx" 表示 Codex 默认调用的模型，名称必须以你接入平台实际支持的模型为准；model_reasoning_effort 控制推理强度，model_verbosity 控制输出详细程度。

步骤 8：配置完后必做的验证

改完配置先运行 codex --version 确认安装无误，再进行一次最简单的对话（比如让 Codex 解释当前目录），确认能正常返回。如果报错，多半是 API Key 配错、模型名不对、或 API Key 配置的调用链路不通——这类问题九成出在”密钥环境变量没生效”或”接入端点拼写错误”上，对照官方接入文档逐行核对即可。

Codex 上手实战：它到底能帮你做什么？

装好配好之后，Codex 上手很简单：进入项目目录，运行 codex，然后用自然语言描述任务。实测中最常用的几类任务：

• 看懂陌生项目：”这个项目是干什么的？入口在哪？” Codex 会读结构、抓关键文件、给你讲明白；
• 修 Bug：”跑测试报了这个错，帮我定位并修复”——它会改完代码再跑一遍验证；
• 写功能：”给这个页面加一个搜索框”——直接产出可运行的代码片段；
• 出文档：”为这个模块生成 README 和测试用例”——批量生成结构化产出。

关键是任务描述越具体，Codex 的产出越可用：把”帮我优化一下”改成”把首页图片换成懒加载，保持现在的样式不变，并跑一遍构建确认没报错”，效果会好一个量级。

新手最常见的五个坑：Codex 安装与使用避坑清单

1. command not found：npm 全局 bin 不在 PATH，npm prefix -g 拿到路径后加进 PATH；
2. API Key 不生效：环境变量改了没 source / 新开终端没重新加载；macOS 记得 source ~/.zshrc，Windows 记得重开 CMD；
3. 调用一直超时或连接失败：接入端点 base_url 拼写错误，或本地 代理/网络配置没生效；先在浏览器确认 API 地址本身可访问，再排查终端里的网络出口；
4. Codex 在项目里乱改代码：重要项目先让 Codex 只”解释/出方案”（加 --plan 或明确”只改 x 文件”），并养成先 git commit 再让 AI 动手的习惯；
5. 模型名/Provider 填错：不同接入方式支持的 model 不一样，model = "auto" 最保险，或严格按你购买服务的文档填。

小提示：Codex 调 API 的网络底座，别等超时了才想起来

如果你的 Codex 接入的是海外模型服务（比如 OpenAI 官方 API），那调用链路稳不稳，很大程度取决于本机到 API 服务器的网络质量——丢包、抖动、出口 IP 被限流，都会让 Codex 时好时坏，表面上却像是”配置问题”。这类问题的根源往往在出口这一环：共享出口 IP 容易触发服务商限流，请求频繁超时，AI 工具自然用不顺。

不少开发者会给开发环境配一个稳定、干净的出口 IP来根治这类问题，比如 kookeey 住宅代理/静态代理：业务级清洗的独立出口，既能减少被 API 服务商限流和误伤的几率，也让 Codex、Cursor 这类 AI 编程工具的 API 调用更稳更顺。如果哪天 Codex 突然”变笨”、一直转圈不返回，先 ping 一下 API 接入点的连通性和延迟，多半能省下半小时的排错时间。

结语：Codex 值得花一个下午入门

Codex 的学习曲线其实很浅：准备 Git/Node → npm 安装 → 配 API Key → 跑起来，一个下午足够。真正拉开差距的是你会不会把任务描述清楚、敢不敢让 AI 进真实项目干活。建议从小项目开始，先让它做文档和测试，再逐步放手改业务代码。

安装或调用过程中如果遇到 连接超时、API 访问不稳定这类网络问题，可以检查本地网络链路与 API 接入点的连通性——稳定的出口环境是 AI 工具链顺不顺手的隐形基础。这篇文章如果对你有帮助，欢迎收藏转发，也欢迎在评论区交流你的 Codex 使用心得。