Codex 这名字这两年折腾 AI 编程的人都绕不开但很多人冲到下载页装完发现它默认跑的是一套云端模型服务本地环境完全没利用起来。我花了大半天时间把 Codex 从安装、配置到接入本地大模型完整跑了一遍最后整出了一个能脱网状态下继续干活的 AI 编程助手。这篇就从头讲讲我是怎么做的适合正在评估 Codex 或者想把 AI 编程能力搬进本地环境的朋友参考。先说清楚Codex 是 OpenAI 出的一个 AI 编程代理工具它不是一个聊天窗口而是能直接在你项目目录里读代码、改代码、跑命令的那种。你可以把它理解成一个“住在终端里的结对工程师”。默认情况下它走的是在线模型接口依赖网络、依赖平台账号。而我这次做的本地部署核心思路很简单把模型这一环从云端换成本地或可自控的模型服务让 Codex 的客户端能力继续保留但推理后端由自己掌控。1. Codex 到底是什么为什么值得本地部署1.1 先理解 Codex 的定位Codex 在外观上确实只是个命令行程序装好后你在终端敲codex就能交互。但它的内核是一个“代理式”编程助手跟那些只做补全的代码插件不是一类东西。它可以扫描你的整个项目结构理解上下文按你的自然语言指令修改多个文件自动执行测试、lint、构建命令在沙箱环境里试验代码给出运行结果。实际上Codex 的工程化能力来自“模型推理 工具调用”的闭环。它会先拆解你的需求生成步骤然后逐步调用终端工具、读写文件每一步都回到模型重新评估。这也是为什么它比“复制粘贴问答”要复杂得多。1.2 做本地部署解决的几个问题我选择本地部署不是因为 Codex 默认体验不好而是有现实痛点数据敏感公司项目或者个人私有代码不适合丢给外部服务本地部署意味着代码只在本地进出推理也在本机或内网完成。依赖外部服务的不稳定网络抖动、服务限流、登录失效都会打断工作流。本地模型跑起来之后这些因素基本被隔离了。成本与配额云端模型服务按 token 计费高强度使用一上午可能就消耗不少额度。本地模型只要硬件扛得住想跑多少跑多少。可定制性想要给模型加特定系统提示、微调行为、限定工具权限本地部署能完全掌控。这里要提醒一下Codex 本身是开源 CLI但“本地部署”不等于彻底离线。如果你要用 OpenAI 官方模型依然需要网络如果你想完全走本地模型就需要像 Ollama 这样的大模型运行环境来提供推理服务。所谓“本地部署”正确理解是把 Codex 客户端和模型服务都装在自己可控的环境里。2. 下载与安装开发机环境准备2.1 环境要求与检查Codex 官方对操作系统有明确支持范围macOS、Ubuntu 这类主流 Linux 发行版、Windows 桌面版是最近才补上的。不同平台安装方式略有差别但核心依赖是一样的。我这次是在 Ubuntu 22.04 上操作的硬件配置是 i7-12700K 32GB 内存 RTX 3060 12GB。如果你的机器配置偏低后面跑本地模型时建议选小参数模型或者直接用 API 兼容服务。环境检查主要看三样系统版本lsb_release -a确认系统发行版和版本Node.jsCodex 的 npm 包是官方主推安装方式需要 Node.js 18 或更高版本node -v查看网络连通确认能访问需要访问的模型服务域和 GitHub如果要从源码仓库获取东西。注意如果你的机器上 Node 版本太老建议先用 nvm 装一个新版 Node不要直接改系统默认 Node避免影响其他项目。2.2 三种安装方式第一种是最常见的 npm 方式npm install -g openai/codex这个包名是openai/codex别漏了 scope。装完会在全局 bin 目录生成codex可执行文件。优点是简单、自动处理依赖缺点是 Codex 发布新版本时需要手动执行同样的命令来升级。第二种是官方原生安装脚本。它的好处是不依赖 Node.js 环境适合想隔离环境的人。在官方发布页能找到指向对应 tar.gz 包的下载链接解压后把二进制放进$PATH即可。你可以手动下载适合自己平台的包然后执行tar -xzf codex-x86_64-linux.tar.gz sudo mv codex /usr/local/bin/ codex --version第三种是从源码编译。如果你要修改或者魔改 Codex 的行为这种最合适。需要先git clone官方仓库然后npm install和npm run build最终产物同样是一个 CLI。对于大多数使用者第一、二种足够。Windows 桌面版的话官方有安装包下载后一路下一步就行。但要注意Windows 桌面版本质是图形外壳加 Codex CLI 内核如果你习惯终端工作流还是建议用 WSL 2 跑 Linux 版整体体验更顺。2.3 验证安装与初始化配置装完先验证codex --version能输出版本号说明核心可用。但此时你还不能直接开工因为它没有任何账号或 API 登录信息。官方支持两种登录方式一种是直接用 ChatGPT 账号做 OAuth 登录适合有订阅的用户另一种是配置 OpenAI API Key适合想按量计费或者走兼容 API 的用户。执行登录codex login会弹出一个浏览器窗口完成授权后 CLI 会拿到本地凭据。如果你的环境没有浏览器也可以用设备码流程终端会给出一个链接和一个验证码在另一台设备上访问并输入即可。如果不想用官方账号直接在环境变量里配置export OPENAI_API_KEY你的密钥这样 Codex 会自动读取该变量。对我来说直接配了密钥省去 OAuth 的折腾。需要留意的是密钥不要写进 shell 历史或者项目配置文件里最好放在.env或者密钥管理器里。3. 本地大模型接入让 Codex 跑在本地模型上3.1 用 Ollama 部署本地模型Codex 本身不带模型它只负责“干活”。要让 Codex 使用本地模型最省事的方案是 Ollama。Ollama 是一个大模型本地运行框架支持从拉取模型到启动服务的完整闭环而且它会暴露一个 OpenAI 兼容接口端口默认是11434这就让 Codex 可以像对接标准 API 一样对接本地模型。安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh或者 Windows 直接下载安装包。装完启动服务ollama serve然后拉取模型。以我常用的 qwen2.5-coder 为例ollama pull qwen2.5-coder:32b这一步耗时会比较久取决于网络和模型大小。32b 模型光参数文件就十几个 G你机器只有 12GB 显存的话就跑不动 32B 全精度了。我实际选用的是qwen2.5-coder:14b量化后大概 9GB 多一点能塞进显存并且留出上下文空间。经验之谈本地部署大模型不要盲目追求大参数。显存不够导致部分层跑在 CPU 上推理速度会掉到没法用的程度而且大模型还容易超出上下文限制直接报错。先在ollama run里单聊几句确认响应速度和上下文窗口都正常再约到 Codex 里面。3.2 在 Codex 配置里接入本地端点Ollama 就绪后Codex 并不知道它的存在。Codex 的配置需要改config.toml这个文件默认在~/.codex/config.toml。如果没有就手动创建。配置核心思路是新增一个自定义模型提供商指向http://localhost:11434/v1并指定一个模型名称model local/qwen2.5-coder:14b [model_providers.local] name Local Ollama base_url http://localhost:11434/v1 env_key LOCAL_API_KEY wire_api chat如果你愿意也可以不自定义 provider直接把 base_url 指向 Ollama 的/v1路径再设置model为 Ollama 里的模型名。Codex 兼容 OpenAI 的 chat completions 接口所以用wire_api chat这一项即可。env_key表示从环境变量里读取的 API Key 名称。Ollama 默认不校验 Key但 Codex 依然会尝试读取一个值。你可以在 shell 里随便设置一个export LOCAL_API_KEYollama然后在~/.codex/config.toml里指定模型后进入 Codex 交互会话输入!model可以查看当前模型如果显示的是你配置的本地模型名说明已经被正确加载。3.3 本地模型该怎么选这是很多人最容易踩坑的地方。Codex 这种代理型工具对模型的“指令遵循”“工具调用”能力要求很高不是所有本地模型都能胜任。太小参数的模型经常会犯两个毛病看不懂工具调用格式回复的是纯文本而不是结构化动作拆解任务时过于简单几步就走偏。按我的实测7B 级别的量化模型在 Codex 里基本不能用它连“读完文件再修改”这种嵌套指令都容易翻车14B 级别的中端模型能在简单任务里胜任例如改一个函数、补一个测试32B 级别明显更稳能处理跨文件的改动但显存要求水涨船高。这里贴一个我实测过的基础对比表模型参数量显存建议Codex 可用性备注qwen2.5-coder:7b7B8GB低只适合极其简单的任务qwen2.5-coder:14b14B12GB中能处理单文件修改qwen2.5-coder:32b32B24GB高跨文件任务稳定deepseek-coder:33b33B24GB高代码理解强但部署成本高codellama:13b13B12GB中低工具调用格式偶有错误如果你既想保住成本又想提升能力还可以用支持外部 API 的兼容服务把本地模型换成云上的大模型。YAML 配置里把base_url替成对应服务地址model换成对应模型名Codex 照样能用。好处是无需重新安装坏处是又回到了“依赖网络”的状态。这完全看你自己的选择。4. 日常实操与核心环节实现跑通一次真实修复任务4.1 启动 Codex 和两种交互姿势一切就绪后进入一个真实项目目录直接敲codex进入交互模式。此时它会读取当前目录的上下文。如果你想要更明确的工程上下文可以先跑codex 解释这个项目的架构这是单轮模式跑完自动退出适合快速问答。而交互模式下你可以连续发指令Codex 会一边读文件一边处理不断跟你确认下一步。我建议你在已有 git 的项目里测试因为 Codex 会自动看 diff你很容易确认它改了哪些文件。如果没有 git先git init并提交一个初始快照否则改错了想回滚就很麻烦。4.2 掌握审批模式和沙箱Codex 默认不是“直接乱改”模式它会向你请求确认每一步操作。这个设计很关键尤其是当它准备执行有副作用的命令时。启动时可以指定审批级别常用这几个--full-auto全自动不询问适合完全信任的场景--ask每次执行工具前询问适合日常使用--sandbox启用沙箱隔离限制它对系统的访问范围。我在实际操作中喜欢用--ask加--sandbox组合即便偶尔放空了也不会因为一次错误的rm -rf把项目搞坏。沙箱不是万能的Codex 在沙箱里依然能访问项目目录的所有文件只是对项目之外的文件系统访问更受限。4.3 演示一次完整修复流程我手头一个 Python 项目里有个小 bug一个函数在输入为空列表的时候会抛IndexError。我直接在 Codex 里下指令项目里 parse_config 在 config 列表为空时会抛 IndexError帮我修复并补一个单测。Codex 的行动路径大概是先列出项目目录定位parse_config所在文件读取该函数源码理解异常触发点修改函数增加空列表保护找到测试文件补一个空列表的用例运行 pytest 验证确认测试通过。期间它会多次停下来问我是否允许读取某个目录、是否运行 pytest。等它跑完我git diff查看改动基本都是预期代码。这就是一个典型的本地模型闭环工作流理解需求、修改代码、执行验证、汇报结果。要注意一点Codex 在本地模型下跑任务速度感知会跟云端模型不一样。云上模型推理快交互像聊天14B 模型跑一步可能要等十几秒多文件任务可能会有明显等待。这不是故障是本地推理的正常节奏。建议在指令里把需求写得更明确减少来回试错的轮次。5. 常见问题与排查技巧实录5.1 登录不上、组织设置加载不出来遇到codex login之后一直转圈、或者提示“无法加载组织设置”先分两种情况看。一种是网络不通畅这种情况检查域名可达性即可另一种是浏览器授权回调端口被占用或防火墙拦截可以尝试换个网络环境或者干脆用 API Key 方式绕过 OAuth 登录。我自己的经验是如果只是要在本地折腾 CodexAPI Key 方式远比其他登录方式省心因为不依赖浏览器授权流程。设置好OPENAI_API_KEY后Codex 会自动跳过登录步骤。5.2 配置不生效和奇怪的配置告警Codex 在启动时如果检测到config.toml里有它不认识的字段会提示codex is ignoring 1 unrecognized configuration setting. Check for typos or deprecated options.我确实遇到过一次原因是我把某个 provider 的api_key_env_var写错成了env_varCodex 不认识这个字段就直接忽略了结果模型请求一路上没有 key。解决办法是先用codex --version确认版本再去官方文档对照字段名尽量不要靠记忆写配置。另一个隐蔽问题config.toml里如果同时设置了多个 providerCodex 默认只认model字段指向的 provider。你在model_providers里写了半天配置但顶层model没改那一切都不会生效。改完配置后进入交互模式执行!model是最快的验证方式。5.3 模型不支持或报错当你让 Codex 使用某个模型但它明确提示该模型不受支持时通常是模型名不匹配。Codex 有自己的模型白名单哪怕它是一个本地模型名你也必须在model_providers里注册并且顶层model要写成provider名/模型名这种形式。直接填一个裸模型名它可能拿这个去探测官方端点当然会失败。我遇到过类似这样的报错老版本 Codex 会对某些新模型名直接拒绝处理办法是先用一个小模型测试你的 provider 配置是否可用确认连通后再替换模型名避免模型名错误和配置错误混在一起排障。5.4 请求超时和响应缓慢本地模型推理慢是常态但 Codex 侧有默认超时时间。如果你跑的是 32B 大模型一个生成请求经常超过几十秒Codex 就会中断。我的解决方法是尽量启动前热一次模型ollama run qwen2.5-coder:14b 你好让它把权重加载进显存如果还是频繁超时换更小模型或量化版本在 Ollama 侧调整环境变量比如增加空闲时保持模型加载的时间。排查超时问题时建议开两个终端。一个跑 Codex另一个随时用nvidia-smi或者ollama ps观察显存和模型状态这能直观看出到底是模型没加载还是推理卡住了。5.5 Windows 上的特殊问题Windows 桌面版最常见的两个问题一是安装包下完后安装向导卡住通常是系统缺少 VC 运行库二是桌面版登录完成但无法进入主界面可能是因为它内置的 Node 服务和系统代理冲突。我的建议是如果你在 Windows 上工作优先用 WSL 2 Linux 版 Codex很多奇怪问题可以天然绕开。桌面版作为尝鲜可以但做严肃项目还是 CLI 顺手。另外在 Windows 上用 WSL 跑 Ollama 时注意一个坑WSL 默认只会分配部分内存给 Linux如果跑模型经常被系统杀进程去.wslconfig里给memory设一个合适的上限比如 24GB。别把整个物理内存全给 WSLWindows 宿主机也需要余量。6. 一点个人总结和后续扩展思路折腾完这一整套我最大的体会是Codex 的价值不只在“它很聪明”更多是在“它能自己动手”。而本地部署让这种动手能力有了自主可控的底座。你不用再担心项目代码被第三方拿去训练也不用掐着手指算 token 成本。代价是你得自己维护模型、调参、处理环境问题这本质上是在用工程时间换资源和隐私。如果你打算长期用我想额外推荐两个扩展方向。一个是把 Codex 和 Dify 这类工作流平台结合让代理任务可以挂到更大的自动化链条里去另一个是把代码仓库迁移到 Gitea 这类本地托管服务配合 Codex 形成内网可用的研发闭环。我自己已经把本地 Git 仓库的古早项目逐渐迁移到 Gitea 上配合 Codex 用起来非常顺。后续我还会继续尝试给 Codex 配置不同的模型和工具链有值得分享的再单独写一篇。
