最近后台收到不少关于 Codex 的私信大多集中在几个问题上Codex 怎么安装命令行工具为什么提示找不到能不能接入国产模型以及 Codex 和普通 AI 编程助手到底有什么区别。说实话Codex 的迭代速度非常快网上的教程今天还能运行明天可能就失效了。所以这篇文章我尽量不写死版本而是把底层逻辑和通用步骤整理成一条可以长期复用的路线从安装、配置、实战到排错一次讲清楚。如果你是完全没接触过 Codex 的新手可以按照前面的章节一步步操作。如果已经装过一些 AI 编程工具可以直接跳到第 5 节看实战或者到第 8 节查报错。整个教程的目标只有一个让 Codex 在你自己的电脑上真正跑起来并且知道它在做什么。1. Codex 到底是什么为什么大家都在用它1.1 从代码模型到 AI 编程代理很多同学第一次听到 Codex会以为它只是个“能写代码的大模型”。这个理解没有错但不够准确。Codex 这个名字在 OpenAI 的历史上承载过两层含义早期它是指一个专门用于代码生成的大模型GitHub Copilot 早期版本背后就用过相关技术而现在我们说的 Codex更多是指 OpenAI 推出的 AI 编程代理Agent它不再只是“生成一段代码给你看”而是可以在你的电脑或云端环境中直接执行任务读取文件、运行命令、修改代码、检查结果再根据反馈继续调整。换句话说传统的 AI 编程工具像“高级补全插件”你问一句它给你一段代码而 Codex 更像一个“结对程序员”你布置一个目标它会自己拆解步骤、动手操作、验证结果。这个变化是整个工具链使用方式最大的不同也是为什么 Codex 在使用时会有权限、审批、沙箱这些概念——因为它真的会改你的文件、跑你的命令。1.2 Codex 能做什么在你真正使用之前先建立对能力边界的认识会很有帮助。根据官方定位和社区实践Codex 目前常见的用途包括从零生成项目用一句话描述需求让 Codex 创建目录结构、写入初始代码、配置依赖。重构与修复在已有项目里定位 bug修复类型错误或者对某个函数做重构。批量文件操作重命名文件、统一代码风格、更新多个模块中的方法调用。执行命令和脚本调用 shell 命令运行测试根据测试结果修改代码。解释代码阅读你指定的代码片段或整个项目输出结构说明和文档。配合 IDE 与桌面端在编辑器里选中代码直接生成修改建议或在 ChatGPT 桌面端里以对话方式完成任务。需要注意的是Codex 并不是“一定成功”。它仍然可能误解需求可能改错文件也可能因为权限不足无法完成某些操作。它更像一个执行力很强的初级工程师需要你提供清晰的上下文并且在关键步骤做审查。1.3 Codex CLI、云端和 IDE 的区别现在打开 Codex 官方文档你会发现它有好几种入口新手经常被绕晕。我按使用场景简单区分形态使用场景适合人群Codex CLI在终端里执行任务可操作本地文件系统后端、脚本、项目级重构ChatGPT 桌面端内置 Codex在对话界面里调用本地 CLI 完成任务不习惯命令行的用户IDE 扩展在 VS Code 等编辑器中代码补全、修改日常编码、单文件修改云端 Codex在 OpenAI 云环境中运行隔离任务实验、批量任务、不操作本地环境这篇文章的核心会聚焦在 Codex CLI 上因为它是其他入口的基础。很多桌面端和 IDE 的功能底层都是调用同一个 CLI你只要把命令行版本搞明白其他入口遇到的报错也能迎刃而解。2. 环境准备与版本认知2.1 运行环境要求Codex CLI 本质上是一个 Node.js 编写的命令行程序所以对环境的要求并不复杂。理论上只要你的操作系统能运行 Node.js就可以安装 Codex CLI。常见的支持环境包括Windows 10/11推荐使用 PowerShell 或 Windows Terminal。macOSApple Silicon 或 Intel 都行。主流 Linux 发行版例如 Ubuntu、Debian、CentOS。如果你是在 Windows 上使用建议先确认系统已安装 Git Bash 或基于 Unix 的终端因为 Codex 在执行部分 shell 命令时更习惯 Unix 风格。不过这不是绝对限制官方会持续优化 Windows 支持。安装 Node.js 时建议选择 LTS长期支持版本避免使用过于激进的开发版。2.2 需要准备什么在安装之前你需要准备下面几样东西Node.js 环境建议版本高于 18具体以官方仓库要求为准。npm 包管理器一般会随 Node.js 一起安装。一个可用的 OpenAI 账号用于登录或获取 API Key。一个准备测试的空目录新手不要一上来直接对生产仓库操作。如果是接入第三方模型还要准备对应的 API Key。这里要特别提醒Codex 的更新速度非常快你在网上看到安装命令时先看一眼命令中的版本号是否过旧。如果你已经安装了旧版建议先执行npm update -g openai/codex再继续后面的操作避免因为版本不一致导致配置项不识别。2.3 版本选择建议有不少同学会搜“Codex 官网下载”和“Codex 安装包”但 Codex CLI 最稳的安装来源其实不是某个安装包站点而是 npm 和官方 GitHub 仓库。认准openai/codex这个 npm 包名以及 GitHub 上的openai/codex仓库基本不会错。第三方打包的“绿色版”“离线安装包”虽然也能跑但存在两个问题一是版本可能滞后二是无法确认是否被修改过。对于这种会执行本地命令的 AI 工具我强烈建议使用官方渠道哪怕多花几分钟安装也远比下载一个来路不明的压缩包安全。3. 安装 Codex CLI 的完整流程3.1 通过 npm 全局安装安装 Codex CLI 最常用的命令是npm install -g openai/codex如果你没有全局安装的权限可以在命令前加sudo但我更推荐使用 Node.js 的版本管理工具如 nvm来安装 Node这样就不需要 sudo 了。安装完成后可以执行下面两条命令确认版本信息和帮助说明codex --version codex --help如果codex命令找不到通常有两个原因npm 全局安装目录没有加入 PATH或者安装过程中出现了异常。Windows 上可以重新打开终端macOS 和 Linux 上可以检查~/.npm-global或 nvm 的 bin 目录。3.2 使用项目内安装可选如果你的团队希望固定 Codex 版本也可以不全局安装而是把它作为一个 npm 包放到项目里npm install --save-dev openai/codex npx codex --version这种方式的好处是不同的项目可以使用不同版本的 Codex避免某个项目升级后行为变化影响其他项目。缺点是每次调用要写npx codex稍微麻烦一点。对于个人使用全局安装更省事对于团队协作项目内安装更可控。3.3 安装常见问题安装过程中最常遇到的报错是EACCES permission denied也就是权限不足。出现这个问题时不要急着用sudo npm install去覆盖先检查一下 npm 的全局目录是否有问题npm config get prefix如果这个目录在系统级路径下比如/usr/lib/node_modules说明你需要 nvm 或修改 npm 全局目录。使用 nvm 后npm 会安装在用户目录下权限问题会少很多。如果你已经装好了 Codex但输入codex提示“command not found”可以在终端里执行which codex然后把输出目录加入 PATH或者在 ChatGPT 桌面端设置中手动填写这个路径。4. 配置登录与环境4.1 登录 ChatGPT 账号安装完成后第一次运行codex时通常会出现登录引导。如果你的账号支持 ChatGPT 登录可以运行codex login命令会打开一个浏览器页面授权后会把凭证保存到本机。这种登录方式适合有 ChatGPT 订阅的用户使用起来比较省心不需要自己管理 API Key。如果你的网络环境比较特殊或者所在网络无法正常访问 OpenAI 的登录页面我建议先不要登录转用 API Key 方式。这里不讨论网络访问问题只记住一点凭证安全比方便更重要不要把自己的登录态随便暴露给第三方脚本。4.2 使用 API Key 接入使用 API Key 的常见方式是在终端里设置环境变量export OPENAI_API_KEYsk-你的密钥如果是在 Windows PowerShell 中可以用$env:OPENAI_API_KEYsk-你的密钥设置好之后运行codex就不会强制要求浏览器登录了。当然不同的 Codex 版本可能对 API Key 的校验方式略有差异如果运行时报错提示“login required”或者“authentication failed”可以再执行一次codex login或者检查 API Key 是否有对应模型的访问权限。4.3 配置文件默认位置与基本字段Codex CLI 会把用户级别的配置放在~/.codex/config.toml。这个文件不是必须手动创建的首次运行后会自动生成。你可以在里面设置模型、审批策略、沙箱模式等。一个常见的配置示例如下# ~/.codex/config.toml approval_policy on-failure sandbox_mode workspace-write这里简单解释一下approval_policy on-failure表示只有在命令执行失败时需要人工确认。sandbox_mode workspace-write表示允许 Codex 在工作目录内写文件但对外部目录的操作会更严格。不同版本的配置字段可能有变化如果你修改后没有生效先运行codex --help查看当前版本的配置说明不要拿着过时博客的参数硬套。4.4 环境变量与敏感信息管理在配置文件中直接写 API Key 是方便但很危险。如果你把~/.codex/config.toml同步到 Git 或云盘密钥就泄露了。更好的做法是通过环境变量注入密钥配置文件只保留非敏感字段。如果你确实需要把配置文件发给别人参考记得先抹掉所有 token、key、secret 字段。生产环境里可以借助系统的密钥管理服务或者使用 dotenv 工具把 API Key 统一放在.env文件中并确保.env被加入.gitignore。这个方法不仅适用于 Codex也适用于所有 AI 工具。你可以从一开始就养成习惯命令与配置公开密钥永远私有。5. 第一个 Codex 实战自动完成一个小项目5.1 使用场景与准备工作为了让你直观感受 Codex 的工作方式我这里用一个最简单的场景在一个空目录里让 Codex 实现一个批量文件重命名工具。这个工具需要支持命令行参数允许用户设置目录路径、旧关键词和新关键词然后批量重命名所有匹配的文件。先创建目录并进入mkdir codex-demo cd codex-demo这个阶段不要放真实业务文件所有操作都在测试目录里进行。如果 Codex 出现了超出预期的行为最多也就是删除一个空目录或写几个临时文件风险可控。5.2 交互式模式直接运行codex会进入一个交互式界面类似一个带上下文的聊天框。你可以输入需求请帮我在当前目录实现一个批量文件重命名工具使用 Python 编写支持命令行参数目录路径、旧关键词、新关键词。需要处理文件名冲突打印每个文件的重命名结果。Codex 会先展示它的执行计划然后逐步创建文件。你可能会看到类似下面几个步骤读取当前目录结构。新建rename_tool.py。安装或检查依赖如果它认为需要。运行测试命令验证脚本。每一步都可能请求你的批准尤其是执行写文件或运行命令时。这就是前面说的审批策略在起作用。如果你觉得这一步没问题可以同意如果发现它准备删除重要文件可以直接终止会话。5.3 单次任务模式与沙箱权限如果你不想进入交互式界面也可以使用一次性任务模式codex --sandbox workspace-write 实现一个批量文件重命名工具目录参数用 --dir旧关键词用 --old新关键词用 --new使用 Python 实现--sandbox参数用来控制 Codex 的权限范围。常见选项有read-only只能读取文件不能修改。workspace-write可以修改当前工作目录。danger-full-access可以访问系统上的所有文件。新手阶段我建议从read-only开始先让 Codex 给出方案你确认后再用workspace-write执行。等熟悉了它的行为模式再决定是否需要更大的权限。在命令行里加--help可以看到当前版本支持哪些沙箱模式。5.4 结果验证与后续优化任务完成后目录下应该会出现一个 Python 脚本。你可以打开文件检查也可以直接运行python rename_tool.py --dir ./testfiles --old draft --new final这个阶段的核心不是“看 Codex 写出来的代码能不能跑”而是你能否理解它做了什么。如果脚本运行报错你不需要自己动手改可以继续问 Codex运行时报错了错误信息是xxx。请分析原因并修复。Codex 会根据你提供的文档或错误信息继续修改。经过两三轮迭代一个可用的工具通常就能成型了。这正是 Agent 模式最有价值的场景不是一次性生成完美代码而是在循环中不断修正直到满足目标。6. 在 ChatGPT 桌面端与 IDE 中使用 Codex6.1 ChatGPT 桌面端集成 Codex 的步骤很多同学是在 ChatGPT 桌面端里第一次看到 Codex 入口结果点击后提示找不到 CLI。其实这是正常现象因为桌面端本身并不包含 Codex 的执行引擎它需要在你的电脑上找到已经安装好的 Codex CLI。基本的集成步骤如下在终端中安装 Codex CLI并确认codex --version能正常输出。打开 ChatGPT 桌面端进入 Codex 或 Agent 相关设置页面。在设置中找到 Codex CLI 路径输入框。在终端执行which codex将输出的路径填入。重启 ChatGPT 桌面端。如果你已经安装了 Codex CLI但桌面端仍然找不到它极大概率是 PATH 环境变量没有在桌面端启动前加载或者路径填写不对。这种情况不会影响命令行使用只需要手动指定路径即可。6.2 解决“Unable to locate the Codex CLI binary”报错这是搜索量很高的一个报错典型信息是Unable to locate the Codex CLI binary. Set Codex CLI path or ensure the executable is in PATH.我从大量反馈里总结出三个主要原因Codex CLI 根本没有安装或者安装失败了。Codex CLI 安装在 PATH 之外桌面端无法自动发现。桌面端启动时没有重新读取环境变量导致 PATH 里暂时找不到。排查顺序很简单。第一步在终端执行codex --version如果提示command not found说明 CLI 没装好回到第 3 节重新安装。如果版本号正常输出就执行which codex把路径填到桌面端的 Codex CLI 路径设置里然后重启应用。最后如果你用的是 Windows注意 npm 全局目录可能会在%APPDATA%\npm需要把这个目录同时加入系统 PATH。6.3 IDE 扩展的基本用法除了桌面端Codex 也提供 IDE 扩展常见的有 VS Code 版本。在扩展市场中搜索 Codex安装后通常会在侧边栏出现一个面板或者在编辑器里通过右键菜单触发选中代码后让 Codex 解释这段代码在做什么。选中代码后让 Codex 生成修改建议。在终端面板里直接运行codex与命令行完全一致。IDE 扩展的本质仍然是调用 Codex CLI所以配置登录、API Key、沙箱权限这些步骤和命令行完全一样。遇到插件连接不上、任务无响应时先确认不是 CLI 版本过旧然后重启 VS Code问题一般就能解决。7. 进阶Codex 接入 DeepSeek 等 OpenAI 兼容模型7.1 为什么要接入第三方模型官方 Codex 默认使用 OpenAI 的模型效果虽然好但并不是所有团队都有可用的账号和额度。于是很多人开始尝试把 Codex 接到第三方模型服务上其中 DeepSeek 是比较热门的选择。DeepSeek 提供 OpenAI 兼容接口理论上可以让 Codex 这类工具通过基础 URL 的变化来调用它的模型。不过我要提前说明一句Codex 对模型的指令遵循能力、工具调用能力要求很高第三方模型的表现会随模型版本和评测数据不同而变化。接入后如果 Codex 经常理解错指令不一定是 Codex 本身的 bug可能是当前模型对 Agent 任务的适配度不够。7.2 配置思路与环境变量示例接入第三方模型的通用思路是把原来的 OpenAI 端点换成第三方服务的端点把 API Key 换成第三方服务的 Key。在命令行中可以用环境变量临时指定export OPENAI_BASE_URLhttps://api.deepseek.com/v1 export OPENAI_API_KEY你的DeepSeekKey export OPENAI_MODELdeepseek-chat codex这段配置在部分版本中是有效的但不同版本的 Codex 对环境变量的支持情况不同。如果设置后没有生效你可以查看~/.codex/config.toml