Codex CLI 安装配置与实战：终端AI编程助手使用指南

最近在 9 月底重新搭建环境时，把 Codex 的安装、登录、配置和使用完整跑了一遍。很多朋友第一次接触这类终端 AI 编程工具时，卡在环境安装、模型配置、常见报错上，网上资料比较零散。这篇文章围绕 Codex CLI 的完整使用链路展开，从概念解释到安装步骤，从 config.toml 配置到真实项目实战，再到高频报错排查和工程建议，适合零基础入门，也适合已经在用其他编码助手的开发者参考。

1. Codex 是什么？它解决什么问题？

Codex 是 OpenAI 推出的 AI 编码代理工具。它和普通的代码补全插件不一样，它不是一个只负责“跳到下一行”的自动补全工具，而是一个可以理解项目上下文、读取文件、执行终端命令、修改代码、运行测试的智能助手。你在终端里用自然语言描述需求，Codex 会规划操作步骤，然后实际修改项目文件，再通过命令验证结果。

举个例子，以前你写一个 Python 脚本处理 CSV 文件，可能需要自己打开文件、看字段、写循环、处理异常、再运行调试。使用 Codex 时，你可以直接说：“请读取项目里的 data.csv，统计其中每个分类的总数量，并把结果输出到 summary.txt。”它会先查看目录结构，读取文件，编写脚本，然后执行命令。整个过程是交互式的，你随时可以查看它改了哪些文件、执行了哪些命令，并可以批准或拒绝。

Codex 的常见应用场景包括：

• 快速生成项目脚手架和工具脚本。
• 在已有代码仓库中定位 bug 并修复。
• 自动补充单元测试。
• 重构代码、优化函数结构。
• 执行重复性的代码分析和命令操作。
• 通过 Git 提交记录理解项目变更。

这里需要区分 Codex CLI 与一般聊天式 AI 工具。Codex 被设计为“有手有脚”的编程代理，它能操作本地文件系统和终端。这种能力带来效率提升，同时也带来安全边界问题，所以官方推荐在沙箱环境或受限权限下使用，后面我也会专门讲审批策略和沙箱模式。

另一个需要说明的词是“免费”。Codex CLI 本身是一个开源且免费安装的终端工具，你不需要为安装工具付费。但 Codex 要调用大模型，模型服务通常按 API 调用量或订阅额度计费，OpenAI 平台是否提供新用户试用额度、哪些模型可用，要以官方账号页面和文档为准。文章后面会给出配置第三方模型服务的基本思路，但前提是遵守各平台的服务条款和合规要求。

理解这些之后，我们先把环境准备好，再进入安装流程。

2. 安装前的准备工作：环境、账号与免费额度

在安装 Codex 之前，建议先确认电脑环境满足基础条件。Codex CLI 基于 Node.js 生态，通过 npm 全局包分发，所以第一步是安装 Node.js 和 npm。

2.1 安装 Node.js 和 npm

打开终端（macOS 的 Terminal、Linux 的 shell，或 Windows 的 PowerShell），输入以下命令检查 Node.js 和 npm 是否已安装：

bash复制node -v
npm -v

如果你看到了类似 v18.20.4 和 10.8.2 这样的版本号，说明环境已具备。如果提示 node: command not found，需要先安装 Node.js。建议从 Node.js 官网下载 LTS（长期支持）版本，或使用系统对应的包管理器安装。安装完成后重新打开终端，再次执行上面的命令确认。

2.2 安装并配置 Git

Codex 经常工作在 Git 仓库中，它会通过 Git 查看文件变更、创建分支、生成提交。即使你只是写一个小脚本，也建议提前安装 Git。检查方法：

bash复制git --version

Windows 用户安装 Git 时，建议保持默认的 Git Bash 组件，这样之后在 VS Code 或 Windows Terminal 中使用 Codex 会更顺畅。

2.3 准备 API Key 或登录账号

Codex CLI 支持两种认证方式：

第一种是使用 OpenAI 账号直接登录。在终端执行 codex login，会弹出浏览器授权页面，登录后 Codex 会把令牌保存到本地认证文件中。这种方式适合个人开发者，操作直观。

