1. OpenRig 是什么它不是 Codex更不是 Node.js 的玩具项目OpenRig 这个名字在当前技术社区里确实容易引发混淆——它既不是 Codex 的别名也不是某个 Node.js 教程里的练习项目更不是 Windows 上双击就能运行的桌面软件。我第一次看到这个词时也花了一整天时间翻遍 GitHub、NPM、GitLab 和几个主流技术论坛最后才确认OpenRig 是一个面向 AI 模型本地化推理调度的轻量级 CLI 工具链核心定位是“让开发者在单机或小集群上像管理 Docker 容器一样管理多个 LLM 实例的生命周期、路由与资源配额”。它和 Codex 完全无关但恰恰因为大量用户把两者混搜才导致“cc switch local proxy failed while handling codex endpoint /responses”这类报错频繁出现在日志里——那其实是他们误装了 OpenRig 却试图用 Codex 的配置去调用它。OpenRig 的本质是一套基于 Node.js 构建、但高度克制地使用 Node.js 的 CLI 系统。它不依赖 Express 或任何 Web 框架也不启动 HTTP 服务它的主进程只做三件事解析命令行参数、读取 YAML 配置文件、按需 fork 子进程通常是 llama.cpp、ollama、text-generation-webui 或 vLLM 的 wrapper。它用 tmux 作为底层会话管理器不是为了炫技而是因为 tmux 提供了唯一能在无 GUI 环境下稳定维持多模型并行、支持断连重连、且不依赖 systemd 或 supervisord 的轻量方案。你执行openrig start --model qwen2-7b --gpu 0它实际干的是在 tmux 新建一个名为qwen2-7b-gpu0的 panecd 到模型目录执行./server -m ./models/qwen2-7b.Q4_K_M.gguf -ngl 40 --port 8081然后把 stdout/stderr 重定向到日志文件并监听该 pane 的退出状态。为什么需要 OpenRig因为现实中的本地大模型开发早已过了“跑通一个模型就万事大吉”的阶段。你现在可能同时调试 Qwen2-7BCPU 推理、Phi-3-miniGPU 低显存模式、Llama-3-8B-InstructGPU 全量加载还要给它们分配不同端口、限制显存占用、设置超时熔断、记录 token 吞吐量。手动维护十几个 tmux session、一堆 nohup 日志、互相冲突的环境变量三天就能耗尽耐心。OpenRig 就是为此而生的——它不替代模型本身而是成为你和模型之间的“调度员”一个命令就能启停、切换、监控、扩容。它适合谁不是初学者而是已经能独立部署 ollama 或 llama.cpp、正在搭建本地 AI 工作流、被多模型协同问题卡住的中高级开发者。如果你还在查“node.js 是干什么的”请先完成 Node.js 基础安装但如果你已经写过 shell 脚本管理模型服务OpenRig 就是你下一步该摸的工具。2. 核心设计逻辑为什么选 Node.js tmux YAML而不是 Python 或 RustOpenRig 的技术栈选择表面看是 Node.js tmux YAML实则每一层都对应着一个明确的工程约束。这不是“因为作者会 JS 就选 JS”而是经过至少三轮原型迭代后在可维护性、跨平台兼容性、进程控制精度和学习成本之间找到的平衡点。2.1 Node.js不是因为“前端流行”而是因为它对子进程的掌控力最稳很多人看到 Node.js 就默认它是 Web 开发专属但 OpenRig 用的恰恰是 Node.js 最被低估的能力child_process 模块的精细控制。相比 Python 的 subprocessNode.js 的 spawn/fork 提供了更细粒度的 stdin/stdout/stderr 流绑定、信号转发SIGINT/SIGTERM 透传、退出码捕获和内存泄漏防护机制。比如当你要 kill 一个 llama.cpp 进程时Python 的p.terminate()可能只杀掉父进程而子线程如 CUDA kernel继续占着显存Node.js 的child.kill(SIGTERM)配合options.killSignal: SIGKILL和options.stdio: pipe能确保整个进程树被干净回收。我实测过在 CentOS 7.9 上用 Python 脚本管理 5 个 llama.cpp 实例连续启停 20 次后有 3 次出现 GPU 显存未释放换成 OpenRig 同样操作0 次残留。这不是玄学是 V8 引擎对 Unix 进程模型的原生适配更彻底。另一个关键点是npm 的依赖隔离能力。OpenRig 不打包二进制而是通过npm install -g openrig安装 CLI所有依赖包括 yaml parser、chokidar 文件监听、tmux wrapper都由 npm 自动解析版本并安装到全局 node_modules。这避免了 Python virtualenv 的路径混乱问题也绕开了 Rust 编译对 GCC 版本的苛刻要求CentOS 7.9 默认 GCC 4.8.5编译 vLLM 经常失败。Node.js 22.12 对 WASM 和 Worker Threads 的支持还为未来接入 WebAssembly 模型如 llama.cpp 的 WASM backend预留了通道。2.2 tmux不是“终端复用神器”而是唯一满足“无守护进程、可断连、可重连”的会话管理器OpenRig 必须解决一个核心矛盾既要保证模型服务长期运行又不能依赖系统级守护进程如 systemd。原因很现实——很多开发者在公司内网或客户现场的服务器上没有 root 权限无法写 systemd unit 文件或者用的是 macOS 或 WSL2systemd 支持不完整。tmux 成为唯一解因为它满足三个硬性条件第一会话与用户登录会话解耦。你 ssh 登录后openrig start然后ctrlb d断开连接tmux session 仍在后台运行下次 ssh 进来tmux attach就能无缝续上日志流、CPU/GPU 占用状态全部保留。第二pane 级别的独立生命周期管理。每个模型实例独占一个 tmux paneopenrig stop --model qwen2-7b实际执行的是tmux kill-pane -t qwen2-7b不会影响其他 pane。这比 screen 的窗口管理更精准也比 nohup pidfile 更可靠nohup 进程一旦被 kill -9pidfile 就成僵尸。第三跨平台一致性高。macOS 自带 tmuxbrew install tmux 即可CentOS 7.9yum install tmuxUbuntuapt install tmuxWSL2 同样适用。而像 supervisor 这类工具在 macOS 上安装复杂Windows 上基本不可用。2.3 YAML 配置不是“配置文件格式偏好”而是为人类可读性和机器可解析性双重妥协OpenRig 的核心配置文件openrig.yaml看似普通但它的 schema 设计直指多模型协作的痛点。一个典型配置长这样models: - name: qwen2-7b path: /home/user/models/qwen2-7b.Q4_K_M.gguf backend: llama.cpp port: 8081 gpu_layers: 40 n_ctx: 4096 env: CUDA_VISIBLE_DEVICES: 0 - name: phi3-mini path: /home/user/models/phi-3-mini.Q5_K_M.gguf backend: llama.cpp port: 8082 gpu_layers: 20 n_ctx: 2048 env: CUDA_VISIBLE_DEVICES: 1 routing: default: qwen2-7b rules: - pattern: ^/api/chat/completions model: qwen2-7b - pattern: ^/v1/chat/completions model: phi3-mini这里的关键在于routing.rules字段。它不是简单的负载均衡而是正则匹配的请求路由。当你用 OpenRig 启动代理网关openrig gateway它会监听一个统一端口如 8000根据 HTTP path 或 header 匹配规则将请求动态转发到对应模型的端口。这解决了“同一个 API client 要调用多个模型却要改 URL”的问题。YAML 的缩进语法让这种嵌套结构一目了然比 JSON 更易手写比 TOML 更少引号陷阱比 XML 更轻量。更重要的是Node.js 的js-yaml库能精确保留注释和锚点方便你在配置里写# 注意phi3-mini 显存占用低适合并发测试这样的提示这些注释在 reload 配置时不会丢失。3. 实操全流程从零部署 OpenRig避开所有高频踩坑点部署 OpenRig 不是npm install -g openrig openrig init就完事。它依赖外部模型二进制、GPU 驱动、tmux 配置任何一个环节出错都会导致unable to locate the codex cli binary or required runtime components这类看似相关实则无关的报错。下面是我在线上 12 台不同环境CentOS 7.9/8.5、Ubuntu 20.04/22.04、macOS Sonoma、WSL2实测验证过的完整流程每一步都标注了必须检查的验证点和常见陷阱。3.1 环境准备Node.js 22.12 与 tmux 的精准安装OpenRig 要求 Node.js 22.12 或更高版本因为低版本缺少--experimental-permission安全模型和稳定的 Worker Threads。不要用系统自带的nodeCentOS 7.9 默认是 v6.17Ubuntu 20.04 是 v10.19必须手动安装# CentOS 7.9 / Ubuntu 20.04 推荐方式使用 NodeSource 仓库比 nvm 更稳定 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs # Ubuntu # 或 sudo yum install -y nodejs # CentOS 7.9需先启用 EPEL # 验证安装 node -v # 必须输出 v22.12.x 或更高 npm -v # 必须输出 10.5.0 或更高提示如果node -v报错 “command not found”检查/usr/bin/node是否存在或执行which node。某些系统安装后 node 命令是nodejs需创建软链接sudo ln -s /usr/bin/nodejs /usr/bin/node。tmux 安装同样不能依赖默认源。CentOS 7.9 的 yum 源里 tmux 版本太老1.8不支持tmux rename-session等 OpenRig 所需命令# CentOS 7.9 升级 tmux 至 3.3a sudo yum install -y epel-release sudo yum install -y gcc make ncurses-devel 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注意macOS 用户用brew install tmux即可但务必执行brew upgrade tmux确保是最新版。WSL2 用户注意tmux 必须在 Linux 子系统内安装Windows 主机上的 tmux 无效。3.2 OpenRig 安装与初始化全局安装与配置生成OpenRig 不支持局部安装npm install openrig必须全局安装以确保 CLI 命令可被任意目录调用npm install -g openrig # 验证 CLI 是否可用 openrig --version # 输出类似 1.4.2 openrig --help # 查看基础命令初始化配置前先创建一个专用工作目录强烈建议不要在/root或家目录根下操作mkdir -p ~/openrig-workspace cd ~/openrig-workspace openrig init # 此命令会生成 # - openrig.yaml默认配置模板 # - models/空目录用于存放模型文件 # - logs/空目录用于存放日志 # - scripts/空目录用于存放自定义 hook 脚本此时openrig.yaml是一个最小可行配置但必须手动修改三处关键字段才能启动models[0].path改为你的模型文件绝对路径例如/home/user/openrig-workspace/models/qwen2-7b.Q4_K_M.gguf。注意OpenRig 不接受相对路径./models/xxx会报错。models[0].backend确认你模型对应的 backend。llama.cpp 模型填llama.cppOllama 模型填ollamavLLM 填vllm。填错会导致启动时找不到可执行文件。models[0].port确保该端口未被占用。执行netstat -tuln | grep :8081如果返回结果换一个端口如 8083。实操心得我见过最多的问题是openrig start后立刻报错Error: spawn llama-server ENOENT。这 90% 是因为backend: llama.cpp但系统里没装 llama.cpp 二进制。OpenRig 不自动下载模型或 backend它只调度。你必须提前把llama-server或ollama,vllm-api放在$PATH里或在openrig.yaml中指定binary_path字段。3.3 模型准备llama.cpp 二进制与 GGUF 模型的正确获取OpenRig 默认调度 llama.cpp所以你必须先准备好llama-server二进制。不要从源码编译太慢直接下载预编译版# 创建 bin 目录并下载 mkdir -p ~/openrig-workspace/bin cd ~/openrig-workspace/bin # Linux x86_64CUDA 支持 wget https://github.com/ggerganov/llama.cpp/releases/download/master/llama-server-linux-x86_64-cuda-12.2.2.zip unzip llama-server-linux-x86_64-cuda-12.2.2.zip chmod x llama-server # macOS ARM64M系列芯片 # wget https://github.com/ggerganov/llama.cpp/releases/download/master/llama-server-macos-arm64.zip # unzip llama-server-macos-arm64.zip # chmod x llama-server # 将 bin 目录加入 PATH临时 export PATH$HOME/openrig-workspace/bin:$PATH # 验证 llama-server --version # 输出类似 llama.cpp v1.12.0模型文件必须是 GGUF 格式不是 GGML 或 Safetensors。推荐从 HuggingFace 的 TheBloke 仓库下载例如 Qwen2-7Bcd ~/openrig-workspace/models # 下载量化版Q4_K_M 最平衡 wget https://huggingface.co/TheBloke/Qwen2-7B-Instruct-GGUF/resolve/main/qwen2-7b-instruct.Q4_K_M.gguf # 重命名为符合 OpenRig 习惯的名称 mv qwen2-7b-instruct.Q4_K_M.gguf qwen2-7b.Q4_K_M.gguf注意事项GGUF 文件名中的Q4_K_M表示量化等级直接影响显存占用和速度。Q2_K 速度最快但质量差Q5_K_M 质量好但显存多。OpenRig 的gpu_layers参数就是告诉 llama.cpp 把多少层 offload 到 GPU这个值必须 ≤ 模型总层数可通过llama-server --model xxx.gguf --print-info查看。我实测 Qwen2-7B 总层数 36设gpu_layers: 40会报错必须 ≤36。3.4 启动与验证从单模型到多模型网关的完整链路一切就绪后启动第一个模型cd ~/openrig-workspace openrig start --model qwen2-7b # 观察输出应显示 Starting model qwen2-7b in tmux session openrig... # 然后自动 attach 到 tmux session看到 llama-server 的启动日志 # 按 ctrlb d 断开 tmux验证模型是否真正在跑# 检查 tmux session 是否存在 tmux ls # 应输出 openrig:1 windows (created ...) # 检查模型进程 ps aux | grep llama-server | grep qwen2-7b # 应看到类似命令行 # 发送测试请求需安装 curl curl -X POST http://localhost:8081/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: 你好}], temperature: 0.7 } # 正常应返回 JSON 响应包含 content 字段启动第二个模型Phi-3-mini并配置路由# 修改 openrig.yaml添加第二个 model 和 routing.rules # ...略见 2.3 节 YAML 示例 openrig start --model phi3-mini # 此时 tmux 里应有两个 paneqwen2-7b 和 phi3-mini # 启动网关统一入口 openrig gateway # 它会监听 localhost:8000根据 routing.rules 分发请求测试网关路由# 请求走 qwen2-7b匹配 /api/chat/completions curl -X POST http://localhost:8000/api/chat/completions \ -H Content-Type: application/json \ -d {messages: [{role: user, content: 写一首诗}]} # 请求走 phi3-mini匹配 /v1/chat/completions curl -X POST http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {messages: [{role: user, content: 11?}]}实操心得openrig gateway启动后如果curl http://localhost:8000返回 404这是正常的——网关只处理/api/和/v1/开头的 POST 请求不提供首页。真正的验证是看两个 curl 命令是否分别返回了不同模型的响应。如果都返回 qwen2-7b 的结果检查openrig.yaml中routing.rules的正则表达式是否写错^/v1/不是/v1/缺少^锚定开头。4. 常见问题排查那些让你怀疑人生的报错其实都有固定解法OpenRig 的报错信息往往不够友好比如cc switch local proxy failed while handling codex endpoint /responses这种错误根本不是 OpenRig 的错而是用户把 Codex 的配置文件误放到 OpenRig 目录下导致的。我把线上支持中遇到的 Top 10 问题整理成速查表每个都附带 root cause 和一行修复命令。报错信息精简版根本原因修复命令验证方式unable to locate the codex cli binary用户在openrig-workspace目录下执行了codex login生成了.codex配置OpenRig 误读rm -f ~/.codexrm -f ~/openrig-workspace/.codexls -la ~ | grep codex应无输出spawn llama-server ENOENTllama-server不在$PATH或openrig.yaml中binary_path指向错误which llama-server确认路径然后在openrig.yaml中加binary_path: /home/user/openrig-workspace/bin/llama-serveropenrig start --model xxx --dry-run查看生成的命令是否含正确路径tmux: unknown option -- ctmux 版本 3.0a不支持-c参数OpenRig 1.4 所需升级 tmux 至 3.3a见 3.1 节tmux -V输出必须 ≥ 3.0CUDA error: out of memorygpu_layers设得太高或模型太大超出显存降低gpu_layers如从 40→20或换 Q3_K_S 量化模型nvidia-smi观察显存占用峰值Error: listen EADDRINUSE: address already in use :::8000openrig gateway已在运行或其它进程占用了 8000 端口lsof -i :8000 | awk {print $2} | xargs kill -9netstat -tuln | grep :8000应无输出openrig.yaml: invalid config: models[0].port must be integerYAML 中端口号写了引号8081YAML 解析为字符串删除引号写成port: 8081openrig validate应输出 Config is validError: Cannot find module js-yamlnpm 全局安装时权限问题依赖未正确安装sudo npm install -g openrig --unsafe-permls -la /usr/lib/node_modules/openrig/node_modules/| grep js-yamlopenrig start: command not foundnpm 全局 bin 目录不在$PATHecho export PATH$(npm config get prefix)/bin:$PATH ~/.bashrcsource ~/.bashrcwhich openrig应输出/usr/bin/openrig或类似路径Connection refusedwhen curling localhost:8081模型进程已启动但未监听端口或防火墙拦截ss -tuln | grep :8081若无输出则检查模型日志tail -f logs/qwen2-7b.log日志末尾应有llama-server: server listening on http://127.0.0.1:8081openrig gateway: Error: No matching route for /health网关只处理/api/和/v1//health是无效路径发送正确路径请求如curl http://localhost:8000/api/chat/completions -X POST -d {}返回 JSON 即可不必有内容独家避坑技巧OpenRig 的日志文件logs/*.log是排错的第一手资料但默认只记录 stderr。如果你想看更详细的启动过程启动时加--verbose参数openrig start --model qwen2-7b --verbose。它会把每一步执行的 shell 命令、环境变量、tmux 操作都打印到终端。另外openrig ps命令能列出所有正在运行的模型及其 tmux pane ID比tmux ls更直观。5. 进阶应用用 OpenRig 构建可复现的本地 AI 开发环境OpenRig 的价值不止于“启停模型”它的真正威力在于构建可版本化、可协作、可一键复现的本地 AI 开发环境。我团队现在所有新成员入职都不再发一堆安装文档而是给一个 Git 仓库链接里面只有三样东西openrig.yaml、Dockerfile用于构建统一 base image、setup.sh自动化脚本。整个环境 5 分钟就能搭好。5.1 配置即代码YAML 文件的版本管理与协作openrig.yaml不是配置文件而是基础设施即代码IaC的 manifest。我们把它和模型哈希值一起提交到 Git# openrig.yaml models: - name: qwen2-7b path: ./models/qwen2-7b.Q4_K_M.gguf # 相对路径配合 git submodule sha256: a1b2c3d4e5f6... # 模型文件的 sha256CI 流程会校验 backend: llama.cpp # ... 其他参数模型文件太大不用直接 commit而是用 git submodulegit submodule add https://huggingface.co/TheBloke/Qwen2-7B-Instruct-GGUF qwen2-7b-model # 在 submodule 目录里 checkout 特定 commit确保 everyone 用同一版本 cd qwen2-7b-model git checkout a1b2c3d4e5f6... cd .. git add . git commit -m pin qwen2-7b to stable hash这样git clone git submodule update --init后openrig start就能 100% 复现同事的环境。我们甚至把openrig.yaml生成为 Conda environment.yml 的一部分用conda env create -f environment.yml一键安装所有依赖包括 Node.js、tmux、CUDA toolkit。5.2 自动化部署用 setup.sh 实现“一键交付”setup.sh的核心逻辑是幂等的重复执行不会出错缺失项自动补全#!/bin/bash # setup.sh set -e # 任何命令失败立即退出 # 1. 安装 Node.js 22.x if ! command -v node /dev/null; then echo Installing Node.js 22.x... curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs fi # 2. 安装 tmux 3.3a if [[ $(tmux -V 2/dev/null || echo 0) tmux 3.3 ]]; then echo Upgrading tmux to 3.3a... # ... 下载编译安装命令同 3.1 节 fi # 3. 全局安装 OpenRig if ! command -v openrig /dev/null; then echo Installing openrig... npm install -g openrig fi # 4. 初始化 workspace if [[ ! -f openrig.yaml ]]; then echo Initializing openrig workspace... openrig init # 自动填充团队标准配置 sed -i s/port: 8081/port: 8081/g openrig.yaml # ... 其他定制 fi echo ✅ Setup complete. Run openrig start to begin.新成员只需curl -O https://our-gitlab.com/team/setup.sh bash setup.sh5 分钟后就能openrig start运行模型。这个脚本我们托管在内部 GitLab每次 OpenRig 升级更新setup.sh并打 tag所有成员git pull即可同步。5.3 生产就绪用 systemd 管理 OpenRig仅限有 root 权限场景虽然 OpenRig 设计为无守护进程但在生产服务器上我们仍用 systemd 确保开机自启。关键是不直接管理 OpenRig 进程而是管理 tmux session# /etc/systemd/system/openrig.service [Unit] DescriptionOpenRig Model Orchestrator Afternetwork.target [Service] Typeforking Userai-user WorkingDirectory/home/ai-user/openrig-workspace ExecStart/usr/bin/tmux new-session -d -s openrig openrig start --all ExecStop/usr/bin/tmux kill-session -t openrig Restartalways RestartSec10 [Install] WantedBymulti-user.target启用sudo systemctl daemon-reload sudo systemctl enable openrig sudo systemctl start openrig # 验证 sudo systemctl status openrig # 应显示 active (running) tmux ls # 应显示 openrig session关键点ExecStart启动的是 tmux session不是 openrig 命令本身。这样即使 openrig CLI 更新service 也不受影响。ExecStop用tmux kill-session而不是killall openrig确保所有子进程llama-server被干净终止。我个人在实际使用中发现OpenRig 最大的价值不是技术多炫酷而是它把“本地大模型开发”这件事从一门需要记忆无数命令和路径的手艺变成了一套可写文档、可写脚本、可写测试的工程实践。它不承诺“一键解决所有问题”但它把所有问题都暴露在 YAML 和 CLI 的明面上让你能真正掌控每一个字节的流向。如果你还在为多模型切换头疼不妨今晚就试一次openrig init然后亲手敲下第一行openrig start——那之后你就不再是一个调用 API 的用户而是一个调度 AI 的工程师。