如果你这段时间刷技术社区看到不少人在终端里让 AI 帮忙改代码、跑测试、整理 Git 提交那他们用的多半就是 Codex CLI——OpenAI 出品的命令行 AI 编程助手。最近后台和评论区天天有人问“Codex 到底怎么装、怎么配”很多朋友卡在第一步就进行不下去了。这篇我就按保姆级的粒度把下载、安装、配置每一步都拆开写清楚你照着操作就行。先说清楚这篇教程不是什么概念介绍是实实在在的安装配置指南。我会把常见的坑也一并列出来包括我实际踩过的、帮别人排查过的问题。如果你打算用 Codex 来提升日常开发效率这篇文章能帮你省下不少摸索时间。1. 动手之前先搞清楚 Codex 到底是什么值不值得装1.1 一句话讲懂 Codex CLICodex CLI 是 OpenAI 推出的命令行 AI 编程工具本质是一个跑在终端里的智能编程助手。你启动它之后它先读取当前项目的文件结构、代码内容、Git 状态然后理解你的自然语言指令再自己去改代码、执行终端命令、运行测试甚至直接帮你提交代码。它不是网页对话框那种“聊完就完事”的工具。Codex 是真正和你的开发环境连在一起的它能看到你仓库里的真实代码改完能立刻跑给你看结果。这种“能动手干活”的体验和单纯问 ChatGPT 写一段代码完全不是一回事。1.2 它和普通聊天机器人、其他 AI 工具的区别我先把 Codex CLI 跟其他几种常见工具做个对比你一看就明白它定位在哪。对比维度ChatGPT 网页版各类聊天式 AI 插件Codex CLI是否读取本地代码否需要手动粘贴部分支持依赖编辑器插件是直接读取项目目录是否帮你执行命令否只给代码建议部分支持但执行范围有限是可以运行命令并处理结果交互方式网页对话框编辑器内对话框终端命令行对话使用门槛最低较低需要一点命令行基础自动化能力弱中强适合复杂任务适用场景问答、写文案编辑器内辅助编码完整开发流程、自动化执行从这个表能看出来Codex CLI 最大的特点是“离你的代码足够近”。普通聊天工具给你代码片段你得自己复制粘贴再跑Codex 直接在你本地环境里操作它可以自己打开文件、自己改、自己验证。这也是为什么很多资深开发者用了之后说“回不去了”。1.3 它适合谁不适合谁先泼一盆冷水Codex 不适合一点命令行都没接触过的纯小白。你至少要知道cd进目录、ls看文件、会打开终端否则配置环境变量、排查报错时会比较吃力。不过只要你愿意照着教程一步步来胆子大一点其实也没有想象中那么难。适合的人是这几类日常用终端开发的前后端工程师想让 AI 处理重复性编码工作。独立开发者、开源爱好者需要快速梳理陌生代码库。测试和运维同学想用 AI 自动写脚本、检查配置文件。对新技术敏感、愿意折腾的学习者想提前体验 AI 辅助开发的新范式。不适合的人也有完全不想碰终端、只希望有图形界面点来点去的人或者期望 AI 百分百正确、自己完全不想 review 代码的人。工具毕竟是工具Codex 也会犯错你得有最基本的判断力。2. 安装前的准备工作三个步骤花五分钟安装最怕装到一半发现缺这缺那。提前把环境、依赖、账号准备好后面就顺畅了。2.1 确认系统与硬件条件Codex CLI 对系统的要求不算苛刻但官方建议尽量用新一点的系统macOSmacOS 12 及以上推荐 Apple SiliconM1/M2/M3/M4 系列或 Intel 机型都行。LinuxUbuntu 20.04、Debian 11、CentOS 8 等常见发行版都能跑内核版本别太老。WindowsWindows 10 及以上版本推荐使用 PowerShell 或 Windows Terminal 作为终端。你要是平时用 WSL那更省事直接在 WSL 里按 Linux 方式装。硬件方面内存建议 8GB 以上磁盘留出至少 1GB 空间。Codex 本身不大但模型推理在服务端完成本地只是跑一个客户端所以对电脑性能要求不高。真正吃资源的是你日常开发的项目这个按你平时开发环境的标准来就行。一个加分项是网络要稳定。Codex 多数功能依赖云端接口网络差会出现请求超时这个我后面会在常见问题里详细说。2.2 安装依赖Node.js 和 Git 不能少Codex CLI 最常见的安装方式是通过 npm 全局安装所以 Node.js 是必须的。如果你之前装过 Node.js可以在终端里检查版本node -v npm -v我建议 Node.js 版本不低于 18npm 版本不低于 9。如果版本太低后续安装 Codex 时可能因为依赖包语法不兼容而报错。没有安装的话根据系统选一种方式macOS推荐用 Homebrew 安装命令是brew install node。Windows去 Node.js 官网下载 LTS 版本安装包一路下一步就行或者用命令winget install OpenJS.NodeJS.LTS也可以。LinuxUbuntu 系可以用sudo apt install nodejs npm但 apt 里的版本通常比较旧我更推荐先去 NodeSource 仓库配置源再装。Git 也是建议装的。Codex 本身不强制依赖 Git但你要让它做版本相关操作、看 Git diff、提交代码没有 Git 会很不方便。安装方式同样简单macOSbrew install gitWindows下载 Git for Windows 安装包安装后会自动配置好环境变量。Linuxsudo apt install git或者sudo yum install git。装完记得验证git --version能输出版本号说明环境就绪了。2.3 终端权限与环境变量检查Codex 安装到系统全局目录在 macOS 和 Linux 上通常需要写入/usr/local/bin或/opt/homebrew/bin如果你不是管理员账号安装时会遇到权限不足的报错。解决方式是在安装命令前加sudo或者在保证安全的机器上给当前用户授权。Windows 上用 npm 全局安装时建议用“管理员身份”打开 PowerShell这样能避免不少奇奇怪怪的权限问题。另外我强烈建议你提前想好“要用哪个账号”的问题。Codex 提供两种登录方式ChatGPT 账号登录适合有 ChatGPT Plus 或 Pro 订阅的用户。OpenAI API Key 方式适合按量付费的用户。无论哪种建议提前去官网确认账号可用、有足够额度。不然装好之后卡在登录环节非常恼火。API Key 的创建一般是在平台后台的 API Keys 页面生成创建后马上复制保存因为它只显示一次。2.4 顺手把 npm 镜像配置好这一步是给网络不好、安装速度慢的朋友准备的。npm 默认源在国外国内网络环境下载大依赖包时经常出现“安装到一半停住”的情况。你可以把 npm 源切换到国内镜像比如 npmmirrornpm config set registry https://registry.npmmirror.com设置完之后可以验证一下npm config get registry能看到刚才设置的地址就成功了。这个设置只影响 npm 下载源不影响你后续使用 Codex 本身。装完 Codex 后如果还觉得官方服务响应慢那是另一回事后面我会讲对应解法。3. 保姆级安装流程三条路线选一条就能跑起来Codex CLI 的官方安装方式不止一种。我按不同系统和使用习惯整理成三条路线你先根据自己的情况选一条剩下的就不用看。3.1 路线一npm 全局安装全平台通用最推荐这是最经典、覆盖平台最广的方式。macOS、Linux、Windows 只要装好了 Node.js命令是一样的。在终端执行npm install -g openai/codex如果你用的是 Linux 或 macOS 并且之前没加过 npm 全局目录权限可以加 sudosudo npm install -g openai/codex安装过程大概会持续一两分钟取决于网络。看到类似这样的输出就说明装好了added 1 package in 15s我推荐新用户优先走这条路线因为 npm 是全球统一的包管理工具出错率最低。而且后续升级、卸载都有明确命令不知道从哪里下手时至少有章可循。安装完成后马上验证codex --version能输出类似codex version 0.x.x的信息说明安装成功了。如果提示command not found别慌往下看 3.4 节的解决办法。3.2 路线二macOS / Linux 用 Homebrew 安装如果你用 macOS而且平时已经装了 Homebrew那这条路线最顺手。只需要一条命令brew install codex等它自动拉取依赖并链接到系统目录后直接执行codex --version将来想升级也很简单brew upgrade codex这里有个经验之谈Homebrew 安装有两个容易出问题的点。一是 Homebrew 本身在国内网络下经常拉取更新失败解决方法是在安装前先临时禁用自动更新HOMEBREW_NO_AUTO_UPDATE1 brew install codex另一个是如果你的机器没装 Xcode Command Line Toolsbrew 安装时可能报错先执行xcode-select --install装上再继续。Linux 用户理论上也可以走 Homebrew但说实话没必要。我更建议 Linux 用户直接用 npm 或官方二进制安装少折腾环境依赖。3.3 路线三Windows 用户的正确打开方式Windows 装 Codex 有两条路我分别说清楚你按自己的使用习惯选。第一种是在 PowerShell 里用 npm 全局安装。打开 PowerShell建议右键“以管理员身份运行”执行npm install -g openai/codex装完在同一窗口执行codex --version注意如果提示codex 不是内部或外部命令关掉当前 PowerShell 重新开一个让环境变量重新加载。如果还是不行检查 npm 全局目录是否在 PATH 里方法我放在后面问题排查部分。第二种是用 WSLWindows Subsystem for Linux。如果你平时开发就在 WSL 里那直接在 WSL 的终端里执行 Linux 安装命令效果和原生 Linux 一致。WSL 的好处是命令行为、路径约定、权限模型都和 Linux 一致遇到报错时网上查到的 Linux 方案基本都能直接套用省心很多。我个人在 Windows 上更推荐 WSL 方案。Codex 这类命令行工具天然更适合类 Unix 环境而且 WSL 里跑项目、配 Git、写脚本都更顺畅。不过如果你日常就是 Windows 纯生态那 PowerShell 方式也没问题安装配置多一点耐心就行。3.4 安装后的验证与升级维护无论哪条路线装完都建议先跑一次版本号验证codex --version如果你装完发现command not found大概率是 npm 全局安装目录没有在系统 PATH 里。这时先查一下 npm 全局目录在哪npm prefix -g以 macOS 为例输出可能是/usr/local或/opt/homebrew对应的全局 bin 目录就是/usr/local/bin或/opt/homebrew/bin。确认这个目录在 PATH 里即可。Linux 同理。Windows 上则是看一下C:\Users\你的用户名\AppData\Roaming\npm是不是在环境变量的 Path 里。升级 Codex 的方法取决于安装方式# npm 方式升级 npm update -g openai/codex # brew 方式升级 brew upgrade codex升级前建议看一眼当前版本和官方最新版本差异如果只是小版本更新直接升就行如果跨大版本先阅读一下官方变更说明避免配置文件不兼容。4. 配置篇登录认证和 config.toml 核心参数详解安装完成只是第一步真正让 Codex 跑起来还需要完成登录认证和基础配置。这块我拆开讲重点讲清楚“为什么这样配”。4.1 登录认证ChatGPT 账号还是 API KeyCodex 支持两种认证方式你根据自己的付费模式选一个。方式一ChatGPT 账号登录。这是最推荐的方式尤其适合已经有 ChatGPT Plus 或 Pro 订阅的用户。在终端执行codex login它会弹出一个浏览器窗口让你登录 ChatGPT 账号并授权 Codex 访问。授权完成后回到终端看到登录成功的提示就行。这个方式的好处是你的订阅套餐里通常已包含 Codex 的使用额度不需要单独再为 API 调用付费计费逻辑对你来说是透明的。方式二OpenAI API Key。适合没有订阅、想按量付费的用户。创建好 API Key 后把它设置为环境变量# macOS / Linux export OPENAI_API_KEYsk-你的密钥 # Windows PowerShell $env:OPENAI_API_KEYsk-你的密钥为了避免每次开终端都要重新设置建议把这一行写入 shell 配置文件比如~/.zshrc或~/.bashrcecho export OPENAI_API_KEYsk-你的密钥 ~/.zshrc source ~/.zshrc两种方式的区别主要在计费方式和使用额度。订阅用户通常包含 Codex 使用额度超了可能限速API Key 用户则是纯按量计费用多少扣多少。如果你不确定自己到底该选哪种可以先去官方帮助中心看计费说明或者先买一个最小额度的 API Key 试用熟了再切订阅。4.2 config.toml 配置文件Codex 行为的总开关登录完成后Codex 会生成一个配置目录。默认位置是~/.codex/里面的config.toml就是它的核心配置文件。我第一次因为不知道这个文件存在导致改参数每次都要加启动参数特别麻烦。你直接编辑这个文件一劳永逸。如果这个文件不存在就用编辑工具手动创建一个mkdir -p ~/.codex touch ~/.codex/config.toml我用一个常用的基础配置作为模板你直接复制后按需修改# Codex 基础配置示例 model gpt-5-codex temperature 0.2 approval_policy on-request sandbox_mode workspace-write逐项解释一下model指定使用的模型。注意不同区域、不同账号可用的模型名不完全一样填之前先确认你账号里实际可用的模型名称填错会报模型不存在。temperature控制回答的随机性。0 到 1 之间代码任务我建议 0.1~0.3太低容易死板太高容易乱写。approval_policy控制 Codex 执行危险操作时是否需要你确认。on-request表示关键操作前会询问你on-failure表示操作失败时才询问never表示完全信任、自动执行。新人期建议用on-request稳妥一点。sandbox_mode沙箱权限级别。read-only只允许读取文件workspace-write允许修改当前工作区文件danger-full-access完全放行。项目代码不熟悉的阶段建议先用read-only让它分析分析完再放开。这几个参数直接影响 Codex 的行为边界一定要自己过一遍再落地别直接复制网上的高权限配置。安全性和效率要平衡我见过有人直接把danger-full-access开着让 Codex 乱跑结果项目文件被改得面目全非。4.3 接入第三方模型以 DeepSeek 为例除了 OpenAI 官方模型Codex 也支持通过配置接入兼容接口的第三方模型。这个功能对国内开发者非常实用因为它不依赖特定网络环境就能获得不错的编码能力。我以 DeepSeek 为例因为它接口风格与 OpenAI 兼容配置门槛低。在config.toml中加入模型服务商配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY然后设置环境变量DEEPSEEK_API_KEY填入你在 DeepSeek 开放平台申请的密钥export DEEPSEEK_API_KEY你的密钥完成后重新启动 Codex它会通过 DeepSeek 的接口来处理请求。这样做的好处是DeepSeek 服务在国内访问比较稳定同时价格通常比官方模型便宜适合日常大量使用。有一点要提醒第三方模型虽然在接口层面兼容但写代码的能力和 Codex 官方模型的差距是真实存在的。复杂任务你用第三方模型跑不出来不要马上怀疑 Codex 坏了很可能是模型能力上限。我一般把第三方模型当作日常开发辅助遇到复杂架构问题还是会切回官方模型处理。4.4 常用环境变量与调试开关除了配置文件和 API KeyCodex 还提供一些环境变量用来控制运行行为。我列出三个最高频的OPENAI_API_KEYAPI Key 认证时使用。OPENAI_BASE_URL指定兼容接口的请求地址。这个主要用于对接企业内部网关或与 OpenAI 接口兼容的自建服务。只要接口格式一致Codex 就能正常工作。CODEX_HOME指定 Codex 配置目录的路径。默认是~/.codex只有在你想把配置迁移到别的位置时才需要设置。调试时最有用的命令是加--debug参数启动codex --debug执行后 Codex 会把详细的请求日志打印在终端包括路由地址、请求体、响应状态等。遇到“莫名其妙不工作”的情况先加这个参数跑一遍通常能直接定位问题。另外Codex 的日志文件存在~/.codex/log/目录里滚动到最后几行看看有没有error、timeout之类的关键词也是排查问题的高效手段。5. 常见问题排查我踩过的坑和别人的坑都在这这部分是整篇教程里最有价值的地方。我在安装配置 Codex 时踩过不少坑也帮很多朋友排查过问题整理成速查表你遇到问题直接按表操作。问题现象可能原因解决方法command not foundnpm 全局目录不在 PATH 里执行npm prefix -g把对应 bin 目录加入 PATH安装速度慢或卡住npm 默认源在国外网络波动换成 npmmirror 镜像源后重装登录时浏览器没弹出默认浏览器配置异常手动复制终端里显示的授权链接去浏览器打开登录反复失败账号状态异常或本地认证文件损坏删除~/.codex/auth.json后重新执行codex loginmodel not found配置的模型名不存在确认账号可用模型清单修改config.toml中的model请求超时网络不稳定或服务限流稍后重试或者改用连接更稳定的模型服务改动配置不生效没有重启 Codex退出当前会话重新启动写代码权限报错沙箱模式限制过严检查sandbox_mode是否设置为read-only中文乱码终端编码不是 UTF-8Windows 终端执行chcp 65001切换到 UTF-8 编码5.1 command not found 的详细排查这是安装后最常遇到的问题。命令明明显示安装成功了但一执行就提示找不到命令。绝大部分原因是 npm 的全局 bin 目录不在系统 PATH 环境变量里。先运行npm prefix -g假设输出是/usr/local那全局 bin 就是/usr/local/bin。把它加到 PATHexport PATH/usr/local/bin:$PATH为了永久生效写入 shell 配置文件echo export PATH/usr/local/bin:$PATH ~/.zshrc source ~/.zshrcWindows 用户就在“系统属性 → 环境变量 → Path”里把C:\Users\你的用户名\AppData\Roaming\npm加进去然后重开终端。5.2 登录失败的一个隐蔽原因很多人执行codex login后终端显示正在等待授权但浏览器窗口就是不出来或者出来了却一直转圈。这种情况下检查一下浏览器是不是已经登录了正确的账号以及当前终端所在的环境是否能正常访问授权页面。如果反复失败我建议直接删除本地旧的认证文件后重新登录rm -f ~/.codex/auth.json codex login删文件之前想清楚这会让你当前登录状态失效需要重新走一遍授权流程。这个方法解决过好几个“登录死循环”的问题值得一试。5.3 请求超时的应对思路Codex 的核心能力在云端网络一旦不稳定就会频繁请求失败。常见的报错有超时、流式响应中断、连接重置等。遇到这类问题我一般按以下顺序排查先确认本地网络正常打开其他网页看看通不通或者执行ping命令测试目标服务。检查是不是有其他软件在管理系统网络流量。这类软件如果配置不当经常会拦截或中断长连接导致 Codex 这类需要长时间保持连接的工具体验很差。如果存在这种情况尝试暂停它再测试。如果你所在网络环境本身就对境外接口有访问限制那无论怎么调都无法稳定访问官方服务。这时最实用的方案是把 Codex 切换到国内可直连的模型服务商比如前面讲的 DeepSeek通过修改model_provider和base_url在config.toml中指定新的服务地址。如果用的是官方服务可以尝试降低请求频率别在同一个会话中发起太多并行任务避免触发限流。5.4 配置不生效的检查要点改config.toml后不生效通常有两个原因一是没有重启 Codex配置文件是在启动时读取的你得退出当前会话再重新进入二是 TOML 语法写错了导致整个文件解析失败Codex 静默跳过。检查 TOML 格式时重点看三点字符串有没有加引号、数组的逗号是否遗漏、标题[model_providers.xxx]是否和上层字段拼写一致。一个常见的错别字就是把model_provider写成model_providers前者是主配置字段后者是服务商定义块两者拼写不同功能也不同。写完后可以用在线 TOML 校验工具检查一下再重启 Codex。5.5 学会看日志是排查问题的终极手段我见过太多人面对报错只会干瞪眼其实 Codex 自己把问题都写在日志里了。用 debug 模式启动codex --debug然后复现刚才的报错终端会输出一长串日志。核心看这几个位置有没有error、fatal关键词请求的返回状态码是 4xx 还是 5xx4xx 一般是配置或认证问题5xx 多半在服务端配置文件加载路径是不是和你预期的一致。日志文件默认存在~/.codex/log/按日期滚动。看不懂全部内容没关系搜索error关键字把附近几行上下文发到社区或者问 AI很快就能定位。6. 实操心得配置好之后Codex 可以这样用起来安装配置只是开始真正发挥价值的是日常使用。这个部分我分享一些我实际操作中的心得和技巧你上手可以少走弯路。6.1 第一次运行从一个最小项目开始很多新手第一次用 Codex上来就让它分析一个大型项目结果 Codex 读文件读半天还经常理解偏。建议你第一次运行先用一个小项目试验。比如先建一个临时目录手写一个简单的 Python 脚本然后启动 Codexcd ~/codex-test codex在交互提示符里输入帮我读取当前目录下的 main.py解释这段代码的功能并指出潜在问题Codex 会读取文件、分析并给出结论。这个流程走通之后你对 Codex 的工作方式就有了直观感受。接下来可以试着让它改代码、加注释、写单元测试。建议第一次全程盯着它动作看它怎么理解你的指令、怎么处理文件慢慢建立信任感。6.2 三个让效率翻倍的实用技巧第一个技巧指令写得越具体结果越好。不要只说“优化代码”要说明“把 main.py 里读取文件的部分改为使用 with open 写法并补充异常处理”。指令越清晰Codex 的修改越精准。第二个技巧让 Codex 动手前先明确边界。项目如果比较大明确告诉它“只修改 src/utils 目录下的文件不要碰其他目录”能大幅减少它误改文件的风险。第三个技巧结合 Git 分支使用。每次让 Codex 做改动之前先新建一个分支改完确认没问题再合并。这样就算 Codex 改错了你也能随时回滚底牌始终在自己手里。6.3 我的个人配置模板前文给过一个基础模板这里把我目前实际在用的配置分享出来适合已经熟悉 Codex、想进一步提升效率的开发者参考model gpt-5-codex temperature 0.2 approval_policy on-request sandbox_mode workspace-write [chat] auto_approve true [history] ttl 7d说明一下approval_policy on-request保证关键操作会问我sandbox_mode workspace-write允许它修改工作区但不会越界动系统文件。auto_approve true的意思是普通聊天性质的请求不需要我逐个确认提高对话流畅度。历史记录保留 7 天方便我回溯之前的操作。每个参数背后都是取舍。你如果对安全性要求高就收紧权限如果追求效率就适当放开。没有绝对正确的配置只有适合你工作流的配置。6.4 这套工具的后续扩展方向Codex 装好之后可以做的事情比想象中多。除了日常写代码我目前在实际工作中用得最多的几个方向让它当“代码审查员”每次改动后让 Codex 检查 diff指出潜在问题。让它批量处理重复任务比如重命名变量、整理目录结构、批量加注释。让它帮你写项目文档和 README省去大量文档时间。把它融入个人自动化脚本比如定时分析日志、检查配置文件等。甚至你可以把它当作一个本地代码库的“问答入口”新接手一个陌生项目时直接问它“这个项目的模块依赖是怎么组织的”比自己翻半天文档快得多。安装配置只是起点真正提升效率要靠你日常持续使用、不断调整交互方式。我现在每天打开终端的第一件事就是和 Codex 打个招呼让它帮我梳理当天的待办代码问题。这个习惯帮我省下的时间说实话不算少。最后再分享一个安装阶段的小经验不要追求一次性全配置到位先把 Codex 跑起来、登录成功、能回答简单问题这就是阶段性的胜利。之后再慢慢调模型、调权限、接第三方服务循序渐进才不会把自己劝退。