OpenAI Codex CLI入门：AI编程智能体的安装配置与实战

一个月前我在朋友的仓库里跑通了人生中第一个Codex任务。当时我只是随口说了一句“帮我把这几个文件里的接口调用全部统一一下”然后看着它在终端里一个文件一个文件地改跑测试遇到报错还会自己回头修。那种感觉和以前用过的AI编程工具完全不一样——以前是“你写一句它补一段”Codex则是“你交代一句它跑一程”。这篇文章我就按自己的实际操作路径来写先讲清楚Codex到底是什么然后带你把安装、登录、配置走一遍跑通第一个真实任务最后把高频命令和最常见的坑一次说清。无论你是刚听说这个东西还是已经装了但卡在登录或配置上都可以照着一步步来。文章里的命令和配置以当前主流版本为准如果你的版本有点小差别以终端里的--help输出为准。1. Codex到底是什么它和Cursor、Copilot不是同一类工具1.1 一个会“干活”的编程智能体2025年前后的AI编程工具大致分两类一类是Copilot这种“补全选手”在你光标位置给出下一行、下一段代码建议另一类是Cursor这种“对话IDE”你在侧边栏跟模型聊需求它帮你改文件。Codex走的是第三条路线——自主执行。给它一个目标它会自己拆解步骤按顺序读文件、改代码、跑命令、看结果再继续迭代直到任务完成或被你喊停。我举个真实例子。之前我接手一个旧项目一百多个Python文件里全是print调试输出需要统一替换成logging调用同时把数据库连接串抽到配置文件里。这事手动做至少半天。用Codex我在项目根目录启动对话描述完需求后它先分析了目录结构列出修改计划然后挨个文件改动最后自己跑了一遍测试来验证。整个过程中它会在关键节点问我“当前处于只读模式是否允许修改工作区”我确认后它继续。这就是它和对话式补全工具最本质的区别它真的有执行环境能看到代码运行的结果。1.2 三种主要使用形态日常使用中你会接触到三个入口Codex CLI命令行工具也是功能最完整的核心形态。在项目目录里输入codex就能进入交互式会话适合处理本地代码库、批量脚本任务。Codex IDE扩展官方提供VS Code扩展把同样的能力搬到编辑器侧边栏里能看到diff、逐行接受修改交互体验更适合日常编码。Codex云任务在网页端发起任务Codex在云端沙箱里执行。比如你可以在GitHub上扔一个issue给它它在云端改完代码直接提PR。适合不依赖本地环境的自动化场景。对刚入门的人来说我建议先玩熟CLI因为CLI的反馈最直接也最能看出它每一步在做什么。把CLI跑通了再用IDE扩展会觉得顺理成章。1.3 谁适合用Codex适合你如果你经常做这些事项目里批量改格式、跨文件重构、补单元测试、修一堆重复报错如果你不是程序员但需要写脚本处理数据、整理文件如果你在维护一个历史悠久的项目代码量大到不想人肉翻。相反如果你只想在写代码时获得即时补全Copilot或Cursor更顺手。Codex解决的痛点是“知道要改什么但不想亲自改”的那类劳动密集型任务。2. 环境准备Windows与macOS的安装细节2.1 确认依赖与安装路线Codex CLI支持macOS和Windows。安装前先确认Node.js的版本建议至少20 LTS或更高。原因很简单虽然Codex本身是原生二进制但官方主推的安装方式走npmNode版本太老会直接安装失败。macOS上最省事的命令brew install codexWindows上推荐用npm方式在PowerShell里执行npm install -g openai/codex如果你在npm下载阶段经常超时把镜像源切到国内常用的npmmirror就行npm config set registry https://registry.npmmirror.com切换后再重试安装。这一步只影响软件包的下载速度不影响Codex本身的使用。2.2 桌面版和安装器的选择如果不喜欢终端OpenAI也发布了Codex桌面版Windows和macOS都能用。直接去官网下载对应安装包装完打开就是图形界面。注意一点桌面版和CLI共用同一套OpenAI账号体系但会话数据不一定互通。你在这个环境里开的会话换到另一个环境用/resume是恢复不了的别指望跨端同步。另外官方安装脚本在某些版本里也能用。脚本方式的好处是不依赖Node适合环境比较干净、不想装Node的情况。但脚本地址经常变动我建议直接看官网当前给出的安装方式不要在网上翻旧教程里的链接。2.3 安装验证与PATH问题装完先在终端确认codex --version能打印出版本号就说明装好了。如果提示codex: command not found十有八九是npm的全局bin目录没加进PATH。Windows上常见的原因是安装Node时没勾选自动加入PATHmacOS上如果用了nvm可能需要手动加一下当前Node版本的bin路径。这个排查不难运行npm config get prefix拿到全局目录再把对应的bin路径加进环境变量就行。3. 登录与账号准备手机号验证、订阅方案与登录失败处理3.1 codex login 到底做了什么安装完成后第一步是登录。在终端运行codex login终端会显示一个授权链接和一个一次性设备码。用浏览器打开链接登录OpenAI账号输入设备码确认授权。登录成功后Codex会把凭据保存到本机之后使用不用重复登录。登录之前要知道一个前提Codex不是免费的。要么你的ChatGPT账号是Plus/Pro这类订阅官方会开放Codex使用额度要么你是API用户可以给CLI配置API Key。具体配额以账号中心的显示为准。所以“不登录能用吗”这个问题没有悬念——不行核心能力全部要登录后才能用。3.2 手机号验证和短信收不到怎么办新账号在注册或登录时经常触发手机号验证我身边不少人卡在这一步。最容易踩的坑是区号选错短信一直发不到。先确认手机号前面加了正确的国家/地区区号再检查一下短信是不是被手机自带的拦截规则吞了。如果还收不到等几分钟再点一次发送别狂点。验证通过后手机号和账号绑定后续登录会顺很多。如果短信始终到不了换个时间段再试或者联系OpenAI官方支持渠道别走什么野路子。3.3 登录不上、一直在reconnecting的排查顺序“登录不上”和“一直在reconnecting”是入门阶段出现频率最高的两个问题。我的排查顺序是这样的先在浏览器里打开OpenAI官网确认账号能正常登录、订阅状态正常。浏览器没问题但CLI不行看终端报错的关键词是认证失败、网络超时还是连接被重置。换一个网络环境试一遍比如切到手机热点。很多时候是当前网络的连通性问题和Codex本身没关。清除本机保存的旧凭据重新codex login。升级Codex到最新版旧版本的登录流程偶尔有bug。注意Codex的账号体系和服务范围以OpenAI官方公布为准。如果你所在的地区连OpenAI官网都无法正常访问那Codex大概率也会在登录和调用阶段反复出问题。这一点是前提不用在别处找原因。4. 第一次实战让Codex替你改真实代码4.1 交互模式与单次执行的区别在项目目录里直接输入codex会进入交互式REPL模式有一个输入框可以连续对话。如果你只想执行一个一次性任务可以用codex exec 你的任务描述它会跑完任务后直接退出。新手我强烈建议先进交互模式因为你能看到它每一步的计划和动作理解它的工作方式也方便随时打断纠偏。4.2 权限、沙盒和安全习惯初次使用时Codex会引导你选择沙盒模式。三个档次read-only只能读文件和分析代码不能修改任何东西。适合让它做代码评审、解释项目结构。workspace-write允许修改当前工作区里的文件。日常开发用这个最合适。danger-full-access完全放开权限能改任何文件、执行任何命令。只推荐在一次性容器或测试环境里开。权限请求的审批方式也有三种自动接受、手动逐个接受、每次任务询问。新手阶段建议手动逐个接受看清楚每个动作再同意。用一段时间后摸清了它的行为模式再改成自动接受也不迟。4.3 一个可以照抄的小任务假设你有个项目想把所有Python文件里的print改成logger.info同时保证logger正确初始化。可以对Codex说“扫描当前目录下的所有Python文件把print调用替换成logger.info。如果文件顶部没有定义logger就自动创建。改完后运行pytest确认测试全部通过。”Codex会怎么做它一般会先列出计划扫描文件列表、逐文件检查、设计替换规则、执行修改、运行测试。遇到文件写入时会停下来请求权限。你同意后它继续如果pytest挂掉它会读报错信息自己定位是哪个文件改坏了回头修好再重跑。我第一次看它自己修报错时确实有点意外。以前用的工具只负责“生成代码”而Codex会看运行结果这决定了它处理复杂任务时的可靠度完全不一样。4.4 给它清晰的边界有个重要经验Codex的自主能力强但它不是读心机。你的描述越精确结果越可控。比如不要只说“优化一下代码”要说“把用户模块里的重复查询逻辑抽取成公共函数修改对应的测试文件并确保测试通过”。任务边界、验收标准、允许修改的范围这三样东西在描述里讲清楚它基本不会跑偏。如果你只说“优化一下”它可能会顺手改掉一堆无关的东西你审批时还得一条条看diff反而更累。5. 高频命令手册/compact、/model、/resume 的正确打开方式在交互模式里斜杠开头的命令是核心控制手段。我把常用的整理成一张表命令作用什么时候用/help查看帮助记不住命令时/compact压缩当前会话上下文对话太长、上下文快超限时/model切换模型想换一个模型处理当前任务时/resume恢复历史会话回到之前的任务现场/reset清空当前上下文开始一个新任务时/status查看当前会话状态想看当前模型、模式、上下文占用/login/logout重新登录或退出账号异常、更换账号时/quit/exit退出交互模式结束会话5.1 /compact长会话的续命药Codex的上下文窗口再大也有上限。当一个会话聊了太久它会开始“遗忘”前面的细节这时候跑任务容易跑偏。/compact会把当前对话压缩成一份摘要释放上下文空间。它做的事情相当于把聊天记录重新整理成一份精炼的备忘录然后带着这份备忘录继续工作。我的习惯是每次连续对话超过二三十轮或者感觉它在重复问同一个问题时就主动/compact一次。别等到报上下文超限再处理那就有点晚了。5.2 /model随时切换模型/model会弹出当前可用模型列表选中即可切换不用改配置。这个命令很实用比如日常小改动用轻量模型复杂重构切到能力更强的模型成本和质量可以自己平衡。如果你在配置里手动指定了一个不存在的模型名启动或调用时会直接报错比如有朋友在配置文件里写了某个模型名结果终端弹出一段“model is not supported”的提示就是这个原因。解决办法很简单进交互模式按/model看看当前provider真实可用的模型列表改回默认模型即可。5.3 /resume回到上次的工地Codex会把会话记录存在本机一般在~/.codex/sessions目录下。/resume可以列出历史会话选择之后无缝恢复。这个功能特别适合跨天做同一个大任务昨天让Codex改到一半今天回来不需要重述需求直接恢复会话继续。这也是我建议“一个新任务开一个新会话”的原因——会话是按任务隔离的干净利落。6. 配置文件解析模型切换、接入DeepSeek与中文设置6.1 config.toml 的基本结构Codex的全局配置在~/.codex/config.tomlTOML格式。核心字段就几个model gpt-5-codex model_provider openai sandbox_mode workspace-write approval_mode on-requestmodel默认使用的模型。model_provider默认使用的模型提供商。sandbox_mode默认沙盒级别。approval_mode默认审批模式。这些配置项不是必须手动写第一次运行时Codex会用内置默认值。你只需要在需要覆盖默认行为时编辑这个文件。改完配置要重启Codex才生效这是很多人改了没反应的第一原因。6.2 接入DeepSeek等第三方模型Codex CLI支持通过OpenAI兼容接口接入其他模型服务商。这个能力很实用——如果你想在同一个agent框架里调用别的模型不用换工具。以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然后在系统环境变量里设置DEEPSEEK_API_KEY重启Codex生效。这里顺便说下为什么能接Codex对外调用用的是OpenAI的API协议而DeepSeek这类服务商提供的是OpenAI兼容端点所以Codex可以把第三方模型“伪装”成自己的provider来调度。原理不复杂但配置格式容易记错。如果你用的版本对provider配置有细微差别以官方配置文档为准。另外提醒一句第三方模型能不能跑好自主任务取决于模型本身的Agent能力别指望所有模型都能达到Codex官方模型的执行水平。6.3 中文界面设置与“设置了不生效”的修复关于“Codex怎么设置成中文”——新版Codex在设置界面里直接提供了语言选项找到Language或语言相关项选择简体中文保存后重启即可。如果你的版本里找不到这个选项大概率是版本太旧先升级再看。“设置中文之后不生效”是另一个热搜问题。我排查过几个朋友的机器最常见的原因有三个改完设置没有彻底重启Codex进程只关了窗口还不行得连后台进程一起退出。存在多个配置文件互相覆盖比如全局配置里写了一种语言项目级配置里又写了另一种。终端本身不支持中文字体或编码设置有问题Codex其实已经切换了中文只是显示成乱码或方块。如果是第三种情况换一个现代终端模拟器或者在系统设置里检查语言和区域格式就能解决。Codex官方界面本身是支持中文的不需要额外汉化包。7. 在VS Code里用Codex插件市场、聊天面板与右键操作7.1 安装官方扩展VS Code用户想用Codex直接在扩展市场里搜索“Codex”认准发布者是OpenAI官方的那一个点安装。装好后左侧边栏会出现Codex图标打开面板点击Sign In走一遍登录流程。登录方式和CLI一致浏览器授权即可。为什么不建议装来路不明的第三方插件因为登录会携带你的OpenAI账号凭据插件如果被塞了偷凭据的代码风险太大。官方插件之外的那些奇奇怪怪的“Codex增强”我还真见过有人踩坑个人信息安全这种事不值得赌。7.2 编辑器里的工作流在VS Code里用Codex有两个入口一个是侧边栏聊天面板可以直接对话它会读取当前打开文件甚至整个工作区的上下文另一个是选中代码后右键“Ask Codex”把选区拿去做解释、重构或找bug。它给出的修改通常以diff形式展示你可以逐行看决定接受还是丢弃这比CLI里直接改文件要更直观。日常开发建议把VS Code扩展当作主入口CLI留着跑大批量任务和服务端操作两者搭配效率很高。7.3 其他编辑器能不能用有人问PyCharm能不能配置Codex。截至目前JetBrains系列没有官方Codex插件。最务实的做法是在PyCharm终端里直接跑Codex CLI一样能用只是少了可视化diff。官方扩展目前主要就VS Code一条线。顺便提一句现在AI编程工具有好几个Cursor、Codex、Claude Code、Trae各有拥趸。它们不冲突我的分法是CLI批处理任务用Codex重交互的日常编辑用Cursor脚本化的流程用Claude CodeTrae适合新手试水。工具是手段别神化某一个。8. 入门阶段最容易踩的坑与我的使用习惯8.1 五个高频坑第一个坑装了CLI就想用不登录。这个上文说过所有核心功能都被登录墙挡住。第二个坑一上来就授权danger-full-access。我见过有人图省事直接全放开结果Codex改动超出了预期范围想恢复又得费劲找备份。安全习惯要一开始就养成日常workspace-write公共网络测试环境再考虑全放开。第三个坑会话太长不清理。一个会话从早用到晚上下文塞满之后它就开始“失忆”。别舍不得该/compact就/compact该/reset就/reset。第四个坑乱改model字段。看到搜索里有人用了一个很新的模型名我也试过结果直接报错“model is not supported”。模型名必须以你当前provider的可用列表为准别从网上随手抄配置。第五个坑不在git仓库里跑任务。Codex改动文件是不可逆的如果你的项目没做版本控制改错了想回滚就只能哭。任何让它跑任务的项目先git init最好再开一个分支。8.2 我现在的日常工作流用了一段时间后我固定下来的流程是这样的新任务开新会话避免上下文互相污染。进入交互模式先让它用read-only做一轮分析看计划合不合理。确认计划没问题切换到workspace-write权限让它动工。每个阶段都过一遍diff不盲目全盘接受。任务收尾后让它跑一遍测试或lint确认没破坏东西。这套流程看起来多花了几分钟但长期看省掉的是大量返工时间。尤其是“先read-only看计划”这一步给了我一个机会在成本很低的时候叫停可以及时改变方向。8.3 更远一步Skills和内容工作流Codex新版本里有Skills机制可以把一些固定套路打包成技能文件夹后续遇到同类任务它会自动加载并执行。社区里还有人把它用在非编程场景比如配合Remotion的视频渲染管线批量生成短视频素材、做自动化内容生产。这些属于进阶玩法入门阶段先不着急把基础会话、权限管理和命令用熟再慢慢探索这些方向。最后分享一点个人体会。用Codex一段时间后我最明显的变化不是“写代码变快了”而是敢接以前一看就头疼的脏活了——批量改格式、跨文件重构、补测试这些低创造性但高耗时的任务现在基本都丢给它。但它毕竟是工具不是人你给它越清晰的边界和验收标准它给你的结果就越可控。入门的第一步就是别怕在终端里写下codex这四个字母装上、登录、跑通一个小任务你就已经超过了大多数还在观望的人。