零基础搞定Codex CLI：从安装配置到实战项目全攻略

最近身边有不少朋友开始跟着各种视频了解 Codex，但真正动手时往往卡在第一步：要么 Node.js 没装好，要么登录之后不知道下一步干嘛，要么满屏英文报错看得一头雾水。网上的资料又分散在不同的平台，有的讲原理、有的只给命令，对零基础用户并不友好。

这篇文章就是一份系统课性质的图文教程，目标是把 Codex 从“听说过的工具”变成“自己用得起来的工具”。我会从概念、环境准备、安装配置、登录认证开始，再带着你完成两个实战项目，最后补上常见报错排查和工程建议。过程中会给出可以直接复制的命令和配置，你只需要打开终端，一步一步照做即可。

需要提前说明一点：不写代码不代表不接触终端。你要能打开命令行窗口、进入某个文件夹、粘贴命令并查看输出结果。这些操作不需要编程基础，但它们是使用 Codex 这类工具的基本功。

1. Codex 到底是什么？为什么零基础也能上手

1.1 直观理解 Codex

Codex 是 OpenAI 推出的 AI 编程助手产品线，目前最常见的形态是命令行工具 Codex CLI，也有对应的桌面端和网页端入口。你可以把它理解成一个“住在终端里的 AI 程序员”：你用自然语言告诉它想要什么，它会在你的项目目录里帮你创建文件、编写代码、运行命令，甚至根据报错信息继续修改，直到任务完成。

它和普通聊天机器人的区别在于场景不同。聊天工具只能给你一段代码让你自己复制粘贴，而 Codex 被设计成直接嵌入开发工作流。它知道你当前打开了哪个文件夹，可以读取项目里的文件内容，可以执行命令查看结果，然后基于实际情况做下一步操作。这种“代理式”的工作方式，让代码生成从“给答案”变成了“帮你干活”。

1.2 核心概念与工作流程

想用好 Codex，先理解四个关键词：

• CLI：Command-Line Interface，命令行界面。Codex CLI 是一个 npm 包，安装后在终端里输入 codex 命令启动。
• 模型：Codex 背后的大语言模型，负责理解需求并生成代码。模型可以切换，官方提供 OpenAI 系列模型，也可以通过配置接入其他 OpenAI 兼容的服务。
• Provider：模型提供方。你可以把 Provider 理解为“代码生成服务从哪来”。默认是 OpenAI，也可以指向其他兼容服务。
• API Key：访问模型服务的密钥，相当于你的身份凭证。配置好 API Key 后，Codex 才能调用模型生成内容。

它的典型工作流程是：在项目目录中启动 Codex → 用自然语言描述需求 → Codex 分析项目结构和上下文 → 生成或修改代码 → 你运行代码验证 → 如果出错，把报错信息继续发给它 → 循环迭代直到可用。

零基础用户之所以也能尝试，是因为这个流程中的“需求描述”完全是自然语言，不需要懂语法。但我也要诚实提醒：最终运行代码、查看结果、判断代码是否符合预期，仍然需要基本常识。AI 会犯错，你才是最终负责人。

2. 安装前的准备：一张环境清单

在正式安装之前，先把环境准备好。很多报错不是 Codex 本身的问题，而是基础环境缺失或版本冲突导致的。

2.1 操作系统与终端

Codex CLI 支持 Windows、macOS、Linux 三大平台。

• Windows：建议使用 PowerShell 或 Windows Terminal。PowerShell 是系统自带工具，直接搜索“PowerShell”就能打开。部分教程会建议在 Windows 上使用 WSL（Windows Subsystem for Linux，Linux 子系统），但如果你只是跟着本文操作，原生 PowerShell 完全够用。
• macOS：使用系统自带的 Terminal，或者 iTerm2。
• Linux：使用任意终端模拟器即可。

Node.js 和 npm 是跨平台的，安装方式略有差异，后面会分平台说明。

2.2 必备软件清单

安装 Codex CLI 之前，建议先准备好下面几样东西：

