Codex CLI 安装与使用教程：从环境配置到跑通第一个任务

过去两年，AI 编程助手经历了一轮明显分化：最早大家用的是“聊天式补全”，比如在 IDE 里让 AI 写一个函数、补一段注释；后来 Cursor、Copilot 把“对话生成代码”做成了主流交互。但很多人会碰到同一个尴尬局面——AI 帮你在编辑器里写了代码，却没人负责把它跑起来。依赖装没装、环境变量配没配、测试过没过，仍然是开发者自己兜底。

Codex 之所以值得单独写一篇安装使用教程，是因为它换了一个思路：不再只是“写代码的工具”，而是直接住进你的终端，以 Agent 的方式把任务拆解、执行、验证完整走完。换句话说，它的重点不是“生成一段代码给你看”，而是“直接把活干完给你看”。

这篇文章会从零开始，带你完成 Codex 的环境检查、安装、登录认证、任务跑通和问题排查。目标是让你在十分钟内完成安装，并理解它背后的工作方式。无论你是第一次听说 Codex，还是已经在用但被各种报错卡住，这篇文章都可以当作一份可收藏的落地手册。

1. 这篇文章真正要解决的问题

很多开发者第一次听到 Codex，第一反应是“又一个 AI 写代码工具”。这个判断不算错，但会低估它的定位差异。如果只把它当作聊天窗口用，你很难理解为什么安装完 CLI 之后，还要关心 PATH 路径、模型配置、本地代理这些事。

Codex 真正解决的问题，是“从代码生成到任务完成”之间的那一段空白。

传统 AI 编程助手的流程通常是：你在对话框里描述需求，AI 给你一段代码，你手动复制到项目里，然后自己处理依赖、运行、报错、修复。这个流程里，AI 只参与了“写代码”这一个环节，剩下的脏活累活仍然是人来干。而 Codex 的设计目标是让 Agent 直接进入终端环境，读取项目结构，执行命令，观察结果，再根据结果决定下一步动作。开发者要做的是给出目标，然后在关键节点做确认。

这意味着它解决的痛点不是“少打字”，而是“少切换上下文”。你不需要在 IDE、终端、浏览器文档之间来回跳，因为 Agent 可以在同一个环境里完成文件修改、命令执行和结果检查。

什么人最应该读这篇文章？

• 正在使用 Cursor 或 Copilot，但对“AI 写代码但不管运行结果”感到不满的开发者。
• 想尝试终端型 AI Agent，但不知道从哪开始、环境怎么配的新手。
• 已经安装过 Codex，但遇到unable to locate the codex cli binary、本地代理报错、模型不支持等问题的用户。
• 团队里想统一 AI 编程工具链，需要一份可复用配置模板的工程负责人。

一句话总结本文判断：Codex 的安装门槛并不高，真正容易踩坑的地方集中在“CLI 路径”、“认证方式”和“模型配置”这三件事上。把这三件事理顺，十分钟跑通完全可行。

2. 认识 Codex：它不是又一个代码补全插件

2.1 Codex 与 IDE 插件的本质区别

在看安装步骤之前，有必要先搞清楚 Codex 的定位。

Codex 是一个以终端为交互界面的编程 Agent。它由 OpenAI 开发，核心能力不是“根据上文补全下一个 token”，而是“接收一个任务，调用工具，完成任务”。这意味着它内部有一套循环机制：理解任务 -> 规划步骤 -> 执行命令或修改文件 -> 查看输出 -> 判断是否完成 -> 必要时修正再试。

这个循环在技术上通常被称为 Agent Loop 或者 Harness。你在网上搜 Codex 时经常看到codex harness这个词，它指的就是这套“驱动模型执行任务”的工程框架。

作为对比，传统 IDE 插件更接近“结对编程的副驾驶”，你在主驾，它在副驾，你决定什么时候用它的建议。Codex 更接近“临时交给一个实习生去跑腿”，你给目标，它自己探索、试错、汇报结果。当然，最终控制权还在你手里，因为它执行关键操作时通常会请求确认。

2.2 和其他 AI 编程工具的对比

