1. 为什么要在本地跑 Codex从云端依赖到自主可控Codex 这个名字这两年重新回到开发者视野里含义已经和早年的代码补全模型不太一样了。现在大家说的 Codex更多是指一类能理解自然语言、直接生成可运行代码、还能在终端里跟你对话式改代码的 AI 编程助手。它可以是官方 CLI 工具也可以是接入 DeepSeek、本地大模型后自己搭出来的一套东西。核心诉求就一个让写代码这件事从“我查文档、我拼 API、我调 bug”变成“我说需求、它给实现、我来验收”。那为什么非要本地部署我自己的经历很直接。最早用云端 API图的是省事注册完拿个 key 就能跑。但用久了问题就冒出来第一网络抖动的时候请求超时正写到关键逻辑突然断掉心态很崩第二代码里涉及公司内部接口、数据库连接串、业务规则往云端一贴合规上过不去第三按 token 计费调试阶段反复试错账单涨得比进度快。这三点加起来本地部署就从“可选项”变成了“必选项”。本地部署 Codex 的本质是在你自己的机器上跑一个推理服务再让 Codex 的客户端去连这个服务。推理服务可以是 Ollama、vLLM、LM Studio 这类工具加载的开源模型也可以是 DeepSeek 这类支持本地化部署的模型。客户端这边Codex CLI 负责接收你的自然语言指令转成请求发给本地服务拿到结果后再呈现给你。整条链路都在本机或者内网里完成数据不出门断网也能用成本从“按量付费”变成“一次性投入硬件”。适合谁来参考这套方案三类人最合适。第一类是有一定开发经验、想提升编码效率但又不放心把代码传出去的工程师第二类是手里有闲置显卡或者想配一台开发机的技术爱好者第三类是在团队里负责搭建内部工具、想让整个组都用上 AI 辅助但又受限于合规要求的负责人。如果你只是偶尔写几行脚本云端免费额度可能就够了没必要折腾本地。但只要你的代码有保密要求、或者你每天都要和 AI 结对编程本地部署的投入产出比会非常高。这里要先说清楚一个前提Codex 本身是一个客户端工具它不包含模型。你要么连官方服务要么连自己部署的模型服务。所谓“Codex 本地部署”准确说是“Codex 客户端 本地模型服务”的组合。理解了这一点后面的安装和配置就不会迷路。2. 部署前的整体设计与选型思路2.1 三种典型部署形态对比在动手之前先想清楚你要走哪条路。我把常见的方案归成三类各自的适用场景和门槛差别很大。方案类型模型运行位置硬件要求数据是否出本机适合人群纯云端 API厂商服务器无是临时试用、无保密需求本地模型 Codex CLI本机显卡 8G 显存起步否个人开发者、小团队内网服务器 多客户端内网服务器服务器级显卡否仅在内网团队协作、合规要求高纯云端方案不展开重点说后两种。本地模型加 Codex CLI 是最常见的个人玩法一台带独显的机器就能跑。内网服务器方案则是把模型服务部署在一台性能较强的机器上其他同事通过内网地址连接适合团队统一管理模型版本和访问权限。选哪种取决于三个问题你的代码能不能出本机你的硬件够不够你是不是一个人用三个问题答案清楚了方案自然就定了。2.2 模型选型的核心考量模型是整套方案里最影响体验的部分。选模型不能只看参数规模要看四个维度代码能力、显存占用、推理速度、中文支持。代码能力方面DeepSeek 系列在代码生成和补全上的表现比较均衡对 Python、JavaScript、Go 这些主流语言支持都不错。如果你主要写某一种语言可以优先选在该语言上表现突出的模型。显存占用方面7B 级别的模型量化后大概需要 6 到 8G 显存14B 级别需要 12 到 16G32B 级别就要 24G 以上了。推理速度方面同样的模型量化等级越低速度越快但质量会下降需要权衡。中文支持这一点经常被忽略。很多开源模型英文能力很强但中文注释、中文需求描述理解起来会打折扣。如果你习惯用中文写注释、用中文描述需求选模型时一定要实际测一下中文场景。提示不要一上来就追求最大参数。先用 7B 或 14B 跑通全流程确认链路没问题、体验能接受再考虑换更大的模型。直接上大模型一旦显存不够或者速度太慢排查起来很浪费时间。2.3 容器化部署的价值用 Docker 来跑模型服务和相关组件是我强烈推荐的做法。原因有三个。第一环境隔离。模型推理依赖的 CUDA 版本、Python 版本、各种库版本很容易冲突容器把这些问题封在里面不污染宿主机。第二迁移方便。换机器的时候把镜像和配置一搬环境就重建了不用重新踩一遍依赖的坑。第三版本管理清晰。不同模型用不同容器互不干扰想回退就回退。Docker Desktop 在 Windows 和 macOS 上都能用Linux 上直接用 Docker Engine 就行。安装过程不复杂但有几个坑后面会专门讲。3. 环境准备与 Docker 安装实操3.1 硬件与系统检查清单动手之前先确认你的机器满足基本条件。这一步花五分钟能省后面几小时的折腾。操作系统Windows 10/11 64 位、macOS 12 以上、或者主流 Linux 发行版内存至少 16G推荐 32G 以上显卡NVIDIA 显卡显存 8G 起步跑 7B 量化模型推荐 12G 以上硬盘至少预留 50G 空间模型文件动辄几个 G 到几十个 G虚拟化BIOS 里要开启虚拟化支持Windows 上还要确认 Hyper-V 或 WSL2 可用显卡这块多说一句。如果你用的是 NVIDIA 显卡先装好驱动用nvidia-smi命令确认能正常输出。这个命令会显示显卡型号、驱动版本、CUDA 版本和显存占用。如果这个命令报错后面所有 GPU 加速都无从谈起先把驱动搞定。3.2 Docker Desktop 安装与常见报错处理Windows 上装 Docker Desktop去官网下载安装包双击运行一路下一步。安装完成后重启启动 Docker Desktop等托盘图标变成稳定状态。这里有个高频报错virtualization support not detected或者docker desktop failed to start because virtualization support is not enabled。这个问题的根源是虚拟化没开。解决办法是进 BIOS找到 Intel VT-x 或者 AMD-V 选项设为 Enabled。不同主板 BIOS 界面不一样但关键词就这几个。开完保存重启再启动 Docker Desktop 就好了。另一个常见问题是 WSL2 相关。Windows 上 Docker Desktop 默认用 WSL2 作为后端如果 WSL2 没装或者版本太旧会报错。解决办法是打开 PowerShell运行wsl --update更新然后wsl --set-default-version 2设为默认版本。如果还没装 WSL运行wsl --install会自动装好。macOS 上装 Docker Desktop 相对简单下载 dmg 拖进应用文件夹就行。但要注意macOS 上 Docker 跑 GPU 加速比较麻烦Apple Silicon 芯片可以用 Metal 加速Intel 芯片基本只能靠 CPU速度会慢不少。所以 macOS 用户如果追求速度建议把模型服务放在别的机器上本机只跑客户端。Linux 上直接用包管理器装 Docker Engine 和 Docker Compose 插件就行不装 Desktop。以 Ubuntu 为例先更新源再装 docker.io 和 docker-compose-plugin然后把当前用户加入 docker 组避免每次都要 sudo。安装完成后用docker run hello-world验证。能正常输出一段欢迎信息说明 Docker 装好了。3.3 Docker 基础配置优化装好之后别急着跑模型先做几项配置优化后面会顺很多。第一配置镜像加速。默认的镜像源在国内拉取速度可能很慢编辑 Docker 的配置文件加上国内可用的镜像地址重启 Docker 服务后拉取速度会明显提升。第二调整资源限制。Docker Desktop 默认给容器的内存和 CPU 可能不够跑模型在设置里把内存调到 8G 以上CPU 核心数给足。如果要用 GPU还要确认 GPU 支持已开启。第三设置数据目录。模型文件很大默认存在系统盘可能把盘撑满。在 Docker 设置里把磁盘镜像位置改到大容量分区。注意修改 Docker 配置后一定要重启 Docker 服务否则配置不生效。重启后可以用docker info查看当前配置是否已经应用。4. 本地模型服务的部署与 Codex 对接4.1 用 Docker 拉起模型推理服务模型推理服务我习惯用 Ollama 来跑它对 Docker 支持好模型管理也方便。先拉取 Ollama 的镜像然后运行容器把模型存储目录挂载到宿主机这样模型文件不会随容器删除而丢失。docker run -d \ --name ollama \ --gpus all \ -v /your/path/ollama:/root/.ollama \ -p 11434:11434 \ ollama/ollama--gpus all是让容器能用上宿主机的 GPU前提是宿主机装好了 NVIDIA 驱动和容器工具包。-v把模型目录挂出来-p把端口映射出来后面 Codex 就连这个端口。容器起来后进容器拉模型docker exec -it ollama ollama pull deepseek-coder:6.7b模型大小不同拉取时间从几分钟到几十分钟不等。拉完后用ollama list确认模型已经在本地。4.2 验证模型服务是否正常模型拉好后先别急着接 Codex单独测一下服务通不通。curl http://localhost:11434/api/generate -d { model: deepseek-coder:6.7b, prompt: 写一个 Python 函数判断一个数是否为质数, stream: false }如果返回一段包含代码的 JSON说明模型服务正常。如果报连接错误检查容器是否在运行、端口是否映射正确。如果返回很慢或者卡住可能是显存不够模型加载失败去看容器日志docker logs ollama排查。这一步很关键。很多人跳过验证直接配 Codex结果 Codex 报错分不清是模型服务的问题还是客户端配置的问题。先把模型服务单独验证通过后面排查范围就小一半。4.3 Codex 客户端安装与配置Codex CLI 的安装方式取决于你用的具体工具。如果是官方 CLI通常通过包管理器安装比如 npm 全局安装或者下载二进制包。安装完成后核心是配置它去连本地的模型服务而不是官方云端。配置文件一般是一个 JSON 或者 YAML 文件放在用户目录下。关键配置项包括模型服务的地址指向http://localhost:11434、模型名称和你在 Ollama 里拉的一致、API 格式Ollama 兼容 OpenAI 的接口格式。把这几项配对Codex 就能把请求发到本地模型服务。配置完成后在终端里运行 Codex输入一句自然语言指令比如“帮我写一个读取 CSV 并统计每列缺失值的脚本”看它能不能正常返回代码。如果能整条链路就通了。4.4 接入 DeepSeek 等模型的注意事项如果你不想用 Ollama想直接部署 DeepSeek 的模型思路类似但要注意几点。第一DeepSeek 官方提供了多种规格的模型选适合你显存的版本。第二推理框架可以用 vLLM它对大模型推理做了优化吞吐量比朴素加载高不少但配置稍复杂。第三接口格式要对齐Codex 期望的是 OpenAI 兼容格式vLLM 和 Ollama 都支持但要在启动参数里显式开启。提示不同推理框架的接口路径可能不一样。Ollama 的生成接口是/api/generateOpenAI 兼容接口是/v1/chat/completions。Codex 配置时要用兼容接口不要用原生接口否则会报 404。5. 常见问题排查与避坑经验5.1 连接类问题速查现象可能原因排查方法Codex 报连接被拒绝模型服务没启动或端口不对docker ps看容器状态curl测端口请求超时模型太大推理太慢换小模型或降低量化等级返回 404接口路径配错确认用的是 OpenAI 兼容路径返回 401鉴权配置问题本地服务一般不需要 key检查是否误配连接类问题占了我踩坑经历的一大半。最典型的是端口映射写错容器内部端口和宿主机端口没对上。还有就是容器启动了但模型没加载完这时候请求会挂起看起来像超时其实是模型还在加载。等几分钟再试或者看容器日志确认加载进度。5.2 显存与性能问题处理显存不够是最常见的性能问题。表现是模型加载失败或者推理过程中报 CUDA out of memory。解决办法有几个换更小的模型、用量化版本、减少并发请求数、关闭其他占显存的程序。量化版本值得单独说。同一个模型有 fp16、int8、int4 等不同量化等级。int4 量化后显存占用能降到 fp16 的四分之一左右速度也更快但生成质量会有一定下降。对于代码补全这种任务int4 量化通常够用实测下来代码结构基本正确偶尔细节需要人工修正。如果显存实在不够可以考虑 CPU 推理。速度会慢很多但至少能跑起来。Ollama 支持 CPU 模式去掉--gpus all参数就行。适合应急或者对速度要求不高的场景。5.3 中文与特殊字符处理中文场景下有两个坑。第一模型对中文需求描述的理解可能不如英文建议关键需求用英文写或者中英混合。第二终端编码问题Windows 上默认编码可能是 GBK中文输出会乱码。解决办法是在终端里设置 UTF-8 编码或者用支持 UTF-8 的终端工具。还有一个容易被忽略的点代码里的特殊字符。比如路径里的反斜杠、正则表达式里的转义字符在传给模型和从模型返回的过程中可能被转义处理。如果生成的代码里有奇怪的转义检查一下客户端的转义配置。5.4 我的实操避坑清单先验证模型服务再配客户端顺序不能反模型存储目录一定要挂载到宿主机否则容器一删模型就没了Docker 资源限制要调够默认配置跑模型基本不够用量化模型是显存不够时的首选方案不要硬上大模型终端编码设成 UTF-8省去中文乱码的麻烦配置文件改完要重启 Codex 客户端热加载不一定生效保留一份能跑通的配置备份折腾坏了能快速回滚6. 从跑通到好用进阶优化与扩展思路6.1 提升响应速度的几个手段跑通之后下一步是让它更快。第一个手段是模型预热服务启动后先发一个简单请求让模型加载进显存后续请求就不用等加载了。第二个手段是调整推理参数比如限制最大生成长度、调低 temperature都能减少推理时间。第三个手段是用更快的推理框架vLLM 的连续批处理和 PagedAttention 对吞吐量提升明显。还有一个容易被忽略的点客户端和服务器的网络延迟。如果模型服务在另一台机器上内网延迟通常可以忽略但如果是跨网络访问延迟就会体现出来。尽量让客户端和模型服务在同一台机器或者同一内网。6.2 多模型切换与场景适配不同任务适合不同模型。写业务代码可以用通用代码模型写 SQL 可以用专门优化过 SQL 的模型写前端可以用对 JavaScript 和 CSS 支持好的模型。Ollama 支持同时拉多个模型Codex 配置里可以指定用哪个。切换的时候改一下配置里的模型名称就行。如果频繁切换可以写个小脚本一键改配置并重启客户端。或者用环境变量控制启动 Codex 时指定模型名称不用改配置文件。6.3 团队共享部署的注意事项如果要把这套方案分享给团队用有几个点要注意。第一模型服务部署在一台性能足够的机器上其他同事通过内网 IP 连接。第二做好访问控制虽然在内网但也不能完全裸奔至少加个简单的鉴权。第三统一模型版本避免每个人用的模型不一样导致生成结果差异大。第四写好使用文档把连接地址、配置方法、常见问题整理清楚减少重复答疑。团队部署的硬件投入会比个人高但摊到每个人头上成本就低了。而且模型版本统一后代码风格和生成质量也更一致协作起来更顺。6.4 后续可以扩展的方向这套方案跑通后还能往上叠不少东西。比如接入代码库索引让模型能理解你整个项目的结构生成的代码更贴合现有风格。比如加一层缓存相同或相似的请求直接返回缓存结果省去重复推理。比如对接 CI 流程在提交代码前自动跑一遍 AI 审查。我个人最看好的扩展方向是项目上下文注入。现在的模型大多是单轮对话你给它一段需求它生成一段代码但它不知道你项目里已经有哪些工具类、用了什么框架、命名规范是什么。如果把项目结构、关键文件摘要作为上下文一起传给模型生成质量会有质的提升。这个方向实现起来不难但效果很明显值得试试。最后分享一个小技巧把常用的提示词模板存成文件用的时候直接引用不用每次重新组织语言。比如“生成单元测试”“重构这段代码”“解释这段逻辑”各存一个模板效率能再提一截。这套东西搭好之后我自己的编码节奏明显变了重复性的代码基本交给它我专注在架构和业务逻辑上整体产出比之前高了不少。