最近 GitHub 和开发者社区里，Codex 的讨论度明显高了不少。Codex 是 OpenAI 推出的编程智能体工具，目前最常见的使用形态是终端客户端 Codex CLI，另外还有桌面版入口。很多人把它当成一个“能聊代码的聊天机器人”，其实不太准确。Codex 的核心能力是直接读文件、改代码、跑命令、看运行结果，然后根据结果继续调整，更像一个在项目目录里替你干活的 AI 工程师。
这篇教程按实际踩坑顺序来写：Codex 是什么、需要什么环境、怎么安装 npm 版、怎么配置接口、怎么跑通第一个任务、常见报错怎么查。适合第一次接触 Codex、想快速上手的开发者，也适合那些已经装到一半但卡在配置和报错上的人。先说一个关键判断：Codex CLI 安装本身不收费，但运行它需要有一个能正常响应的模型接口。你手里有什么接口，就按对应方式配置，不要依赖来路不明的共享接口跑真实项目。
1. 先搞清楚 Codex 是什么，再决定怎么安装
1.1 Codex 不是网页聊天窗口，它是一套终端编程智能体
Codex 与普通 AI 聊天工具最大的区别是：它不只在对话框里给答案，而是能真正操作你的项目。你把任务描述给它之后，它通常会经历这么几步：
- 读取当前目录下的文件结构，理解项目上下文。
- 列出准备执行的计划，比如“先看哪个文件”“要改哪里”。
- 请求你的确认，然后修改文件或执行命令。
- 根据终端输出判断结果，如果有报错就继续调整。
所以它解决的问题不是“帮我写一段代码”，而是“帮我把这个任务从头到尾执行完”。比如你给它一个 Python 脚本，说“这个脚本读文件时报编码错误，帮我修一下”，它会先打开脚本，定位读文件那部分，再看你的运行环境，然后修改代码并尝试重新运行。
有一点需要提前区分：Codex 这个名字历史上指过 OpenAI 的代码模型，但现在社区里讨论的 Codex，更多是指这套终端编程智能体工作流。下载安装时不会混淆，但看资料时容易懵。
1.2 安装前先确认环境，不要想着一路 Next
Codex 不要求高端显卡，也不需要本地跑大模型，真正消耗的是后端模型接口。所以在安装之前，先对照下面这张表确认条件：
| 项目 | 建议要求 | 原因 |
|---|---|---|
| 操作系统 | Windows 10/11、macOS、主流 Linux 发行版都可以 | Codex CLI 是跨平台工具 |
| CPU / GPU | 没有特殊要求 | 计算在接口服务端完成 |
| Node.js | 建议 18 或更高版本，具体以官方要求为准 | Codex CLI 是 Node.js 应用，npm 负责安装 |
| git | 建议安装 | 查看代码改动、回滚实验结果非常有用 |
| 终端 | Windows 建议 PowerShell 或 Windows Terminal | 交互式命令体验更稳定 |
| 后端接口 | 至少有一个能访问的模型 API 服务 | 没有可用接口时，Codex 只能启动，不能干活 |
很多人卡在最后一行。装 Codex 只需要 Node.js 和 npm，但“能不能用起来”取决于有没有可访问的接口。这个接口可能是你自己的账号，也可能是某个兼容模型服务平台。越早把接口问题想清楚，后面配置越省事。
1.3 本地 CLI 和容器化方式怎么选
Codex 有本地 CLI 方式，也有官方提供的容器化方式。新手我建议优先走本地 CLI，理由很简单：排错路径短，反馈直接。
容器化的好处是隔离干净，适合做批量实验或者不想污染本机环境。但它的成本也很明显：你得会 Docker，还要处理容器内外的目录挂载、网络连通、权限映射。如果你现在只是想“先跑通一个任务”，没必要让问题链变得更长。
如果你已经熟悉 Docker Desktop，可以去看官方文档里的镜像用法。如果不熟，建议先跳过容器方案，把精力放在 CLI 安装和接口配置上。Codex 的能力差异不在安装方式，而在你用哪个后端模型、任务拆得是否合理。
2. 安装 Codex：从 Node.js 到 CLI 的最小流程
2.1 先准备 Node.js 和 npm 工具链
安装 Codex 前，先检查本机有没有 Node.js。打开终端，执行：
node -v npm -v如果能正常输出版本号，说明工具链已经具备。比如v20.11.0这样的输出就是正常的。如果提示node: command not found，说明没有安装 Node.js。
安装 Node.js 的路径有很多，我建议按系统选：
- Windows：到 Node.js 官网下载 LTS 版本安装包，或者用包管理器安装，比如
winget install OpenJS.NodeJS.LTS。 - macOS：推荐先装 nvm，再通过 nvm 安装 Node.js，方便以后切换版本。
- Linux：发行版软件源装出来往往较旧，容易踩版本坑，推荐用 nvm 或者直接装官网二进制包。
装完之后一定要重启终端，再执行node -v确认。为什么？因为环境变量 PATH 的更新需要新终端进程才生效，Windows 上更明显。
这里给一个 nvm 的通用安装思路，具体命令要以 npm 官网或 nvm 官方 README 为准：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新加载 shell 配置，再执行nvm install --lts安装最新 LTS 版本 Node.js。
2.2 用 npm 全局安装 Codex CLI
工具链就绪后，安装 Codex 的命令很简单：
npm install -g @openai/codex全局安装的意思是：把codex命令装到系统全局目录，任何路径下都能直接调用。不加-g的话，命令只存在于当前项目的node_modules/.bin里，使用起来不方便。
如果你的 npm 源是默认源，但下载速度很慢，可以先切换 npm 镜像源，再执行安装：
npm config set registry https://registry.npmmirror.com这是 npm 仓库镜像，属于常规开发配置，不是绕过什么限制，可以放心用。装完之后如果后续装其他包也需要镜像源，保留这个配置即可。
安装过程中如果报 EACCES 权限错误，常见原因是你当前的普通用户没有全局目录写权限。不要直接加sudo强行装，更稳妥的方式是按 npm 官方文档修复全局目录权限，或者改用 nvm 管理的 Node.js 版本。因为sudo npm -g会改变全局文件的属主，后面升级 Node.js 时容易出各种奇怪问题。
以后想卸载重装，用：
npm uninstall -g @openai/codex2.3 验证安装：version、help、路径三连查
安装完成后，先执行：
codex --version如果输出版本号，说明可执行文件已经装好了。接着执行：
codex --help看它支持哪些子命令，比如登录、执行任务、查看配置之类的入口。不同版本命令可能有差异，以你本机的--help输出为准。
如果提示command not found，先别急着重装，按顺序排查：
- 用
npm prefix -g查看 npm 全局安装目录。 - 看这个目录是否在 PATH 环境变量里。
- Windows 用户重启终端后再验证；macOS / Linux 用户检查
~/.zshrc或~/.bashrc是否导出对了路径。
这一步非常值得花两分钟做完整。很多“安装失败”其实是路径问题，不是 Codex 本身的问题。
3. 配置 API：登录、密钥、Base URL 和模型参数
3.1 三种常见配置方式，先认清你是哪一种
Codex 装好后，还需要告诉它“用哪个接口干活”。常见配置方式有三种：
| 方式 | 需要什么 | 适用场景 |
|---|---|---|
| ChatGPT 登录 | 能访问的 ChatGPT 账号，执行登录流程 | 只想体验官方能力 |
| OpenAI API Key | 有效的 API Key | 已经申请过 OpenAI API |
| OpenAI 兼容服务 | API Key 和服务地址 | 用的第三方兼容接口，比如 DeepSeek |
很多人把“安装 Codex”和“配置接口”混在一起，其实它们是两件事。安装解决的是“命令能不能启动”，配置解决的是“任务能不能执行”。
如果你的账号体系支持codex login登录，可以先走官方登录流程，终端会提示你打开浏览器授权。这种方式最省心，因为你不用手动填 Key。但要明白一点：官方登录页能不能访问、登录后有没有可用额度，取决于你本地网络环境和账号本身的权限。
如果你走 API Key 路线，核心就是设置两个环境变量：一个是OPENAI_API_KEY，一个是OPENAI_BASE_URL。前者是身份凭证，后者是接口地址前缀。
3.2 环境变量和配置文件，先测试再持久化
在终端里临时设置环境变量，可以看到立即可用的结果。macOS / Linux 下这样写：
export OPENAI_API_KEY="sk-你的密钥" export OPENAI_BASE_URL="https://api.example.com/v1" export OPENAI_MODEL="你的模型名"Windows PowerShell 下这样写：
$env:OPENAI_API_KEY = "sk-你的密钥" $env:OPENAI_BASE_URL = "https://api.example.com/v1" $env:OPENAI_MODEL = "你的模型名"设置完之后，先启动 Codex，跑一条最简单的任务。跑通了，再把环境变量写进~/.bashrc或~/.zshrc，实现持久化。
为什么不直接写配置文件？因为 Codex 的配置文件在不同版本里路径和字段可能有差异。常见目录是用户主目录下的.codex文件夹，里面可能是config.toml，但实际字段名要以当前版本的codex --help和官方文档为准。直接用环境变量验证，不用猜配置文件格式，是最稳的排查方式。
还有一个重要概念：Codex 默认走 Responses API 格式，也就是请求/responses这个 endpoint。如果你接的第三方服务只提供旧版的 Chat Completions 接口，且不支持 Responses API，就会在请求阶段报错。这时候不是 Key 的问题，而是接口协议不匹配。遇到这种情况，先去看你使用的 Codex 版本是否支持切换协议模式，或者换一个兼容 Responses API 的服务。
3.3 用 cc-switch 这类小工具管理多套配置
如果你有多套接口配置，比如本机开发环境一套、测试环境一套，手动改环境变量会非常累。社区常用的做法是使用 cc-switch 这类配置管理小工具。
cc-switch 的作用不神秘，它本质上就是帮你切换配置文件或环境变量组合。你提前录入几套配置，需要切到哪套就点一下切换，避免每次手动改 Key 和 Base URL。
使用这类工具时有一个重点：切换配置之后，一定要开一个全新的终端窗口再启动 Codex。因为环境变量是进程级的，旧终端里还保留着上一套配置，直接在当前终端启动 Codex，它会继续用旧配置，看起来就像“切换后没有生效”。
另外，多套配置本身会给排错增加复杂度。如果任务失败，先确认当前终端里导出的是哪套 Key、哪个 Base URL、哪个模型名。经验是：90% 的“切换后报错”都是新旧终端混用导致的。
4. 从零跑通第一个 Codex 任务：新建项目、改 bug、执行命令
4.1 建一个空实验目录，任务要足够简单
第一次跑 Codex，不要直接扔一个生产项目给它，也不要让它完成“搭建一个电商系统”这种大任务。建议建一个完全空的目录，做一次最小验证。
mkdir codex-demo cd codex-demo codex启动后进入交互界面，给它一条具体的任务：
“在当前目录下创建一个 Python 脚本 word_count.py，读取 demo.txt 文件，统计每个单词出现的次数，并按次数从高到低输出。然后再创建一个 demo.txt，里面放几行测试文本。”
这个任务包含两部分：生成代码和创建测试文件，足够验证 Codex 是否具备文件读写能力，又不会复杂到难以判断结果。
第一次跑的时候，重点观察两个东西：一是它能否读取目录上下文，二是它执行每一步前是否会先请求你的确认。这些都正常，说明安装和配置已经没有大问题。
4.2 理解 approve 机制：它不是卡住，而是安全边界
Codex 在执行文件修改和命令运行时，通常会向你请求授权。终端里会出现类似“是否允许修改这个文件”“是否允许执行这条命令”的提示，你需要确认后它才会继续。
很多新手第一次看到这个提示会以为程序卡住了，实际上这是设计好的安全机制。因为 Agent 工具天然有执行权限，如果所有操作都自动放行，一旦任务描述有歧义或模型理解错误，它可能删除文件、覆盖配置、执行危险命令。
所以我的建议是：第一次使用，全程手动确认。先看它打算执行什么命令，再决定是否放行。比如它准备执行rm -rf或git reset --hard，就要特别谨慎。不要为了省事一上来就开启全自动批准。等你对工具行为足够熟悉，再考虑在低风险实验目录里调整授权策略。
4.3 验证结果：看文件、看 diff、跑命令
Codex 执行完任务之后，要按正常代码审查流程检查输出：
- 用文本编辑器或
cat查看生成的文件内容。 - 如果目录里有 git 仓库，先执行
git diff看改动细节。 - 自己手动运行一次它生成的脚本，确认结果是否可复现。
- 如果结果不对，把报错信息甩给 Codex，让它继续修。
比如刚才的单词统计任务，你可以自己执行：
python word_count.py看输出是否符合预期。如果报错，把完整报错贴回 Codex 对话里，让它分析原因。这时候的 Codex 更像是“能自己写代码并且自己验证”的协作者，而不是单纯生成代码的机器。
记住一个原则：第一个任务务必简单，简单到你能判断它的每一步行为是否正确。简单任务跑通之后，再逐步增加项目复杂度和任务粒度。
5. 常见报错排查：endpoint、模型不支持、登录失效
5.1 自定义接口请求 /responses 失败，先查地址再查模型
如果你配置的是自定义 Base URL，启动任务后请求/responses这个 endpoint 失败，是比较常见的报错类型。看到这类报错，先不要怀疑 Codex 没装好，按这个顺序查：
- 确认 Base URL 是否和你的服务商文档一致，注意有没有
/v1后缀，多一个少一个都会出问题。 - 确认 API Key 是否有效，可以先用 curl 直接访问接口测试连通性。
- 看返回状态码：401 说明 Key 无效，404 说明路径不对，429 说明限流，5xx 说明服务端异常。
- 检查模型名是否在你的服务商可用模型列表里。
- 确认 Codex 发起请求的 API 协议，你的服务商是否支持。
这个排查顺序里，最容易被忽略的是第 2 步。直接在终端里用 curl 打接口，能快速把“Codex 问题”和“接口问题”分开。
5.2 model is not supported 报错，优先检查模型名和账号权限
类似the 'xxx' model is not supported when using codex with a ...这样的报错，字面意思是当前模型不受支持。它通常不是安装问题，而是配置问题。
可能的原因有三个：
- 模型名写错了。比如服务商提供的是
deepseek-chat，你写成了gpt-5.6-sol之类不存在的名字，请求自然会被拒绝。 - 当前账号没有该模型的访问权限。有些模型需要特定套餐或单独开通权限。
- 第三方兼容接口不支持 Codex 默认的模型行为，需要在配置里显式指定一个服务商支持的模型。
排查时，先执行env | grep OPENAI或直接在终端里输入codex --help看当前生效的模型参数覆盖。如果模型名是从配置文件或环境变量里设置的，改掉后再开新终端验证。
5.3 登录失效、Key 失效、额度不足，按状态码分层处理
Codex 运行过程中还会遇到账号和额度相关的问题。这类问题的典型现象是：任务刚开始就中断，或者请求发出后被拒绝。处理思路可以按状态码分层：
| 状态码 | 常见含义 | 处理方式 |
|---|---|---|
| 401 | 身份凭证无效 | 检查 API Key 是否正确、是否过期 |
| 402 | 需要付款或额度不足 | 到服务商控制台查看账单和额度 |
| 403 | 没有权限 | 检查账号套餐或模型权限 |
| 404 | 接口路径或模型名错误 | 对照服务商文档确认 Base URL 和模型名 |
| 429 | 请求过于频繁或限流 | 降低任务频率，等待一段时间 |
| 5xx | 服务端异常 | 暂时与服务商节点有关，稍后重试 |
如果走的是codex login官方登录流程，登录状态过期也会导致任务失败。一个建议是：每次大批量跑任务前，先跑一条最小任务确认登录态和额度都正常，不要等到批量任务跑到一半才发现 Key 失效。
6. 进阶用法和安全边界：接入第三方模型、适合场景、别踩的坑
6.1 接入 DeepSeek 等 OpenAI 兼容模型
如果你的网络环境访问官方接口不方便，或者你已经有国内可正常访问的模型服务，可以通过兼容接口方式接入。以 DeepSeek 为例，常见配置是：
export OPENAI_API_KEY="你的DeepSeek密钥" export OPENAI_BASE_URL="https://api.deepseek.com" export OPENAI_MODEL="deepseek-chat"具体地址和模型名，建议以 DeepSeek 平台最新文档为准，因为服务商调整配置是比较常见的事。
接入之后先跑一个最小任务，比如“写一个脚本判断一个数字是否为质数并运行验证”。这类任务能验证接口连通、模型推理、文件写入三个关键链路。
需要提醒的是：不是所有模型在 Codex 里的表现都一样。Codex 的 Agent 行为依赖模型对工具调用指令的理解能力。有经验的模型可能更懂得“先看目录再决定改哪个文件”，性能弱的模型可能只会生成一段代码，不会主动执行和验证。所以接入第三方模型后，要降低预期，先用小任务摸清它的边界。
6.2 哪些场景适合 Codex，哪些场景坚决不用
用了一段时间后，我总结出比较明显的边界：
| 适合场景 | 不适合场景 |
|---|---|
| 生成项目脚手架和脚本 | 直接修改生产环境核心代码 |
| 修复有明确报错的 bug | 执行高危命令（删除目录、重置数据） |
| 补测试、写注释、整理配置文件 | 处理敏感密钥、用户隐私数据 |
| 解释陌生项目的结构和逻辑 | 一次生成完整业务系统 |
| 在 git 仓库里做可回滚的实验 | 完全替代人工代码审查 |
适合场景有一个共同点：可验证、可回滚、风险低。比如生成的脚手架代码，你可以自己跑测试；修复 bug 后，可以用测试用例验证，错了再改。
不适合场景的风险主要来自 Agent 的“自主性”。你给它一个模糊目标，它可能做出一连串不可预期的操作。所以无论如何都要在 git 仓库里跑，让每一次改动都能通过git diff和git checkout恢复。
6.3 几个我踩过之后才知道的实操建议
如果现在重新走一遍，我会把这几件事放在最优先位置。
第一，小任务起步。不要一上来就让它修改几百个文件。先让它做一个简单脚本，确认它能读文件、写文件、执行命令，再逐步扩大范围。
第二，把大需求拆成小需求。Codex 更适合处理“改某个函数”“补某个模块的测试”这类中等粒度任务。你让它“重构整个项目”，它往往会大范围改动，你审查负担会成倍增加。
第三，批量化处理时不要开满并发。如果你有多个目录要处理，先跑一条，记录耗时和输出格式，再逐渐增加并发。很多问题不是模型能力不够，而是并发太高导致接口限流、输出混乱、日志难追踪。
第四，日志是你最好的排查入口。Codex 报错时，先看错误信息里的状态码、模型名、endpoint，再决定改配置还是改代码。不要一遇到问题就重装，那是最后手段。
第五，不要用共享免费接口处理真实项目。这类接口稳定性差，还容易被别人拿到你的代码和密钥。免费额度也许够体验一下，但长期使用要按照服务商正常规则来。
最后说一句个人经验：Codex 这类工具真正能不能落地，往往不是卡在安装那一步，而是卡在“后端接口是否可用稳定”“配置是否读对”“任务是否拆得够小”。先把单任务跑稳，再去想批量和复杂项目。把这三件事理顺，Codex 才能从“装好了”变成“真的能用”。
