最近几个月我几乎每天都要在终端里跟 Codex 打交道也在反复折腾 Codex 的本地部署。这个 OpenAI 开源的命令行 AI 编程助手不是很多人以为的“网页版套壳”而是一个能真实吃透代码库、自己在项目里改文件、跑测试的终端智能体。我今天要讲的就是我从零开始把 Codex 装到本地、接入第三方模型、甚至接上本地大模型的全过程。这套实战路径踩了不少坑尤其是模型端点配置和沙箱权限这两块几乎每个新用户都会在里面栽一回希望这篇文章能帮你少走弯路。不管你是想用官方模型还是想接 DeepSeek又或者打算把量化模型跑在本地当后端下面这一整套方案都能直接照着做。1. 先说清楚Codex“本地部署”到底部署了什么1.1 不是把模型拉到本地而是在本地装了一个“会干活的外壳”很多人听到“本地部署”四个字第一反应是我要在自己的电脑上跑一个能写代码的大模型。这个理解对了一半。Codex CLI 本质上是一个智能体外壳它负责的是和模型之间的对话调度、对代码库的读写、在终端里执行命令、根据环境反馈继续修正动作。而真正的“大脑”——也就是大模型本身——默认仍然是在云端 API 上跑的。你可以把它想成本地装了一个经验丰富的实习生能自己看代码、敲命令、改文件但遇到难题时还是要打电话请教远端的专家。搞清楚这个分工非常重要因为后面所有配置、报错、性能问题的根因几乎都出在“外壳和大脑之间的通道”上。1.2 一次任务请求的完整链路我把自己实际观察到的一次 Codex 任务请求拆解给你看你在终端输入一句话目标比如“帮我把 main.py 里所有魔法数字提取成常量”。Codex CLI 读取当前项目的文件结构、Git 变更、相关文件内容把这些上下文拼装成一次请求。请求发给配置好的模型端点这个端点可以是 OpenAI 官方接口也可以是你自己在 config.toml 里指定的任意 OpenAI 兼容接口。模型返回一段 JSON里面除了纯文本回复还包含工具调用指令比如“读取 xx.py 第 12 行”“执行 python test.py”。CLI 在沙箱环境里执行这些指令把执行结果反馈给模型模型再决定下一步怎么做直到任务结束。这个“执行-反馈-再执行”的循环才是 Codex 值钱的真正所在。它不只是给你一段建议代码而是像一个远程队友一样真的把你仓库里的文件和命令行操作接管了大半。理解了这条链路你再看后面任何报错心里就有了一张地图。1.3 我为什么不在网页版和 IDE 插件里用网页版 Codex 和 IDE 插件我也都用过但最终我还是长期使用本地 CLI原因有三个。第一是隐私和范围控制本地 CLI 可以精确指定它访问哪个目录也可以把沙箱开成只读模式它想给代码库写东西必须要经过你同意这对于公司项目或者仓库敏感度高的场景很重要。第二是终端工作流的亲和力它是真正的命令行工具可以和 git、tmux、CI 脚本放在一起玩方便我把“让 AI 改代码”变成流水线里的一个步骤。第三是可替换的后端我之前因为用量策略问题把后端从 OpenAI 官方切到了 DeepSeek后来又切到本地 Ollama这种自由度在网页版里是完全没有的。2. 动手之前的准备工作三件小事别做错2.1 Node.js 环境版本别太老Codex CLI 绝大多数情况是通过 npm 分发的所以 Node.js 是第一道门槛。要求其实不高Node.js 18 以上就行但我个人建议直接上 20 或 22 长期支持版本。原因是一些比较新的依赖在处理长文本响应时会用到新的流式 API老版本 Node 容易报一些很奇怪的底层错误比如 ERR_CRYPTO_HASH_FINALIZE。你在终端先跑一下node -v和npm -v如果不是 18去官网装当前 LTS 版本就行。装完之后建议顺手把 npm 的全局安装目录加到 PATH。Windows 上尤其要注意npm 全局目录有时候解析不到会导致后面codex命令不被识别。我这里多提一句 npm 源的问题。如果你所在的网络访问 npm 官方源比较慢可以临时切换成国内镜像源命令是npm config set registry https://registry.npmmirror.com。这句命令纯粹是修改 npm 拉包地址跟任何其他配置都没关系装完包之后你可以随时切回官方源。我自己的习惯是全局镜像用 npmmirror因为稳定下载速度快官方源偶尔会因为超时把安装流程打断。2.2 准备好一个 API 接入端点这是“本地部署”核心中的核心。按你的需求要提前想清楚一个问题这个 Codex 的“大脑”到底连哪里我梳理一下常见三种官方 OpenAI 端点最简单功能最全包括新模型的 codex 负载模式。但你需要有可用的 API Key而且价格相对高。适合先跑通逻辑。第三方 OpenAI 兼容服务比如 DeepSeek。便宜、速度快是目前社区里折腾热度最高的一种。你需要去对应平台申请 API Key并确认它提供的接口是 OpenAI 兼容格式。完全本地的模型通过 Ollama 跑量化模型。配置麻烦一点但数据不出本机适合离线环境。这个我在第 6 章单独展开。我强烈建议你第一次走通时先不要纠结“一定要用本地模型”直接用官方或者第三方 API 把链路打通。因为本地模型的性能瓶颈和兼容性问题很容易让你分不清到底是 Codex 配置错了还是模型本身不行。2.3 项目目录与沙箱选项最后检查你的项目目录。别在系统盘根目录这种地方直接开跑Codex 虽然会只读取你能授权的目录但为了保险还是建一个独立的测试项目目录里面放一两个带点逻辑的源文件就行。另外安装 Docker 这个动作我建议现在就做。后面无论你是打算用 workspace-docker 沙箱模式把整个执行环境隔离起来还是想装 Ollama 跑本地模型Docker 都会派上用场。Windows 上装 Docker Desktop 可能会要求你开启 WSL2照着官方文档走就行。如果你暂时不想装 Docker也可以只需要把沙箱模式设置为 read-only 或 workspace-write我把这两种模式的区别放在文末的表格里。3. Codex CLI 下载安装与首次认证3.1 安装命令与安装后的验证安装本身很简单一条命令npm install -g openai/codex安装完验证版本codex --version如果你看到类似 0.x.x 的版本号就说明装上了。这一步大部分人不会出问题真正容易翻车的是后面两个细节。第一个是权限Linux 和 macOS 上用 npm 全局安装如果系统提示 EACCES说明 npm 的全局目录权限不够不要用 sudo 硬怼正确的做法是给当前用户单独设置全局目录或者用 nvm 这样的版本管理器重新装一个 Node。第二个是上次装过其他版本的残留如果你以前用过 codex 的早期预览版或者从源码构建过先跑一遍npm uninstall -g openai/codex再重装否则可能出现两个可执行文件互相覆盖、你敲了codex却调用的是旧版本的情况。我建议你装完之后立刻跑一下codex --help把几个子命令过一遍。不需要记太多但至少要知道这三个codex login登录认证、codex exec单次执行任务、codex app桌面交互模式。桌面模式下界面和网页很像但数据走的是你本地的配置很适合不习惯纯命令行的朋友。3.2 认证官方登录和 API Key 两种方式Codex 的认证有两种。第一种是 OAuth 浏览器登录执行codex login它会在浏览器里打开授权页面同意之后把凭证写进~/.codex/auth.json。这种方式适合你已经是 OpenAI 账号用户的情况后续不用管 key凭证自动刷新。但它在一些受管网络环境下会失败表现就是浏览器明明转圈但授权一直不回来。第二种方式更直接用 API Key。你在终端里先设置环境变量export OPENAI_API_KEYsk-...然后执行codex exec --api-key 简单测试任务或者让 Codex 自己去读环境变量。API Key 方式的最大优点是与登录态解耦失败率低适合脚本化和 CI 场景。如果你在公司的电脑上我个人建议优先使用 API Key 方式因为组织策略或浏览器限制很容易把 OAuth 流程搞挂你会卡在一个“浏览器授权过了但终端没反应”的状态里非常浪费时间。3.3 关于“汉化”和“中文界面”的一种提醒热词里经常有人搜 Codex 汉化、Codex 中文。实际上 Codex CLI 天然支持中文对话你直接用中文写任务描述就行它也能用中文回复。真正不友好的地方在于错误日志里面全是英文调试信息这对初学者不友好但这不是“汉不汉化”的问题而是你要学会从这些英文日志里找到真正有用的关键词比如 auth、sandbox、model、base_url。后面第 4、5 章我会专门带你看几个高频报错长什么样怎么从里面快速抓到重点。4. 把默认模型换成 DeepSeekconfig.toml 的完整解剖4.1 Codex 配置文件的存放逻辑所有关于模型、端点、沙箱的配置都集中在~/.codex/config.toml里。如果你是第一次跑 codex这个目录和文件不一定存在得手动创建。Codex 支持同时读取多个配置文件常规做法是config.toml 放最基础的公共配置config.local.toml 放每台机器不同的本地覆盖项。我看过很多人直接把所有内容堆在一个文件里也能跑但一旦你要在 A 机器接 DeepSeek、B 机器接本地模型分文件管理会让你省心很多。我的习惯是公共配置写默认模型和安全策略本地配置只写 provider 和 key 相关的部分。一个非常常见的报错我先把预防针打在这里如果你在运行时报了 “codex is ignoring 1 unrecognized configuration setting. check for typos or d...” 这种提示说明 config.toml 里存在 Codex 不认识或不支持的字段。这个报错很有意思它是“忽略型”不是“崩溃型”——Codex 会默默忽略错误字段继续启动但你的自定义端点也因此根本没有生效后续请求全落到默认的 OpenAI 端点上导致各种认证失败或者模型名不支持。遇到它别慌按下文配置逐行核对。4.2 一份可以直接用的 DeepSeek 配置我用 DeepSeek 作为例子因为它是目前接第三方的首选API 价格低速度也不错而且接口完全兼容 OpenAI。在~/.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 chat然后设置环境变量export DEEPSEEK_API_KEY你的DeepSeek密钥这里每个字段我都解释一下因为它们的坑非常隐蔽。model 是你要请求的具体模型名model_provider 指向下文 provider 块里的名称告诉 Codex“我要走你自己定义的供应商”name 是显示名随便起base_url 是 OpenAI 兼容 API 根路径注意以 /v1 结尾env_key 表示 Codex 从哪个环境变量里读取 API Key省得把密钥明文写在配置文件里wire_api 是协议格式它有 responses 和 chat 两个可选值默认是 responses这是当前版本最大的一个坑。4.3 wire_api responses 与 “model is not supported” 报错的真相为什么说 wire_api 是最大的坑因为我第一次接 DeepSeek 时没有写这一行结果 Codex 默认走了 responses 协议把请求发到 https://api.deepseek.com/v1/responses。DeepSeek 目前并不对外开放这个接口服务器返回的 JSON 里写着类似 “the model is not supported when using codex with a...” 这样的错误信息。很多人在这一步直接懵了以为是模型名写错或者 key 无效其实本质是协议不匹配。我帮你把逻辑理清楚Codex 原生使用的是 OpenAI 较新的 Responses API 格式但绝大多数第三方模型服务只实现了最通用的 Chat Completions 格式也就是 /v1/chat/completions 这个路径。wire_api chat 的作用就是让 Codex 用老的 Chat Completions 协议去请求第三方的 OpenAI 兼容端点。改完之后Codex 会把请求发到 https://api.deepseek.com/v1/chat/completionsDeepSeek 就能正确解析了。我用打电话类比一下Responses 协议好比新出的智能电话信号好但只有少数交换机支持Chat Completions 协议是传统电话线哪家都通。你要连一个只有传统线路的服务商就得让 Codex 改走传统线路。配置改完之后你可以先用一个最小的命令验证链路codex exec --skip-git-repo-check 请回复一句链路正常如果你看到模型回话说明端点和认证全部打通。这一步是整个部署过程里最关键的里程碑过了它后面再改别的配置都踏实。4.4 一个容易被忽略的链路测试点有时候 Codex 日志看不出问题但直接用 curl 打 API 就能立刻定位。这个习惯我强烈建议你保留。比如你怀疑 DeepSeek 端点配置有误直接在终端模拟一次最简请求curl -X POST https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d {model:deepseek-chat,messages:[{role:user,content:hi}]}如果这个请求能正常返回说明网络、密钥、模型名都没问题问题肯定出在 Codex 这边的协议或 base_url 上。如果这个请求本身就挂那你再检查 Codex 也没有意义先把 API 端弄通。我见过不少朋友在 Codex 配置里反复折腾最后发现是自己的 API Key 额度用光了这种低级错误用 curl 测一次就能发现。5. 用 CC Switch 切换端点以及它报错的排查经验5.1 CC Switch 到底做了什么CC Switch 是社区里一个挺受欢迎的桌面小工具它的定位是帮你快速切换 Codex 和同类型工具的后端供应商。你打开它选一个供应商填好 API Key点应用它就会去改你的~/.codex/config.toml把模型端点指到它自己启动的一个本地转发端口再由这个端口转发到你选的供应商。这么设计的目的是让你不用手动编辑配置文件在几个供应商之间来回切换就像切换桌面壁纸一样方便。我理解它的良苦用心也用了挺长一段时间。但我要坦白说多一层转发就多一个故障点。你在终端里看到的很多诡异报错恰恰就出现在这个本地转发环节。它本身不是一个“不该用”的工具而是你要知道它出问题时的排查思路。5.2 本地转发报错的完整排查链路不少人在用 CC Switch 接 DeepSeek 时会碰到类似这样的报错“cc switch local proxy failed while handling codex endpoint /responses. provider ...” 我第一次看到的时候第一反应是“是不是我的 DeepSeek key 被封了”折腾半天才发现根本不是。这里的 local proxy 指的是 CC Switch 在本地启动的 API 转发端口它收到 Codex 发来的请求后转发给上游供应商时失败了。结合我前面的协议分析这条报错几乎九成的原因是同一个CC Switch 把请求路径处理成了 /responses但上游的 DeepSeek 不支持。也就是说即使你有一个看起来完全正常的供应商配置只要底层的 wire_api 是默认的 responses转发层就会被卡死。排查链路我给你完整列一遍你可以照着做先确认转发端口是否在监听。一般是 127.0.0.1 上的某个端口具体端口号可以在 CC Switch 的界面或配置文件里看到。用最直接的办法验证这个端口能不能响应——直接用 curl 打一次本地转发端口看它返回什么。如果返回的是上游 DeepSeek 的 4xx/5xx 错误说明转发链路本身是通的问题出在协议格式如果连接被拒绝说明 CC Switch 的本地服务根本没起来可能是软件崩溃、端口冲突或防火墙拦截。再下一步把~/.codex/config.toml打开看 CC Switch 帮你写的 base_url 是不是指向了 May 的本地地址还有 model_provider 是不是它预设的块。如果排查完发现是协议不匹配最省事的解法不是去改 CC Switch 内部设置而是直接绕过它把第 4.2 节的 DeepSeek 配置原样写进 config.toml不使用本地转发一切立刻正常。CC Switch 适合你在几个服务商之间频繁切来切去的场景如果你只是像我一样要稳定地接一个 DeepSeek 或本地模型手写配置反而最可靠。5.3 关于第三方模型与代码任务的现实建议顺便提一句接入 DeepSeek 之后你可能会发现代码理解和代码生成类的任务deepseek-chat 的表现已经很够用但涉及一些比较新的框架和 API 时它的知识截止日期可能导致给出的代码样例过时。这时候不要怀疑 Codex 链路配置有问题而是模型本身的训练数据和能力差异问题。我的做法是日常小任务用第三方模型省钱遇到疑难问题临时切回官方模型对比一下。这也是本地部署的最大价值——切换成本极低你不用换工具改一行 model 名就行。6. 真·本地部署用 Ollama 跑量化模型把数据留在本机6.1 完全离线环境下的配置方案如果说前几章还属于“本地装客户端、模型在云端”那这一章就是名副其实的本地部署大语言模型。场景也很明确比如你有一台配置还行的开发机或者像很多人讨论的 Jetson Orin、Titan RTX 这类专用硬件也可以搭配桌面工作站在完全离线或者不想外发代码的环境里跑 Codex。这时后端就不再是 OpenAI 或 DeepSeek 这种云端 API而是本地模型推理服务。社区里最常用的部署方式是 Ollama它能在几行命令内拉起一个 OpenAI 兼容的本地 API 服务。先用 Ollama 拉取一个量化模型。以已蒸馏的 DeepSeek 系模型为例社区里经常提到的有 7B 量化版命令大致是ollama pull deepseek-r1:7b ollama serve启动之后Ollama 会监听 11434 端口并提供一个 /v1/chat/completions 兼容接口。注意Ollama 的接口同样是 Chat Completions 风格按前面的经验wire_api 一定要写成 chat。然后在 config.toml 里加一个 providermodel deepseek-r1:7b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 wire_api chat本地模型不需要 env_key除非你自己给 Ollama 挂了鉴权层。这样配置完Codex 的所有请求都只会在本机内部走一圈代码上下文不会出网。6.2 本地模型的性能边界与超时处理我必须泼一盆冷水。本地模型虽好但“能跑”和“能用”是两个概念。在目前的消费级硬件上7B 量级模型跑代码任务的反应速度明显比云端 API 慢一个数量级。尤其当 Codex 需要反复读取文件、执行测试、根据报错修正代码时一个任务可能要来回调模型十几次每一次等上几十秒体验会相当痛苦。此外本地模型对超长上下文的处理能力也偏弱项目文件一多Codex 拼出的上下文很容易把模型的上下文窗口塞满。但反过来说在数据不落地的场景里这个方案有它的不可替代性。我把自己的经验给你本地模型适合三种任务——小范围代码重构、单一文件调试、离线环境下的错误修复不适合大仓库分析和跨多文件的重构。如果你想改善体验给模型加长一点的超时时间是有用的Codex 的请求超时时间可以写在配置里也可以从环境变量调整具体值要根据你的硬件情况试出来。我自己的 7B 量化模型经常要等 60 秒以上才有响应你至少要从 90 秒开始试。还有一个容易忽略的点Ollama 默认会优先用 GPU但如果驱动装得不干净它可能悄悄回落到 CPU 推理速度差好几倍启动日志里会有明显提示发现不对就去检查 GPU 驱动和 Ollama 版本。6.3 沙箱模式和审批策略怎么选无论你用云端模型还是本地模型沙箱都是 Codex 的安全底线。当前版本支持几种模式我在一张表里列清楚沙箱模式行为适用场景read-onlyCodex 只能读文件不能写也不能执行写操作问问题、生成建议方案、预览代码workspace-write可以读写当前工作区但执行命令受限日常开发让 AI 直接改代码workspace-docker每个任务起一个 Docker 容器文件在该容器里隔离执行跑测试、执行不可信代码相对应的审批策略 approval_policy 也建议设置成 on-request让 Codex 每次执行写操作或敏感命令前都问你一句。新手不要贪图省事设置成全自动否则脚本一旦出错可能批量改动你不想动的东西。我在配置里长期使用的是 workspace-docker 加上 on-request既隔离又可控代价是要预先装好 Docker。7. 从零跑到一个真实任务以及我的踩坑总结7.1 一个可以照做的示例任务讲完配置我带你完整跑一个真实任务。假设你在一个临时目录里有一个 data.csv想用 Python 做一次去重统计。先在这个目录里执行codex exec --sandbox read-only 写一个 Python 脚本统计 data.csv 中每列重复值的数量输出到 report.txt因为这是只读沙箱Codex 会读取目录里的文件分析任务生成脚本文本然后告诉你它准备创建 report.txt问你放不放行。你同意之后它才会把文件写出来。整个流程走下来如果你能顺利看到生成的脚本就说明你从 CLI 到模型端点再到沙箱的整条链路已经全部打通本地部署这件事到这里算是真正“立住”了。如果你连官方 demo 都经常卡在任务中途我的建议是先用最简配置跑一次官方端点、read-only 沙箱、最小项目目录。这个最小闭环通过之后再加第三方模型、再加 Docker 沙箱、再加本地模型一层一层往上叠。很多人失败是因为一开始就把所有变量叠在一起出了错根本无从判断。7.2 高频报错对照表我把这几天实测里反复出现的高频报错整理成了表格建议你收藏备用。报错/现象根因解决方案model is not supported when using codex with a...端点只支持 chat 格式Codex 却发了 responses 请求把该 provider 的 wire_api 改成 chatcc switch local proxy failed while handling codex endpointCC Switch 本地转发层处理不了 /responses 请求手写 config.toml 直连供应商或更新 CC Switchcodex is ignoring 1 unrecognized configuration setting配置文件里写了 Codex 不认识的字段逐行核对字段名常见笔误是 model_providers 和 model_provider 混用auth failed / 401API Key 没读到或环境变量名与 env_key 不一致核对 export 的环境变量名确认 key 没到期sandbox creation failedDocker 没启动或沙箱模式不支持启动 Docker或临时改用 read-only、workspace-write登录不上 / 无法加载组织设置OAuth 登录态失效或组织列表解析异常清除 ~/.codex/auth.json 后重新 codex login或改用 API Key这张表里前四行出现的概率最高。很多时候问题不是出在模型能力而是协议、配置、端点这三者的组合没配对。这也是我反复建议“改一步验证一步”的原因。7.3 最后的配置管理心得最后聊一点实操层面的东西。我的~/.codex目录本身就是一个 git 仓库config.toml 纳入版本管理每次修改配置之前先 commit 一下出问题直接回滚排查效率高很多。另外不同项目可能有不同的模型偏好和沙箱要求Codex 支持在项目根目录放项目级配置做覆盖这个能力很实用。我在公司代码仓库里用项目级配置强制开 read-only在自己的开源项目里才开放 workspace-write这样安全策略跟着项目走脑子里不用记太多规则。如果你刚接触 Codex我的建议是这样一条升级路径先官方模型跑通再第三方模型省钱最后本地模型掌握。每一步都有明确的验证标准跑通了再进下一步。这样最大程度降低排查成本也让你对 Codex 整个工作链路有真正扎实的理解。