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的 pane，cd 到模型目录，执行./server -m ./models/qwen2-7b.Q4_K_M.gguf -ngl 40 --port 8081，然后把 stdout/stderr 重定向到日志文件，并监听该 pane 的退出状态。

为什么需要 OpenRig？因为现实中的本地大模型开发，早已过了“跑通一个模型就万事大吉”的阶段。你现在可能同时调试 Qwen2-7B（CPU 推理）、Phi-3-mini（GPU 低显存模式）、Llama-3-8B-Instruct（GPU 全量加载），还要给它们分配不同端口、限制显存占用、设置超时熔断、记录 token 吞吐量。手动维护十几个 tmux session、一堆 nohup 日志、互相冲突的环境变量，三天就能耗尽耐心。OpenRig 就是为此而生的——它不替代模型本身，而是成为你和模型之间的“调度员”，一个命令就能启停、切换、监控、扩容。它适合谁？不是初学者，而是已经能独立部署 ollama 或 llama.cpp、正在搭建本地 AI 工作流、被多模型协同问题卡住的中高级开发者。如果你还在查“node.js 是干什么的”，请先完成 Node.js 基础安装；但如果你已经写过 shell 脚本管理模型服务，OpenRig 就是你下一步该摸的工具。

2. 核心设计逻辑：为什么选 Node.js + tmux + YAML，而不是 Python 或 Rust？

OpenRig 的技术栈选择，表面看是 Node.js + tmux + YAML，实则每一层都对应着一个明确的工程约束。这不是“因为作者会 JS 就选 JS”，而是经过至少三轮原型迭代后，在可维护性、跨平台兼容性、进程控制精度和学习成本之间找到的平衡点。

2.1 Node.js：不是因为“前端流行”，而是因为它对子进程的掌控力最稳

很多人看到 Node.js 就默认它是 Web 开发专属，但 OpenRig 用的恰恰是 Node.js 最被低估的能力：child_process 模块的精细控制。相比 Python 的 subprocess，Node.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 或 WSL2，systemd 支持不完整。tmux 成为唯一解，因为它满足三个硬性条件：
第一，会话与用户登录会话解耦。你 ssh 登录后openrig start，然后ctrl+b d断开连接，tmux session 仍在后台运行；下次 ssh 进来tmux attach就能无缝续上，日志流、CPU/GPU 占用状态全部保留。
第二，pane 级别的独立生命周期管理。每个模型实例独占一个 tmux pane，openrig stop --model qwen2-7b实际执行的是tmux kill-pane -t qwen2-7b，不会影响其他 pane。这比 screen 的窗口管理更精准，也比 nohup + pidfile 更可靠（nohup 进程一旦被 kill -9，pidfile 就成僵尸）。
第三，跨平台一致性高。macOS 自带 tmux（brew install tmux 即可），CentOS 7.9yum install tmux，Ubuntuapt install tmux，WSL2 同样适用。而像 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。不要用系统自带的node（CentOS 7.9 默认是 v6.17，Ubuntu 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是一个最小可行配置，但必须手动修改三处关键字段才能启动：

1. models[0].path：改为你的模型文件绝对路径，例如/home/user/openrig-workspace/models/qwen2-7b.Q4_K_M.gguf。注意：OpenRig 不接受相对路径，./models/xxx会报错。
2. models[0].backend：确认你模型对应的 backend。llama.cpp 模型填"llama.cpp"，Ollama 模型填"ollama"，vLLM 填"vllm"。填错会导致启动时找不到可执行文件。
3. 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_64（CUDA 支持） 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 ARM64（M系列芯片） # 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-7B：

cd ~/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 的启动日志 # 按 ctrl+b 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 里应有两个 pane：qwen2-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": "1+1=?"}]}'

实操心得：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 和一行修复命令。

独家避坑技巧：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..." # 模型文件的 sha256，CI 流程会校验 backend: "llama.cpp" # ... 其他参数

模型文件太大，不用直接 commit，而是用 git submodule：

git 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.sh，5 分钟后就能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] Description=OpenRig Model Orchestrator After=network.target [Service] Type=forking User=ai-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 Restart=always RestartSec=10 [Install] WantedBy=multi-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 的工程师。