这个对比不是为了说谁更好，而是为了说明使用前提。Codex 能“干活”，前提是它能看到你的环境、命令输出和文件系统。所以安装它时，路径配置、环境变量、工作目录权限这些问题会比普通插件更敏感。

2.3 为什么选择 CLI 形态

你可能会疑问：为什么 Codex 不直接做成 IDE 插件，而要先推 CLI？

原因之一是，很多开发任务的根本载体就是终端。装依赖、跑测试、看日志、启动服务，这些动作在 IDE 里也能做，但终端才是那个“不会被 UI 美化掩盖真相”的地方。Agent 要真正验证自己的代码是否可用，最好的方式就是直接在终端里执行命令，读取真实输出。

另一个原因是工程化需要。CLI 形态更容易接入 CI/CD 流程，也更容易被脚本化调用。团队可以把 Codex 配置写进仓库，让所有成员使用一致的模型和权限策略。这种可编程、可集成的特性，是纯 IDE 插件很难提供的。

3. 环境准备：安装前需要检查的三件事

在安装 Codex 之前，建议先确认本机环境是否满足要求。从大量用户反馈看，很多报错并不是 Codex 本身的问题，而是环境里缺少依赖或者 PATH 没有配好。

3.1 Node.js 与 npm

Codex CLI 作为一款以 Node.js 生态发布的命令行工具，本机需要能正常使用 npm。请注意，这里的“正常使用”不只是能执行npm -v，更重要的是 npm 全局安装目录是否在系统的 PATH 中。

建议执行下面三个命令确认：

node -v npm -v which npm

如果node或npm提示找不到命令，说明 Node.js 没有安装，或者没有加入环境变量。建议先安装 Node.js LTS 版本，然后重新打开终端验证。

部分用户在安装 Node.js 时选择的是压缩包解压方式，没有自动配置环境变量。这种情况下命令行工具能找到 node，但不一定能找到 npm 全局安装的二进制文件。处理方式是手动把 npm 的全局 bin 目录加入 PATH，具体路径因系统而异，后面会在常见问题里再讲。

3.2 Git

Codex 在执行任务时，经常需要读取 Git 仓库状态、查看 diff、创建提交。如果你的项目不是 Git 仓库，很多功能会受限。

验证方式：

git --version

如果没有安装 Git，需要先安装并配置好基础的用户名和邮箱。Codex 生成提交信息时依赖 Git 配置，建议提前设置：

git config --global user.name "your name" git config --global user.email "your email"

3.3 终端环境

Codex 是一个终端工具，Windows 用户建议使用 PowerShell 或 Windows Terminal，macOS 用户建议使用 iTerm2 或系统自带终端，Linux 用户使用主流 shell 即可。

这里要特别提醒：如果你平时使用代理工具访问各类服务，需要注意 Codex 请求 OpenAI 接口时也可能走代理，而代理配置不当会直接导致请求失败。网上常见的报错cc switch local proxy failed while handling codex endpoint就属于这类问题。后面我们会在环境变量部分详细讲代理的正确处理方式。

4. 安装 Codex CLI：三种方式对比

4.1 方式一：npm 全局安装

这是最常用的安装方式，适合大多数 Node.js 开发者。

npm install -g @openai/codex

安装完成后，执行：

codex --version

如果能输出版本号，说明安装成功。如果你在执行codex命令时提示“找不到命令”，但 npm 安装过程没有报错，那么问题几乎可以断定是 npm 全局 bin 目录不在 PATH 中。

查看 npm 全局 bin 路径：

npm bin -g

把输出的目录加入系统的 PATH 环境变量，然后重新打开终端。

4.2 方式二：通过 Homebrew 安装

macOS 用户如果习惯使用 Homebrew，也可以直接通过 brew 安装。具体命令以官方文档为准，一般形式是：

brew install codex

这种方式的好处是 Homebrew 会自动处理可执行文件路径，省去手动配 PATH 的麻烦。需要注意的是，Homebrew 安装的版本可能与 npm 源存在时间差，如果你追求最新版本，npm 方式通常更及时。