第二种是使用 API Key。如果你在使用 OpenAI API 平台，可以创建 API Key，然后通过环境变量注入：

bash复制# macOS / Linux
export OPENAI_API_KEY="你的 API Key"

# Windows PowerShell
$env:OPENAI_API_KEY="你的 API Key"

API Key 属于敏感信息，不要在代码仓库、聊天记录或截图里明文展示。建议只在本地终端会话中临时设置，或者写入受保护的环境变量配置文件。

如果你选择接入其他兼容 OpenAI API 的服务，需要准备对应平台的 API Key，并在后面的 config.toml 中配置独立的模型供应商和 base_url。这个我会在第四章专门讲。

2.4 国内网络环境的安装加速

Codex 本身是 npm 包，安装时通常需要从 npm 仓库下载。如果你在安装过程中遇到网络超时或下载缓慢，可以临时切换 npm 镜像源。这里以国内常用的 npmmirror 镜像为例：

bash复制npm config set registry https://registry.npmmirror.com

查看当前 registry：

bash复制npm config get registry

如果后续要切回官方源，可以执行：

bash复制npm config set registry https://registry.npmjs.org/

切换镜像源只影响 npm 包下载速度，不影响 Codex 登录和模型调用。关于模型调用，OpenAI 的 API 服务在不同地区可能有不同的网络可达性，请你务必在法律允许、服务条款允许的前提下使用。本文不展开网络配置，也不涉及任何绕过访问限制的方法。

3. Codex CLI 安装与登录实战

环境准备好之后，下面进入正式安装流程。整个过程分为四步：安装 CLI、验证版本、登录 / 配置环境变量、进入交互式会话。

3.1 使用 npm 全局安装 Codex

在终端中执行：

bash复制npm install -g @openai/codex

这里的关键点是包名为 @openai/codex，不要漏掉 @openai/ 作用域。安装完成后，终端会提示安装路径和版本信息。

如果你在 Windows 上提示权限不足，可能需要用管理员权限打开 PowerShell。在 macOS 或 Linux 上，如果 /usr/local/lib/node_modules 目录没有写入权限，可以在命令前添加 sudo：

bash复制sudo npm install -g @openai/codex

但不建议全局使用 sudo，更推荐用 nvm 这样的 Node.js 版本管理工具来管理 Node.js 环境，从而避免权限问题。

3.2 验证安装是否成功

执行：

bash复制codex --version

如果输出一个版本号，说明安装成功。如果提示 codex: command not found，通常是 npm 全局包的 bin 目录没有加入系统 PATH。可以先用 npm prefix -g 查看全局安装路径，再把该路径下的 bin 目录加入 PATH。Windows 用户可以通过重新打开终端解决大部分路径刷新问题。

3.3 登录与认证

执行：

bash复制codex login

Codex 会在终端输出一个验证链接，提醒你在浏览器中打开。如果终端本身支持自动唤起浏览器，浏览器会直接打开授权页面。登录成功后，认证文件会写入 ~/.codex/auth.json。

你也可以使用 API Key 方式。上面提到的 OPENAI_API_KEY 环境变量配置过后，Codex 启动时会自动读取，不需要再执行 codex login。两种方式可以共存，但优先级会按照官方文档的实际逻辑处理，建议在同一台机器上只使用一种方式，避免混乱。

3.4 启动 Codex 交互式会话

安装并认证完成后，在项目根目录执行：

bash复制codex

你会看到一个交互式提示符。在这里可以直接输入自然语言任务，例如：

text复制请查看当前目录结构，并告诉我这是一个什么类型的项目。

Codex 会先列出它计划执行的操作，并等待你确认。你可以输入 y 批准执行，输入 n 拒绝，输入 exit 退出会话。

3.5 安装 IDE 扩展（可选）

Codex 除了 CLI 之外，也提供了支持 VS Code 等编辑器的扩展。如果你希望在编辑器里直接看到代码 diff、内联建议和聊天面板，可以打开扩展市场搜索 Codex 进行安装。扩展会复用你已经配置好的 CLI 登录状态，所以先完成 CLI 安装和登录，再安装扩展，体验会更顺畅。

到这里，你已经把 Codex 基本环境跑通了。不要急着执行复杂任务，先用简单命令熟悉交互方式，再进入项目实战。

