上个月帮朋友清理一个历史Python项目里面堆了七八个没人能说清用途的脚本。我打开终端输入codex然后告诉它“帮我把这些脚本的依赖梳理清楚没用的删掉留个README”。几分钟后它先给我列了计划然后自己跑起了pip show逐个确认脚本的import关系改完还在关键位置加了两行注释。整个过程我没怎么动手。这不是我第一次用AI编程工具但Codex确实是第一个让我感觉“像个真人在干活”的终端智能体。这篇文章我打算把Codex从下载、安装到配置的每个环节都写透所有步骤都按我实际跑通过的方式记录争取让零基础的读者照着做也能顺利装好。我会把容易踩的坑、那些报错信息到底什么意思、以及怎么把DeepSeek这类第三方模型接进去一起讲清楚。不管你是刚接触AI编程的新手还是想把手头工具链换一换的开发者应该都能在文章里找到自己需要的部分。1. 先说清楚Codex到底是什么装了它你能得到什么1.1 它不是又一个聊天窗口很多人一听到AI编程工具第一反应是“又是一个网页聊天框”。Codex不太一样它是一个跑在终端里的AI智能体Agent。基本的工作方式是你在项目目录下启动它用自然语言描述需求它会自己去读项目文件、搜索代码、修改文件甚至执行终端命令来验证结果。举例来说如果你说“帮我写一个脚本把当前目录下的CSV文件按日期排序后合并”它的流程通常会是这样先解释自己的计划然后创建脚本文件再跑一次命令验证输出最后把改动的代码展示给你确认。你在整个过程中不是在看一个聊天记录而是在看着一个协作者实际动手。这也意味着它需要拥有比网页聊天更高的权限能执行命令能改文件。所以安装后的配置阶段最重要的其实是“权限边界”这件事。本篇文章后面配置章节会专门讲。1.2 谁最需要它我用了几个月感觉最受益的有这么几类人独立开发者 / 自由职业者一个人就是一支队伍没空把所有库的文档都翻一遍但又要赶交付。Codex适合处理那些“重复但有细节”的开发任务比如接口联调、写单元测试、重构老代码。技术团队的技术负责人Codex可以在新成员入职时用来解释代码仓库结构也可以在代码审查前帮你跑一遍静态梳理。运维和数据分析师处理临时脚本、排查日志、写一次性数据清洗脚本这些场景它表现不错省得你每次都要从零写。非科班但想写代码的人Codex会替你处理很多底层细节你只需要能把需求描述清楚。它不一定能把你变成高级工程师但能让你独立完成不少小项目。当然它也有明显的局限性。比如面对超大仓库时它一次能看到的上下文有限再比如涉及复杂的业务规则时它也会一本正经地给出错误方案。所以我的定位一直是它是很强的助手不是甩手掌柜。1.3 和常见AI编程工具的差异这里做一个简单对比方便你判断自己和哪种工具更合拍工具形态擅长场景主要门槛Codex CLI终端智能体自主改代码、执行命令、跑测试需要习惯命令行操作GitHub CopilotIDE插件写代码时的实时补全编辑器内使用ChatGPT / Claude网页网页对话问答、代码片段生成无法直接操作本地文件CursorAI编辑器在IDE里改项目需要切换整个编辑器Codex最特殊的地方是它在终端里工作这意味着你不必把项目塞进某个编辑器只要项目能用命令行构建和运行它就能接手。对于长期在服务器、容器里干活的人来说这种自由度是别的工具给不了的。不过也要提醒一句正因为它是直接在终端里操作第一次启动时如果配置不当它可能真的会执行一些不是你本意的命令。所以下面环境准备和配置这两章千万别跳过。2. 动手前把环境检查做干净版本依赖和官方渠道2.1 系统和Node.js版本怎么检查Codex CLI本身是一个npm包所以第一依赖是Node.js。不同版本的Codex对Node版本要求略有不同目前主流的版本要求Node.js 18及以上建议直接上20 LTS省得后面遇到兼容性问题。Windows用户特别注意Codex官方推荐在WSL2里使用原生PowerShell下偶尔会有终端交互和文件权限的坑。如果你不想折腾最省心的方式是装好WSL2之后在Ubuntu里操作。macOS用户基本没什么额外负担Linux用户只要能装Node就能装Codex。安装之前先检查一下自己电脑的Node环境。打开终端输入node -v npm -v如果提示找不到命令说明还没装Node.js。安装Node我推荐两个渠道一个是去Node官网下载LTS安装包另一个是用nvmNode Version Manager来管理版本。nvm的好处是以后可以在不同Node版本之间随时切换对经常折腾前端项目的人来说几乎是必需品。# 以nvm为例安装后执行 nvm install 20 nvm use 20装完再次执行node -v确认能看到v20开头的版本号环境这步就算过了。2.2 官方下载渠道有哪些别碰来路不明的“安装包”“Codex下载”这个词在搜索引擎里热度很高但它的下载渠道其实很短目前我使用过的只有以下三个都是官方路径npm安装openai/codex这是最主流的安装方式也是本篇文章主要采用的方式。GitHub ReleasesOpenAI官方在GitHub上发布了Codex的源码和编译产物你可以下载对应平台的二进制包。HomebrewmacOS用户如果没有用npm也可以尝试通过Homebrew安装但需要注意包更新速度可能略慢于npm。看到这里你可能会问那网上那些“Codex安装包下载”“Codex 2026最新版安装包”是什么我的建议是尽量别碰。命令行工具更新频率很高通过包管理器安装才能持续获得更新和新功能。从非官方渠道下载的所谓安装包一来版本可能很旧二来你无法保证里面有没有夹带私货。尤其是需要在终端里执行代码的开发者工具供应链攻击的案例不少工具链来源一定要守住。2.3 npm源慢的问题国内网络环境下npm直接从官方源拉包有时候会很慢甚至超时失败。遇到这种情况可以把npm源切换到国内镜像。这是完全合规且常见的加速手段npm config set registry https://registry.npmmirror.com设置完再安装速度会明显改善。改完镜像源后可以执行npm config get registry确认一下当前源地址。如果后续你想换回官方源执行npm config set registry https://registry.npmjs.org即可。这里再提一个容易被忽略的小点npm安装全局包时Linux和macOS系统下可能会遇到权限问题。如果你看到类似EACCES: permission denied的报错不建议用sudo npm install硬刚更干净的方案是用nvm管理Node这样全局包的安装目录属于当前用户不会出现权限地狱。3. Codex CLI完整安装流程一条命令到命令行补全3.1 用npm安装环境检查没问题后安装其实只是一条命令的事npm install -g openai/codex-g参数表示全局安装这样codex命令就会注册到系统PATH里以后在任何目录都能直接启动。npm安装过程中会输出进度条正常情况下几十秒到几分钟不等取决于你的网络状况。安装结束后终端不会有太多花哨输出所以很多新手会以为没装成功其实只要命令没有报错基本就装好了。如果你之前装过旧版Codex想升级到最新版用npm update -g openai/codex或者干脆先卸载再装npm uninstall -g openai/codex npm install -g openai/codex建议每隔一段时间就升级一次因为Codex迭代非常快功能差异也大。3.2 验证安装和版本安装完成后第一件事是验证命令能不能用codex --version正常会输出类似codex-x.y.z这样的版本号。如果提示command not found大概率是npm全局目录没有加入系统PATH。这时候可以执行npm prefix -g查看全局安装路径然后把该路径加到~/.bashrc或~/.zshrc里。验证版本之后我建议再顺手跑一下codex --help快速扫一眼当前版本支持哪些参数。有些功能可能和你网上看到的教程不一样以你本机版本的帮助信息为准。3.3 Shell集成和命令补全Codex还提供了一些Shell层面的集成装好后可以更方便地在终端里使用。执行codex install它会尝试把Codex的Shell集成脚本写入你的Shell配置文件里。这个集成主要提供几个东西更顺滑的会话体验、命令执行的实时反馈以及一些你自定义的快捷键支持。如果你用的是bash或zsh执行完codex install后重启终端或source ~/.bashrc即可生效。另外新版Codex还支持在现有终端会话里直接通过快捷键呼出而不是每次都要开一个单独的交互界面。这些细节在你实际用起来之后会越来越顺手。安装这步到此结束下面进入最容易出问题、但也是最重要的登录和配置环节。4. 登录与配置ChatGPT授权、API Key和config.toml4.1 登录的两种方式Codex装好后直接输入codex会提示你登录。目前主要有两种登录方式第一种ChatGPT账号授权。如果你有ChatGPT的Plus、Pro或Team订阅可以直接用这个方式登录。执行codex login终端会显示一个code和授权链接你需要在浏览器里打开链接并登录ChatGPT然后输入Codex给的验证码完成授权。授权完成后终端会提示登录成功。第二种API Key方式。如果你更习惯按量付费可以先去OpenAI的API平台创建一个API Key然后登录时选择API Key方式把Key粘贴进去。这种方式很直接适合脚本化、自动化场景。需要提醒的是两种方式的计费逻辑完全不同。ChatGPT订阅是包月制Codex的用量包含在订阅额度里API Key方式则是按token计费跑大量任务时费用可能涨得比你预期快。建议首次接触的朋友先用ChatGPT订阅方式体验确认自己真的需要频繁大量使用后再考虑API方式。登录后Codex会把凭证保存在本地配置目录里。如果哪天提示认证过期或失效重新跑一次codex login即可不需要重装。4.2 config.toml核心配置Codex的配置文件是~/.codex/config.toml。一般情况下登录完成后使用默认配置就能跑但如果想更符合自己的使用习惯可以手动编辑这个文件。下面是一份我目前常用的配置示例model gpt-5 model_provider openai approval_policy suggest [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses逐个解释一下几个关键字段model指定Codex使用的模型具体可根据你账户可用的模型调整。model_provider指定模型提供方默认是OpenAI。approval_policy权限策略这个字段直接决定Codex能替你做多少事非常重要。[model_providers.openai]模型提供方的详细定义其中env_key表示从哪个环境变量读取API Key。如果你登录时选的是ChatGPT授权方式API Key通常已经自动管理好了不一定需要自己设置OPENAI_API_KEY环境变量。但如果你用API Key方式登录建议把Key写入环境变量而不要硬编码到配置文件里避免泄露风险。4.3 权限策略approval_policy怎么选这是我个人认为Codex配置里最需要认真思考的字段。approval_policy控制的是“Codex执行命令和修改文件时到底需要经过你多少确认”。不同版本的可选值可能稍有差异但概念大体一致策略行为适合场景只读模式ReadOnly只读代码、搜索文件不执行任何修改命令代码审查、阅读陌生项目建议模式Suggest执行每个关键操作前都先展示计划等你确认日常开发绝大多数人的首选全自动模式FullAuto不询问直接执行命令和修改已信任的独立沙箱环境或CI我第一次用的时候设的是全自动结果Codex为了完成我交代的任务自作主张安装了一个系统依赖包虽然没造成什么严重后果但吓了我一跳。后来老老实实改回了建议模式。我的建议是除非你非常清楚自己在干什么否则保持默认或者建议模式让Codex“先开口、再动手”你会更安全也更容易理解它的行为逻辑。5. 第一次实战跑通让Codex动真格的完整过程5.1 准备一个实验项目配置完成后建议先不要直接拿去改重要代码库先用一个无关紧要的小项目跑一遍流程熟悉它的脾气。我这里就新建一个临时目录来做演示mkdir ~/codex-demo cd ~/codex-demo git init echo def add(a, b): return a b # TODO: 需要补一个减法函数 calc.py故意留一个没写完的calc.py然后让它补全。之所以强调git init是因为Codex会基于Git工作区来追踪文件变更你后面查看它到底改了什么也方便。5.2 交互式session怎么做在项目目录下直接输入codex它会启动一个交互式会话。输入帮我在calc.py里补一个减法函数并且补一个简单的测试正常情况下Codex会先回复一段简短的计划然后开始创建或修改文件最后把文件内容用diff的形式展示出来。每一步关键操作前它会停下来等你的确认。如果你用的是建议模式终端下方会出现一个选择菜单你可以同意Approve或拒绝Reject它的操作。这台机器上跑下来的实际结果是它很顺利地补了subtract函数加了一个if __name__ __main__的简单测试块并运行了一次文件确认没有语法错误。整个过程大概花了一分钟。如果你不想进入交互模式也可以直接给任务参数codex 帮我给calc.py增加除法函数并处理除数为0的情况这样它会一次性跑完任务然后退出适合脚本化调用。5.3 常用命令和退出在交互式会话里有几个命令我用得最频繁/status查看当前会话里Codex已经执行了多少步改动了哪些文件。/quit退出会话。/model查看或切换当前使用的模型。/reset清空上下文重新开始一个话题。初次操作时你可能会觉得每一步确认有点繁琐但这其实是个好习惯。Codex每次改动文件后Git能让你轻松对比前后差异。我自己的习惯是让它每完成一个子任务就用git diff看一眼改动确认没问题再继续下一个需求。6. 高频报错排查全过程从打不开到模型调用失败再顺手的工具配置过程中也难免遇到报错。下面这几个问题是我在社群里被问到最多的每个我都按实际排查思路写出来照着走一遍基本能解决。6.1 本地代理服务切换失败的报错很多人遇到过这样一段报错cc switch local proxy failed while handling codex endpoint /responses. provi...。第一次看到这个提示我第一反应是配置写错了后来排查了一圈才发现它的意思是Codex在向/responses端点发起请求时本地网络代理服务的切换环节失败了。出现这个报错常见触发场景有两个。第一个是本地代理服务进程本身没有启动或已经崩了第二个是Shell环境里的HTTP_PROXY和HTTPS_PROXY环境变量指向了一个不可达的地址。排查步骤我一般按这个顺序来# 1. 查看当前代理环境变量是否设置 echo $HTTP_PROXY echo $HTTPS_PROXY # 2. 检查代理地址是否可达 curl -I http://localhost:你的代理端口 # 3. 如果代理已经不可用先取消环境变量再重试 unset HTTP_PROXY unset HTTPS_PROXY codex这里所有的排查前提都是你的网络环境本身符合相关服务的使用要求。如果基础网络连通性有问题优先解决网络问题而不是在Codex配置里反复折腾。如果curl确认代理地址可达但Codex依然报同样的错可以再检查一下CA证书相关的配置必要时把NODE_EXTRA_CA_CERTS指到正确的证书文件。这类问题在升级系统或Node版本后更容易出现算是环境变动带来的连锁反应。6.2 登录打不开与认证过期很多人卡在第一步执行codex login终端显示一个链接但浏览器打不开授权页或者打开后页面报错。这种问题大多数情况是网络连通性导致的。确认当前网络能正常访问OpenAI服务后再尝试登录。如果还是打不开可以试试手动在浏览器里粘贴完整链接而不是直接点终端里的链接。有时候终端输出会把链接截断。登录成功后过一段时间可能会遇到提示认证过期或会话失效。这不是什么大问题重新执行codex login即可。如果执行登录后一直转圈可以删除本地旧的凭证文件再重新登录。凭证文件的位置一般在~/.codex/目录下删除前建议先备份。6.3 模型调用失败与网络超时成功登录后偶尔会碰到模型调用失败报错信息通常是超时、连接重置、或者直接提示Request failed with status code ...。排查思路可以分成三块。第一确认模型配置是否存在config.toml里指定的模型名和你的账户可用模型是否匹配。模型名写错是最常见的问题。第二检查网络连通性看能否正常访问api.openai.com域名。第三升级Codex到最新版本旧版本可能因为API协议调整而无法兼容新的模型接口。如果你的config.toml里自定义了model_provider还要检查base_url是否写对。很多接入第三方模型失败的案例都是因为base_url末尾多了或少了一个路径段。6.4 常见报错速查表报错关键词常见原因快速处理command not found: codex全局npm目录不在PATH中执行npm prefix -g后配置PATHEACCES: permission deniednpm全局目录权限不足用nvm重装Node避免sudologin timeout网络连通性或授权页未打开检查网络后重试手动粘贴链接Request failed with 401API Key过期或未设置重新执行codex login或刷新Keymodel not found模型名配置错误检查config.toml中model字段local proxy failed本地代理服务或环境变量问题按6.1的步骤排查代理设置排查问题的核心原则其实很简单先判断是网络问题、配置问题还是版本问题一个一个排除不要同时改多个变量。大多数人卡住都是因为一次性改了配置文件、环境变量、又重装了包最后出了问题都搞不清是哪个环节引入的。7. 进阶玩法接入DeepSeek、IDE集成和Harness7.1 把DeepSeek接到Codex除了OpenAI官方模型Codex也支持接入其他兼容OpenAI接口格式的模型服务商DeepSeek就是其中讨论度很高的一个。它的优势是价格便宜某些场景下运行效率也不错。接入方式其实是在config.toml里增加一个自定义的模型提供方。下面是一份可用的配置示例model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat改完之后还需要在环境变量里设置你的DeepSeek API Keyexport DEEPSEEK_API_KEY你的API Key设置好之后重启codex它就会用DeepSeek的模型来响应任务。需要说明的是第三方模型的接口兼容性可能随版本变化如果调用报错优先去查看对应服务商的接口文档确认base_url和wire_api是否需要调整。这种配置方式的价值在于你不需要因为换一个模型服务商就去重新学一套工具Codex作为一个统一的入口把模型层变成了可插拔的组件。7.2 VS Code扩展如果你主要工作在VS Code里可以在扩展市场搜索“Codex”认准OpenAI官方发布的版本安装。安装后你会看到代码编辑器右侧多出一个Codex面板可以直接选中代码片段、让它解释或修改也可以把整个项目上下文发给它。我个人体验是CLI适合大段任务和自动化流程而VS Code扩展适合边看代码边提问的场景。两者共用同一个登录凭证不会有重复配置的麻烦。7.3 codex harness是干什么的最后提一下codex harness。如果你只是日常写代码这一节可以跳过。但如果你关注AI Agent的自动化评测这个词可能会频繁出现。Codex Harness是OpenAI开源的一套评测框架用来在隔离环境里自动运行和评估Codex这类AI编程智能体。它会启动一个Docker容器把任务丢给Agent等它完成后自动检查结果。简单理解这就是一个“AI程序员做题打分的考场搭建工具”。如果你想验证不同模型在代码任务上的实际能力差异或者想搭建自己的Agent评测流水线Harness是个不错的参考实现。但它的架构相对复杂需要你对Docker和CI/CD有一定基础新手不建议一上来就折腾。用了一段时间Codex之后我自己的感受是它解决的不是“怎么写代码”的问题而是“怎么组织一次完整的开发动作”的问题。它把读文件、改代码、跑命令这些零散操作串成了一条可管理、可确认的流水线。你真正要做的是给它一个清晰的目标然后守住最终的质量关。最后再分享一个小技巧使用Codex时任务描述越具体它的表现越好。与其说“帮我优化这个项目”不如说“优化utils.py里的parse_data函数当前它对空字符串会抛异常希望返回空列表并保持兼容现有调用方”。Codex对明确指令的执行稳定度比模糊指令高出一个量级。这个习惯养成之后你会发现不只是Codex你在和所有AI工具打交道时都会更顺手。
Codex CLI 完整安装与配置指南：从零上手终端 AI 编程智能体
上个月帮朋友清理一个历史Python项目里面堆了七八个没人能说清用途的脚本。我打开终端输入codex然后告诉它“帮我把这些脚本的依赖梳理清楚没用的删掉留个README”。几分钟后它先给我列了计划然后自己跑起了pip show逐个确认脚本的import关系改完还在关键位置加了两行注释。整个过程我没怎么动手。这不是我第一次用AI编程工具但Codex确实是第一个让我感觉“像个真人在干活”的终端智能体。这篇文章我打算把Codex从下载、安装到配置的每个环节都写透所有步骤都按我实际跑通过的方式记录争取让零基础的读者照着做也能顺利装好。我会把容易踩的坑、那些报错信息到底什么意思、以及怎么把DeepSeek这类第三方模型接进去一起讲清楚。不管你是刚接触AI编程的新手还是想把手头工具链换一换的开发者应该都能在文章里找到自己需要的部分。1. 先说清楚Codex到底是什么装了它你能得到什么1.1 它不是又一个聊天窗口很多人一听到AI编程工具第一反应是“又是一个网页聊天框”。Codex不太一样它是一个跑在终端里的AI智能体Agent。基本的工作方式是你在项目目录下启动它用自然语言描述需求它会自己去读项目文件、搜索代码、修改文件甚至执行终端命令来验证结果。举例来说如果你说“帮我写一个脚本把当前目录下的CSV文件按日期排序后合并”它的流程通常会是这样先解释自己的计划然后创建脚本文件再跑一次命令验证输出最后把改动的代码展示给你确认。你在整个过程中不是在看一个聊天记录而是在看着一个协作者实际动手。这也意味着它需要拥有比网页聊天更高的权限能执行命令能改文件。所以安装后的配置阶段最重要的其实是“权限边界”这件事。本篇文章后面配置章节会专门讲。1.2 谁最需要它我用了几个月感觉最受益的有这么几类人独立开发者 / 自由职业者一个人就是一支队伍没空把所有库的文档都翻一遍但又要赶交付。Codex适合处理那些“重复但有细节”的开发任务比如接口联调、写单元测试、重构老代码。技术团队的技术负责人Codex可以在新成员入职时用来解释代码仓库结构也可以在代码审查前帮你跑一遍静态梳理。运维和数据分析师处理临时脚本、排查日志、写一次性数据清洗脚本这些场景它表现不错省得你每次都要从零写。非科班但想写代码的人Codex会替你处理很多底层细节你只需要能把需求描述清楚。它不一定能把你变成高级工程师但能让你独立完成不少小项目。当然它也有明显的局限性。比如面对超大仓库时它一次能看到的上下文有限再比如涉及复杂的业务规则时它也会一本正经地给出错误方案。所以我的定位一直是它是很强的助手不是甩手掌柜。1.3 和常见AI编程工具的差异这里做一个简单对比方便你判断自己和哪种工具更合拍工具形态擅长场景主要门槛Codex CLI终端智能体自主改代码、执行命令、跑测试需要习惯命令行操作GitHub CopilotIDE插件写代码时的实时补全编辑器内使用ChatGPT / Claude网页网页对话问答、代码片段生成无法直接操作本地文件CursorAI编辑器在IDE里改项目需要切换整个编辑器Codex最特殊的地方是它在终端里工作这意味着你不必把项目塞进某个编辑器只要项目能用命令行构建和运行它就能接手。对于长期在服务器、容器里干活的人来说这种自由度是别的工具给不了的。不过也要提醒一句正因为它是直接在终端里操作第一次启动时如果配置不当它可能真的会执行一些不是你本意的命令。所以下面环境准备和配置这两章千万别跳过。2. 动手前把环境检查做干净版本依赖和官方渠道2.1 系统和Node.js版本怎么检查Codex CLI本身是一个npm包所以第一依赖是Node.js。不同版本的Codex对Node版本要求略有不同目前主流的版本要求Node.js 18及以上建议直接上20 LTS省得后面遇到兼容性问题。Windows用户特别注意Codex官方推荐在WSL2里使用原生PowerShell下偶尔会有终端交互和文件权限的坑。如果你不想折腾最省心的方式是装好WSL2之后在Ubuntu里操作。macOS用户基本没什么额外负担Linux用户只要能装Node就能装Codex。安装之前先检查一下自己电脑的Node环境。打开终端输入node -v npm -v如果提示找不到命令说明还没装Node.js。安装Node我推荐两个渠道一个是去Node官网下载LTS安装包另一个是用nvmNode Version Manager来管理版本。nvm的好处是以后可以在不同Node版本之间随时切换对经常折腾前端项目的人来说几乎是必需品。# 以nvm为例安装后执行 nvm install 20 nvm use 20装完再次执行node -v确认能看到v20开头的版本号环境这步就算过了。2.2 官方下载渠道有哪些别碰来路不明的“安装包”“Codex下载”这个词在搜索引擎里热度很高但它的下载渠道其实很短目前我使用过的只有以下三个都是官方路径npm安装openai/codex这是最主流的安装方式也是本篇文章主要采用的方式。GitHub ReleasesOpenAI官方在GitHub上发布了Codex的源码和编译产物你可以下载对应平台的二进制包。HomebrewmacOS用户如果没有用npm也可以尝试通过Homebrew安装但需要注意包更新速度可能略慢于npm。看到这里你可能会问那网上那些“Codex安装包下载”“Codex 2026最新版安装包”是什么我的建议是尽量别碰。命令行工具更新频率很高通过包管理器安装才能持续获得更新和新功能。从非官方渠道下载的所谓安装包一来版本可能很旧二来你无法保证里面有没有夹带私货。尤其是需要在终端里执行代码的开发者工具供应链攻击的案例不少工具链来源一定要守住。2.3 npm源慢的问题国内网络环境下npm直接从官方源拉包有时候会很慢甚至超时失败。遇到这种情况可以把npm源切换到国内镜像。这是完全合规且常见的加速手段npm config set registry https://registry.npmmirror.com设置完再安装速度会明显改善。改完镜像源后可以执行npm config get registry确认一下当前源地址。如果后续你想换回官方源执行npm config set registry https://registry.npmjs.org即可。这里再提一个容易被忽略的小点npm安装全局包时Linux和macOS系统下可能会遇到权限问题。如果你看到类似EACCES: permission denied的报错不建议用sudo npm install硬刚更干净的方案是用nvm管理Node这样全局包的安装目录属于当前用户不会出现权限地狱。3. Codex CLI完整安装流程一条命令到命令行补全3.1 用npm安装环境检查没问题后安装其实只是一条命令的事npm install -g openai/codex-g参数表示全局安装这样codex命令就会注册到系统PATH里以后在任何目录都能直接启动。npm安装过程中会输出进度条正常情况下几十秒到几分钟不等取决于你的网络状况。安装结束后终端不会有太多花哨输出所以很多新手会以为没装成功其实只要命令没有报错基本就装好了。如果你之前装过旧版Codex想升级到最新版用npm update -g openai/codex或者干脆先卸载再装npm uninstall -g openai/codex npm install -g openai/codex建议每隔一段时间就升级一次因为Codex迭代非常快功能差异也大。3.2 验证安装和版本安装完成后第一件事是验证命令能不能用codex --version正常会输出类似codex-x.y.z这样的版本号。如果提示command not found大概率是npm全局目录没有加入系统PATH。这时候可以执行npm prefix -g查看全局安装路径然后把该路径加到~/.bashrc或~/.zshrc里。验证版本之后我建议再顺手跑一下codex --help快速扫一眼当前版本支持哪些参数。有些功能可能和你网上看到的教程不一样以你本机版本的帮助信息为准。3.3 Shell集成和命令补全Codex还提供了一些Shell层面的集成装好后可以更方便地在终端里使用。执行codex install它会尝试把Codex的Shell集成脚本写入你的Shell配置文件里。这个集成主要提供几个东西更顺滑的会话体验、命令执行的实时反馈以及一些你自定义的快捷键支持。如果你用的是bash或zsh执行完codex install后重启终端或source ~/.bashrc即可生效。另外新版Codex还支持在现有终端会话里直接通过快捷键呼出而不是每次都要开一个单独的交互界面。这些细节在你实际用起来之后会越来越顺手。安装这步到此结束下面进入最容易出问题、但也是最重要的登录和配置环节。4. 登录与配置ChatGPT授权、API Key和config.toml4.1 登录的两种方式Codex装好后直接输入codex会提示你登录。目前主要有两种登录方式第一种ChatGPT账号授权。如果你有ChatGPT的Plus、Pro或Team订阅可以直接用这个方式登录。执行codex login终端会显示一个code和授权链接你需要在浏览器里打开链接并登录ChatGPT然后输入Codex给的验证码完成授权。授权完成后终端会提示登录成功。第二种API Key方式。如果你更习惯按量付费可以先去OpenAI的API平台创建一个API Key然后登录时选择API Key方式把Key粘贴进去。这种方式很直接适合脚本化、自动化场景。需要提醒的是两种方式的计费逻辑完全不同。ChatGPT订阅是包月制Codex的用量包含在订阅额度里API Key方式则是按token计费跑大量任务时费用可能涨得比你预期快。建议首次接触的朋友先用ChatGPT订阅方式体验确认自己真的需要频繁大量使用后再考虑API方式。登录后Codex会把凭证保存在本地配置目录里。如果哪天提示认证过期或失效重新跑一次codex login即可不需要重装。4.2 config.toml核心配置Codex的配置文件是~/.codex/config.toml。一般情况下登录完成后使用默认配置就能跑但如果想更符合自己的使用习惯可以手动编辑这个文件。下面是一份我目前常用的配置示例model gpt-5 model_provider openai approval_policy suggest [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses逐个解释一下几个关键字段model指定Codex使用的模型具体可根据你账户可用的模型调整。model_provider指定模型提供方默认是OpenAI。approval_policy权限策略这个字段直接决定Codex能替你做多少事非常重要。[model_providers.openai]模型提供方的详细定义其中env_key表示从哪个环境变量读取API Key。如果你登录时选的是ChatGPT授权方式API Key通常已经自动管理好了不一定需要自己设置OPENAI_API_KEY环境变量。但如果你用API Key方式登录建议把Key写入环境变量而不要硬编码到配置文件里避免泄露风险。4.3 权限策略approval_policy怎么选这是我个人认为Codex配置里最需要认真思考的字段。approval_policy控制的是“Codex执行命令和修改文件时到底需要经过你多少确认”。不同版本的可选值可能稍有差异但概念大体一致策略行为适合场景只读模式ReadOnly只读代码、搜索文件不执行任何修改命令代码审查、阅读陌生项目建议模式Suggest执行每个关键操作前都先展示计划等你确认日常开发绝大多数人的首选全自动模式FullAuto不询问直接执行命令和修改已信任的独立沙箱环境或CI我第一次用的时候设的是全自动结果Codex为了完成我交代的任务自作主张安装了一个系统依赖包虽然没造成什么严重后果但吓了我一跳。后来老老实实改回了建议模式。我的建议是除非你非常清楚自己在干什么否则保持默认或者建议模式让Codex“先开口、再动手”你会更安全也更容易理解它的行为逻辑。5. 第一次实战跑通让Codex动真格的完整过程5.1 准备一个实验项目配置完成后建议先不要直接拿去改重要代码库先用一个无关紧要的小项目跑一遍流程熟悉它的脾气。我这里就新建一个临时目录来做演示mkdir ~/codex-demo cd ~/codex-demo git init echo def add(a, b): return a b # TODO: 需要补一个减法函数 calc.py故意留一个没写完的calc.py然后让它补全。之所以强调git init是因为Codex会基于Git工作区来追踪文件变更你后面查看它到底改了什么也方便。5.2 交互式session怎么做在项目目录下直接输入codex它会启动一个交互式会话。输入帮我在calc.py里补一个减法函数并且补一个简单的测试正常情况下Codex会先回复一段简短的计划然后开始创建或修改文件最后把文件内容用diff的形式展示出来。每一步关键操作前它会停下来等你的确认。如果你用的是建议模式终端下方会出现一个选择菜单你可以同意Approve或拒绝Reject它的操作。这台机器上跑下来的实际结果是它很顺利地补了subtract函数加了一个if __name__ __main__的简单测试块并运行了一次文件确认没有语法错误。整个过程大概花了一分钟。如果你不想进入交互模式也可以直接给任务参数codex 帮我给calc.py增加除法函数并处理除数为0的情况这样它会一次性跑完任务然后退出适合脚本化调用。5.3 常用命令和退出在交互式会话里有几个命令我用得最频繁/status查看当前会话里Codex已经执行了多少步改动了哪些文件。/quit退出会话。/model查看或切换当前使用的模型。/reset清空上下文重新开始一个话题。初次操作时你可能会觉得每一步确认有点繁琐但这其实是个好习惯。Codex每次改动文件后Git能让你轻松对比前后差异。我自己的习惯是让它每完成一个子任务就用git diff看一眼改动确认没问题再继续下一个需求。6. 高频报错排查全过程从打不开到模型调用失败再顺手的工具配置过程中也难免遇到报错。下面这几个问题是我在社群里被问到最多的每个我都按实际排查思路写出来照着走一遍基本能解决。6.1 本地代理服务切换失败的报错很多人遇到过这样一段报错cc switch local proxy failed while handling codex endpoint /responses. provi...。第一次看到这个提示我第一反应是配置写错了后来排查了一圈才发现它的意思是Codex在向/responses端点发起请求时本地网络代理服务的切换环节失败了。出现这个报错常见触发场景有两个。第一个是本地代理服务进程本身没有启动或已经崩了第二个是Shell环境里的HTTP_PROXY和HTTPS_PROXY环境变量指向了一个不可达的地址。排查步骤我一般按这个顺序来# 1. 查看当前代理环境变量是否设置 echo $HTTP_PROXY echo $HTTPS_PROXY # 2. 检查代理地址是否可达 curl -I http://localhost:你的代理端口 # 3. 如果代理已经不可用先取消环境变量再重试 unset HTTP_PROXY unset HTTPS_PROXY codex这里所有的排查前提都是你的网络环境本身符合相关服务的使用要求。如果基础网络连通性有问题优先解决网络问题而不是在Codex配置里反复折腾。如果curl确认代理地址可达但Codex依然报同样的错可以再检查一下CA证书相关的配置必要时把NODE_EXTRA_CA_CERTS指到正确的证书文件。这类问题在升级系统或Node版本后更容易出现算是环境变动带来的连锁反应。6.2 登录打不开与认证过期很多人卡在第一步执行codex login终端显示一个链接但浏览器打不开授权页或者打开后页面报错。这种问题大多数情况是网络连通性导致的。确认当前网络能正常访问OpenAI服务后再尝试登录。如果还是打不开可以试试手动在浏览器里粘贴完整链接而不是直接点终端里的链接。有时候终端输出会把链接截断。登录成功后过一段时间可能会遇到提示认证过期或会话失效。这不是什么大问题重新执行codex login即可。如果执行登录后一直转圈可以删除本地旧的凭证文件再重新登录。凭证文件的位置一般在~/.codex/目录下删除前建议先备份。6.3 模型调用失败与网络超时成功登录后偶尔会碰到模型调用失败报错信息通常是超时、连接重置、或者直接提示Request failed with status code ...。排查思路可以分成三块。第一确认模型配置是否存在config.toml里指定的模型名和你的账户可用模型是否匹配。模型名写错是最常见的问题。第二检查网络连通性看能否正常访问api.openai.com域名。第三升级Codex到最新版本旧版本可能因为API协议调整而无法兼容新的模型接口。如果你的config.toml里自定义了model_provider还要检查base_url是否写对。很多接入第三方模型失败的案例都是因为base_url末尾多了或少了一个路径段。6.4 常见报错速查表报错关键词常见原因快速处理command not found: codex全局npm目录不在PATH中执行npm prefix -g后配置PATHEACCES: permission deniednpm全局目录权限不足用nvm重装Node避免sudologin timeout网络连通性或授权页未打开检查网络后重试手动粘贴链接Request failed with 401API Key过期或未设置重新执行codex login或刷新Keymodel not found模型名配置错误检查config.toml中model字段local proxy failed本地代理服务或环境变量问题按6.1的步骤排查代理设置排查问题的核心原则其实很简单先判断是网络问题、配置问题还是版本问题一个一个排除不要同时改多个变量。大多数人卡住都是因为一次性改了配置文件、环境变量、又重装了包最后出了问题都搞不清是哪个环节引入的。7. 进阶玩法接入DeepSeek、IDE集成和Harness7.1 把DeepSeek接到Codex除了OpenAI官方模型Codex也支持接入其他兼容OpenAI接口格式的模型服务商DeepSeek就是其中讨论度很高的一个。它的优势是价格便宜某些场景下运行效率也不错。接入方式其实是在config.toml里增加一个自定义的模型提供方。下面是一份可用的配置示例model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat改完之后还需要在环境变量里设置你的DeepSeek API Keyexport DEEPSEEK_API_KEY你的API Key设置好之后重启codex它就会用DeepSeek的模型来响应任务。需要说明的是第三方模型的接口兼容性可能随版本变化如果调用报错优先去查看对应服务商的接口文档确认base_url和wire_api是否需要调整。这种配置方式的价值在于你不需要因为换一个模型服务商就去重新学一套工具Codex作为一个统一的入口把模型层变成了可插拔的组件。7.2 VS Code扩展如果你主要工作在VS Code里可以在扩展市场搜索“Codex”认准OpenAI官方发布的版本安装。安装后你会看到代码编辑器右侧多出一个Codex面板可以直接选中代码片段、让它解释或修改也可以把整个项目上下文发给它。我个人体验是CLI适合大段任务和自动化流程而VS Code扩展适合边看代码边提问的场景。两者共用同一个登录凭证不会有重复配置的麻烦。7.3 codex harness是干什么的最后提一下codex harness。如果你只是日常写代码这一节可以跳过。但如果你关注AI Agent的自动化评测这个词可能会频繁出现。Codex Harness是OpenAI开源的一套评测框架用来在隔离环境里自动运行和评估Codex这类AI编程智能体。它会启动一个Docker容器把任务丢给Agent等它完成后自动检查结果。简单理解这就是一个“AI程序员做题打分的考场搭建工具”。如果你想验证不同模型在代码任务上的实际能力差异或者想搭建自己的Agent评测流水线Harness是个不错的参考实现。但它的架构相对复杂需要你对Docker和CI/CD有一定基础新手不建议一上来就折腾。用了一段时间Codex之后我自己的感受是它解决的不是“怎么写代码”的问题而是“怎么组织一次完整的开发动作”的问题。它把读文件、改代码、跑命令这些零散操作串成了一条可管理、可确认的流水线。你真正要做的是给它一个清晰的目标然后守住最终的质量关。最后再分享一个小技巧使用Codex时任务描述越具体它的表现越好。与其说“帮我优化这个项目”不如说“优化utils.py里的parse_data函数当前它对空字符串会抛异常希望返回空列表并保持兼容现有调用方”。Codex对明确指令的执行稳定度比模糊指令高出一个量级。这个习惯养成之后你会发现不只是Codex你在和所有AI工具打交道时都会更顺手。