2026年再聊 AI 编程工具已经不是“要不要用”的选择题而是“怎么把它装进自己的工作流里”的工程题。我自己的主力机器是 Windows家里一台 Mac还有一台常开的 Linux 服务器三种系统都在跑 OpenAI Codex CLIVSCode 也常年挂着。安装配置这件事说难不难但每个平台都有各自的小毛病Windows 的权限、PowerShell 版本macOS 的 Homebrew 缺工具链Linux 的 GLIBC 太老以及 VSCode 里怎么跟 CLI 配合……随便哪一个都能卡住新手半小时。这篇就把我在这三套系统上的完整安装记录、验证方式和踩坑点整理成一份能直接照着走的手册适合第一次装 Codex CLI 的人也适合之前装过但没跑通、想系统整理一遍安装流程的朋友。1. 为什么是 Codex CLI一个终端代理工具的价值边界1.1 和 Web 版、编辑器补全工具的本质区别很多人把 Codex CLI 理解成“网页版 ChatGPT 搬到终端里”这个理解不能说错但会误导使用方式。Web 版适合临时问问题、生成一段代码但它看不到你项目目录里的文件也没法执行命令、读取报错、改动多个文件。编辑器补全类工具比如各类 Copilot 插件更偏重“在你输入的时候给建议”解决的是写单行代码的效率问题。Codex CLI 的定位是本地运行的编码代理它通过 OpenAI 的模型接口理解你的自然语言任务然后在当前工作区里读取文件结构、定位相关代码、执行测试命令、生成修改最后把改动落盘。更直白一点它像是一个“能操作终端、看得见你项目上下文”的远程工程师你只需要把需求说清楚。这个差异决定了它的适用场景重构一套老代码、批量修复测试失败、调查某个模块的调用链、解释一个从未见过的项目结构。这些任务不是“写一行代码”而是“理解一个上下文并操作它”必须跑在终端环境里才有意义这也是我坚持用 CLI 而不是完全依赖编辑器插件的主要原因。1.2 它解决什么问题不解决什么问题先说能解决的部分。跨平台一致性是我体会最深的一点。同一套工作流Windows、macOS、Linux 上的行为基本一致这意味着团队内部可以共用一套安装文档和脚本约定。其次它适合做“可复现的批处理”你可以用非交互模式一次性提交几个任务比如把项目里所有 TODO 整理成表格、给每个函数补注释、跑一遍 lint 然后把错误汇总。这类事情写脚本太繁琐让代理来做刚刚好。但它不解决所有问题。Codex CLI 不会替你决定架构不会自动部署也不会管理权限。你让它“修好登录报错”它可能给你一个只在测试环境有效的方案你让它“优化一下性能”它可能在局部改了三个函数但整体瓶颈仍不明确。我的经验是使用前最好先明确任务边界越窄的任务它完成得越稳。还有一点CLI 本质是把代码请求发送给模型的云端接口虽然操作发生在本地但数据仍然会经过模型服务如果你的项目代码有严格的保密要求需要先获得相应批准再考虑是否用它处理敏感文件。1.3 本地配置与权限模型Codex CLI 的配置入口是各平台下的config.toml文件。macOS 和 Linux 在~/.codex/config.tomlWindows 在%USERPROFILE%\.codex\config.toml。首次安装后不一定有这个文件登录成功通常会生成默认配置。我习惯在里面设置三样东西模型、命令审批策略、沙箱模式。这里最值得关注的是审批策略。代理要执行的每条 shell 命令默认都会征求你的同意你可以把常用命令加进白名单比如git、npm test这样日常操作少一些打断但也要知道白名单越大越依赖你对代理的信任度。对一个新版本或新项目我建议先用默认的逐条审批跑几次观察它提议执行的命令是否符合直觉再决定要不要放宽。2. 动手前的三分钟自检Node 版本、登录方式、终端环境2.1 四条命令确认基础环境安装之前先把基础环境确认一遍。打开终端依次执行这四条命令node --version npm --version git --version curl --version代码包本身依赖 Node 运行时我实测 Node 20 以上的版本基本没问题版本太旧会出现引擎不兼容的报错提示你升级 Node。macOS 和 Linux 如果还没装 Node建议优先用nvm这类版本管理器安装不要直接装系统包管理器的旧版本。git 不是硬性依赖但 Codex CLI 操作项目时经常要用到 git diff、提交信息所以提前装好能少很多麻烦。curl 是给安装脚本用的Windows 10 以上自带macOS 和大多数 Linux 发行版也默认有。确认命令都正常后再看一下终端类型。Windows 用户请务必用 Windows Terminal 搭配 PowerShell 7不要用系统自带的 Windows PowerShell 5.1我实测 5.1 对 Unicode 字符和终端渲染的支持有问题Codex CLI 的交互式界面在旧 PowerShell 里经常出现光标错位和中文乱码。macOS 自带的 Terminal 能用但追求交互体验的话 iTerm2 更好。Linux 没有太大讲究只要终端宽度不小于 120 列就行Codex CLI 有一套基于终端的界面TUI列宽不够时表格对齐会很难看。2.2 API Key 和账号登录怎么选Codex CLI 支持两种认证方式一种是你已有的 ChatGPT 订阅账号直接登录好处是开通就能用不需要额外管理密钥另一种是使用 OpenAI API Key适合自动化脚本、CI 流水线或者不想走交互登录的服务器场景。开发时我建议用登录方式执行codex login它会打开浏览器完成授权登录后本机保存凭证。但在没有浏览器的 Linux 服务器、或者远程桌面环境里登录流程很别扭这时候直接用环境变量传 API Key 更省事。类 Unix 系统写法export OPENAI_API_KEYsk-你的密钥Windows PowerShell 写法$env:OPENAI_API_KEYsk-你的密钥有个容易踩的坑不要把 API Key 写死在config.toml里。虽然有些老教程会让你这么干但配置文件可能被同步工具上传到仓库里一旦泄露就是实打实的账单损失。正确的做法是写在环境变量里或者用 shell 的加载逻辑统一注入。2.3 确认网络连通性Codex CLI 运行时要访问 OpenAI 的接口域名这一步经常被忽略导致装完后一执行就超时。安装前先测试一下curl -I https://chatgpt.com这里不需要输出太多东西只要能看到返回的头部信息就说明基本连通。如果提示超时或连接被拒先检查一下本机网络是否能访问目标域名。如果你所在的公司内网要求走代理访问外网就在当前终端里设置标准的 HTTP 代理环境变量Codex CLI 的请求会遵循这些常规设置。3. Windows 安装两条路径一条实操3.1 路径一npm 全局安装Windows 上最直接的安装方式是通过 npm 全局安装。在 PowerShell 7 中执行npm install -g openai/codex执行结束后运行codex --version验证。如果提示找不到命令多半是 npm 的全局安装目录没有加入 PATH常见位置是%APPDATA%\npm。重启终端后如果还不行手动把这个目录加进系统环境变量即可。这里有一个 Windows 特有的麻烦如果你用安装包直接安装 Nodenpm 全局目录默认在系统盘的用户目录下面权限一般没问题。但如果你之前装过旧版 Node或者用了某些优化工具全局目录权限可能被改过安装时会遇到EACCES权限错误。我自己的解决方案是改用nvm-windows管理 Node 版本卸载系统级 Node然后为当前用户安装一套干净的版本环境从此再没遇到过全局权限问题。还有一个在 Windows 上特别明显的现象第一次运行codex时启动会比较慢。遇到这种情况先别急着删掉重装大概率是 Windows Defender 在实时扫描新增的 node_modules 目录。如果公司电脑统一装了安全软件第一次扫描可能持续十几秒后面会恢复正常。不建议一开始就去加白名单先等一下看能不能正常启动。3.2 路径二官方安装脚本免 Node 方案如果你完全不想装 NodeCodex CLI 还提供了官方安装脚本Windows 上可以用 PowerShell 直接执行iwr -useb https://codex.openai.com/install.ps1 | iex这条命令从官方地址下载安装脚本并执行。PowerShell 默认执行策略可能拦截远程脚本如果报错先允许当前用户执行远程签名脚本Set-ExecutionPolicy -Scope CurrentUser RemoteSigned安装完成后可执行文件通常会放到用户目录下的本地 bin 路径命令行里会提示你把这个路径加入 PATH。脚本安装与 npm 安装本质上是一回事只是帮你把依赖和路径处理好了。我自己在 Windows 上第一条路径和第二条路径都试过。最终保留的是 npm 方案理由很朴素2026 年我大概率会频繁升级 Codex CLI用npm update -g openai/codex拉新版本比重新跑安装脚本更顺手。如果你只是想快速跑起来不想深入了解 Node 生态官方脚本方案更快。3.3 Windows 专属的坑权限与杀毒软件安装完成后先别急着干活Windows 上还有两件事值得提前处理。第一件是权限。不要用管理员权限运行 Codex CLI。我刚开始为了省事直接右键管理员运行终端结果编码代理每次执行命令都需要面对 UAC 的权限边界反而频繁卡在“需要提升权限”的交互上。普通用户权限下只要工作目录对当前用户可写绝大多数开发操作都没问题。第二件是登录。执行codex login后Windows 会弹浏览器进行授权。Edge 和 Chrome 我都试过流程稳定。但如果你是通过远程桌面连到 Windows 机器浏览器可能弹不出来或者回调地址没被本机识别。这种情况要么改用 API Key 环境变量要么在远程会话里安装并打开浏览器完成授权。最后验证安装是否完成走一遍完整流程codex --version codex login codex能看到版本号、登录成功、进入交互界面三步都通过就说明安装已经完成。初次进入 Codex 界面时它通常会在当前目录创建一个会话你可以先让它“列出当前目录有哪些文件”检查它是否真的能看到本地上下文。4. macOS 安装Homebrew 与原生包哪个更顺手4.1 先装 Homebrew还是绕过它macOS 用户装 OpenAPI 系的开发工具几乎绕不开 Homebrew。Codex CLI 在 macOS 上通过 Homebrew 安装非常省事brew install codex但很多新人的电脑连 Homebrew 都没装。如果你还没有 Homebrew建议先装它。官方安装命令是/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装过程中系统可能会提示安装 Command Line ToolsCLT这是 Xcode 的命令行工具集不是完整 Xcode但编译很多软件都需要它。如果没装brew install也会引导你安装。如果你所在网络访问 GitHub 不顺畅Homebrew 的安装会卡在下载阶段这时可以先配置国内镜像再执行安装。这一步不属于 Codex CLI 本身的问题但我在实际装机时卡过好几次提前说一句能省不少时间。4.2 两条安装路径brew 与 npmmacOS 上有两种主流的 Codex CLI 安装方式除了 Homebrew还有 npmnpm install -g openai/codex你可能会问既然有 Homebrew为什么还要用 npm区别主要在于更新节奏和依赖环境。Homebrew 安装的好处是依赖管理干净brew update brew upgrade codex就能完成升级卸载也是brew uninstall codex不会留下麻烦。npm 安装的好处是版本发布通常更快适合你明确知道某个新特性刚上线、想第一时间用到的场景。我个人建议 macOS 用户优先走 Homebrew。原因很简单macOS 自带的系统 Python、系统 Node 这类环境很容易被搞乱而 Homebrew 会把这些工具统一管理在/opt/homebrew下面跟系统自带环境隔离后续维护成本低。如果你已经用 nvm 管理 Node那 npm 安装当然也没问题只要别两种方式混用就行。我见过有人先跑了brew install codex后来又用 npm 安装了一次两个二进制在 PATH 里先后出现codex --version显示的版本时新时旧排查起来非常头疼。4.3 macOS 权限、钥匙串与更新macOS 上第一次运行codex login时系统可能会弹出提示“是否允许访问钥匙串”这是因为 CLI 要把登录凭证保存到系统钥匙串里。相信我这时候一定要允许否则后续每次启动都会报凭证读取失败。万一误点了拒绝去“系统设置 - 隐私与安全性”里找到对应条目重新授权不用重装软件。Apple Silicon 芯片的 Mac 我实测过两种安装方式都正常没有 arm64 架构的兼容障碍。Intel 芯片的老 Mac 只要系统版本还能升级到当前主流版本问题也不大。另外如果你之前从浏览器下载过一些不知名来源的安装包Gatekeeper 对双击安装的 App 有限制但命令行 curl 或 brew 安装不会频繁触发这个机制基本可以忽略。更新频率这里多说一句。Codex CLI 的迭代速度很快我建议每个月至少检查一次新版本。Homebrew 用户直接brew upgrade codexnpm 用户执行npm update -g openai/codex。版本落后太多时模型能力和交互界面的体验差距会非常明显。5. Linux 安装脚本安装的完整命令序列5.1 推荐用官方脚本但先看系统版本Linux 上安装 Codex CLI我最推荐官方脚本方案curl -fsSL https://codex.openai.com/install.sh | bash脚本执行完会自动把可执行文件放到~/.local/bin然后你需要确保这个路径在当前 shell 的 PATH 中export PATH$HOME/.local/bin:$PATH为了下次登录不失效把上面这行追加到~/.bashrc或~/.zshrc里。验证命令照旧codex --version如果你在 Ubuntu 22.04、Debian 12、CentOS Stream 9 这些近两年的主流发行版上操作到这里已经结束了。但如果是 CentOS 7 这类老系统很可能会遇到 GLIBC 版本过旧导致的启动失败。我建议不要在这种老环境里硬啃直接换新一点的发行版或者用 Docker 跑一个隔离环境都比跟系统库较劲划算。5.2 无 sudo 环境下怎么装很多公司服务器不允许开发人员随意使用 sudo甚至主目录下的磁盘空间都很有限。这种情况下我依然能正常安装 Codex CLI因为官方脚本默认就装在用户目录不需要写系统目录。如果服务器完全没有外网只开放了内网那么你可以在本机下载所需的 npm 包然后通过内网传输工具拷到服务器在服务器上指定本地路径安装npm install -g --prefix ~/.local /path/to/codex-package这种方式在离线环境里实测可行只要你找到对应版本的压缩包把依赖也一并带走。如果你对 npm 包结构不熟还有一个更简单的思路直接拷一个已经安装好 Codex CLI 的同架构机器上的~/.local目录到目标机器。Linux 的依赖大多在系统库里可执行文件和 node_modules 的迁移兼容性通常很好但务必注意 glibc 版本匹配。5.3 服务器场景没有浏览器也要能登录Linux 常用于服务器或 Docker 容器这两类场景大概率没有图形浏览器。此时codex login交互登录会很别扭建议直接用 API Keyexport OPENAI_API_KEYsk-你的密钥之后进入交互界面codex我会先在项目的根目录下启动它这样它能看到完整的项目上下文。另外服务器上跑代理要格外关注命令审批策略。在一个不常维护的老项目上我建议第一次跑的时候保持逐条审批让代理先把整个改动计划说出来确认没问题再批量执行。别图省事一次性放开白名单否则遇到一个理解偏差可能造成大范围文件改动回滚都要折腾半天。6. VSCode 集成不是替代 CLI而是互补6.1 安装官方扩展并复用登录态很多人装了扩展就想把 CLI 扔掉我觉得这是一种误解。VSCode 里的 Codex 扩展适合交互式对话、在代码旁边直接看修改建议而 CLI 适合脚本化任务、跨目录操作和非交互执行。两个一起用效率才是最高的。VSCode 扩展的安装很简单打开扩展市场搜索“Codex”选择 OpenAI 官方发布的版本点击安装。安装后左侧会出现对应图标第一次使用时会引导你登录。好消息是登录态通常可以和 CLI 共用如果 CLI 已经登录过扩展这边一般不需要重新授权如果扩展提示未登录先回到终端执行一次codex login再回来刷新看。6.2 在 VSCode 中调用 CLI 的三种实用方式第一种最直接打开 VSCode 内置终端直接运行codex。这种方式的好处是能看到完整 TUI 输出坏处是你要手动在编辑器和终端之间切换上下文。对于简单的“解释这段代码”“生成测试用例”需求已经够用。第二种方式是把 CLI 集成到 VSCode 任务里。创建一个.vscode/tasks.json可以绑定一个自动任务比如把当前文件内容交给codex exec做一次代码审查{ version: 2.0.0, tasks: [ { label: Codex: Review Current File, type: shell, command: codex exec \请审查当前文件$(cat ${file})\ } ] }通过快捷键调出任务列表选中这个任务VSCode 就会把当前文件内容发送给 Codex 执行。这种方式本质上是“命令行桥接”非常灵活你可以按自己的需求改提示词模板。第三种方式是用扩展设置指定 CLI 可执行文件路径。如果你通过脚本方式把 Codex 装到了自定义路径而扩展找不到它可以在 VSCode 设置里搜索 codex 相关配置项手动填入codex的绝对路径。这个处理思路对所有类似工具都通用遇到“扩展找不到二进制”的问题先查 PATH再查设置里的路径覆盖。6.3 我实际怎么分配工作我自己的日常分工是写代码、改逻辑、看 diff 用 VSCode 扩展批量重构、脚本化审查、处理一组文件用 CLI。举个例子当我要清理一个项目里所有未使用的 import 时我会在 CLI 里发起一个任务“扫描 src 目录下所有 .ts 文件找出未使用的 import 并删除”它会同时操作几十个文件这种规模在扩展图形界面里反而不方便。一个重要提醒不要让扩展和 CLI 同时操作同一份代码。我遇到过两次文件冲突扩展面板里已经生成了一段修改而我同时用 CLI 在终端里执行了另一个改动任务两边都往同一个文件写内容最后不得不靠 git 回退。现在我的习惯是同一时间段内要么只用扩展要么只用 CLI绝不交叉。7. 配置与常见报错排查手册7.1 登录态失效与多账号切换登录态失效是使用一段时间后最常见的现象。症状通常是执行codex时报鉴权错误或提示凭证过期。解决办法不复杂重新执行一次codex login就行。如果你有多个账号比如个人账号和公司账号不要反复登录退出更推荐用环境变量做切换。在启动 CLI 之前临时设置对应的 API Key这样每个 shell 会话用哪套身份非常清晰export OPENAI_API_KEYsk-个人 codex另一个 shell 里export OPENAI_API_KEYsk-公司 codex两个会话并行也不会串身份。这条经验在 Windows 上也成立PowerShell 的语法换成$env:OPENAI_API_KEY即可。7.2 与网络和代理相关的超时使用中如果遇到请求一直转圈、最终提示连接超时先不要怀疑工具出问题。第一步测试网络第二步检查环境变量。之前在公司内网碰到过一次所有请求都失败排查后发现是环境变量里设置了指向内网代理的值但该代理已经失效。把无效的环境变量清掉后恢复正常。如果你是正常网络环境仍然遇到偶发超时优先做两件事一是检查当前 Codex 版本升级到最新版二是确认你使用的模型 ID 拼写正确有些自定义配置填了不存在的模型名请求会反复报错而不是直接告诉你配置错误。7.3 版本冲突与 PATH 问题最后把安装阶段最常遇到的几个报错整理成一张表格方便快速定位错误现象常见原因处理办法command not found/ 不是内部或外部命令PATH 未包含 Codex 可执行文件目录重启终端手动添加安装目录到 PATHengine版本不兼容报错Node 版本过旧升级到 Node 20 以上权限错误EACCESnpm 全局目录权限异常用 nvm 重装 Node修复目录归属登录回调地址打不开无浏览器或远程桌面环境改用 API Key在可开浏览器的机器上登录启动很慢首次运行时安全软件扫描多等片刻仍慢则检查 CPU 占用和扫描日志扩展找不到可执行文件PATH 设置或扩展配置未指定绝对路径在扩展设置中填入codex绝对路径config.toml的基础配置也值得提前设置好。我目前使用的核心配置是这几个字段model latest approval_policy on-request [permissions] allow [git, npm test, node]model字段记得填你账号里实际可用的 Codex 模型 ID不确定时可以用latest或者查阅当前可用模型列表approval_policy决定命令审批方式on-request表示逐条请求permissions里的allow是允许代理不经确认执行的命令集合。这个文件改完重启 Codex CLI 生效。最后再分享一个我自己的小习惯。每次在新机器上装完 Codex CLI我不会直接开始干活而是先用一条命令让它总结当前目录结构再让它执行一次git status确认它确实能看懂仓库状态。这个“健康检查”一分钟都花不到但能提前暴露出大部分权限、PATH、网络问题比真正干活时再发现要省心得多。工具装好只是第一步把它调成适合自己的节奏才是这 2026 年真正值得花时间做的事。