4. 配置文件 config.toml 详解

Codex 的个性化配置集中在 ~/.codex/config.toml 文件中。这个文件控制默认模型、模型供应方、沙箱策略、审批策略等多个核心行为。当你安装完成并第一次运行后，可以手动创建或编辑它。

4.1 找到配置文件

在 macOS/Linux 上，配置文件路径是：

bash复制~/.codex/config.toml

在 Windows 上，通常位于：

text复制C:\Users\你的用户名\.codex\config.toml

如果 .codex 目录不存在，先执行一次 codex 命令，它会自动创建目录。或者手动创建也可以。

4.2 一个最小可用的配置示例

toml复制model = "gpt-5"
model_provider = "openai"

这段配置的意思是：默认使用 OpenAI 提供的 gpt-5 模型，模型供应商使用 OpenAI 官方服务。model 字段指定模型标识，model_provider 指定提供该模型的服务商。

这里需要提醒一下：不同时间、不同渠道的模型标识会变化，具体以 codex --help、官方文档和你账号实际可用的模型列表为准。如果你发现某一天启动后提示模型不支持，大概率是默认模型标识发生了变化，调整 model 字段即可。

4.3 常用配置字段解释

model_provider：模型服务商，默认是 openai。

model：具体的模型名称。同一个服务商下可能会有多个模型，例如不同代际或不同定位的模型。

sandbox_mode：沙箱模式。Codex 可以运行在受控环境中，限制对文件系统和网络的访问。推荐先开启沙箱，观察 Codex 的表现后再逐步放宽。

approval_policy：审批策略。比如 on_request 表示每次执行风险操作前都要确认，never 表示不主动请求审批，但这类策略影响安全边界，需要谨慎选择。

下面是一个包含常见策略的配置片段：

toml复制model = "gpt-5"
model_provider = "openai"
sandbox_mode = "workspace-write"
approval_policy = "on_request"

在这个配置中，Codex 可以对当前工作区写入文件，但遇到敏感操作时会主动征求你的确认。对于零基础用户，推荐先使用偏保守的策略。

4.4 如何配置第三方模型服务

Codex 支持通过 model_providers 配置自定义模型服务。如果你希望接入兼容 OpenAI API 的第三方模型平台，可以在 config.toml 中添加自定义 provider。

以一个常见的第三方服务为例，思路如下：

toml复制model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

说明：

• model_providers.deepseek 是自定义 provider 的配置块。
• name 是这个 provider 的显示名称。
• base_url 是该服务商的 API 地址。
• env_key 指定读取 API Key 的环境变量名称。你需要提前设置 DEEPSEEK_API_KEY 环境变量。

配置完成后，重新启动 Codex，它就会通过 deepseek 这个 provider 请求模型服务。这里要特别强调：第三方模型服务的兼容性、可用性、计费规则都以各平台官方文档为准，不要相信任何“破解”“免费无限调用”的灰色方案。接入任何模型服务前，请仔细阅读并遵守对应平台的服务条款和合规要求。

4.5 修改配置文件后的验证

每次修改 config.toml 后，建议先重启 Codex 会话，再执行一个简单任务，比如：

text复制写一个 Python 函数，计算一个列表的平均值。

如果模型调用失败，优先检查 provider 名称、base_url、env_key 和模型名是否都正确。常见错误往往只是配置项拼写不一致。

5. 从零开始实战：用 Codex 完成一个小任务

这一章我们用一个真实场景走一遍完整流程。假设你有一个空的练习目录，希望 Codex 帮你创建一个 Python 脚本，读取一个 CSV 文件并按分类统计数量。

5.1 创建项目目录

在终端执行：

bash复制mkdir codex-demo
cd codex-demo
git init

git init 不是必须的，但推荐创建 Git 仓库，因为 Codex 在识别文件变更、生成 diff 时会更方便，你也能通过 git diff 查看它的改动。

5.2 准备示例数据

先手动创建一个 sales.csv 文件，内容如下：

csv复制category,amount
A,10
B,20
A,15
C,5
B,25

这个文件只有六行，方便观察 Codex 的输出。实际项目中，你可以把文件替换成真实数据。