Node.js 的安装是关键。Codex CLI 依赖现代 JavaScript 运行时，需要 Node.js 18 以上的新版本。请不要安装太老的版本，也不要只看“下载人数多”就乱选，推荐选择官方标注的 LTS（Long Term Support，长期支持版）。

2.3 账号与密钥概念

使用 Codex CLI 有两种认证思路：

1. ChatGPT 账号登录：在终端执行 codex login，会跳转浏览器授权。优点是不用手动创建密钥，缺点是需要 ChatGPT 账号可用，并且订阅或额度要满足模型调用要求。
2. API Key 方式：从模型服务商的控制台生成密钥，然后在环境变量中配置。这种方式适合使用第三方兼容服务的用户，也适合脚本化、自动化场景，可控性更强。

零基础用户可能会搞混“登录账号”和“API Key”的关系。简单说：账号登录就像用手机 App 扫码登录网页版；API Key 更像是一张长期有效的门禁卡，把卡片信息填进去后，程序就能自动开门。两种方式不需要同时配置，选一种即可。

3. 手把手安装 Codex CLI

3.1 安装 Node.js

Node.js 的安装分平台说明。

Windows 安装步骤：

1. 打开 Node.js 官网（nodejs.org）。
2. 下载 LTS 版本的 Windows Installer（.msi 文件）。
3. 双击安装，安装向导中保持默认选项即可。
4. 特别注意：安装到“Custom Setup”页面时，确认 npm 相关选项被勾选。
5. 安装完成后，重新打开 PowerShell，输入 node -v 和 npm -v，能看到版本号说明成功。

bash复制node -v
npm -v

macOS / Linux 安装步骤：

推荐使用 nvm（Node Version Manager，Node 版本管理器）来安装 Node.js。用 nvm 的好处是以后可以随时切换 Node 版本，避免项目之间版本冲突。

macOS 打开终端，Linux 打开终端，执行以下命令安装 nvm：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后重启终端，或执行 source ~/.bashrc（Linux） / source ~/.zshrc（macOS），然后执行：

bash复制nvm install --lts
nvm use --lts
node -v
npm -v

如果你不想使用 nvm，也可以直接去 Node.js 官网下载对应系统的安装包，安装步骤和 Windows 类似。无论哪种方式，最后能输出 Node 版本号即可。

3.2 安装 Git（强烈建议）

Git 不是 Codex 运行的必要条件，但对实战非常重要。让 AI 生成代码意味着你的项目文件会频繁变动，如果没有版本管理，改坏了很难回滚。Git 能让你随时查看 Codex 改了什么，也可以一键还原。

Windows：直接从 git-scm.com 下载安装包，安装时一路默认即可。
macOS：终端中输入 git --version，如果提示不存在，系统会引导你安装 Xcode Command Line Tools；也可以使用 Homebrew 安装：

bash复制brew install git

Linux（Debian/Ubuntu 系列）：

bash复制sudo apt update
sudo apt install git -y

安装后确认版本：

bash复制git --version

3.3 用 npm 全局安装 Codex CLI

Node.js 带上了 npm，接下来只需要一条命令：

bash复制npm install -g @openai/codex

这条命令中的 -g 表示全局安装。全局安装后，无论在哪个目录打开终端，都可以直接使用 codex 命令，不需要每次进入固定目录。

安装过程中如果看到大量打印日志，属于正常现象。如果出现权限报错，在 Windows 上可以用“以管理员身份运行 PowerShell”重试；macOS/Linux 上如果是权限问题，可以在命令前加 sudo 尝试：

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

这里提醒一下：使用 sudo 只是解决全局写权限的常见办法，但如果你对系统权限不熟悉，建议优先排查 npm 的全局安装目录配置是否正确，如果只需要当前用户使用，也可以不加 sudo 改用用户级全局安装。

3.4 验证安装与桌面版说明

安装完成后，验证命令：

bash复制codex --version

或者：

bash复制codex --help

能输出版本号或帮助信息，说明安装成功。如果提示“codex 不是内部或外部命令”，大概率是 Node.js 的全局 bin 目录没有加入 PATH 环境变量。Windows 用户重新打开一次 PowerShell 通常能解决；如果还是不行，需要检查 npm 全局前缀并手动将其加入系统 PATH。

