1. VibeCoding 火了一年还在盯云 API 的人可以看看另一条路VibeCoding 从热度上来那天起就一直处在“编程方式之争”的漩涡中心。说人话就是不再一个字符一个字符地手写代码而是把需求、报错、甚至一句含糊的“给我搭一个内部用的报表系统”丢给 AI 编码助手由它完成读文件、改代码、跑命令、循环修复的全流程。Claude Code 和 Codex 是这一波里最受关注的两个命令行编码 AgentClaude Code 背靠 Anthropic 的模型能力交互节奏更像一个坐在旁边的工作伙伴Codex 是 OpenAI 的官方 CLI把 agentic 编码和代码评审一把抓。抛开“谁更强”不谈这两类工具默认都是走云端 API 的。代码要离开你的电脑送到公共接口去做推理。个人玩可能无所谓但放到公司内部项目、客户现场、或者对数据要求严格的环境里这就是硬伤。于是“局域网离线 VibeCoding”——把 Claude Code、Codex 这类前端工具接到本机或局域网内的大模型服务上——就成了一个非常现实的需求。好处很直接源码不出内网、不按 token 计费、没有外部接口的配额和频次限制日常用着也确实更省心。这篇文章不是概念科普而是我折腾完整套离线编程链路之后的实操记录。适合谁看正在用或准备用 Claude Code / Codex、手头有一台能跑模型的好机器、或者团队想在内部统一铺一套 AI 编码基础设施的开发者和运维。下面不废话直接讲架构、配置、模型选择、踩坑实录。1.1 Claude Code 和 Codex 的本质CLI 壳 模型内核要理解离线方案先得知道这两工具到底是什么。Claude Code 本体是一个 Node.js 命令行应用核心职能是维护会话上下文、拆分任务、决定调用哪个工具、解析模型的意图。它不包含模型模型是它背后的推理大脑。Claude Code 启动时读取环境变量里的 API 地址和密钥默认指向 Anthropic 的云端接口通过 Anthropic Messages API/v1/messages发送请求模型返回结构化回复CLI 再根据内容执行文件读写、终端命令等动作。Codex 同理。Codex CLI 是一个 Rust 编写的命令行编码 Agent默认走 OpenAI 的 Chat Completions/v1/chat/completions或者较新的 Responses API/v1/responses它的工具调用能力同样依赖模型。Codex 的配置自由度比 Claude Code 高一点原生支持“自定义模型提供者”——也就是说你可以不接 OpenAI 的官方接口而是指向任何一个 OpenAI 兼容的服务。这就是离线方案的着眼点模型接口是可以替换的。前端工具不变把背后的 API 地址从云端换成局域网里的推理服务就完成了“离线化”。剩下的核心工作只有两件事让本地推理服务提供一个可用的 API 格式以及把 Claude Code 或 Codex 的请求正确导过去。1.2 为什么非要离线加局域网很多人第一反应是明明是联网工具为什么要搞离线我的体会是离线不是倒退而是针对几种真实场景的必要妥协。第一个场景是代码保密。公司内部项目、未发布的产品线、客户定制的业务逻辑代码一旦发到外网 API就脱离了你的控制范围。哪怕平台承诺数据不用于训练合规和审计这两关也过不去。局域网本地部署之后推理在本地 GPU 上完成任何代码都不会离开内网这是最彻底的隔离方案。第二个场景是成本。按 token 计费的云端 API一次大型代码重构可能烧掉不少预算团队里十个人天天挂着这类编码 Agent月账单会很可观。本地模型一次性买硬件后续推理几乎零边际成本跑得再狠也就是电费。第三个场景是可用性。生产环境、客户现场往往网络条件受限或者外部接口的频次限制很严。离线部署之后只要内网通工具随时能用不受第三方服务波动影响。我把话说清楚离线不是要替代云端大模型——本地模型在很多复杂任务上确实不如顶尖云模型——离线是“可控”和“可落地”优先的替代选择。对大多数日常重构、补测试、写脚本的任务一个调教得当的本地模型完全够用。2. 离线链路的核心架构一条清晰的请求链路离线 VibeCoding 的整套链路用一句话概括就是Claude Code / Codex 作为前端把请求送到一个“本地网关”网关处理协议和路由后再把请求递交给局域网里的模型服务。拆开看是三个部件。2.1 三个部件的分工第一个部件是前端工具也就是 Claude Code 或 Codex 的 CLI。它负责维护对话、输出工具调用计划、展示生成结果。它只管发请求不关心背后是什么模型。第二个部件是本地模型服务常见的是 LM Studio 或 Ollama。它们在一台配置足够好、最好带独立 GPU 的机器上加载模型以 OpenAI 兼容接口的方式对外提供推理能力。LM Studio 默认端口是 1234Ollama 是 11434两者都支持开放局域网访问。第三个部件是“协议网关”。这一步不是所有教程都会提到但恰恰是坑最多的地方。Claude Code 默认说 Anthropic 的 Messages 协议而 LM Studio / Ollama 对外说的是 OpenAI 的 Chat Completions 协议。两种协议的请求体结构、工具调用表达方式都不一样。所以 Claude Code 不能直接指向 LM Studio 的地址中间必须有一个人能把 Anthropic 的请求翻译成 OpenAI 的请求。可选方案包括 LiteLLM 和 claude-code-routerCC Switch 这类管理工具则内置了类似的转发能力。Codex 就没那么麻烦。它的 config.toml 原生支持 model_providers可以直接把一个 OpenAI 兼容的 base_url 填进去只要协议匹配就能用。所以 Codex 接 LM Studio / Ollama 通常不需要额外的网关一台机器直连也行。2.2 为什么用网关而不是直接改 Claude Code每隔一段时间就有人问能不能直接把 Claude Code 的模型地址改成 LM Studio答案是可以改地址但协议不匹配时请求会直接失败。Claude Code 发的请求头里带着 anthropic-version请求体带 system、messages、tools 这些字段本地服务必须能正确解析并回答。如果自己写脚本去适配这套协议工作量和维护成本都很高。网关方案最省心——它在协议层做好兼容Claude Code 认为自己在跟 Anthropic 对话网关在背后替你把请求翻译给任何你想用的模型。选网关也有讲究。LiteLLM 是老牌方案能同时管理十几个供应商适合团队级基础设施claude-code-router 更轻专门给 Claude Code 与本地/第三方模型做桥接配置是 JSON 文件个人开发者用起来非常顺手。我两个都用过追求稳定和可复用选 LiteLLM追求快速上手选 claude-code-router。下文会分别给配置示例。2.3 模型选型的几个真实标准模型选什么直接决定离线 VibeCoding 好不好用。这个问题比很多人想得更关键——编码 Agent 对模型的“工具调用能力”要求远高于普通对话。首先必须支持 function calling / tool calling。Claude Code 和 Codex 都要靠模型输出结构化的工具调用指令来读写文件、执行命令。如果模型不会主动调用工具或者调用格式不稳定编码 Agent 就会变成“话痨而不干活”的摆设。许多通用对话模型看着聪明实际接进去后完全没法用就是这个原因。其次是上下文长度。编程任务动辄要读十几个文件上下文至少要 32K 以上建议选原生支持 64K 的模型。上下文不是越大越好还要考虑显存占用这个下面会详细算。最后是实际体感。就我的体验来说本地跑编码 AgentQwen3-Coder 系列和 GLM 的 Z 系列专门为 Agent 场景设计的版本表现比较好DeepSeek 的 Coder 系列也不错。这几种模型的工具调用格式规整能听懂“继续”“修复失败”“再看一眼测试”这种指令。我不推荐在代理场景里用参数太大但显存塞不下的模型——宁可 14B 高精度不要 30B 强量化后者在长链路任务里很容易“断片”。注意以上的“运行效果”指纯粹本地推理时的体感。不同版本、不同量化档位差异很大建议以实测为准。3. 软硬件准备先把模型服务跑起来先明确一件事模型服务必须跑在局域网内一台“能打”的机器上其他成员通过内网 IP 访问。这一步是离线方案的地基地基不牢后面全是扯皮。3.1 硬件底线和量化预算小算盘给一个诚实的硬件底线。只跑 7B 模型16GB 显存的显卡加 32GB 内存就够想舒服跑 14B 模型推荐 24GB 显存级别要跑 30B 以上的强模型得考虑双卡或大显存方案。内存带宽也很重要苹果 M 系列统一内存的机器跑大模型表现不错因为带宽高普通 PC 如果只靠 CPU 跑速度会非常痛苦不建议。量化预算有一个经验公式模型权重文件大小 上下文 KV cache必须能放进显存。以 14B 模型 Q4_K_M 为例权重约 89GB上下文 32K 时的 KV cache 约 24GB合计 12GB 左右。16GB 显卡会比较紧张但可运行24GB 则从容很多。别只看模型文件体积KV cache 虽然经常被忽略但长上下文编程场景里它是实打实的显存消耗大户。3.2 LM Studio 部署与局域网开放LM Studio 是目前本地推理里最省心的图形化方案。官网下载对应系统安装包装完在 Models 标签页搜索并下载模型比如 Qwen3-Coder-14B 的 Q4_K_M GGUF 文件。下载完成后进入 Developer 标签页选择模型并启动本地服务器。关键一步是局域网开放。较新版本的 LM Studio 默认服务绑定在 0.0.0.0也就是所有网卡都监听。如果不放心可以在启动服务的命令行里手动指定lms server start --host 0.0.0.0 --port 1234看到服务运行提示后先在本机验证curl http://localhost:1234/v1/models能返回模型列表说明服务起来了。然后在同一局域网的另外一台机器上执行同样的命令把地址换成 LM Studio 所在机器的内网 IPcurl http://192.168.1.100:1234/v1/models这个测试必须做因为后面所有 CLI 工具的 base_url 都会填这个内网地址。如果局域网访问不通八成是系统防火墙拦了 1234 端口放行即可。3.3 Ollama 部署与局域网开放如果团队更偏好命令行Ollama 是更轻的选择。我第一次接触时一条命令就跑起了模型干净利落。安装后拉取模型ollama pull qwen3-coder:14b默认情况下 Ollama 只监听本机回环地址 127.0.0.1不满足局域网共享需求。需要设置环境变量 OLLAMA_HOST。Linux/macOS 上export OLLAMA_HOST0.0.0.0:11434 ollama serveWindows 上更简单在系统环境变量里新建 OLLAMA_HOST值填 0.0.0.0保存后重启 Ollama 服务。然后同样用 curl 验证curl http://192.168.1.100:11434/v1/models注意 Ollama 的 OpenAI 兼容接口前缀是 /v1。Codex 直接指向这个地址就能用这也是 Ollama 在编码 Agent 场景里受欢迎的原因之一。3.4 一个容易忽略的点并发和资源要提前算好把服务跑起来之后我踩过最烦的坑是“并发”。本地模型服务不是多线程随便扛的显存有多大同时能承载的请求就有上限。LM Studio 和 Ollama 都默认单请求排队也就是说一个成员在跑大任务时其他人只能等。这对“局域网团队共享”来说是一个必须提前说清楚的限制。我的做法如果团队超过三个人就准备两套模型端口一个给高优先级重构任务一个给日常轻量任务如果只有一个人用单实例完全够。另外建议把模型服务的机器放在有线网络里无线环境下长任务偶发断连会让 CLI 工具非常痛苦。4. Claude Code 接入本地模型的完整配置Claude Code 的接入是整个方案里“协议翻译”最明显的一环也是出错率最高的地方。我把它拆成安装、网关、settings.json、验证四个步骤。4.1 安装方式与离线机器的应对Claude Code 是 npm 包正常安装一步到位npm install -g anthropic-ai/claude-code但局域网离线机器的典型困境是机器本身没有外网npm 装不了。我的应对是在一台临时能联网的机器上先完成安装然后把全局 node_modules 里的 anthropic-ai 目录整体拷贝到离线机器的对应位置。Windows 上是%APPDATA%\npm\node_modulesLinux 是/usr/lib/node_modules或用户目录下的.npm-global。拷贝完成后执行claude --version验证。这个办法实测可行麻烦在于离线机器的 Node.js 版本要和拷贝来源机器基本一致否则二进制兼容性会出问题。另外如果安装时报 Windows 的 WinINet 错误比如internetopenurl() failed 0x8009Fxxx基本可以定位到网络访问问题。对策就是上面说的“联网机器装好再拷贝”或者检查 npm 源是否可用。4.2 搭一个本地网关两种我都试过先讲 claude-code-router。安装命令npm install -g musistudio/claude-code-router配置写在~/.claude-code-router/config.json一个最小可用配置如下{ provider: lmstudio, providers: { lmstudio: { baseUrl: http://192.168.1.100:1234/v1, apiKey: lmstudio } }, model: qwen3-coder-14b }不同版本的配置键名可能有差异安装后先执行ccr --help看说明确认 provider 名称和配置字段。启动后它会在本地开一个监听端口默认 3456Claude Code 把请求发给这个端口路由器再转发给 LM Studio。LiteLLM 网关是另一条路。安装和启动pip install litellm[proxy] litellm --config config.yamlconfig.yaml 里把模型指向 LM Studiomodel_list: - model_name: qwen3-coder-14b litellm_params: model: openai/qwen3-coder-14b api_base: http://192.168.1.100:1234/v1 api_key: localLiteLLM 启动后默认监听 4000 端口自带 Anthropic 兼容的 /v1/messages 接口Claude Code 可以直接对接。这正是我前面说的“网关做协议翻译”的标准实现。4.3 让 Claude Code 指向网关的三种配置方式最推荐的方式是改 Claude Code 的配置文件~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:3456, ANTHROPIC_API_KEY: local-key, ANTHROPIC_MODEL: qwen3-coder-14b, ANTHROPIC_DEFAULT_SONNET_MODEL: qwen3-coder-14b, ANTHROPIC_DEFAULT_HAIKU_MODEL: qwen3-coder-14b, API_TIMEOUT_MS: 600000 } }几个字段逐个说明。ANTHROPIC_BASE_URL 指向网关地址router 是 3456LiteLLM 是 4000不要直接指向 LM Studio。ANTHROPIC_API_KEY 随便填一个非空值因为本地网关不校验密钥但留空的话 Claude Code 会拒绝工作。ANTHROPIC_MODEL 和两个 DEFAULT 模型字段统一设成网关上配置的模型名否则 Claude Code 会按默认模型名去找导致网关查无此模型。API_TIMEOUT_MS 必须调大本地模型每步推理在几秒到十几秒之间默认超时在长任务里根本不够。第二种方式是直接导出环境变量适合临时验证export ANTHROPIC_BASE_URLhttp://localhost:3456 export ANTHROPIC_API_KEYlocal export ANTHROPIC_MODELqwen3-coder-14b claude第三种方式是使用 CC Switch 这类工具统一管理点选一下就能切换适合经常在云端和本地之间来回切换的人。它的原理其实也是帮你改 ANTHROPIC_BASE_URL背后可能还会起一层本地转发。这个工具我在第 6 节单独讲。4.4 验证接入成功的关键信号配置完之后不要急着干重活先做冒烟测试。在 Claude Code 里输入“你好请告诉我你当前使用的模型名称并简单说明你能做什么。”如果配置正确你会看到响应内容来自本地模型。如果报错按下面三种现象对号入座请求发出后立刻 404检查 ANTHROPIC_BASE_URL 端口是不是写错了请求能到网关但返回 401检查 API key 是否为空请求一直转圈然后超时大概率是本地模型推理太慢把 API_TIMEOUT_MS 再往上调。冒烟通过之后建议跑一个真实的小任务让 Claude Code 在临时目录里创建一个 Python 脚本完成一个 CSV 文件的排序和去重并要求它执行验证。这个任务同时覆盖了文件读写、命令执行和错误修复三个核心工具调用能比较全面地检验本地模型在 Agent 场景下的可用性。5. Codex 接入本地模型与第三方模型的配置Codex 的接入逻辑和 Claude Code 不同它原生支持自定义模型提供者不需要中间网关。这个设计省了很多事但也带来了一个比较隐蔽的坑默认模型路由和请求格式问题。5.1 安装 Codex 与初始化Codex CLI 目前的分发方式之一是 npmnpm install -g openai/codex安装完成后先执行一次codex让它生成默认配置目录~/.codex/。第一次运行会引导登录如果目标是本地模型这一步可以跳过——直接编辑配置文件即可。配置文件是 TOML 格式位于~/.codex/config.toml。5.2 model_providers 配置与关键参数Codex 的配置核心是 model_providers 这一段。接 LM Studio 的配置示例model_provider lmstudio [model_providers.lmstudio] name LM Studio Local base_url http://192.168.1.100:1234/v1 env_key LMSTUDIO_API_KEY wire_api chat接 Ollama 的配置示例model_provider ollama [model_providers.ollama] name Ollama Local base_url http://192.168.1.100:11434/v1 env_key OLLAMA_API_KEY wire_api chatmodel_provider 指定默认提供者base_url 指向局域网模型服务env_key 是一个环境变量名Codex 会从这里读取 API key本地服务不需要真实密钥但环境变量必须存在且非空否则 Codex 会认为没有认证信息。可以在 shell 配置里加一行export LMSTUDIO_API_KEYlocal或者直接在系统环境变量里设置。wire_api 是最关键的字段。Codex 默认走它偏好的 responses 接口而本地模型服务普遍只支持 chat 接口。把 wire_api 设成 chat 之后Codex 会用 OpenAI 兼容的 chat completions 格式发请求本地服务才能正确理解。如果不设这个字段很多本地模型会在第一轮请求就报“model not supported”或者直接 404。5.3 跑通 Codex 加本地模型的完整动作配置完成后启动时指定模型名codex --model qwen3-coder-14b模型名必须和你本地服务里已加载的模型名称一致。如果不加 --modelCodex 会按默认模型列表去找本地服务里没有就会报错。更稳妥的做法是把默认模型也写在 config.toml 里这样直接codex就能用。还有一个值得注意的动作关闭 Codex 对模型路由的预检。Codex 启动时会尝试加载组织设置和模型路由表如果这些请求走不到就会出现类似“无法加载组织设置”的报错。这时候检查两点一是认证相关的环境变量是否配置正确二是在使用第三方提供者时确认 config.toml 中没有残留任何官方账户的登录信息。本地模型模式下组织信息其实无关紧要Codex 只要能把请求发到 base_url 就算成功。5.4 接第三方开放 APIDeepSeek、Qwen、GLM 同样适用不只是本地模型Codex 也可以接第三方开放 API。原理和接 LM Studio 完全一致写一个 model_provider把 base_url 换掉。以 DeepSeek 为例model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后设置 DEEPSEEK_API_KEY 为你的真实 API key启动时codex --model deepseek-chat即可。需要注意第三方 API 的模型名称要按服务商文档来不要自己臆造。Qwen、GLM 的服务商对外也都提供 OpenAI 兼容接口写法大同小异灵活度相当高。这种“把 Codex 导向第三方 API”的做法特别适合想体验 agentic coding 又不想在本地配 GPU 服务器的人。它虽然不是离线但同样绕开了对单一官方服务的强依赖是一种务实折中。当然凡是把代码发到外部 API 的场景数据安全边界要自己把关。6. CC Switch端点切换工具的使用与报错排查CC Switch 是近半年被提得非常多的工具它的定位是“给多个 AI 编程工具做模型端点配置管理”。它的价值在于当你在官方 API、第三方平台 API、本地模型地址之间反复切换时不用反复手改 settings.json 或 config.toml点一下就能切换。6.1 CC Switch 到底帮你做了什么CC Switch 干了三件事。第一件事是管理配置把不同提供者的 base_url、模型名、密钥集中存储每个提供者对应一套参数。第二件事是切换生效一键把当前模型提供者从 A 切到 B。第三件事往往被忽略——它很多时候会启动一个本地转发通道把 Claude Code 或 Codex 的请求先接到自己这里再按配置转发给目标模型服务。正是这第三件事成为不少报错的来源。这里有个概念要澄清本地转发通道属于“请求路由”和我之前讲的“协议转换网关”不完全是一回事。路由只负责把请求送到目标格式转换才是真正解决协议不匹配的部分。只有路由而协议不翻译时Claude Code 接 LM Studio 依然不通。所以判断 CC Switch 是否适合你要看它是否针对你用的工具做了完整的协议适配而不只是配了个地址。6.2 配置示例与常见用法以 Claude Code 为例在 CC Switch 里新增一个提供者名称填“本地 Qwen”类型选择 Claude Code地址填 http://localhost:3456如果你用了 claude-code-router 做网关模型填 qwen3-coder-14b密钥随意。保存后点“应用”它会自动改写~/.claude/settings.json里的环境变量。下一次启动 claude 时请求就直接走本地链路。Codex 类似但更简单。新增提供者时选择 Codex类型填本地模型它会帮你写 config.toml 的 model_providers 段落。因为 Codex 不需要格式转换网关CC Switch 在这里起的作用更偏向配置管理。6.3 高频报错本地转发失败该怎么查有一个报错关键词很典型“CC Switch 本地转发失败处理 Codex 端点 /responses 时出错”。如果你碰到的是同类报错本质是 CC Switch 启动的那个本地转发服务在处理请求时崩了。我建议按这个顺序排查。第一步看转发服务本身。CC Switch 的转发依赖一个本地端口如果端口被占用或者转发进程没起来就会报这个错。在命令行里看看端口监听状态确认 CC Switch 有正常监听。第二步看目标地址连通性。转发服务最终要把请求送到 base_url 指定的模型服务。如果模型服务没启动、IP 写错、防火墙拦了端口转发失败只是表象根因在目标服务。先单独用 curl 验证 base_url 能不能通。第三步看协议匹配。报错里的 /responses 路径很关键——如果转发服务把请求按 responses 格式发给一个只支持 chat 格式的本地模型目标服务会直接拒绝。解决办法仍然是确保 codex 的 wire_api 设成 chat或者使用做好协议转换的工具。最后说一句如果 CC Switch 在你用的组合里反复出问题不要死磕它。它只是管理工具直接手改配置文件往往更可控。工具是给人省事的不是给人添堵的。7. 局域网多机共享与团队协作要点离线方案的终点通常不是“自己一个人用”而是“团队里每个人都用”。多机共享的难点不在于配置——那只是把 IP 从 localhost 改成内网 IP——而在于资源控制和体验一致性。7.1 把模型服务做成“服务器模式”如果是团队共享建议把模型服务单独部署在一台固定 IP 的机器上不要跑在某个成员的笔记本里。原因很实际笔记本会关机、会休眠、会被拿去开会。模型服务应该像一台常规服务器一样常年在线。机器选型上内存和显存按团队峰值并发来配一般三四个人同时用单张 24GB 显卡配 14B 模型是起步线长期用建议预留 50% 富余。所有成员的 base_url 都填同一台机器的内网 IP例如 http://192.168.10.20:1234/v1LM Studio或 http://192.168.10.20:11434/v1Ollama。配置文件里的模型名保持完全一致。这一步做完每个成员本地只需要装好 Claude Code / Codex 和各自的网关配置就能连上同一个共建的 AI 编程大脑。7.2 访问控制与接口保护局域网不等于完全开放。模型服务虽然没有业务数据但被人恶意调用也会造成资源浪费。两个实用的控制手段一是在模型服务机器上配置防火墙只允许内网网段访问对应端口二是如果选择 Ollama它的 API 本身支持简单的请求校验搭配一层轻量的网络隔离就够用。LM Studio 目前没有内置鉴权更依赖网络层面的控制。安全水位自己把握至少不要直接暴露到不可信的网络里。另外我强烈建议给成员发一份简短的“接入说明”把 base_url、模型名、环境变量设置、验证命令写清楚。团队里不是每个人都熟 TOML 和 JSON一份说明能减少一半的“帮我看看为什么我的连不上”的问题。7.3 并发与排队如何让团队体验不那么痛苦并发控制是局域网共享的体验分水岭。本地推理服务默认是排队执行的一个人发了一个超长重构任务另外两个人就得等。我的缓解办法有三条。第一任务分级把高优先级的临时任务放到轻量模型端口重任务走大模型端口避免互相抢资源。第二显存足够的时候可以同时加载两个模型一个偏快的小模型处理快速问答一个偏强的大模型处理深度重构。第三提前在网关层做简单限流或队列提示至少让成员知道当前是在排队而不是死机。7.4 一点关于“离线”的补充理解“离线”有两个层面的含义。一个是完全离线模型服务所在的机器和员工电脑都接入内网不访问外网另一个是“外网不可用时也能工作”机器本身可以联网但日常路径完全走内网模型。我建议不要追求绝对离线除非有硬性合规要求。适度联网仍有一些好处比如首次下载模型、偶尔拉取 npm 依赖、或者对比云端模型的效果。把“默认走内网、按需才出网”作为常态是体验和安全的平衡点。8. 常见问题与排查技巧实录配置流程走完不等于万事大吉真正的战斗在报错信息里。我把自己和同事遇到的高频问题整理成一张速查表按“症状—原因—对策”的格式写方便你直接按图索骥。8.1 高频报错速查表症状常见原因对策Claude Code 启动报错 internetopenurl failed安装阶段联网失败或本机外网受限在联网机器上完成 npm 全局安装再拷贝整个包目录到目标机器的全局 node_modules保证 Node.js 版本一致提示组织已禁用 Claude 订阅访问使用组织订阅认证但组织策略不允许改用个人 API key 或本地网关本地模型模式下不依赖订阅认证Claude Code 请求发出后立刻 404ANTHROPIC_BASE_URL 端口错误或网关没有启动确认网关端口在监听curl 检查网关地址是否能访问Claude Code 长时间转圈后超时本地模型推理慢默认超时太短把 settings.json 中 API_TIMEOUT_MS 调大建议 600000 以上Claude Code 提示查无模型模型名和本地服务实际加载名不一致查看 /v1/models 返回结果把真实模型 id 填进配置Codex 报 model not supported自定义提供者时仍走了官方模型路由或 wire_api 不匹配确认 model_provider 指向自定义提供者wire_api 设成 chat启动时显式指定 --modelCodex 报无法加载组织设置组织管理接口不可达或残留官方登录信息清除 config.toml 与用户目录里的官方登录信息本地提供者模式下组织设置不影响使用CC Switch 本地转发失败转发端口被占用、目标模型服务不通、协议不匹配依次检查转发进程、base_url 连通性、wire_api 是否正确局域网内其他机器连不上服务防火墙拦截端口或服务只监听 127.0.0.1放行端口确认 LM Studio 监听 0.0.0.0Ollama 设置 OLLAMA_HOST0.0.0.0长任务中途断连无线网络抖动或服务端排队超时模型服务走有线网络客户端调大超时必要时本地先跑完再同步8.2 我最常踩的三个坑第一个坑是“模型名不用心”。本地模型的 id 往往带着量化后缀比如qwen3_coder_14b_q4_k_m这种完整 id。你配置的模型名必须和 /v1/models 返回的 id 完全一致少一个下划线都连不上。别偷懒看 UI 上显示的展示名要看 API 返回的真实 id。第二个坑是“上下文窗口设置过高”。Claude Code 默认会按较大的上下文窗口来做请求本地模型的上下文如果只有 32K而请求把窗口撑得太大服务端会直接报错或者强行截断导致输出质量崩坏。需要在网关或模型服务里把上下文上限和请求协商值对齐。第三个坑是“密钥没设置导致认证失败”。我见过最多的本地接入问题不是地址错而是 API key 留空。Claude Code 只要发现没有 key就直接拒绝工作。记住本地网关不校验密钥但 CLI 需要看到一个非空的 key 才肯发请求。8.3 排查思路的通用套路如果看完速查表还没解决提供一个通用的定位流程。第一步换一个大模型验证 CLI 本身是否正常比如先用云端模型跑通一个最简单的任务。第二步用 curl 直接请求本地服务的接口验证服务端是否正常。第三步分别测网关和模型服务两跳的连通性。第四步看日志CLI 一般都有 debug 模式或日志文件把报错的上下文看清楚再动手。这四步走完90% 的问题都能定位到某一个环节。我在给别人远程排障时也一直用这个套路效率和直接猜答案完全不是一个量级。9. 一段时间的实操体会折腾这套离线 VibeCoding 方案到现在我最深的体会是它改变的不仅是“代码发不发外网”这个选择题更改变了编程助手的使用心智。以前用云端服务每次大型重构都提心吊胆看着消耗现在用本地模型我可以随时让编码 Agent “多试几个方案”成本压力几乎不存在。这种心理变化对产出质量的影响比想象中大得多。另一个体会是关于模型选择的。刚开始我以为离线方案的短板在模型能力后来发现真正的短板往往在模型“性格”——工具调用是否规整、是否会在长任务里跑偏、是否听得懂“别改了先跑一遍测试看看”这种半截指令。这些体验只有实测才知道但大体上认准专门的 Coder 系列模型不会错。云端强模型在绝对智商上仍然领先但对本地部署来说稳定、听话、不幻觉工具调用比所谓的“聪明”更重要。最后再分享一个小技巧。如果你打算长期维护这套方案把“模型服务启动检查”写成一个一键脚本curl 模型服务、检查显存占用、检查端口、打印当前加载的模型 id。团队成员在接入时只需跑一次这个脚本就能在 30 秒内判断环境是否健康。这套链路的真实价值在于稳定和可控而可控的前提永远是你能清楚地知道每一跳都在干什么。
离线VibeCoding：Claude Code/Codex接入本地模型全解析
1. VibeCoding 火了一年还在盯云 API 的人可以看看另一条路VibeCoding 从热度上来那天起就一直处在“编程方式之争”的漩涡中心。说人话就是不再一个字符一个字符地手写代码而是把需求、报错、甚至一句含糊的“给我搭一个内部用的报表系统”丢给 AI 编码助手由它完成读文件、改代码、跑命令、循环修复的全流程。Claude Code 和 Codex 是这一波里最受关注的两个命令行编码 AgentClaude Code 背靠 Anthropic 的模型能力交互节奏更像一个坐在旁边的工作伙伴Codex 是 OpenAI 的官方 CLI把 agentic 编码和代码评审一把抓。抛开“谁更强”不谈这两类工具默认都是走云端 API 的。代码要离开你的电脑送到公共接口去做推理。个人玩可能无所谓但放到公司内部项目、客户现场、或者对数据要求严格的环境里这就是硬伤。于是“局域网离线 VibeCoding”——把 Claude Code、Codex 这类前端工具接到本机或局域网内的大模型服务上——就成了一个非常现实的需求。好处很直接源码不出内网、不按 token 计费、没有外部接口的配额和频次限制日常用着也确实更省心。这篇文章不是概念科普而是我折腾完整套离线编程链路之后的实操记录。适合谁看正在用或准备用 Claude Code / Codex、手头有一台能跑模型的好机器、或者团队想在内部统一铺一套 AI 编码基础设施的开发者和运维。下面不废话直接讲架构、配置、模型选择、踩坑实录。1.1 Claude Code 和 Codex 的本质CLI 壳 模型内核要理解离线方案先得知道这两工具到底是什么。Claude Code 本体是一个 Node.js 命令行应用核心职能是维护会话上下文、拆分任务、决定调用哪个工具、解析模型的意图。它不包含模型模型是它背后的推理大脑。Claude Code 启动时读取环境变量里的 API 地址和密钥默认指向 Anthropic 的云端接口通过 Anthropic Messages API/v1/messages发送请求模型返回结构化回复CLI 再根据内容执行文件读写、终端命令等动作。Codex 同理。Codex CLI 是一个 Rust 编写的命令行编码 Agent默认走 OpenAI 的 Chat Completions/v1/chat/completions或者较新的 Responses API/v1/responses它的工具调用能力同样依赖模型。Codex 的配置自由度比 Claude Code 高一点原生支持“自定义模型提供者”——也就是说你可以不接 OpenAI 的官方接口而是指向任何一个 OpenAI 兼容的服务。这就是离线方案的着眼点模型接口是可以替换的。前端工具不变把背后的 API 地址从云端换成局域网里的推理服务就完成了“离线化”。剩下的核心工作只有两件事让本地推理服务提供一个可用的 API 格式以及把 Claude Code 或 Codex 的请求正确导过去。1.2 为什么非要离线加局域网很多人第一反应是明明是联网工具为什么要搞离线我的体会是离线不是倒退而是针对几种真实场景的必要妥协。第一个场景是代码保密。公司内部项目、未发布的产品线、客户定制的业务逻辑代码一旦发到外网 API就脱离了你的控制范围。哪怕平台承诺数据不用于训练合规和审计这两关也过不去。局域网本地部署之后推理在本地 GPU 上完成任何代码都不会离开内网这是最彻底的隔离方案。第二个场景是成本。按 token 计费的云端 API一次大型代码重构可能烧掉不少预算团队里十个人天天挂着这类编码 Agent月账单会很可观。本地模型一次性买硬件后续推理几乎零边际成本跑得再狠也就是电费。第三个场景是可用性。生产环境、客户现场往往网络条件受限或者外部接口的频次限制很严。离线部署之后只要内网通工具随时能用不受第三方服务波动影响。我把话说清楚离线不是要替代云端大模型——本地模型在很多复杂任务上确实不如顶尖云模型——离线是“可控”和“可落地”优先的替代选择。对大多数日常重构、补测试、写脚本的任务一个调教得当的本地模型完全够用。2. 离线链路的核心架构一条清晰的请求链路离线 VibeCoding 的整套链路用一句话概括就是Claude Code / Codex 作为前端把请求送到一个“本地网关”网关处理协议和路由后再把请求递交给局域网里的模型服务。拆开看是三个部件。2.1 三个部件的分工第一个部件是前端工具也就是 Claude Code 或 Codex 的 CLI。它负责维护对话、输出工具调用计划、展示生成结果。它只管发请求不关心背后是什么模型。第二个部件是本地模型服务常见的是 LM Studio 或 Ollama。它们在一台配置足够好、最好带独立 GPU 的机器上加载模型以 OpenAI 兼容接口的方式对外提供推理能力。LM Studio 默认端口是 1234Ollama 是 11434两者都支持开放局域网访问。第三个部件是“协议网关”。这一步不是所有教程都会提到但恰恰是坑最多的地方。Claude Code 默认说 Anthropic 的 Messages 协议而 LM Studio / Ollama 对外说的是 OpenAI 的 Chat Completions 协议。两种协议的请求体结构、工具调用表达方式都不一样。所以 Claude Code 不能直接指向 LM Studio 的地址中间必须有一个人能把 Anthropic 的请求翻译成 OpenAI 的请求。可选方案包括 LiteLLM 和 claude-code-routerCC Switch 这类管理工具则内置了类似的转发能力。Codex 就没那么麻烦。它的 config.toml 原生支持 model_providers可以直接把一个 OpenAI 兼容的 base_url 填进去只要协议匹配就能用。所以 Codex 接 LM Studio / Ollama 通常不需要额外的网关一台机器直连也行。2.2 为什么用网关而不是直接改 Claude Code每隔一段时间就有人问能不能直接把 Claude Code 的模型地址改成 LM Studio答案是可以改地址但协议不匹配时请求会直接失败。Claude Code 发的请求头里带着 anthropic-version请求体带 system、messages、tools 这些字段本地服务必须能正确解析并回答。如果自己写脚本去适配这套协议工作量和维护成本都很高。网关方案最省心——它在协议层做好兼容Claude Code 认为自己在跟 Anthropic 对话网关在背后替你把请求翻译给任何你想用的模型。选网关也有讲究。LiteLLM 是老牌方案能同时管理十几个供应商适合团队级基础设施claude-code-router 更轻专门给 Claude Code 与本地/第三方模型做桥接配置是 JSON 文件个人开发者用起来非常顺手。我两个都用过追求稳定和可复用选 LiteLLM追求快速上手选 claude-code-router。下文会分别给配置示例。2.3 模型选型的几个真实标准模型选什么直接决定离线 VibeCoding 好不好用。这个问题比很多人想得更关键——编码 Agent 对模型的“工具调用能力”要求远高于普通对话。首先必须支持 function calling / tool calling。Claude Code 和 Codex 都要靠模型输出结构化的工具调用指令来读写文件、执行命令。如果模型不会主动调用工具或者调用格式不稳定编码 Agent 就会变成“话痨而不干活”的摆设。许多通用对话模型看着聪明实际接进去后完全没法用就是这个原因。其次是上下文长度。编程任务动辄要读十几个文件上下文至少要 32K 以上建议选原生支持 64K 的模型。上下文不是越大越好还要考虑显存占用这个下面会详细算。最后是实际体感。就我的体验来说本地跑编码 AgentQwen3-Coder 系列和 GLM 的 Z 系列专门为 Agent 场景设计的版本表现比较好DeepSeek 的 Coder 系列也不错。这几种模型的工具调用格式规整能听懂“继续”“修复失败”“再看一眼测试”这种指令。我不推荐在代理场景里用参数太大但显存塞不下的模型——宁可 14B 高精度不要 30B 强量化后者在长链路任务里很容易“断片”。注意以上的“运行效果”指纯粹本地推理时的体感。不同版本、不同量化档位差异很大建议以实测为准。3. 软硬件准备先把模型服务跑起来先明确一件事模型服务必须跑在局域网内一台“能打”的机器上其他成员通过内网 IP 访问。这一步是离线方案的地基地基不牢后面全是扯皮。3.1 硬件底线和量化预算小算盘给一个诚实的硬件底线。只跑 7B 模型16GB 显存的显卡加 32GB 内存就够想舒服跑 14B 模型推荐 24GB 显存级别要跑 30B 以上的强模型得考虑双卡或大显存方案。内存带宽也很重要苹果 M 系列统一内存的机器跑大模型表现不错因为带宽高普通 PC 如果只靠 CPU 跑速度会非常痛苦不建议。量化预算有一个经验公式模型权重文件大小 上下文 KV cache必须能放进显存。以 14B 模型 Q4_K_M 为例权重约 89GB上下文 32K 时的 KV cache 约 24GB合计 12GB 左右。16GB 显卡会比较紧张但可运行24GB 则从容很多。别只看模型文件体积KV cache 虽然经常被忽略但长上下文编程场景里它是实打实的显存消耗大户。3.2 LM Studio 部署与局域网开放LM Studio 是目前本地推理里最省心的图形化方案。官网下载对应系统安装包装完在 Models 标签页搜索并下载模型比如 Qwen3-Coder-14B 的 Q4_K_M GGUF 文件。下载完成后进入 Developer 标签页选择模型并启动本地服务器。关键一步是局域网开放。较新版本的 LM Studio 默认服务绑定在 0.0.0.0也就是所有网卡都监听。如果不放心可以在启动服务的命令行里手动指定lms server start --host 0.0.0.0 --port 1234看到服务运行提示后先在本机验证curl http://localhost:1234/v1/models能返回模型列表说明服务起来了。然后在同一局域网的另外一台机器上执行同样的命令把地址换成 LM Studio 所在机器的内网 IPcurl http://192.168.1.100:1234/v1/models这个测试必须做因为后面所有 CLI 工具的 base_url 都会填这个内网地址。如果局域网访问不通八成是系统防火墙拦了 1234 端口放行即可。3.3 Ollama 部署与局域网开放如果团队更偏好命令行Ollama 是更轻的选择。我第一次接触时一条命令就跑起了模型干净利落。安装后拉取模型ollama pull qwen3-coder:14b默认情况下 Ollama 只监听本机回环地址 127.0.0.1不满足局域网共享需求。需要设置环境变量 OLLAMA_HOST。Linux/macOS 上export OLLAMA_HOST0.0.0.0:11434 ollama serveWindows 上更简单在系统环境变量里新建 OLLAMA_HOST值填 0.0.0.0保存后重启 Ollama 服务。然后同样用 curl 验证curl http://192.168.1.100:11434/v1/models注意 Ollama 的 OpenAI 兼容接口前缀是 /v1。Codex 直接指向这个地址就能用这也是 Ollama 在编码 Agent 场景里受欢迎的原因之一。3.4 一个容易忽略的点并发和资源要提前算好把服务跑起来之后我踩过最烦的坑是“并发”。本地模型服务不是多线程随便扛的显存有多大同时能承载的请求就有上限。LM Studio 和 Ollama 都默认单请求排队也就是说一个成员在跑大任务时其他人只能等。这对“局域网团队共享”来说是一个必须提前说清楚的限制。我的做法如果团队超过三个人就准备两套模型端口一个给高优先级重构任务一个给日常轻量任务如果只有一个人用单实例完全够。另外建议把模型服务的机器放在有线网络里无线环境下长任务偶发断连会让 CLI 工具非常痛苦。4. Claude Code 接入本地模型的完整配置Claude Code 的接入是整个方案里“协议翻译”最明显的一环也是出错率最高的地方。我把它拆成安装、网关、settings.json、验证四个步骤。4.1 安装方式与离线机器的应对Claude Code 是 npm 包正常安装一步到位npm install -g anthropic-ai/claude-code但局域网离线机器的典型困境是机器本身没有外网npm 装不了。我的应对是在一台临时能联网的机器上先完成安装然后把全局 node_modules 里的 anthropic-ai 目录整体拷贝到离线机器的对应位置。Windows 上是%APPDATA%\npm\node_modulesLinux 是/usr/lib/node_modules或用户目录下的.npm-global。拷贝完成后执行claude --version验证。这个办法实测可行麻烦在于离线机器的 Node.js 版本要和拷贝来源机器基本一致否则二进制兼容性会出问题。另外如果安装时报 Windows 的 WinINet 错误比如internetopenurl() failed 0x8009Fxxx基本可以定位到网络访问问题。对策就是上面说的“联网机器装好再拷贝”或者检查 npm 源是否可用。4.2 搭一个本地网关两种我都试过先讲 claude-code-router。安装命令npm install -g musistudio/claude-code-router配置写在~/.claude-code-router/config.json一个最小可用配置如下{ provider: lmstudio, providers: { lmstudio: { baseUrl: http://192.168.1.100:1234/v1, apiKey: lmstudio } }, model: qwen3-coder-14b }不同版本的配置键名可能有差异安装后先执行ccr --help看说明确认 provider 名称和配置字段。启动后它会在本地开一个监听端口默认 3456Claude Code 把请求发给这个端口路由器再转发给 LM Studio。LiteLLM 网关是另一条路。安装和启动pip install litellm[proxy] litellm --config config.yamlconfig.yaml 里把模型指向 LM Studiomodel_list: - model_name: qwen3-coder-14b litellm_params: model: openai/qwen3-coder-14b api_base: http://192.168.1.100:1234/v1 api_key: localLiteLLM 启动后默认监听 4000 端口自带 Anthropic 兼容的 /v1/messages 接口Claude Code 可以直接对接。这正是我前面说的“网关做协议翻译”的标准实现。4.3 让 Claude Code 指向网关的三种配置方式最推荐的方式是改 Claude Code 的配置文件~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:3456, ANTHROPIC_API_KEY: local-key, ANTHROPIC_MODEL: qwen3-coder-14b, ANTHROPIC_DEFAULT_SONNET_MODEL: qwen3-coder-14b, ANTHROPIC_DEFAULT_HAIKU_MODEL: qwen3-coder-14b, API_TIMEOUT_MS: 600000 } }几个字段逐个说明。ANTHROPIC_BASE_URL 指向网关地址router 是 3456LiteLLM 是 4000不要直接指向 LM Studio。ANTHROPIC_API_KEY 随便填一个非空值因为本地网关不校验密钥但留空的话 Claude Code 会拒绝工作。ANTHROPIC_MODEL 和两个 DEFAULT 模型字段统一设成网关上配置的模型名否则 Claude Code 会按默认模型名去找导致网关查无此模型。API_TIMEOUT_MS 必须调大本地模型每步推理在几秒到十几秒之间默认超时在长任务里根本不够。第二种方式是直接导出环境变量适合临时验证export ANTHROPIC_BASE_URLhttp://localhost:3456 export ANTHROPIC_API_KEYlocal export ANTHROPIC_MODELqwen3-coder-14b claude第三种方式是使用 CC Switch 这类工具统一管理点选一下就能切换适合经常在云端和本地之间来回切换的人。它的原理其实也是帮你改 ANTHROPIC_BASE_URL背后可能还会起一层本地转发。这个工具我在第 6 节单独讲。4.4 验证接入成功的关键信号配置完之后不要急着干重活先做冒烟测试。在 Claude Code 里输入“你好请告诉我你当前使用的模型名称并简单说明你能做什么。”如果配置正确你会看到响应内容来自本地模型。如果报错按下面三种现象对号入座请求发出后立刻 404检查 ANTHROPIC_BASE_URL 端口是不是写错了请求能到网关但返回 401检查 API key 是否为空请求一直转圈然后超时大概率是本地模型推理太慢把 API_TIMEOUT_MS 再往上调。冒烟通过之后建议跑一个真实的小任务让 Claude Code 在临时目录里创建一个 Python 脚本完成一个 CSV 文件的排序和去重并要求它执行验证。这个任务同时覆盖了文件读写、命令执行和错误修复三个核心工具调用能比较全面地检验本地模型在 Agent 场景下的可用性。5. Codex 接入本地模型与第三方模型的配置Codex 的接入逻辑和 Claude Code 不同它原生支持自定义模型提供者不需要中间网关。这个设计省了很多事但也带来了一个比较隐蔽的坑默认模型路由和请求格式问题。5.1 安装 Codex 与初始化Codex CLI 目前的分发方式之一是 npmnpm install -g openai/codex安装完成后先执行一次codex让它生成默认配置目录~/.codex/。第一次运行会引导登录如果目标是本地模型这一步可以跳过——直接编辑配置文件即可。配置文件是 TOML 格式位于~/.codex/config.toml。5.2 model_providers 配置与关键参数Codex 的配置核心是 model_providers 这一段。接 LM Studio 的配置示例model_provider lmstudio [model_providers.lmstudio] name LM Studio Local base_url http://192.168.1.100:1234/v1 env_key LMSTUDIO_API_KEY wire_api chat接 Ollama 的配置示例model_provider ollama [model_providers.ollama] name Ollama Local base_url http://192.168.1.100:11434/v1 env_key OLLAMA_API_KEY wire_api chatmodel_provider 指定默认提供者base_url 指向局域网模型服务env_key 是一个环境变量名Codex 会从这里读取 API key本地服务不需要真实密钥但环境变量必须存在且非空否则 Codex 会认为没有认证信息。可以在 shell 配置里加一行export LMSTUDIO_API_KEYlocal或者直接在系统环境变量里设置。wire_api 是最关键的字段。Codex 默认走它偏好的 responses 接口而本地模型服务普遍只支持 chat 接口。把 wire_api 设成 chat 之后Codex 会用 OpenAI 兼容的 chat completions 格式发请求本地服务才能正确理解。如果不设这个字段很多本地模型会在第一轮请求就报“model not supported”或者直接 404。5.3 跑通 Codex 加本地模型的完整动作配置完成后启动时指定模型名codex --model qwen3-coder-14b模型名必须和你本地服务里已加载的模型名称一致。如果不加 --modelCodex 会按默认模型列表去找本地服务里没有就会报错。更稳妥的做法是把默认模型也写在 config.toml 里这样直接codex就能用。还有一个值得注意的动作关闭 Codex 对模型路由的预检。Codex 启动时会尝试加载组织设置和模型路由表如果这些请求走不到就会出现类似“无法加载组织设置”的报错。这时候检查两点一是认证相关的环境变量是否配置正确二是在使用第三方提供者时确认 config.toml 中没有残留任何官方账户的登录信息。本地模型模式下组织信息其实无关紧要Codex 只要能把请求发到 base_url 就算成功。5.4 接第三方开放 APIDeepSeek、Qwen、GLM 同样适用不只是本地模型Codex 也可以接第三方开放 API。原理和接 LM Studio 完全一致写一个 model_provider把 base_url 换掉。以 DeepSeek 为例model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后设置 DEEPSEEK_API_KEY 为你的真实 API key启动时codex --model deepseek-chat即可。需要注意第三方 API 的模型名称要按服务商文档来不要自己臆造。Qwen、GLM 的服务商对外也都提供 OpenAI 兼容接口写法大同小异灵活度相当高。这种“把 Codex 导向第三方 API”的做法特别适合想体验 agentic coding 又不想在本地配 GPU 服务器的人。它虽然不是离线但同样绕开了对单一官方服务的强依赖是一种务实折中。当然凡是把代码发到外部 API 的场景数据安全边界要自己把关。6. CC Switch端点切换工具的使用与报错排查CC Switch 是近半年被提得非常多的工具它的定位是“给多个 AI 编程工具做模型端点配置管理”。它的价值在于当你在官方 API、第三方平台 API、本地模型地址之间反复切换时不用反复手改 settings.json 或 config.toml点一下就能切换。6.1 CC Switch 到底帮你做了什么CC Switch 干了三件事。第一件事是管理配置把不同提供者的 base_url、模型名、密钥集中存储每个提供者对应一套参数。第二件事是切换生效一键把当前模型提供者从 A 切到 B。第三件事往往被忽略——它很多时候会启动一个本地转发通道把 Claude Code 或 Codex 的请求先接到自己这里再按配置转发给目标模型服务。正是这第三件事成为不少报错的来源。这里有个概念要澄清本地转发通道属于“请求路由”和我之前讲的“协议转换网关”不完全是一回事。路由只负责把请求送到目标格式转换才是真正解决协议不匹配的部分。只有路由而协议不翻译时Claude Code 接 LM Studio 依然不通。所以判断 CC Switch 是否适合你要看它是否针对你用的工具做了完整的协议适配而不只是配了个地址。6.2 配置示例与常见用法以 Claude Code 为例在 CC Switch 里新增一个提供者名称填“本地 Qwen”类型选择 Claude Code地址填 http://localhost:3456如果你用了 claude-code-router 做网关模型填 qwen3-coder-14b密钥随意。保存后点“应用”它会自动改写~/.claude/settings.json里的环境变量。下一次启动 claude 时请求就直接走本地链路。Codex 类似但更简单。新增提供者时选择 Codex类型填本地模型它会帮你写 config.toml 的 model_providers 段落。因为 Codex 不需要格式转换网关CC Switch 在这里起的作用更偏向配置管理。6.3 高频报错本地转发失败该怎么查有一个报错关键词很典型“CC Switch 本地转发失败处理 Codex 端点 /responses 时出错”。如果你碰到的是同类报错本质是 CC Switch 启动的那个本地转发服务在处理请求时崩了。我建议按这个顺序排查。第一步看转发服务本身。CC Switch 的转发依赖一个本地端口如果端口被占用或者转发进程没起来就会报这个错。在命令行里看看端口监听状态确认 CC Switch 有正常监听。第二步看目标地址连通性。转发服务最终要把请求送到 base_url 指定的模型服务。如果模型服务没启动、IP 写错、防火墙拦了端口转发失败只是表象根因在目标服务。先单独用 curl 验证 base_url 能不能通。第三步看协议匹配。报错里的 /responses 路径很关键——如果转发服务把请求按 responses 格式发给一个只支持 chat 格式的本地模型目标服务会直接拒绝。解决办法仍然是确保 codex 的 wire_api 设成 chat或者使用做好协议转换的工具。最后说一句如果 CC Switch 在你用的组合里反复出问题不要死磕它。它只是管理工具直接手改配置文件往往更可控。工具是给人省事的不是给人添堵的。7. 局域网多机共享与团队协作要点离线方案的终点通常不是“自己一个人用”而是“团队里每个人都用”。多机共享的难点不在于配置——那只是把 IP 从 localhost 改成内网 IP——而在于资源控制和体验一致性。7.1 把模型服务做成“服务器模式”如果是团队共享建议把模型服务单独部署在一台固定 IP 的机器上不要跑在某个成员的笔记本里。原因很实际笔记本会关机、会休眠、会被拿去开会。模型服务应该像一台常规服务器一样常年在线。机器选型上内存和显存按团队峰值并发来配一般三四个人同时用单张 24GB 显卡配 14B 模型是起步线长期用建议预留 50% 富余。所有成员的 base_url 都填同一台机器的内网 IP例如 http://192.168.10.20:1234/v1LM Studio或 http://192.168.10.20:11434/v1Ollama。配置文件里的模型名保持完全一致。这一步做完每个成员本地只需要装好 Claude Code / Codex 和各自的网关配置就能连上同一个共建的 AI 编程大脑。7.2 访问控制与接口保护局域网不等于完全开放。模型服务虽然没有业务数据但被人恶意调用也会造成资源浪费。两个实用的控制手段一是在模型服务机器上配置防火墙只允许内网网段访问对应端口二是如果选择 Ollama它的 API 本身支持简单的请求校验搭配一层轻量的网络隔离就够用。LM Studio 目前没有内置鉴权更依赖网络层面的控制。安全水位自己把握至少不要直接暴露到不可信的网络里。另外我强烈建议给成员发一份简短的“接入说明”把 base_url、模型名、环境变量设置、验证命令写清楚。团队里不是每个人都熟 TOML 和 JSON一份说明能减少一半的“帮我看看为什么我的连不上”的问题。7.3 并发与排队如何让团队体验不那么痛苦并发控制是局域网共享的体验分水岭。本地推理服务默认是排队执行的一个人发了一个超长重构任务另外两个人就得等。我的缓解办法有三条。第一任务分级把高优先级的临时任务放到轻量模型端口重任务走大模型端口避免互相抢资源。第二显存足够的时候可以同时加载两个模型一个偏快的小模型处理快速问答一个偏强的大模型处理深度重构。第三提前在网关层做简单限流或队列提示至少让成员知道当前是在排队而不是死机。7.4 一点关于“离线”的补充理解“离线”有两个层面的含义。一个是完全离线模型服务所在的机器和员工电脑都接入内网不访问外网另一个是“外网不可用时也能工作”机器本身可以联网但日常路径完全走内网模型。我建议不要追求绝对离线除非有硬性合规要求。适度联网仍有一些好处比如首次下载模型、偶尔拉取 npm 依赖、或者对比云端模型的效果。把“默认走内网、按需才出网”作为常态是体验和安全的平衡点。8. 常见问题与排查技巧实录配置流程走完不等于万事大吉真正的战斗在报错信息里。我把自己和同事遇到的高频问题整理成一张速查表按“症状—原因—对策”的格式写方便你直接按图索骥。8.1 高频报错速查表症状常见原因对策Claude Code 启动报错 internetopenurl failed安装阶段联网失败或本机外网受限在联网机器上完成 npm 全局安装再拷贝整个包目录到目标机器的全局 node_modules保证 Node.js 版本一致提示组织已禁用 Claude 订阅访问使用组织订阅认证但组织策略不允许改用个人 API key 或本地网关本地模型模式下不依赖订阅认证Claude Code 请求发出后立刻 404ANTHROPIC_BASE_URL 端口错误或网关没有启动确认网关端口在监听curl 检查网关地址是否能访问Claude Code 长时间转圈后超时本地模型推理慢默认超时太短把 settings.json 中 API_TIMEOUT_MS 调大建议 600000 以上Claude Code 提示查无模型模型名和本地服务实际加载名不一致查看 /v1/models 返回结果把真实模型 id 填进配置Codex 报 model not supported自定义提供者时仍走了官方模型路由或 wire_api 不匹配确认 model_provider 指向自定义提供者wire_api 设成 chat启动时显式指定 --modelCodex 报无法加载组织设置组织管理接口不可达或残留官方登录信息清除 config.toml 与用户目录里的官方登录信息本地提供者模式下组织设置不影响使用CC Switch 本地转发失败转发端口被占用、目标模型服务不通、协议不匹配依次检查转发进程、base_url 连通性、wire_api 是否正确局域网内其他机器连不上服务防火墙拦截端口或服务只监听 127.0.0.1放行端口确认 LM Studio 监听 0.0.0.0Ollama 设置 OLLAMA_HOST0.0.0.0长任务中途断连无线网络抖动或服务端排队超时模型服务走有线网络客户端调大超时必要时本地先跑完再同步8.2 我最常踩的三个坑第一个坑是“模型名不用心”。本地模型的 id 往往带着量化后缀比如qwen3_coder_14b_q4_k_m这种完整 id。你配置的模型名必须和 /v1/models 返回的 id 完全一致少一个下划线都连不上。别偷懒看 UI 上显示的展示名要看 API 返回的真实 id。第二个坑是“上下文窗口设置过高”。Claude Code 默认会按较大的上下文窗口来做请求本地模型的上下文如果只有 32K而请求把窗口撑得太大服务端会直接报错或者强行截断导致输出质量崩坏。需要在网关或模型服务里把上下文上限和请求协商值对齐。第三个坑是“密钥没设置导致认证失败”。我见过最多的本地接入问题不是地址错而是 API key 留空。Claude Code 只要发现没有 key就直接拒绝工作。记住本地网关不校验密钥但 CLI 需要看到一个非空的 key 才肯发请求。8.3 排查思路的通用套路如果看完速查表还没解决提供一个通用的定位流程。第一步换一个大模型验证 CLI 本身是否正常比如先用云端模型跑通一个最简单的任务。第二步用 curl 直接请求本地服务的接口验证服务端是否正常。第三步分别测网关和模型服务两跳的连通性。第四步看日志CLI 一般都有 debug 模式或日志文件把报错的上下文看清楚再动手。这四步走完90% 的问题都能定位到某一个环节。我在给别人远程排障时也一直用这个套路效率和直接猜答案完全不是一个量级。9. 一段时间的实操体会折腾这套离线 VibeCoding 方案到现在我最深的体会是它改变的不仅是“代码发不发外网”这个选择题更改变了编程助手的使用心智。以前用云端服务每次大型重构都提心吊胆看着消耗现在用本地模型我可以随时让编码 Agent “多试几个方案”成本压力几乎不存在。这种心理变化对产出质量的影响比想象中大得多。另一个体会是关于模型选择的。刚开始我以为离线方案的短板在模型能力后来发现真正的短板往往在模型“性格”——工具调用是否规整、是否会在长任务里跑偏、是否听得懂“别改了先跑一遍测试看看”这种半截指令。这些体验只有实测才知道但大体上认准专门的 Coder 系列模型不会错。云端强模型在绝对智商上仍然领先但对本地部署来说稳定、听话、不幻觉工具调用比所谓的“聪明”更重要。最后再分享一个小技巧。如果你打算长期维护这套方案把“模型服务启动检查”写成一个一键脚本curl 模型服务、检查显存占用、检查端口、打印当前加载的模型 id。团队成员在接入时只需跑一次这个脚本就能在 30 秒内判断环境是否健康。这套链路的真实价值在于稳定和可控而可控的前提永远是你能清楚地知道每一跳都在干什么。
