最近把日常编码场景基本都迁到了终端里的 Codex CLI 上越用越觉得这东西值得写一份完整的参考笔记。Codex CLI 是 OpenAI 官方出品的命令行编程代理——在终端敲一句话它就能读项目、改代码、跑命令、看报错、再迭代修正整个过程你只需要做 review。这份笔记不是官方文档的翻译而是我从安装到日常使用、从默认配置到接入第三方模型、从踩坑到排查的完整记录重点解决“装好了但不知道怎么写配置”“遇到报错不知道怎么查”这两个高频痛点。适合三类人第一次听说 Codex CLI 的开发者、装完但只会用默认参数的新手以及想把它接到更便宜或私有模型上的技术负责人。1. 从“welcome to codex”说起终端里的 AI 编程代理到底是什么1.1 Codex CLI 是什么为什么选择终端第一次在终端敲下codex看到那行Welcome to Codex, OpenAIs command-line coding agent我就意识到这次思路完全不一样了。它不是在 IDE 里给你补全代码的插件而是一个能直接操作你电脑的智能体读文件、改代码、跑测试、装依赖、看报错全都在当前这台机器的真实环境里完成。为什么是终端因为终端对开发者来说是最不需要额外信任成本的地方。VSCode 插件要适配编辑器版本桌面应用要开 GUI而终端是每一种操作系统都有的通用入口更关键的是不管你是在本地开发、SSH 到服务器、还是写一次性运维脚本终端都会有。Codex CLI 直接长在这个通用入口上意味着它天然具备“操作真实环境”的能力不需要通过编辑器那层间接接口。1.2 它能做什么、不能做什么先说能做的。Codex CLI 的核心能力是理解现存代码库然后直接修改它。你可以让它“给 main.py 加上 argparse 参数”它会先通读你的文件判断改动位置再给出待应用的变更确认后它真的会写文件。它还能执行 shell 命令跑pytest或者npm test看到测试失败输出之后自己分析、自己修修完再跑一遍验证。不能做的事情也需要讲清楚。它不是万能的模型本体而是模型的一个客户端——最终回答质量取决于你配置了哪个模型以及这个模型对工具调用的支持程度。上下文窗口也有限一个巨大仓库不可能全部喂进去它依赖你通过指令文件、会话管理和精准提问把“最重要”的信息暴露给它。最后如果给的指令太模糊它一样会写出让 maintainer 生气的代码。本质上它像一个上手速度非常快的远程实习生方向感需要你把控。1.3 和 Claude Code 这类工具比差异在哪不少朋友问我它和 Claude Code 有什么区别。两者理念几乎同源都认为未来编程入口是“自然语言 终端代理”而不是又一层 IDE 面板。差异主要在三处默认模型体系不同Codex 走 OpenAI 系列Claude Code 走 Anthropic 系列审批与权限机制的成熟度不同Codex 对“文件写入、命令执行、MCP 调用”三类权限是分开管控的生态上 Claude Code 社区插件多Codex 官方迭代速度快。如果你只打算长期用其中一款我的建议是别纠结“哪个强”先看你日常用的 API 是哪个体系。如果你本来就在用 OpenAI 系的模型或者打算接入各类兼容服务Codex CLI 的自然语言交互和沙箱机制足够稳。本文后续所有操作都是以 Codex CLI 为基准展开的。2. 环境准备与安装先把环境跑起来2.1 前置依赖Node.js 与 npmCodex CLI 是基于 Node.js 构建的所以第一件事是把 Node 装好。官方要求 Node 18 以上我的建议是直接用当前 LTS 版本20 或更新省得以后遇到兼容性问题。先确认环境node -v npm -v两条命令都能输出版本号说明基础环境没问题。没有 Node 的话去官网下载 LTS 安装包即可macOS 也可以用 Homebrew 装装完顺手把全局bin路径写进 shell 配置。为什么这个工具用 Node 而不是 Go、Rust说白了是生态原因OpenAI 的 CLI 最开始就是 TypeScript 技术栈npm 上现成的包多后续插件的扩展路径也顺。普通用户不需要关心这一点只要知道“缺 Node 就装不上”就行。2.2 安装、登录与版本管理安装就是一条命令npm install -g openai/codexlatest装完先验证版本codex --version第一次运行codex会引导登录。执行codex login会弹出浏览器窗口用 ChatGPT 账号完成授权授权凭证会存到本地。如果你更习惯 API Key 方式可以在当前 shell 里设置环境变量OPENAI_API_KEYCodex 会自动读取并使用这个凭证。登录凭证的位置在~/.codex/auth.jsonmacOS/Linux或用户目录下的.codex/auth.jsonWindows。这个文件以后排查登录问题会用到——当授权状态异常时删掉它重新codex login往往比在网页端折腾更快。升级和卸载也很简单npm update -g openai/codex npm uninstall -g openai/codex现在 Codex 也有桌面版了习惯 GUI 的朋友可以下载桌面版但 CLI 在脚本化、自动化和服务器场景里仍然不可替代这篇笔记聚焦 CLI 方向。2.3 Windows 环境两个经典坑Windows 用户最容易栽的第一个坑是 PowerShell 执行策略。很多人执行npm install -g时没问题一运行codex就报类似 “npm: 无法加载文件 ...npm.ps1因为在此系统上禁止运行脚本” 的错。这不是 Codex 的问题而是 Windows 默认禁止执行本地脚本。处理方式用管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned原理是RemoteSigned允许本机创建的脚本运行只有从远程下载的脚本才要求签名对个人开发者来说足够安全又省心。第二个坑是codex命令找不到。npm 全局包的 bin 目录通常不在 PATH 里可以执行npm config get prefix查看全局路径再把prefix目录加入系统 PATH。装了 nvm 的同学一般不会有这个问题因为 nvm 会自动把全局 bin 配好。如果这两个坑都没有但启动时仍然提示找不到组件参考第 6 章的排查清单。3. 配置文件细读每个参数背后的为什么3.1 config.toml 的位置与整体结构Codex CLI 的配置主文件是config.toml位于~/.codex/config.toml。没有这个文件Codex 也会用默认值跑起来但想真正把它调到好用还是得手动建这个文件。整体结构分三层。顶层是一堆常规选项比如默认模型、权限策略、安静模式接下来是[model_providers.*]表格每一张表定义一个模型提供方provider你可以定义多个再往下是审批策略、沙箱工作区等更细粒度的权限设置。这个分层的设计思路很清楚把“选择哪个模型”和“模型从哪里来”解耦把“能不能做”和“怎么做”分开这样日常切换模型不会影响权限规则。强烈建议每一次改完配置都执行codex --help或codex /status确认当前生效的参数不同版本之间字段名会有细微差异。3.2 模型与模型提供方配置默认情况下Codex 会请求 OpenAI 官方服务。但真正让它变得灵活的是自定义 provider。下面这个配置把 DeepSeek 加进来model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat然后设置环境变量DEEPSEEK_API_KEYCodex 就会通过base_url指向的兼容端点发请求。这里有几个参数你必须理解因为绝大多数对接报错都出在它们身上。base_url是请求的根地址。Codex 会把对话补全的请求路径拼在后面所以如果base_url写错了最常见的错误就是 404 或者连接失败。env_key告诉 Codex 从哪个环境变量读取 API Key写错了就会一直 401。wire_api则决定用 OpenAI 的哪种协议格式官方新模型用responses很多第三方兼容端点只实现了chat也就是 chat/completions 协议。如果你的后端只支持chat你却配成responses报错就会非常隐晦。切换任何 provider 之后先用一个最简单的对话验证连通性再投入真实任务。3.3 权限与沙箱把 AI 锁在笼子里让 AI 在终端里执行命令信任问题比能力问题更关键。Codex 提供了几个权限档位approval_policy on-request # 默认写文件/执行命令前都会询问 approval_policy never # 不询问完全自动 approval_policy on-failure # 只在命令执行失败时询问 approval_policy unrestricted # 完全放开不推荐日常用我的实际建议是日常开发锁在on-request让 AI 每次改文件、跑命令前都先汇报当你把工作区限定到某个独立实验项目里再考虑放宽到never。AI 生成的命令有时候看起来合理实际跑出来的副作用完全不可控宁可多看一次确认。同时配合沙箱模式使用。sandbox-mode可以设为read-onlyAI 只能读不能写、workspace-write只能写当前工作区、danger-full-access无限制。这个机制的价值在于即使 AI 在会话中产生了“出格”的意图物理上也动不了工作区以外的文件。提示权限和沙箱是 Codex 使用里面最值得花时间理解的部分。把它当成你给实习生开账号时的权限矩阵——开局可以限制得严一点摸清脾气之后再慢慢放开。3.4 那些容易被忽略的实用配置有几个选项平时不起眼但实际体验差别很大。quiet可以减少日志输出适合在自动化脚本里调用 Codex 时使用。autoupdate决定要不要自动更新 CLI 版本介意新版本行为变化的人可以关掉手动更新。skip_git_repo_check用于允许在非 Git 目录中运行不过我个人不建议关掉这个检查——Git 仓库是回溯所有 AI 改动的安全网没有它你很难 diff 看出 AI 动了什么。还有一个我很看重的机制项目指令文件。Codex 支持读取项目根目录下的AGENTS.md或CODEX.md作为“项目说明书”你可以在里面写清构建命令、测试命令、目录结构、代码规范、绝对不做的事。AI 每次开工前会先读它相当于给 AI 注入项目的背景知识。这一条强烈推荐每个人用起来收益比想象中大得多。4. 日常使用全流程从一句话到一段代码落地4.1 第一次启动会话与编写第一个任务在项目目录下直接输入codex进入交互式会话。界面会提示当前你处于哪个目录、Git 状态如何。举个例子。假设你有一个 Python 项目想给main.py增加命令行参数处理可以这样输入给 main.py 加上 argparse 支持提供 --input 和 --output 两个参数 默认值分别是 data/in.txt 和 data/out.txt不要改动其他函数。Codex 会先读main.py可能还会看一眼同目录的文件然后给出它准备做的修改计划并且因为权限策略是默认的on-request它会等你确认才真正写文件。这个流程非常关键AI 在写文件之前已经先经过“读取-理解-规划-申请”四个阶段。如果不想进入交互式会话也可以一次性执行codex 给 main.py 加上 argparse支持 --input 和 --output 参数它会直接处理这个请求但同样会在写文件前等待你确认。4.2 常用内置命令与会话管理进入会话后有几个斜杠命令必须知道/init让 Codex 扫描当前目录并生成/建议项目的初始配置适合新项目首次接入。/status查看当前会话状态、已用 token 量、当前模型与工作区范围。/model在会话里临时切换模型方便对比不同模型的输出质量。/help随时查看内置命令帮助。/quit或/exit退出会话。会话管理是我非常喜欢的部分。Codex 支持断点续聊用--resume接续某个历史会话用--session开启新会话。实际迭代一个功能时我往往上午让 AI 实现第一版下午回来--resume让它继续优化上下文还都保留着不需要重新交代背景。用codex --list之类的命令可以回看历史会话列表这一点在长时间项目里非常实用。4.3 一次完整的“报错→修复”闭环看一个完整的实操闭环比零散命令更有参考价值。第一步我故意在测试文件里留下一个 bug然后对 Codex 说“跑一下测试看哪里挂了”。Codex 执行pytest终端里出现失败堆栈它会主动把报错信息读进自己的上下文然后分析根因。第二步我说“修好它但不要改公共接口”它提出一个修改方案定位到具体的函数给出 diff。第三步我确认后它写入文件然后我会补一句“再跑一遍测试验证”它会重新执行测试命令直到确认通过。这里重点不在于 AI 一次成功而在于整个链路是闭环的发现问题、定位原因、修改代码、运行验证全部由 AI 在真实环境里完成你只需要在每个环节做判断。相比“从 IDE 复制报错到网页里问再粘回来”效率差别非常大。因为这个流程有实时行为安全网很重要。我每次开始这类任务前都会确认当前在 Git 仓库内并且在工作区沙箱限制下运行。即使 AI 做出了不可控的修改git diff和git checkout能让我一分钟内回滚。4.4 结合 Git 工作流的协作技巧Codex 和 Git 结合得好才算真正融入开发流。最常见的一个用法是提交信息生成写完代码后对 Codex 说“git diff 看一下帮我生成 commit message按 conventional commits 风格”。它会先git diff分析改动内容再给出几条 commit message 候选。这比手动敲 message 省时间而且它确实会认真看你到底改了哪些行。第二个用法是变更自查对 Codex 说“帮我 review 这次 diff找出潜在的 bug 或遗漏”。它会把 diff 从头看一遍指出哪些地方不安全或者逻辑不完整。这种“AI review 自己写的代码”的过程能在提交前拦截掉很多低级错误。第三如果你有远端 issue 文本直接把 issue 内容粘贴给 Codex让它“按这个需求实现然后提交”。它在看 issue 之后开工产出的代码往往更贴近需求描述。注意它不会自动 push推送前建议你自己看一下git log和git diff。5. 第三方模型接入把 Codex CLI 接到 DeepSeek 等兼容服务5.1 为什么要换模型什么时候值得换Codex CLI 用户里很大比例都在折腾接入第三方模型核心驱动力无非三个成本、速率、可用性。OpenAI 官方模型能力强但计费对高频入门用户不太友好第三方兼容服务在 API 价格和并发速率上有明显优势另外不少团队有内网私有化模型需求希望把 Codex 的交互层接在自己内部的模型服务上。Codex CLI 在这件事上做得聪明的地方是它把“模型提供方”做成了可配置层只要对方实现了 OpenAI 的chat/completions或responses协议就能接进来。这不是破解也不是绕过而是官方支持的扩展能力。什么时候值得换如果你每天跑大量类似“生成测试、批量重构”这类任务、对推理能力要求不那么极限完全可以把高频琐碎任务放在低成本模型上有硬骨头再切回强力模型。5.2 DeepSeek 接入配置实战以 DeepSeek 为例完整操作如下。先确认环境变量export DEEPSEEK_API_KEY你的key然后修改~/.codex/config.tomlmodel deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat保存后在项目目录跑一次最简单的验证codex 11等于几能正常回答说明连接通了如果报 401查env_key是否和实际环境变量一致如果报 404查base_url是否正确尤其注意不要多写/v1之类的路径如果是 400 或协议错误查wire_api是否匹配。一个容易被忽略的点Codex 的很多高级功能比如“AI 自己运行命令并读取结果”依赖模型对工具调用tool calling的支持程度。第三方模型如果只支持纯文本对话Codex 就退化成“能改文件但不会自主执行命令”的弱化形态。DeepSeek 这类模型在常见任务上可用但如果你发现 AI 经常在“我无法直接运行命令”这类回答里打转大概率就是模型工具调用兼容性不足这时候要么换模型要么明确告诉它你手动执行命令后把结果贴给它。5.3 用 cc switch 管理多套配置当我有“官方模型”“低成本模型”“团队内网模型”几套不同配置之后手动改config.toml就会变得很痛苦。社区里有个开源工具叫 cc switch专门做 Codex以及 Claude Code的多配置管理核心功能是保存多份配置和凭证一键切换并验证新配置能否连通。cc switch 的原理不复杂它会在你的~/.codex目录下维护多套配置模板切换时替换config.toml和相关鉴权文件并检测当前环境变量。但它不会碰你的代码也不会上传任何东西。实际使用中我遇到最多的问题反而是切换之后忘了刷新环境变量——shell 里还保留着旧 provider 的 key新 provider 根本读不到。切换完先执行env | grep -i api看一眼环境变量再跑一条测试命令能少踩很多坑。注意第三方的配置管理工具更新节奏不一如果切换后出现类似“handling codex endpoint /responses failed”的报错优先检查新配置的 base_url、api key、wire_api 三者是否匹配不要第一时间怀疑工具坏了。6. 常见问题速查与避坑实录6.1 安装与启动问题codex命令找不到。npm 全局包的 bin 目录不在 PATH 里。执行npm config get prefix把输出目录加入系统 PATH。注意改完要重新开终端才会生效。PowerShell 提示无法加载脚本。如 2.3 节所述用管理员权限执行Set-ExecutionPolicy RemoteSigned。提示 unable to locate the codex cli binary or required runtime components。这个报错通常说明安装不完整或运行时组件缺失。第一优先做法卸载后重新安装最新版npm uninstall -g openai/codex npm install -g openai/codexlatest然后再codex --version验证。如果还不行检查是否用了比较老的 Node 版本尽量升级到 20 再试。npm 安装太慢或反复失败。把 npm registry 切换为国内镜像服务然后重新安装。装完之后再跑一次codex --version确认。6.2 登录与鉴权问题codex login无法完成授权。先看浏览器是否能正常打开授权页如果授权页打不开大概率是网络环境问题。也可以删掉~/.codex/auth.json后重新登录清掉可能损坏的本地凭证。一直 401 unauthorized。检查环境变量是否真的设置成功echo $OPENAI_API_KEYmacOS/Linux或echo $env:OPENAI_API_KEYWindows PowerShell。如果用了自定义 provider检查env_key配置的变量名是否和实际一致。403 forbidden。通常是 API Key 没有访问指定模型的权限或者该模型在你当前网络环境中不可用。换一个模型名试试或者确认 Key 对应的账号是否有该模型访问权。6.3 请求与连接问题切换配置后报错 handling codex endpoint /responses failed。这是很常见的对接类报错。按顺序排查先确认base_url是否可达用curl探一下端点再确认wire_api和你所用的后端是否匹配接着看环境变量里 key 是否被正确读取最后用最简 prompt 跑一遍连通测试。如果自定义配置没问题再考虑是不是 cc switch 这类切换工具没把旧环境变量清理干净。请求返回乱码或中英文错乱。终端编码问题。Windows 下使用 Windows Terminal 并设置 UTF-8 编码macOS/Linux 一般不会出现。返回内容经常被截断。上下文窗口不够用。要么精简项目说明把无关文件排除要么用--model切换上下文更大的模型也可以把一个大任务拆成多个小会话每个会话聚焦一个文件或一个功能。6.4 功能行为问题与排查思路AI 尝试修改我不想动的文件。权限策略没有限制住工作区。建议开启沙箱read-only或workspace-write同时用自然语言明确告诉它“只允许改动 src 目录下的文件其他地方一律不要碰”。每次写文件都询问太多效率低。如果你已经在一个实验性项目里摸清了 AI 的行为规律可以临时把approval_policy调整为on-failure甚至never但切回正式项目时记得调回来。反复在多个项目间切换时推荐维护两份配置或借助 cc switch 快速切换。终端卡住敲不出字母。大多数情况是会话中有命令在等待输入。先尝试CtrlC中断当前操作不行就CtrlD退出会话重新进入。Windows 下尽量用 Windows Terminal而不是老旧控制台输入和编码体验会好很多。AI 的改动在 git 中无法追踪。这通常是因为你在非 Git 目录运行了 Codex。建议要么把项目初始化成 Git 仓库要么至少备份一份目录快照再去跑自动化修改任务。没有版本管理兜底的 AI 改代码风险等级直接上一个台阶。把上面这些整理成一个速查表现象最常见原因首查项codex 命令找不到npm bin 目录不在 PATHnpm config get prefix安装后提示组件缺失Node 版本过旧/安装不完整重装最新版、升级 Node登录无法弹窗网络问题/本地凭证损坏清理 auth.json 重新登录401API Key 未设置/变量名不匹配echo 检查环境变量403Key 无权限或模型不可用换 Key 或换模型404base_url 或请求路径不对curl 探端点响应乱码终端编码非 UTF-8切换 Windows Terminal输出截断上下文窗口不足精简任务、拆分会话AI 乱动文件沙箱权限过宽开启 workspace-write 限制最后分享几点我个人在实际使用中的体会。Codex CLI 用得好不好和三件事强相关权限设置要在开工前想清楚项目指令文件要写清楚每次让 AI 改动前先说明可验收的边界条件。我长期只在on-request模式下让它自动改文件验证过多轮之后才敢在特定项目里放开权限这个流程别嫌麻烦。另外强烈建议在项目里维护一份AGENTS.md——把构建命令、测试命令、格式化规范、绝对禁忌写进去AI 每次开工前先读一遍整个体验会提升一个量级。这一条不在官方入门文档的显眼位置但实测收益最大。先写到这等踩到新坑再回来补。
Codex CLI 完全指南：终端AI编程代理的安装配置与实战手册
最近把日常编码场景基本都迁到了终端里的 Codex CLI 上越用越觉得这东西值得写一份完整的参考笔记。Codex CLI 是 OpenAI 官方出品的命令行编程代理——在终端敲一句话它就能读项目、改代码、跑命令、看报错、再迭代修正整个过程你只需要做 review。这份笔记不是官方文档的翻译而是我从安装到日常使用、从默认配置到接入第三方模型、从踩坑到排查的完整记录重点解决“装好了但不知道怎么写配置”“遇到报错不知道怎么查”这两个高频痛点。适合三类人第一次听说 Codex CLI 的开发者、装完但只会用默认参数的新手以及想把它接到更便宜或私有模型上的技术负责人。1. 从“welcome to codex”说起终端里的 AI 编程代理到底是什么1.1 Codex CLI 是什么为什么选择终端第一次在终端敲下codex看到那行Welcome to Codex, OpenAIs command-line coding agent我就意识到这次思路完全不一样了。它不是在 IDE 里给你补全代码的插件而是一个能直接操作你电脑的智能体读文件、改代码、跑测试、装依赖、看报错全都在当前这台机器的真实环境里完成。为什么是终端因为终端对开发者来说是最不需要额外信任成本的地方。VSCode 插件要适配编辑器版本桌面应用要开 GUI而终端是每一种操作系统都有的通用入口更关键的是不管你是在本地开发、SSH 到服务器、还是写一次性运维脚本终端都会有。Codex CLI 直接长在这个通用入口上意味着它天然具备“操作真实环境”的能力不需要通过编辑器那层间接接口。1.2 它能做什么、不能做什么先说能做的。Codex CLI 的核心能力是理解现存代码库然后直接修改它。你可以让它“给 main.py 加上 argparse 参数”它会先通读你的文件判断改动位置再给出待应用的变更确认后它真的会写文件。它还能执行 shell 命令跑pytest或者npm test看到测试失败输出之后自己分析、自己修修完再跑一遍验证。不能做的事情也需要讲清楚。它不是万能的模型本体而是模型的一个客户端——最终回答质量取决于你配置了哪个模型以及这个模型对工具调用的支持程度。上下文窗口也有限一个巨大仓库不可能全部喂进去它依赖你通过指令文件、会话管理和精准提问把“最重要”的信息暴露给它。最后如果给的指令太模糊它一样会写出让 maintainer 生气的代码。本质上它像一个上手速度非常快的远程实习生方向感需要你把控。1.3 和 Claude Code 这类工具比差异在哪不少朋友问我它和 Claude Code 有什么区别。两者理念几乎同源都认为未来编程入口是“自然语言 终端代理”而不是又一层 IDE 面板。差异主要在三处默认模型体系不同Codex 走 OpenAI 系列Claude Code 走 Anthropic 系列审批与权限机制的成熟度不同Codex 对“文件写入、命令执行、MCP 调用”三类权限是分开管控的生态上 Claude Code 社区插件多Codex 官方迭代速度快。如果你只打算长期用其中一款我的建议是别纠结“哪个强”先看你日常用的 API 是哪个体系。如果你本来就在用 OpenAI 系的模型或者打算接入各类兼容服务Codex CLI 的自然语言交互和沙箱机制足够稳。本文后续所有操作都是以 Codex CLI 为基准展开的。2. 环境准备与安装先把环境跑起来2.1 前置依赖Node.js 与 npmCodex CLI 是基于 Node.js 构建的所以第一件事是把 Node 装好。官方要求 Node 18 以上我的建议是直接用当前 LTS 版本20 或更新省得以后遇到兼容性问题。先确认环境node -v npm -v两条命令都能输出版本号说明基础环境没问题。没有 Node 的话去官网下载 LTS 安装包即可macOS 也可以用 Homebrew 装装完顺手把全局bin路径写进 shell 配置。为什么这个工具用 Node 而不是 Go、Rust说白了是生态原因OpenAI 的 CLI 最开始就是 TypeScript 技术栈npm 上现成的包多后续插件的扩展路径也顺。普通用户不需要关心这一点只要知道“缺 Node 就装不上”就行。2.2 安装、登录与版本管理安装就是一条命令npm install -g openai/codexlatest装完先验证版本codex --version第一次运行codex会引导登录。执行codex login会弹出浏览器窗口用 ChatGPT 账号完成授权授权凭证会存到本地。如果你更习惯 API Key 方式可以在当前 shell 里设置环境变量OPENAI_API_KEYCodex 会自动读取并使用这个凭证。登录凭证的位置在~/.codex/auth.jsonmacOS/Linux或用户目录下的.codex/auth.jsonWindows。这个文件以后排查登录问题会用到——当授权状态异常时删掉它重新codex login往往比在网页端折腾更快。升级和卸载也很简单npm update -g openai/codex npm uninstall -g openai/codex现在 Codex 也有桌面版了习惯 GUI 的朋友可以下载桌面版但 CLI 在脚本化、自动化和服务器场景里仍然不可替代这篇笔记聚焦 CLI 方向。2.3 Windows 环境两个经典坑Windows 用户最容易栽的第一个坑是 PowerShell 执行策略。很多人执行npm install -g时没问题一运行codex就报类似 “npm: 无法加载文件 ...npm.ps1因为在此系统上禁止运行脚本” 的错。这不是 Codex 的问题而是 Windows 默认禁止执行本地脚本。处理方式用管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned原理是RemoteSigned允许本机创建的脚本运行只有从远程下载的脚本才要求签名对个人开发者来说足够安全又省心。第二个坑是codex命令找不到。npm 全局包的 bin 目录通常不在 PATH 里可以执行npm config get prefix查看全局路径再把prefix目录加入系统 PATH。装了 nvm 的同学一般不会有这个问题因为 nvm 会自动把全局 bin 配好。如果这两个坑都没有但启动时仍然提示找不到组件参考第 6 章的排查清单。3. 配置文件细读每个参数背后的为什么3.1 config.toml 的位置与整体结构Codex CLI 的配置主文件是config.toml位于~/.codex/config.toml。没有这个文件Codex 也会用默认值跑起来但想真正把它调到好用还是得手动建这个文件。整体结构分三层。顶层是一堆常规选项比如默认模型、权限策略、安静模式接下来是[model_providers.*]表格每一张表定义一个模型提供方provider你可以定义多个再往下是审批策略、沙箱工作区等更细粒度的权限设置。这个分层的设计思路很清楚把“选择哪个模型”和“模型从哪里来”解耦把“能不能做”和“怎么做”分开这样日常切换模型不会影响权限规则。强烈建议每一次改完配置都执行codex --help或codex /status确认当前生效的参数不同版本之间字段名会有细微差异。3.2 模型与模型提供方配置默认情况下Codex 会请求 OpenAI 官方服务。但真正让它变得灵活的是自定义 provider。下面这个配置把 DeepSeek 加进来model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat然后设置环境变量DEEPSEEK_API_KEYCodex 就会通过base_url指向的兼容端点发请求。这里有几个参数你必须理解因为绝大多数对接报错都出在它们身上。base_url是请求的根地址。Codex 会把对话补全的请求路径拼在后面所以如果base_url写错了最常见的错误就是 404 或者连接失败。env_key告诉 Codex 从哪个环境变量读取 API Key写错了就会一直 401。wire_api则决定用 OpenAI 的哪种协议格式官方新模型用responses很多第三方兼容端点只实现了chat也就是 chat/completions 协议。如果你的后端只支持chat你却配成responses报错就会非常隐晦。切换任何 provider 之后先用一个最简单的对话验证连通性再投入真实任务。3.3 权限与沙箱把 AI 锁在笼子里让 AI 在终端里执行命令信任问题比能力问题更关键。Codex 提供了几个权限档位approval_policy on-request # 默认写文件/执行命令前都会询问 approval_policy never # 不询问完全自动 approval_policy on-failure # 只在命令执行失败时询问 approval_policy unrestricted # 完全放开不推荐日常用我的实际建议是日常开发锁在on-request让 AI 每次改文件、跑命令前都先汇报当你把工作区限定到某个独立实验项目里再考虑放宽到never。AI 生成的命令有时候看起来合理实际跑出来的副作用完全不可控宁可多看一次确认。同时配合沙箱模式使用。sandbox-mode可以设为read-onlyAI 只能读不能写、workspace-write只能写当前工作区、danger-full-access无限制。这个机制的价值在于即使 AI 在会话中产生了“出格”的意图物理上也动不了工作区以外的文件。提示权限和沙箱是 Codex 使用里面最值得花时间理解的部分。把它当成你给实习生开账号时的权限矩阵——开局可以限制得严一点摸清脾气之后再慢慢放开。3.4 那些容易被忽略的实用配置有几个选项平时不起眼但实际体验差别很大。quiet可以减少日志输出适合在自动化脚本里调用 Codex 时使用。autoupdate决定要不要自动更新 CLI 版本介意新版本行为变化的人可以关掉手动更新。skip_git_repo_check用于允许在非 Git 目录中运行不过我个人不建议关掉这个检查——Git 仓库是回溯所有 AI 改动的安全网没有它你很难 diff 看出 AI 动了什么。还有一个我很看重的机制项目指令文件。Codex 支持读取项目根目录下的AGENTS.md或CODEX.md作为“项目说明书”你可以在里面写清构建命令、测试命令、目录结构、代码规范、绝对不做的事。AI 每次开工前会先读它相当于给 AI 注入项目的背景知识。这一条强烈推荐每个人用起来收益比想象中大得多。4. 日常使用全流程从一句话到一段代码落地4.1 第一次启动会话与编写第一个任务在项目目录下直接输入codex进入交互式会话。界面会提示当前你处于哪个目录、Git 状态如何。举个例子。假设你有一个 Python 项目想给main.py增加命令行参数处理可以这样输入给 main.py 加上 argparse 支持提供 --input 和 --output 两个参数 默认值分别是 data/in.txt 和 data/out.txt不要改动其他函数。Codex 会先读main.py可能还会看一眼同目录的文件然后给出它准备做的修改计划并且因为权限策略是默认的on-request它会等你确认才真正写文件。这个流程非常关键AI 在写文件之前已经先经过“读取-理解-规划-申请”四个阶段。如果不想进入交互式会话也可以一次性执行codex 给 main.py 加上 argparse支持 --input 和 --output 参数它会直接处理这个请求但同样会在写文件前等待你确认。4.2 常用内置命令与会话管理进入会话后有几个斜杠命令必须知道/init让 Codex 扫描当前目录并生成/建议项目的初始配置适合新项目首次接入。/status查看当前会话状态、已用 token 量、当前模型与工作区范围。/model在会话里临时切换模型方便对比不同模型的输出质量。/help随时查看内置命令帮助。/quit或/exit退出会话。会话管理是我非常喜欢的部分。Codex 支持断点续聊用--resume接续某个历史会话用--session开启新会话。实际迭代一个功能时我往往上午让 AI 实现第一版下午回来--resume让它继续优化上下文还都保留着不需要重新交代背景。用codex --list之类的命令可以回看历史会话列表这一点在长时间项目里非常实用。4.3 一次完整的“报错→修复”闭环看一个完整的实操闭环比零散命令更有参考价值。第一步我故意在测试文件里留下一个 bug然后对 Codex 说“跑一下测试看哪里挂了”。Codex 执行pytest终端里出现失败堆栈它会主动把报错信息读进自己的上下文然后分析根因。第二步我说“修好它但不要改公共接口”它提出一个修改方案定位到具体的函数给出 diff。第三步我确认后它写入文件然后我会补一句“再跑一遍测试验证”它会重新执行测试命令直到确认通过。这里重点不在于 AI 一次成功而在于整个链路是闭环的发现问题、定位原因、修改代码、运行验证全部由 AI 在真实环境里完成你只需要在每个环节做判断。相比“从 IDE 复制报错到网页里问再粘回来”效率差别非常大。因为这个流程有实时行为安全网很重要。我每次开始这类任务前都会确认当前在 Git 仓库内并且在工作区沙箱限制下运行。即使 AI 做出了不可控的修改git diff和git checkout能让我一分钟内回滚。4.4 结合 Git 工作流的协作技巧Codex 和 Git 结合得好才算真正融入开发流。最常见的一个用法是提交信息生成写完代码后对 Codex 说“git diff 看一下帮我生成 commit message按 conventional commits 风格”。它会先git diff分析改动内容再给出几条 commit message 候选。这比手动敲 message 省时间而且它确实会认真看你到底改了哪些行。第二个用法是变更自查对 Codex 说“帮我 review 这次 diff找出潜在的 bug 或遗漏”。它会把 diff 从头看一遍指出哪些地方不安全或者逻辑不完整。这种“AI review 自己写的代码”的过程能在提交前拦截掉很多低级错误。第三如果你有远端 issue 文本直接把 issue 内容粘贴给 Codex让它“按这个需求实现然后提交”。它在看 issue 之后开工产出的代码往往更贴近需求描述。注意它不会自动 push推送前建议你自己看一下git log和git diff。5. 第三方模型接入把 Codex CLI 接到 DeepSeek 等兼容服务5.1 为什么要换模型什么时候值得换Codex CLI 用户里很大比例都在折腾接入第三方模型核心驱动力无非三个成本、速率、可用性。OpenAI 官方模型能力强但计费对高频入门用户不太友好第三方兼容服务在 API 价格和并发速率上有明显优势另外不少团队有内网私有化模型需求希望把 Codex 的交互层接在自己内部的模型服务上。Codex CLI 在这件事上做得聪明的地方是它把“模型提供方”做成了可配置层只要对方实现了 OpenAI 的chat/completions或responses协议就能接进来。这不是破解也不是绕过而是官方支持的扩展能力。什么时候值得换如果你每天跑大量类似“生成测试、批量重构”这类任务、对推理能力要求不那么极限完全可以把高频琐碎任务放在低成本模型上有硬骨头再切回强力模型。5.2 DeepSeek 接入配置实战以 DeepSeek 为例完整操作如下。先确认环境变量export DEEPSEEK_API_KEY你的key然后修改~/.codex/config.tomlmodel deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat保存后在项目目录跑一次最简单的验证codex 11等于几能正常回答说明连接通了如果报 401查env_key是否和实际环境变量一致如果报 404查base_url是否正确尤其注意不要多写/v1之类的路径如果是 400 或协议错误查wire_api是否匹配。一个容易被忽略的点Codex 的很多高级功能比如“AI 自己运行命令并读取结果”依赖模型对工具调用tool calling的支持程度。第三方模型如果只支持纯文本对话Codex 就退化成“能改文件但不会自主执行命令”的弱化形态。DeepSeek 这类模型在常见任务上可用但如果你发现 AI 经常在“我无法直接运行命令”这类回答里打转大概率就是模型工具调用兼容性不足这时候要么换模型要么明确告诉它你手动执行命令后把结果贴给它。5.3 用 cc switch 管理多套配置当我有“官方模型”“低成本模型”“团队内网模型”几套不同配置之后手动改config.toml就会变得很痛苦。社区里有个开源工具叫 cc switch专门做 Codex以及 Claude Code的多配置管理核心功能是保存多份配置和凭证一键切换并验证新配置能否连通。cc switch 的原理不复杂它会在你的~/.codex目录下维护多套配置模板切换时替换config.toml和相关鉴权文件并检测当前环境变量。但它不会碰你的代码也不会上传任何东西。实际使用中我遇到最多的问题反而是切换之后忘了刷新环境变量——shell 里还保留着旧 provider 的 key新 provider 根本读不到。切换完先执行env | grep -i api看一眼环境变量再跑一条测试命令能少踩很多坑。注意第三方的配置管理工具更新节奏不一如果切换后出现类似“handling codex endpoint /responses failed”的报错优先检查新配置的 base_url、api key、wire_api 三者是否匹配不要第一时间怀疑工具坏了。6. 常见问题速查与避坑实录6.1 安装与启动问题codex命令找不到。npm 全局包的 bin 目录不在 PATH 里。执行npm config get prefix把输出目录加入系统 PATH。注意改完要重新开终端才会生效。PowerShell 提示无法加载脚本。如 2.3 节所述用管理员权限执行Set-ExecutionPolicy RemoteSigned。提示 unable to locate the codex cli binary or required runtime components。这个报错通常说明安装不完整或运行时组件缺失。第一优先做法卸载后重新安装最新版npm uninstall -g openai/codex npm install -g openai/codexlatest然后再codex --version验证。如果还不行检查是否用了比较老的 Node 版本尽量升级到 20 再试。npm 安装太慢或反复失败。把 npm registry 切换为国内镜像服务然后重新安装。装完之后再跑一次codex --version确认。6.2 登录与鉴权问题codex login无法完成授权。先看浏览器是否能正常打开授权页如果授权页打不开大概率是网络环境问题。也可以删掉~/.codex/auth.json后重新登录清掉可能损坏的本地凭证。一直 401 unauthorized。检查环境变量是否真的设置成功echo $OPENAI_API_KEYmacOS/Linux或echo $env:OPENAI_API_KEYWindows PowerShell。如果用了自定义 provider检查env_key配置的变量名是否和实际一致。403 forbidden。通常是 API Key 没有访问指定模型的权限或者该模型在你当前网络环境中不可用。换一个模型名试试或者确认 Key 对应的账号是否有该模型访问权。6.3 请求与连接问题切换配置后报错 handling codex endpoint /responses failed。这是很常见的对接类报错。按顺序排查先确认base_url是否可达用curl探一下端点再确认wire_api和你所用的后端是否匹配接着看环境变量里 key 是否被正确读取最后用最简 prompt 跑一遍连通测试。如果自定义配置没问题再考虑是不是 cc switch 这类切换工具没把旧环境变量清理干净。请求返回乱码或中英文错乱。终端编码问题。Windows 下使用 Windows Terminal 并设置 UTF-8 编码macOS/Linux 一般不会出现。返回内容经常被截断。上下文窗口不够用。要么精简项目说明把无关文件排除要么用--model切换上下文更大的模型也可以把一个大任务拆成多个小会话每个会话聚焦一个文件或一个功能。6.4 功能行为问题与排查思路AI 尝试修改我不想动的文件。权限策略没有限制住工作区。建议开启沙箱read-only或workspace-write同时用自然语言明确告诉它“只允许改动 src 目录下的文件其他地方一律不要碰”。每次写文件都询问太多效率低。如果你已经在一个实验性项目里摸清了 AI 的行为规律可以临时把approval_policy调整为on-failure甚至never但切回正式项目时记得调回来。反复在多个项目间切换时推荐维护两份配置或借助 cc switch 快速切换。终端卡住敲不出字母。大多数情况是会话中有命令在等待输入。先尝试CtrlC中断当前操作不行就CtrlD退出会话重新进入。Windows 下尽量用 Windows Terminal而不是老旧控制台输入和编码体验会好很多。AI 的改动在 git 中无法追踪。这通常是因为你在非 Git 目录运行了 Codex。建议要么把项目初始化成 Git 仓库要么至少备份一份目录快照再去跑自动化修改任务。没有版本管理兜底的 AI 改代码风险等级直接上一个台阶。把上面这些整理成一个速查表现象最常见原因首查项codex 命令找不到npm bin 目录不在 PATHnpm config get prefix安装后提示组件缺失Node 版本过旧/安装不完整重装最新版、升级 Node登录无法弹窗网络问题/本地凭证损坏清理 auth.json 重新登录401API Key 未设置/变量名不匹配echo 检查环境变量403Key 无权限或模型不可用换 Key 或换模型404base_url 或请求路径不对curl 探端点响应乱码终端编码非 UTF-8切换 Windows Terminal输出截断上下文窗口不足精简任务、拆分会话AI 乱动文件沙箱权限过宽开启 workspace-write 限制最后分享几点我个人在实际使用中的体会。Codex CLI 用得好不好和三件事强相关权限设置要在开工前想清楚项目指令文件要写清楚每次让 AI 改动前先说明可验收的边界条件。我长期只在on-request模式下让它自动改文件验证过多轮之后才敢在特定项目里放开权限这个流程别嫌麻烦。另外强烈建议在项目里维护一份AGENTS.md——把构建命令、测试命令、格式化规范、绝对禁忌写进去AI 每次开工前先读一遍整个体验会提升一个量级。这一条不在官方入门文档的显眼位置但实测收益最大。先写到这等踩到新坑再回来补。