4.3 方式三：构建产物或源码方式

部分用户会在 CI 环境或 Docker 镜像中安装 Codex，这时可以选择直接下载官方构建产物，或者从源码构建。这类方式适合有定制需求的团队，对普通用户不是必须的。

如果你想了解最新的安装方式，建议直接查阅官方 GitHub 仓库的 README，那里会有针对不同操作系统的说明。不要轻信第三方博客上写的“死命令”，因为工具版本迭代很快，几个月前的命令可能已经变化。

4.4 验证安装结果

无论使用哪种方式，装完之后都建议执行一次完整验证：

codex --version codex --help

--help会列出当前版本的常用命令和参数。熟悉这些命令，比死记教程更有用，因为不同版本的 Codex 命令结构可能不同。

5. 配置认证：登录、API Key 与环境变量

Codex CLI 本身只是客户端，真正执行任务的是背后的模型服务。所以你安装完 CLI 之后，还需要完成认证配置，否则任何任务都无法运行。

5.1 登录方式

Codex 支持两种认证方式，一种是使用 ChatGPT 账号登录，适合订阅了 ChatGPT Plus 或 Pro 等服务的用户；另一种是使用 OpenAI API Key，适合按量付费的开发者。

执行登录命令：

codex login

按照终端提示完成授权流程即可。如果登录过程中遇到浏览器无法打开、授权页面验证缓慢等问题，先检查你当前网络能否正常访问 OpenAI 相关服务，再检查本地代理设置。

5.2 API Key 方式

如果你使用 API Key，需要先到 OpenAI 平台创建 Key，然后写入环境变量。在 Linux 或 macOS 上，可以临时导出：

export OPENAI_API_KEY="your-api-key"

如果要永久生效，把这一行写入 shell 配置文件，比如~/.bashrc或~/.zshrc，然后执行source使其生效。

Windows 用户可以使用 PowerShell：

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

或者通过“系统属性 -> 环境变量”界面进行配置。

这里要重点提醒：API Key 是你的账号凭证，不要提交到 Git 仓库，也不要截图发到公开群聊。推荐使用.env文件配合dotenv机制管理，或者使用系统密钥管理工具。

5.3 代理环境变量

网络环境是一个容易踩坑的地方。Codex 请求 OpenAI 接口时，会读取常见的代理环境变量。如果你在使用代理，可以先确认自己的代理端口，然后设置：

export HTTPS_PROXY="http://127.0.0.1:你的代理端口" export HTTP_PROXY="http://127.0.0.1:你的代理端口"

如果代理配置不当，会出现网络连接失败，或者前面提到的local proxy failed类报错。这类问题的排查思路是先确认代理端口是否写对，再确认代理服务是否真的在运行，最后确认目标服务是否允许该代理访问。

这里需要强调：请在你的网络环境合规前提下使用相关服务，不要使用任何非法的网络访问手段。如果当前网络无法正常访问，建议先处理网络合规问题，再继续工具配置。

5.4 配置检查

认证配置完成后，可以执行一个简单的对话命令验证是否连通：

codex exec "回复 OK 两个字"

如果返回了模型输出，说明认证和网络都正常。如果报错，按照错误信息中的提示检查 API Key、模型名称和网络环境。

6. 第一次使用：跑通一个真实任务

现在环境已经就绪，我们来跑一个最小可用的任务。建议新建一个临时目录，在里面初始化一个 Git 仓库，避免影响真实项目。

6.1 初始化测试项目

mkdir codex-demo cd codex-demo git init

这一步不是形式主义。Codex 在识别项目上下文时，会依赖 Git 仓库来理解变更范围。没有 Git 仓库，它也能工作，但很多基于 diff 的操作会受限。

6.2 执行第一个任务

在项目里创建一个简单的 Python 脚本，故意留下一个 bug，然后让 Codex 去修复。

先创建文件demo.py：

# 文件路径：codex-demo/demo.py def divide(a, b): return a / b if __name__ == "__main__": print(divide(10, 0))

这个脚本会在运行时抛出ZeroDivisionError。现在让 Codex 来修复：