如果你使用的是 Codex 桌面版或网页版，本文后面的配置思路同样适用，只是入口不同。本文主线以 Codex CLI 为例，因为命令行版本更适合跟着实战走，而且很多第三方接入配置都是围绕 CLI 展开的。

4. 登录与认证配置

安装完成后，Codex 还不能直接干活。它需要知道你以什么身份调用模型服务，这一步就是认证配置。

4.1 两种认证方式对比

建议本教程先掌握 API Key 方式，因为它的通用性最强。即使后续要切换模型服务商，也只是换一个 Key 的事。

4.2 ChatGPT 登录方式（可选）

在终端执行：

bash复制codex login

终端会显示一个地址和授权码。浏览器打开地址，登录你的账号并粘贴授权码，完成后回到终端，Codex 会保存登录态。

这种方式的坑点在于：如果账号本身没有可用的模型额度，或者页面无法加载组织设置、登录状态过期，你会看到各种“无法加载”或“认证失败”的提示。遇到这类问题不用慌，先确认账号状态、清除浏览器旧会话后重试。如果持续失败，直接切换到 API Key 方式更省心。

4.3 配置 API Key 环境变量

先用浏览器登录模型服务商的控制台，创建一个 API Key。创建之后，密钥通常只会完整显示一次，务必复制保存。

然后配置环境变量。Windows PowerShell：

powershell复制$env:OPENAI_API_KEY="sk-你的密钥"

macOS / Linux：

bash复制export OPENAI_API_KEY="sk-你的密钥"

这种配置只在当前终端窗口生效。如果希望每次打开终端都自动加载，需要把 export 写入配置文件中。macOS/Linux 写入 ~/.zshrc 或 ~/.bashrc，Windows 可以在系统环境变量中新建一个用户变量。

重要原则：绝对不要把 API Key 写进项目文件、Git 仓库或任何会被分享的代码中。 Key 一旦泄露就可能被他人盗用，产生不必要的费用。

4.4 理解配置文件 config.toml

Codex CLI 会读取一个配置文件，默认路径是用户目录下的 .codex/config.toml：

• Windows：C:\Users\你的用户名\.codex\config.toml
• macOS / Linux：~/.codex/config.toml

如果文件不存在，可以手动创建。一个最小配置看起来像这样：

toml复制model = "gpt-5"

model 指定请求的模型名称。问题在于，不同账号可见的模型不一样，模型名称也在快速更新。如果你不确定账号支持哪些模型，可以先不要写死 model，让它使用内置默认值，或查阅当前版本的官方文档来确认模型列表。

config.toml 中还可以配置提供商、请求超时、是否自动审批等参数，下面一节会专门讲最常用的提供商配置。

5. 配置模型提供商：接入 OpenAI 兼容服务

很多用户在配置时会遇到类似“model is not supported”或“无法加载组织设置”的报错，原因往往不是 Codex 装错了，而是默认的模型服务在当前网络或账号环境下不可用。这时候可以切换模型提供商，让 Codex 指向其他 OpenAI 兼容服务。

5.1 为什么需要理解 model_provider

简单来说，Codex 会向一个固定的 API 地址发送请求。默认情况下，它访问 OpenAI 的接口。但市面上的很多模型服务都兼容 OpenAI 的请求协议，也就是说，Codex 只要把请求发送到另一个地址，就能切换底层模型。

在 Codex CLI 的配置里，这个“另一个地址”由 model_providers 定义。你可以在配置文件中给每个服务商起一个名字，然后设置：

• base_url：服务商 API 地址。
• env_key：从哪个环境变量读取 API Key。
• wire_api：接口风格，一般是 chat 或 responses。

为什么这个配置重要？因为很多人直接把网上搜来的配置复制进文件里，结果模型名对不上、协议不匹配，自然报错。理解这三项的含义后，你就能自己判断配置是否合理。

5.2 提供商配置模板