5.3 启动 Codex 并提出任务

在当前目录下启动：

bash复制codex

在交互提示符中输入：

text复制请读取当前目录中的 sales.csv，按 category 字段分组，计算每个分类的 amount 总和，并将结果写入 summary.txt。

Codex 可能会先列出操作步骤，例如：

• 读取 sales.csv。
• 编写一个 Python 脚本处理分组统计。
• 运行脚本。
• 查看 summary.txt 内容。

你可以输入 y 批准它逐条执行。Codex 会在终端中显示它执行命令的输出。预期结果是在目录下新增一个脚本文件，并且 summary.txt 中会包含类似这样的内容：

text复制A: 25
B: 45
C: 5

实际文件名和脚本形式可能不同，但结果应该符合统计逻辑。

5.4 查看 Codex 改动了什么

退出 Codex 后，在终端执行：

bash复制git status
git diff

通过这两个命令，你可以看到 Codex 创建或修改了哪些文件。这是使用 AI 编程代理时的好习惯：无论 AI 改了什么，都要审查 diff，确认代码逻辑正确后再提交。

5.5 更复杂的项目任务

简单任务跑通之后，你可以尝试让 Codex 完成更多操作，例如：

text复制把这段统计逻辑封装成函数，并添加命令行参数支持选择输入和输出文件。

text复制为这个脚本编写单元测试，测试空文件、缺少字段、重复分类等边界情况。

在这个过程中，Codex 会逐步展示出它不只是补全代码，而是一个能理解项目目标、调用命令、迭代修改文件的工具。你越能把需求描述清楚，Codex 的执行效果越好。

6. 常见报错与排查清单

在安装和使用 Codex 的过程中，我收集了几个高频问题。下面用表格汇总现象、可能原因和解决思路，再详细展开说明。

6.1 本地服务连接失败

这个报错通常出现在你配置了自定义模型服务之后。Codex 的 base_url 指向一个本地服务或中间层服务，但该服务没有启动、端口不正确、或者服务地址写错，导致 Codex 无法处理模型请求。

排查顺序：

• 确认自定义服务是否已启动。
• 检查 base_url 是否与服务的实际地址一致。
• 检查环境变量对应的 API Key 是否存在。
• 在浏览器中直接访问 base_url，看是否有响应。

6.2 模型不支持

如果你在 config.toml 中写了类似 gpt-5.6-sol 这样的模型名，但服务商和模型版本不匹配，Codex 会提示模型不支持。这个问题的核心是模型标识必须与所选 provider 的真实模型列表一致。

解决方式很简单：打开当前 provider 的模型列表文档，把 model 字段改成实际可用的模型名。如果你使用的是 OpenAI 官方服务，不同账号可访问的模型也可能不同，以官方页面显示的模型为准。

6.3 无法加载组织设置

有些团队会使用 OpenAI 组织账号登录 Codex。如果登录后提示无法加载组织设置，常见原因是组织账号的登录状态失效、网络请求失败、或者当前账号没有对应组织的访问权限。

建议先执行：

bash复制codex login status

查看当前登录信息，然后重新执行 codex login。如果组织设置了 SSO 或额外安全验证，需要先在浏览器中完成对应验证，再回到终端。

6.4 codex 命令找不到

codex: command not found 是安装类场景中最常见的问题。原因通常是 npm 的全局安装目录不在 PATH 中。你可以用 npm prefix -g 查看全局路径，然后把该路径下的 bin 目录加入 PATH。Windows 用户重新打开终端往往就能解决；macOS/Linux 用户需要检查 shell 配置文件。

6.5 登录卡住或验证失败

浏览器授权页面打不开、验证链接失效、登录后没有任何反应，这类问题多半和本机网络环境、浏览器默认行为、认证文件残留有关。可以清除旧的认证文件后重试：

bash复制codex logout

然后再次执行 codex login。如果本地网络无法访问授权服务，请先确认是否符合你所在环境的网络合规要求，再排查其他因素。

7. 最佳实践与工程建议

Codex 这类工具效率很高，但在真实项目中不能把它当作“自动驾驶”。它有边界，也有风险，使用时要建立规范。

7.1 从小项目入手，先跑通最小示例

