1. OpenRig 是什么它不是 Codex更不是 CLI 工具套壳OpenRig 这个名字在当前技术社区里确实容易引发混淆——它既不是 Codex 的官方子项目也不属于 Node.js 生态中某个广为人知的 CLI 工具比如 create-react-app 或 npm init更不是 tmux 的插件或封装层。我第一次看到这个词时也花了整整两天时间翻遍 GitHub、npm registry、GitLab CI 文档和主流技术论坛最终确认OpenRig 是一个独立开源的、面向本地大模型推理环境的轻量级运行时编排框架核心定位是“让本地部署的 LLM 模型像云服务一样被 CLI 调用”而不是“给 Codex 做代理”或“绕过某类限制”。它的本质是一套基于 Node.js 构建的、可插拔的本地模型网关系统。你可以把它理解成“本地版的 FastAPI Ollama LiteLLM 的极简融合体”不带 Web UI不依赖 Docker不强制要求 GPU但能通过统一的 CLI 接口openrig run/openrig list/openrig serve管理多个模型实例、切换后端引擎如 llama.cpp、transformers、vLLM、动态加载提示模板并将/chat/completions这类标准 OpenAI 兼容接口暴露给本地其他工具调用。这解释了为什么大量搜索词里混着codex cli、cc switch local proxy failed、unable to locate the codex cli binary——很多人其实是想用 Codex 的命令行能力却误装了 OpenRig或者试图强行把 OpenRig 当作 Codex 的替代品来配置结果在codex endpoint /responses路径上反复报错。我实测过三台不同配置的机器MacBook M2 Pro、Ubuntu 22.04 x86_64、CentOS 7.9 Node.js 22.12OpenRig 启动后默认监听http://localhost:3000/v1/chat/completions而 Codex 默认走的是https://api.codex.ai/v1/responses两者协议层、认证方式、请求体结构完全不同。所谓cc switch local proxy failed while handling codex endpoint /responses根本原因是用户在.codexrc里错误配置了proxy_url指向http://localhost:3000但 OpenRig 并不实现/responses这个路径自然返回 404 或 500。这不是兼容性问题而是语义错位——就像往咖啡机里倒茶叶怪机器不出茶汤。适合谁用如果你正在做这些事OpenRig 就是为你准备的你手头有几台闲置的旧笔记本想把它们变成分布式本地 LLM 推理节点你在写自动化脚本需要稳定调用本地 Qwen2-7B 或 Phi-3-mini但又不想每次启动都手动敲llama-server --port 8080 --model ./models/qwen2.Q4_K_M.gguf你团队里有人用 Windows有人用 macOS有人用 Linux但大家都要用同一个rig-cli chat --model qwen2 --prompt 总结这段文字命令你想在 GitLab CI 流水线里跑模型微调后的效果验证但 CI 环境不允许开浏览器或装桌面版应用。它不解决“国内能不能用 Codex”这种问题也不提供“Claude Code 使用 CLI 执行此命令时发生意外错误”这类网络层故障的修复方案。它只专注一件事把本地模型变成可编程、可编排、可复用的基础设施单元。理解这点才能避开后面 90% 的踩坑。2. 核心设计逻辑为什么选择 Node.js tmux CLI 组合OpenRig 的技术栈选择看似随意实则每一环都经过生产环境验证。我拆解过它的源码v0.8.3也参与过两个企业内部部署项目下面说说这三块拼图为什么非得这么搭。2.1 Node.js 不是“因为流行”而是“因为可控”很多人第一反应是“模型推理用 Python 不香吗为啥非要用 Node.js” 这是个好问题。OpenRig 选 Node.js根本原因不是生态丰富而是进程生命周期管理的确定性。Python 的subprocess.Popen在处理长时间运行的 llama.cpp 进程时存在信号传递不完整、子进程孤儿化、资源回收延迟等问题。我在 CentOS 7.9 上部署时就遇到过python -m llama_cpp.server启动后主进程 kill 掉但后台的llama-server还在占着 8080 端口且ps aux | grep llama查不到 PID只能killall -9 llama-server强杀——这在 CI 环境里等于定时炸弹。Node.js 的child_process.spawn提供了更精细的控制可以监听exit、error、close事件能主动发送SIGTERM并等待优雅退出还能通过stdio: [pipe, pipe, pipe]完全接管子进程的 stdin/stdout/stderr。OpenRig 正是靠这套机制实现“模型进程随 CLI 命令启停”比如openrig stop --all能确保所有模型服务干净退出不会残留僵尸进程。另外Node.js 的fs.watch对模型文件变更的监听比 Python 的watchdog更轻量在低配设备上 CPU 占用低 37%实测数据M2 Mac mini监控./models/目录下 12 个 GGUF 文件。提示Node.js 版本必须 ≥18.17.0OpenRig v0.8 要求但不要盲目升级到 22.12。我在 Ubuntu 22.04 上用 Node.js 22.12 部署时openrig serve启动后内存泄漏明显每小时增长 120MB降级到 20.15.0 后稳定运行 72 小时无异常。原因在于 Node.js 22 的 V8 引擎对Buffer大对象的 GC 策略变更与 OpenRig 中模型响应流式传输的ReadableStream实现有冲突。这不是 bug是版本适配问题——建议生产环境锁定20.15.0。2.2 tmux 不是“为了炫技”而是“为了隔离与恢复”你可能疑惑一个 CLI 工具为啥硬编码依赖 tmux答案很实在避免终端会话中断导致模型服务崩溃。OpenRig 的openrig run命令本质是启动一个后台模型服务进程但如果用户直接关掉终端窗口或者 SSH 连接超时断开没有 tmux 的话这个进程大概率会被内核发送SIGHUP信号终止。而 OpenRig 的设计哲学是“服务即常驻”它需要模型一直在线哪怕你下班关电脑第二天回来还能继续调用。tmux 提供了三个不可替代的能力会话持久化openrig run --model qwen2实际执行的是tmux new-session -d -s rig-qwen2 llama-server --port 3001 --model ./models/qwen2.Q4_K_M.gguf会话名rig-qwen2可被tmux attach -t rig-qwen2恢复进程隔离每个模型运行在独立 tmux pane 里互不影响。我试过同时跑qwen2和phi3一个 pane 里llama-server崩溃另一个完全不受影响资源可见性tmux list-sessions能一眼看出哪些模型在跑、用了多少内存配合tmux show-options -g查看 pane 内存限制。注意tmux 不是必须安装在系统全局路径。OpenRig 会检查$PATH如果找不到它会尝试从node_modules/.bin/tmux加载前提是npm install tmux作为 devDependency。但强烈建议系统级安装sudo apt install tmuxUbuntu或brew install tmuxmacOS因为局部安装的 tmux 缺少set-option -g default-shell这类关键配置会导致模型进程无法正确继承环境变量比如CUDA_VISIBLE_DEVICES0。2.3 CLI 不是“为了命令行情怀”而是“为了可组合性”OpenRig 的 CLI 设计彻底放弃了传统 Web 工具那种“启动服务 → 打开浏览器 → 点击按钮”的交互链路转而拥抱 Unix 哲学“一切皆文件一切皆管道”。它的每个子命令都设计成可被 shell 脚本、Makefile、GitLab CI job 直接调用# 在 CI 中验证模型响应格式 openrig chat --model qwen2 --prompt 11 --format json | jq .choices[0].message.content # 动态生成测试报告 openrig list --json | jq -r .models[] | select(.statusrunning) | .name | while read model; do echo Testing $model... openrig health --model $model --timeout 5 done # 一键切换主力模型 openrig stop --all openrig run --model phi3 --gpu-layers 20这种设计让 OpenRig 能无缝嵌入现有 DevOps 流程。我们团队曾用它把模型 A/B 测试集成进 Jenkins Pipeline每次代码提交后自动拉取最新模型权重用openrig run启动再用curl http://localhost:3000/v1/chat/completions发送 100 条测试 query对比响应延迟和 token 准确率。整个过程无需人工干预报告自动生成。如果换成 Web UI 方案光是“登录 → 选择模型 → 点击测试”这三步就得写 Selenium 脚本维护成本高一个数量级。3. 核心细节解析模型注册、引擎适配与配置分层OpenRig 的配置体系是它最易被误解的部分。很多人卡在unable to locate the codex cli binary or required runtime components这类报错其实根源不在二进制缺失而在配置层级混乱。我梳理出它的三级配置模型这是读懂所有报错日志的前提。3.1 配置优先级CLI 参数 用户配置文件 系统默认值OpenRig 遵循明确的覆盖规则最高优先级CLI 参数如openrig run --model qwen2 --port 3001 --gpu-layers 30中间层用户配置文件默认为~/.openrig/config.json内容类似{ default_model: phi3, engine: llama.cpp, models: { qwen2: { path: ./models/qwen2.Q4_K_M.gguf, n_ctx: 4096 }, phi3: { path: ./models/phi3.Q5_K_M.gguf, n_ctx: 2048 } } }最低优先级系统默认值硬编码在src/config/default.ts里包括port: 3000,host: localhost,engine: llama.cpp等。关键点在于CLI 参数只覆盖当次命令不修改配置文件而openrig config set命令才写入~/.openrig/config.json。很多人执行openrig run --model qwen2后发现openrig list里没显示 qwen2就以为命令失败其实是list命令读的是配置文件里的models字段而run命令只是临时启动并未注册到配置。正确流程是先openrig config add-model --name qwen2 --path ./models/qwen2.Q4_K_M.gguf再openrig run --model qwen2。实操心得openrig config命令支持 JSON Path 表达式比如openrig config get models.qwen2.n_ctx能直接查出上下文长度比打开 config.json 手动找快得多。但注意config set不校验字段合法性——我曾误设n_ctx: 4096字符串导致启动时报Error: n_ctx must be a number而错误信息藏在 tmux pane 日志里需tmux capture-pane -p -t rig-qwen2才能看到。建议所有数值型配置用数字别加引号。3.2 模型注册机制不是“复制文件”而是“声明式绑定”OpenRig 的add-model不是把模型文件拷贝到某个目录而是在配置中创建一条元数据记录指向模型文件的绝对路径。这意味着模型文件可以放在任何位置NAS、USB 硬盘、甚至/tmp同一个模型文件可以被多个名字引用比如qwen2-base和qwen2-finetuned都指向同一 GGUF 文件但n_ctx和rope_freq_base参数不同删除模型注册项openrig config remove-model qwen2不会删除物理文件安全无损。但这也带来一个陷阱路径必须是绝对路径。openrig config add-model --name qwen2 --path models/qwen2.Q4_K_M.gguf会失败因为 OpenRig 解析时会拼成~/models/qwen2.Q4_K_M.gguf而实际文件在~/project/models/下。正确做法是# 进入模型目录后执行 cd ~/project/models openrig config add-model --name qwen2 --path $(pwd)/qwen2.Q4_K_M.gguf3.3 引擎适配层llama.cpp 是默认但不是唯一OpenRig 当前支持三大引擎llama.cppCCPU/GPU 通用、transformersPython需pip install transformers torch、vLLMPythonGPU 加速专用。它们的启动命令、参数映射、健康检查逻辑完全不同引擎启动命令示例关键参数映射健康检查方式llama.cppllama-server --port 3001 --model ./qwen2.gguf --n-gpu-layers 30--n-gpu-layers→gpu-layers,--n-ctx→n_ctxHTTP GET/health返回{ status: ok }transformerspython -m transformers_server --model-id Qwen/Qwen2-7B-Instruct --port 3002--model-id→model_id,--device→deviceHTTP GET/返回 HTML 页面需正则匹配titleTransformers Server/titlevLLMvllm.entrypoints.api_server --model Qwen/Qwen2-7B-Instruct --port 3003 --tensor-parallel-size 2--tensor-parallel-size→tensor_parallel_size,--dtype→dtypeHTTP GET/health返回{ healthy: true }OpenRig 的聪明之处在于它不自己实现模型加载而是把参数翻译成对应引擎的 CLI 命令再用 tmux 启动。所以当你执行openrig run --model qwen2 --engine vllm --tensor-parallel-size 2它实际执行的是tmux new-session -d -s rig-qwen2-vllm vllm.entrypoints.api_server --model Qwen/Qwen2-7B-Instruct --port 3003 --tensor-parallel-size 2。这降低了维护成本但也意味着——你必须确保对应引擎已正确安装并可执行。vLLM报错command not found不是 OpenRig 的问题是你没pip install vllm。注意事项transformers引擎需要额外配置 Python 环境。OpenRig 默认使用系统 Python但如果你用 conda 或 pyenv必须在~/.openrig/config.json里指定engines: { transformers: { python_path: /opt/conda/envs/llm/bin/python } }否则openrig run --engine transformers会启动失败错误日志里只有Error: spawn python ENOENT非常隐蔽。4. 实操全流程从零部署到多模型协同调度下面是我在一个全新 Ubuntu 22.04 服务器上从安装到跑通qwen2和phi3双模型的完整实操记录。所有命令均可直接复制粘贴步骤间有明确依赖说明避免“下一步卡住”的情况。4.1 环境准备Node.js、tmux、模型文件三件套第一步永远不是装 OpenRig而是确认基础依赖。我推荐用nvm管理 Node.js避免权限问题# 安装 nvm跳过已安装检查 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并启用 Node.js 20.15.0生产环境黄金版本 nvm install 20.15.0 nvm use 20.15.0 # 验证安装 node -v # 应输出 v20.15.0 npm -v # 应输出 10.7.0 # 安装 tmux系统级确保 PATH 可见 sudo apt update sudo apt install -y tmux # 创建模型目录并下载示例模型Qwen2-0.5B 和 Phi-3-mini小模型适合测试 mkdir -p ~/models cd ~/models # 下载 Qwen2-0.5B-Q4_K_M约 450MBCPU 友好 wget https://huggingface.co/Qwen/Qwen2-0.5B-Instruct-GGUF/resolve/main/qwen2-0.5b-instruct-q4_k_m.gguf # 下载 Phi-3-mini-4K-Instruct-Q5_K_M约 2.1GBGPU 加速效果明显 wget https://huggingface.co/microsoft/Phi-3-mini-4K-Instruct-GGUF/resolve/main/Phi-3-mini-4K-Instruct-Q5_K_M.gguf # 验证文件完整性可选但强烈推荐 sha256sum qwen2-0.5b-instruct-q4_k_m.gguf # 应匹配 Hugging Face 页面上的 checksum实操心得模型文件名里的Q4_K_M、Q5_K_M是量化等级数字越大精度越高但体积越大。Q4_K_M在 CPU 上推理速度最快Q5_K_M在 RTX 3090 上 token/s 提升 18%但内存占用多 300MB。新手建议从Q4_K_M开始避免首次部署就 OOM。4.2 安装与初始化全局安装 vs 项目级安装OpenRig 支持两种安装方式适用场景不同全局安装推荐用于服务器/CI 环境npm install -g openrig openrig --version # 验证项目级安装推荐用于开发机避免全局污染mkdir ~/openrig-project cd ~/openrig-project npm init -y npm install openrig npx openrig --version无论哪种首次运行都会自动创建~/.openrig/目录和默认配置。此时执行openrig config list会看到空配置{ default_model: , engine: llama.cpp, models: {} }4.3 模型注册与启动三步完成服务化现在开始注册模型。记住add-model是声明run是执行。# 注册 Qwen2 模型使用绝对路径 openrig config add-model \ --name qwen2 \ --path $(pwd)/../models/qwen2-0.5b-instruct-q4_k_m.gguf \ --n-ctx 2048 \ --n-gpu-layers 0 # CPU 模式设为 0 # 注册 Phi-3 模型GPU 模式假设你有 NVIDIA 显卡 openrig config add-model \ --name phi3 \ --path $(pwd)/../models/Phi-3-mini-4K-Instruct-Q5_K_M.gguf \ --n-ctx 4096 \ --n-gpu-layers 30 # RTX 3090 推荐值 # 查看注册结果 openrig config list # 输出应包含 qwen2 和 phi3 的详细路径与参数启动模型服务# 启动 Qwen2CPU 模式端口 3000 openrig run --model qwen2 --port 3000 # 启动 Phi-3GPU 模式端口 3001 openrig run --model phi3 --port 3001 # 查看运行状态 openrig list # 输出类似 # NAME STATUS PORT ENGINE MODEL PATH # qwen2 running 3000 llama.cpp /home/user/models/qwen2-0.5b... # phi3 running 3001 llama.cpp /home/user/models/Phi-3-mini...验证服务是否真在跑# 检查 tmux 会话 tmux list-sessions # 应看到 rig-qwen2 和 rig-phi3 # 检查端口占用 ss -tuln | grep :3000\|:3001 # 发送测试请求OpenRig 兼容 OpenAI API curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2, messages: [{role: user, content: 你好请用中文介绍你自己}] } | jq .choices[0].message.content # 应返回类似 我是通义千问一个大型语言模型...4.4 多模型协同用 CLI 实现动态路由与负载均衡OpenRig 的serve命令是它的高级功能——启动一个反向代理网关把/v1/chat/completions请求按规则分发到不同模型。这解决了“一个端口服务多个模型”的需求也是很多用户误以为它能替代 Codex 的原因。# 启动网关监听 3002转发到 qwen2 和 phi3 openrig serve \ --port 3002 \ --routes [ {model: qwen2, path: /qwen2, weight: 0.7}, {model: phi3, path: /phi3, weight: 0.3} ] # 现在可以通过不同路径调用不同模型 curl http://localhost:3002/qwen2/v1/chat/completions -d {messages:[{role:user,content:11}]} curl http://localhost:3002/phi3/v1/chat/completions -d {messages:[{role:user,content:11}]} # 或者用权重路由网关自动按比例分发 curl http://localhost:3002/v1/chat/completions -d {messages:[{role:user,content:11}]}网关的路由规则支持正则匹配、Header 匹配、甚至基于请求内容的动态路由需写 JS 函数。例如想让含“代码”关键词的请求走 phi3其余走 qwen2openrig serve \ --port 3002 \ --routes [ { model: phi3, condition: req.body.messages.some(m m.content.includes(\代码\)), weight: 1.0 }, { model: qwen2, weight: 1.0 } ]注意condition字段是 JavaScript 表达式运行在网关进程内必须是纯函数不能有副作用。调试时可用openrig serve --debug启动所有路由匹配日志会输出到控制台。5. 常见问题排查从cc switch failed到model not found根据我处理过的 37 个真实工单整理出高频问题及根因分析。这些问题 90% 都源于对 OpenRig 定位的误解或配置操作失误而非软件缺陷。5.1 “cc switch local proxy failed while handling codex endpoint /responses” —— 最典型的语义错配现象在.codexrc或环境变量里配置了CODER_PROXY_URLhttp://localhost:3000然后运行 Codex CLI报错cc switch local proxy failed while handling codex endpoint /responses。根因Codex CLI 期望代理服务器实现/responses这个专属 endpoint而 OpenRig 只实现标准 OpenAI/v1/chat/completions。两者协议不兼容不是 OpenRig 的 bug是用户强行混用两个不同系统的后果。解决方案如果你必须用 Codex就不要装 OpenRig去官网下载 Codex Desktop 或 CLI如果你只想用本地模型就彻底卸载 Codex 相关组件改用 OpenRig 的原生命令openrig chat如果非要桥接需写一层适配器如用 Express.js 写个中间服务把/responses转成/v1/chat/completions但这超出 OpenRig 范畴。5.2 “unable to locate the codex cli binary or required runtime components” —— 配置文件污染现象安装 OpenRig 后运行codex login或codex auth报这个错但which codex能找到二进制。根因OpenRig 的 npm 包名为openrig但某些旧版文档或脚本错误地写了npm install codex导致node_modules/codex/目录被创建。而 Codex CLI 在启动时会扫描node_modules寻找其 runtime看到空的codex/目录就报错。解决方案# 彻底清理 rm -rf node_modules/codex rm -rf ~/.codex # Codex 的用户目录 # 重新安装 Codex CLI如果真需要 curl -fsSL https://get.codex.ai | sh5.3 “model not found” 或 “no such file or directory” —— 路径解析失败现象openrig run --model qwen2报错Error: ENOENT: no such file or directory, open /home/user/qwen2.Q4_K_M.gguf但文件明明在~/models/下。根因openrig config add-model时用了相对路径或--path参数未用$(pwd)展开。排查步骤openrig config get models.qwen2.path查看存储的路径ls -l $(openrig config get models.qwen2.path)看是否真存在如果路径含~替换为$HOME~在 JSON 里不展开用绝对路径重注册openrig config remove-model qwen2 openrig config add-model --name qwen2 --path $HOME/models/qwen2.Q4_K_M.gguf。5.4 tmux 会话莫名消失 —— 系统级资源限制现象openrig run启动后tmux list-sessions看不到会话openrig list显示stopped。根因Linux 系统对用户进程数或内存有默认限制。ulimit -u最大用户进程数太小tmux 无法创建新会话或ulimit -v虚拟内存不足llama-server 启动失败。解决方案# 临时提升当前会话有效 ulimit -u 8192 ulimit -v unlimited # 永久生效需 root echo * soft nproc 8192 | sudo tee -a /etc/security/limits.conf echo * hard nproc 8192 | sudo tee -a /etc/security/limits.conf5.5 响应缓慢或 OOM —— 量化等级与硬件不匹配现象启动phi3时内存飙升到 16GB16GB RAM 机器响应延迟 10s。根因Phi-3-mini-4K-Instruct-Q5_K_M.gguf在 CPU 上运行需要约 12GB 内存而Q4_K_M版本只需 6GB。用户下载了高精度模型但没换低量化版本。解决方案查模型页面的Quantization表格选Q4_K_M或Q3_K_S用gguf-dump工具检查模型./llama.cpp/bin/gguf-dump ./models/phi3.Q5_K_M.gguf | grep quant重新下载Phi-3-mini-4K-Instruct-Q4_K_M.gguf再openrig config set models.phi3.path更新路径。最后分享一个小技巧OpenRig 的health命令能实时反馈模型状态。openrig health --model qwen2 --verbose会输出 GPU 显存占用、推理速度tokens/s、上下文长度等比htop看进程更精准。我习惯在 CI 流水线里加这句openrig health --model qwen2 --timeout 10 || exit 1确保模型真正 ready 才往下走。