最近很多开发者开始尝试 Codex CLI它不是一个图形界面软件而是跑在终端里的 AI 编程助手。你可以把它理解成一个能直接读写项目文件的“命令行队友”让它写代码、改 bug、搭脚手架、解释一段陌生代码都能在终端里完成。这篇教程按目前最新稳定版流程整理从零开始讲安装、配置、第一次调用以及国内开发者最容易踩的报错坑。如果你正打算把 Codex 跑起来但又不想被各种环境问题卡住可以先花几分钟看完这篇再动手。先说一个容易误会的点Codex CLI 本身是开源免费的命令行工具但“免费”不等于不配置任何模型凭据。工具安装不花钱真正产生成本的是调用模型 API。所以这篇文章会把“安装工具”和“配置模型”分开讲这样你就能清楚自己卡在了哪一步。1. 先搞清楚 Codex 是什么以及“免费”指的是什么1.1 一个命令行里的 AI 编程助手到底能做什么Codex CLI 是 OpenAI 推出的命令行编程助手核心思路是让你在终端里直接和 AI 对话让它帮你完成代码任务。和很多聊天式工具不同Codex 是以“代理”方式工作它在你的项目目录下运行可以读取文件内容、修改代码、执行命令然后根据执行结果继续调整。日常能做的事情大致包括根据一段自然语言需求直接生成一个完整文件或函数修改现有代码比如重命名变量、补全异常处理解释项目里陌生的代码逻辑为代码写单元测试、注释、README多轮对话反复调整生成结果如果你用过 Claude Code会发现两者形态很接近都是命令行 Agent。Codex 更贴近 OpenAI 生态默认模型和相关接口都来自 OpenAI 体系但它的提供方机制也支持接入其他兼容模型服务。1.2 安装前需要准备的 4 样东西零基础用户最容易犯的错是直接跑到命令安装环节结果环境缺这个缺那个。建议先按清单确认Node.js。Codex CLI 是通过 npm 发布的 Node.js 工具需要 Node.js 18 或更高版本具体以当前官方 README 要求为准。Git。Windows 下强烈建议安装 Git for Windows因为它自带 Git Bash很多命令行工具在 bash 环境里跑得比 CMD 和 PowerShell 更稳定。终端工具。Windows 推荐 Windows TerminalmacOS 用自带终端即可Linux 只要你的 shell 环境正常就行。模型 API 凭据。OpenAI 官方服务需要 OpenAI API Key如果使用第三方兼容服务也需要对应服务的 API Key 和 base URL。这里不需要额外安装 Python、MySQL、Docker 之类的东西也不要被其他安装教程带偏。Codex 的使用门槛主要是 Node.js 环境和 API 配置不是大型软件环境。1.3 新手最容易忽略的三个概念第一个是 PATH。安装完 npm 全局包后终端能不能直接执行codex命令取决于 npm 的全局 bin 目录有没有写进 PATH。很多“command not found”问题都出在这里。第二个是终端和 IDE 的差别。你在 VS Code 里打开终端和你在桌面端 Codex 应用里调用 CLI是两套不同的查找逻辑。桌面端或插件往往会额外要求指定 CLI 可执行文件路径否则就会出现“找不到 codex cli binary”的错误。第三个是 API 端点。Codex 默认会向 OpenAI 的接口发请求但如果你配置了第三方兼容服务就必须改 base URL 和模型名。很多人明明安装成功却一直报错问题不在安装而在请求发到了不支持的接口。2. 从零开始安装 Codex CLIWindows / macOS / Linux 通用流程2.1 第一步安装 Node.js 和 Git如果电脑上还没有 Node.js去官网下载 LTS 版本的安装包即可。安装时保持默认选项Windows 用户注意勾选“Add to PATH”这类选项。装完打开一个新终端执行node -v npm -v两个命令都能输出版本号说明 Node.js 环境正常。Git 的安装同理。Windows 用户下载 Git for Windows 安装包安装时可以保留默认配置Git Bash 组件建议选上。macOS 用户一般自带 Git如果没有就执行xcode-select --install。Linux 用户按发行版包管理安装即可例如 Ubuntu 下sudo apt update sudo apt install git这一步不复杂但它是后面排查问题的基础。很多报错看起来是 Codex 的问题实际是 Git 或 Node.js 环境有问题。2.2 第二步用 npm 镜像安装 openai/codex国内开发者直接访问 npm 官方源有时会比较慢甚至出现连接超时。我一般会先把 npm 的 registry 切到镜像源比如 npmmirrornpm config set registry https://registry.npmmirror.com设置完成后可以用npm config get registry确认输出的是镜像地址然后再全局安装 Codex CLInpm install -g openai/codex安装过程中如果出现权限错误Windows 用户可以尝试用管理员身份打开终端macOS 和 Linux 用户如果遇到 EACCES 权限问题不要直接忽略先排查 Node.js 安装目录的权限再决定是否需要加 sudo。安装成功后npm 会输出 Codex 的版本信息。不同版本可能存在差异但只要命令能正常安装后续的配置流程基本一致。2.3 第三步验证安装结果安装完先做一次最小验证codex --version如果能够输出版本号安装环节就结束了。如果提示找不到命令先执行npm prefix -g这个命令会输出 npm 全局包的安装目录例如 Windows 下可能是C:\Users\你的用户名\AppData\Roaming\npm把这个目录加入系统 PATH 后重新打开终端再执行codex --version。macOS 和 Linux 用户则检查对应 shell 的配置文件比如.bashrc或.zshrc。2.4 升级与卸载Codex CLI 更新速度不慢过一段时间就会出现新版本。升级命令很简单npm update -g openai/codex卸载则是npm uninstall -g openai/codex升级前可以先跑一次codex --version记录旧版本号升级后再对比避免因为缓存导致版本没变。3. 第一次运行 Codex登录、提问、完成一个真实小任务3.1 登录与密钥配置Codex 安装完成后第一次运行需要处理模型凭据。如果你使用 OpenAI 官方服务通常需要配置 OpenAI API Key这个 Key 可以在 OpenAI 开发者平台创建。环境变量是常见做法。Windows PowerShell 里可以临时设置$env:OPENAI_API_KEY你的API KeyLinux 或 macOS 的 bash 里可以执行export OPENAI_API_KEY你的API Key但终端关闭后环境变量就失效了。长期使用更推荐写进 shell 配置文件或使用 Codex 自身的登录机制。Codex CLI 支持通过浏览器登录 ChatGPT 账号具体入口在运行codex后会出现提示。这里有个关键点浏览器登录和 API Key 是两种不同的认证方式错误提示也不一样。如果登录后提示“登录失败”或“认证无效”优先检查网络可达性、账号状态以及是不是用了不支持登录的第三方模型服务。3.2 用一行命令验证连通性建议不要一上来就跑大型任务先做一次最小请求。在任意目录打开终端执行codex exec 用一句话介绍你自己如果配置正确Codex 会返回一段简短回答。这一步能同时验证三件事CLI 能启动、模型凭据有效、网络能到达 API 服务。如果这一步就失败后面所有项目操作都不用试了先解决连通性问题。这里最容易踩的坑是把项目目录打开后直接让 Codex 改代码结果模型没连通AI 把“失败”当成“没输出”反复空转。先跑通一条简单消息能省很多时间。3.3 交互式对话和文件操作示例连通性没有问题后可以进入交互式会话。直接在项目目录运行codex进入交互模式后你可以输入中文或英文需求Codex 会读取当前目录下的文件并根据任务执行修改。例如在一个空项目里输入创建一个 Python 脚本读取当前目录下 data.csv 文件计算每一列的平均值并输出到 result.txtCodex 会生成对应脚本必要时会创建文件、修改代码甚至执行命令。你可以继续追问细节让它补充异常处理、命令行参数、测试用例等。我建议第一次实操时单独建一个测试目录里面放一份简单的 CSV 文件避免 Codex 在真实项目里乱改代码。等它表现出足够稳定后再拿到正式项目里去用。3.4 输出结果怎么检查Codex 完成任务后你不仅要注意它生成了什么还要主动检查三个地方文件是否真的创建到了预期目录文件名和内容是否完整代码是否能运行是否存在缺失引用的库日志中是否有“权限不足”“文件不存在”“命令失败”等警告AI 生成代码不是重点重点是你有没有验证能力。一个能正常结束任务的 Codex生成的代码也可能因为环境差异跑不起来。所以每次跑完后自己执行一遍再交给它修复这是最稳妥的用法。4. 把 Codex 接入 VS Code / 桌面端解决找不到 CLI binary 的问题4.1 IDE 集成的基础逻辑很多用户不满足于只在终端里用 Codex还想把 Codex 接到 VS Code、Cursor 或桌面端 App 里。这样可以在编辑器里选中代码再让 AI 进行修改。这里的核心逻辑是IDE 插件或桌面应用本身不包含 Codex 核心而是调用你已经安装好的 CLI。所以它必须先知道codex这个命令在哪里。如果找不到就会报类似错误unable to locate the codex cli binary遇到这种问题先别急着卸载重装。它大概率不是 Codex 坏了而是应用找不到 CLI 路径。4.2 unable to locate the codex cli binary 怎么排查排查顺序可以固定成三步。第一步在系统终端里执行codex --version如果这个命令都报错说明 CLI 本身没装好先去处理 PATH 问题。第二步找到codex的实际路径。Linux 和 macOS 用which codexWindows 下如果codex是一个.cmd文件可以先执行where codex第三步把路径填进 IDE 或桌面端的设置里。比如 VS Code 的相关扩展设置中如果有Codex CLI Path之类的选项就填which codex或where codex输出的完整路径。如果设置了路径仍然报错Windows 用户要特别注意某些应用无法直接执行.cmd文件这时可以在设置里指定bash路径或者改用 WSL 环境运行 Codex。用 Git Bash 打开终端并执行codex --version如果 Git Bash 里能正常执行说明 Windows 下端到端链路是通的问题只是应用解析命令的方式不同。4.3 通过环境变量指定 CLI 路径部分应用支持通过环境变量指定 CLI 路径。根据报错信息里的提示可以设置类似这样的变量export CODEX_CLI_PATH/usr/local/bin/codexWindows PowerShell$env:CODEX_CLI_PATHC:\Users\你的用户名\AppData\Roaming\npm\codex.cmd设置完环境变量后一定要重新启动应用不能只关掉当前窗口。如果应用有缓存最好重启一次进程。需要注意的是不同版本对环境变量名的要求可能有差异有的读CODEX_CLI_PATH有的读CODE_CLI_PATH或其他配置项。最可靠的方式是看应用里的占位提示或打开设置面板搜索 “CLI path”。不要盲目照搬网络上的环境变量名。4.4 在 Windows 上推荐用 Git Bash 或 WSL 运行Windows 的 CMD 和 PowerShell 对路径、引号、命令格式的处理并不完全一致。Codex 这类工具在 bash 环境里运行通常更顺畅。Windows 用户可以考虑三种运行方式Git Bash安装 Git 后自带最轻量适合大多数人WSL适合需要在 Linux 环境里跑项目的用户隔离性好Windows Terminal PowerShell如果已经配置好 PATH也能用但遇到奇怪路径问题时要多留个心眼如果你同时装了多个 Node.js 版本比如 nvm-windows 或 Volta那么 PATH 里的codex可能来自某个特定版本。IDE 应用读到系统级 PATH和你当前终端里的 PATH 不一致时也容易报找不到 CLI。遇到这种情况直接在应用里填写绝对路径最省事。5. 国内开发者的模型接入思路从 OpenAI Key 到兼容接口5.1 为什么不是“装完就能用”Codex CLI 是一个客户端工具它并不自带模型能力。安装成功后还需要一个能响应请求的模型服务。很多国内新手卡在这里以为是安装没成功其实是没有可用的模型凭据。如果你有 OpenAI API Key可以直接用官方服务。但更常见的场景是开发者希望使用在国内网络环境下更容易访问或更便宜的模型服务。这时候可以把 Codex 的模型提供方指向一个 OpenAI 兼容接口。所谓“兼容接口”简单说就是某服务商提供了和 OpenAI API 格式相近的接口。Codex 按 OpenAI 格式发请求服务商按相同格式返回结果这样 Codex 就能用上第三方模型。5.2 配置兼容服务端点以 DeepSeek 为例社区里比较常见的做法是把 Codex 接入 DeepSeek。这里不讨论具体费用和额度只讲通用配置思路。通常需要两个信息base URL即服务商文档里提供的 API 基础地址API Key在服务商平台创建然后通过环境变量覆盖默认端点例如在终端里执行export OPENAI_BASE_URLhttps://api.deepseek.com export OPENAI_API_KEY你的DeepSeek Key在 Windows PowerShell 里对应$env:OPENAI_BASE_URLhttps://api.deepseek.com $env:OPENAI_API_KEY你的DeepSeek Key设置完成后先执行codex exec 你好请回复正常如果成功说明该服务商的接口可以被 Codex 使用。如果还没有成功不要急着调参数先看 Codex 的日志或错误信息确认请求到底打到了什么地址。这里必须强调不同服务商的兼容程度不一样。有的服务商只支持/chat/completions这类传统端点而新版 Codex 可能默认走/responses端点。两者不兼容时就会报接口错误或模型不支持。5.3 模型名和 /responses 端点不兼容怎么办有一种报错很典型请求发出去了但接口返回“模型不支持”。这种问题通常不是因为你的模型不存在而是 Codex 默认请求的模型名与当前服务商不匹配或者服务商根本不支持/responses类型的请求。处理顺序建议如下查看 Codex 当前配置里的模型名确认它是官方默认模型还是你手动指定的模型去服务商文档确认它支持哪些模型名以及是否兼容 Codex 使用的接口类型如果服务商只支持 chat completions 接口可以尝试换一个支持更高版本接口的服务商或者在 Codex 配置里显式指定旧版接口查看 Codex 的详细日志拿到请求返回的完整 HTTP 错误体不要看到“model is not supported”就以为要换更贵的模型。很多时候问题只是模型服务商与 Codex 的接口协议没有对齐。5.4 成本和额度怎么控制使用第三方兼容服务成本通常比官方 API 更直观但不同服务商的计费方式不一样。我在实际使用中会关注这几个指标单次请求消耗的输入 token 和输出 token模型是否支持流式输出流式输出会不会额外计费账户是否有日限流超出后是报错还是排队是否支持用量查询能否设置消费告警尽量在 Codex 配置里把上下文窗口和最大输出 token 控制在一个合理范围不要一上来就让它读取整个项目所有文件。Codex 会把读取到的文件内容作为上下文发送给模型文件越大消耗越高响应也越慢。如果你是学习用途可以用额度较小的账户先试或者使用提供免费额度的平台。但要注意任何平台的免费额度都有使用期限或次数限制不要把“能用”当成“永远免费”。6. 常见报错与排查顺序先看现象再查环境6.1 npm 安装失败现象执行npm install -g openai/codex时卡住或直接报 404、ETIMEDOUT。排查顺序先执行npm config get registry确认 registry 是官方源还是镜像源如果是官方源建议切换到 npmmirror 镜像后重试再确认 Node.js 版本是否过低升级到 LTS 版本查看 npm 缓存和日志必要时执行npm cache clean --force后再试试如果安装过程中出现 permission deniedWindows 先检查是否用了管理员终端macOS/Linux 检查 Node.js 安装目录属主不要急着用 sudo 绕过。6.2 codex 命令不存在现象终端输入codex --version提示 command not found。大概率是 npm 全局 bin 目录没有加入 PATH。先用npm prefix -g找到目录把目录加到 PATH再重启终端。如果重启后仍然不行检查是不是装了多个 Node.js导致codex被安装到了另一个版本目录下。另外提醒一下在 Windows 上设置完 PATH 环境变量后已经打开的终端不会自动读取必须打开新的终端窗口。6.3 登录失败 / API Key 无效现象Codex 提示认证失败、登录失败或 API Key 无效。先确认三件事Key 是否复制完整有没有多余空格或换行账户是否还有额度试一下服务商平台的网页端接口环境变量名拼写是否准确PowerShell 和 Linux 的语法是否有误如果使用官方 ChatGPT 账号登录而不是 API Key那么要确认当前网络能否访问 OpenAI 服务。这里不讨论任何非官方访问方式只建议你确认自己的网络环境是否符合服务方的要求。6.4 请求超时 / 响应失败现象Codex 启动了但执行任务时长时间没有输出或者提示超时。先看请求有没有发出。可以在终端里开启 debug 日志观察是否发到了正确地址。然后看错误是超时、限流还是响应格式错误。常见原因包括上下文文件太多单次请求过大模型服务商限流返回 429 Too Many Requests网络不稳定请求被中断模型名写错服务商返回 404 或模型不存在处理方式不是马上加大超时时间而是先缩小任务范围。让 Codex 只处理一个文件减少上下文再逐步扩展。6.5 网络或镜像问题导致的依赖安装异常国内环境安装依赖时除了 npm 镜像还可能遇到 GitHub 下载失败、某些二进制依赖下载超时等问题。如果安装过程中卡在某个二进制下载阶段通常不是 Codex 本身的问题而是对应的 CDN 源不稳定。可以尝试切换 npm 镜像源设置 HTTP 超时时间参数使用包管理工具自带的镜像配置在官网下载安装包手动安装不建议在安装失败后反复执行同一个命令不加思考。先看报错日志里的具体 URL再判断是网络问题还是权限问题。6.6 使用日志定位问题Codex 一般会提供日志输出机制。推荐在排查问题时开启 verbose 或 debug 模式具体命令可以通过codex --help查看。日志会记录请求地址、模型名、HTTP 状态码和错误响应体这些信息比界面上的报错提示准确得多。我自己的排查习惯是先复现问题记录完整报错看请求发到了哪个地址看返回的 HTTP 状态码和错误体检查环境变量和配置文件最后才考虑重装版本这个顺序能避免很多重复劳动。我个人更建议先把单任务跑稳再考虑把 Codex 引入正式项目。Codex 这类命令行工具安装其实只占一小半剩下大量时间都是在处理 API 端点、模型配置和环境差异。尤其是使用第三方兼容服务时一定要确认服务商支持 Codex 实际调用的接口类型。遇到报错不要急着重装先开日志、看环境和模型名大多数问题都能在信息里找到答案。