下面是通用的配置模板。假设服务商叫 my-provider，API 地址是 https://example.com/v1，环境变量名是 MY_API_KEY：

toml复制model = "my-model-name"
model_provider = "my-provider"

[model_providers.my-provider]
name = "My Provider"
base_url = "https://example.com/v1"
env_key = "MY_API_KEY"
wire_api = "chat"

配置分两段：

1. 顶部两个全局参数：model 指定最终使用的模型名，model_provider 指定走哪个提供商。
2. [model_providers.my-provider] 表格中定义提供商的详细信息。

base_url 必须以 /v1 结尾还是不带 /v1，取决于服务商文档。写之前先看一下对方给出的接口示例，通常 API 文档中调用示例的地址就是 base_url。

5.3 示例：接入 DeepSeek

这里以常见的 DeepSeek API 为例。先设置环境变量：

bash复制export DEEPSEEK_API_KEY="sk-你的DeepSeek密钥"

然后在 config.toml 中加入：

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

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

配置完成后，启动 Codex。如果它能正常响应你的问题并生成代码，说明切换成功。如果提示模型不支持，先确认服务商提供的模型名是否正确，比如有些服务商区分 deepseek-chat 和 deepseek-reasoner，你要根据服务商文档填写实际可用的模型名。

需要强调的是：不同服务商的兼容程度不同，不是所有服务都能完美复现 Codex 的全部功能。遇到能力缺失时，优先查阅服务商文档和 Codex 的官方更新说明，而不是盲目改配置。

5.4 切换后如何验证配置

做一个最简验证。启动 Codex 后，问一句没有任何代码含义的普通问题，比如“请用一句话说明你现在是什么状态”。如果能收到正常回复，说明认证、地址、协议都通了。

如果启动时报错“codex is ignoring 1 unrecognized configuration setting”，这通常表示配置文件中某个字段拼写错误，或者该字段是其他工具的配置，Codex 不认识。解决方法是根据提示打开配置文件，逐行核对字段名，删除多余项。版本更新后也可能出现老配置被废弃的情况，这时需要对照当前版本的官方文档更新。

6. 第一个实战项目：用 Codex 写一个待办清单脚本

理论讲得再多，不如亲手跑一个小项目。这一节我们让 Codex 从零生成一个可用的 Python 待办清单工具，功能非常简单：支持在命令行添加任务、查看任务、删除任务，数据保存在本地 JSON 文件中。

6.1 需求描述示例

零基础用户最需要练习的能力，就是把自己脑子里的想法转换成 Codex 能理解的描述。差的描述是“帮我写个东西”，好的描述包含：语言、形态、功能列表、数据保存方式。

示例描述：

用 Python 写一个命令行待办清单工具。它支持三个命令：add 添加任务，list 查看所有任务，delete 按编号删除任务。任务保存在当前目录的 tasks.json 文件中。给我完整的 Python 代码，并告诉我每一步怎么运行。

这段描述足够具体：明确了语言、工具形态、功能范围、文件存储和输出要求。

6.2 初始化项目目录

打开终端，进入一个你希望创建项目的目录，然后新建文件夹并进入：

bash复制mkdir todo-app
cd todo-app

初始化 Git 仓库，方便后续查看 Codex 的改动：

bash复制git init

这时会生成一个隐藏的 .git 目录，代表版本控制已开启。之后 Codex 生成的任何文件，都可以用 git status 查看。

6.3 启动 Codex 并描述需求

在项目目录下启动 Codex：

bash复制codex

看到命令提示符后，输入上面那段需求描述并回车。Codex 会分析当前目录，然后逐步生成文件。它可能会直接创建 todo.py，也可能会先询问你几个问题，比如“是否需要彩色输出”“是否支持模糊匹配”。新手建议保持默认，不要一开始就要求复杂功能。

生成过程可能需要几十秒到几分钟不等，取决于模型和服务商响应速度。耐心等待，不要中途关闭终端。

6.4 运行生成的代码

生成完成后，退出 Codex（按 Ctrl+C 或输入 exit），在终端查看目录：

bash复制ls