codex exec "修复 demo.py 中的除零错误，让程序输出 0 而不是报错"

Codex 会读取文件内容、理解问题、修改代码。执行过程中，它可能会展示计划、输出命令，并在关键节点请求确认。不同版本的交互方式略有差异，但整体流程是相似的。

修复后的代码可能长这样：

# 文件路径：codex-demo/demo.py def divide(a, b): if b == 0: return 0 return a / b if __name__ == "__main__": print(divide(10, 0))

注意，这只是它可能给出的一种方案。实际输出取决于模型判断和上下文。

6.3 验证结果

修改完成后，手动运行脚本验证：

python demo.py

预期输出：

0

到这一步，你已经完成了“让 Agent 在真实环境里改代码并验证结果”的最小闭环。后续可以把任务复杂度逐步提升，比如让它写测试、重构函数、修复多个文件的问题。

6.4 交互式会话

除了codex exec这种一次性执行方式，Codex 还支持交互式对话。直接运行：

codex

会进入一个交互终端，你可以连续提需求，它会记住上下文，像和一个远程工程师对话一样工作。这种方式适合做更复杂的任务，比如：“帮我看一下这个仓库的整体结构”，“给订单模块补充单测”，“解释一下这个算法的时间复杂度”。

交互模式下同样要注意权限确认。当它准备执行可能影响环境的命令时，会停下来征求你的同意。如果你希望全程自动执行，可以查看帮助文档中的--dangerously-bypass-approvals参数，但日常使用不建议开启这个选项，尤其是第一次使用的时候。

7. 常用模式与进阶技巧

7.1 在指定目录下运行

Codex 默认会在当前工作目录下工作。如果项目在别的路径，可以先cd到目标目录，再启动 Codex。也可以使用--cd参数指定工作目录。

codex --cd /path/to/project

这个参数适合在脚本中调用，避免频繁切换目录。

7.2 指定模型

Codex 默认会使用官方推荐模型，但部分场景下你可以手动指定模型。

codex exec --model gpt-5 "生成一个快速排序"

注意，不同账号类型和 API 权限可用的模型列表不同。如果出现类似the 'gpt-5.6-sol' model is not supported when using codex with a...的报错，说明你指定了当前认证方式不支持的模型。解决方案是去掉--model参数，恢复默认配置，或者改成账号权限支持的模型名称。

7.3 配置文件管理个性化参数

Codex 支持通过配置文件管理模型、权限、代理等参数。配置文件的作用是让你不用每次都在命令行写一堆参数，也能让团队共享一致配置。

从目前的使用实践看，Codex 支持在项目根目录放置配置文件，也支持在用户主目录放置全局配置。配置项一般包括：

• 默认模型
• 权限策略
• 代理设置
• 关闭自动确认等行为开关

具体字段名和格式会因为版本不同而变化。建议在安装完成后先运行一次codex --help或查看官方文档，了解当前版本支持哪些配置项。不要直接复制旧博客的配置文件，因为字段可能已经改版。

7.4 接入第三方模型服务

Codex 也可以配置为连接兼容 OpenAI 协议的其他模型服务，例如某些国产大模型平台提供的 API。网络上有不少开发者尝试把 Codex 接入 DeepSeek 等模型，思路大致相同：通过配置base_url和model，让 Codex 将请求发送到第三方服务的地址。

这类配置本质上依赖第三方服务是否兼容 OpenAI 的接口协议。如果你要配置，建议先确认该服务商提供的 API 文档中是否标明了 OpenAI 兼容模式，再按官方文档填写对应配置项。

需要提醒的是，不同模型的能力差异很大。Codex 的 Agent 循环非常依赖模型的工具调用能力，如果模型本身不支持工具调用，或者调用格式不标准，即使请求能发出去，任务也无法正常执行。所以“接入哪家模型”不只是改个地址的问题，还要考虑模型的指令遵循能力和推理稳定性。

7.5 Skill 与工程化扩展

Codex 正在往“可扩展”的方向发展。社区里已经有人在讨论通过定义额外 Skill 的方式，让 Codex 学会特定项目的专属操作流程。这种设计类似于给 Agent 追加“领域知识包”，让它在处理特定框架或内部系统时更顺手。

