1. 为什么我要在本地折腾一个 AI 编程助手第一次听说 Codex 能本地跑的时候我其实是持怀疑态度的。毕竟过去两年我试过的绝大多数 AI 编程工具都是云端方案——响应快、模型强但有两个问题始终绕不开一是代码隐私公司内部项目根本不敢往云端传二是网络抖动赶上高峰期延迟能飙到十几秒补全一个函数等得人想砸键盘。直到我在几个开源社区看到有人把 Codex 跑在本地 Docker 里配合本地大模型做推理才意识到这条路是真的能走通的。Codex 本质上是一个 AI 编程助手的客户端框架它负责把你的代码上下文、编辑指令、对话历史打包成模型能理解的请求再把模型返回的结果解析成可用的代码补全、重构建议或者解释说明。它本身不绑定某个特定模型你可以把它理解成一个翻译官——左边连着你的编辑器右边连着任意一个兼容接口的大模型服务。这个特性决定了它天然适合本地部署模型跑在你自己的机器上Codex 只做协议转换和交互层数据不出内网。那本地部署到底解决了什么问题我总结下来是三个数据主权、响应确定性、成本可控。数据主权不用多说代码是公司的核心资产能不出本机就不出本机。响应确定性指的是没有网络波动本地推理延迟稳定在几百毫秒到几秒之间取决于你的显卡。成本可控则是长期账——云端 API 按 token 计费重度使用一个月几百块很正常而本地部署一次性投入硬件之后边际成本几乎为零。这篇文章适合谁看如果你是有一定命令行基础的后端或全栈开发者想给自己搭一个不依赖外部服务的编程助手那这篇内容就是为你写的。如果你完全没碰过 Docker也没关系我会把每一步拆到能直接复制粘贴的程度。但我要提前说清楚本地部署不是一键安装包中间会遇到显卡驱动、容器网络、模型加载各种坑你得有折腾的心理准备。2. 部署前的整体设计与选型思路2.1 为什么选 Docker 而不是裸机安装Codex 的官方安装方式其实有两种一种是直接在本机装二进制包另一种是走 Docker 容器。我两种都试过最后坚定地选了 Docker原因有三个。第一是依赖隔离。Codex 运行时会依赖特定版本的 Node.js、Python 运行时以及一些系统库。如果你本机已经装了其他项目需要的不同版本裸机安装很容易出现版本冲突。我有个朋友就是本机 Node 18 和 Codex 要求的 Node 20 打架折腾了一下午才搞定。Docker 把所有这些依赖封在容器里跟宿主机完全隔离你本机装什么版本都不影响。第二是环境可复现。Docker 的镜像和 compose 文件就是一份完整的环境说明书。你在这台机器上跑通了换一台机器只要把 compose 文件拷过去一条命令就能拉起一模一样的环境。这对团队协作特别有用——不用再写在我机器上是好的这种废话。第三是清理方便。本地部署最怕的就是装了一堆东西最后不用了卸载还卸不干净。Docker 的好处是不想要了直接docker compose down -v容器、网络、卷全部清掉宿主机干干净净。当然 Docker 也不是没缺点。最大的问题是GPU 透传。如果你要用显卡加速推理需要装 NVIDIA Container Toolkit还得确认驱动版本匹配。这一步是新手最容易卡住的地方后面我会专门讲。2.2 模型选型本地大模型怎么挑Codex 本身不带模型你得自己准备一个推理后端。目前本地部署最主流的选择是 Ollama 或者 vLLM前者适合个人开发者后者适合有服务器资源的团队。模型方面DeepSeek 系列、Qwen 系列都是编程能力比较强的选择。选模型的时候要看三个指标参数量、量化等级、显存占用。参数量决定能力上限7B 的模型写简单函数没问题但复杂重构就力不从心32B 以上的模型编程能力明显更强但对显存要求也高。量化等级是在精度和显存之间做权衡Q4 量化能把显存占用压到 FP16 的四分之一左右精度损失在编程任务上基本感知不到。我整理了一个简单的对照表方便你根据自己的硬件选模型规模推荐量化显存需求适用场景7BQ4_K_M6-8GB代码补全、简单问答14BQ4_K_M10-12GB函数级重构、注释生成32BQ4_K_M20-24GB模块级重构、架构建议70BQ4_K_M40GB复杂项目理解、多文件修改如果你只有一张 8GB 显存的消费级显卡7B 或 14B 量化版是现实的选择。如果你用的是 Apple Silicon 的 Mac统一内存架构反而有优势32GB 内存的 M 系列芯片能跑 14B 甚至 32B 量化模型速度也还能接受。2.3 网络与端口规划本地部署还有一个容易被忽略的点端口冲突。Codex 默认监听某个端口Ollama 默认监听 11434如果你本机还跑着其他服务很容易撞车。我的习惯是在部署前先用netstat或者lsof查一遍常用端口把要用的端口规划好写进 compose 文件。另外如果你打算让局域网内其他机器也能访问这个 Codex 服务需要把容器端口映射到0.0.0.0而不是127.0.0.1。但这里有个安全提醒不要把这个端口直接暴露到公网本地服务就让它待在本地需要远程访问的话走内网或者加一层认证。3. 核心细节解析与实操要点3.1 Docker 环境准备别跳过这一步很多人部署失败问题都出在 Docker 环境本身没装好。我见过太多人直接docker run然后报一堆错最后发现是 Docker Desktop 根本没启动成功。Windows 用户注意Docker Desktop 依赖 WSL2 或者 Hyper-V。安装的时候如果提示 virtualization support not detected说明你主板的虚拟化技术在 BIOS 里没开。重启进 BIOS找到 Intel VT-x 或者 AMD-V 选项打开就行。这个坑我踩过当时以为是软件问题折腾半天才发现是 BIOS 设置。装完 Docker Desktop 之后一定要验证三件事# 1. 确认 Docker 守护进程在跑 docker info # 2. 确认能拉取镜像 docker pull hello-world # 3. 确认 compose 插件可用 docker compose version这三条命令都通过才说明环境没问题。如果docker info报 Cannot connect to the Docker daemonWindows 上通常是 Docker Desktop 没启动Linux 上是 docker 服务没起sudo systemctl start docker即可。3.2 GPU 支持配置NVIDIA 用户的必经之路如果你要用 NVIDIA 显卡加速推理光装 Docker 还不够还得装NVIDIA Container Toolkit。这一步的作用是让容器能访问宿主机的 GPU。Linux 上的安装步骤大致是这样# 添加 NVIDIA 容器工具包的软件源 distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list # 安装并重启 Docker sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker装完之后用这条命令验证docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi如果能看到显卡信息输出说明 GPU 透传配置成功。如果报错 could not select device driver说明 toolkit 没装好或者 Docker 没重启。Windows 上的情况稍微复杂一点。Docker Desktop 的 WSL2 后端对 GPU 的支持需要较新版本的驱动而且不是所有显卡都支持。我的建议是如果你在 Windows 上折腾 GPU 透传超过一小时还没搞定先退回到 CPU 推理把整个流程跑通再回头解决 GPU 问题。CPU 推理慢是慢但至少能验证 Codex 本身是能工作的。3.3 Codex 配置文件的几个关键项Codex 的配置通常是一个 JSON 或者 TOML 文件里面有几个参数直接决定它能不能正常工作。模型接口地址是最关键的。如果你用 Ollama 做后端地址通常是http://host.docker.internal:11434。注意这里不能用localhost因为容器里的 localhost 指的是容器自己不是宿主机。host.docker.internal是 Docker 提供的一个特殊域名专门用来从容器访问宿主机。Linux 上这个域名默认不生效需要在 compose 文件里加extra_hosts配置。模型名称要和你在 Ollama 里拉取的模型名完全一致。比如你ollama pull deepseek-coder:6.7b配置里就得写deepseek-coder:6.7b少一个字符都会报模型找不到。超时时间建议调大一点。本地推理首次加载模型可能要几十秒默认超时往往不够。我一般设成 120 秒起步模型大的话设 300 秒。还有一个容易忽略的配置是context window。Codex 会把你的代码上下文发给模型上下文越长模型能理解的代码范围越大但显存占用也越高。7B 模型建议设 4096 到 819232B 模型可以设到 16384。设太大反而会因为显存不足导致推理失败。4. 完整实操流程从零到跑通4.1 第一步拉起本地模型服务我以 Ollama 为例因为它的安装和模型管理最简单。Docker 方式启动 Ollamadocker run -d \ --name ollama \ --gpus all \ -p 11434:11434 \ -v ollama_data:/root/.ollama \ ollama/ollama这里-v ollama_data:/root/.ollama是把模型文件持久化到 Docker 卷里这样容器删了模型不用重新下载。--gpus all是启用 GPU如果你用 CPU 推理就去掉这个参数。容器起来之后进容器拉模型docker exec -it ollama ollama pull deepseek-coder:6.7b下载时间取决于你的网速6.7B 的量化模型大概 4GB 左右。下载完成后验证一下curl http://localhost:11434/api/generate -d { model: deepseek-coder:6.7b, prompt: 写一个 Python 快速排序, stream: false }如果返回了排序代码说明模型服务正常。4.2 第二步部署 Codex 容器Codex 的部署我推荐用 docker compose因为要配置的东西比较多写成文件比一长串命令行参数清晰得多。version: 3.8 services: codex: image: codex:latest container_name: codex ports: - 8080:8080 environment: - MODEL_ENDPOINThttp://host.docker.internal:11434 - MODEL_NAMEdeepseek-coder:6.7b - TIMEOUT120 - CONTEXT_WINDOW8192 extra_hosts: - host.docker.internal:host-gateway restart: unless-stoppedextra_hosts那行是给 Linux 用户准备的让容器能解析host.docker.internal。Windows 和 Mac 的 Docker Desktop 自带这个解析但加上也不会有副作用。启动docker compose up -d docker compose logs -f codex看日志里有没有报错。常见的错误是连不上模型服务这时候检查 Ollama 容器是不是在跑端口是不是通的。4.3 第三步验证端到端链路容器都起来之后用 curl 测一下 Codex 的接口curl -X POST http://localhost:8080/v1/completions \ -H Content-Type: application/json \ -d { prompt: def fibonacci(n):, max_tokens: 100 }如果返回了补全的代码恭喜你整条链路通了。如果报错看 Codex 的日志通常是模型地址配错或者模型名不对。这一步跑通之后你就可以把 Codex 接到编辑器插件里了。大多数编辑器插件支持配置自定义的 API 端点把地址填成http://localhost:8080就行。4.4 参数调优让推理更快更稳跑通只是第一步用起来爽才是目的。本地推理有几个参数值得调num_ctx控制上下文长度前面说过按显存来设。num_gpu控制有多少层跑在 GPU 上如果你的显存不够跑完整模型可以设成部分层数剩下的跑 CPU速度会慢但至少能跑。temperature控制输出的随机性写代码建议设 0.2 左右太低会死板太高会胡编。Ollama 的这些参数可以在 Modelfile 里设也可以在请求时传。我一般是在 Modelfile 里设好默认值特殊场景再在请求里覆盖。5. 常见问题与排查技巧实录5.1 容器启动失败排查表现象可能原因排查方法容器起不来日志空白镜像没拉全docker images看镜像是否存在报端口被占用端口冲突lsof -i:8080查占用进程报 GPU 不可用toolkit 没装或驱动不匹配nvidia-smi看宿主机能否识别显卡连不上模型服务网络配置错误进容器curl模型地址测试模型加载超时显存不足或模型太大换小模型或降低量化等级5.2 几个我踩过的坑第一个坑是 Docker Desktop 的 WSL2 内存限制。Windows 上 Docker Desktop 默认只给 WSL2 分配一半物理内存如果你有 32GB 内存WSL2 只能用 16GB。跑大模型的时候会 OOM。解决办法是在用户目录下建一个.wslconfig文件手动指定内存上限[wsl2] memory24GB swap8GB改完wsl --shutdown重启 WSL 生效。第二个坑是模型名大小写。Ollama 的模型名是大小写敏感的DeepSeek-Coder和deepseek-coder是两个不同的东西。我因为这个排查了半小时最后发现就是大小写问题。第三个坑是防火墙。Windows 上第一次启动 Docker 容器映射端口时防火墙会弹窗询问是否允许。如果你手快点了拒绝后面怎么都连不上。去防火墙设置里手动放行对应端口就行。第四个坑是磁盘空间。模型文件动辄几个 GBDocker 镜像也不小再加上容器日志很容易把系统盘塞满。建议把 Docker 的数据目录迁到空间大的盘上或者定期docker system prune清理。5.3 性能不达预期的调优思路如果你觉得推理速度慢按这个顺序排查先看 GPU 利用率。nvidia-smi如果显示 GPU 利用率很低说明模型大部分层跑在 CPU 上需要调整num_gpu参数。再看显存占用如果显存快满了说明模型太大或者上下文设太长需要降配。最后看是不是首次加载慢模型第一次加载到显存需要时间之后的请求会快很多。CPU 推理的话速度主要取决于内存带宽和核心数。DDR5 比 DDR4 快不少核心数多的 CPU 也有优势。但说实话CPU 推理跑 7B 模型生成速度大概每秒几个 token写代码补全勉强够用复杂任务还是建议上 GPU。6. 本地部署之后的使用心得跑通本地 Codex 之后我用了大概两个月有几个真实体会想分享。第一本地部署的体验和云端差距在缩小但还没到无感的程度。7B 量化模型在代码补全这种短任务上响应速度和云端差不多但遇到需要理解大段代码的重构任务本地模型的能力明显弱一截。我的做法是分工日常补全用本地复杂重构还是切回云端。第二硬件投入要理性。我一开始想着一步到位上 32B 模型结果发现 24GB 显存的卡价格不菲而且功耗和散热都是问题。后来退回到 14B 量化日常够用电费也友好。建议先用手头的硬件跑起来确认工作流真的用得上再考虑升级。第三维护成本不能忽略。本地服务不是装完就一劳永逸Docker 镜像要更新模型要升级偶尔还会遇到容器起不来的情况。如果你只是想偶尔用一下 AI 编程助手云端方案其实更省心。本地部署适合的是那种每天都要用、对数据敏感、愿意花时间维护的开发者。最后分享一个我常用的小技巧把 Codex 和 Ollama 的启动命令写成一个 shell 脚本开机自动拉起。这样你打开电脑就能用不用每次手动敲命令。脚本里加个健康检查服务没起来就自动重启省心不少。