你应该能看到类似 todo.py 的文件。接下来按 Codex 给的使用说明运行，比如：

bash复制python todo.py add "写一篇文章"
python todo.py list
python todo.py delete 1

如果你的电脑只安装了 Python 3，有时需要使用 python3 命令；Windows 用户也可能是 py：

bash复制python3 todo.py add "写一篇文章"

运行后如果正常输出“添加成功”和任务列表，恭喜你，第一个 AI 辅助生成的小工具已经可以用了。

6.5 发现问题并迭代修复

第一次运行不一定成功。常见的情况包括：

• 报错 FileNotFoundError，说明代码没有处理 JSON 文件不存在的情况。
• 报错 ModuleNotFoundError，说明代码使用了你没安装的第三方库。
• 命令行参数解析报错，说明代码对参数顺序处理有问题。

无论出现什么报错，方法都一样：把终端的报错信息完整复制，重新启动 Codex，粘贴报错并加一句“请修复这个问题”，让它分析并修改代码。这个过程是整个 AI 编程工作流中最核心的一环：不是期待 AI 一次写对，而是通过对话不断逼近正确结果。

修复后重新运行，你会发现自己的角色变了：你不需要理解每一行代码，但你需要能描述现象、提供报错、验证结果。这项能力通过几次实战就能培养起来。

7. 进阶实战：让 Codex 修 Bug 和做代码审查

第七章拔高操作。前面生成的是单文件小工具，真实项目往往有多个文件，还涉及已有代码的修改。这一节掌握三个进阶用法。

7.1 用报错信息驱动修复

假设你的脚本运行时报了这样一个错误：

code复制Traceback (most recent call last):
  File "todo.py", line 21, in <module>
    tasks = json.loads(f.read())
json.decoder.JSONDecodeError: Expecting value: line 1 column 1

这个报错说明程序在读取一个空文件时，直接尝试解析 JSON，结果失败了。你不需要了解背后的原理，直接复制全部报错，发给 Codex：

我的 todo.py 运行报错：粘贴报错信息。请修复。

Codex 会定位到读取文件那段逻辑，通常会加入“如果文件为空则返回空列表”的判断。它可能还会顺便改进代码结构。

这类能力特别适合以后复用到自己的场景中：以后遇到任何看不懂的报错，第一步都是完整复制报错文本，不要只截一行。

7.2 主动请求代码审查

Codex 可以做“代码评审”。把当前文件的代码内容交给它，或者直接让它读取项目文件后，发出类似指令：

请审查当前目录下的 todo.py，指出潜在 bug、代码风格问题和安全隐患，并给出修改建议，不要直接改代码。

不直接改代码很重要，因为审查和修改是两回事。新手往往让 AI 一股脑把代码重写了，结果改完自己也看不懂，出了问题更难排查。先让它列出问题，你来决定哪些值得改。

常见审查结果包括：缺少异常处理、路径硬编码、没有处理 JSON 文件损坏、命令行参数校验不完整等。每一条都是你学习编程常识的素材。

7.3 多文件项目的协作方式

当项目文件较多时，不要一次性把所有内容都贴进对话，这既浪费上下文，也容易让 Codex 逻辑混乱。更好的做法是：

1. 明确当前要改的模块：比如“只修改文件读取相关的 utils.py”。
2. 让 Codex 先描述修改计划，确认后再动手。
3. 查看它改动后的差异。

查看差异的命令是：

bash复制git diff

如果你发现某次修改不合适，可以随时回滚：

bash复制git checkout -- 文件名

学会使用 git diff 和回滚命令，是 AI 生成代码时代最值得花时间掌握的技能。它给你“后悔药”，也给你审视 AI 工作的能力。

8. 常见问题与排查思路

配置和使用过程中难免遇到各类报错。这里整理一张常用排查表，遇到问题先对照查找。

排查建议遵循“由近到远”的顺序：先看本地基础环境，再看配置，最后看服务商状态。大多数本地问题集中在 PATH 和配置文件两项。

