局域网里跑 AI 编程助手这件事我从去年下半年开始折腾到现在踩过的坑比写过的代码还多。最开始的想法很简单公司内网有几台性能不错的机器平时闲置着而 Claude Code、Codex 这类工具又特别吃网络和算力能不能把它们放到局域网里让团队几个人共用既省资源又不用担心数据往外跑。结果一上手才发现事情远没有想象中那么直接——从环境安装、模型接入、代理转发到局域网联机每一步都有坑。这篇就把我这一路折腾下来的完整经验整理出来从零开始讲清楚局域网离线环境下怎么把 Claude Code 和 Codex 跑顺适合想在内网自建 AI 编程环境的开发者、运维以及被网络问题折磨过的同行参考。1. 为什么要在局域网里折腾 AI 编程助手1.1 公网直连的真实痛点先说清楚动机不然很多人会觉得多此一举。Claude Code 和 Codex 这类工具默认都是走公网 API 的用起来确实方便但一旦放到团队协作或者企业内网场景问题就集中爆发了。第一个痛点是网络稳定性。公网 API 的响应时间波动很大尤其是高峰期一个稍微复杂点的代码补全请求可能要等十几秒甚至超时。我在实际项目里遇到过连续三次请求失败的情况代码写到一半卡住体验非常糟糕。局域网内部署之后请求走的是内网千兆甚至万兆链路延迟能压到个位数毫秒这个差距是质变。第二个痛点是数据安全。很多公司的代码是不能随便往外发的哪怕只是发给模型做推理。虽然各家 API 都声称不训练用户数据但合规部门不认这个。把模型部署在局域网内部数据不出内网这是最稳妥的方案。第三个痛点是成本。团队里如果每个人都单独订阅费用叠加起来很可观。局域网共享一套推理服务几个人分摊成本能降一大截。1.2 局域网方案能解决什么、不能解决什么这里必须泼一盆冷水避免大家期望过高。局域网离线方案能解决的是网络链路和数据边界问题但模型能力取决于你本地部署的是什么模型。如果你本地跑的是开源模型比如通过 LM Studio 或者 Ollama 部署的量化版本那能力上限和云端旗舰模型是有差距的。Claude Code 本身是一个客户端工具它需要对接一个模型后端。你可以让它对接云端 API也可以对接本地模型服务。局域网方案的核心思路就是把模型服务部署在内网某台机器上其他机器通过局域网访问这个服务。所以这套方案适合的场景是对数据敏感、对延迟敏感、能接受本地模型能力、或者有内网 API 网关可以转发到合规云端服务的团队。不适合的场景是追求极致模型能力、完全不想维护本地服务的个人用户。1.3 整体架构长什么样在动手之前先把架构理清楚后面每一步操作你才知道自己在干什么。整个局域网方案分三层模型服务层部署在内网一台性能较好的机器上负责实际推理。可以是 LM Studio、Ollama、vLLM 等对外暴露一个兼容 OpenAI 格式的 API 接口。客户端层每台开发机安装 Claude Code 或 Codex CLI配置指向内网的模型服务地址。网络层确保各机器在同一局域网内IP 可达端口开放。关键点在于接口兼容性。Claude Code 和 Codex 默认对接的是各自厂商的 API 格式但都支持通过配置指向兼容 OpenAI 格式的端点。所以本地模型服务只要暴露 OpenAI 兼容接口理论上就能接上。2. 模型服务端的选型与部署2.1 LM Studio、Ollama、vLLM 到底选哪个这是第一个要做的决策选错了后面全是返工。我把三个主流方案的实际体验列出来对比方案部署难度硬件要求并发能力接口兼容适合场景LM Studio极低中弱OpenAI 兼容个人/小团队Ollama低中中OpenAI 兼容小团队vLLM高高强OpenAI 兼容团队/生产LM Studio的优势是图形界面下载模型、加载、启动服务全在界面上点几下就行对新手极其友好。缺点是并发能力弱基本只适合一两个人用多人同时请求会排队。Ollama是命令行工具安装一条命令搞定模型管理也很方便。它的并发比 LM Studio 好一些但也不是为高并发设计的。适合三五人的小团队。vLLM是真正为生产环境设计的推理框架支持连续批处理、PagedAttention 等优化并发能力强。但部署复杂需要配 Python 环境、CUDA、模型权重对硬件要求也高。适合有运维能力的团队。我的建议是先跑通再优化。新手直接用 LM Studio 或 Ollama 把流程跑通确认整条链路没问题再考虑换 vLLM 提升并发。2.2 硬件配置怎么估算很多人卡在这一步不知道该买什么机器。核心看两个指标显存和内存带宽。模型推理的速度主要受显存带宽限制。一个粗略的估算公式是模型参数量B× 量化位数bit÷ 8 所需显存GB。比如一个 7B 的模型用 4bit 量化大约需要 7 × 4 ÷ 8 3.5GB 显存加上上下文缓存实际留 6-8GB 比较稳妥。对于代码补全场景我实测下来 7B 到 14B 的模型是比较甜点的区间。再小的模型代码能力不够再大的模型消费级显卡跑不动。具体配置参考入门单张 12GB 显存的显卡跑 7B 4bit 量化模型够 1-2 人用。进阶单张 24GB 显存跑 14B 4bit 或 7B 8bit够 3-5 人用。团队多卡或者专业卡跑 32B 以上模型配合 vLLM 支持 10 人以上。内存方面至少 32GB推荐 64GB。因为模型加载、上下文缓存、系统本身都要吃内存。硬盘用 NVMe SSD模型文件动辄几个 GB机械盘加载会等到怀疑人生。2.3 以 LM Studio 为例的完整部署流程选 LM Studio 做演示因为它的流程最直观新手最容易复现。第一步去 LM Studio 官网下载对应系统的安装包。Windows 和 macOS 都有图形安装程序Linux 有 AppImage。安装过程没什么好说的一路下一步。第二步打开软件在搜索框里找模型。推荐几个代码能力不错的Qwen2.5-Coder-7B-Instruct、DeepSeek-Coder-V2-Lite。注意选 GGUF 格式的量化版本Q4_K_M 是速度和质量的平衡点。第三步下载完成后在左侧菜单找到 Local Server 标签页选择刚下载的模型点击 Start Server。默认监听http://localhost:1234。第四步也是最关键的一步开启局域网访问。默认情况下 LM Studio 只监听 localhost其他机器访问不了。需要在设置里找到 Serve on Local Network 选项并打开。打开后服务会监听0.0.0.0:1234局域网内其他机器就能通过这台机器的 IP 访问了。注意开启局域网访问后同一网络下的任何设备都能访问你的模型服务。如果是在公共网络或者不信任的环境务必配合防火墙规则限制访问来源 IP。第五步验证服务。在另一台机器上打开浏览器访问http://服务端IP:1234/v1/models如果返回模型列表的 JSON说明服务正常。2.4 服务端防火墙与端口放行这一步是新手最容易翻车的地方。服务明明启动了另一台机器就是连不上八成是防火墙拦了。Windows 上打开高级安全 Windows Defender 防火墙新建入站规则选择端口TCP填 1234允许连接应用到所有网络类型。或者用命令行netsh advfirewall firewall add rule nameLM Studio dirin actionallow protocolTCP localport1234Linux 上用 ufw 或 firewalldsudo ufw allow 1234/tcp # 或者 sudo firewall-cmd --permanent --add-port1234/tcp sudo firewall-cmd --reloadmacOS 相对省心系统偏好设置里的防火墙默认对已签名的应用放行一般不用额外配置。配完之后用telnet 服务端IP 1234或者nc -zv 服务端IP 1234测试端口连通性。这一步过了网络层就没问题了。3. Claude Code 在局域网环境下的接入配置3.1 Claude Code 的安装与版本选择Claude Code 目前有几种形态CLI 版本、VS Code 插件版本、桌面版。局域网场景下我推荐用 CLI 版本因为它配置最灵活最容易指向自定义端点。安装方式官方推荐用 npmnpm install -g anthropic-ai/claude-code装完之后用claude --version验证。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Windows 用户如果不想折腾 Node 环境也可以用官方提供的安装包。不过 CLI 版本更新更及时功能也更全我还是建议走 npm 这条路。提示安装过程中如果遇到网络问题可以配置 npm 的镜像源。但注意这里只是解决包下载问题不涉及任何网络访问工具。3.2 把 Claude Code 指向本地模型服务这是整个流程的核心。Claude Code 默认对接 Anthropic 的 API要让它走本地服务需要设置环境变量。关键环境变量是ANTHROPIC_BASE_URL把它指向本地模型服务的地址export ANTHROPIC_BASE_URLhttp://192.168.1.100:1234/v1 export ANTHROPIC_API_KEYlm-studioAPI Key 这里随便填一个非空值就行本地服务一般不校验。Windows 上用set或者$env:语法$env:ANTHROPIC_BASE_URLhttp://192.168.1.100:1234/v1 $env:ANTHROPIC_API_KEYlm-studio设置完之后运行claude启动它就会把请求发到你的本地服务。这里有个大坑要提醒Claude Code 使用的是 Anthropic 的 Messages API 格式而 LM Studio 暴露的是 OpenAI 的 Chat Completions 格式。两者虽然都是 JSON但字段结构不一样。直接对接大概率会报错比如cc switch local proxy failed while handling codex endpoint /responses这类错误本质就是格式不匹配。解决办法是加一层协议转换代理。常见做法是用 LiteLLM 或者 one-api 这类工具它们能把 Anthropic 格式的请求转成 OpenAI 格式转发给本地服务。3.3 协议转换代理的搭建以 LiteLLM 为例它能同时暴露 Anthropic 兼容和 OpenAI 兼容的接口非常适合这种场景。安装pip install litellm[proxy]写一个配置文件config.yamlmodel_list: - model_name: local-coder litellm_params: model: openai/Qwen2.5-Coder-7B-Instruct api_base: http://192.168.1.100:1234/v1 api_key: lm-studio启动代理litellm --config config.yaml --port 4000这样 LiteLLM 会在 4000 端口暴露一个 Anthropic 兼容的接口。然后把 Claude Code 的ANTHROPIC_BASE_URL指向http://192.168.1.100:4000就行了。这层代理看起来多此一举但它是打通 Claude Code 和本地模型的关键。我一开始想省掉这步结果折腾了大半天都在报格式错误加上代理之后一次就通了。3.4 实测中遇到的报错与排查把常见报错整理成表方便对照排查报错信息根本原因解决方向Connection refused服务未启动或端口不对检查服务状态和端口401 UnauthorizedAPI Key 未设置设置任意非空 Key404 Not Found路径不对确认是 /v1 还是 /v1/messages格式解析错误协议不匹配加协议转换代理超时模型加载中或显存不足等待加载或换小模型排查顺序建议从网络层往上走先ping通不通再telnet端口通不通再curl接口返回什么最后才看客户端配置。这样能快速定位问题在哪一层。4. Codex 的局域网接入与常见问题4.1 Codex CLI 的安装与配置Codex 的安装和 Claude Code 类似也是走 npmnpm install -g openai/codex装完用codex --version验证。Codex 的配置文件和 Claude Code 不太一样它用的是~/.codex/config.toml。一个指向本地服务的配置示例model local-coder model_provider local [model_providers.local] name Local base_url http://192.168.1.100:4000/v1 env_key LOCAL_API_KEY然后在环境变量里设置LOCAL_API_KEY。Codex 对 OpenAI 兼容接口的支持比 Claude Code 直接因为它本身就是 OpenAI 家的工具格式天然一致。所以 Codex 接本地服务通常不需要额外的协议转换层直接指向 LM Studio 的/v1端点就行。4.2 Codex 接入本地模型的两种路径路径一直连本地 OpenAI 兼容服务。这是最简单的把base_url指向 LM Studio 或 Ollama 的地址即可。适合本地模型本身就是 OpenAI 格式的情况。路径二通过 LiteLLM 中转。如果你的本地服务不是标准 OpenAI 格式或者你想统一管理多个模型就走 LiteLLM。好处是可以在一个代理后面挂多个模型客户端切换模型只改一个名字。我实测下来Codex 直连 LM Studio 的成功率很高基本不用折腾。反倒是 Claude Code 因为格式差异必须走代理。4.3 关于 Codex 端点报错的深度排查前面提到的cc switch local proxy failed while handling codex endpoint /responses这个报错我专门研究过。它的意思是代理在处理 Codex 的/responses端点时失败了。Codex 新版用的是/responses端点而不是传统的/chat/completions。很多本地模型服务和代理工具只实现了/chat/completions没实现/responses所以会报这个错。解决办法有两个一是降级 Codex 到使用/chat/completions的版本。二是在代理层做端点映射把/responses的请求转成/chat/completions转发出去。LiteLLM 较新版本已经支持/responses端点的转换升级到最新版通常能解决。如果还不行检查配置文件里模型的mode设置是否正确。4.4 多客户端共存的端口规划团队里如果同时有人用 Claude Code 和 Codex端口规划要提前想好不然会打架。我的建议是模型服务1234LM Studio 默认LiteLLM 代理4000如果跑多个代理实例用 4001、4002 依次递增每台客户端机器上的环境变量指向对应的代理端口。这样服务端一套模型客户端各取所需互不干扰。5. 局域网联机与网络层的那些坑5.1 为什么能上网但访问不了局域网这是热词里出现频率很高的问题我身边好几个同事都遇到过。现象是机器能正常上互联网但访问不了同一局域网内的其他机器。根本原因通常是网络配置文件类型不对。Windows 把网络分为公用和专用两种。如果当前网络被识别为公用网络系统会默认禁止局域网内的设备发现和文件共享防火墙也会更严格。解决办法打开设置 - 网络和 Internet - 状态点击当前连接的网络把网络配置文件改成专用。改完之后局域网访问通常就恢复了。另一个常见原因是多网卡路由冲突。机器同时接了有线和无线或者装了虚拟网卡路由表里有多条默认路由导致局域网流量走错了出口。用route print查看路由表确认局域网网段的路由指向正确的网卡。5.2 交换机组建局域网时的连接拒绝热词里有linux 用交换机组建局域网为什么显示拒绝连接这个我也踩过。用交换机把几台机器连起来物理层通了但应用层连不上一般是这几个原因IP 网段不一致几台机器不在同一网段比如一台是 192.168.1.x另一台是 192.168.0.x。交换机只做二层转发不跨网段。要么手动配同网段 IP要么上路由器。子网掩码配错掩码配成 255.255.255.0 但实际需要更大范围导致判断为不同网段。服务只监听 localhost这个前面提过服务默认只绑 127.0.0.1外部访问不了。要改成监听 0.0.0.0。防火墙拦截即使同网段防火墙也可能拦。排查顺序先ip addr看 IP 和掩码再ping测连通再telnet测端口最后看服务监听地址。5.3 跨操作系统互访的注意事项团队里机器系统不统一是常态Windows、macOS、Linux 混着用。跨系统互访有几个点要注意换行符和路径分隔符配置文件里如果涉及路径Windows 用反斜杠Linux 用正斜杠。写配置时尽量用正斜杠兼容性更好。防火墙策略差异Windows 防火墙默认拦入站Linux 的 iptables/firewalld 规则更复杂macOS 相对宽松。每台机器都要单独确认。主机名解析局域网内用 IP 最稳别依赖主机名。如果一定要用主机名确保各机器的 hosts 文件或者内网 DNS 配好了。5.4 局域网 IP 地址的规划与查询IP 规划建议用静态 IP别用 DHCP 动态分配。因为客户端配置里写的是服务端 IP如果 IP 变了所有客户端都要改配置很麻烦。查询本机 IP# Linux/macOS ip addr show # 或 ifconfig # Windows ipconfig给服务端机器配一个固定的内网 IP比如 192.168.1.100然后在路由器上做 IP-MAC 绑定防止被其他设备占用。这样整套环境就稳定了。6. 性能调优与多人共用的实战经验6.1 上下文长度与显存的平衡代码补全场景对上下文长度要求比较高因为要理解整个文件甚至多个文件。但上下文越长占用的显存越多。LM Studio 里可以设置上下文长度默认可能是 4096对于代码场景偏小。建议调到 8192 或 16384。但要注意上下文翻倍显存占用也会显著增加。如果显存不够模型会加载失败或者推理极慢。我的经验是先确定显存能支撑的最大上下文再在这个范围内取一个够用的值。7B 模型 4bit 量化12GB 显存大概能撑 16K 上下文。如果不够降到 8K。6.2 多人同时请求时的排队问题LM Studio 和 Ollama 的并发能力有限多人同时用会排队。表现是第一个人请求很快返回第二个人要等第一个人处理完。缓解办法有几个错峰使用团队约定不同时段集中使用减少并发。升级到 vLLMvLLM 的连续批处理能把多个请求合并处理吞吐量提升明显。部署多个模型实例如果显存够跑两个模型实例客户端分流。实测下来3 人以内用 Ollama 还能接受超过 5 人就必须上 vLLM 了。6.3 模型选择对代码质量的影响本地模型和云端旗舰模型的代码能力差距是客观存在的。我实测过几个模型在代码补全任务上的表现7B 级别能处理简单的函数补全、语法纠错复杂逻辑容易出错。14B 级别能处理中等复杂度的代码生成理解上下文能力明显更好。32B 级别接近可用水平但硬件要求高。选择模型时优先看它在代码基准测试上的表现别只看参数量。有些 7B 的代码专用模型实际表现比通用 13B 还好。6.4 日常维护与监控局域网服务跑起来之后日常维护不能少监控显存占用用nvidia-smi定期看显存满了会导致服务崩溃。日志检查LM Studio 和 LiteLLM 都有日志出问题先看日志。定期重启长时间运行可能内存泄漏建议每周重启一次服务。模型更新新模型出来可以试试但别在生产环境直接换先测试。7. 几个容易被忽略的细节7.1 环境变量的持久化前面设置的环境变量都是临时的关掉终端就没了。要持久化Linux/macOS 写进~/.bashrc或~/.zshrcWindows 用系统环境变量设置界面或者setx命令。# Linux/macOS 追加到 ~/.bashrc echo export ANTHROPIC_BASE_URLhttp://192.168.1.100:4000 ~/.bashrc echo export ANTHROPIC_API_KEYlocal ~/.bashrc source ~/.bashrcWindowssetx ANTHROPIC_BASE_URL http://192.168.1.100:4000 setx ANTHROPIC_API_KEY local注意setx设置后要新开终端才生效。7.2 客户端配置文件的备份Claude Code 和 Codex 的配置文件散落在不同位置重装系统或者换机器时容易丢。建议把关键配置集中备份Claude Code~/.claude/目录Codex~/.codex/config.tomlLiteLLMconfig.yaml把这些文件放到一个 git 仓库里管理换机器时直接拉下来省得重新配。7.3 安全边界局域网不等于绝对安全最后强调一个容易被忽视的点。很多人觉得局域网就是安全的其实不然。局域网内任何一台机器被入侵攻击者就能访问你的模型服务。所以模型服务不要暴露到公网只在内网监听。如果内网有访客网络确保访客网络和办公网络隔离。定期检查服务日志看有没有异常请求。敏感项目建议单独部署一套服务物理隔离。这套局域网离线方案我用了大半年团队五个人共用一套服务稳定性和数据安全性都比公网方案好很多。中间踩的坑主要集中在协议转换和网络配置上把这两块理顺之后日常使用基本无感。如果你也在考虑类似方案建议先从单机跑通开始再逐步扩展到局域网别一上来就搞复杂架构。