1. 为什么要在本地跑一个 AI 编程助手先把话说在前头Codex 这类 AI 编程助手云端版本用起来确实省事但只要你真正在团队里推过一轮就会遇到几个绕不开的问题。第一是代码隐私很多公司的核心业务代码是不允许往外部服务上传的哪怕只是片段补全合规那边也过不去。第二是网络稳定性云端接口一旦抖动你正写到关键逻辑补全突然卡住那种体验非常割裂。第三是成本团队规模一上来按调用量计费的开销会变得很难预测。本地部署的核心价值就在这三个点上代码不出内网、响应延迟可控、长期成本固定。Codex 的本地部署本质上是把模型推理服务跑在你自己的机器或者内网服务器上再通过一个客户端CLI 或者编辑器插件去调用它。听起来简单但真正动手的时候你会发现坑主要集中在环境准备和依赖管理上尤其是 Docker 这一层。这篇文章面向的是有一定命令行基础、想在自己机器上把 Codex 跑起来的开发者。不管你用的是 Windows、macOS 还是 Linux思路是通的区别只在一些系统层面的细节。我会把整个流程拆成可复现的步骤同时把每一步为什么这么做讲清楚避免你照着敲完却不知道出问题该往哪查。需要提前说明的是本地部署对硬件是有门槛的。模型参数量决定了显存需求7B 级别的模型量化后大概需要 6 到 8GB 显存13B 级别建议 12GB 以上再大的模型消费级显卡基本就别想了。如果你手头只有集成显卡也不是完全没戏CPU 推理能跑但速度会让你怀疑人生只适合做功能验证不适合日常开发使用。2. 部署前的环境盘点与硬件账本2.1 先算清楚你的机器能不能扛很多人一上来就装 Docker、拉镜像结果跑到一半发现显存不够白折腾。所以第一步不是装软件是算账。下面这张表是我根据实际跑下来的经验整理的供你对照自己的机器模型规模量化方式最低显存推荐显存内存建议适用场景1.5BINT42GB4GB8GB轻量补全、语法提示7BINT46GB8GB16GB日常代码补全、注释生成7BFP1614GB16GB32GB高质量补全13BINT410GB12GB32GB复杂逻辑生成34BINT420GB24GB64GB接近云端体验这张表里的数字是保守估计实际占用会因为推理框架、上下文长度、并发数而浮动。上下文越长KV Cache 占用越大这一点在长文件补全时特别明显。我建议你按推荐显存那一列来准备留出余量否则跑起来之后稍微加点上下文就爆显存。如果你用的是 Apple Silicon 的 Mac情况稍微特殊一点。M 系列芯片是统一内存架构显存和内存共享所以 16GB 内存的 Mac 大概能跑 7B INT432GB 能跑 13B INT4。好处是不用单独买显卡坏处是推理速度和同价位的独立显卡比还是有差距尤其是首 token 延迟。2.2 操作系统层面的前置检查在装 Docker 之前有几个系统层面的东西必须先确认否则后面 Docker 起不来你还得回头补。Windows 用户重点看两件事一是虚拟化有没有在 BIOS 里打开二是 WSL2 有没有装好。Docker Desktop 在 Windows 上依赖 WSL2 或者 Hyper-V如果虚拟化没开你会看到 virtualization support not detected 这类报错Docker Desktop 直接启动失败。检查方法很简单任务管理器里看性能标签页CPU 那一栏如果有虚拟化已启用就没问题。没启用的话进 BIOS 打开不同主板位置不一样一般在 Advanced 或者 CPU Configuration 里面。macOS 用户相对省心Docker Desktop 装好基本就能用但要注意芯片架构。M 系列是 arm64Intel 是 x86_64拉镜像的时候要确认镜像支持你的架构否则会跑在模拟层上性能打折。Linux 用户最自由但也最容易踩权限的坑。Docker 默认需要 root 权限每次敲命令都要 sudo 很烦正确做法是把当前用户加进 docker 用户组sudo usermod -aG docker $USER执行完要重新登录才生效。这一步很多人漏掉然后一直用 sudo 跑后面挂载目录的时候就会出现权限混乱容器里写的文件宿主机读不了或者反过来。2.3 Docker 安装的版本选择Docker 现在分 Docker Desktop 和 Docker Engine 两条线。桌面版带图形界面适合 Windows 和 macOSEngine 是纯命令行适合 Linux 服务器。如果你是在自己的开发机上折腾桌面版更省事如果是往内网服务器上部署用 Engine。安装包去官网下就行注意选对系统版本。Windows 上装的时候会问你要不要用 WSL2 后端建议选 WSL2比 Hyper-V 性能好文件系统交互也顺畅。装完之后在终端敲docker --version docker compose version两个命令都能正常输出版本号说明基础环境 OK。这里提醒一句Docker Compose 现在是 v2 版本命令是docker compose中间是空格不是老的docker-compose中间是横杠。网上很多老教程还在用横杠写法你照着敲会报 command not found别慌换成空格就行。3. 拉取镜像与容器编排的实操细节3.1 镜像源的选择与拉取策略环境准备好之后下一步是拉镜像。Codex 本地部署通常涉及两类镜像一类是推理服务本身的镜像一类是配套的依赖服务比如向量数据库、缓存之类的。具体用哪个镜像取决于你选的推理框架常见的有基于 vLLM 的、基于 Ollama 的、基于 llama.cpp 的各有取舍。vLLM 吞吐高适合多人共用但对显存要求高配置也复杂Ollama 上手最快一条命令就能跑适合个人开发者llama.cpp 最省资源CPU 也能跑但速度一般。我个人建议第一次部署先用 Ollama 跑通流程确认整条链路没问题再根据实际需求换更重的方案。拉镜像的时候如果发现速度慢可以配置镜像加速。在 Docker Desktop 的设置里找到 Docker Engine编辑配置文件加上 registry-mirrors 字段。Linux 用户改/etc/docker/daemon.json改完重启 Docker 服务sudo systemctl restart docker这里有个经验镜像加速地址不是越多越好配一两个稳定的就行配太多反而会因为轮询导致拉取不稳定。另外拉大镜像的时候建议用docker pull单独拉别在docker compose up的时候一起拉因为 compose 拉取失败的回滚处理不如单独拉清晰出问题不好定位。3.2 用 Compose 编排多容器服务Codex 本地部署很少是单容器通常至少有一个推理服务容器可能还有一个反向代理或者管理界面。用 Docker Compose 编排是最清晰的方式。下面是一个典型的 compose 文件结构我做了简化你可以根据自己的镜像调整services: codex-inference: image: your-inference-image:latest container_name: codex-inference ports: - 8000:8000 volumes: - ./models:/app/models - ./config:/app/config environment: - MODEL_PATH/app/models/your-model - CONTEXT_LENGTH8192 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] restart: unless-stopped几个关键点解释一下。volumes把模型目录挂进容器这样模型文件不用打进镜像镜像体积小换模型也方便。environment里的CONTEXT_LENGTH控制上下文长度这个值直接决定显存占用别一上来就拉满先设小一点跑通再调。deploy.resources那段是 GPU 透传配置NVIDIA 显卡需要装 nvidia-container-toolkit否则容器里看不到 GPU。restart: unless-stopped这个策略很实用机器重启或者容器意外退出时会自动拉起省得你每次手动启动。但要注意如果容器本身配置有问题一直崩溃这个策略会导致无限重启日志刷得飞快。排查阶段可以先设成no确认稳定了再改回来。3.3 GPU 透传最容易卡住的一环GPU 透传是本地部署里翻车率最高的环节我单独拿出来讲。Linux 上需要三步装 NVIDIA 驱动、装 nvidia-container-toolkit、配置 Docker runtime。驱动装好之后用nvidia-smi验证能看到显卡信息就对了。然后装 toolkitsudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker配置完之后跑一个测试容器验证docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi如果这个命令能输出显卡信息说明透传成功。如果报错说找不到 GPU八成是 toolkit 没配好或者 Docker 服务没重启。Windows 上的 GPU 透传走的是 WSL2需要确保 WSL2 里的 CUDA 驱动是通的。Docker Desktop 的设置里有个Use the WSL 2 based engine勾上之后WSL2 发行版里能跑nvidia-smiDocker 容器里一般就能用。这里有个坑Windows 的显卡驱动和 WSL2 里的 CUDA 驱动是两套东西别搞混WSL2 里不需要单独装显卡驱动它直接用 Windows 的。4. 配置 Codex 客户端并打通调用链路4.1 客户端安装与配置文件定位推理服务跑起来之后接下来是让 Codex 客户端连上它。Codex 的客户端形态有 CLI 和编辑器插件两种CLI 更适合脚本化和调试插件更适合日常开发。安装方式根据你用的形态不同CLI 一般是通过包管理器装插件是在编辑器里搜扩展。装完之后第一件事是找配置文件。不同系统的位置不一样系统配置文件路径Windows%USERPROFILE%\.codex\configmacOS~/.codex/configLinux~/.codex/config配置文件通常是 JSON 或者 TOML 格式核心是告诉客户端去哪里找推理服务。一个典型的配置长这样{ endpoint: http://localhost:8000/v1, model: your-model-name, apiKey: local-key, maxTokens: 2048, temperature: 0.2 }endpoint指向你本地推理服务的地址model要和推理服务加载的模型名对上对不上会报模型不存在的错。apiKey本地部署其实用不上但有些客户端强制要求填随便填一个非空字符串就行。temperature建议设低一点代码生成场景不需要太高的随机性0.1 到 0.3 之间比较合适。4.2 那个让人头大的 local proxy 报错部署过程中有一个报错特别常见就是 cc switch local proxy failed while handling codex endpoint /responses。这个报错的意思是客户端在切换本地代理的时候处理/responses这个接口失败了。根因通常有三个一是推理服务根本没起来端口不通二是 endpoint 地址写错了比如多写了或者少写了/v1三是代理配置和直连配置冲突了。排查顺序我建议这样走。先用 curl 直接打推理服务的健康检查接口curl http://localhost:8000/v1/models如果这个命令返回模型列表说明服务是好的问题在客户端配置。如果连不上说明服务没起来去看容器日志docker logs codex-inference --tail 100日志里通常能看到具体原因比如模型加载失败、显存不足、端口被占用。端口占用这个特别隐蔽如果你之前跑过别的服务占了 8000新容器起不来但也不报明显错误换个端口就行。如果服务是好的那大概率是 endpoint 配置问题。注意/v1这个后缀有些推理服务的 API 路径带/v1有些不带配置的时候要和实际接口对齐。你可以用 curl 分别试http://localhost:8000/v1/models和http://localhost:8000/models哪个通用哪个。4.3 验证整条链路是否通畅配置改完之后别急着在编辑器里用先用 CLI 做一次端到端验证。跑一个最简单的补全请求看能不能拿到返回。如果 CLI 能通插件基本也能通如果 CLI 不通插件那边报错信息更模糊不好排查。验证的时候注意观察首 token 延迟和整体生成速度。首 token 延迟高通常是模型加载或者显存交换的问题整体速度慢可能是上下文太长或者并发太高。这两个指标是你后续调优的基准记下来。还有一个容易忽略的点客户端的超时设置。本地推理如果模型大、硬件弱单次请求可能要几十秒客户端默认超时可能只有 30 秒会导致请求被中断。配置文件里如果有 timeout 字段调大一点比如 120 秒。5. 性能调优与常见故障的排查链路5.1 让推理速度提上来的几个开关跑通之后接下来是让它跑得快。本地推理的性能瓶颈主要在显存带宽和计算单元利用率上调优的方向也就围绕这两点。第一是量化。FP16 精度最高但最吃显存INT8 能省一半显存INT4 再省一半但质量会下降。代码生成场景对精度其实没那么敏感INT4 通常够用我实测下来 INT4 和 FP16 在补全质量上的差距日常开发基本感知不到但显存占用差了一倍这个取舍很划算。第二是批处理。如果你是一个人用批处理意义不大如果是团队共用开启连续批处理能显著提升吞吐。vLLM 在这方面做得比较好Ollama 相对弱一些。第三是上下文长度。这个是最容易被忽视的显存杀手。上下文从 4096 拉到 8192KV Cache 占用翻倍。如果你的实际使用场景不需要那么长的上下文就别开那么大。我一般建议从 4096 起步不够再加。第四是 GPU 层数。llama.cpp 这类框架支持把部分层放到 GPU、部分放 CPU显存不够的时候可以调这个参数把一部分层卸载到 CPU 内存。代价是速度下降但至少能跑起来。5.2 一份按症状索引的排查表本地部署的报错五花八门但归类下来就那么几类。我整理了一张按症状查原因的表你遇到问题可以直接对号入座症状可能原因排查动作容器起不来秒退配置错误、端口占用docker logs看退出原因容器起来了但接口不通端口映射错、服务未就绪curl健康检查接口报显存不足模型太大、上下文太长降量化、减上下文推理极慢跑在 CPU 上、显存交换nvidia-smi看 GPU 利用率客户端连不上endpoint 错、代理冲突检查配置文件和网络生成结果乱码模型文件损坏、编码问题重新下载模型、检查编码请求超时客户端超时太短调大 timeout这张表覆盖了我遇到过的绝大多数情况。排查的核心思路是分层定位先确认容器状态再确认服务接口最后确认客户端配置。一层一层往下查别跳步跳步容易误判。5.3 几个我踩过的坑和对应的解法第一个坑是模型文件下载不完整。大模型动辄几个 G下载中断是常事但有些下载工具不会校验完整性文件看着在加载的时候才报错。解法是下载完做一次哈希校验或者用支持断点续传的工具重新拉一遍。第二个坑是 Docker 的磁盘占用。镜像、容器、卷加起来很占空间跑一段时间磁盘就满了然后各种奇怪报错。定期清理docker system prune -a这个命令会删掉所有没在用的镜像和容器执行前确认一下没有你需要保留的东西。模型文件如果挂在宿主机目录不受影响。第三个坑是 WSL2 的内存占用。Windows 上 WSL2 默认会吃掉大量内存跑大模型的时候宿主机可能卡死。可以在用户目录下建一个.wslconfig文件限制内存[wsl2] memory32GB swap8GB数值根据你机器的实际内存调整一般给 WSL2 分配总内存的一半到三分之二比较合适。第四个坑是配置文件里的拼写错误。有个报错叫 codex is ignoring 1 unrecognized configuration setting意思是配置文件里有个字段它不认识被忽略了。这种报错不致命但说明你的配置没完全生效可能是字段名拼错了或者版本不匹配。对着官方文档核对一遍字段名别想当然。6. 把它变成日常可用的开发工具6.1 接入编辑器的实际体验CLI 跑通只是第一步真正提升效率的是把它接进编辑器。Codex 的编辑器插件装好之后需要在插件设置里指向本地服务地址。配置项和 CLI 类似endpoint、model、apiKey 三件套。接进去之后你会明显感觉到和云端版本的差异。本地版本的首 token 延迟取决于你的硬件好的显卡能压到几百毫秒差的可能两三秒。这个延迟在写代码的时候是能感知的尤其是你习惯了云端秒回之后。我的建议是把补全触发方式调成手动触发而不是自动触发这样不会因为频繁请求拖慢编辑器。另一个体验点是上下文理解。本地模型如果参数量小对长文件的理解能力会弱一些补全的时候可能抓不住整个文件的上下文。这时候可以通过在文件顶部加注释的方式把关键信息喂给它提升补全准确率。6.2 多模型切换与场景适配本地部署的一个好处是你可以同时跑多个模型针对不同场景切换。比如补全用一个小的快模型代码解释和重构用一个大的慢模型。配置上可以通过多个 endpoint 或者同一个服务的不同模型名来实现。切换的方式取决于客户端支持程度。有些客户端支持在配置里定义多个 profile一键切换有些需要手动改配置文件。如果客户端不支持可以写个简单的脚本改完配置重启客户端。这里有个实用技巧把不同模型的配置存成不同的文件切换的时候用软链接或者复制覆盖。虽然土但管用比每次手改配置快得多。6.3 长期运行的维护要点本地服务跑起来之后维护是个长期的事。几个要点记一下。日志要定期看。容器日志默认会一直累积时间长了占满磁盘。可以在 compose 里配置日志轮转logging: driver: json-file options: max-size: 10m max-file: 3模型更新要有计划。新模型出来想换别直接覆盖先拉新的镜像和模型文件用不同端口跑起来验证确认没问题再切流量。直接覆盖的话出问题回滚很麻烦。资源监控要跟上。nvidia-smi看显存和 GPU 利用率docker stats看容器资源占用。发现显存持续高位可能是上下文泄漏或者并发没控制好早点处理别等崩了再查。备份配置。配置文件、compose 文件、模型清单这些加起来不大但重建的时候能省你半天时间。丢进 git 仓库管理起来改了什么一目了然。我在实际使用中最大的体会是本地部署的难点不在装而在调。装的过程照着文档走基本能通但调优和排错需要你对整个链路有清晰的认识知道每一层在干什么出问题该往哪看。这套东西一旦跑顺了日常开发的体验是很舒服的代码不出内网响应稳定成本可控值得花时间折腾一次。