如果出现 codex is ignoring 1 unrecognized configuration setting. check for typos 这类提示，它其实已经告诉你方向了。打开 config.toml，找到多余的或拼错的字段，删掉即可。这类提示不会阻止 Codex 启动，但会提醒你配置不干净，最好处理掉，避免以后引发更隐蔽的问题。

9. 最佳实践与工程建议

当你能顺利跑通一个项目后，就要开始考虑使用质量了。AI 编程助手用得好不好，往往取决于使用习惯。

9.1 把需求拆成小任务

不要一上来就让 Codex“帮我做一个电商系统”。它虽然能生成一个庞大的骨架，但很可能包含大量你不需要的假设。更高效的方式是拆成可验证的小任务：

• 先生成数据模型。
• 再生成命令行接口。
• 再生成测试用例。
• 最后集成到一起。

每一步都可以独立运行验证，出问题也知道该找哪段逻辑。对新手而言，小任务的产出更容易看懂，也更容易学会判断对错。

9.2 密钥与敏感信息管理

API Key 是资源和费用的访问凭证，务必按下面的原则管理：

• 使用环境变量或 Codex 配置中的 env_key 引用，不要直接在代码或配置里写明文。
• 将 .gitignore 中加入可能包含密钥的本地文件，防止误提交。
• 如果怀疑密钥泄露，立即去服务商控制台吊销并重建。
• 在生产环境和敏感数据场景中，先用脱敏数据测试。

另外，发送给模型的内容会经过第三方服务。如果项目包含商业机密或个人隐私，尽量使用脱敏样本，避免直接发送原始敏感信息。

9.3 用 Git 兜底

我再次强调 Git 的价值。每次让 Codex 修改代码之前，建议先确认当前状态无碍：

bash复制git status

如果觉得改动较大，可以先提交一次，作为基线：

bash复制git add .
git commit -m "feat: 待办清单初始版本"

之后每次让 Codex 修改，都用 git diff 查看变化。这个习惯能让你对 AI 的改动保持掌控力，也方便对比不同方案。

9.4 选择合适模型与成本控制

大模型能力越强，通常单次请求成本越高、响应越慢。对于“生成一个简单脚本”这样的任务，不一定非要使用最强的旗舰模型。配置中改成参数量更小、速度更快的模型，往往体验更好。

实际项目中建议：

• 日常小工具、快速生成：选择响应更快的模型。
• 复杂架构分析、多文件重构：选择更强的高阶模型。
• 定期查看服务商的用量统计，及时发现异常消耗。

这里的核心思维是“为任务匹配工具”，而不是所有任务都用同一个模型。

10. 总结与后续学习路线

这篇教程带你走完了 Codex 的完整链路：从理解概念，到安装 Node.js、Git，再到安装 Codex CLI；从登录认证，到配置 API Key 和第三方兼容模型；最后通过待办清单脚本和 Bug 修复实战，体验了“描述需求 → 生成代码 → 运行验证 → 迭代修复”的完整流程。

如果接下来想继续深入，建议按下面的路线练习：

1. 场景预热：让 Codex 生成 3 个你想用的小工具，比如批量重命名文件、整理文件夹、定时提醒脚本。重点锻炼需求描述能力。
2. 项目扩展：在待办清单项目上继续加功能，比如优先级、截止日期、搜索功能，让 Codex 逐步修改文件。
3. 版本控制：熟悉 git init、git add、git commit、git diff、git checkout 五个命令，成为 AI 协作的基本功。
4. 代码可读性：让 Codex 为每个命令加上中文注释，并解释关键函数的作用，用这种方式反向学习代码思路。
5. 测试意识：让 Codex 生成一个简单的测试脚本，学会验证“改动没有破坏已有功能”。

这条路径上的每一步都不需要你先成为程序员，但会让你越来越像一个会用工具的开发者。AI 编程工具最大的价值不是替代你写代码，而是帮你把想法快速变成可运行的东西，再让你在验证和修改中逐步理解技术逻辑。后续遇到新的报错或配置问题，也别忘了回到这篇文章的排查表，按照“基础环境 → 配置文件 → 服务商状态”的顺序逐项检查，多数问题都能自己解决。