1. 为什么我要在本地跑一个 AI 编程助手第一次听说 Codex 能本地部署的时候我正被两件事折磨一是公司内网环境没法稳定调用外部接口二是手头几个老项目的代码涉及业务逻辑不太适合往外部服务上传。那段时间我试过好几个在线 AI 编程工具写个正则、补个单元测试确实快但一到真实项目里就卡壳——要么网络抖动导致请求超时要么上下文长度不够要么就是响应里夹着一堆和当前代码库无关的通用建议。后来我花了一个周末把 Codex 在本地从零搭了起来。整个过程踩了不少坑Docker Desktop 起不来、虚拟化支持没开、模型权重下载到一半断流、CLI 登录一直转圈、配置文件里多了一个不认识的字段导致启动直接报错。但搭好之后那种“断网也能补全代码”的踏实感确实值得。这篇内容就是把我整个搭建过程完整复盘一遍。Codex 本地部署这件事说难不难说简单也不简单——它不像装个普通软件那样一路下一步就行中间涉及容器环境、模型文件、接口配置、CLI 工具链好几个环节。我会从整体思路讲起把每个关键步骤拆开包括我实际用到的命令、参数、配置文件以及那些文档里不会写但实际一定会遇到的坑。适合谁看如果你满足下面任意一条这篇内容应该能帮到你想在自己的机器上跑一个AI 编程助手不依赖外部网络对Docker有一定了解但没试过用它部署 AI 相关服务已经尝试过Codex 安装但卡在某个环节没继续下去想搞清楚本地部署大语言模型到底需要什么硬件和软件条件。我默认你有一台能跑 Docker 的电脑Windows、macOS、Linux 都行但不同系统下有些细节差异我会分别说明。硬件方面后面会给出具体的显存和内存参考值你先不用急着对号入座看完整体设计思路再判断自己的机器能不能扛住。2. 整体部署思路与方案选型2.1 为什么选 Docker 而不是直接装Codex 本地部署有好几种路子直接下载二进制包运行、用 Python 虚拟环境装依赖、或者走 Docker 容器。我三种都试过最后稳定用的是 Docker 方案原因有三个。第一是依赖隔离。Codex 运行时会牵扯到 Python 版本、CUDA 驱动、各种底层库直接装在宿主机上很容易和你现有的开发环境打架。我之前用虚拟环境装过一次结果把系统里的 numpy 版本升上去了另一个项目直接跑不起来。Docker 把这一切封在容器里宿主机上只需要一个 Docker 引擎干净利落。第二是版本管理方便。Codex 更新比较频繁用 Docker 的话拉新镜像、重启容器就行回滚也简单旧镜像留着随时能切回去。直接装的话升级一次可能要重新配一遍环境。第三是跨平台一致。我在 Windows 和 Linux 上都部署过Docker 方案下除了挂载路径写法不同其他步骤几乎一模一样。这对需要多台机器同步环境的人来说省事很多。当然 Docker 方案也有代价镜像体积大、首次拉取慢、容器和宿主机之间的文件挂载需要额外配置。但综合来看对于本地部署大语言模型这类场景Docker 仍然是目前最省心的选择。2.2 硬件门槛到底在哪很多人一上来就问“我这台电脑能不能跑”其实这个问题要拆成两部分看模型推理需要多少资源以及容器本身需要多少资源。模型推理这块主要看显存。Codex 这类编程助手模型参数量从几 B 到几十 B 不等。我实测下来量化后的 7B 级别模型8GB 显存能跑起来但上下文一长就吃力13B 级别建议 16GB 显存起步如果要用更大的模型或者更长的上下文24GB 以上会更从容。没有独立显卡的话纯 CPU 推理也能跑但速度会慢很多补全一个函数可能要等十几秒体验大打折扣。内存方面容器本身加上模型加载建议至少 16GB 系统内存32GB 会更稳。硬盘空间要留足模型文件动辄几个 GB 到几十 GB加上 Docker 镜像和缓存建议预留 50GB 以上。这里给一个我实际用过的配置参考表方便你对照使用场景显存系统内存硬盘预留体验预期轻量补全、短上下文8GB16GB50GB可用长代码会卡日常开发辅助16GB32GB80GB流畅推荐配置大模型、长上下文24GB64GB150GB接近在线服务体验纯 CPU 推理无要求32GB50GB能跑速度慢注意显存不是唯一指标显卡的计算能力也很关键。同样是 8GB 显存不同代际的卡跑同一个模型速度可能差好几倍。选卡的时候别只看显存大小。2.3 网络与存储的前置准备本地部署虽然叫“本地”但下载镜像和模型文件这一步还是需要网络的。我的建议是提前把该下的都下好后面断网也能用。镜像方面Codex 的官方镜像在主流容器仓库都能找到拉取的时候注意选对标签别默认拉 latest因为 latest 有时候会指向开发版稳定性不如固定版本号。模型文件一般从模型托管平台下载文件大的话建议用支持断点续传的工具别用浏览器直接下断一次就得重来。存储路径也要提前规划。Docker 默认把镜像和数据放在系统盘如果系统盘空间紧张最好在安装 Docker 之后先把数据目录改到大容量硬盘上。这个操作在 Docker Desktop 的设置里能改Linux 下则是改 daemon.json 配置。我一开始没注意结果系统盘被镜像撑满折腾了半天才迁移过去。3. Docker 环境搭建与避坑要点3.1 Docker Desktop 安装的正确姿势Windows 和 macOS 用户一般用 Docker DesktopLinux 用户可以直接装 Docker Engine。这里重点说 Docker Desktop因为踩坑最多。Windows 下安装 Docker Desktop第一个拦路虎就是虚拟化支持。很多人装完启动会看到 “virtualization support not detected” 或者 “docker desktop failed to start because virtualisation support wasnt detected” 这类提示。这不是 Docker 的问题是主板 BIOS 里的虚拟化功能没开。重启进 BIOS找到 Intel VT-x 或者 AMD-V 选项设为 Enabled保存重启就行。不同主板菜单位置不一样实在找不到就搜自己主板型号加“开启虚拟化”。第二个坑是 WSL2。Windows 版 Docker Desktop 默认用 WSL2 作为后端如果系统里没装 WSL2或者 WSL 版本太旧Docker 也起不来。解决办法是先在 PowerShell 里运行wsl --update再运行wsl --set-default-version 2然后重启 Docker Desktop。macOS 下相对简单下载 dmg 拖进应用文件夹就行。但要注意芯片架构M 系列芯片和 Intel 芯片要选对应的安装包装错了虽然能运行但性能会受影响。Linux 下我推荐用官方脚本安装比手动配源省事curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER最后一行是把当前用户加入 docker 组这样后面运行 docker 命令不用每次都加 sudo。执行完要重新登录一次才生效。3.2 安装后必做的三项检查Docker 装完别急着往下走先做三个检查能省掉后面很多麻烦。第一确认 Docker 服务正常运行docker version docker infodocker version能看到客户端和服务端版本信息docker info能看到容器数量、存储驱动、内存限制等。如果docker info报错说连不上守护进程说明服务没起来Windows 下检查 Docker Desktop 是否在运行Linux 下检查systemctl status docker。第二确认能正常拉取镜像docker pull hello-world docker run hello-world这一步是验证网络和镜像仓库配置。如果拉取很慢或者超时可以配置镜像加速地址。国内用户这一步基本都要配不然拉个大镜像能等到怀疑人生。第三确认存储路径和空间docker system df这个命令能看到镜像、容器、数据卷占用的空间。如果发现默认路径在系统盘且空间不足趁现在还没拉大镜像赶紧改数据目录。3.3 镜像加速与数据目录迁移镜像加速的配置Windows 和 macOS 在 Docker Desktop 的设置里找 Docker Engine编辑 JSON 配置Linux 下编辑/etc/docker/daemon.json。加的内容类似这样{ registry-mirrors: [ https://your-mirror-address ] }改完重启 Docker 服务生效。具体用哪个加速地址各平台不一样选一个稳定可靠的就行。数据目录迁移Docker Desktop 在设置里有 Disk image location 选项直接改路径然后 Apply它会自动迁移已有数据。Linux 下稍微麻烦点要先停 Docker 服务把/var/lib/docker整个目录移到新位置再改 daemon.json 里的>docker pull codex:1.x.x-cuda拉取过程中如果中断重新执行同一条命令会续传不用从头来。但如果换了标签就得重新拉。拉完用docker images确认一下看看镜像大小是否正常。CUDA 版本的镜像通常好几个 GBCPU 版本小一些。如果大小明显不对可能是拉到了错误的标签。4.2 启动容器的参数怎么配启动 Codex 容器核心是把端口、数据目录、模型路径这几样映射好。我实际用的命令大概是这样docker run -d \ --name codex \ --gpus all \ -p 8080:8080 \ -v /path/to/models:/models \ -v /path/to/data:/data \ -e MODEL_PATH/models/codex-model \ -e API_PORT8080 \ codex:1.x.x-cuda逐项说明一下--gpus all是让容器能用宿主机的 GPU纯 CPU 环境去掉这行-p 8080:8080把容器端口映射到宿主机后面 CLI 和接口都走这个端口-v挂载模型目录和数据目录这样模型文件不用打进镜像更新模型也方便-e设置环境变量指定模型路径和监听端口。这里有个细节模型路径一定要和挂载路径对应上。比如你把模型放在宿主机的/data/models/codex挂载到容器里的/models那MODEL_PATH就要写容器内的路径不是宿主机的。我第一次配的时候就是这里搞混了容器一直报找不到模型文件。4.3 启动后怎么确认服务正常容器起来之后用docker logs codex看日志。正常的话会看到模型加载进度加载完会提示服务已监听某个端口。如果日志里出现 “codex is ignoring 1 unrecognized configuration setting” 这类提示说明配置文件里有不认识的字段一般是版本不匹配导致的检查一下配置文件和镜像版本是否对应。再用docker ps确认容器状态是 Up不是 Restarting 或者 Exited。如果是 Restarting多半是启动参数有问题看日志找具体报错。最后在宿主机上测一下端口通不通curl http://localhost:8080/health返回正常状态码就说明服务起来了。这一步很关键别跳过后面 CLI 连不上很多时候就是服务本身没起好。5. Codex CLI 安装与登录配置5.1 CLI 安装的几种方式Codex CLI 是跟本地服务交互的主要工具安装方式看你的系统。macOS 和 Linux 下可以用包管理器Windows 下推荐用官方安装包或者包管理工具。以常见的安装方式为例# macOS brew install codex-cli # Linux curl -fsSL https://example.com/codex-cli/install.sh | sh # Windows winget install codex-cli装完运行codex --version确认。如果提示命令找不到检查一下 PATH 有没有配好或者重新开一个终端窗口。这里提醒一句CLI 版本最好和容器里的服务版本匹配。版本差太多的话接口协议可能对不上会出现连上了但请求一直失败的情况。我遇到过 CLI 比服务新一个大版本结果登录一直转圈降级到匹配版本就正常了。5.2 登录与接口对接CLI 装好后第一步是配置它连到本地服务。默认它可能指向在线地址要改成http://localhost:8080。配置方式一般是改配置文件或者用命令行参数。配置文件通常在用户目录下的.codex/config或者类似路径内容大概长这样{ endpoint: http://localhost:8080, api_key: local-key, model: codex-model }api_key本地部署一般随便填一个或者用服务启动时生成的。model要和服务端加载的模型名一致。配好之后运行codex login或者codex auth如果配置正确会提示登录成功。如果卡住不动先检查服务是否在运行再检查端口和地址有没有写错。我遇到过一次 “cc switch local proxy failed while handling codex endpoint /responses” 的报错排查下来是本地代理配置和 CLI 的 endpoint 冲突了把代理关掉或者改 endpoint 就解决了。5.3 首次使用的基础验证登录成功后别急着上真实项目先用一个简单请求验证整条链路。比如让 Codex 补全一个函数codex complete 写一个 Python 函数计算斐波那契数列如果返回了合理的代码说明服务、CLI、模型三者都通了。如果返回空或者报错按下面顺序排查服务是否在运行docker ps端口是否通curl http://localhost:8080/healthCLI 配置是否正确检查 endpoint 和 model模型是否加载完成看容器日志。这个验证步骤看起来简单但能帮你快速定位问题出在哪一层比直接上复杂请求高效得多。6. 常见报错与排查速查6.1 启动阶段的典型问题启动阶段的问题八成集中在 Docker 环境和容器参数上。我把遇到过的和社区里常见的整理成表报错信息可能原因解决方向virtualization support not detectedBIOS 虚拟化未开启进 BIOS 开启 VT-x/AMD-Vdocker desktop failed to startWSL2 未安装或版本旧更新 WSL2 并设为默认容器一直 Restarting启动参数错误或模型路径不对看 docker logs 定位端口被占用8080 已被其他程序使用换端口或停掉占用程序模型加载失败模型文件损坏或路径错误校验文件、检查挂载路径端口占用这个问题特别常见因为 8080 是个热门端口。换端口的话-p参数和 CLI 配置里的 endpoint 都要改别只改一个。6.2 运行阶段的接口与配置问题运行阶段的问题多半和配置、版本、网络有关。几个高频的“codex is ignoring 1 unrecognized configuration setting”配置文件里有当前版本不认识的字段。要么删掉那个字段要么升级到支持该字段的版本。我一般选择删字段因为升级可能引入新问题。“cc switch local proxy failed while handling codex endpoint /responses”本地代理和 CLI 的 endpoint 冲突。检查系统代理设置或者把 CLI 的 endpoint 改成不走代理的地址。“codex 无法加载组织设置”这个一般出现在登录环节本地部署下多半是 api_key 或 endpoint 配错了。重新检查配置文件确认服务地址和密钥。请求超时模型太大、显存不够、或者上下文太长。先缩短请求内容试试如果短请求正常那就是资源问题考虑换小模型或者加显存。6.3 我踩过的三个真实坑第一个坑是模型文件下载不完整。我用浏览器下了一个十几 GB 的模型文件下到 99% 断了重新下又从头开始。后来改用支持断点续传的工具并且下完校验了文件哈希才确保没问题。模型文件不完整的话容器启动时可能不报错但推理结果会乱七八糟很难排查。第二个坑是 Docker 数据目录在系统盘。我一开始没改拉了几个大镜像之后系统盘直接满了Docker 各种异常。迁移数据目录花了半个多小时早知道一开始就配好。第三个坑是 CLI 和服务版本不匹配。我图省事装了最新版 CLI结果和服务端的接口协议对不上登录一直失败。后来查了版本对应关系装了匹配的版本一次就通了。所以版本这块别盲目追新匹配最重要。提示遇到问题先看日志docker logs和 CLI 的详细输出能解决八成问题。别一上来就重装重装往往解决不了配置层面的问题。7. 性能调优与日常维护7.1 让推理速度再快一点服务跑起来之后如果觉得速度不够理想有几个方向可以调。首先是量化。模型量化能显著降低显存占用和提升推理速度代价是精度略有下降。对于编程补全这类任务适度量化对结果影响不大。常见的量化等级有 8bit、4bit显存紧张就上 4bit显存够就 8bit。其次是批处理和并发。如果你是一个人用默认配置一般够如果团队共用要调大并发数但注意并发上去之后显存占用也会涨别调过头把服务搞崩。第三是上下文长度。上下文越长推理越慢显存占用也越大。日常补全用不到特别长的上下文适当调小能明显提速。我一般设成 4096 或 8192够用且快。7.2 日常维护的几件事本地部署不是一劳永逸日常有几件事要定期做。定期清理无用镜像和容器docker system prune能清掉停止的容器、无用镜像和缓存。但注意别把正在用的镜像清了加-a参数要谨慎。监控资源占用docker stats能实时看容器的 CPU、内存、GPU 占用。如果发现内存持续上涨可能是内存泄漏重启容器能缓解长期要看是不是版本问题。备份配置文件CLI 配置、容器启动参数、模型路径这些建议记在一个文档里。换机器或者重装的时候照着文档走一遍就行不用重新摸索。关注版本更新Codex 更新比较频繁新版本可能修复了旧版本的 bug也可能引入新特性。但别一有更新就升等一两个小版本稳定了再升或者先在测试环境验证。7.3 扩展玩法接入其他模型与工具Codex 本地部署好之后其实不只能当编程助手用。它的接口是通用的可以对接其他工具。比如接入 DeepSeek 这类模型只要模型格式兼容改一下MODEL_PATH和配置就能切换。我试过用同一套容器环境跑不同的模型切换成本很低。再比如和本地知识库结合把项目文档、代码规范喂进去让 Codex 生成更贴合项目风格的代码。这个需要额外配置检索模块但思路是通的。还有就是把 Codex 的接口接到编辑器插件里实现类似在线服务的补全体验。主流编辑器基本都支持自定义接口地址配一下就能用。这些扩展玩法我还在陆续尝试后面有新的心得再单独整理。本地部署最大的好处就是可控想怎么折腾都行不用担心调用次数和隐私问题。最后分享一个小技巧如果你在 Windows 上部署容器和宿主机之间的文件挂载性能可能不太理想尤其是大量小文件读写的时候。我的做法是把模型和数据都放在 WSL2 的文件系统里而不是 Windows 的 NTFS 分区速度会快不少。这个细节文档里一般不写但实际用起来差别挺明显的。