OpenAI Codex CLI 安装配置实操：从 npm 安装到接入 DeepSeek

这次我们直接看 OpenAI 官方开源的 Codex CLI。简单说它是一个跑在终端里的 AI 编程助手安装完成后你可以用自然语言直接派活读一下 src 目录的代码结构给这个函数补单元测试把这段 JSON 解析逻辑改成异步处理。Codex 会自己读文件、改代码、执行命令然后把改动以 diff 形式展示给你确认。它解决的并不是在聊天框里问一句怎么写代码的问题而是让 AI 在真实项目里自动完成一段编码任务的问题。从大家搜索的热词来看目前关注点集中在五件事codex 安装方式、codex 官网入口、codex 使用教程、codex 接入 DeepSeek、以及 ChatGPT 桌面端报 unable to locate the codex cli binary 这类错误。这些内容本文都会展开。门槛方面如果你只想快速试用Node.js 环境加一条 npm 命令就够了如果你想换用 DeepSeek 等 API 服务也不需要额外安装第三方工具改一个配置文件就能接上。这篇文章会按环境准备、安装启动、登录认证、功能测试、自定义模型接入、桌面端联动、报错排查、最佳实践的顺序带你用十分钟左右跑通 Codex CLI 的完整流程。适合刚接触终端 AI 编程助手的开发者也适合已经在用但被各种报错卡住的人。开始之前先明确一条安全边界Codex 生成的代码、执行的命令都必须经过人工审查不要把账号密钥写进提示词也不要让它在未授权的仓库或服务器上随便执行操作。1. Codex CLI 核心能力速览能力项说明项目类型终端 AI 编程助手Coding Agent开源命令行工具官方来源OpenAI 团队开源GitHub 仓库为 openai/codex安装方式npm 全局安装、wingetWindows、HomebrewmacOS、官方安装包启动方式命令行启动codex进入交互模式codex exec执行单次任务登录认证ChatGPT 账号登录codex login或 API Key 认证支持平台Windows、macOS、Linux只要有终端环境即可主要功能代码问答、代码生成、文件修改、测试补全、命令执行、会话续聊沙箱控制read-only、workspace-write、danger-full-access 三档权限自定义模型供应商支持可通过配置文件接入 DeepSeek 等兼容 OpenAI 格式的服务桌面端联动可与 ChatGPT 桌面端 Codex 功能联动需配置 codex_cli_path批量任务CLI 天然适合脚本化批量调用单个任务一次exec完成适合场景日常重构、补测试、生成文档、批量代码处理、终端问答从表里能看出来Codex CLI 并不依赖任何图形界面核心就是终端命令。这意味着它可以被更高层工具调用很多codex 插件ChatGPT 桌面端集成本质上都是在这些命令外面包了一层。后面章节会讲到当桌面端告诉你找不到 codex cli binary时本质就是它没找到本机上那个可执行文件解决方法通常是安装 CLI 或手动指定路径。需要注意Codex 本身是客户端工具真正的智力来自背后的大模型。官方默认走 OpenAI 模型服务但配置文件支持自定义供应商。国内开发者比较常用的做法是把它接到 DeepSeek 这类国内可直连的 API 上网络更稳定成本也更可控。这在第 6 节会给出完整配置。2. Codex 能干什么使用边界在哪里Codex 有两种常用工作方式。第一种是一次性任务codex exec 任务描述直接派活执行完退出适合脚本化和批量调用。第二种是交互式会话直接输入codex进入对话界面可以连续提需求像在终端里开了一个 AI 结对编程窗口。实际项目里比较稳妥的用法是先让 Codex 读项目结构和关键文件再让它做小范围改动最后逐个查看 diff 确认。沙箱是 Codex 比较值得关注的设计。read-only模式下它只能读取文件不能修改workspace-write允许修改当前工作目录下的文件danger-full-access不限制命令执行范围。对第一次使用的人来说先用 read-only 或默认模式观察它怎么工作确认输出没问题再放开权限是比较稳妥的顺序。权限给得越大效率越高但风险也越大这个权衡要自己做。使用边界方面需要注意几点。第一Codex 生成的是建议而不是结论改动必须经过代码审查和自动化测试不能直接合入生产分支。第二不要在提示词里粘贴密钥、Token、隐私数据代码会发送到你配置的模型服务端私有仓库和敏感项目要尤其谨慎。第三danger-full-access模式下它可以执行任意命令务必确认当前目录和机器是可控的。第四涉及版权代码、人脸、声音、隐私素材等场景必须确认授权后再让 AI 处理。这些边界不是劝退而是让工具在可控范围内发挥价值。3. 环境准备与前置条件在装 Codex 之前先确认三个东西Node.js 版本、npm 是否可用、终端是否正常。npm 安装方式要求 Node.js 18 以上版本版本太低会导致安装失败或运行时报错。打开终端执行node -v npm -v如果 node 命令不存在先去 Node.js 官网下载 LTS 版本安装。Windows 用户建议用 winget 或官方安装包装 Node.js装完重新打开终端让 PATH 生效macOS 用户如果习惯用 Homebrew也可以执行brew install node。检查命令能正常输出版本号说明 Node 环境没问题。除了 Node.js 本身还需要准备一个账号。如果你是 OpenAI 官方渠道用户用 ChatGPT 账号登录即可如果打算通过 API Key 调用需要到 OpenAI 平台生成一个具备 Codex 模型权限的 Key。如果不想依赖 OpenAI 官方网络更常见的选择是准备一个 DeepSeek 开放平台的 API Key第 6 节会把接入配置完整写出来。磁盘空间方面npm 全局安装一般占用不到 300MB基本不用额外考虑Git 不是硬性要求但如果后续要让它处理 git 仓库建议提前装好。最后是网络环境。Codex 是一个客户端它需要访问模型服务接口官方版访问 OpenAI API自定义供应商访问对应的 base_url。安装阶段npm 也要能访问 npm 仓库。如果安装或请求卡住先检查本机到目标服务地址的连通性以及终端里的网络环境变量是否正常确保网络通畅后再继续排查。本文只讨论常规网络调试不涉及任何绕过访问限制的工具或方法。4. 安装部署与登录认证4.1 npm 全局安装最通用、最省事的方式是 npm 全局安装一条命令搞定npm install -g openai/codex安装完成后codex命令会被放到 npm 的全局 bin 目录。如果你的 npm 全局目录不在系统 PATH 里终端会提示命令找不到这时候需要手动把 npm 全局 bin 目录加进 PATH或者重新打开终端让配置生效。安装过程如果出现 EACCES 权限错误说明当前用户对 npm 全局目录没有写权限可以用 nvm 管理 Node.js 版本或者按 npm 官方文档修复目录权限不建议直接加 sudo 硬装。4.2 Windows 使用 wingetWindows 10/11 用户如果本机有 winget也可以直接安装官方发布的 Windows 版本winget install --id OpenAI.Codex这种方式不需要先装 Node.js安装完重启终端执行codex --version验证即可。如果 winget 源里找不到该包或者版本滞后退回 npm 方式最稳。4.3 macOS 使用 HomebrewmacOS 用户可以在 Homebrew 里尝试安装brew install codex需要说明的是Homebrew 可能存在同名包冲突不同时期 formula 名称也可能变化。如果安装失败或装成了别的同名工具直接用 npm 方式安装效果完全一样不折腾。4.4 官方安装包与二进制在 openai/codex 的 GitHub Releases 页面官方会提供预编译的二进制安装包Windows 对应.exe或.msimacOS 和 Linux 对应各自的二进制文件。下载解压后把可执行文件放到 PATH 目录即可。这个方式适合没有 Node.js、也不想为此安装运行时环境的用户。具体文件名和安装步骤以 Release 页面说明为准。4.5 验证安装不管用哪种方式安装完成后先执行codex --version能输出一个版本号例如 0.x.x 开头的数字说明安装成功。如果提示command not found或无法识别 codex大概率是 PATH 没配好回到 4.1 补配置。4.6 登录认证安装成功后需要认证官方支持 ChatGPT 账号登录和 API Key 两种方式。ChatGPT 账号登录直接执行codex login命令会打开浏览器在 ChatGPT 页面完成授权成功后终端会提示已登录。这种方式适合个人开发者不需要自己维护 API Key。如果希望用 API Key 模式执行codex login --api-key也可以跳过 login直接设置环境变量。Linux/macOS 在~/.bashrc或~/.zshrc里加一行export OPENAI_API_KEYsk-你的keyWindows PowerShell 执行$env:OPENAI_API_KEYsk-你的keyWindows CMD 执行set OPENAI_API_KEYsk-你的key注意环境变量方式设置的 Key 只对当前终端会话生效重新打开终端会失效。如果只是临时测试这样反而更安全Key 不会长期留在系统里。5. 功能测试与效果验证5.1 单次任务测试登录完成后的第一个测试建议用一次简单的文件生成任务验证输入提示词、输出代码文件的完整链路codex exec 用 Python 写一个函数读取 CSV 文件并返回每一列的平均值首次运行会经历模型初始化接着 Codex 会给出执行计划生成代码并保存文件。判断是否成功的标准很明确当前目录是否生成了目标文件代码内容是否符合要求是否可以直接运行验证。如果任务只要求生成代码而不是修改现有文件Codex 会新建文件或直接输出到终端不同版本行为略有差异以实际输出为准。5.2 交互式会话测试交互模式下可以连续提需求适合边看代码边提问的工作流codex进入后会出现对话输入框输入exit或/quit退出。你可以连续发多条消息Codex 会记住当前会话上下文。比如先问这个项目用了哪些第三方库再问把其中过期的依赖列出来最后问帮我把这些依赖升级并修复兼容性问题。对第一次上手的用户交互模式比 exec 模式更容易建立信任感因为每一步都能看到上下文。5.3 文件上下文测试让 Codex 修改指定文件时可以用--read显式传入文件路径codex exec --read src/main.py 给这个文件里的函数补充类型注解和 docstring--read可以多次使用一次