尧图网站建设 
我自己折腾 Codex 从下载到接入本地模型踩了不少坑最后总算跑通了。这篇就把完整的实战过程写出来从安装、认证、配置模型到实际修 bug 的全流程都捋一遍顺便把那些文档里不会写、但你一定会遇到的坑提前给你标出来。不管你用的是 macOS、Linux 还是 Windows照着做基本都能搞定尤其是想省钱、想把代码留在本地的朋友这篇应该能帮你省下不少时间。1. 先搞清楚一件事Codex CLI 到底是什么1.1 它不是一个模型而是一个终端智能体很多人第一次听到 Codex会下意识以为它是一个类似 ChatGPT 那样的独立大模型。其实 Codex 是 OpenAI 推出的一个终端智能体工具全称叫 Codex CLI它以命令行工具的形式跑在你的本机上替你完成读取代码、分析问题、修改文件、执行命令这一整套流程。你可以把它理解成一个住在你终端里的 AI 开发搭档你给它一个任务比如帮我修复 login 接口的 bug它会先扫描你的项目文件结构定位可疑代码给出修改方案甚至直接帮你把补丁写进文件里。它和普通聊天式 AI 最大的区别是它拥有执行能力能看到你的文件系统、能调用命令、能把改动落地。这里有个关键点要和所有初次接触的朋友说明白Codex CLI 本身不包含模型能力它只是一个壳真正干活儿的模型跑在后端。后端可以是 OpenAI 官方的云端 API也可以是你自己部署的本地大模型。这个弹性设计就是它最香的地方也是我们本地部署玩法的理论依据。1.2 云端模型与本地部署的真实关系谁在跑推理刚开始我也有个误解以为本地部署 Codex就是把 OpenAI 的模型下载到本地跑。实际上 Codex CLI 是客户端模型是服务端两者通过 API 协议通信。你可以在不改变 Codex 客户端的情况下把模型提供商从 OpenAI 换成 DeepSeek、通义千问或者本地跑起来的模型服务。搞清楚这个架构模型很重要因为你后续所有配置都会围绕它进行。Codex 的配置核心就是指定模型提供商的 base URL和API Key只要能兼容 Codex 要求的 API 格式任何大模型都能被它调用。这就像手机里的地图应用无论是高德还是百度地图界面和使用逻辑是一样的只要换了数据源底图就变了。1.3 主流 AI 编程助手对比Codex CLI 的优势定位我自己用过的 AI 编程工具不算少从 Cursor 到 Copilot 再到通义灵码各有各的好处但 Codex CLI 有几个特性是它们替代不了的全终端工作流不依赖 IDE 插件任何编辑器里都能用配合 vim 或者远程 SSH 开发非常顺手。沙箱执行环境它改文件、跑命令都在受控的沙箱中执行权限边界清晰比直接让你无脑接受 AI 改动的工具更安全。本地部署友好它支持用户自定义模型后端接 DeepSeek 或者本地部署的 Qwen、Llama 等模型数据可以不离开你的机器。任务追踪机制多文件、多步骤任务它会拆解成一个列表逐步推进中途出错了能局部重试不用整个任务推倒重来。至于适合谁我的建议是如果你平时用命令行开发、习惯 vim/Emacs、或者有代码隐私方面的顾虑想要本地推理Codex CLI 值得花时间折腾。如果你重度依赖 IDE 的可视化操作那 Cursor 可能更适合二者并不冲突。2. 下载安装全流程三个平台一次说明白2.1 安装前你需要知道的环境要求正式动手之前先花两分钟检查一下机器环境避免装到一半才发现版本不兼容。Codex CLI 是基于 Node.js 构建的这意味着你的电脑上必须有一个可用的 Node.js 运行时。我自己装的时候最初以为是独立二进制文件直接复制就能用结果发现它是走 npm 全球安装的Node.js 版本低了直接报错。官方要求 Node.js 版本在 18 以上但为了保险起见建议你直接上 20 以上的 LTS 版本因为有些新版本 Codex 对异步处理和类型解析有要求Node 20 的兼容性最好。另外如果你在 Windows 上使用建议先搞定 WSL 2。不是说 Windows 原生不行而是很多 AI 相关依赖库在 POSIX 环境下更省心后续如果你要跑本地推理模型Linux 环境下的 CUDA 支持也远好于 Windows 的 Docker 方案。我第二次折腾时换成 WSL 2 Ubuntu 22.04体感是顺畅了一整个量级。# 检查 Node.js 版本 node -v # 如果能输出 v20.x 以上说明环境OK输出的版本号如果是 v18 以下建议先升级 Node.js。macOS 用户推荐用 Homebrew 装Windows 用户推荐从官网下载 LTS 安装包升级完记得重新开一个终端窗口因为环境变量不会自动刷新。2.2 macOS 与 Linux 安装最顺滑的路径在 macOS 和主流 Linux 发行版上安装 Codex CLI 的统一入口是 npm 全球安装命令。这个命令会从 npm 仓库拉取 Codex CLI 包然后把它注册到系统的全局命令路径中。npm install -g openai/codex安装完成后验证一下是否成功codex --version如果看到类似0.x.x的版本号输出说明安装成功了。这里有个小坑我必须提一下npm 的全局安装路径可能不在你的 PATH 环境变量里尤其是当你通过 nvm 管理 Node.js 版本时。如果出现codex: command not found多半是这个问题。解决办法是把 npm 全局 bin 目录加到 PATH。macOS 下一般在~/.npm-global/binnvm 用户一般在~/.nvm/versions/node/当前版本/bin。你可以先执行npm bin -g查看路径再把它拼到 shell 配置文件的 PATH 里。另外Homebrew 用户还有一个额外选项用brew install codex直接安装 Formula。这个方法的好处是不依赖 Node 环境但版本更新可能比 npm 慢一些。我个人更推荐 npm 方式因为可以随时手动指定版本升级。2.3 Windows 桌面版装起来比命令行版本复杂一点Windows 用户有两套方案可以选一个是 WSL 2 里面走 Linux 路线另一个是直接装 Windows 桌面版。桌面版有独立的图形界面对不习惯敲命令的朋友友好很多但安装步骤也相对繁琐有几个前置条件必须满足。首先 Windows 桌面版要求系统必须是 Windows 10 1903 以上的 64 位版本并且开启 Windows Terminal 支持。其次桌面版的安装包需要从官网的下载页面获取拿了安装包之后一路默认安装即可。不过桌面版默认还是需要依赖 Node.js 运行时所以前面说的 Node.js 环境检查依然要做。我的建议是如果你计划长期用 Codex 做正经开发WSL 2 npm 方案的稳定性和可扩展性远高于 Windows 原生桌面版因为本地模型推理的 Docker 和 GPU 工具链在 WSL 里都更好配。桌面版拿去尝鲜体验挺好但重度使用还是走 Linux 路线更舒服。2.4 环境变量配置与工具箱检查无论是哪个平台安装完第一件事就是检查 Codex CLI 的所有命令是否完整。你可以执行codex --help正常会输出一大段命令说明包括codex login、codex init、codex exec等子命令。如果这些命令都没问题恭喜你安装环节过了。接下来才是真正需要花心思的环节——认证和模型配置。3. 本地模型的接入与部署配置3.1 方案一接入 DeepSeek API最实惠的在线方案很多人说本地部署其实并不是说模型权重一定得在自己机器上而是指把 Codex 从 OpenAI 官方的绑定中解放出来接入自己选的模型。这里性价比最高的一步就是把 Codex 接到 DeepSeek 的 API 上。DeepSeek 的 API 兼容 Codex 需要的协议格式所以不需要改任何代码只需要在 Codex 的配置文件里指定请求地址和密钥。第一步去 DeepSeek 开放平台注册账号并创建 API Key然后找到配置文件。Codex 的配置文件存放位置因平台而异macOS/Linux 下是~/.codex/config.tomlWindows 下在%USERPROFILE%\.codex\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 responses注意几个要点base_url统一填https://api.deepseek.com/v1这是它的 OpenAI 兼容端点。env_key指的是环境变量名不是让你把密钥直接写在配置文件里。你需要设置一个叫DEEPSEEK_API_KEY的环境变量值就是你的密钥。wire_api字段建议设成responses老版本 Codex 用的是chat模式新版已经全面切到 responses 模式DeepSeek 对两者都兼容但 responses 模式功能更全。配置完成后你可以在命令行里验证一下export DEEPSEEK_API_KEY你的密钥 codex exec 写一个 Python 快速排序并打印测试用例如果 DeepSeek 正常响应你会看到它直接在终端里给出完整代码并执行测试。这个方案唯一的缺点就是依然依赖公网 API。3.2 方案二接入本地大模型数据不出内网真正意义上的本地部署是把模型跑在你自己的机器或者内网服务器上Codex 只是作为客户端连到本地地址。这个方案最适合两种情况一是你处理的是敏感业务代码不想把代码送到第三方 API二是你手头有闲置的显卡资源想物尽其用。标准的接入方式是用一个兼容 OpenAI API 的本地推理服务作为中间层。目前我用过的有两个主流选择Ollama 和 vLLM。Ollama 更适合个人电脑安装简单、一键拉模型vLLM 更适合服务器和多用户场景吞吐量高但对显存要求也高。以 Ollama 为例接入流程是这样的安装 Ollama 后拉取一个适合代码生成的模型比如 Qwen2.5-Coder 系列ollama pull qwen2.5-coder:14b ollama serve然后修改 Codex 配置model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api responses这里有个容易踩的坑本地 Ollama 服务默认不需要 API Key但 Codex 配置里如果不给env_key它可能启动不了。所以我的做法是在环境变量里随便设一个占位值比如export OLLAMA_API_KEYollama反正本地服务不会去校验它但又满足了 Codex 的参数要求。至于本地模型选择我的经验是纯代码生成和补全Qwen2.5-Coder 系列在开源模型里目前做得最好14B 模型在 24GB 显存下跑得很流畅7B 则可以在 16GB 显存上运行但能力折扣明显。如果你的显存只有 8GB那就得考虑 4-bit 量化版本的 7B 模型或者干脆叫一台 GPU 服务器。3.3 模型与算力的选择逻辑别盲目追大体积并不是模型的全部别看到 70B 模型就盲目往上冲。我自己做过对比实验在同样的 Codex 任务集上Qwen2.5-Coder 32B 的输出质量明显优于 7B 和 14B但代码修复任务里 14B 和 32B 的实际差距并没有想象中那么大而 14B 的推理速度差不多是 32B 的三倍。这里我提供一个经过实测的选型参考表显存大小推荐模型量化级别实测体感8GBqwen2.5-coder:7b-instruct-q4Q4能跑但速度一般适合小任务16GBqwen2.5-coder:14bQ8速度和质量的甜点24GBqwen2.5-coder:14b / 32b(q5)Q5/Q8更推荐 14B留显存给上下文48GBqwen2.5-coder:32bQ8接近云端API体验顺带一提你是 NVIDIA 显卡的话安装好 CUDA 驱动和 cuDNN 库Ollama 走 GPU 加速几乎零配置但如果你用的是 AMD 卡或者纯 CPU 环境运行大型模型会比较痛苦建议老老实实走 API 方案。4. 从零跑通第一个任务配置、原理与实战记录4.1 完整配置流程复盘Auth 文件与配置文件的相互作用Codex 的认证机制有两个来源一个是官方 OpenAI 账号体系一个是配置文件里自己指定的 API Key 来源。当你配置了model_provider指向第三方时Codex 不会强制要求 OpenAI 的登录态但第一次启动时它可能还是会问你是否要登录 OpenAI 账号。这个交互曾让很多人困惑包括我。我明明配置了 DeepSeek为什么还让我登录 OpenAI其实这是 Codex 的初始化逻辑——它默认优先尝试官方账号认证如果你不想用官方选择跳过登录步骤即可后续所有请求都会走你配置的自定义 provider。一个更干净的初始方式是在配置里显式禁用官方登录[experimental] disable_login true设置完之后启动codex进入交互模式它会直接使用你指定的 provider不再废话。如果你是非 OpenAI 用户这一行配置能省掉无数烦恼。4.2 实操从零修复一个真实 Bug 的完整过程理论讲了一堆实际跑一次才能彻底搞懂。我在本机准备了一个简单的 Node.js 项目模拟常见的并发数据覆盖问题。我在inventory.js里故意留了一个 setTimeout 延迟写入的 bug然后打开 Codex 交互界面直接输入任务codexCodex 启动之后进入 REPL 交互界面我输入这个库存模块有并发问题多个入库请求同时到达时库存数据会被覆盖。 请修复它并且加上单元测试。Codex 的工作方式是先扫描项目下所有文件识别inventory.js和现有测试文件的结构然后它会把任务拆成多个步骤——分析问题、设计修复方案、改写代码、补充测试。每个步骤都会在界面里显示为一个小卡片你能清楚地看到它在做什么。它给出的修复方案是把简单的setTimeout延迟写入改成基于 Promise 队列的顺序写入每个异步操作完成后再处理下一个这样就不会互相覆盖。整个修复过程中它能读懂异步逻辑的边界这个表现比我预期的更好。值得注意的是Codex 不止改文件它还会主动执行测试命令。如果测试失败它会读失败日志继续修改代码再跑一遍直到测试通过为止。这个自主循环机制是 Codex 最核心的亮点也是它区别于普通自动补全工具的地方。4.3 理解 Codex 的两种模式Chat 与 Agent用 Codex 时有两种模式需要分清楚简单对话模式和自主执行模式。简单对话模式就是和它聊天它会回答你的问题但不会动你的文件和系统。适合问这个函数的复杂度是多少帮我解释一下这段正则这类问题。自主执行模式需要你在对话前先同意它执行操作或者通过codex exec直接命令行下达任务格式是codex exec 把所有 TODO 注释提取成一个 markdown 文件在自主执行模式下Codex 会自己创建任务清单、逐步执行并且在涉及修改文件前向你确认。这里提到一个安全选项你可以在配置中限制沙箱只读不允许它修改文件只输出建议适合只做代码审查的场景。[sandbox] read_only true4.4 代理与网络配置本地服务连接疑难杂症如果你在某个特定的网络环境里跑 Codex连接本地推理服务时遇到cc switch local proxy failed while handling codex endpoint /responses报错大概率不是模型的问题而是 Codex 默认走了系统代理。我自己遇到这个错误时一开始怀疑是 Ollama 服务没监听对端口查了半天也没发现端口问题。最后用curl http://localhost:11434/v1/models测试发现接口明明通但 Codex 就是连不上才反应过来是代理设置搞的鬼。解决方案分两种。第一种在发起请求时显式告诉 Codex 不要走代理export NO_PROXYlocalhost,127.0.0.1 export no_proxylocalhost,127.0.0.1 export HTTP_PROXY export HTTPS_PROXY第二种检查系统代理设置把 localhost 加入例外列表。macOS 和 Windows 都在系统网络设置里操作WSL 用户则要检查/etc/environment或 shell 配置文件。这里我不展开细节但你要记住排查顺序先测 API 通不通再查代理是否介入最后才去怀疑 Codex 配置这个思路能帮你快速定位绝大多数连接问题。5. 常见问题与排查技巧实录5.1 组织设置加载失败项目列表一片空白如果你用 OpenAI 官方账号登录 Codex可能会碰到无法加载组织设置的问题项目列表一直转圈不出数据。这个问题的根源多半是网络层。Codex 在加载组织设置时需要访问 OpenAI 的 API如果请求超时界面就会卡在加载状态。最直接的解决方法是把网络切换到更稳定的环境再试一次如果不行就退回第三方模型方案绕开官方 API 的访问需求。群里还有朋友反馈过登录不上的问题情况也类似codex login弹出浏览器授权窗口但授权完成后命令行没有自动检测到登录成功。这是时序问题。我的建议是不要急着关浏览器等命令行提示输出Logged in再关。如果一直没有提示手动重启终端再执行codex login status检查。5.2 配置模型后报错 model is not supported 的真相我在尝试某些模型时遇到过类似这样一段报错the gpt-5.6-sol model is not supported when using codex with a custom model provider这种报错发生在你把model配置成 OpenAI 家族模型、但model_provider却是第三方时。Codex 的逻辑是当你使用自定义 provider它就按通用 API 处理而你配置的gpt-5.6-sol属于 OpenAI 专属模型命名它既不在通用 API 的模型清单里也不被第三方后端识别于是直接拒绝启动。解决办法很简单把model改成你实际连接的模型名比如用 DeepSeek 就填deepseek-chat用 Ollama 就填qwen2.5-coder:14b。不要让客户端模型名和真实的 provider 模型名不一致。5.3 配置文件格式错误与日志排查方法Codex 对配置文件里的拼写错误非常敏感但它给的报错却是那种非致命信息类型codex is ignoring 1 unrecognized configuration setting. check for typos or deprecation如果看到这句话说明你在配置文件里写了一行它不认识的配置项。它不会阻止运行但你期望的功能不会生效比如你把model_provider拼成了model_provder请求就会走默认的 OpenAI 通道。排查方式是到官方文档里找到正确的配置项名称逐字比对。一个简单技巧配置文件里所有顶级 key 和次级 key 都可以用codex --debug启动来观察实际解析结果Codex 会把有效配置打印出来一目了然。5.4 几个值得收藏的 Terminal 技巧与工具推荐最后分享几个我在实际使用中觉得很受用的终端小技巧。设置命令别名如果你经常切换模型可以在.bashrc或.zshrc里配置几个别名例如alias codex-deepseekDEEPSEEK_API_KEYxxx codex这样一条命令直达不用每次手动设环境变量。配合 TMUX 使用在远程服务器上开发时建议在 tmux 会话里启动 Codex防止 SSH 断线导致任务中断。善用执行权限Codex 在自主模式下执行命令前会询问你确认如果你确定任务安全可以用codex exec --dangerously-bypass-approvals跳过确认环节但这会失去安全检查的保护完全不建议新手用。另外想多说一句Codex 的沙箱功能默认在 macOS 上依赖 Seatbelt 机制Windows WSL 和 Linux 则使用 Linux 命名空间隔离。如果你发现改文件时经常弹出权限确认说明沙箱在保护你不要为了方便直接关闭它否则一旦模型被恶意提示词诱导执行危险命令后果相当严重。6. 一些踩坑之后的真实体会我自己从安装到真正稳定使用前前后后折腾了大概三天。第一天卡在 Node 版本和 PATH 配置第二天卡在模型选择上拿着 7B 的模型硬跑复杂任务输出质量不忍直视最后换了 14B 模型并调整了 prompt 策略才真正体会到 Codex 的自主执行有多爽。如果你也准备入坑我的建议是先按照第 3 节的方案接入 DeepSeek API 跑通全流程再用 Ollama 搭本地推理。这样即使本地模型效果不理想你也有一个可用的退路不会被劝退。还有一个小技巧写任务描述时尽量具体直接给出期望的结果、涉及的文件范围、约束条件。比如修改auth.js让它支持 token 刷新并且不要改动其他文件比帮我优化一下登录要好用十倍。Codex 对指令理解得已经很好差的往往就是你给的上下文还不够。代码写久了你会发现AI 编程助手真正省时间的不是它替你按几个快捷键而是它能把那些需要通读全项目才能做的事情压缩成一句话的指令。这次实战折腾下来Codex 在我日常开发中的地位已经仅次于编辑器本身了。 Codex CLI实战：从安装到本地模型接入与Bug修复
我自己折腾 Codex 从下载到接入本地模型踩了不少坑最后总算跑通了。这篇就把完整的实战过程写出来从安装、认证、配置模型到实际修 bug 的全流程都捋一遍顺便把那些文档里不会写、但你一定会遇到的坑提前给你标出来。不管你用的是 macOS、Linux 还是 Windows照着做基本都能搞定尤其是想省钱、想把代码留在本地的朋友这篇应该能帮你省下不少时间。1. 先搞清楚一件事Codex CLI 到底是什么1.1 它不是一个模型而是一个终端智能体很多人第一次听到 Codex会下意识以为它是一个类似 ChatGPT 那样的独立大模型。其实 Codex 是 OpenAI 推出的一个终端智能体工具全称叫 Codex CLI它以命令行工具的形式跑在你的本机上替你完成读取代码、分析问题、修改文件、执行命令这一整套流程。你可以把它理解成一个住在你终端里的 AI 开发搭档你给它一个任务比如帮我修复 login 接口的 bug它会先扫描你的项目文件结构定位可疑代码给出修改方案甚至直接帮你把补丁写进文件里。它和普通聊天式 AI 最大的区别是它拥有执行能力能看到你的文件系统、能调用命令、能把改动落地。这里有个关键点要和所有初次接触的朋友说明白Codex CLI 本身不包含模型能力它只是一个壳真正干活儿的模型跑在后端。后端可以是 OpenAI 官方的云端 API也可以是你自己部署的本地大模型。这个弹性设计就是它最香的地方也是我们本地部署玩法的理论依据。1.2 云端模型与本地部署的真实关系谁在跑推理刚开始我也有个误解以为本地部署 Codex就是把 OpenAI 的模型下载到本地跑。实际上 Codex CLI 是客户端模型是服务端两者通过 API 协议通信。你可以在不改变 Codex 客户端的情况下把模型提供商从 OpenAI 换成 DeepSeek、通义千问或者本地跑起来的模型服务。搞清楚这个架构模型很重要因为你后续所有配置都会围绕它进行。Codex 的配置核心就是指定模型提供商的 base URL和API Key只要能兼容 Codex 要求的 API 格式任何大模型都能被它调用。这就像手机里的地图应用无论是高德还是百度地图界面和使用逻辑是一样的只要换了数据源底图就变了。1.3 主流 AI 编程助手对比Codex CLI 的优势定位我自己用过的 AI 编程工具不算少从 Cursor 到 Copilot 再到通义灵码各有各的好处但 Codex CLI 有几个特性是它们替代不了的全终端工作流不依赖 IDE 插件任何编辑器里都能用配合 vim 或者远程 SSH 开发非常顺手。沙箱执行环境它改文件、跑命令都在受控的沙箱中执行权限边界清晰比直接让你无脑接受 AI 改动的工具更安全。本地部署友好它支持用户自定义模型后端接 DeepSeek 或者本地部署的 Qwen、Llama 等模型数据可以不离开你的机器。任务追踪机制多文件、多步骤任务它会拆解成一个列表逐步推进中途出错了能局部重试不用整个任务推倒重来。至于适合谁我的建议是如果你平时用命令行开发、习惯 vim/Emacs、或者有代码隐私方面的顾虑想要本地推理Codex CLI 值得花时间折腾。如果你重度依赖 IDE 的可视化操作那 Cursor 可能更适合二者并不冲突。2. 下载安装全流程三个平台一次说明白2.1 安装前你需要知道的环境要求正式动手之前先花两分钟检查一下机器环境避免装到一半才发现版本不兼容。Codex CLI 是基于 Node.js 构建的这意味着你的电脑上必须有一个可用的 Node.js 运行时。我自己装的时候最初以为是独立二进制文件直接复制就能用结果发现它是走 npm 全球安装的Node.js 版本低了直接报错。官方要求 Node.js 版本在 18 以上但为了保险起见建议你直接上 20 以上的 LTS 版本因为有些新版本 Codex 对异步处理和类型解析有要求Node 20 的兼容性最好。另外如果你在 Windows 上使用建议先搞定 WSL 2。不是说 Windows 原生不行而是很多 AI 相关依赖库在 POSIX 环境下更省心后续如果你要跑本地推理模型Linux 环境下的 CUDA 支持也远好于 Windows 的 Docker 方案。我第二次折腾时换成 WSL 2 Ubuntu 22.04体感是顺畅了一整个量级。# 检查 Node.js 版本 node -v # 如果能输出 v20.x 以上说明环境OK输出的版本号如果是 v18 以下建议先升级 Node.js。macOS 用户推荐用 Homebrew 装Windows 用户推荐从官网下载 LTS 安装包升级完记得重新开一个终端窗口因为环境变量不会自动刷新。2.2 macOS 与 Linux 安装最顺滑的路径在 macOS 和主流 Linux 发行版上安装 Codex CLI 的统一入口是 npm 全球安装命令。这个命令会从 npm 仓库拉取 Codex CLI 包然后把它注册到系统的全局命令路径中。npm install -g openai/codex安装完成后验证一下是否成功codex --version如果看到类似0.x.x的版本号输出说明安装成功了。这里有个小坑我必须提一下npm 的全局安装路径可能不在你的 PATH 环境变量里尤其是当你通过 nvm 管理 Node.js 版本时。如果出现codex: command not found多半是这个问题。解决办法是把 npm 全局 bin 目录加到 PATH。macOS 下一般在~/.npm-global/binnvm 用户一般在~/.nvm/versions/node/当前版本/bin。你可以先执行npm bin -g查看路径再把它拼到 shell 配置文件的 PATH 里。另外Homebrew 用户还有一个额外选项用brew install codex直接安装 Formula。这个方法的好处是不依赖 Node 环境但版本更新可能比 npm 慢一些。我个人更推荐 npm 方式因为可以随时手动指定版本升级。2.3 Windows 桌面版装起来比命令行版本复杂一点Windows 用户有两套方案可以选一个是 WSL 2 里面走 Linux 路线另一个是直接装 Windows 桌面版。桌面版有独立的图形界面对不习惯敲命令的朋友友好很多但安装步骤也相对繁琐有几个前置条件必须满足。首先 Windows 桌面版要求系统必须是 Windows 10 1903 以上的 64 位版本并且开启 Windows Terminal 支持。其次桌面版的安装包需要从官网的下载页面获取拿了安装包之后一路默认安装即可。不过桌面版默认还是需要依赖 Node.js 运行时所以前面说的 Node.js 环境检查依然要做。我的建议是如果你计划长期用 Codex 做正经开发WSL 2 npm 方案的稳定性和可扩展性远高于 Windows 原生桌面版因为本地模型推理的 Docker 和 GPU 工具链在 WSL 里都更好配。桌面版拿去尝鲜体验挺好但重度使用还是走 Linux 路线更舒服。2.4 环境变量配置与工具箱检查无论是哪个平台安装完第一件事就是检查 Codex CLI 的所有命令是否完整。你可以执行codex --help正常会输出一大段命令说明包括codex login、codex init、codex exec等子命令。如果这些命令都没问题恭喜你安装环节过了。接下来才是真正需要花心思的环节——认证和模型配置。3. 本地模型的接入与部署配置3.1 方案一接入 DeepSeek API最实惠的在线方案很多人说本地部署其实并不是说模型权重一定得在自己机器上而是指把 Codex 从 OpenAI 官方的绑定中解放出来接入自己选的模型。这里性价比最高的一步就是把 Codex 接到 DeepSeek 的 API 上。DeepSeek 的 API 兼容 Codex 需要的协议格式所以不需要改任何代码只需要在 Codex 的配置文件里指定请求地址和密钥。第一步去 DeepSeek 开放平台注册账号并创建 API Key然后找到配置文件。Codex 的配置文件存放位置因平台而异macOS/Linux 下是~/.codex/config.tomlWindows 下在%USERPROFILE%\.codex\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 responses注意几个要点base_url统一填https://api.deepseek.com/v1这是它的 OpenAI 兼容端点。env_key指的是环境变量名不是让你把密钥直接写在配置文件里。你需要设置一个叫DEEPSEEK_API_KEY的环境变量值就是你的密钥。wire_api字段建议设成responses老版本 Codex 用的是chat模式新版已经全面切到 responses 模式DeepSeek 对两者都兼容但 responses 模式功能更全。配置完成后你可以在命令行里验证一下export DEEPSEEK_API_KEY你的密钥 codex exec 写一个 Python 快速排序并打印测试用例如果 DeepSeek 正常响应你会看到它直接在终端里给出完整代码并执行测试。这个方案唯一的缺点就是依然依赖公网 API。3.2 方案二接入本地大模型数据不出内网真正意义上的本地部署是把模型跑在你自己的机器或者内网服务器上Codex 只是作为客户端连到本地地址。这个方案最适合两种情况一是你处理的是敏感业务代码不想把代码送到第三方 API二是你手头有闲置的显卡资源想物尽其用。标准的接入方式是用一个兼容 OpenAI API 的本地推理服务作为中间层。目前我用过的有两个主流选择Ollama 和 vLLM。Ollama 更适合个人电脑安装简单、一键拉模型vLLM 更适合服务器和多用户场景吞吐量高但对显存要求也高。以 Ollama 为例接入流程是这样的安装 Ollama 后拉取一个适合代码生成的模型比如 Qwen2.5-Coder 系列ollama pull qwen2.5-coder:14b ollama serve然后修改 Codex 配置model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api responses这里有个容易踩的坑本地 Ollama 服务默认不需要 API Key但 Codex 配置里如果不给env_key它可能启动不了。所以我的做法是在环境变量里随便设一个占位值比如export OLLAMA_API_KEYollama反正本地服务不会去校验它但又满足了 Codex 的参数要求。至于本地模型选择我的经验是纯代码生成和补全Qwen2.5-Coder 系列在开源模型里目前做得最好14B 模型在 24GB 显存下跑得很流畅7B 则可以在 16GB 显存上运行但能力折扣明显。如果你的显存只有 8GB那就得考虑 4-bit 量化版本的 7B 模型或者干脆叫一台 GPU 服务器。3.3 模型与算力的选择逻辑别盲目追大体积并不是模型的全部别看到 70B 模型就盲目往上冲。我自己做过对比实验在同样的 Codex 任务集上Qwen2.5-Coder 32B 的输出质量明显优于 7B 和 14B但代码修复任务里 14B 和 32B 的实际差距并没有想象中那么大而 14B 的推理速度差不多是 32B 的三倍。这里我提供一个经过实测的选型参考表显存大小推荐模型量化级别实测体感8GBqwen2.5-coder:7b-instruct-q4Q4能跑但速度一般适合小任务16GBqwen2.5-coder:14bQ8速度和质量的甜点24GBqwen2.5-coder:14b / 32b(q5)Q5/Q8更推荐 14B留显存给上下文48GBqwen2.5-coder:32bQ8接近云端API体验顺带一提你是 NVIDIA 显卡的话安装好 CUDA 驱动和 cuDNN 库Ollama 走 GPU 加速几乎零配置但如果你用的是 AMD 卡或者纯 CPU 环境运行大型模型会比较痛苦建议老老实实走 API 方案。4. 从零跑通第一个任务配置、原理与实战记录4.1 完整配置流程复盘Auth 文件与配置文件的相互作用Codex 的认证机制有两个来源一个是官方 OpenAI 账号体系一个是配置文件里自己指定的 API Key 来源。当你配置了model_provider指向第三方时Codex 不会强制要求 OpenAI 的登录态但第一次启动时它可能还是会问你是否要登录 OpenAI 账号。这个交互曾让很多人困惑包括我。我明明配置了 DeepSeek为什么还让我登录 OpenAI其实这是 Codex 的初始化逻辑——它默认优先尝试官方账号认证如果你不想用官方选择跳过登录步骤即可后续所有请求都会走你配置的自定义 provider。一个更干净的初始方式是在配置里显式禁用官方登录[experimental] disable_login true设置完之后启动codex进入交互模式它会直接使用你指定的 provider不再废话。如果你是非 OpenAI 用户这一行配置能省掉无数烦恼。4.2 实操从零修复一个真实 Bug 的完整过程理论讲了一堆实际跑一次才能彻底搞懂。我在本机准备了一个简单的 Node.js 项目模拟常见的并发数据覆盖问题。我在inventory.js里故意留了一个 setTimeout 延迟写入的 bug然后打开 Codex 交互界面直接输入任务codexCodex 启动之后进入 REPL 交互界面我输入这个库存模块有并发问题多个入库请求同时到达时库存数据会被覆盖。 请修复它并且加上单元测试。Codex 的工作方式是先扫描项目下所有文件识别inventory.js和现有测试文件的结构然后它会把任务拆成多个步骤——分析问题、设计修复方案、改写代码、补充测试。每个步骤都会在界面里显示为一个小卡片你能清楚地看到它在做什么。它给出的修复方案是把简单的setTimeout延迟写入改成基于 Promise 队列的顺序写入每个异步操作完成后再处理下一个这样就不会互相覆盖。整个修复过程中它能读懂异步逻辑的边界这个表现比我预期的更好。值得注意的是Codex 不止改文件它还会主动执行测试命令。如果测试失败它会读失败日志继续修改代码再跑一遍直到测试通过为止。这个自主循环机制是 Codex 最核心的亮点也是它区别于普通自动补全工具的地方。4.3 理解 Codex 的两种模式Chat 与 Agent用 Codex 时有两种模式需要分清楚简单对话模式和自主执行模式。简单对话模式就是和它聊天它会回答你的问题但不会动你的文件和系统。适合问这个函数的复杂度是多少帮我解释一下这段正则这类问题。自主执行模式需要你在对话前先同意它执行操作或者通过codex exec直接命令行下达任务格式是codex exec 把所有 TODO 注释提取成一个 markdown 文件在自主执行模式下Codex 会自己创建任务清单、逐步执行并且在涉及修改文件前向你确认。这里提到一个安全选项你可以在配置中限制沙箱只读不允许它修改文件只输出建议适合只做代码审查的场景。[sandbox] read_only true4.4 代理与网络配置本地服务连接疑难杂症如果你在某个特定的网络环境里跑 Codex连接本地推理服务时遇到cc switch local proxy failed while handling codex endpoint /responses报错大概率不是模型的问题而是 Codex 默认走了系统代理。我自己遇到这个错误时一开始怀疑是 Ollama 服务没监听对端口查了半天也没发现端口问题。最后用curl http://localhost:11434/v1/models测试发现接口明明通但 Codex 就是连不上才反应过来是代理设置搞的鬼。解决方案分两种。第一种在发起请求时显式告诉 Codex 不要走代理export NO_PROXYlocalhost,127.0.0.1 export no_proxylocalhost,127.0.0.1 export HTTP_PROXY export HTTPS_PROXY第二种检查系统代理设置把 localhost 加入例外列表。macOS 和 Windows 都在系统网络设置里操作WSL 用户则要检查/etc/environment或 shell 配置文件。这里我不展开细节但你要记住排查顺序先测 API 通不通再查代理是否介入最后才去怀疑 Codex 配置这个思路能帮你快速定位绝大多数连接问题。5. 常见问题与排查技巧实录5.1 组织设置加载失败项目列表一片空白如果你用 OpenAI 官方账号登录 Codex可能会碰到无法加载组织设置的问题项目列表一直转圈不出数据。这个问题的根源多半是网络层。Codex 在加载组织设置时需要访问 OpenAI 的 API如果请求超时界面就会卡在加载状态。最直接的解决方法是把网络切换到更稳定的环境再试一次如果不行就退回第三方模型方案绕开官方 API 的访问需求。群里还有朋友反馈过登录不上的问题情况也类似codex login弹出浏览器授权窗口但授权完成后命令行没有自动检测到登录成功。这是时序问题。我的建议是不要急着关浏览器等命令行提示输出Logged in再关。如果一直没有提示手动重启终端再执行codex login status检查。5.2 配置模型后报错 model is not supported 的真相我在尝试某些模型时遇到过类似这样一段报错the gpt-5.6-sol model is not supported when using codex with a custom model provider这种报错发生在你把model配置成 OpenAI 家族模型、但model_provider却是第三方时。Codex 的逻辑是当你使用自定义 provider它就按通用 API 处理而你配置的gpt-5.6-sol属于 OpenAI 专属模型命名它既不在通用 API 的模型清单里也不被第三方后端识别于是直接拒绝启动。解决办法很简单把model改成你实际连接的模型名比如用 DeepSeek 就填deepseek-chat用 Ollama 就填qwen2.5-coder:14b。不要让客户端模型名和真实的 provider 模型名不一致。5.3 配置文件格式错误与日志排查方法Codex 对配置文件里的拼写错误非常敏感但它给的报错却是那种非致命信息类型codex is ignoring 1 unrecognized configuration setting. check for typos or deprecation如果看到这句话说明你在配置文件里写了一行它不认识的配置项。它不会阻止运行但你期望的功能不会生效比如你把model_provider拼成了model_provder请求就会走默认的 OpenAI 通道。排查方式是到官方文档里找到正确的配置项名称逐字比对。一个简单技巧配置文件里所有顶级 key 和次级 key 都可以用codex --debug启动来观察实际解析结果Codex 会把有效配置打印出来一目了然。5.4 几个值得收藏的 Terminal 技巧与工具推荐最后分享几个我在实际使用中觉得很受用的终端小技巧。设置命令别名如果你经常切换模型可以在.bashrc或.zshrc里配置几个别名例如alias codex-deepseekDEEPSEEK_API_KEYxxx codex这样一条命令直达不用每次手动设环境变量。配合 TMUX 使用在远程服务器上开发时建议在 tmux 会话里启动 Codex防止 SSH 断线导致任务中断。善用执行权限Codex 在自主模式下执行命令前会询问你确认如果你确定任务安全可以用codex exec --dangerously-bypass-approvals跳过确认环节但这会失去安全检查的保护完全不建议新手用。另外想多说一句Codex 的沙箱功能默认在 macOS 上依赖 Seatbelt 机制Windows WSL 和 Linux 则使用 Linux 命名空间隔离。如果你发现改文件时经常弹出权限确认说明沙箱在保护你不要为了方便直接关闭它否则一旦模型被恶意提示词诱导执行危险命令后果相当严重。6. 一些踩坑之后的真实体会我自己从安装到真正稳定使用前前后后折腾了大概三天。第一天卡在 Node 版本和 PATH 配置第二天卡在模型选择上拿着 7B 的模型硬跑复杂任务输出质量不忍直视最后换了 14B 模型并调整了 prompt 策略才真正体会到 Codex 的自主执行有多爽。如果你也准备入坑我的建议是先按照第 3 节的方案接入 DeepSeek API 跑通全流程再用 Ollama 搭本地推理。这样即使本地模型效果不理想你也有一个可用的退路不会被劝退。还有一个小技巧写任务描述时尽量具体直接给出期望的结果、涉及的文件范围、约束条件。比如修改auth.js让它支持 token 刷新并且不要改动其他文件比帮我优化一下登录要好用十倍。Codex 对指令理解得已经很好差的往往就是你给的上下文还不够。代码写久了你会发现AI 编程助手真正省时间的不是它替你按几个快捷键而是它能把那些需要通读全项目才能做的事情压缩成一句话的指令。这次实战折腾下来Codex 在我日常开发中的地位已经仅次于编辑器本身了。