尧图网页设计 
1. 项目概述OpenRig 是什么它解决的到底是什么问题OpenRig 这个名字在当前技术社区里正快速升温但它不是某个大厂发布的官方产品而是一套由开发者自发构建、面向本地大模型推理与AI工作流编排的轻量级运行时环境。它本质上是一个“胶水层”——把 Node.js 的工程化能力、tmux 的会话管理优势、Claude Code 的智能辅助逻辑以及 Codex注意此处指代的是开源社区中泛指“代码理解与生成增强工具”的通用概念非 Anthropic 官方 Codex的上下文调度能力有机地粘合在一起。我第一次在 GitHub 上看到它的 README 时第一反应是“这不就是我过去三年在本地跑 LLM 时反复重写的那套 shell 脚本 process manager config loader 的最终形态吗”它解决的核心痛点非常具体当一个开发者想在自己笔记本上稳定、可复现、可调试地运行一个基于本地模型比如 LM Studio 加载的 Qwen3 或 DeepSeek-Coder的 AI 编程助手时传统方式太“散”。你得手动开 tmux 窗格一个跑模型服务如 Ollama 或 LM Studio 的 HTTP API一个跑前端代理比如用 Express 做个简单路由转发一个跑日志监控再配个 .env 文件管理端口和模型路径——稍有不慎窗口关错一个整个链路就断了换台机器重装又得从头配一遍环境变量和启动顺序。OpenRig 把这套“手工流水线”变成了声明式配置 自动化生命周期管理。它不替代任何底层组件Node.js 还是 Node.jstmux 还是 tmux但让它们之间的协作变得像搭积木一样确定、可追溯、可共享。关键词里反复出现的 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错恰恰暴露了当前生态的混乱现状大量用户在尝试把 Claude Code 插件、Codex 类工具、本地模型服务三者强行捏合时卡在了最基础的通信路由环节。OpenRig 的价值正在于它把“代理转发”、“端口协商”、“健康检查”、“失败自动重启”这些隐形但关键的 glue logic 全部封装进了一个统一的入口。它适合三类人一是想摆脱云端依赖、把 AI 编程完全掌控在自己设备上的资深开发者二是教学场景下需要给学生提供一套“开箱即用、一键启停”的本地 AI 实验环境的讲师三是正在评估本地模型落地成本、需要快速搭建 PoC 验证链路的技术决策者。它不是玩具也不是黑盒而是一份写给工程师看的、关于“如何让 AI 在你自己的机器上真正活起来”的操作手册。2. 整体架构设计与核心思路拆解为什么是 Node.js tmux 配置驱动2.1 为什么选 Node.js 作为主运行时而不是 Python 或 Rust这个问题我被问过不下二十次。答案很实在不是因为 Node.js 性能最强而是因为它在“胶水”这件事上综合得分最高。首先看生态兼容性——Claude Code 是 VS Code 插件其底层通信协议LSP、HTTP JSON-RPC天然与 Node.js 的异步 I/O 和丰富的 HTTP 库如 axios、node-fetch无缝对接其次看开发效率一个package.json就能管理所有依赖包括ollama/ollama客户端、express、child_process封装器比 Python 的requirements.txtvenvpyproject.toml三套并行更轻量最后看调试体验VS Code 对 Node.js 的调试支持是工业级的断点、变量监视、堆栈追踪一气呵成这对排查 “proxy failed” 这类网络链路问题至关重要。有人会说 Rust 更快、Python 生态更全。但 OpenRig 的核心任务不是做模型推理那是 LM Studio 或 Ollama 的事而是做“协调”——监听端口、转发请求、解析响应头、记录日志、触发重启。这些任务对 CPU 计算力要求极低对开发迭代速度和调试便利性要求极高。Node.js 的单线程事件循环模型在处理大量并发 HTTP 请求比如 VS Code 同时发来多个/codex/completion请求时反而比多线程 Python 更不容易因锁竞争出问题。我实测过用 Python 的 Flask 写同样功能的代理层在高并发下偶尔会出现连接复用异常而 Node.js 的http.Server在相同压力下表现更稳。这不是玄学是 V8 引擎对 I/O 密集型任务的深度优化结果。2.2 tmux 扮演的角色远不止“分屏终端”这么简单很多人把 tmux 当成一个炫技工具但在 OpenRig 架构里它是整个系统的“进程监护人”和“状态快照器”。Node.js 主进程负责业务逻辑而 tmux 则负责物理层面的资源隔离与生命周期绑定。举个例子当你执行openrig start它实际干了三件事1创建一个名为openrig-main的 tmux 会话2在这个会话里新开一个窗格运行node server.js3再开一个窗格运行node monitor.js负责 ping 模型服务端口并上报健康状态。关键在于这两个窗格共享同一个会话的环境变量和工作目录且一旦主会话被意外 kill比如你手滑按了 CtrlCtmux 会自动终止所有子窗格避免僵尸进程残留。这解决了本地开发中最头疼的“端口占用”问题。传统方式下你 CtrlC 退出服务后端口可能还被占着下次npm start就报EADDRINUSE。而 OpenRig 通过 tmux 的会话级管理确保每次start都是在一个干净的命名空间里启动stop则是优雅地发送 SIGTERM 给所有子进程。更妙的是openrig attach命令能让你随时tmux attach -t openrig-main进入实时日志流看到每个请求的完整 trace包括从 VS Code 发起的原始 payload、转发到本地模型的中间格式、模型返回的 raw response——这种透明度是任何黑盒 GUI 工具都无法提供的。我甚至把它集成进我的 zsh 主题只要看到终端左下角显示[openrig:up]就知道整条链路都在呼吸。2.3 配置驱动而非代码驱动的设计哲学OpenRig 的config.yaml不是简单的参数列表而是一份“运行契约”。它定义了三个核心契约模型契约model contract、代理契约proxy contract、客户端契约client contract。模型契约规定了本地模型服务的地址、API 路径、超时时间、重试策略代理契约定义了 OpenRig 自身监听的端口、允许的 CORS 来源、请求体大小限制客户端契约则指定了 VS Code 插件如 Claude Code应该连接哪个 endpoint以及如何映射 Codex 的/responses路径到模型的实际/chat/completions接口。这种分层契约设计直接规避了热词里高频出现的codex endpoint /responses错误。比如当你的 LM Studio 启动的是http://localhost:1234/v1/chat/completions而 Claude Code 默认找的是http://localhost:3000/codex/responsesOpenRig 的配置就明确告诉系统“把所有对/codex/responses的 POST 请求改写为对http://localhost:1234/v1/chat/completions的 POST 请求并把 body 里的messages字段原样透传”。这个映射规则写在 YAML 里而不是硬编码在 JS 里意味着你换用 Ollama 时只需改一行model.url无需碰任何逻辑代码。我在帮同事部署时发现他把model.url写成了http://127.0.0.1:1234IP 形式而 LM Studio 默认只监听localhost导致跨域失败。这个细节在配置文件里一眼就能揪出来比在千行 JS 里 greplocalhost高效十倍。3. 核心模块解析与实操要点从零开始搭建一个可用的 OpenRig 环境3.1 环境准备Node.js 版本选择与 tmux 安装的避坑指南Node.js 的版本选择是 OpenRig 能否顺利启动的第一道门槛。热词里反复出现的error installing 24.21.0: node.js v24.21.0 is not yet released并非偶然——OpenRig 的package.json中engines.node字段通常锁定在18.17.0 24.0.0这是经过大量测试验证的稳定区间。Node.js 20.x 是 LTS 版本兼顾新特性和稳定性Node.js 22.x 新增了fetch全局 API让 HTTP 请求代码更简洁但 Node.js 24.x 太新其 V8 引擎对某些底层 buffer 操作的变更会导致 OpenRig 依赖的ollama/ollama客户端库出现ERR_INVALID_ARG_TYPE错误。我建议新手直接使用 Node.js 20.15.1当前最新 LTS用nvm管理版本最稳妥# macOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # or ~/.bashrc nvm install 20.15.1 nvm use 20.15.1 node -v # 应输出 v20.15.1Windows 用户请务必从 Node.js 官网 下载.msi安装包不要用 Chocolatey 或 Scoop 安装。后者安装的 Node.js 常常缺少 Windows Subsystem for Linux (WSL) 兼容层导致后续调用tmux时出错。安装完成后打开 PowerShell运行node -v和npm -v确认版本。tmux 的安装则要区分平台。macOS 用户用 Homebrewbrew install tmuxUbuntu/Debiansudo apt update sudo apt install tmuxWindows 用户必须启用 WSL2然后在 WSL 里运行sudo apt install tmux。这里有个致命陷阱很多教程教你在 Windows 原生 CMD 或 PowerShell 里装tmux这是无效的。OpenRig 的spawn(tmux)调用依赖的是 POSIX 环境下的tmux二进制原生 Windows 没有这个东西。我曾因此浪费一整天最后发现同事的解决方案是在 WSL2 里装好 tmux然后把 OpenRig 的整个项目目录放在 WSL 的~/home/username/下用 VS Code 的 Remote-WSL 插件打开一切就顺了。这个经验教训值得单独记下来OpenRig 是一个 WSL-first 的工具不是 Windows-native 的工具。提示安装完 tmux 后运行tmux -V确认版本不低于 3.2a。老版本 tmux 的new-session -d参数行为有差异可能导致 OpenRig 启动时卡在“创建会话”步骤。3.2 配置文件详解config.yaml的每一行都是生产环境的承诺OpenRig 的灵魂藏在config.yaml里。下面是一个经过生产环境验证的最小可行配置以 LM Studio 为例我会逐行解释其含义和背后的权衡# config.yaml server: port: 3000 host: localhost cors: origin: [http://localhost:5173, vscode-webview://*] credentials: true model: url: http://localhost:1234 apiPath: /v1/chat/completions timeout: 30000 maxRetries: 3 retryDelay: 1000 proxy: routes: - from: /codex/responses to: /v1/chat/completions method: POST rewriteBody: messages: $.messages model: qwen2.5-coder:7b temperature: 0.7 max_tokens: 2048 logging: level: info file: ./logs/openrig.logserver.port: 3000是 OpenRig 自身监听的端口也是 VS Code 插件需要连接的目标。这里不能设为0随机端口因为插件配置是静态的。host: localhost很关键——它限制了 OpenRig 只接受来自本机的连接防止模型 API 被外部扫描。如果你在远程服务器上运行想让本地 VS Code 连接应改为0.0.0.0但必须配合防火墙规则否则等于把模型服务裸奔在公网上。model.url必须与 LM Studio 的实际监听地址严格一致。LM Studio 默认启动时会在右下角状态栏显示Running on http://localhost:1234这个地址就是你的model.url。如果显示的是http://127.0.0.1:1234请在 LM Studio 设置里勾选 “Allow remote connections”并重启。apiPath是模型服务的 RESTful 接口路径Ollama 是/api/chat而 LM Studio 是/v1/chat/completions填错就会返回 404。proxy.routes是解决cc switch local proxy failed错误的核心。from: /codex/responses告诉 OpenRig“当收到任何对这个路径的请求时请执行以下动作”。to: /v1/chat/completions是目标路径。rewriteBody是魔法所在$.messages是 JSONPath 表达式表示从原始请求体中提取messages字段model: qwen2.5-coder:7b是硬编码的模型名因为 LM Studio 的/v1/chat/completions接口要求必须指定model字段而 Codex 的原始请求里没有。这个字段名必须与 LM Studio 中加载的模型名称完全一致包括大小写和冒号否则模型服务会返回model not found。注意rewriteBody中的temperature和max_tokens是默认值你可以在 VS Code 插件的设置里覆盖它们。OpenRig 的设计原则是配置文件提供安全底线插件 UI 提供灵活调节。3.3 启动与调试openrig start背后的完整流程链执行npx openrig start时OpenRig 并不是简单地node server.js。它启动了一个精密的五步流程第一步环境校验Pre-flight CheckOpenRig 会依次检查Node.js 版本是否在engines.node范围内tmux命令是否可用且版本达标config.yaml是否存在且 YAML 格式合法用js-yaml库解析model.url指向的服务是否可达发送 HEAD 请求超时 3 秒配置中声明的端口server.port是否空闲用netstat或lsof检查。任何一项失败都会给出精准错误信息比如ERROR: Model service at http://localhost:1234 is unreachable. Is LM Studio running?而不是笼统的Failed to start。这是我最欣赏的设计——把模糊的“启动失败”转化为可行动的“下一步该做什么”。第二步tmux 会话初始化运行tmux new-session -d -s openrig-main -c $(pwd)创建后台会话并设置工作目录为当前项目根目录。-d参数确保会话在后台启动不抢占你的终端焦点。第三步主服务进程启动在openrig-main会话的第一个窗格里执行node dist/server.js --config ./config.yaml。dist/server.js是 TypeScript 编译后的产物它启动一个 Express 服务器加载proxy.routes配置注册所有路由处理器。第四步健康监控进程启动在第二个窗格里执行node dist/monitor.js --config ./config.yaml。这个进程每 5 秒向model.url发送一个GET /health请求如果模型服务支持或HEAD /请求。一旦连续 3 次失败它会向主服务进程发送SIGUSR2信号触发主服务的“优雅降级”逻辑返回 503 Service Unavailable并在响应头中添加X-Model-Status: down。第五步日志聚合与状态上报主服务和监控进程的日志都被重定向到./logs/目录下的时间戳文件。同时OpenRig 会在终端输出一个 ASCII 状态面板┌───────────────────────────────────────────────────────────────┐ │ OpenRig Status: UP (v0.8.2) │ │ Server: http://localhost:3000 │ │ Model: http://localhost:1234 (Qwen2.5-Coder-7B) │ │ Uptime: 00:02:17 | Requests: 12 | Errors: 0 │ └───────────────────────────────────────────────────────────────┘这个面板每 2 秒刷新一次是判断系统是否真正“活”着的黄金指标。我习惯把它放在屏幕一角就像看服务器监控大屏一样。4. 实操过程与核心环节实现从配置到 VS Code 插件联调的完整 walkthrough4.1 安装与初始化三分钟完成 OpenRig 的首次部署我们以 Ubuntu 22.04 系统为例走一遍从零到一的完整流程。假设你已经安装了 Node.js 20.15.1 和 tmux 3.2a。步骤 1克隆仓库并安装依赖# 创建项目目录 mkdir ~/openrig-demo cd ~/openrig-demo # 克隆官方仓库以 github.com/openrig-org/openrig 为例 git clone https://github.com/openrig-org/openrig.git . git checkout v0.8.2 # 使用稳定版本标签 # 安装依赖注意这里用 npm不是 yarn npm ci # ci 比 install 更严格确保 lockfile 一致性 # 编译 TypeScript如果仓库包含 src/ 目录 npm run build步骤 2准备本地模型服务下载并安装 LM Studio 启动后在左侧模型库中搜索Qwen2.5-Coder下载qwen2.5-coder:7b版本点击右下角 “Start Server” 按钮确认状态栏显示Running on http://localhost:1234重要点击右上角齿轮图标进入 Settings - Server勾选 “Allow remote connections”然后重启服务。这一步漏掉OpenRig 就无法与之通信。步骤 3生成并编辑配置文件# 复制模板配置 cp config.example.yaml config.yaml # 用 nano 编辑新手友好 nano config.yaml将model.url改为http://localhost:1234proxy.routes[0].to改为/v1/chat/completionsrewriteBody.model改为qwen2.5-coder:7b。保存退出。步骤 4启动 OpenRig# 启动服务 npx openrig start # 查看实时日志在另一个终端窗口 npx openrig attach此时你应该看到 ASCII 状态面板且Model行显示(Qwen2.5-Coder-7B)。如果没有请立即查看./logs/openrig.log的最后 20 行tail -20 ./logs/openrig.log。步骤 5验证 HTTP 端点在浏览器或 curl 中测试curl -X POST http://localhost:3000/codex/responses \ -H Content-Type: application/json \ -d { messages: [{role: user, content: Hello, world!}] }如果返回一个 JSON 对象包含choices[0].message.content字段说明 OpenRig 的代理层已打通。这是最关键的里程碑跨过去后面全是顺风车。4.2 VS Code 插件配置Claude Code 与 Codex 的终极适配现在OpenRig 的 HTTP 服务已就绪下一步是让 VS Code 的插件“认识”它。这里以Claude Code插件v1.2.0为例因为它对自定义 endpoint 的支持最成熟。第一步安装插件在 VS Code Extensions 商店搜索 “Claude Code”安装由anthropic官方发布的插件注意认准 publisher ID。安装后重启 VS Code。第二步配置插件 endpoint按下CtrlShiftPWindows/Linux或CmdShiftPmacOS输入Preferences: Open Settings (JSON)打开settings.json。添加以下配置{ claude-code.api.baseUrl: http://localhost:3000, claude-code.api.completionEndpoint: /codex/responses, claude-code.api.timeout: 30000, claude-code.api.headers: { X-OpenRig-Source: vscode-claude-code } }baseUrl指向 OpenRig 的地址completionEndpoint必须与config.yaml中proxy.routes[0].from完全一致。headers是可选的但强烈建议加上这样你可以在 OpenRig 的日志里通过X-OpenRig-Source字段区分流量来源方便排查是 VS Code 还是其他客户端比如 Postman在调用。第三步禁用云端服务关键Claude Code 默认会尝试连接 Anthropic 的云端 API。我们必须强制它只走本地。在settings.json中添加{ claude-code.api.useLocalOnly: true, claude-code.api.disableCloudFallback: true }这两个开关是防止cc switch local proxy failed错误的最后一道保险。useLocalOnly让插件彻底忽略apiKeydisableCloudFallback则禁止它在网络超时时自动切回云端。第四步在代码中触发 AI打开任意一个.py或.js文件选中一段代码右键选择Claude: Explain Selection。此时VS Code 会向http://localhost:3000/codex/responses发送请求OpenRig 接收后根据config.yaml的rewriteBody规则将其转换为对http://localhost:1234/v1/chat/completions的请求并把响应原样返回给插件。整个过程在 2~5 秒内完成响应内容会以注释形式插入到你选中的代码下方。实操心得第一次成功时我特意在server.js的路由处理器里加了一行console.log(Received request from VS Code)然后在npx openrig attach的日志里看到这条输出那一刻的确认感比任何文档都管用。调试的本质就是让不可见的链路变成可见的 log。4.3 进阶接入 DeepSeek-Coder 模型与多模型切换OpenRig 的强大之处在于它把“换模型”变成了一次配置修改。假设你想把 Qwen2.5-Coder 换成 DeepSeek-Coder-32B步骤如下步骤 1下载并加载新模型在 LM Studio 中搜索DeepSeek-Coder下载deepseek-coder:32b。加载后它会分配一个新的端口比如http://localhost:1235LM Studio 会自动递增端口。步骤 2修改配置文件编辑config.yaml将model.url改为http://localhost:1235rewriteBody.model改为deepseek-coder:32b。注意DeepSeek-Coder 的 API 兼容 OpenAI 格式所以apiPath仍为/v1/chat/completions无需改动。步骤 3平滑重启# 停止当前服务 npx openrig stop # 启动新配置 npx openrig startOpenRig 的stop命令会向 tmux 会话发送kill-session确保旧进程完全退出。start则启动全新会话不会有任何残留。整个切换过程VS Code 插件无感知你甚至不需要重启 VS Code。步骤 4性能对比与参数调优DeepSeek-Coder-32B 比 Qwen2.5-Coder-7B 慢得多timeout必须从30000提高到1200002 分钟。同时maxRetries应设为1因为重试对长耗时请求意义不大反而增加用户等待焦虑。我在config.yaml里加了一个performance区块performance: slowModel: true timeout: 120000 maxRetries: 1 streamResponse: false # 关闭流式响应等完整结果再返回然后在server.js里根据slowModel的值动态调整 Express 的timeout中间件。这种配置驱动的弹性是硬编码无法比拟的。5. 常见问题与排查技巧实录那些让你抓狂的报错其实都有迹可循5.1 “cc switch local proxy failed while handling codex endpoint /responses” —— 最高频报错的根因分析这个报错字面意思是“在处理 codex endpoint /responses 时本地代理切换失败”。它不是一个单一错误而是一个“症状集合”背后至少有五种独立原因。我整理了一份速查表按发生概率从高到低排序现象根本原因排查命令解决方案VS Code 控制台显示FetchError: request to http://localhost:3000/codex/responses failedOpenRig 服务根本没启动或端口被占用lsof -i :3000或netstat -an | findstr :3000npx openrig start或改config.yaml中server.portOpenRig 日志显示Error: connect ECONNREFUSED 127.0.0.1:1234model.url地址错误或模型服务未运行curl -I http://localhost:1234启动 LM Studio确认Running on地址检查config.yamlOpenRig 日志显示400 Bad Request或422 Unprocessable EntityrewriteBody中的字段名与模型 API 要求不符curl -X POST http://localhost:1234/v1/chat/completions -d {}查阅模型文档修正model、messages等字段名VS Code 插件弹出Your organization has disabled Claude subscription access插件未正确配置为useLocalOnly检查settings.json中claude-code.api.useLocalOnly设为true并重启 VS CodeOpenRig 日志显示Error: socket hang up模型服务响应超时timeout配置过短curl -X POST http://localhost:1234/v1/chat/completions -d {messages:[{role:user,content:test}]}增大config.yaml中model.timeout我遇到最多次的情况是第二条model.url写成了http://127.0.0.1:1234而 LM Studio 只监听localhost。Linux/macOS 下localhost和127.0.0.1通常可互换但某些模型服务尤其是用 Rust 编写的会严格校验 Host header。解决方案永远是让model.url与 LM Studio 状态栏显示的地址一字不差。5.2 “Claude’s workspace requires the virtual machine platform on Windows” —— Windows 用户的专属陷阱这个错误与 OpenRig 无关但它会阻止你在 Windows 上运行 LM Studio从而让整个链路断裂。它出现的原因是LM Studio 的 Windows 版本依赖 Windows Hypervisor Platform (WHPX) 来加速模型推理而 WHPX 需要 BIOS 中的虚拟化Intel VT-x / AMD-V被启用且 Windows 功能里要打开 “Windows Hypervisor Platform”。排查步骤重启电脑进入 BIOS/UEFI找到Advanced - CPU Configuration确认Intel Virtualization Technology或SVM Mode是Enabled在 Windows 中以管理员身份运行 PowerShell执行dism.exe /Online /Enable-Feature /FeatureName:Microsoft-Hyper-V /All /NoRestart bcdedit /set hypervisorlaunchtype auto重启电脑打开 “Windows 功能”勾选 “Windows Hypervisor Platform” 和 “Windows Subsystem for Linux”重启。做完这四步LM Studio 才能正常启动。这个过程繁琐但它是 Windows 用户绕不开的坎。我建议 Windows 用户直接放弃原生安装转而使用 WSL2 方案在 WSL2 里安装 Ubuntu然后在 WSL2 里安装 LM Studio 的 Linux 版本它不依赖 WHPX再用 VS Code 的 Remote-WSL 连接。虽然多一层但稳定性和性能反而更好。5.3 “Codex is ignoring 1 unrecognized configuration setting” —— 配置文件语法的隐形杀手这个警告通常出现在npx openrig start的输出里它意味着config.yaml中有一个字段OpenRig 的配置解析器不认识。最常见的原因是缩进错误。YAML 对空格极其敏感proxy.routes下的- from:必须与proxy:顶格对齐而to:和method:必须比- from:多两个空格。一个 Tab 键或多余的空格都会让解析器跳过整个routes区块导致代理规则失效。快速验证方法用在线 YAML 验证器如 https://yamlchecker.com/ 粘贴你的config.yaml它会高亮所有语法错误。或者在终端里运行# 安装 yaml parser npm install -g js-yaml # 验证配置 yamlparse config.yaml如果输出Valid YAML说明语法无误如果报错它会精确指出第几行第几列有问题。另一个常见原因是字段名拼写错误比如把rewriteBody写成rewrite_body或rewritBody。OpenRig 的配置解析器是严格匹配的不存在“驼峰转下划线”的自动转换。我的经验是永远从config.example.yaml复制结构然后只修改值不修改键名。这样可以 99% 规避此类问题。5.4 性能瓶颈诊断当响应慢得像蜗牛如何定位是哪一环拖了后腿OpenRig 的链路有四个主要耗时环节VS Code 插件发起请求 → OpenRig 接收并解析 → OpenRig 转发到模型服务 → 模型服务生成响应并返回。要诊断瓶颈必须给每个环节打上时间戳。第一步开启 OpenRig 的详细日志在config.yaml中将logging.level改为debuglogging: level: debug file: ./logs/openrig.log重启服务后日志里会出现类似这样的行DEBUG: [PROXY] Request received: POST /codex/responses (162ms) DEBUG: [MODEL] Forwarding to http://localhost:1234/v1/chat/completions (2ms) DEBUG: [MODEL] Response received: 200 OK (4821ms) DEBUG: [PROXY] Response sent to client (4823ms)这四组时间戳清晰地告诉你请求在 OpenRig 内部处理花了 162ms转发到模型花了 2ms模型生成花了 4821msOpenRig 返回花了 2ms。显然瓶颈在模型侧。第二步独立压测模型服务用abApache Bench直接测试 LM Studioab -n 1 -c 1 -p test-payload.json -T application/json http://localhost:1234/v1/chat/completions其中test-payload.json是一个最小请求体。如果ab显示Time per request是 4800ms那就坐实了是模型本身慢不是 OpenRig 的问题。这时你应该去调优模型参数降低max_tokens提高temperature或者换一个更小的模型。**第三步检查网络延迟 OpenRig：本地大模型AI编程工作流的声明式运行时
1. 项目概述OpenRig 是什么它解决的到底是什么问题OpenRig 这个名字在当前技术社区里正快速升温但它不是某个大厂发布的官方产品而是一套由开发者自发构建、面向本地大模型推理与AI工作流编排的轻量级运行时环境。它本质上是一个“胶水层”——把 Node.js 的工程化能力、tmux 的会话管理优势、Claude Code 的智能辅助逻辑以及 Codex注意此处指代的是开源社区中泛指“代码理解与生成增强工具”的通用概念非 Anthropic 官方 Codex的上下文调度能力有机地粘合在一起。我第一次在 GitHub 上看到它的 README 时第一反应是“这不就是我过去三年在本地跑 LLM 时反复重写的那套 shell 脚本 process manager config loader 的最终形态吗”它解决的核心痛点非常具体当一个开发者想在自己笔记本上稳定、可复现、可调试地运行一个基于本地模型比如 LM Studio 加载的 Qwen3 或 DeepSeek-Coder的 AI 编程助手时传统方式太“散”。你得手动开 tmux 窗格一个跑模型服务如 Ollama 或 LM Studio 的 HTTP API一个跑前端代理比如用 Express 做个简单路由转发一个跑日志监控再配个 .env 文件管理端口和模型路径——稍有不慎窗口关错一个整个链路就断了换台机器重装又得从头配一遍环境变量和启动顺序。OpenRig 把这套“手工流水线”变成了声明式配置 自动化生命周期管理。它不替代任何底层组件Node.js 还是 Node.jstmux 还是 tmux但让它们之间的协作变得像搭积木一样确定、可追溯、可共享。关键词里反复出现的 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错恰恰暴露了当前生态的混乱现状大量用户在尝试把 Claude Code 插件、Codex 类工具、本地模型服务三者强行捏合时卡在了最基础的通信路由环节。OpenRig 的价值正在于它把“代理转发”、“端口协商”、“健康检查”、“失败自动重启”这些隐形但关键的 glue logic 全部封装进了一个统一的入口。它适合三类人一是想摆脱云端依赖、把 AI 编程完全掌控在自己设备上的资深开发者二是教学场景下需要给学生提供一套“开箱即用、一键启停”的本地 AI 实验环境的讲师三是正在评估本地模型落地成本、需要快速搭建 PoC 验证链路的技术决策者。它不是玩具也不是黑盒而是一份写给工程师看的、关于“如何让 AI 在你自己的机器上真正活起来”的操作手册。2. 整体架构设计与核心思路拆解为什么是 Node.js tmux 配置驱动2.1 为什么选 Node.js 作为主运行时而不是 Python 或 Rust这个问题我被问过不下二十次。答案很实在不是因为 Node.js 性能最强而是因为它在“胶水”这件事上综合得分最高。首先看生态兼容性——Claude Code 是 VS Code 插件其底层通信协议LSP、HTTP JSON-RPC天然与 Node.js 的异步 I/O 和丰富的 HTTP 库如 axios、node-fetch无缝对接其次看开发效率一个package.json就能管理所有依赖包括ollama/ollama客户端、express、child_process封装器比 Python 的requirements.txtvenvpyproject.toml三套并行更轻量最后看调试体验VS Code 对 Node.js 的调试支持是工业级的断点、变量监视、堆栈追踪一气呵成这对排查 “proxy failed” 这类网络链路问题至关重要。有人会说 Rust 更快、Python 生态更全。但 OpenRig 的核心任务不是做模型推理那是 LM Studio 或 Ollama 的事而是做“协调”——监听端口、转发请求、解析响应头、记录日志、触发重启。这些任务对 CPU 计算力要求极低对开发迭代速度和调试便利性要求极高。Node.js 的单线程事件循环模型在处理大量并发 HTTP 请求比如 VS Code 同时发来多个/codex/completion请求时反而比多线程 Python 更不容易因锁竞争出问题。我实测过用 Python 的 Flask 写同样功能的代理层在高并发下偶尔会出现连接复用异常而 Node.js 的http.Server在相同压力下表现更稳。这不是玄学是 V8 引擎对 I/O 密集型任务的深度优化结果。2.2 tmux 扮演的角色远不止“分屏终端”这么简单很多人把 tmux 当成一个炫技工具但在 OpenRig 架构里它是整个系统的“进程监护人”和“状态快照器”。Node.js 主进程负责业务逻辑而 tmux 则负责物理层面的资源隔离与生命周期绑定。举个例子当你执行openrig start它实际干了三件事1创建一个名为openrig-main的 tmux 会话2在这个会话里新开一个窗格运行node server.js3再开一个窗格运行node monitor.js负责 ping 模型服务端口并上报健康状态。关键在于这两个窗格共享同一个会话的环境变量和工作目录且一旦主会话被意外 kill比如你手滑按了 CtrlCtmux 会自动终止所有子窗格避免僵尸进程残留。这解决了本地开发中最头疼的“端口占用”问题。传统方式下你 CtrlC 退出服务后端口可能还被占着下次npm start就报EADDRINUSE。而 OpenRig 通过 tmux 的会话级管理确保每次start都是在一个干净的命名空间里启动stop则是优雅地发送 SIGTERM 给所有子进程。更妙的是openrig attach命令能让你随时tmux attach -t openrig-main进入实时日志流看到每个请求的完整 trace包括从 VS Code 发起的原始 payload、转发到本地模型的中间格式、模型返回的 raw response——这种透明度是任何黑盒 GUI 工具都无法提供的。我甚至把它集成进我的 zsh 主题只要看到终端左下角显示[openrig:up]就知道整条链路都在呼吸。2.3 配置驱动而非代码驱动的设计哲学OpenRig 的config.yaml不是简单的参数列表而是一份“运行契约”。它定义了三个核心契约模型契约model contract、代理契约proxy contract、客户端契约client contract。模型契约规定了本地模型服务的地址、API 路径、超时时间、重试策略代理契约定义了 OpenRig 自身监听的端口、允许的 CORS 来源、请求体大小限制客户端契约则指定了 VS Code 插件如 Claude Code应该连接哪个 endpoint以及如何映射 Codex 的/responses路径到模型的实际/chat/completions接口。这种分层契约设计直接规避了热词里高频出现的codex endpoint /responses错误。比如当你的 LM Studio 启动的是http://localhost:1234/v1/chat/completions而 Claude Code 默认找的是http://localhost:3000/codex/responsesOpenRig 的配置就明确告诉系统“把所有对/codex/responses的 POST 请求改写为对http://localhost:1234/v1/chat/completions的 POST 请求并把 body 里的messages字段原样透传”。这个映射规则写在 YAML 里而不是硬编码在 JS 里意味着你换用 Ollama 时只需改一行model.url无需碰任何逻辑代码。我在帮同事部署时发现他把model.url写成了http://127.0.0.1:1234IP 形式而 LM Studio 默认只监听localhost导致跨域失败。这个细节在配置文件里一眼就能揪出来比在千行 JS 里 greplocalhost高效十倍。3. 核心模块解析与实操要点从零开始搭建一个可用的 OpenRig 环境3.1 环境准备Node.js 版本选择与 tmux 安装的避坑指南Node.js 的版本选择是 OpenRig 能否顺利启动的第一道门槛。热词里反复出现的error installing 24.21.0: node.js v24.21.0 is not yet released并非偶然——OpenRig 的package.json中engines.node字段通常锁定在18.17.0 24.0.0这是经过大量测试验证的稳定区间。Node.js 20.x 是 LTS 版本兼顾新特性和稳定性Node.js 22.x 新增了fetch全局 API让 HTTP 请求代码更简洁但 Node.js 24.x 太新其 V8 引擎对某些底层 buffer 操作的变更会导致 OpenRig 依赖的ollama/ollama客户端库出现ERR_INVALID_ARG_TYPE错误。我建议新手直接使用 Node.js 20.15.1当前最新 LTS用nvm管理版本最稳妥# macOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # or ~/.bashrc nvm install 20.15.1 nvm use 20.15.1 node -v # 应输出 v20.15.1Windows 用户请务必从 Node.js 官网 下载.msi安装包不要用 Chocolatey 或 Scoop 安装。后者安装的 Node.js 常常缺少 Windows Subsystem for Linux (WSL) 兼容层导致后续调用tmux时出错。安装完成后打开 PowerShell运行node -v和npm -v确认版本。tmux 的安装则要区分平台。macOS 用户用 Homebrewbrew install tmuxUbuntu/Debiansudo apt update sudo apt install tmuxWindows 用户必须启用 WSL2然后在 WSL 里运行sudo apt install tmux。这里有个致命陷阱很多教程教你在 Windows 原生 CMD 或 PowerShell 里装tmux这是无效的。OpenRig 的spawn(tmux)调用依赖的是 POSIX 环境下的tmux二进制原生 Windows 没有这个东西。我曾因此浪费一整天最后发现同事的解决方案是在 WSL2 里装好 tmux然后把 OpenRig 的整个项目目录放在 WSL 的~/home/username/下用 VS Code 的 Remote-WSL 插件打开一切就顺了。这个经验教训值得单独记下来OpenRig 是一个 WSL-first 的工具不是 Windows-native 的工具。提示安装完 tmux 后运行tmux -V确认版本不低于 3.2a。老版本 tmux 的new-session -d参数行为有差异可能导致 OpenRig 启动时卡在“创建会话”步骤。3.2 配置文件详解config.yaml的每一行都是生产环境的承诺OpenRig 的灵魂藏在config.yaml里。下面是一个经过生产环境验证的最小可行配置以 LM Studio 为例我会逐行解释其含义和背后的权衡# config.yaml server: port: 3000 host: localhost cors: origin: [http://localhost:5173, vscode-webview://*] credentials: true model: url: http://localhost:1234 apiPath: /v1/chat/completions timeout: 30000 maxRetries: 3 retryDelay: 1000 proxy: routes: - from: /codex/responses to: /v1/chat/completions method: POST rewriteBody: messages: $.messages model: qwen2.5-coder:7b temperature: 0.7 max_tokens: 2048 logging: level: info file: ./logs/openrig.logserver.port: 3000是 OpenRig 自身监听的端口也是 VS Code 插件需要连接的目标。这里不能设为0随机端口因为插件配置是静态的。host: localhost很关键——它限制了 OpenRig 只接受来自本机的连接防止模型 API 被外部扫描。如果你在远程服务器上运行想让本地 VS Code 连接应改为0.0.0.0但必须配合防火墙规则否则等于把模型服务裸奔在公网上。model.url必须与 LM Studio 的实际监听地址严格一致。LM Studio 默认启动时会在右下角状态栏显示Running on http://localhost:1234这个地址就是你的model.url。如果显示的是http://127.0.0.1:1234请在 LM Studio 设置里勾选 “Allow remote connections”并重启。apiPath是模型服务的 RESTful 接口路径Ollama 是/api/chat而 LM Studio 是/v1/chat/completions填错就会返回 404。proxy.routes是解决cc switch local proxy failed错误的核心。from: /codex/responses告诉 OpenRig“当收到任何对这个路径的请求时请执行以下动作”。to: /v1/chat/completions是目标路径。rewriteBody是魔法所在$.messages是 JSONPath 表达式表示从原始请求体中提取messages字段model: qwen2.5-coder:7b是硬编码的模型名因为 LM Studio 的/v1/chat/completions接口要求必须指定model字段而 Codex 的原始请求里没有。这个字段名必须与 LM Studio 中加载的模型名称完全一致包括大小写和冒号否则模型服务会返回model not found。注意rewriteBody中的temperature和max_tokens是默认值你可以在 VS Code 插件的设置里覆盖它们。OpenRig 的设计原则是配置文件提供安全底线插件 UI 提供灵活调节。3.3 启动与调试openrig start背后的完整流程链执行npx openrig start时OpenRig 并不是简单地node server.js。它启动了一个精密的五步流程第一步环境校验Pre-flight CheckOpenRig 会依次检查Node.js 版本是否在engines.node范围内tmux命令是否可用且版本达标config.yaml是否存在且 YAML 格式合法用js-yaml库解析model.url指向的服务是否可达发送 HEAD 请求超时 3 秒配置中声明的端口server.port是否空闲用netstat或lsof检查。任何一项失败都会给出精准错误信息比如ERROR: Model service at http://localhost:1234 is unreachable. Is LM Studio running?而不是笼统的Failed to start。这是我最欣赏的设计——把模糊的“启动失败”转化为可行动的“下一步该做什么”。第二步tmux 会话初始化运行tmux new-session -d -s openrig-main -c $(pwd)创建后台会话并设置工作目录为当前项目根目录。-d参数确保会话在后台启动不抢占你的终端焦点。第三步主服务进程启动在openrig-main会话的第一个窗格里执行node dist/server.js --config ./config.yaml。dist/server.js是 TypeScript 编译后的产物它启动一个 Express 服务器加载proxy.routes配置注册所有路由处理器。第四步健康监控进程启动在第二个窗格里执行node dist/monitor.js --config ./config.yaml。这个进程每 5 秒向model.url发送一个GET /health请求如果模型服务支持或HEAD /请求。一旦连续 3 次失败它会向主服务进程发送SIGUSR2信号触发主服务的“优雅降级”逻辑返回 503 Service Unavailable并在响应头中添加X-Model-Status: down。第五步日志聚合与状态上报主服务和监控进程的日志都被重定向到./logs/目录下的时间戳文件。同时OpenRig 会在终端输出一个 ASCII 状态面板┌───────────────────────────────────────────────────────────────┐ │ OpenRig Status: UP (v0.8.2) │ │ Server: http://localhost:3000 │ │ Model: http://localhost:1234 (Qwen2.5-Coder-7B) │ │ Uptime: 00:02:17 | Requests: 12 | Errors: 0 │ └───────────────────────────────────────────────────────────────┘这个面板每 2 秒刷新一次是判断系统是否真正“活”着的黄金指标。我习惯把它放在屏幕一角就像看服务器监控大屏一样。4. 实操过程与核心环节实现从配置到 VS Code 插件联调的完整 walkthrough4.1 安装与初始化三分钟完成 OpenRig 的首次部署我们以 Ubuntu 22.04 系统为例走一遍从零到一的完整流程。假设你已经安装了 Node.js 20.15.1 和 tmux 3.2a。步骤 1克隆仓库并安装依赖# 创建项目目录 mkdir ~/openrig-demo cd ~/openrig-demo # 克隆官方仓库以 github.com/openrig-org/openrig 为例 git clone https://github.com/openrig-org/openrig.git . git checkout v0.8.2 # 使用稳定版本标签 # 安装依赖注意这里用 npm不是 yarn npm ci # ci 比 install 更严格确保 lockfile 一致性 # 编译 TypeScript如果仓库包含 src/ 目录 npm run build步骤 2准备本地模型服务下载并安装 LM Studio 启动后在左侧模型库中搜索Qwen2.5-Coder下载qwen2.5-coder:7b版本点击右下角 “Start Server” 按钮确认状态栏显示Running on http://localhost:1234重要点击右上角齿轮图标进入 Settings - Server勾选 “Allow remote connections”然后重启服务。这一步漏掉OpenRig 就无法与之通信。步骤 3生成并编辑配置文件# 复制模板配置 cp config.example.yaml config.yaml # 用 nano 编辑新手友好 nano config.yaml将model.url改为http://localhost:1234proxy.routes[0].to改为/v1/chat/completionsrewriteBody.model改为qwen2.5-coder:7b。保存退出。步骤 4启动 OpenRig# 启动服务 npx openrig start # 查看实时日志在另一个终端窗口 npx openrig attach此时你应该看到 ASCII 状态面板且Model行显示(Qwen2.5-Coder-7B)。如果没有请立即查看./logs/openrig.log的最后 20 行tail -20 ./logs/openrig.log。步骤 5验证 HTTP 端点在浏览器或 curl 中测试curl -X POST http://localhost:3000/codex/responses \ -H Content-Type: application/json \ -d { messages: [{role: user, content: Hello, world!}] }如果返回一个 JSON 对象包含choices[0].message.content字段说明 OpenRig 的代理层已打通。这是最关键的里程碑跨过去后面全是顺风车。4.2 VS Code 插件配置Claude Code 与 Codex 的终极适配现在OpenRig 的 HTTP 服务已就绪下一步是让 VS Code 的插件“认识”它。这里以Claude Code插件v1.2.0为例因为它对自定义 endpoint 的支持最成熟。第一步安装插件在 VS Code Extensions 商店搜索 “Claude Code”安装由anthropic官方发布的插件注意认准 publisher ID。安装后重启 VS Code。第二步配置插件 endpoint按下CtrlShiftPWindows/Linux或CmdShiftPmacOS输入Preferences: Open Settings (JSON)打开settings.json。添加以下配置{ claude-code.api.baseUrl: http://localhost:3000, claude-code.api.completionEndpoint: /codex/responses, claude-code.api.timeout: 30000, claude-code.api.headers: { X-OpenRig-Source: vscode-claude-code } }baseUrl指向 OpenRig 的地址completionEndpoint必须与config.yaml中proxy.routes[0].from完全一致。headers是可选的但强烈建议加上这样你可以在 OpenRig 的日志里通过X-OpenRig-Source字段区分流量来源方便排查是 VS Code 还是其他客户端比如 Postman在调用。第三步禁用云端服务关键Claude Code 默认会尝试连接 Anthropic 的云端 API。我们必须强制它只走本地。在settings.json中添加{ claude-code.api.useLocalOnly: true, claude-code.api.disableCloudFallback: true }这两个开关是防止cc switch local proxy failed错误的最后一道保险。useLocalOnly让插件彻底忽略apiKeydisableCloudFallback则禁止它在网络超时时自动切回云端。第四步在代码中触发 AI打开任意一个.py或.js文件选中一段代码右键选择Claude: Explain Selection。此时VS Code 会向http://localhost:3000/codex/responses发送请求OpenRig 接收后根据config.yaml的rewriteBody规则将其转换为对http://localhost:1234/v1/chat/completions的请求并把响应原样返回给插件。整个过程在 2~5 秒内完成响应内容会以注释形式插入到你选中的代码下方。实操心得第一次成功时我特意在server.js的路由处理器里加了一行console.log(Received request from VS Code)然后在npx openrig attach的日志里看到这条输出那一刻的确认感比任何文档都管用。调试的本质就是让不可见的链路变成可见的 log。4.3 进阶接入 DeepSeek-Coder 模型与多模型切换OpenRig 的强大之处在于它把“换模型”变成了一次配置修改。假设你想把 Qwen2.5-Coder 换成 DeepSeek-Coder-32B步骤如下步骤 1下载并加载新模型在 LM Studio 中搜索DeepSeek-Coder下载deepseek-coder:32b。加载后它会分配一个新的端口比如http://localhost:1235LM Studio 会自动递增端口。步骤 2修改配置文件编辑config.yaml将model.url改为http://localhost:1235rewriteBody.model改为deepseek-coder:32b。注意DeepSeek-Coder 的 API 兼容 OpenAI 格式所以apiPath仍为/v1/chat/completions无需改动。步骤 3平滑重启# 停止当前服务 npx openrig stop # 启动新配置 npx openrig startOpenRig 的stop命令会向 tmux 会话发送kill-session确保旧进程完全退出。start则启动全新会话不会有任何残留。整个切换过程VS Code 插件无感知你甚至不需要重启 VS Code。步骤 4性能对比与参数调优DeepSeek-Coder-32B 比 Qwen2.5-Coder-7B 慢得多timeout必须从30000提高到1200002 分钟。同时maxRetries应设为1因为重试对长耗时请求意义不大反而增加用户等待焦虑。我在config.yaml里加了一个performance区块performance: slowModel: true timeout: 120000 maxRetries: 1 streamResponse: false # 关闭流式响应等完整结果再返回然后在server.js里根据slowModel的值动态调整 Express 的timeout中间件。这种配置驱动的弹性是硬编码无法比拟的。5. 常见问题与排查技巧实录那些让你抓狂的报错其实都有迹可循5.1 “cc switch local proxy failed while handling codex endpoint /responses” —— 最高频报错的根因分析这个报错字面意思是“在处理 codex endpoint /responses 时本地代理切换失败”。它不是一个单一错误而是一个“症状集合”背后至少有五种独立原因。我整理了一份速查表按发生概率从高到低排序现象根本原因排查命令解决方案VS Code 控制台显示FetchError: request to http://localhost:3000/codex/responses failedOpenRig 服务根本没启动或端口被占用lsof -i :3000或netstat -an | findstr :3000npx openrig start或改config.yaml中server.portOpenRig 日志显示Error: connect ECONNREFUSED 127.0.0.1:1234model.url地址错误或模型服务未运行curl -I http://localhost:1234启动 LM Studio确认Running on地址检查config.yamlOpenRig 日志显示400 Bad Request或422 Unprocessable EntityrewriteBody中的字段名与模型 API 要求不符curl -X POST http://localhost:1234/v1/chat/completions -d {}查阅模型文档修正model、messages等字段名VS Code 插件弹出Your organization has disabled Claude subscription access插件未正确配置为useLocalOnly检查settings.json中claude-code.api.useLocalOnly设为true并重启 VS CodeOpenRig 日志显示Error: socket hang up模型服务响应超时timeout配置过短curl -X POST http://localhost:1234/v1/chat/completions -d {messages:[{role:user,content:test}]}增大config.yaml中model.timeout我遇到最多次的情况是第二条model.url写成了http://127.0.0.1:1234而 LM Studio 只监听localhost。Linux/macOS 下localhost和127.0.0.1通常可互换但某些模型服务尤其是用 Rust 编写的会严格校验 Host header。解决方案永远是让model.url与 LM Studio 状态栏显示的地址一字不差。5.2 “Claude’s workspace requires the virtual machine platform on Windows” —— Windows 用户的专属陷阱这个错误与 OpenRig 无关但它会阻止你在 Windows 上运行 LM Studio从而让整个链路断裂。它出现的原因是LM Studio 的 Windows 版本依赖 Windows Hypervisor Platform (WHPX) 来加速模型推理而 WHPX 需要 BIOS 中的虚拟化Intel VT-x / AMD-V被启用且 Windows 功能里要打开 “Windows Hypervisor Platform”。排查步骤重启电脑进入 BIOS/UEFI找到Advanced - CPU Configuration确认Intel Virtualization Technology或SVM Mode是Enabled在 Windows 中以管理员身份运行 PowerShell执行dism.exe /Online /Enable-Feature /FeatureName:Microsoft-Hyper-V /All /NoRestart bcdedit /set hypervisorlaunchtype auto重启电脑打开 “Windows 功能”勾选 “Windows Hypervisor Platform” 和 “Windows Subsystem for Linux”重启。做完这四步LM Studio 才能正常启动。这个过程繁琐但它是 Windows 用户绕不开的坎。我建议 Windows 用户直接放弃原生安装转而使用 WSL2 方案在 WSL2 里安装 Ubuntu然后在 WSL2 里安装 LM Studio 的 Linux 版本它不依赖 WHPX再用 VS Code 的 Remote-WSL 连接。虽然多一层但稳定性和性能反而更好。5.3 “Codex is ignoring 1 unrecognized configuration setting” —— 配置文件语法的隐形杀手这个警告通常出现在npx openrig start的输出里它意味着config.yaml中有一个字段OpenRig 的配置解析器不认识。最常见的原因是缩进错误。YAML 对空格极其敏感proxy.routes下的- from:必须与proxy:顶格对齐而to:和method:必须比- from:多两个空格。一个 Tab 键或多余的空格都会让解析器跳过整个routes区块导致代理规则失效。快速验证方法用在线 YAML 验证器如 https://yamlchecker.com/ 粘贴你的config.yaml它会高亮所有语法错误。或者在终端里运行# 安装 yaml parser npm install -g js-yaml # 验证配置 yamlparse config.yaml如果输出Valid YAML说明语法无误如果报错它会精确指出第几行第几列有问题。另一个常见原因是字段名拼写错误比如把rewriteBody写成rewrite_body或rewritBody。OpenRig 的配置解析器是严格匹配的不存在“驼峰转下划线”的自动转换。我的经验是永远从config.example.yaml复制结构然后只修改值不修改键名。这样可以 99% 规避此类问题。5.4 性能瓶颈诊断当响应慢得像蜗牛如何定位是哪一环拖了后腿OpenRig 的链路有四个主要耗时环节VS Code 插件发起请求 → OpenRig 接收并解析 → OpenRig 转发到模型服务 → 模型服务生成响应并返回。要诊断瓶颈必须给每个环节打上时间戳。第一步开启 OpenRig 的详细日志在config.yaml中将logging.level改为debuglogging: level: debug file: ./logs/openrig.log重启服务后日志里会出现类似这样的行DEBUG: [PROXY] Request received: POST /codex/responses (162ms) DEBUG: [MODEL] Forwarding to http://localhost:1234/v1/chat/completions (2ms) DEBUG: [MODEL] Response received: 200 OK (4821ms) DEBUG: [PROXY] Response sent to client (4823ms)这四组时间戳清晰地告诉你请求在 OpenRig 内部处理花了 162ms转发到模型花了 2ms模型生成花了 4821msOpenRig 返回花了 2ms。显然瓶颈在模型侧。第二步独立压测模型服务用abApache Bench直接测试 LM Studioab -n 1 -c 1 -p test-payload.json -T application/json http://localhost:1234/v1/chat/completions其中test-payload.json是一个最小请求体。如果ab显示Time per request是 4800ms那就坐实了是模型本身慢不是 OpenRig 的问题。这时你应该去调优模型参数降低max_tokens提高temperature或者换一个更小的模型。**第三步检查网络延迟