装 Codex 这件事我第一次做的时候在 Windows 上耗了整整两个晚上。第一晚卡在codex windows安装未完成第二晚卡在登录之后一直转圈提示正在重新连接。后来把环境换成 WSL、把配置文件里的一行wire_api改掉五分钟就通了。所以这篇不讲虚的把Codex下载、Codex安装、Codex本地部署这条链路从头到尾捋一遍包括怎么让它跑在本地的开源大模型上以及那些官方文档里不会写的报错怎么处理。如果你手上只有一台普通开发机想在不依赖外部服务的前提下用上命令行编码助手或者你已经在用 Ollama、LM Studio 跑本地模型想把它接进 Codex 的工作流这篇基本能覆盖你 90% 会遇到的问题。全文按先想清楚再动手的顺序展开每一步我都会说清楚为什么这么做而不是丢一堆命令让你照抄。1. Codex 本地化到底要解决哪几件事很多人对Codex 本地部署这个说法有误解以为是把整个模型下载到本机就完事了。实际情况要拆成两层看Codex 本身是个客户端模型是另一回事。搞混这两层后面所有报错都会看不太懂。1.1 Codex CLI 是什么它不包含模型Codex 是 OpenAI 开源的一个终端编码助手本质是一个跑在你本机命令行里的交互程序。它负责的是读取你的项目文件、理解你的自然语言指令、决定要调用哪些工具读文件、写文件、执行命令、把上下文组织成请求发给模型、再把模型返回的内容解析成实际操作。模型不在这个程序里。Codex 自己不带权重它只带怎么和模型对话的逻辑。所以Codex 本地部署严格说包含两件事装好 Codex 客户端以及给它指定一个可访问的模型服务地址。这个地址可以是官方的云端接口也可以是你本机 Ollama 起的http://127.0.0.1:11434/v1。把这个前提想清楚你就能理解为什么会有Codex 装好了但一用就报错的情况——客户端没问题是它连的那个模型服务不支持 Codex 需要的接口形态。1.2 三种落地路径成本和效果差很多从我实际用下来的经验本地化 Codex 大致有三条路适合的场景完全不同路径模型位置硬件要求适合谁客户端本地 云端模型远程无特殊要求日常写业务代码追求效果客户端本地 局域网模型服务公司内网服务器一台带显卡的机器团队共享数据不出内网客户端本地 本机模型本机16G 内存起步显卡更好个人研究、离线环境、学习第三条路是大多数人说的本地部署。要提醒一句能跑起来和能干活是两回事。一个 7B 参数的模型在代码补全上勉强能用但 Codex 这种需要多步推理、工具调用、长上下文的任务7B 基本撑不住。我的建议是本地模型至少 14B 起步量化后显存占用 10G 左右上下文窗口调到 32K 以上才比较像样。1.3 先确认你的机器能不能扛在动手之前花五分钟做个体检能省掉后面两小时的无用功。三个指标内存、显存、磁盘。内存方面模型加载时会先读进内存再分发到显存所以系统内存建议是模型文件大小的 1.5 倍以上。一个 14B 的 Q4 量化模型文件约 9G那你至少要有 16G 内存32G 更舒服。显存方面如果显存不够部分层会回落到 CPU 计算速度会掉得非常明显。14B Q4 建议 12G 显存起步。没有独显也能跑就是响应速度会让你怀疑人生——一轮对话等三分钟写代码的节奏全断了。磁盘方面模型文件动辄几个 GOllama 默认存在用户目录下Windows 上就是C:\Users\用户名\.ollama。C 盘紧张的话提前把这个目录迁走或者设置环境变量OLLAMA_MODELS指到别的盘。2. 装之前先备齐Node、Git 与目录约定Codex 的安装方式有好几种最省事的是通过 npm 全局安装。这意味着你的机器上得先有 Node.js 和 npm。这一步看起来简单但 Windows 上出问题最多的就是这里。2.1 Node.js 版本选择与 npm 源配置Codex 对 Node 版本有要求太老的版本会直接装不上或运行时报语法错误。我的建议是Node 20 LTS 或更高22 也可以。别用奇数版本那些不是长期支持版。安装包从 Node 官网下载.msi或者.zip都行。如果你已经装了旧版本直接装新版覆盖别手动删目录容易留下残余的 PATH 污染。装完之后开一个新的终端窗口验证node -v npm -v两个命令都能输出版本号说明 PATH 配好了。如果提示不是内部或外部命令多半是装的时候没勾选Add to PATH或者你用的是旧终端会话没刷新环境变量。接下来配一下 npm 源这一步能显著减少安装时的等待时间npm config set registry https://registry.npmmirror.com npm config get registry第二条命令会回显你刚设置的地址确认生效。这么做不是必须的但实测下来能少等好几分钟尤其是装带依赖的包时。2.2 Git 的角色以及 Windows 换行符的坑Codex 本身不强制要求装 Git但只要你让它在项目目录里干活Git 就几乎绕不开。原因有两个一是 Codex 会主动调用git diff来看自己改了哪些文件二是它的很多操作会依赖 Git 仓库的边界判断。Git for Windows 安装时有一个选项叫core.autocrlf默认选的是true意思是提交时把换行符转成 LF检出时转成 CRLF。这个设置在纯 Windows 项目里没问题但如果你的仓库里有 shell 脚本、Dockerfile、YAML 配置就会出现诡异现象你只改了三个字git diff却显示整个文件都被重写了。我在一个前端项目里就吃过这个亏。Codex 改了一个组件文件里的一个变量名结果 diff 出来 800 行全是改动根本没法 review。后来在项目根目录加了.gitattributes* textauto eollf *.bat text eolcrlf *.cmd text eolcrlf这条规则的意思是所有文本文件在仓库里统一用 LF 存储只有.bat和.cmd这类 Windows 批处理脚本保留 CRLF。加上之后Codex 的改动 diff 就干净了。如果你是在已有项目上补这个配置可能需要执行一次规范化git add --renormalize . git commit -m normalize line endings2.3 工作目录怎么放别放在中文路径下这是个看起来很小、踩起来很疼的细节。Codex 和它调用的一些底层工具在处理中文路径、带空格的路径、超长路径时经常出问题。我遇到过一次项目放在D:\我的项目\前端重构版\下面Codex 每次执行命令都报路径找不到换到D:\work\frontend-refactor\就一切正常。所以工作时尽量遵循这几条路径全英文不带空格用短横线或下划线连接别放在桌面、文档这类带中文名的系统目录下路径总长度控制在 100 字符以内Windows 的 260 字符限制至今还在很多工具里生效终端推荐用 Windows Terminal 里的 PowerShell 7颜色、复制粘贴、分屏体验都比老版 cmd 好一大截。如果你打算用 WSL那更推荐——后面第 5 章会讲为什么。3. Codex CLI 安装与首次启动的完整链路环境和目录都收拾干净了接下来就是正题。3.1 安装命令与安装失败的三种典型表现全局安装的命令很简单npm install -g openai/codex装完之后验证codex --version能输出版本号就成了。如果这一步出问题大概率是下面三种情况之一。第一种权限不足。Windows 上如果 Node 装在C:\Program Files下面全局安装需要写权限。表现是安装过程报EACCES或EPERM。解决办法是用管理员身份打开终端重新执行或者干脆把 Node 装到用户目录下。第二种codex安装包下载中断。表现是卡在某个包下载不动最后超时。这时候换源就派上用场了回到 2.1 节配一下registry。如果已经装了一半失败先清缓存再重装npm cache clean --force npm install -g openai/codex第三种装完了但codex命令找不到。这就是热词里说的codex打不开。原因通常是 npm 的全局 bin 目录没在 PATH 里。执行下面这条命令看看全局目录在哪npm config get prefix把这个路径下面的binLinux/macOS或根目录Windows加到系统 PATH 里重开终端就好了。别用临时export PATH糊弄重启就没了。3.2 首次启动的登录分支账号登录和密钥登录第一次运行codex会进入登录引导。这里有两套完全不同的路径选错了后面会很别扭。第一条是账号登录走浏览器授权流程。适合你已有对应的订阅账号好处是不用管密钥、额度按套餐走。缺点是登录态会过期隔一段时间要重新授权。第二条是API Key 登录直接用密钥。适合按量计费或者需要接到自建服务上的场景。Codex 会优先读环境变量OPENAI_API_KEY你也可以在配置文件里指定别的环境变量名。对于本地部署这条路我们最终要走的其实是第三条路自定义模型服务商。它不属于上面两种登录分支而是在配置文件里声明一个model_providers条目把base_url指向本机。这条后面 4.3 节详细讲。如果你只是想先确认客户端能不能跑用 API Key 方式最直接。在项目目录下打开终端codex进去之后敲一句解释一下这个项目的目录结构看它能不能正常读文件、正常回话。跑通了再往下做本地模型的接入。3.3 配置文件长什么样放在哪Codex 的主配置文件是config.toml位置在用户家目录下的.codex文件夹里Linux / macOS~/.codex/config.tomlWindowsC:\Users\用户名\.codex\config.tomlWSL~/.codex/config.toml注意这是 WSL 内部的家目录不是 Windows 那个这个文件默认可能不存在需要你自己建。TOML 格式对新手稍微有点陌生但规则很简单[区块]划范围key value赋值。注意字符串必须加引号布尔值不加数字不加。同目录下还有一个auth.json存登录凭据别提交到仓库里也别随手分享出去。配置文件支持分层~/.codex/config.toml是全局的项目根目录下也可以放一个.codex/config.toml做项目级覆盖。这个设计很实用——全局配本地模型做日常实验具体项目里覆盖成云端模型做正式开发互不干扰。还有一个特性值得单独说profiles配置档案。你可以在一个配置文件里定义多套参数组合用命令行切换[profiles.local] model qwen2.5-coder:14b model_provider ollama [profiles.cloud] model gpt-5 model_provider openai用的时候codex --profile local或者codex --profile cloud。这样就不用每次改配置文件了我觉得这是 Codex 设计得最贴心的地方之一。4. 让 Codex 接上本地大模型兼容接口的配置细节这一章是整篇的核心。前面都是铺垫这里才真正决定你能不能把 Codex 跑在自己的模型上。4.1 为什么本地模型能接进来关键在于Codex 支持自定义模型服务商而这些服务商只需要暴露一套和 OpenAI 接口形状一致的 HTTP 端点。目前主流的本地推理工具基本都提供了这层兼容接口Ollama 默认监听127.0.0.1:11434兼容端点在/v1LM Studio 打开 Local Server 后监听127.0.0.1:1234兼容端点在/v1vLLM、SGLang 这类推理框架也都提供/v1/chat/completions所以 Codex 并不认识Ollama它只是把请求发到一个符合约定的地址上。理解了这一点很多配置项就顺理成章了。4.2 先把本地的模型服务跑起来以 Ollama 为例。安装完之后服务默认随开机启动也可以手动确认状态ollama serve然后拉一个适合写代码的模型。选择模型这件事没有标准答案但有几个维度要考虑参数量、量化等级、是否支持工具调用、上下文窗口。ollama pull qwen2.5-coder:14b ollama listollama list会列出本地已有的模型确认你刚拉的那个在里面。想快速验证服务通不通用 curl 打一下curl http://127.0.0.1:11434/v1/models返回一个 JSON 列表就说明服务正常。如果这条命令失败后面所有配置都是白搭先把服务本身跑通。LM Studio 的话相对图形化下载模型之后切到左侧的开发者标签页启动 Local Server记住端口号。它默认就带 OpenAI 兼容接口不用额外配置。4.3 config.toml 里的关键字段逐个拆现在写配置。一个能跑通的本地模型配置大概长这样model qwen2.5-coder:14b model_provider ollama model_context_window 32768 model_max_output_tokens 8192 [model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 env_key OLLAMA_API_KEY wire_api chat逐行说清楚每一条为什么这么写。model必须和ollama list里显示的模型名完全一致包括后面的标签。写成qwen2.5-coder少了:14b就会报模型找不到。model_provider指向下面定义的区块名两者要对上。model_context_window是告诉 Codex 这个模型能装多少 token。Codex 会据此决定往上下文里塞多少文件内容。设小了它读不到足够的代码设大了超出模型实际能力模型会开始胡言乱语或者直接截断报错。这个值要和你实际跑的模型配置对齐Ollama 可以通过PARAMETER num_ctx调整。model_max_output_tokens是单次回复的上限。代码生成场景下 8192 比较合适太小会导致写一半被截断。base_url就是 4.2 节验证过的那个地址末尾的/v1别漏。env_key是个容易踩坑的地方。很多本地服务根本不需要密钥但 Codex 要求这个字段存在并且它指定的那个环境变量必须真的被设置否则启动就报错。解决办法是随便设一个非空值# Linux / macOS export OLLAMA_API_KEYlocal # Windows PowerShell $env:OLLAMA_API_KEYlocal # Windows 永久写入 setx OLLAMA_API_KEY localwire_api是整份配置里最关键的一行下一节单独讲。4.4 wire_api 选错就是那个 /responses 报错的根因线上有一类报错很典型failed while handling codex endpoint /responses或者提示某个模型在线协议下不被支持。这个问题的根因就藏在wire_api这个字段上。wire_api有两个可选值值实际请求的路径说明responses/v1/responses新版协议结构化能力更强chat/v1/chat/completions传统对话接口通用性最好几乎所有本地推理工具只实现了/v1/chat/completions没有实现/v1/responses。如果你的配置里写了responses或者用的是某个默认走 responses 的模板请求打过去就是 404 或者一条看不懂的错误。把它改成chat问题立刻消失。我见过有人因为这个报错折腾了一整天怀疑是模型不对、网络不对、端口不对其实就是一个字符串的事。所以记住这条接本地模型wire_api一律填chat。4.5 两个硬门槛工具调用和上下文长度配置写对了不代表能用。本地模型跑 Codex 还有两道门槛过不去就会表现成能聊天但干不了活。第一道门槛是工具调用能力。Codex 的工作方式是让模型输出结构化的工具调用请求比如读取 src/main.py、执行 npm test然后由客户端去执行。如果模型不支持这套结构化输出它就会把工具调用当成普通文本吐出来Codex 解析不了于是你看到的现象是它说它要读文件但什么都没发生。解决办法是选支持的模型。实测下来Qwen 系列的代码模型在这方面表现比较可靠DeepSeek 系列的代码模型也可以。太小的模型3B 以下基本不用考虑工具调用格式经常出错。第二道门槛是上下文长度。Codex 会往请求里塞系统提示词、项目结构、相关文件内容这个量很容易超过 16K token。如果你的模型只配了 8K 上下文Codex 会把请求截断模型看到的是一段不完整的代码生成的东西自然驴唇不对马嘴。建议把服务端的上下文参数调到 32K 起能到 64K 更好。Ollama 里通过 Modelfile 调整ollama show --modelfile qwen2.5-coder:14b Modelfile # 编辑 Modelfile把 num_ctx 改大 ollama create qwen2.5-coder-32k -f Modelfile然后在 Codex 的model字段里用新建的这个名字。注意上下文调大之后显存占用会跟着涨8K 到 32K 大概要多占 2 到 4G 显存提前算好余量。5. 从能起来到跑得动实测故障排查实录这一章记录的都是我自己撞过的坑每一个都有完整的排查链路。如果你正卡在某个报错上可以直接跳着看。5.1 一直显示正在重新连接怎么办这是本地部署里出现频率最高的现象。程序没崩界面上就是反复提示重连什么都不回。排查顺序我一般是这么走的第一步确认模型服务真的在跑。开一个新终端curl http://127.0.0.1:11434/v1/models。如果这条不通问题根本不在于 Codex去检查服务进程。有时候是内存不够被系统杀掉了有时候是上次没退干净端口被占着。第二步确认端口没被别的东西占了。Windows 上用netstat -ano | findstr 11434Linux 上用ss -ltnp | grep 11434。看到一个你不认识的进程占着这个端口那就是冲突了改端口或者把占用进程关掉。第三步检查地址写的是127.0.0.1还是localhost。这两个在大多数情况下等价但在一些配置了 IPv6 优先的机器上localhost会解析成::1而服务只监听了 IPv4于是连不上。统一写127.0.0.1能避开一大类玄学问题。第四步看模型是不是正在加载。首次调用一个大模型加载权重可能要一两分钟。这段时间请求就是在等界面看起来像卡住了。耐心等第一轮返回之后就快了。第五步把请求日志打开。Ollama 可以用OLLAMA_DEBUG1 ollama serve启动看它有没有收到请求、收到了什么、返回了什么。这一步能直接定位是客户端没发出去还是服务端返回异常。5.2 Windows 上安装未完成的三种真实原因codex windows安装未完成这个提示背后其实对应好几种不同的失败得分开看。原因一WSL 依赖没装。早期版本的 Codex 在 Windows 上强依赖 WSL如果系统里没启用 WSL 组件安装脚本跑到一半就停了。解决办法是在管理员 PowerShell 里执行wsl --install然后重启。装完之后wsl --list --verbose能看到发行版列表就说明好了。原因二系统版本太老。WSL2 需要比较新的系统版本太老的版本上只能装 WSL1而 WSL1 在文件系统上有兼容问题Codex 在里面跑会出现各种奇怪的 IO 错误。这种情况下要么升级系统要么改用原生 Windows 版本。原因三Long Path 没开启。Node 生态的依赖目录嵌套非常深Windows 默认的 260 字符路径限制会在node_modules里爆掉。表现是安装到 90% 突然报路径太长。开启长路径支持# 管理员 PowerShell New-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force改完之后重启才生效。这个改动对开发体验的整体提升比想象中大早点开。5.3 沙箱模式和审批策略先理解再关掉Codex 默认带一层安全机制防止它在你没授权的情况下乱改文件或执行命令。这套机制由两个概念组成沙箱模式sandbox_mode决定它能碰什么模式能力范围read-only只能读任何写操作都被拦workspace-write可以在工作目录内写目录外不行danger-full-access无限制审批策略approval_policy决定什么时候问你策略行为untrusted只对可信操作自动放行其余都问on-failure先执行失败了再问on-request由模型自己决定要不要问never从不询问直接执行在 Windows 原生环境下沙箱的底层实现支持不如 Linux 完整有时候会遇到明明在 workspace 里却被拦的情况。这时候可以退一步把approval_policy设成on-request让它在需要的时候问你而不是硬拦。注意danger-full-access配合never是最高权限组合等于把整台机器的控制权交出去。除非是在一次性的虚拟机或者容器里否则别这么配。热词里提到的vmware虚拟机安装教程在这里就有意义了——想放开手脚做实验先在虚拟机里跑一遍是更稳妥的做法。5.4 响应慢、输出中途断掉怎么调本地模型跑 Codex 速度不理想是常态但可以优化。显存不足导致部分层跑在 CPU 上是最常见的原因。判断方法是看推理时的 GPU 占用如果显存吃满了但 GPU 利用率上不去说明在等 CPU。降一档量化等级比如从 Q8 换到 Q4通常比换模型更有效。输出中途断掉多半是model_max_output_tokens或者模型的num_predict限制住了。两个地方都要检查客户端和服务端的限制是取小值生效的。还有一种是模型在长上下文下变慢。注意力计算量随上下文长度是平方级增长的32K 上下文比 8K 慢好几倍很正常。如果只是做小范围改动可以把model_context_window临时调回 16K速度会明显回升。6. 把 Codex 编进日常工具链MCP 与本地服务协同Codex 单独用已经能解决不少问题但它真正发挥威力的地方是和周边工具串起来。这一章讲几个我用得比较多的组合。6.1 用 MCP 给 Codex 扩展能力MCP 是一套让模型访问外部工具的标准接口。Codex 支持把 MCP 服务注册进配置注册之后模型就能主动调用这些工具。举个实用的场景让 Codex 能查本地数据库表结构。在config.toml里加[mcp_servers.mysql] command npx args [-y, some-scope/mcp-mysql, --host, 127.0.0.1, --port, 3306] env { MYSQL_USER readonly, MYSQL_PASSWORD your_password }配上之后你就可以直接问 Codex 帮我看看 users 表的结构然后写一个查询接口。它会自己调工具去查表再根据实际的字段名生成代码。这比手动复制粘贴表结构高效太多。配置 MCP 有两个经验一是只给只读权限除非你很清楚在做什么二是一个服务一个区块别把多个服务的参数混在一起调试的时候会很痛苦。6.2 和本地知识库、工作流平台的配合如果你的团队已经在用本地部署的工作流平台或者知识库系统Codex 可以扮演代码生成和修改这一环。典型的串法是知识库负责检索需求文档和历史方案Codex 负责把方案落成代码工作流平台负责串联和触发。我自己搭过一条比较简单的链路把接口文档放进本地知识库写代码前先让 Codex 通过 MCP 检索相关接口约定然后再开始改文件。效果比让它自由发挥好很多因为它不用猜接口长什么样。还有一个容易被忽略的点Codex 的会话上下文是有限的别指望它在一次会话里处理跨越十几个文件的大重构。我的做法是按模块拆任务一个模块一次会话做完提交一次 Git出问题好回滚。这个习惯养成之后本地模型的能力上限会被拉高不少。6.3 团队共享一套本地模型服务的配置要点如果是一台带显卡的机器给多个人用有几个地方需要调。服务监听地址要从127.0.0.1改成0.0.0.0否则只有本机能访问。Ollama 通过环境变量OLLAMA_HOST0.0.0.0:11434设置。并发请求要限制。默认配置下多个请求同时打过来显存直接爆掉全部失败。Ollama 的OLLAMA_NUM_PARALLEL可以控制并发数一般设成 1 到 2多了反而更慢。模型常驻内存要开启避免每次请求都重新加载。OLLAMA_KEEP_ALIVE设成一个较大的值比如-1表示永不卸载。代价是显存一直被占着。客户端的config.toml里把base_url改成那台机器的 IP。注意防火墙要放行对应端口这个在 Windows 上默认是拦的需要在防火墙规则里加一条入站允许。最后再说一句关于模型选择的经验。本地部署里最纠结的就是选哪个模型我的建议是先用一个中等规模、工具调用支持好的模型把流程跑通再考虑换更大的。很多人的问题不是模型不够强而是流程本身没通却以为是模型不行然后不停地换模型、拉权重、重配环境最后时间全花在下载上了。先跑通再优化这个顺序别搞反。我在实际使用中最大的体会是本地部署 Codex 的难点从来不在模型本身而在环境、配置和接口约定这三件看起来不起眼的事上。把wire_api设成chat、把路径统一成英文、把长路径支持打开这三件事做完成功率会高出一大截。剩下的时间才是真正用来调模型和写提示词的。 
长河君 · 2026/9/19 8:29:21 · 阅读 1.2k Codex下载安装与本地部署：接入Ollama及Windows排错
装 Codex 这件事我第一次做的时候在 Windows 上耗了整整两个晚上。第一晚卡在codex windows安装未完成第二晚卡在登录之后一直转圈提示正在重新连接。后来把环境换成 WSL、把配置文件里的一行wire_api改掉五分钟就通了。所以这篇不讲虚的把Codex下载、Codex安装、Codex本地部署这条链路从头到尾捋一遍包括怎么让它跑在本地的开源大模型上以及那些官方文档里不会写的报错怎么处理。如果你手上只有一台普通开发机想在不依赖外部服务的前提下用上命令行编码助手或者你已经在用 Ollama、LM Studio 跑本地模型想把它接进 Codex 的工作流这篇基本能覆盖你 90% 会遇到的问题。全文按先想清楚再动手的顺序展开每一步我都会说清楚为什么这么做而不是丢一堆命令让你照抄。1. Codex 本地化到底要解决哪几件事很多人对Codex 本地部署这个说法有误解以为是把整个模型下载到本机就完事了。实际情况要拆成两层看Codex 本身是个客户端模型是另一回事。搞混这两层后面所有报错都会看不太懂。1.1 Codex CLI 是什么它不包含模型Codex 是 OpenAI 开源的一个终端编码助手本质是一个跑在你本机命令行里的交互程序。它负责的是读取你的项目文件、理解你的自然语言指令、决定要调用哪些工具读文件、写文件、执行命令、把上下文组织成请求发给模型、再把模型返回的内容解析成实际操作。模型不在这个程序里。Codex 自己不带权重它只带怎么和模型对话的逻辑。所以Codex 本地部署严格说包含两件事装好 Codex 客户端以及给它指定一个可访问的模型服务地址。这个地址可以是官方的云端接口也可以是你本机 Ollama 起的http://127.0.0.1:11434/v1。把这个前提想清楚你就能理解为什么会有Codex 装好了但一用就报错的情况——客户端没问题是它连的那个模型服务不支持 Codex 需要的接口形态。1.2 三种落地路径成本和效果差很多从我实际用下来的经验本地化 Codex 大致有三条路适合的场景完全不同路径模型位置硬件要求适合谁客户端本地 云端模型远程无特殊要求日常写业务代码追求效果客户端本地 局域网模型服务公司内网服务器一台带显卡的机器团队共享数据不出内网客户端本地 本机模型本机16G 内存起步显卡更好个人研究、离线环境、学习第三条路是大多数人说的本地部署。要提醒一句能跑起来和能干活是两回事。一个 7B 参数的模型在代码补全上勉强能用但 Codex 这种需要多步推理、工具调用、长上下文的任务7B 基本撑不住。我的建议是本地模型至少 14B 起步量化后显存占用 10G 左右上下文窗口调到 32K 以上才比较像样。1.3 先确认你的机器能不能扛在动手之前花五分钟做个体检能省掉后面两小时的无用功。三个指标内存、显存、磁盘。内存方面模型加载时会先读进内存再分发到显存所以系统内存建议是模型文件大小的 1.5 倍以上。一个 14B 的 Q4 量化模型文件约 9G那你至少要有 16G 内存32G 更舒服。显存方面如果显存不够部分层会回落到 CPU 计算速度会掉得非常明显。14B Q4 建议 12G 显存起步。没有独显也能跑就是响应速度会让你怀疑人生——一轮对话等三分钟写代码的节奏全断了。磁盘方面模型文件动辄几个 GOllama 默认存在用户目录下Windows 上就是C:\Users\用户名\.ollama。C 盘紧张的话提前把这个目录迁走或者设置环境变量OLLAMA_MODELS指到别的盘。2. 装之前先备齐Node、Git 与目录约定Codex 的安装方式有好几种最省事的是通过 npm 全局安装。这意味着你的机器上得先有 Node.js 和 npm。这一步看起来简单但 Windows 上出问题最多的就是这里。2.1 Node.js 版本选择与 npm 源配置Codex 对 Node 版本有要求太老的版本会直接装不上或运行时报语法错误。我的建议是Node 20 LTS 或更高22 也可以。别用奇数版本那些不是长期支持版。安装包从 Node 官网下载.msi或者.zip都行。如果你已经装了旧版本直接装新版覆盖别手动删目录容易留下残余的 PATH 污染。装完之后开一个新的终端窗口验证node -v npm -v两个命令都能输出版本号说明 PATH 配好了。如果提示不是内部或外部命令多半是装的时候没勾选Add to PATH或者你用的是旧终端会话没刷新环境变量。接下来配一下 npm 源这一步能显著减少安装时的等待时间npm config set registry https://registry.npmmirror.com npm config get registry第二条命令会回显你刚设置的地址确认生效。这么做不是必须的但实测下来能少等好几分钟尤其是装带依赖的包时。2.2 Git 的角色以及 Windows 换行符的坑Codex 本身不强制要求装 Git但只要你让它在项目目录里干活Git 就几乎绕不开。原因有两个一是 Codex 会主动调用git diff来看自己改了哪些文件二是它的很多操作会依赖 Git 仓库的边界判断。Git for Windows 安装时有一个选项叫core.autocrlf默认选的是true意思是提交时把换行符转成 LF检出时转成 CRLF。这个设置在纯 Windows 项目里没问题但如果你的仓库里有 shell 脚本、Dockerfile、YAML 配置就会出现诡异现象你只改了三个字git diff却显示整个文件都被重写了。我在一个前端项目里就吃过这个亏。Codex 改了一个组件文件里的一个变量名结果 diff 出来 800 行全是改动根本没法 review。后来在项目根目录加了.gitattributes* textauto eollf *.bat text eolcrlf *.cmd text eolcrlf这条规则的意思是所有文本文件在仓库里统一用 LF 存储只有.bat和.cmd这类 Windows 批处理脚本保留 CRLF。加上之后Codex 的改动 diff 就干净了。如果你是在已有项目上补这个配置可能需要执行一次规范化git add --renormalize . git commit -m normalize line endings2.3 工作目录怎么放别放在中文路径下这是个看起来很小、踩起来很疼的细节。Codex 和它调用的一些底层工具在处理中文路径、带空格的路径、超长路径时经常出问题。我遇到过一次项目放在D:\我的项目\前端重构版\下面Codex 每次执行命令都报路径找不到换到D:\work\frontend-refactor\就一切正常。所以工作时尽量遵循这几条路径全英文不带空格用短横线或下划线连接别放在桌面、文档这类带中文名的系统目录下路径总长度控制在 100 字符以内Windows 的 260 字符限制至今还在很多工具里生效终端推荐用 Windows Terminal 里的 PowerShell 7颜色、复制粘贴、分屏体验都比老版 cmd 好一大截。如果你打算用 WSL那更推荐——后面第 5 章会讲为什么。3. Codex CLI 安装与首次启动的完整链路环境和目录都收拾干净了接下来就是正题。3.1 安装命令与安装失败的三种典型表现全局安装的命令很简单npm install -g openai/codex装完之后验证codex --version能输出版本号就成了。如果这一步出问题大概率是下面三种情况之一。第一种权限不足。Windows 上如果 Node 装在C:\Program Files下面全局安装需要写权限。表现是安装过程报EACCES或EPERM。解决办法是用管理员身份打开终端重新执行或者干脆把 Node 装到用户目录下。第二种codex安装包下载中断。表现是卡在某个包下载不动最后超时。这时候换源就派上用场了回到 2.1 节配一下registry。如果已经装了一半失败先清缓存再重装npm cache clean --force npm install -g openai/codex第三种装完了但codex命令找不到。这就是热词里说的codex打不开。原因通常是 npm 的全局 bin 目录没在 PATH 里。执行下面这条命令看看全局目录在哪npm config get prefix把这个路径下面的binLinux/macOS或根目录Windows加到系统 PATH 里重开终端就好了。别用临时export PATH糊弄重启就没了。3.2 首次启动的登录分支账号登录和密钥登录第一次运行codex会进入登录引导。这里有两套完全不同的路径选错了后面会很别扭。第一条是账号登录走浏览器授权流程。适合你已有对应的订阅账号好处是不用管密钥、额度按套餐走。缺点是登录态会过期隔一段时间要重新授权。第二条是API Key 登录直接用密钥。适合按量计费或者需要接到自建服务上的场景。Codex 会优先读环境变量OPENAI_API_KEY你也可以在配置文件里指定别的环境变量名。对于本地部署这条路我们最终要走的其实是第三条路自定义模型服务商。它不属于上面两种登录分支而是在配置文件里声明一个model_providers条目把base_url指向本机。这条后面 4.3 节详细讲。如果你只是想先确认客户端能不能跑用 API Key 方式最直接。在项目目录下打开终端codex进去之后敲一句解释一下这个项目的目录结构看它能不能正常读文件、正常回话。跑通了再往下做本地模型的接入。3.3 配置文件长什么样放在哪Codex 的主配置文件是config.toml位置在用户家目录下的.codex文件夹里Linux / macOS~/.codex/config.tomlWindowsC:\Users\用户名\.codex\config.tomlWSL~/.codex/config.toml注意这是 WSL 内部的家目录不是 Windows 那个这个文件默认可能不存在需要你自己建。TOML 格式对新手稍微有点陌生但规则很简单[区块]划范围key value赋值。注意字符串必须加引号布尔值不加数字不加。同目录下还有一个auth.json存登录凭据别提交到仓库里也别随手分享出去。配置文件支持分层~/.codex/config.toml是全局的项目根目录下也可以放一个.codex/config.toml做项目级覆盖。这个设计很实用——全局配本地模型做日常实验具体项目里覆盖成云端模型做正式开发互不干扰。还有一个特性值得单独说profiles配置档案。你可以在一个配置文件里定义多套参数组合用命令行切换[profiles.local] model qwen2.5-coder:14b model_provider ollama [profiles.cloud] model gpt-5 model_provider openai用的时候codex --profile local或者codex --profile cloud。这样就不用每次改配置文件了我觉得这是 Codex 设计得最贴心的地方之一。4. 让 Codex 接上本地大模型兼容接口的配置细节这一章是整篇的核心。前面都是铺垫这里才真正决定你能不能把 Codex 跑在自己的模型上。4.1 为什么本地模型能接进来关键在于Codex 支持自定义模型服务商而这些服务商只需要暴露一套和 OpenAI 接口形状一致的 HTTP 端点。目前主流的本地推理工具基本都提供了这层兼容接口Ollama 默认监听127.0.0.1:11434兼容端点在/v1LM Studio 打开 Local Server 后监听127.0.0.1:1234兼容端点在/v1vLLM、SGLang 这类推理框架也都提供/v1/chat/completions所以 Codex 并不认识Ollama它只是把请求发到一个符合约定的地址上。理解了这一点很多配置项就顺理成章了。4.2 先把本地的模型服务跑起来以 Ollama 为例。安装完之后服务默认随开机启动也可以手动确认状态ollama serve然后拉一个适合写代码的模型。选择模型这件事没有标准答案但有几个维度要考虑参数量、量化等级、是否支持工具调用、上下文窗口。ollama pull qwen2.5-coder:14b ollama listollama list会列出本地已有的模型确认你刚拉的那个在里面。想快速验证服务通不通用 curl 打一下curl http://127.0.0.1:11434/v1/models返回一个 JSON 列表就说明服务正常。如果这条命令失败后面所有配置都是白搭先把服务本身跑通。LM Studio 的话相对图形化下载模型之后切到左侧的开发者标签页启动 Local Server记住端口号。它默认就带 OpenAI 兼容接口不用额外配置。4.3 config.toml 里的关键字段逐个拆现在写配置。一个能跑通的本地模型配置大概长这样model qwen2.5-coder:14b model_provider ollama model_context_window 32768 model_max_output_tokens 8192 [model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 env_key OLLAMA_API_KEY wire_api chat逐行说清楚每一条为什么这么写。model必须和ollama list里显示的模型名完全一致包括后面的标签。写成qwen2.5-coder少了:14b就会报模型找不到。model_provider指向下面定义的区块名两者要对上。model_context_window是告诉 Codex 这个模型能装多少 token。Codex 会据此决定往上下文里塞多少文件内容。设小了它读不到足够的代码设大了超出模型实际能力模型会开始胡言乱语或者直接截断报错。这个值要和你实际跑的模型配置对齐Ollama 可以通过PARAMETER num_ctx调整。model_max_output_tokens是单次回复的上限。代码生成场景下 8192 比较合适太小会导致写一半被截断。base_url就是 4.2 节验证过的那个地址末尾的/v1别漏。env_key是个容易踩坑的地方。很多本地服务根本不需要密钥但 Codex 要求这个字段存在并且它指定的那个环境变量必须真的被设置否则启动就报错。解决办法是随便设一个非空值# Linux / macOS export OLLAMA_API_KEYlocal # Windows PowerShell $env:OLLAMA_API_KEYlocal # Windows 永久写入 setx OLLAMA_API_KEY localwire_api是整份配置里最关键的一行下一节单独讲。4.4 wire_api 选错就是那个 /responses 报错的根因线上有一类报错很典型failed while handling codex endpoint /responses或者提示某个模型在线协议下不被支持。这个问题的根因就藏在wire_api这个字段上。wire_api有两个可选值值实际请求的路径说明responses/v1/responses新版协议结构化能力更强chat/v1/chat/completions传统对话接口通用性最好几乎所有本地推理工具只实现了/v1/chat/completions没有实现/v1/responses。如果你的配置里写了responses或者用的是某个默认走 responses 的模板请求打过去就是 404 或者一条看不懂的错误。把它改成chat问题立刻消失。我见过有人因为这个报错折腾了一整天怀疑是模型不对、网络不对、端口不对其实就是一个字符串的事。所以记住这条接本地模型wire_api一律填chat。4.5 两个硬门槛工具调用和上下文长度配置写对了不代表能用。本地模型跑 Codex 还有两道门槛过不去就会表现成能聊天但干不了活。第一道门槛是工具调用能力。Codex 的工作方式是让模型输出结构化的工具调用请求比如读取 src/main.py、执行 npm test然后由客户端去执行。如果模型不支持这套结构化输出它就会把工具调用当成普通文本吐出来Codex 解析不了于是你看到的现象是它说它要读文件但什么都没发生。解决办法是选支持的模型。实测下来Qwen 系列的代码模型在这方面表现比较可靠DeepSeek 系列的代码模型也可以。太小的模型3B 以下基本不用考虑工具调用格式经常出错。第二道门槛是上下文长度。Codex 会往请求里塞系统提示词、项目结构、相关文件内容这个量很容易超过 16K token。如果你的模型只配了 8K 上下文Codex 会把请求截断模型看到的是一段不完整的代码生成的东西自然驴唇不对马嘴。建议把服务端的上下文参数调到 32K 起能到 64K 更好。Ollama 里通过 Modelfile 调整ollama show --modelfile qwen2.5-coder:14b Modelfile # 编辑 Modelfile把 num_ctx 改大 ollama create qwen2.5-coder-32k -f Modelfile然后在 Codex 的model字段里用新建的这个名字。注意上下文调大之后显存占用会跟着涨8K 到 32K 大概要多占 2 到 4G 显存提前算好余量。5. 从能起来到跑得动实测故障排查实录这一章记录的都是我自己撞过的坑每一个都有完整的排查链路。如果你正卡在某个报错上可以直接跳着看。5.1 一直显示正在重新连接怎么办这是本地部署里出现频率最高的现象。程序没崩界面上就是反复提示重连什么都不回。排查顺序我一般是这么走的第一步确认模型服务真的在跑。开一个新终端curl http://127.0.0.1:11434/v1/models。如果这条不通问题根本不在于 Codex去检查服务进程。有时候是内存不够被系统杀掉了有时候是上次没退干净端口被占着。第二步确认端口没被别的东西占了。Windows 上用netstat -ano | findstr 11434Linux 上用ss -ltnp | grep 11434。看到一个你不认识的进程占着这个端口那就是冲突了改端口或者把占用进程关掉。第三步检查地址写的是127.0.0.1还是localhost。这两个在大多数情况下等价但在一些配置了 IPv6 优先的机器上localhost会解析成::1而服务只监听了 IPv4于是连不上。统一写127.0.0.1能避开一大类玄学问题。第四步看模型是不是正在加载。首次调用一个大模型加载权重可能要一两分钟。这段时间请求就是在等界面看起来像卡住了。耐心等第一轮返回之后就快了。第五步把请求日志打开。Ollama 可以用OLLAMA_DEBUG1 ollama serve启动看它有没有收到请求、收到了什么、返回了什么。这一步能直接定位是客户端没发出去还是服务端返回异常。5.2 Windows 上安装未完成的三种真实原因codex windows安装未完成这个提示背后其实对应好几种不同的失败得分开看。原因一WSL 依赖没装。早期版本的 Codex 在 Windows 上强依赖 WSL如果系统里没启用 WSL 组件安装脚本跑到一半就停了。解决办法是在管理员 PowerShell 里执行wsl --install然后重启。装完之后wsl --list --verbose能看到发行版列表就说明好了。原因二系统版本太老。WSL2 需要比较新的系统版本太老的版本上只能装 WSL1而 WSL1 在文件系统上有兼容问题Codex 在里面跑会出现各种奇怪的 IO 错误。这种情况下要么升级系统要么改用原生 Windows 版本。原因三Long Path 没开启。Node 生态的依赖目录嵌套非常深Windows 默认的 260 字符路径限制会在node_modules里爆掉。表现是安装到 90% 突然报路径太长。开启长路径支持# 管理员 PowerShell New-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force改完之后重启才生效。这个改动对开发体验的整体提升比想象中大早点开。5.3 沙箱模式和审批策略先理解再关掉Codex 默认带一层安全机制防止它在你没授权的情况下乱改文件或执行命令。这套机制由两个概念组成沙箱模式sandbox_mode决定它能碰什么模式能力范围read-only只能读任何写操作都被拦workspace-write可以在工作目录内写目录外不行danger-full-access无限制审批策略approval_policy决定什么时候问你策略行为untrusted只对可信操作自动放行其余都问on-failure先执行失败了再问on-request由模型自己决定要不要问never从不询问直接执行在 Windows 原生环境下沙箱的底层实现支持不如 Linux 完整有时候会遇到明明在 workspace 里却被拦的情况。这时候可以退一步把approval_policy设成on-request让它在需要的时候问你而不是硬拦。注意danger-full-access配合never是最高权限组合等于把整台机器的控制权交出去。除非是在一次性的虚拟机或者容器里否则别这么配。热词里提到的vmware虚拟机安装教程在这里就有意义了——想放开手脚做实验先在虚拟机里跑一遍是更稳妥的做法。5.4 响应慢、输出中途断掉怎么调本地模型跑 Codex 速度不理想是常态但可以优化。显存不足导致部分层跑在 CPU 上是最常见的原因。判断方法是看推理时的 GPU 占用如果显存吃满了但 GPU 利用率上不去说明在等 CPU。降一档量化等级比如从 Q8 换到 Q4通常比换模型更有效。输出中途断掉多半是model_max_output_tokens或者模型的num_predict限制住了。两个地方都要检查客户端和服务端的限制是取小值生效的。还有一种是模型在长上下文下变慢。注意力计算量随上下文长度是平方级增长的32K 上下文比 8K 慢好几倍很正常。如果只是做小范围改动可以把model_context_window临时调回 16K速度会明显回升。6. 把 Codex 编进日常工具链MCP 与本地服务协同Codex 单独用已经能解决不少问题但它真正发挥威力的地方是和周边工具串起来。这一章讲几个我用得比较多的组合。6.1 用 MCP 给 Codex 扩展能力MCP 是一套让模型访问外部工具的标准接口。Codex 支持把 MCP 服务注册进配置注册之后模型就能主动调用这些工具。举个实用的场景让 Codex 能查本地数据库表结构。在config.toml里加[mcp_servers.mysql] command npx args [-y, some-scope/mcp-mysql, --host, 127.0.0.1, --port, 3306] env { MYSQL_USER readonly, MYSQL_PASSWORD your_password }配上之后你就可以直接问 Codex 帮我看看 users 表的结构然后写一个查询接口。它会自己调工具去查表再根据实际的字段名生成代码。这比手动复制粘贴表结构高效太多。配置 MCP 有两个经验一是只给只读权限除非你很清楚在做什么二是一个服务一个区块别把多个服务的参数混在一起调试的时候会很痛苦。6.2 和本地知识库、工作流平台的配合如果你的团队已经在用本地部署的工作流平台或者知识库系统Codex 可以扮演代码生成和修改这一环。典型的串法是知识库负责检索需求文档和历史方案Codex 负责把方案落成代码工作流平台负责串联和触发。我自己搭过一条比较简单的链路把接口文档放进本地知识库写代码前先让 Codex 通过 MCP 检索相关接口约定然后再开始改文件。效果比让它自由发挥好很多因为它不用猜接口长什么样。还有一个容易被忽略的点Codex 的会话上下文是有限的别指望它在一次会话里处理跨越十几个文件的大重构。我的做法是按模块拆任务一个模块一次会话做完提交一次 Git出问题好回滚。这个习惯养成之后本地模型的能力上限会被拉高不少。6.3 团队共享一套本地模型服务的配置要点如果是一台带显卡的机器给多个人用有几个地方需要调。服务监听地址要从127.0.0.1改成0.0.0.0否则只有本机能访问。Ollama 通过环境变量OLLAMA_HOST0.0.0.0:11434设置。并发请求要限制。默认配置下多个请求同时打过来显存直接爆掉全部失败。Ollama 的OLLAMA_NUM_PARALLEL可以控制并发数一般设成 1 到 2多了反而更慢。模型常驻内存要开启避免每次请求都重新加载。OLLAMA_KEEP_ALIVE设成一个较大的值比如-1表示永不卸载。代价是显存一直被占着。客户端的config.toml里把base_url改成那台机器的 IP。注意防火墙要放行对应端口这个在 Windows 上默认是拦的需要在防火墙规则里加一条入站允许。最后再说一句关于模型选择的经验。本地部署里最纠结的就是选哪个模型我的建议是先用一个中等规模、工具调用支持好的模型把流程跑通再考虑换更大的。很多人的问题不是模型不够强而是流程本身没通却以为是模型不行然后不停地换模型、拉权重、重配环境最后时间全花在下载上了。先跑通再优化这个顺序别搞反。我在实际使用中最大的体会是本地部署 Codex 的难点从来不在模型本身而在环境、配置和接口约定这三件看起来不起眼的事上。把wire_api设成chat、把路径统一成英文、把长路径支持打开这三件事做完成功率会高出一大截。剩下的时间才是真正用来调模型和写提示词的。