1. 为什么要在本地跑一个 AI 编程助手先把话说在前头Codex 这类 AI 编程助手云端版本用起来确实省事但只要你真正在项目里深度用过一段时间就会碰到几个绕不开的痛点。第一是代码隐私公司的业务代码、内部的接口定义、数据库表结构这些东西你未必放心往云端传第二是网络稳定性高峰期响应慢、偶尔超时写代码写到一半助手卡住那种体验非常割裂第三是成本按量计费的模式在重度使用下账单会悄悄涨上去。这三点叠加起来本地部署就成了很多团队和个人开发者的刚需。所谓本地部署说白了就是把模型推理服务和 Codex 的调用链路都放在你自己的机器或者内网服务器上数据不出本地响应走局域网成本变成一次性的硬件投入。听起来很美好但真正动手你会发现坑主要集中在两个地方一是运行环境的准备尤其是 Docker 这一层二是 Codex 客户端和服务端之间的对接配置。我见过太多人卡在virtualization support not detected或者cc switch local proxy failed while handling codex endpoint /responses这类报错上折腾一整天都没跑起来。这篇内容就是把这套流程从头到尾捋一遍。我会假设你是一个有一定开发基础、但没怎么碰过容器和本地模型部署的人从 Docker 的安装讲起到模型服务的拉起再到 Codex 的下载、安装、配置和联调每一步都告诉你为什么这么做、容易在哪里翻车。适合谁看想给自己搭一套私有 AI 编程助手的独立开发者、需要在内网环境跑代码助手的小团队、以及单纯想搞明白本地大模型部署这套链路的技术爱好者。读完你应该能独立完成一次完整的部署并且知道出问题时该往哪个方向排查。2. Docker 环境准备那些让人抓狂的启动报错2.1 为什么本地部署几乎绕不开 Docker很多人第一反应是我直接下载个模型文件用 Python 跑起来不就行了为什么要多套一层 Docker这个疑问很合理。直接跑当然可以但你会很快遇到依赖地狱模型推理框架对 Python 版本、CUDA 版本、各种底层库的版本要求极其苛刻你机器上原有的环境很可能和它冲突。Docker 的价值就在于把这些依赖全部打包进一个隔离的容器里容器内是容器内的世界和你宿主机的环境互不干扰。另一个现实原因是现在主流的本地模型服务方案比如 Ollama、各种推理后端官方推荐的部署方式基本都是容器化的。你用 Docker 拉起一个服务端口映射好Codex 那边配置一个本地地址就能连上整个链路非常干净。而且容器删掉重建的成本极低试错起来没有心理负担。所以哪怕你以前没怎么用过 Docker为了这套部署花点时间把它搞明白是值得的。2.2 Windows 上安装 Docker Desktop 的完整路径Windows 用户是踩坑的重灾区我重点讲。首先去 Docker 官网下载 Docker Desktop 的安装包注意选对版本Windows 一般就是 x86_64 的那个。下载完直接双击安装安装过程本身没什么难度一路下一步就行。真正的问题出在安装完之后启动的那一刻。如果你看到Docker Desktop failed to start because virtualization support wasnt detected这个报错别慌这不是 Docker 装坏了而是你的系统没有开启硬件虚拟化。Docker Desktop 在 Windows 上依赖 WSL2 或者 Hyper-V而这两者都需要 CPU 的虚拟化支持。解决办法分两步第一步进 BIOS找到Intel Virtualization Technology或者SVM ModeAMD 平台叫这个把它设成 Enabled。不同主板 BIOS 界面差别很大一般在 Advanced 或者 CPU Configuration 菜单下面。第二步回到 Windows打开启用或关闭 Windows 功能确认虚拟机平台和适用于 Linux 的 Windows 子系统这两个选项都勾上了然后重启。重启之后如果 Docker Desktop 还是起不来大概率是 WSL2 的内核没更新。这时候去微软官网下载 WSL2 的 Linux 内核更新包装完再试。我个人的经验是Windows 上这套流程走完九成以上的启动问题都能解决。剩下那一成通常是系统版本太老Windows 10 需要 2004 版本以上才支持 WSL2这种情况只能先升级系统。2.3 验证 Docker 是否真正可用装完之后别急着往下走先验证一下。打开终端敲docker --version docker run hello-world第一条命令看版本号能正常输出说明命令行工具装好了。第二条命令是拉一个测试镜像跑一下如果能看到Hello from Docker!这行字说明 Docker 引擎、镜像拉取、容器运行这条链路全通了。这一步非常重要因为后面所有的部署都建立在这个基础之上如果这里就有问题后面只会更乱。提示国内拉取镜像有时候会比较慢如果hello-world卡在拉取阶段可以配置一下镜像加速地址。在 Docker Desktop 的设置里找到 Docker Engine编辑配置文件加上 registry-mirrors 字段即可。具体地址这里不展开选一个稳定可用的就行。2.4 一个容易被忽略的磁盘与内存配置Docker Desktop 默认给 WSL2 分配的资源是动态的但在跑大模型的时候这个默认值往往不够。模型文件动辄几个 G 到几十个 G内存占用也高。建议在 Docker Desktop 的 Settings 里找到 Resources 那一栏把内存调到至少 8G如果机器有 32G 内存给到 16G 更稳妥。磁盘镜像的位置也建议改到空间充足的盘符默认放在 C 盘的话跑几个模型下来 C 盘很容易爆红。这个配置看起来是小事但我见过不少人模型跑到一半容器被 OOM kill 掉排查半天以为是模型问题最后发现是 Docker 分配的内存不够。提前把资源给足能省掉很多莫名其妙的故障。3. 本地模型服务的选型与拉起3.1 Ollama 还是其他方案怎么选本地跑模型目前对新手最友好的方案是 Ollama。它的定位有点像本地模型界的 Docker一条命令就能把模型拉下来跑起来屏蔽了底层的各种复杂性。你只需要ollama pull加模型名然后ollama run就能对话服务默认监听在 11434 端口提供一个兼容的 API 接口Codex 这类客户端可以直接对接。当然也有别的选择比如直接用推理框架自己搭服务灵活度更高但配置成本也高得多。对于我要一个能用的 AI 编程助手这个目标来说Ollama 是性价比最高的起点。等你把整套链路跑通了再考虑换更专业的推理后端也不迟。选型的核心逻辑就是先用最低的成本把流程打通验证可行性再逐步优化。3.2 用 Docker 拉起 Ollama 服务虽然 Ollama 有直接安装的版本但既然我们前面已经把 Docker 准备好了用容器跑会更干净。命令大概是这样docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama拆解一下这条命令。-d是后台运行不占用你的终端。-v ollama:/root/.ollama是把容器内的模型存储目录挂载到一个命名卷上这样容器删了重建下载好的模型还在不用重新拉。-p 11434:11434是端口映射把容器内的 11434 端口映射到宿主机的同名端口这样你本机就能通过localhost:11434访问到服务。--name ollama给容器起个名字方便后续管理。跑起来之后用docker ps看一眼容器状态确认是 Up 的。然后拉一个模型比如docker exec -it ollama ollama pull deepseek-coder这里选模型有个讲究。编程助手场景下代码能力强的模型优先参数量不用一味求大。7B 到 14B 这个区间的代码模型在消费级显卡或者纯 CPU 上都能跑响应速度也还能接受。参数量太大的模型除非你有专业显卡否则推理速度会让你等到怀疑人生。3.3 模型拉取慢和失败的应对拉模型这一步是另一个高频卡点。模型文件大网络波动一下就可能中断。如果ollama pull卡住不动先别急着 CtrlC等几分钟看看是不是在慢慢下。如果确实失败了重新执行一次 pull 命令Ollama 支持断点续传已经下好的部分不会重来。如果反复失败检查一下磁盘空间模型动辄几个 G空间不够会直接报错。另外容器内的存储如果没做挂载模型会存在容器里容器一删就没了这也是前面强调要挂载卷的原因。我一般会预留至少 50G 的空间给模型存储跑两三个模型完全够用。3.4 验证模型服务是否正常响应模型拉好之后验证一下服务能不能正常出结果curl http://localhost:11434/api/generate -d { model: deepseek-coder, prompt: 写一个 Python 快速排序, stream: false }如果返回的 JSON 里有正常的代码内容说明模型服务这条链路完全通了。这一步是整个部署的地基地基稳了后面 Codex 的对接才有意义。如果这里返回错误先解决模型服务的问题别急着往下走。4. Codex 的下载、安装与客户端配置4.1 从官网获取安装包的注意事项Codex 的安装包从官网下载是最稳妥的渠道别去各种第三方站点下版本混乱不说还可能夹带东西。官网下载页面会区分操作系统Windows 用户注意选桌面版别下成命令行版或者别的平台的包。下载之前先确认一下你的系统架构现在大部分是 x64少数新机器是 ARM 架构下错了装不上。安装包拿到手之后Windows 上一般是个 exe 或者 msi双击安装即可。安装路径建议不要放在中文目录下虽然现在大部分软件对中文路径支持已经不错了但涉及模型加载、配置文件读取这类操作英文路径能避免很多玄学问题。这是我踩过坑之后的习惯能省事就省事。4.2 安装过程中的常见拦截Windows 上装这类工具最常见的拦截是 SmartScreen 弹窗提示Windows 已保护你的电脑。这不是病毒是因为这个安装包没有微软的签名或者签名较新。点更多信息然后仍要运行就行。如果公司电脑有安全策略限制可能装不了这种情况要么找 IT 开权限要么换个人设备折腾。另一个坑是杀毒软件误报。有些安全软件对这类工具比较敏感安装过程中会把某些文件隔离掉导致装完打不开。如果遇到装完启动没反应先去杀毒软件的隔离区看看有没有被拦的文件有的话恢复并加白名单。4.3 首次启动的登录与初始化Codex 首次启动一般会要求登录。这里要区分清楚登录是为了账号体系和使用统计和你后面配置本地模型服务是两回事。如果你打算完全走本地链路登录之后在设置里把模型来源切换到本地或者自定义接口。有些版本会提示无法加载组织设置这个报错通常和网络或者账号权限有关如果只是个人使用忽略它继续配置本地模型即可不影响核心功能。初始化的过程中软件可能会让你选默认模型、设置工作目录这些。工作目录建议选一个你专门用来测试的项目文件夹别一上来就指向重要的生产代码库等确认整套流程稳定了再扩大使用范围。4.4 配置文件的位置与结构Codex 的配置一般放在用户目录下的一个隐藏文件夹里Windows 上是%USERPROFILE%\.codex这样的路径macOS 和 Linux 上是~/.codex。里面通常有一个主配置文件格式可能是 JSON 或者 TOML。这个文件是后面接入本地模型的关键你需要在这里告诉 Codex别去连云端了去连我本地的服务。配置项一般包括模型提供方、接口地址、模型名称、API Key本地服务通常随便填一个占位符就行。具体字段名不同版本可能有差异以你装的那个版本的文档为准。改配置之前先备份一份原文件改坏了能快速回滚这个习惯能救你很多次。5. 打通 Codex 与本地模型的对接链路5.1 接口地址到底该填什么这是最容易出错的地方。你的模型服务跑在 Docker 容器里端口映射到了宿主机的 11434。那么 Codex 作为宿主机上的程序应该访问http://localhost:11434或者http://127.0.0.1:11434。注意不是容器内部的地址也不是容器的 IP因为 Codex 不在容器网络里它走的是宿主机的端口映射。如果你把 Codex 也放进了容器那情况就不一样了得用 Docker 的网络别名或者宿主机地址。但绝大多数情况下Codex 是装在宿主机上的桌面程序所以填 localhost 就对了。这个细节看起来简单但cc switch local proxy failed while handling codex endpoint /responses这类报错十有八九就是地址填错或者服务没起来导致的。5.2 那个让人头大的 proxy failed 报错怎么破cc switch local proxy failed while handling codex endpoint /responses这个报错信息翻译过来就是Codex 在往/responses这个接口发请求的时候本地代理转发失败了。拆解一下可能的原因按排查优先级排排查项具体检查方法常见结果模型服务是否在跑docker ps看容器状态容器没起来或已退出端口是否通curl http://localhost:11434连接被拒绝接口路径是否匹配对照模型服务的 API 文档路径写错比如多了或少了一层模型名称是否正确看配置里的 model 字段名字和实际拉取的模型对不上请求格式是否兼容看服务端日志字段结构不匹配我遇到这个报错最多的情况是模型服务其实没起来或者起来了但 Codex 配置里写的模型名和实际拉下来的不一致。先确认服务活着再确认名字对得上基本能解决大半。如果服务活着、名字也对那就要看接口协议了有些模型服务的 API 路径和 Codex 期望的不完全一致可能需要在中间加一层转换或者调整配置里的接口路径。5.3 模型不被支持时的处理思路有时候你会看到类似某个模型在 Codex 下不被支持的提示。这通常是因为 Codex 对模型的能力有要求比如需要支持特定的对话格式或者工具调用能力。遇到这种情况换一个兼容性更好的模型往往比死磕配置更快。代码类模型里主流的几个开源模型兼容性都不错选一个社区里被验证过能配合 Codex 使用的能少走很多弯路。如果非要用某个特定模型那就得看它的 API 是否兼容 OpenAI 的接口格式。兼容的话把 Codex 的接口地址指向它就行不兼容的话可能需要在中间搭一个适配层把请求格式转一下。这个工作量就大了除非有特殊需求否则不建议新手一上来就搞这个。5.4 联调成功的验证方法配置改完重启 Codex然后在对话框里输入一个简单的编程问题比如用 Python 写一个读取 CSV 并统计行数的脚本。如果几秒到几十秒内取决于你的硬件返回了合理的代码恭喜你整条链路通了。如果一直转圈或者报错回到上一节的排查表一项一项过。联调成功之后建议做一次压力测试连续问几个问题看看响应是否稳定会不会中途断掉。本地部署的稳定性受硬件影响很大跑几个问题就能大致摸清你这套配置的脾气。6. 部署完成后的调优与日常维护6.1 响应速度的优化方向本地模型跑起来之后很多人第一反应是怎么这么慢。这很正常消费级硬件和云端集群的算力差距摆在那。优化方向有几个一是换更小的模型参数量降下来速度立竿见影二是确认有没有用上 GPU 加速如果机器有独立显卡让推理走 GPU 比纯 CPU 快好几倍三是调整推理参数比如限制最大生成长度避免模型啰嗦半天。还有一个容易被忽略的点是上下文长度。你给模型的上下文越长它处理起来越慢。日常写代码没必要把整个项目文件都塞进去按需给相关的代码片段就行既快又准。6.2 模型更新与版本管理本地模型也是会迭代的隔一段时间就有新版本出来。更新模型很简单重新 pull 一下新版本就行。但要注意新版本不一定就比旧版本好尤其是代码场景有些新版本在通用对话上强了代码能力反而有波动。我的做法是保留一两个用着顺手的旧版本新版本先小范围试试确认稳定再切换。容器和镜像也要定期清理。跑久了会积累一堆没用的镜像和停止的容器占空间。docker system prune能清理掉这些垃圾但执行前确认一下别把有用的卷删了模型数据都在卷里。6.3 数据安全与备份本地部署最大的卖点就是数据不出本地但这也意味着数据安全的责任全在你自己身上。模型文件、配置文件、对话记录这些都要考虑备份。尤其是配置文件改来改去很容易改乱定期备份一份能省很多事。另外如果你是在多人共用的机器上部署注意一下端口暴露的范围。默认监听 localhost 只有本机能访问如果改成监听所有网卡局域网内其他机器也能连方便是方便但要想清楚这是不是你想要的。内网环境相对安全但也别把服务暴露到不该暴露的地方。6.4 长期使用的几个实用习惯用了一段时间之后我总结了几个让这套本地助手更好用的习惯。第一给常用的提示词建个模板库写代码时直接调用比每次重新描述需求高效得多。第二把模型服务设置成开机自启省得每次用之前还要手动拉容器。第三定期看看服务日志有些小问题在日志里早有苗头早发现早处理。还有一点别指望本地小模型能完全替代云端大模型。它的定位是你的私有助手处理日常的、不涉及复杂推理的编码任务绰绰有余遇到真正棘手的架构设计问题该用云端还是用云端。把工具用在合适的地方才是聪明的用法。7. 我在实际部署中踩过的几个真实坑说几个具体的、文档里不会写的坑。第一个是端口冲突。11434 这个端口有时候会被别的程序占用容器起不来但报错信息很隐晦。遇到服务起不来又找不到原因先netstat看一眼端口是不是被占了换个端口映射能立刻解决。第二个是 WSL2 和 Docker 的资源争抢。Windows 上 WSL2 本身也吃内存Docker 再跑在里面如果机器内存本来就不宽裕跑模型的时候整个系统会卡到没法用。这种情况要么加内存要么把模型服务放到另一台机器上Codex 通过局域网连过去。第三个是配置文件的编码问题。Windows 上编辑配置文件如果不小心存成了带 BOM 的 UTF-8某些程序解析会出错报一些莫名其妙的语法错误。用 VS Code 这类编辑器注意看右下角的编码格式选不带 BOM 的 UTF-8。第四个是模型名的大小写和连字符。有些模型名字里带连字符或者大小写敏感配置里写错一个字符就连不上。复制粘贴模型名的时候仔细核对别手打。这套本地 AI 编程助手的部署说到底就是把 Docker、模型服务、客户端配置这三块拼起来。每一块单独看都不复杂难的是它们之间的衔接。把每个环节的为什么搞明白出问题时你就有方向而不是对着报错干瞪眼。跑通一次之后后面再部署就是肌肉记忆了。