现阶段，这类能力在不同版本中支持程度不同。对初学者，建议先掌握基础安装、认证、任务执行和配置管理，等对 Agent 的工作方式有感觉之后，再去探索 Skill 和自定义扩展，否则容易陷入“配置学了一大堆，任务一个没跑通”的误区。

8. 常见问题与排查方法

Codex 安装使用过程中，绝大多数问题都集中在四个方向：找不到命令、认证失败、网络代理出错、模型不支持。下面用表格整理常见情况。

排查问题时记住一个原则：先看完整报错，再查对应环节。很多人在网上搜到错误信息的前半段就去问，结果给建议的人也只能猜。把完整报错贴出来，才能更准确定位是网络、认证还是模型配置的问题。

9. 最佳实践与工程建议

工具能跑通是一回事，能在真实项目里稳定、安全地用好是另一回事。以下建议来自实际工程经验，希望能帮你少走弯路。

9.1 在隔离环境中练习

第一次使用 Codex 时，不要直接对一个重要项目下手。建议在临时目录、测试仓库或 Docker 容器里先跑几个任务，熟悉它的交互模式和权限确认逻辑。等确认它不会乱改文件之后，再逐步应用到真实项目。

9.2 善用 Git 作为安全网

Codex 修改代码之前，确保当前分支是干净的，或者至少有一个可以回退的提交点。这样即使它改错了，也能通过git checkout或git revert恢复。更稳妥的做法是让 Codex 在单独的分支上工作，检查通过后再合并到主分支。

9.3 理解权限控制，不做危险操作

Codex 需要执行命令才能完成任务，但并不是所有命令都值得放行。建议保持默认的人工确认策略，尤其是在遇到删除命令、全局安装、修改系统配置、清理依赖这类高风险操作时，多看一眼再确认。不要因为嫌麻烦而直接开启跳过所有确认的选项。

在生产环境中，不要直接让 Codex 执行数据库变更、推送代码到线上、删除生产环境文件等操作。即使它具备这个能力，也不意味着应该让它不经审查地执行。任何涉及生产环境的变更，都应该走人工审查和回滚流程。

9.4 API 成本控制

Codex 背后调用的是大模型接口，长时间、大任务量的会话会产生可观的费用。建议通过平台控制台观察请求量和 Token 消耗，设置账单提醒。在开发环境中，尽量缩小任务范围，比如只指定修复某个模块，而不是“把整个项目优化一遍”。

9.5 不要迷信一键完成

Codex 确实能完成很多任务，但它的输出仍然需要人审查。对生成代码的边界情况、安全逻辑、性能瓶颈，开发者要有判断能力。把它当作“效率放大器”而不是“思考替代品”，才能在提高速度的同时守住代码质量。

9.6 版本管理

Codex 迭代速度比较快，新版本可能调整命令参数、配置格式和默认行为。建议在团队内固定使用某个已验证版本，或者至少每个人都知道自己当前用的版本号。升级前先在测试项目里跑一遍，避免突然升级导致配置失效。

10. 总结与后续学习方向

Codex 的安装使用，本质上是在回答一个问题：当 AI 不仅能写代码，还能执行命令、读取结果、自我修正时，开发者的工作方式会发生什么变化？这篇文章从环境检查、安装认证、任务跑通、问题排查到工程建议，已经帮你梳理了一遍完整的上手路径。重要的不是背下某条命令，而是理解整套流程里哪些环节容易出问题，以及为什么这些环节会出问题。

安装完成后，建议按这个顺序继续深入：先用 Codex 完成一个小项目的 bug 修复和测试补充，再尝试把常用配置写进项目配置文件，最后探索 Skill 扩展、第三方模型接入和团队协同方案。等你对它的交互模式足够熟悉，就可以根据自己的开发习惯，设计一套最适合自己的使用边界和审查流程。

一句话总结：Codex 的价值上限，不取决于模型有多强，而取决于你有多清楚自己想让它完成什么，以及你有多严谨地检查它完成的结果。