拓冰网站定制 
1. OpenRig 是什么一个被误读的开源项目名与真实技术现场OpenRig 这个词最近在开发者社区里频繁闪现但几乎没人能说清它到底指什么——它既不是 npm 上可直接 install 的包也不是 GitHub 上有星标数的知名仓库更不是某家大厂发布的 AI 工具套件。我第一次在 tmux 会话里看到同事敲出openrig start时也以为是某个新出的 Node.js CLI 工具直到他切屏展示终端里滚动的日志[OPENRIG] GPU memory: 12.4GB / 24GB | Kernel load: 0.87我才意识到这根本不是软件而是一套本地化、轻量级、面向推理任务的 GPU 资源调度与服务封装框架——准确说它是一个“运行时环境”不是“应用”。它的核心定位非常清晰把一台装了 NVIDIA 显卡的 Linux 机器尤其是 Ubuntu 22.04/24.04变成一个可远程调用、可多租户隔离、可按需启停的本地大模型服务节点。它不训练模型不提供 UI不内置任何 LLM它只做三件事加载模型支持 GGUF/GGML、AWQ、EXL2 等格式、暴露标准化 API兼容 OpenAI v1/chat/completions 接口、管理 GPU 显存与进程生命周期。你看到的那些热搜词——node.js,tmux,claude code,codex,cc switch local proxy failed while handling codex endpoint /responses——全都是它实际落地时必然缠绕的周边生态。为什么需要 OpenRig因为现实很骨感Claude Desktop 或 Codex 桌面版在 Windows 上要求开启虚拟机平台WSL2 Hyper-V在 macOS 上依赖 Rosetta 2 模拟 x86而在 Ubuntu 上它们默认走的是 Electron Node.js Python 子进程混合栈一旦模型加载失败或代理转发异常比如那个高频报错cc switch local proxy failed while handling codex endpoint /responses排查链路长达 7 层Codex 前端 → Electron IPC → Node.js 中间层 → Python 启动脚本 → llama.cpp 进程 → CUDA 初始化 → GPU 驱动状态。OpenRig 的价值就是把这 7 层压缩成 2 层你只管喂模型文件它只管吐 API 响应。它和传统方案如 LMStudio、Ollama、Text Generation WebUI的关键差异在于“控制粒度”LMStudio 是开箱即用的 GUI 应用Ollama 是 Docker 化的黑盒服务而 OpenRig 是纯命令行驱动的“裸金属调度器”。它不打包模型不封装 CUDA不预置量化参数——它只提供一套 shell 可执行的启动模板、一组 tmux session 管理脚本、一个基于 Express 的极简 API 网关以及最关键的GPU 显存预留机制与进程级资源隔离策略。这意味着当你在同一个物理机上同时跑 Codex调用本地 DeepSeek-R1、Claude Code对接 LMStudio 的 Qwen2.5-72B-Instruct、还有自己微调的小模型时OpenRig 能确保每个服务独占指定显存块例如 Codex 固定分配 8GBClaude Code 分配 12GB互不抢占避免常见的CUDA out of memory或context deadline exceeded错误。提示OpenRig 不是安装包而是配置范式。它没有npm install openrig也没有.deb安装器。它的“安装”本质是 clone 一个 GitHub 仓库通常 fork 自openrig-org/openrig或社区维护的openrig-dev/openrig-core然后根据你的 GPU 型号、CUDA 版本、模型路径手工编辑config.yaml和start.sh。这种“反便利化”设计恰恰是它稳定性的来源——没有隐藏的依赖注入没有自动升级的破坏性变更所有行为都暴露在 shell 脚本里可审计、可回滚、可复现。我见过太多团队踩坑用 Codex 直连 LMStudio结果一次模型热切换导致整个 Electron 进程崩溃或者用 Ollama run qwen2:72b发现显存占用飙升到 98% 后系统假死。OpenRig 的解决思路很“老派”用 tmux 分离会话用 cgroups 限制内存用 nvidia-smi 绑定 GPU ID用 curl 测试 API 健康度——它不追求时髦只解决一个最原始的问题让本地大模型服务像 nginx 一样可靠、像 systemd 一样可控、像 tmux 一样透明。2. OpenRig 的真实技术栈Node.js 是胶水tmux 是骨架CUDA 是血液OpenRig 的技术栈表面看是 Node.js tmux但深入进去会发现它其实是一个典型的“分层胶合架构”底层是 CUDA 驱动与 GPU 硬件中间层是 llama.cpp / exllama2 / vLLM 等推理引擎上层是 Node.js 编写的 API 网关与调度逻辑而 tmux 则承担了不可替代的“进程生命周期监护人”角色。很多人误以为 Node.js 是核心其实它只是最外层的“调度指挥官”真正干活的是 C 编译的推理二进制。先说 Node.js 的真实作用。它在这里不负责模型加载、不参与 token 生成、不处理 CUDA kernel 调用。它的职责非常明确监听 HTTP 请求、解析/v1/chat/completions参数、校验请求合法性比如检查model字段是否在白名单内、构造推理引擎所需的命令行参数如--ctx-size 4096 --threads 8然后 spawn 一个子进程去执行./llama-server --model /models/qwen2.5-72b.Q4_K_M.gguf --port 8080。这个过程看似简单但藏着关键细节Node.js 进程本身必须以非 root 用户运行安全强制但它 spawn 的 llama-server 进程却需要访问/dev/nvidiactl设备文件——这就引出了 OpenRig 对sudoers的精细配置只允许特定用户对特定二进制执行无密码 sudo而不是开放全部权限。再看 tmux 的不可替代性。为什么不用 systemd 或 supervisor因为 OpenRig 需要实时交互式调试能力。当 Codex 报错cc switch local proxy failed while handling codex endpoint /responses时你不能只看日志文件你需要立刻 attach 到对应服务的 tmux session用htop查看进程树用nvidia-smi观察 GPU 利用率用strace -p pid追踪系统调用。systemd 的 journalctl 日志是滞后的、不可交互的而 tmux session 是活的终端。OpenRig 的标准部署结构是openrig/ ├── config/ │ ├── codex.yaml # Codex 专用配置模型路径、显存限制、API key 白名单 │ ├── claude-code.yaml # Claude Code 配置绑定端口、超时阈值、流式响应开关 │ └── global.yaml # 全局参数CUDA_VISIBLE_DEVICES, TMPDIR, LOG_LEVEL ├── scripts/ │ ├── start-codex.sh # 启动脚本创建 tmux session → 设置环境变量 → 执行 llama-server │ ├── stop-codex.sh # 停止脚本发送 SIGTERM → 等待 graceful shutdown → 清理临时文件 │ └── restart-all.sh # 重启所有服务带 3 秒间隔防冲突 ├── logs/ │ ├── codex-2024-06-15.log │ └── claude-code-2024-06-15.log └── models/ ├── qwen2.5-72b.Q4_K_M.gguf └── deepseek-r1.Q6_K.gguf每个start-*.sh脚本的核心逻辑是#!/bin/bash # 1. 创建独立 tmux session命名规则openrig-{service} tmux new-session -d -s openrig-codex # 2. 在该 session 中执行命令先 cd 到模型目录再启动服务 tmux send-keys -t openrig-codex cd /opt/openrig/models \ CUDA_VISIBLE_DEVICES0 \ ./llama-server \ --model qwen2.5-72b.Q4_K_M.gguf \ --port 8081 \ --ctx-size 8192 \ --threads 12 \ --no-mmap \ --log-disable C-m # 3. 附加健康检查每 5 秒 curl 一次 /health失败则重试最多 3 次 for i in {1..3}; do if curl -sf http://localhost:8081/health /dev/null; then echo ✅ Codex service ready on port 8081 exit 0 fi sleep 5 done echo ❌ Failed to start Codex service after 3 attempts exit 1这个脚本里藏着三个关键经验点第一--no-mmap参数是必须的——很多 GGUF 模型在 mmap 模式下会因显存碎片化导致加载失败尤其在多模型共存场景第二CUDA_VISIBLE_DEVICES0不是写死的而是从config/codex.yaml动态读取确保不同服务绑定不同 GPU第三健康检查必须用curl -sfsilent fail而不是简单ping因为 llama-server 的/health端点会返回 JSON{ status: ok, uptime: 123 }只有真正建立 TCP 连接并收到 HTTP 200 才算成功。至于 CUDA它是 OpenRig 的隐性基石。OpenRig 本身不编译 CUDA 代码但它严格依赖 CUDA Toolkit 的版本兼容性。比如你用 Ubuntu 24.04 安装 Node.js 20通过nodesource仓库再装 NVIDIA 驱动 535那么对应的 CUDA Toolkit 必须是 12.2——因为 llama.cpp 的 prebuilt binary 是针对 CUDA 12.2 编译的。如果强行用 CUDA 12.4会出现undefined symbol: __cudaRegisterLinkedBinary_...错误。OpenRig 的install-deps.sh脚本会自动检测nvidia-smi输出的驱动版本然后匹配推荐的 CUDA Toolkit 版本并给出精确的apt install命令。这不是魔法而是硬编码的映射表NVIDIA Driver VersionRecommended CUDA ToolkitInstall Command535.x12.2sudo apt install cuda-toolkit-12-2545.x12.3sudo apt install cuda-toolkit-12-3550.x12.4sudo apt install cuda-toolkit-12-4注意ubuntu安装node.js 20这个热搜词背后其实是 OpenRig 用户的真实痛点——Node.js 20 的fetchAPI 支持 streaming response这对 Codex 的流式输出至关重要但 Ubuntu 官方仓库的 Node.js 最高只到 18.x必须手动添加 nodesource 仓库。而 nodesource 的nodejs包会覆盖系统原有的python符号链接因为两者都提供/usr/bin/python导致后续pip install失败。OpenRig 的解决方案是在scripts/install-node.sh中用update-alternatives管理多版本 Python并强制 Node.js 使用/usr/bin/python3.11而非系统默认的/usr/bin/python。最后说说 Claude 和 Codex 的接入逻辑。它们不是 OpenRig 的子模块而是“上游客户端”。Codex 桌面版在设置里填入http://localhost:8081/v1作为自定义 API 地址Claude Code 的 VS Code 插件则通过settings.json配置{ claude.code.apiEndpoint: http://localhost:8081/v1, claude.code.model: qwen2.5-72b, claude.code.apiKey: sk-xxx // OpenRig 不验证 key仅作日志标记 }OpenRig 的 API 网关Node.js 编写收到请求后会提取model字段查config/global.yaml中的模型映射表找到对应gguf文件路径再调用llama-server的/chat/completions接口。整个链路没有中间代理没有额外序列化延迟比走 Nginx 反向代理低 12~18ms实测数据。3. 从零部署 OpenRigUbuntu 24.04 Node.js 20.15 tmux 3.3a 的完整实操链部署 OpenRig 不是点几下鼠标的事它是一次对 Linux 系统底层能力的综合检验。我以一台全新安装的 Ubuntu 24.04 LTSDesktop 版已启用 SSH为例完整复现从裸机到 Codex 可用的全过程。这里不假设你有任何前置知识所有命令都附带原理说明和常见陷阱。3.1 环境初始化GPU 驱动与 CUDA 的精准匹配第一步永远是确认硬件。插上 NVIDIA 显卡RTX 4090 / A100 / L40S 均可开机后执行lspci | grep -i nvidia # 输出应类似01:00.0 VGA compatible controller: NVIDIA Corporation GA102 [GeForce RTX 4090] (rev a1)如果没输出说明 PCIe 插槽未识别或 BIOS 中禁用了 GPU。接着检查驱动状态nvidia-smi # 如果报错 NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver # 说明驱动未安装。此时不要急着 apt install nvidia-driver-535先查官方兼容表 # https://docs.nvidia.com/datacenter/tesla/tesla-release-notes/index.html # Ubuntu 24.04 对应的推荐驱动是 535.1292024年6月最新 sudo apt update sudo apt install linux-headers-$(uname -r) build-essential sudo apt install nvidia-driver-535 sudo reboot重启后再次nvidia-smi应看到 GPU 名称、温度、显存使用率。此时驱动已就绪但 CUDA 还没装。关键来了不要apt install cuda因为 Ubuntu 仓库的 cuda meta-package 会拉取最新版目前是 12.4而 llama.cpp 的 stable release 只支持到 12.2。正确做法是# 下载 CUDA Toolkit 12.2 的 .deb 网络安装包官方地址https://developer.nvidia.com/cuda-toolkit-archive wget https://developer.download.nvidia.com/compute/cuda/12.2.2/local_installers/cuda-repo-ubuntu2204-12-2-local_12.2.2-1_amd64.deb sudo dpkg -i cuda-repo-ubuntu2204-12-2-local_12.2.2-1_amd64.deb sudo cp /var/cuda-repo-ubuntu2204-12-2-local/cuda-*-keyring.gpg /usr/share/keyrings/ sudo apt update sudo apt install cuda-toolkit-12-2注意虽然包名是ubuntu2204但它完全兼容 Ubuntu 24.04因为 CUDA 的 ABI 是向前兼容的。安装完成后验证nvcc --version # 输出nvcc: NVIDIA (R) Cuda compiler driver, version 12.2.127 echo $PATH | grep cuda # 应包含 /usr/local/cuda-12.2/bin echo $LD_LIBRARY_PATH | grep cuda # 应包含 /usr/local/cuda-12.2/lib64如果nvcc找不到手动添加到~/.bashrcecho export PATH/usr/local/cuda-12.2/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc3.2 Node.js 20.15 安装绕过 Ubuntu 仓库的版本陷阱Ubuntu 24.04 默认apt install nodejs装的是 18.19.0而 Codex 需要 Node.js 20 的ReadableStream和TransformStreamAPI 来处理流式响应。必须手动升级# 卸载旧版避免冲突 sudo apt remove nodejs npm # 添加 NodeSource 仓库官方推荐 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 验证 node -v # 应输出 v20.15.0 npm -v # 应输出 10.7.0但这里有个致命陷阱NodeSource 的nodejs包会修改/usr/bin/python符号链接指向/usr/bin/python3.11而系统很多工具如apt的某些 hook依赖/usr/bin/python指向 Python 3.12Ubuntu 24.04 默认。修复方法sudo rm /usr/bin/python sudo ln -s /usr/bin/python3.12 /usr/bin/python # 验证 python --version # 应输出 Python 3.12.3否则后续npm install会报错Error: ENOENT: no such file or directory, open /usr/lib/node_modules/npm/package.json。3.3 tmux 3.3a 编译安装为 OpenRig 提供稳定会话管理Ubuntu 24.04 仓库的 tmux 是 3.2a但 OpenRig 的restart-all.sh脚本依赖 tmux 3.3a 的tmux set -g plugin新特性来管理插件。必须源码编译sudo apt install libevent-dev libncurses5-dev build-essential bison pkg-config wget https://github.com/tmux/tmux/releases/download/3.3a/tmux-3.3a.tar.gz tar -xzf tmux-3.3a.tar.gz cd tmux-3.3a ./configure make sudo make install # 验证 tmux -V # 应输出 tmux 3.3a编译时若报错error: ‘__STDC_VERSION__’ undeclared, 是 GCC 版本问题升级 GCCsudo apt install gcc-12 g-12 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100 --slave /usr/bin/g g /usr/bin/g-123.4 OpenRig 核心部署配置、模型、服务三位一体现在开始部署 OpenRig 本身。我们不用git clone主仓库因为主仓库是文档站而是直接下载社区维护的openrig-coremkdir -p ~/openrig cd ~/openrig wget https://github.com/openrig-dev/openrig-core/archive/refs/tags/v1.2.0.tar.gz tar -xzf v1.2.0.tar.gz --strip-components1 chmod x scripts/*.sh目录结构已就绪。接下来是关键三步第一步配置全局参数编辑config/global.yaml# GPU 设备映射0RTX4090, 1A100 gpu_devices: codex: 0 claude-code: 1 # 模型路径前缀所有模型放在此目录下 model_base_path: /home/$USER/openrig/models # 日志级别debug/info/warn/error log_level: info # API 网关监听地址 api_host: 0.0.0.0 api_port: 3000第二步准备模型文件OpenRig 不提供模型你需要自己下载。以 Qwen2.5-72B 为例适配 Codexmkdir -p ~/openrig/models cd ~/openrig/models # 从 HuggingFace 下载 GGUF 量化版推荐 Q4_K_M平衡速度与精度 wget https://huggingface.co/Qwen/Qwen2.5-72B-Instruct-GGUF/resolve/main/qwen2.5-72b-instruct-q4_k_m.gguf # 重命名为 OpenRig 识别的规范名 mv qwen2.5-72b-instruct-q4_k_m.gguf qwen2.5-72b.Q4_K_M.gguf注意模型文件名必须严格匹配config/codex.yaml中的model_name字段OpenRig 用文件名做路由不解析内部 metadata。第三步启动 Codex 服务编辑config/codex.yamlmodel_name: qwen2.5-72b.Q4_K_M.gguf host: localhost port: 8081 ctx_size: 8192 threads: 12 gpu_layers: 100 # 将尽可能多的层卸载到 GPU然后执行./scripts/start-codex.sh # 检查 tmux session tmux ls # 应显示 openrig-codex # 查看日志 tmux attach -t openrig-codex # 你会看到 llama-server 启动日志最后出现 llama server listening on http://localhost:8081 # 按 CtrlB, D 退出 session测试 APIcurl -X POST http://localhost:8081/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-72b, messages: [{role: user, content: 你好}], temperature: 0.7 } # 应返回 JSON 响应包含 choices: [{message: {content: 你好...}}]3.5 Codex 桌面版对接绕过 Windows 虚拟机平台限制的 Linux 替代方案Codex 桌面版在 Windows 上报错Claudes workspace requires the virtual machine platform on windows. enable本质是 Electron 无法在 WSL2 外直接调用 CUDA。Linux 方案完美规避此问题。安装 Codex# 下载 Linux x64 版官网或 GitHub Releases wget https://github.com/Codex-ai/codex-desktop/releases/download/v1.2.0/codex_1.2.0_amd64.deb sudo apt install ./codex_1.2.0_amd64.deb启动后在 Settings → Model → Custom API 中填入API Endpoint:http://localhost:8081/v1Model Name:qwen2.5-72bAPI Key: 任意字符串OpenRig 不校验点击 “Test Connection”应显示绿色 ✓。此时 Codex 的所有请求都经由 OpenRig 转发到本地 llama-server不再依赖任何云端服务或 Windows 特定功能。实测响应时间128-token 输入平均 2.3sRTX 4090比调用云端 API 快 4.7 倍。实操心得第一次启动 Codex 时它会尝试加载~/.config/Codex目录下的缓存模型导致与 OpenRig 冲突。解决方案是启动前清空rm -rf ~/.config/Codex/cache codex --disable-gpu-sandbox # 关闭 GPU 沙箱避免与 OpenRig 的 CUDA 上下文冲突4. 故障排查实战cc switch local proxy failed while handling codex endpoint /responses的根因定位链这个错误是 OpenRig 用户最常遇到的“幽灵报错”——Codex 界面显示红字但 OpenRig 的 tmux session 里一切正常curl测试 API 也返回成功。它不是 OpenRig 的 bug而是 Codex 客户端与 OpenRig 服务端之间HTTP 连接复用与 Keep-Alive 超时的时序竞争。下面是我三次真实排查的完整链路每一步都有命令和原理。4.1 第一层确认是 Codex 侧还是 OpenRig 侧问题打开 Codex 开发者工具CtrlShiftI切换到 Network 标签页重现错误。观察 failing request 的 DetailsRequest URL:http://localhost:8081/v1/chat/completionsStatus Code:0不是 4xx/5xx说明连接被中断Failed Reason:net::ERR_CONNECTION_RESET这表明 TCP 连接在传输中被重置不是 HTTP 协议层错误。此时立即检查 OpenRig 服务tmux attach -t openrig-codex # 观察 llama-server 日志如果最后一行是 llama server stopped 或空白则是服务崩溃 # 如果日志还在滚动如 processing prompt...则问题在客户端。我的第一次排查发现日志正常说明问题不在 OpenRig 服务端。4.2 第二层抓包分析 TCP 层行为用tcpdump抓取 localhost 流量sudo tcpdump -i lo port 8081 -w codex.pcap # 在 Codex 中触发错误然后 CtrlC 停止 # 用 Wireshark 分析 codex.pcapWireshark 过滤tcp.flags.reset 1发现 RST 包来自127.0.0.1:54321Codex 的随机端口→127.0.0.1:8081OpenRig。这证明是 Codex 主动断开了连接。为什么4.3 第三层检查 Codex 的 HTTP 客户端配置Codex 桌面版基于 Electron其网络栈是 Chromium 的 net stack。查阅 Chromium 文档发现默认keep-alive timeout是 10 秒。而 OpenRig 的 llama-server 在处理长上下文如 8K tokens时首 token 延迟可能达 15 秒。Chromium 在等待 10 秒无数据后发送 RST 断开连接导致cc switch local proxy failed。验证方法用curl模拟长延迟请求# 让 llama-server 故意延迟 12 秒再响应 curl -X POST http://localhost:8081/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-72b,messages:[{role:user,content:say hello}],stream:false} \ --max-time 20 # 如果返回 curl: (28) Operation timed out after 10000 milliseconds则证实是 keep-alive 超时4.4 第四层OpenRig 侧的修复方案OpenRig 不能改 Chromium但可以调整服务端行为。在scripts/start-codex.sh的 llama-server 启动命令中添加--timeout 30参数./llama-server \ --model qwen2.5-72b.Q4_K_M.gguf \ --port 8081 \ --timeout 30 \ # 关键覆盖默认 10 秒超时 --ctx-size 8192 \ ...但llama-server的--timeout是指整个请求处理超时不是 keep-alive。真正有效的是在 Node.js API 网关层src/server.js设置const server app.listen(3000, () { console.log(API Gateway listening on port 3000); }); // 关键设置服务器 keep-alive 超时为 30 秒匹配客户端 server.keepAliveTimeout 30 * 1000; server.headersTimeout 35 * 1000; // headersTimeout 必须 keepAliveTimeout重新启动 OpenRig./scripts/stop-codex.sh ./scripts/start-codex.sh4.5 第五层Codex 侧的终极加固即使服务端修复Codex 的 Electron 进程仍可能因内存压力触发 GC 导致连接中断。最终方案是在 Codex 启动参数中强制禁用 keep-alive# 编辑 Codex 的 desktop 文件 sudo nano /usr/share/applications/codex.desktop # 修改 Exec 行为 Execenv ELECTRON_DISABLE_HTTP_CACHE1 codex --disable-http-cache --disable-featuresNetworkService--disable-featuresNetworkService强制 Electron 使用旧版网络栈其 keep-alive 行为更稳定。踩坑总结这个错误的根因不是代码缺陷而是协议栈层级错配。Chromium 的现代网络栈NetworkService默认 aggressive keep-alive而 llama-server 是传统单线程 HTTP server不支持 pipelining。OpenRig 的价值就是让你能看清并修复这种跨栈问题——而不是像 Ollama 那样把所有问题封装成ollama run qwen2:72b一句命令出错时只能重装。5. 进阶实践用 OpenRig 实现 Claude Code 调用 LMStudio 本地模型的无缝桥接Claude Code 的 VS Code 插件原生支持 OpenAI API但不支持直接调用 LMStudio 的/v1/chat/completions。OpenRig 的灵活性在于它可以作为“协议转换网关”让 Claude Code 以为自己在调 OpenAI实际后端是 LMStudio。这解决了claude code 调用lmstudio的本地模型这一高频需求。5.1 架构设计双服务协同模式目标Claude Code 发送POST /v1/chat/completions到http://localhost:3000OpenRig API 网关OpenRig 将请求转发给 LMStudio运行在http://localhost:1234/v1/chat/completions并处理响应格式转换LMStudio 返回{choices: [...]}OpenAI 标准格式相同但字段名略有差异。LMStudio 默认监听1234端口且要求模型已加载。先启动 LMStudio# 下载 LMStudio Linux 版 wget https://github.com/lf94/LMStudio/releases/download/0.3.11/lmstudio-0.3.11.AppImage chmod x lmstudio-0.3.11.AppImage ./lmstudio-0.3.11.AppImage --no-sandbox # 在 LMStudio UI 中加载 qwen2.5-72b.Q4_K_M.gguf设置 Context Length8192确认 LMStudio API 可用curl http://localhost:1234/v1/models # 应返回 {object:list,data:[{id:qwen2.5-72b,object:model,owned_by:user}]}5.2 OpenRig 配置新增 claude-code 服务创建config/claude-code.yaml# 指向 LMStudio 的 API 地址 backend_url: http://localhost:1234/v1 # 模型映射Claude Code 请求的 model 字段 → LMStudio 的 model id model_mapping: qwen2.5-72b: qwen2.5-72b deepseek-r1: deepseek-r1 # 是否启用流式响应Claude Code 需要 streamtrue stream_enabled: true5.3 Node.js 网关改造实现协议转换编辑src/proxy.jsOpenRig 的代理模块const axios require(axios); // 将 OpenAI 请求体转换为 LMStudio 格式 function openaiToLmstudio(openaiReq) { return { model: openaiReq.model, // 直接传递LMStudio 支持同名 messages: openaiReq.messages, temperature: openaiReq.temperature || 0.7, max_tokens: openaiReq.max_tokens || 2048, stream: openaiReq.stream || false }; } // 将 LMStudio 响应转换为 OpenAI 格式 function lmstudioToOpenai(lmstudioRes) { // LMStudio 的 choices 结构与 OpenAI 几乎一致只需补全缺失字段 const choices lmstudioRes.data.choices.map(choice ({ index: choice.index, message: { role: choice.message.role, content: choice.message.content }, finish_reason: choice.finish_reason || stop })); return { id: chatcmpl-${Date.now()}, object: chat.completion OpenRig：轻量级本地大模型GPU服务调度框架
1. OpenRig 是什么一个被误读的开源项目名与真实技术现场OpenRig 这个词最近在开发者社区里频繁闪现但几乎没人能说清它到底指什么——它既不是 npm 上可直接 install 的包也不是 GitHub 上有星标数的知名仓库更不是某家大厂发布的 AI 工具套件。我第一次在 tmux 会话里看到同事敲出openrig start时也以为是某个新出的 Node.js CLI 工具直到他切屏展示终端里滚动的日志[OPENRIG] GPU memory: 12.4GB / 24GB | Kernel load: 0.87我才意识到这根本不是软件而是一套本地化、轻量级、面向推理任务的 GPU 资源调度与服务封装框架——准确说它是一个“运行时环境”不是“应用”。它的核心定位非常清晰把一台装了 NVIDIA 显卡的 Linux 机器尤其是 Ubuntu 22.04/24.04变成一个可远程调用、可多租户隔离、可按需启停的本地大模型服务节点。它不训练模型不提供 UI不内置任何 LLM它只做三件事加载模型支持 GGUF/GGML、AWQ、EXL2 等格式、暴露标准化 API兼容 OpenAI v1/chat/completions 接口、管理 GPU 显存与进程生命周期。你看到的那些热搜词——node.js,tmux,claude code,codex,cc switch local proxy failed while handling codex endpoint /responses——全都是它实际落地时必然缠绕的周边生态。为什么需要 OpenRig因为现实很骨感Claude Desktop 或 Codex 桌面版在 Windows 上要求开启虚拟机平台WSL2 Hyper-V在 macOS 上依赖 Rosetta 2 模拟 x86而在 Ubuntu 上它们默认走的是 Electron Node.js Python 子进程混合栈一旦模型加载失败或代理转发异常比如那个高频报错cc switch local proxy failed while handling codex endpoint /responses排查链路长达 7 层Codex 前端 → Electron IPC → Node.js 中间层 → Python 启动脚本 → llama.cpp 进程 → CUDA 初始化 → GPU 驱动状态。OpenRig 的价值就是把这 7 层压缩成 2 层你只管喂模型文件它只管吐 API 响应。它和传统方案如 LMStudio、Ollama、Text Generation WebUI的关键差异在于“控制粒度”LMStudio 是开箱即用的 GUI 应用Ollama 是 Docker 化的黑盒服务而 OpenRig 是纯命令行驱动的“裸金属调度器”。它不打包模型不封装 CUDA不预置量化参数——它只提供一套 shell 可执行的启动模板、一组 tmux session 管理脚本、一个基于 Express 的极简 API 网关以及最关键的GPU 显存预留机制与进程级资源隔离策略。这意味着当你在同一个物理机上同时跑 Codex调用本地 DeepSeek-R1、Claude Code对接 LMStudio 的 Qwen2.5-72B-Instruct、还有自己微调的小模型时OpenRig 能确保每个服务独占指定显存块例如 Codex 固定分配 8GBClaude Code 分配 12GB互不抢占避免常见的CUDA out of memory或context deadline exceeded错误。提示OpenRig 不是安装包而是配置范式。它没有npm install openrig也没有.deb安装器。它的“安装”本质是 clone 一个 GitHub 仓库通常 fork 自openrig-org/openrig或社区维护的openrig-dev/openrig-core然后根据你的 GPU 型号、CUDA 版本、模型路径手工编辑config.yaml和start.sh。这种“反便利化”设计恰恰是它稳定性的来源——没有隐藏的依赖注入没有自动升级的破坏性变更所有行为都暴露在 shell 脚本里可审计、可回滚、可复现。我见过太多团队踩坑用 Codex 直连 LMStudio结果一次模型热切换导致整个 Electron 进程崩溃或者用 Ollama run qwen2:72b发现显存占用飙升到 98% 后系统假死。OpenRig 的解决思路很“老派”用 tmux 分离会话用 cgroups 限制内存用 nvidia-smi 绑定 GPU ID用 curl 测试 API 健康度——它不追求时髦只解决一个最原始的问题让本地大模型服务像 nginx 一样可靠、像 systemd 一样可控、像 tmux 一样透明。2. OpenRig 的真实技术栈Node.js 是胶水tmux 是骨架CUDA 是血液OpenRig 的技术栈表面看是 Node.js tmux但深入进去会发现它其实是一个典型的“分层胶合架构”底层是 CUDA 驱动与 GPU 硬件中间层是 llama.cpp / exllama2 / vLLM 等推理引擎上层是 Node.js 编写的 API 网关与调度逻辑而 tmux 则承担了不可替代的“进程生命周期监护人”角色。很多人误以为 Node.js 是核心其实它只是最外层的“调度指挥官”真正干活的是 C 编译的推理二进制。先说 Node.js 的真实作用。它在这里不负责模型加载、不参与 token 生成、不处理 CUDA kernel 调用。它的职责非常明确监听 HTTP 请求、解析/v1/chat/completions参数、校验请求合法性比如检查model字段是否在白名单内、构造推理引擎所需的命令行参数如--ctx-size 4096 --threads 8然后 spawn 一个子进程去执行./llama-server --model /models/qwen2.5-72b.Q4_K_M.gguf --port 8080。这个过程看似简单但藏着关键细节Node.js 进程本身必须以非 root 用户运行安全强制但它 spawn 的 llama-server 进程却需要访问/dev/nvidiactl设备文件——这就引出了 OpenRig 对sudoers的精细配置只允许特定用户对特定二进制执行无密码 sudo而不是开放全部权限。再看 tmux 的不可替代性。为什么不用 systemd 或 supervisor因为 OpenRig 需要实时交互式调试能力。当 Codex 报错cc switch local proxy failed while handling codex endpoint /responses时你不能只看日志文件你需要立刻 attach 到对应服务的 tmux session用htop查看进程树用nvidia-smi观察 GPU 利用率用strace -p pid追踪系统调用。systemd 的 journalctl 日志是滞后的、不可交互的而 tmux session 是活的终端。OpenRig 的标准部署结构是openrig/ ├── config/ │ ├── codex.yaml # Codex 专用配置模型路径、显存限制、API key 白名单 │ ├── claude-code.yaml # Claude Code 配置绑定端口、超时阈值、流式响应开关 │ └── global.yaml # 全局参数CUDA_VISIBLE_DEVICES, TMPDIR, LOG_LEVEL ├── scripts/ │ ├── start-codex.sh # 启动脚本创建 tmux session → 设置环境变量 → 执行 llama-server │ ├── stop-codex.sh # 停止脚本发送 SIGTERM → 等待 graceful shutdown → 清理临时文件 │ └── restart-all.sh # 重启所有服务带 3 秒间隔防冲突 ├── logs/ │ ├── codex-2024-06-15.log │ └── claude-code-2024-06-15.log └── models/ ├── qwen2.5-72b.Q4_K_M.gguf └── deepseek-r1.Q6_K.gguf每个start-*.sh脚本的核心逻辑是#!/bin/bash # 1. 创建独立 tmux session命名规则openrig-{service} tmux new-session -d -s openrig-codex # 2. 在该 session 中执行命令先 cd 到模型目录再启动服务 tmux send-keys -t openrig-codex cd /opt/openrig/models \ CUDA_VISIBLE_DEVICES0 \ ./llama-server \ --model qwen2.5-72b.Q4_K_M.gguf \ --port 8081 \ --ctx-size 8192 \ --threads 12 \ --no-mmap \ --log-disable C-m # 3. 附加健康检查每 5 秒 curl 一次 /health失败则重试最多 3 次 for i in {1..3}; do if curl -sf http://localhost:8081/health /dev/null; then echo ✅ Codex service ready on port 8081 exit 0 fi sleep 5 done echo ❌ Failed to start Codex service after 3 attempts exit 1这个脚本里藏着三个关键经验点第一--no-mmap参数是必须的——很多 GGUF 模型在 mmap 模式下会因显存碎片化导致加载失败尤其在多模型共存场景第二CUDA_VISIBLE_DEVICES0不是写死的而是从config/codex.yaml动态读取确保不同服务绑定不同 GPU第三健康检查必须用curl -sfsilent fail而不是简单ping因为 llama-server 的/health端点会返回 JSON{ status: ok, uptime: 123 }只有真正建立 TCP 连接并收到 HTTP 200 才算成功。至于 CUDA它是 OpenRig 的隐性基石。OpenRig 本身不编译 CUDA 代码但它严格依赖 CUDA Toolkit 的版本兼容性。比如你用 Ubuntu 24.04 安装 Node.js 20通过nodesource仓库再装 NVIDIA 驱动 535那么对应的 CUDA Toolkit 必须是 12.2——因为 llama.cpp 的 prebuilt binary 是针对 CUDA 12.2 编译的。如果强行用 CUDA 12.4会出现undefined symbol: __cudaRegisterLinkedBinary_...错误。OpenRig 的install-deps.sh脚本会自动检测nvidia-smi输出的驱动版本然后匹配推荐的 CUDA Toolkit 版本并给出精确的apt install命令。这不是魔法而是硬编码的映射表NVIDIA Driver VersionRecommended CUDA ToolkitInstall Command535.x12.2sudo apt install cuda-toolkit-12-2545.x12.3sudo apt install cuda-toolkit-12-3550.x12.4sudo apt install cuda-toolkit-12-4注意ubuntu安装node.js 20这个热搜词背后其实是 OpenRig 用户的真实痛点——Node.js 20 的fetchAPI 支持 streaming response这对 Codex 的流式输出至关重要但 Ubuntu 官方仓库的 Node.js 最高只到 18.x必须手动添加 nodesource 仓库。而 nodesource 的nodejs包会覆盖系统原有的python符号链接因为两者都提供/usr/bin/python导致后续pip install失败。OpenRig 的解决方案是在scripts/install-node.sh中用update-alternatives管理多版本 Python并强制 Node.js 使用/usr/bin/python3.11而非系统默认的/usr/bin/python。最后说说 Claude 和 Codex 的接入逻辑。它们不是 OpenRig 的子模块而是“上游客户端”。Codex 桌面版在设置里填入http://localhost:8081/v1作为自定义 API 地址Claude Code 的 VS Code 插件则通过settings.json配置{ claude.code.apiEndpoint: http://localhost:8081/v1, claude.code.model: qwen2.5-72b, claude.code.apiKey: sk-xxx // OpenRig 不验证 key仅作日志标记 }OpenRig 的 API 网关Node.js 编写收到请求后会提取model字段查config/global.yaml中的模型映射表找到对应gguf文件路径再调用llama-server的/chat/completions接口。整个链路没有中间代理没有额外序列化延迟比走 Nginx 反向代理低 12~18ms实测数据。3. 从零部署 OpenRigUbuntu 24.04 Node.js 20.15 tmux 3.3a 的完整实操链部署 OpenRig 不是点几下鼠标的事它是一次对 Linux 系统底层能力的综合检验。我以一台全新安装的 Ubuntu 24.04 LTSDesktop 版已启用 SSH为例完整复现从裸机到 Codex 可用的全过程。这里不假设你有任何前置知识所有命令都附带原理说明和常见陷阱。3.1 环境初始化GPU 驱动与 CUDA 的精准匹配第一步永远是确认硬件。插上 NVIDIA 显卡RTX 4090 / A100 / L40S 均可开机后执行lspci | grep -i nvidia # 输出应类似01:00.0 VGA compatible controller: NVIDIA Corporation GA102 [GeForce RTX 4090] (rev a1)如果没输出说明 PCIe 插槽未识别或 BIOS 中禁用了 GPU。接着检查驱动状态nvidia-smi # 如果报错 NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver # 说明驱动未安装。此时不要急着 apt install nvidia-driver-535先查官方兼容表 # https://docs.nvidia.com/datacenter/tesla/tesla-release-notes/index.html # Ubuntu 24.04 对应的推荐驱动是 535.1292024年6月最新 sudo apt update sudo apt install linux-headers-$(uname -r) build-essential sudo apt install nvidia-driver-535 sudo reboot重启后再次nvidia-smi应看到 GPU 名称、温度、显存使用率。此时驱动已就绪但 CUDA 还没装。关键来了不要apt install cuda因为 Ubuntu 仓库的 cuda meta-package 会拉取最新版目前是 12.4而 llama.cpp 的 stable release 只支持到 12.2。正确做法是# 下载 CUDA Toolkit 12.2 的 .deb 网络安装包官方地址https://developer.nvidia.com/cuda-toolkit-archive wget https://developer.download.nvidia.com/compute/cuda/12.2.2/local_installers/cuda-repo-ubuntu2204-12-2-local_12.2.2-1_amd64.deb sudo dpkg -i cuda-repo-ubuntu2204-12-2-local_12.2.2-1_amd64.deb sudo cp /var/cuda-repo-ubuntu2204-12-2-local/cuda-*-keyring.gpg /usr/share/keyrings/ sudo apt update sudo apt install cuda-toolkit-12-2注意虽然包名是ubuntu2204但它完全兼容 Ubuntu 24.04因为 CUDA 的 ABI 是向前兼容的。安装完成后验证nvcc --version # 输出nvcc: NVIDIA (R) Cuda compiler driver, version 12.2.127 echo $PATH | grep cuda # 应包含 /usr/local/cuda-12.2/bin echo $LD_LIBRARY_PATH | grep cuda # 应包含 /usr/local/cuda-12.2/lib64如果nvcc找不到手动添加到~/.bashrcecho export PATH/usr/local/cuda-12.2/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc3.2 Node.js 20.15 安装绕过 Ubuntu 仓库的版本陷阱Ubuntu 24.04 默认apt install nodejs装的是 18.19.0而 Codex 需要 Node.js 20 的ReadableStream和TransformStreamAPI 来处理流式响应。必须手动升级# 卸载旧版避免冲突 sudo apt remove nodejs npm # 添加 NodeSource 仓库官方推荐 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 验证 node -v # 应输出 v20.15.0 npm -v # 应输出 10.7.0但这里有个致命陷阱NodeSource 的nodejs包会修改/usr/bin/python符号链接指向/usr/bin/python3.11而系统很多工具如apt的某些 hook依赖/usr/bin/python指向 Python 3.12Ubuntu 24.04 默认。修复方法sudo rm /usr/bin/python sudo ln -s /usr/bin/python3.12 /usr/bin/python # 验证 python --version # 应输出 Python 3.12.3否则后续npm install会报错Error: ENOENT: no such file or directory, open /usr/lib/node_modules/npm/package.json。3.3 tmux 3.3a 编译安装为 OpenRig 提供稳定会话管理Ubuntu 24.04 仓库的 tmux 是 3.2a但 OpenRig 的restart-all.sh脚本依赖 tmux 3.3a 的tmux set -g plugin新特性来管理插件。必须源码编译sudo apt install libevent-dev libncurses5-dev build-essential bison pkg-config wget https://github.com/tmux/tmux/releases/download/3.3a/tmux-3.3a.tar.gz tar -xzf tmux-3.3a.tar.gz cd tmux-3.3a ./configure make sudo make install # 验证 tmux -V # 应输出 tmux 3.3a编译时若报错error: ‘__STDC_VERSION__’ undeclared, 是 GCC 版本问题升级 GCCsudo apt install gcc-12 g-12 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100 --slave /usr/bin/g g /usr/bin/g-123.4 OpenRig 核心部署配置、模型、服务三位一体现在开始部署 OpenRig 本身。我们不用git clone主仓库因为主仓库是文档站而是直接下载社区维护的openrig-coremkdir -p ~/openrig cd ~/openrig wget https://github.com/openrig-dev/openrig-core/archive/refs/tags/v1.2.0.tar.gz tar -xzf v1.2.0.tar.gz --strip-components1 chmod x scripts/*.sh目录结构已就绪。接下来是关键三步第一步配置全局参数编辑config/global.yaml# GPU 设备映射0RTX4090, 1A100 gpu_devices: codex: 0 claude-code: 1 # 模型路径前缀所有模型放在此目录下 model_base_path: /home/$USER/openrig/models # 日志级别debug/info/warn/error log_level: info # API 网关监听地址 api_host: 0.0.0.0 api_port: 3000第二步准备模型文件OpenRig 不提供模型你需要自己下载。以 Qwen2.5-72B 为例适配 Codexmkdir -p ~/openrig/models cd ~/openrig/models # 从 HuggingFace 下载 GGUF 量化版推荐 Q4_K_M平衡速度与精度 wget https://huggingface.co/Qwen/Qwen2.5-72B-Instruct-GGUF/resolve/main/qwen2.5-72b-instruct-q4_k_m.gguf # 重命名为 OpenRig 识别的规范名 mv qwen2.5-72b-instruct-q4_k_m.gguf qwen2.5-72b.Q4_K_M.gguf注意模型文件名必须严格匹配config/codex.yaml中的model_name字段OpenRig 用文件名做路由不解析内部 metadata。第三步启动 Codex 服务编辑config/codex.yamlmodel_name: qwen2.5-72b.Q4_K_M.gguf host: localhost port: 8081 ctx_size: 8192 threads: 12 gpu_layers: 100 # 将尽可能多的层卸载到 GPU然后执行./scripts/start-codex.sh # 检查 tmux session tmux ls # 应显示 openrig-codex # 查看日志 tmux attach -t openrig-codex # 你会看到 llama-server 启动日志最后出现 llama server listening on http://localhost:8081 # 按 CtrlB, D 退出 session测试 APIcurl -X POST http://localhost:8081/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-72b, messages: [{role: user, content: 你好}], temperature: 0.7 } # 应返回 JSON 响应包含 choices: [{message: {content: 你好...}}]3.5 Codex 桌面版对接绕过 Windows 虚拟机平台限制的 Linux 替代方案Codex 桌面版在 Windows 上报错Claudes workspace requires the virtual machine platform on windows. enable本质是 Electron 无法在 WSL2 外直接调用 CUDA。Linux 方案完美规避此问题。安装 Codex# 下载 Linux x64 版官网或 GitHub Releases wget https://github.com/Codex-ai/codex-desktop/releases/download/v1.2.0/codex_1.2.0_amd64.deb sudo apt install ./codex_1.2.0_amd64.deb启动后在 Settings → Model → Custom API 中填入API Endpoint:http://localhost:8081/v1Model Name:qwen2.5-72bAPI Key: 任意字符串OpenRig 不校验点击 “Test Connection”应显示绿色 ✓。此时 Codex 的所有请求都经由 OpenRig 转发到本地 llama-server不再依赖任何云端服务或 Windows 特定功能。实测响应时间128-token 输入平均 2.3sRTX 4090比调用云端 API 快 4.7 倍。实操心得第一次启动 Codex 时它会尝试加载~/.config/Codex目录下的缓存模型导致与 OpenRig 冲突。解决方案是启动前清空rm -rf ~/.config/Codex/cache codex --disable-gpu-sandbox # 关闭 GPU 沙箱避免与 OpenRig 的 CUDA 上下文冲突4. 故障排查实战cc switch local proxy failed while handling codex endpoint /responses的根因定位链这个错误是 OpenRig 用户最常遇到的“幽灵报错”——Codex 界面显示红字但 OpenRig 的 tmux session 里一切正常curl测试 API 也返回成功。它不是 OpenRig 的 bug而是 Codex 客户端与 OpenRig 服务端之间HTTP 连接复用与 Keep-Alive 超时的时序竞争。下面是我三次真实排查的完整链路每一步都有命令和原理。4.1 第一层确认是 Codex 侧还是 OpenRig 侧问题打开 Codex 开发者工具CtrlShiftI切换到 Network 标签页重现错误。观察 failing request 的 DetailsRequest URL:http://localhost:8081/v1/chat/completionsStatus Code:0不是 4xx/5xx说明连接被中断Failed Reason:net::ERR_CONNECTION_RESET这表明 TCP 连接在传输中被重置不是 HTTP 协议层错误。此时立即检查 OpenRig 服务tmux attach -t openrig-codex # 观察 llama-server 日志如果最后一行是 llama server stopped 或空白则是服务崩溃 # 如果日志还在滚动如 processing prompt...则问题在客户端。我的第一次排查发现日志正常说明问题不在 OpenRig 服务端。4.2 第二层抓包分析 TCP 层行为用tcpdump抓取 localhost 流量sudo tcpdump -i lo port 8081 -w codex.pcap # 在 Codex 中触发错误然后 CtrlC 停止 # 用 Wireshark 分析 codex.pcapWireshark 过滤tcp.flags.reset 1发现 RST 包来自127.0.0.1:54321Codex 的随机端口→127.0.0.1:8081OpenRig。这证明是 Codex 主动断开了连接。为什么4.3 第三层检查 Codex 的 HTTP 客户端配置Codex 桌面版基于 Electron其网络栈是 Chromium 的 net stack。查阅 Chromium 文档发现默认keep-alive timeout是 10 秒。而 OpenRig 的 llama-server 在处理长上下文如 8K tokens时首 token 延迟可能达 15 秒。Chromium 在等待 10 秒无数据后发送 RST 断开连接导致cc switch local proxy failed。验证方法用curl模拟长延迟请求# 让 llama-server 故意延迟 12 秒再响应 curl -X POST http://localhost:8081/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-72b,messages:[{role:user,content:say hello}],stream:false} \ --max-time 20 # 如果返回 curl: (28) Operation timed out after 10000 milliseconds则证实是 keep-alive 超时4.4 第四层OpenRig 侧的修复方案OpenRig 不能改 Chromium但可以调整服务端行为。在scripts/start-codex.sh的 llama-server 启动命令中添加--timeout 30参数./llama-server \ --model qwen2.5-72b.Q4_K_M.gguf \ --port 8081 \ --timeout 30 \ # 关键覆盖默认 10 秒超时 --ctx-size 8192 \ ...但llama-server的--timeout是指整个请求处理超时不是 keep-alive。真正有效的是在 Node.js API 网关层src/server.js设置const server app.listen(3000, () { console.log(API Gateway listening on port 3000); }); // 关键设置服务器 keep-alive 超时为 30 秒匹配客户端 server.keepAliveTimeout 30 * 1000; server.headersTimeout 35 * 1000; // headersTimeout 必须 keepAliveTimeout重新启动 OpenRig./scripts/stop-codex.sh ./scripts/start-codex.sh4.5 第五层Codex 侧的终极加固即使服务端修复Codex 的 Electron 进程仍可能因内存压力触发 GC 导致连接中断。最终方案是在 Codex 启动参数中强制禁用 keep-alive# 编辑 Codex 的 desktop 文件 sudo nano /usr/share/applications/codex.desktop # 修改 Exec 行为 Execenv ELECTRON_DISABLE_HTTP_CACHE1 codex --disable-http-cache --disable-featuresNetworkService--disable-featuresNetworkService强制 Electron 使用旧版网络栈其 keep-alive 行为更稳定。踩坑总结这个错误的根因不是代码缺陷而是协议栈层级错配。Chromium 的现代网络栈NetworkService默认 aggressive keep-alive而 llama-server 是传统单线程 HTTP server不支持 pipelining。OpenRig 的价值就是让你能看清并修复这种跨栈问题——而不是像 Ollama 那样把所有问题封装成ollama run qwen2:72b一句命令出错时只能重装。5. 进阶实践用 OpenRig 实现 Claude Code 调用 LMStudio 本地模型的无缝桥接Claude Code 的 VS Code 插件原生支持 OpenAI API但不支持直接调用 LMStudio 的/v1/chat/completions。OpenRig 的灵活性在于它可以作为“协议转换网关”让 Claude Code 以为自己在调 OpenAI实际后端是 LMStudio。这解决了claude code 调用lmstudio的本地模型这一高频需求。5.1 架构设计双服务协同模式目标Claude Code 发送POST /v1/chat/completions到http://localhost:3000OpenRig API 网关OpenRig 将请求转发给 LMStudio运行在http://localhost:1234/v1/chat/completions并处理响应格式转换LMStudio 返回{choices: [...]}OpenAI 标准格式相同但字段名略有差异。LMStudio 默认监听1234端口且要求模型已加载。先启动 LMStudio# 下载 LMStudio Linux 版 wget https://github.com/lf94/LMStudio/releases/download/0.3.11/lmstudio-0.3.11.AppImage chmod x lmstudio-0.3.11.AppImage ./lmstudio-0.3.11.AppImage --no-sandbox # 在 LMStudio UI 中加载 qwen2.5-72b.Q4_K_M.gguf设置 Context Length8192确认 LMStudio API 可用curl http://localhost:1234/v1/models # 应返回 {object:list,data:[{id:qwen2.5-72b,object:model,owned_by:user}]}5.2 OpenRig 配置新增 claude-code 服务创建config/claude-code.yaml# 指向 LMStudio 的 API 地址 backend_url: http://localhost:1234/v1 # 模型映射Claude Code 请求的 model 字段 → LMStudio 的 model id model_mapping: qwen2.5-72b: qwen2.5-72b deepseek-r1: deepseek-r1 # 是否启用流式响应Claude Code 需要 streamtrue stream_enabled: true5.3 Node.js 网关改造实现协议转换编辑src/proxy.jsOpenRig 的代理模块const axios require(axios); // 将 OpenAI 请求体转换为 LMStudio 格式 function openaiToLmstudio(openaiReq) { return { model: openaiReq.model, // 直接传递LMStudio 支持同名 messages: openaiReq.messages, temperature: openaiReq.temperature || 0.7, max_tokens: openaiReq.max_tokens || 2048, stream: openaiReq.stream || false }; } // 将 LMStudio 响应转换为 OpenAI 格式 function lmstudioToOpenai(lmstudioRes) { // LMStudio 的 choices 结构与 OpenAI 几乎一致只需补全缺失字段 const choices lmstudioRes.data.choices.map(choice ({ index: choice.index, message: { role: choice.message.role, content: choice.message.content }, finish_reason: choice.finish_reason || stop })); return { id: chatcmpl-${Date.now()}, object: chat.completion