第一次使用不要直接丢进一个庞大的生产仓库。先创建一个临时目录，放几个测试文件，让 Codex 完成简单任务。这样一来，你可以熟悉它的交互流程、审批机制和常见输出，也能在出错时更容易定位问题。

7.2 打开审批策略，保留人工审查环节

在 config.toml 中设置 approval_policy = "on_request"，让 Codex 执行风险操作前必须经过确认。尤其是它可能运行终端命令、修改文件或安装依赖，人工确认能避免很多意外。代码改动必须审查 diff，确认逻辑符合预期后再提交。

7.3 合理使用沙箱模式

沙箱模式可以限制 Codex 对文件系统和网络的访问范围。对不熟悉的项目，优先开启沙箱。如果你需要 Codex 执行 npm install、运行测试、网络请求等操作，再根据实际情况放宽权限。不要在敏感目录中直接放开所有权限。

7.4 API Key 和敏感信息的管理

永远不要把 API Key 写在代码文件或 config.toml 中。推荐使用环境变量，或使用密钥管理工具保存。Codex 生成的文件也可能包含硬编码路径、账号信息，使用前要检查生成内容是否泄露了敏感数据。

如果团队成员共同使用同一套模型服务，建议为不同成员分配独立 Key，方便审计和成本隔离。不要把个人 Key 提交到 Git 仓库，也不要在公开论坛、群聊或个人博客中粘贴完整 Key。

7.5 成本控制与模型选择

云模型调用通常有费用，使用前先关注两点：

• 当前模型的价格是按 token 计算还是按次计算。
• 自己的任务是否真的需要最贵、最新的模型。

简单任务可以选择性价比更高的模型，复杂推理任务再使用能力更强的模型。你可以通过 codex --help 或 config.toml 调整默认模型。为团队使用时，最好由负责人统一配置 provider 和模型，避免成员随意切换导致费用不可控。

7.6 合规使用与安全边界

Codex 是合法工具，但使用者需要遵守平台服务条款、数据隐私政策和所在地区的法律法规。尤其是涉及公司代码、用户数据、生产环境时，必须获得授权，使用最小权限原则，并在测试环境验证后再进行变更。不要把敏感业务代码上传到未经评估的第三方模型平台，也不要使用任何违反服务条款的破解或批量滥用手段。

7.7 记录日志，便于回溯

当 Codex 在项目中执行较多操作时，建议把它的会话记录和命令输出保存下来。你可以直接在终端回看，也可以使用 script 命令或 shell 的日志功能。出现问题时，这些记录能帮助你确定是模型理解错误、代码逻辑错误，还是配置问题。

8. 总结与下一步实践

到这一步，你已经掌握了 Codex 从环境准备、安装、登录、配置文件到实战使用的大部分内容。简单回顾一下重点：

• Codex CLI 是开源免费工具，可通过 npm 全局安装。
• 使用前需要准备好 Node.js、Git、OpenAI 账号或第三方模型 API Key。
• config.toml 是核心配置文件，model、model_provider、sandbox_mode、approval_policy 都需要理解清楚。
• 接入第三方模型时，只需要配置自定义 provider，但必须遵守对应平台条款。
• 实际使用中，审批策略、沙箱模式和 diff 审查是保证安全的关键。

如果你已经成功跑通第一个任务，下一步可以尝试让 Codex 处理真实项目中的 issue，比如修复单元测试、补充类型标注、重构重复代码。也可以把 Codex 接入到 CI/CD 流程中，辅助生成变更描述和代码审查意见。不过要记住，AI 编程代理的输出始终需要人工把关，尤其是在生产环境、数据库操作、权限变更等高风险场景下。

最后给你一个实用建议：不要急着用 Codex 处理最难的项目，先从一个小练习开始，比如写一个脚本、修一个简单的 bug、生成一个测试用例。体验完整流程之后，你会发现它的使用逻辑并不复杂，真正重要的是你如何把任务描述清楚，以及如何审查它的每一步操作。如果你想进一步了解 Codex 的自定义配置、模型选型或团队协作方案，可以先翻一翻官方文档，再对照自己的项目场景做实验。希望这份安装与使用笔记能帮你少踩一些坑，把工具真正用起来。