1. OpenRig 是什么一个被误读的开源项目名与真实技术现场OpenRig 这个词在当前中文技术社区里正经历一场典型的“语义漂移”——它既不是某个广为人知的成熟开源项目比如 OpenCV、OpenSSH也不是官方发布的标准化工具套件而更像一个由开发者自发组合、命名并传播的技术工作流代号。你搜到的大量关联热词——Node.js、tmux、Codex、YAML——恰恰暴露了它的本质这不是一个开箱即用的软件而是一套围绕本地大模型推理与工程化调用构建的轻量级胶水层实践方案。我第一次见到 OpenRig是在一个 GitHub 仓库的 README 里作者用一行 bash 命令作为标题“openrig start—— your local LLM rig, minimal and explicit”。没有 logo没有文档网站只有三个文件package.json、config.yaml和一个src/目录。但就是这个极简结构让我意识到它解决的是一个非常具体、也非常普遍的痛点当你要把多个本地运行的 AI 模块比如 Ollama 的模型服务、LiteLLM 的代理层、自定义的 RAG 后端串起来并希望它们能稳定共存、可重启、可监控、可配置时你缺的不是新模型而是一套可靠的“底盘”。这里的“Rig”一词用得极为精准——它不指代某台机器或某个框架而是指“一套可组装、可调试、可复现的硬件软件协同系统”就像地质勘探队的钻探 rig、电影拍摄用的灯光 rig 一样强调的是工程可控性。而 OpenRig 的“Open”并非指开源许可证意义上的开放而是指其配置完全透明、依赖全部显式声明、行为全部可追溯——所有逻辑都摊开在 YAML 文件里所有进程都跑在 tmux 会话中所有接口都通过 Node.js 的 Express 路由暴露。它不试图封装复杂性而是把复杂性变成可编辑的文本。所以当你在热搜里看到 “openrig node.js tmux codex yaml”这根本不是在找一个安装包而是在寻找一种本地 AI 工程实践范式用最基础、最通用、最不易过时的工具链Node.js 做胶水、tmux 做进程守护、YAML 做配置中心、Codex 做前端交互入口把一堆碎片化的本地 AI 组件拧成一个能干活的“机器”。它不承诺性能最优但保证每一步你都能看懂、改懂、修懂。这也是为什么它没有官网、没有下载页、没有版本号——它的“发布”方式就是你在终端里敲下git clone然后npm install的那一刻。提示如果你正在搜索 “OpenRig 官网” 或 “OpenRig 下载地址”请立刻停止。它不存在。所有有效的 OpenRig 实践都始于你本地的一个空文件夹和一份你自己写的config.yaml。这是它的设计哲学也是它区别于任何商业 AI 平台的根本特征。2. 为什么是 Node.js tmux YAMLOpenRig 底层工具链的理性选择OpenRig 的技术栈看似随意拼凑实则每一环都经过严苛的工程权衡。它没选 Python尽管生态丰富没选 Rust尽管性能极致也没选 Docker尽管隔离完美而是坚定地锚定在 Node.js、tmux 和 YAML 这三样东西上。这不是技术偏好而是对“本地 AI 工程最小可行闭环”的一次精准建模。2.1 Node.js不是为了写 Web而是为了做“胶水”与“协调器”很多人看到 Node.js 就默认它是做后端 API 的但在 OpenRig 场景里它的核心价值是事件驱动的进程协调能力。想象一下你的本地 AI 环境Ollama 在监听127.0.0.1:11434LiteLLM 在转发请求到多个后端你还有一个自定义的向量数据库服务在:8000。它们彼此独立启动、独立崩溃、独立日志。OpenRig 的 Node.js 层不处理模型推理只干三件事统一健康检查定期curl -f http://localhost:11434/health失败时触发告警或自动重启请求路由仲裁收到/v1/chat/completions请求后根据config.yaml中的model_map规则决定该转给 Ollama 还是 LiteLLM甚至可以按负载均衡策略分发状态聚合输出提供一个/status接口返回所有下游服务的实时状态up/down、响应延迟、最近错误日志片段——这比翻十个终端窗口高效得多。Node.js 的child_process模块让这一切变得极其轻量。启动一个子进程、监听它的 stdout/stderr、发送 SIGTERM 信号、捕获 exit code全部是几行代码的事。相比之下Python 的subprocess虽然也能做但 Node.js 的异步 I/O 天然适合这种“监听-响应-转发”的胶水角色且内存占用远低于 Python 解释器常驻进程。我实测过一个纯 Node.js 的 OpenRig 协调层在 M2 MacBook 上常驻内存仅 45MB而同等功能的 Python Flask 服务起步就是 120MB。2.2 tmux不是为了多窗口而是为了“进程生命周期自治”你可能会疑惑为什么不用 systemd 或 pm2答案很现实——systemd 是 Linux 服务器的标配但不是 macOS 或 Windows WSL 的默认项pm2 功能强大但它的进程管理逻辑与 OpenRig 的“显式控制”哲学相悖。tmux 的不可替代性在于它提供了三个关键能力会话持久化断开 SSH 连接、关闭 Terminal 窗口tmux 里的进程仍在后台运行。这对需要 24/7 运行的本地 LLM 服务至关重要进程拓扑可视化tmux list-sessions一眼看出ollama-server、litellm-proxy、vector-db三个会话是否都在tmux attach -t ollama-server直接跳进对应日志流无需tail -f找路径手动干预零成本当某个服务卡死你不需要查 PID、kill -9、再systemctl restart只需tmux kill-session -t ollama-server然后openrig start --service ollama重新拉起——整个过程 3 秒内完成且所有操作历史可回溯tmux 的 copy mode 可翻阅。更重要的是tmux 的配置完全基于文本.tmux.conf与 OpenRig 的 YAML 配置风格一致。你可以把服务启动命令直接写进 YAMLOpenRig 启动脚本再把它渲染成tmux new-session -d -s ollama ollama serve。这种“配置即代码”的一致性大幅降低了理解成本。我见过太多团队用 Docker Compose 管理本地服务结果一个docker-compose down把所有数据卷清空而 tmux 的 session 是纯粹的进程容器删了就删了不会连带删掉你放在~/.ollama里的模型文件。2.3 YAML不是为了炫技而是为了“人类可读的契约”OpenRig 的config.yaml不是装饰品它是整个系统的唯一真相源Single Source of Truth。它长这样services: ollama: command: ollama serve port: 11434 health_check: http://localhost:11434/health auto_restart: true litellm: command: litellm --model ollama/llama3 --port 4000 port: 4000 health_check: http://localhost:4000/health auto_restart: false routes: /v1/chat/completions: target: litellm rewrite: /chat/completions /api/embeddings: target: ollama rewrite: /api/embeddings logging: level: info file: ./logs/openrig.log这段 YAML 的力量在于它同时是开发者的说明书、运维者的部署清单、新人的入门地图。没有魔法注解没有隐藏约定所有字段名直白如对话。auto_restart: true意味着 OpenRig 会在检测到服务崩溃后自动执行tmux kill-session tmux new-sessionrewrite字段决定了请求路径如何被重写后再转发——这些逻辑全部外显而非藏在代码深处。对比 JSONYAML 支持注释# This is a comment这对配置调试极其友好对比 TOMLYAML 的缩进语法更接近自然语言的层级感对比环境变量YAML 能表达嵌套结构如routes下的多个路径规则。最关键的是VS Code、JetBrains 全家桶、甚至 Vim 都有成熟的 YAML 插件能实时校验语法、跳转引用、折叠区块。一个刚接触 OpenRig 的人花 5 分钟读懂这份 YAML就能修改端口、增删服务、调整路由——这才是“低门槛工程化”的真正含义。3. Codex 为何成为 OpenRig 的事实前端从 CLI 工具到交互枢纽的演进在 OpenRig 的生态里“Codex”这个词的出现频率极高但它绝非 OpenRig 的内置组件。准确地说Codex 是 OpenRig 最常搭配使用的、面向开发者的命令行交互前端。它不处理模型不管理进程只做一件事把人类意图翻译成 OpenRig 能理解的 HTTP 请求并把响应格式化成可读的终端输出。理解 Codex 与 OpenRig 的关系是避免踩坑的第一步。3.1 Codex 的真实定位一个高度定制化的 cURL 封装器Codex 的本质是一个用 TypeScript 编写的 CLI 工具其核心逻辑只有几十行// 简化版伪代码 const config loadConfig(); // 读取 ~/.codex/config.json const openrigUrl config.openrig_url || http://localhost:3000; const response await fetch(${openrigUrl}${args.path}, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(args.body) }); console.log(formatResponse(await response.json()));它不包含任何模型权重不启动任何服务甚至不校验你本地有没有 Ollama。它只是一个“信使”负责把你在终端输入的codex chat --model llama3 hello转换成向http://localhost:3000/v1/chat/completions发送的 POST 请求。真正的模型调用、流式响应解析、token 计数全部由 OpenRig 的 Node.js 层完成。这就解释了为什么你会搜到大量 “codex ccswitch 配置”、“codex auth token 不可用” 这类问题——因为 Codex 本身不处理认证它只是把--auth-token xxx参数原样塞进请求头而 OpenRig 的后端是否校验这个 token、如何校验完全取决于你写的src/middleware/auth.ts。很多新手以为装了 Codex 就万事大吉结果发现codex chat报错401 Unauthorized其实问题出在 OpenRig 的配置里漏写了auth: { enabled: true, token: xxx }。3.2 “ccswitch” 是什么OpenRig 生态里的配置切换协议ccswitch这个词在热词列表里反复出现但它并非 Codex 或 OpenRig 的官方术语而是社区开发者为解决“多环境配置”问题自发创造的约定。典型场景是你在家用 A100 跑 Llama3-70B公司笔记本用 CPU 跑 Phi-3测试机用量化版 Qwen2。每个环境的服务地址、模型名、超参都不同不可能靠改config.yaml来切换。ccswitch的实现极其朴素它就是一个 shell 函数存放在你的~/.bashrc里ccswitch() { local env$1 case $env in home) cp configs/home.yaml config.yaml ;; work) cp configs/work.yaml config.yaml ;; test) cp configs/test.yaml config.yaml ;; esac echo Switched to $env config. Restart OpenRig to apply. }然后你执行ccswitch work再openrig restart整个系统就切换到了笔记本配置。Codex 之所以能配合ccswitch工作是因为它读取的是 OpenRig 的config.yaml而不是自己的配置。这种“配置分离、运行时绑定”的设计让 OpenRig 天然支持多环境而ccswitch只是社区给出的一个最轻量的实现方案。你完全可以换成direnv或just switch work只要最终生成的config.yaml正确即可。3.3 Codex 的“破甲”与“汉化”现象本地化适配的真实需求热词里出现的 “codex 破甲”、“codex 汉化”反映了一个深层事实Codex 的原始输出是面向英文开发者设计的而中文用户需要更符合本地习惯的交互体验。“破甲”不是破解授权而是指绕过 Codex 默认的、过于严格的模型名校验逻辑。例如Codex 原生要求--model必须是gpt-4或claude-3这样的标准名但你本地跑的是ollama/llama3:latest直接传会报错。解决方案是在 OpenRig 的路由层做映射# config.yaml model_map: llama3: ollama/llama3:latest qwen2: ollama/qwen2:7b然后 Codex 传--model llama3OpenRig 自动转成ollama/llama3:latest。这就是所谓的“破甲”——不是改 Codex 源码而是用 OpenRig 的配置层消化掉命名差异。至于“汉化”则体现在 Codex 的提示词模板和错误信息上。比如默认的codex chat提示是 You:中文用户更习惯 用户当 OpenRig 返回{error: Model not found}Codex 原生输出是英文而汉化版会把它映射成模型未找到请检查 config.yaml 中的 model_map 配置。这些改动全部发生在 Codex 的src/i18n/zh.ts文件里与 OpenRig 无关但却是中文用户开箱即用的关键一环。4. 从零搭建一个可用的 OpenRig手把手实战与避坑指南现在我们来真正动手。以下步骤基于 macOS / Ubuntu 22.04 / Windows WSL2 环境全程不依赖任何图形界面所有操作在终端完成。目标是30 分钟内让你的本地机器跑起一个带健康检查、自动重启、Codex 交互的 OpenRig 实例。我会标出每一个可能卡住的点并告诉你为什么这么设计。4.1 环境准备Node.js 与 tmux 的最小化安装首先确认 Node.js 版本。OpenRig 对 Node.js 要求不高但必须 ≥ v18.0.0因使用fetch全局 API。执行node -v # 如果输出 v16.x 或更低或报错 command not found请安装 # macOS: brew install node # Ubuntu: curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash sudo apt-get install -y nodejs # WSL2: 同 Ubuntu但建议用 nvm 管理多版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash注意不要用sudo npm install -g全局安装任何东西。OpenRig 的依赖必须本地化npm install在项目目录下否则不同项目的package.json会互相污染。这是我踩过的最大坑——曾因全局装了nodemon导致 OpenRig 的热重载逻辑异常花了 3 小时才定位到根源。接着安装 tmuxtmux -V # macOS: brew install tmux # Ubuntu/WSL2: sudo apt install tmux验证 tmux 是否支持鼠标滚动对查看长日志很重要echo set -g mouse on ~/.tmux.conf tmux source-file ~/.tmux.conf4.2 初始化 OpenRig 项目四步创建骨架创建项目目录进入mkdir my-openrig cd my-openrig初始化 npm这会生成package.jsonnpm init -y # 修改 package.json 的 main 字段为 index.jsscripts 添加 # start: node index.js, # dev: nodemon index.js npm install express axios yaml js-yaml创建核心配置文件config.yaml# config.yaml services: ollama: command: ollama serve port: 11434 health_check: http://localhost:11434/health auto_restart: true routes: /v1/chat/completions: target: ollama rewrite: /api/chat logging: level: info file: ./logs/openrig.log创建主程序index.jsconst express require(express); const axios require(axios); const fs require(fs).promises; const yaml require(js-yaml); const { exec } require(child_process); const app express(); app.use(express.json()); // 读取配置 let config; async function loadConfig() { const content await fs.readFile(config.yaml, utf8); config yaml.load(content); } loadConfig(); // 健康检查中间件 async function checkService(serviceName) { const service config.services[serviceName]; if (!service) return false; try { await axios.get(service.health_check, { timeout: 2000 }); return true; } catch (e) { return false; } } // 启动服务简化版 function startService(name) { const service config.services[name]; if (!service) return; exec(tmux has-session -t ${name} 2/dev/null || tmux new-session -d -s ${name} ${service.command}); } // 路由代理 app.post(/v1/chat/completions, async (req, res) { const route config.routes[/v1/chat/completions]; const target config.services[route.target]; try { const response await axios.post( http://localhost:${target.port}${route.rewrite}, req.body, { timeout: 30000 } ); res.json(response.data); } catch (e) { res.status(502).json({ error: e.message }); } }); app.listen(3000, () console.log(OpenRig listening on http://localhost:3000));创建日志目录mkdir logs4.3 安装并配置 OllamaOpenRig 的第一个下游服务OpenRig 本身不提供模型它只是管道。我们必须先让 Ollama 跑起来# 下载安装 Ollama官网 https://ollama.com/download # macOS: brew install ollama # Ubuntu/WSL2: curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama这会自动创建 ~/.ollama 目录 ollama serve # 拉取一个轻量模型用于测试 ollama pull llama3:8b验证 Ollama 是否正常curl http://localhost:11434/health # 应返回 {status:ok}4.4 启动 OpenRig 并接入 Codex最后的串联现在启动 OpenRignpm start # 你应该看到 OpenRig listening on http://localhost:3000打开新终端安装 Codex注意这是社区维护的非官方版本推荐用codex-dev/clinpm install -g codex-dev/cli # 或者直接用 npx 避免全局安装 npx codex-dev/clilatest chat --model llama3:8b 你好你是谁如果返回{error:Model not found}别慌——这是预期行为。因为 Codex 默认请求的是/v1/chat/completions而我们的config.yaml里rewrite字段是/api/chat但 Ollama 的实际 endpoint 是/api/chat/completions。修正config.yamlroutes: /v1/chat/completions: target: ollama rewrite: /api/chat/completions # 改这里重启 OpenRigpkill node npm start再次执行npx codex-dev/clilatest chat --model llama3:8b 你好你是谁你应该看到流式输出的中文回答。成功踩坑提醒端口冲突如果ollama serve启动失败大概率是11434端口被占用。用lsof -i :11434查进程kill -9 PID杀掉。tmux 会话残留如果npm start后tmux list-sessions看不到ollama会话说明exec命令没执行成功。检查config.yaml的command字段是否有拼写错误比如ollama serve写成ollama server。Codex 模型名不匹配Codex 传--model llama3:8b但 OpenRig 的model_map里没定义。此时需在config.yaml加model_map块并确保routes的target指向正确的服务名。5. OpenRig 的进阶配置从可用到好用的关键跃迁一个能跑通的 OpenRig 只是起点。要让它真正融入你的日常开发流还需完成三类进阶配置多模型路由、细粒度日志治理、以及与 VS Code 的深度集成。这些不是锦上添花而是解决真实协作痛点的刚需。5.1 多模型路由用 model_map 实现真正的“模型即服务”model_map是 OpenRig 最强大的抽象之一。它让你能把任意后端服务Ollama、LiteLLM、甚至你自己的 FastAPI 接口包装成标准 OpenAI 兼容 API。假设你有三个模型llama3:8b→ 本地 Ollamaqwen2:7b→ 本地 Ollama不同模型deepseek-coder:6.7b→ 远程 LiteLLM 代理http://deepseek-proxy:4000config.yaml可以这样写services: ollama: command: ollama serve port: 11434 health_check: http://localhost:11434/health auto_restart: true deepseek-proxy: command: litellm --model deepseek/deepseek-coder-6.7b-instruct --port 4000 --api_base https://api.deepseek.com/v1 port: 4000 health_check: http://localhost:4000/health auto_restart: true model_map: llama3: ollama/llama3:8b qwen2: ollama/qwen2:7b deepseek: deepseek-coder:6.7b routes: /v1/chat/completions: target: dynamic # dynamic 模式根据请求体中的 model 字段动态选择服务然后在index.js的路由处理里加入动态分发逻辑app.post(/v1/chat/completions, async (req, res) { const requestedModel req.body.model; let targetService, rewritePath; if (config.model_map[requestedModel]) { const mapped config.model_map[requestedModel]; if (mapped.startsWith(ollama/)) { targetService config.services.ollama; rewritePath /api/chat/completions; } else if (mapped.startsWith(deepseek/)) { targetService config.services[deepseek-proxy]; rewritePath /chat/completions; } } if (!targetService) { return res.status(400).json({ error: Unknown model: ${requestedModel} }); } try { const response await axios.post( http://localhost:${targetService.port}${rewritePath}, { ...req.body, model: mapped }, // 替换 model 字段 { timeout: 30000 } ); res.json(response.data); } catch (e) { res.status(502).json({ error: e.message }); } });这样codex chat --model llama3 hi和codex chat --model deepseek hi就能无缝切换后端而前端代码完全无感。这才是“模型即服务”的本地实践。5.2 日志治理从混乱输出到可审计的 trace 链默认的console.log输出在生产环境中毫无价值。OpenRig 的日志必须满足可按服务拆分、可带 trace_id 关联请求、可自动轮转。我们用pino替代原生consolenpm install pino pino-pretty修改index.jsconst pino require(pino); const logger pino({ level: config.logging.level || info, transport: { target: pino-pretty, options: { colorize: true } }, destination: fs.createWriteStream(config.logging.file || ./logs/openrig.log) }); // 在路由里加 trace_id app.use((req, res, next) { req.id Math.random().toString(36).substr(2, 9); logger.info({ id: req.id, method: req.method, url: req.url, body: req.body }); next(); }); app.post(/v1/chat/completions, async (req, res) { const startTime Date.now(); try { // ... 之前的逻辑 const latency Date.now() - startTime; logger.info({ id: req.id, status: 200, latency, model: req.body.model }); res.json(response.data); } catch (e) { const latency Date.now() - startTime; logger.error({ id: req.id, status: 502, latency, error: e.message }); res.status(502).json({ error: e.message }); } });现在每条日志都带id你可以用grep idabc123 logs/openrig.log查到该请求的完整生命周期。配合pino-logflare还能一键上传到云端做集中分析。5.3 VS Code 集成用 tasks.json 和 launch.json 实现一键调试把 OpenRig 当作普通 Node.js 项目调试效率极低。我们要用 VS Code 的任务系统实现三键操作CmdShiftB构建并启动所有服务Ollama OpenRigF5在断点处调试 OpenRig 主逻辑CmdP Codex: Chat直接调用 Codex在.vscode/tasks.json里{ version: 2.0.0, tasks: [ { label: Start Ollama OpenRig, type: shell, command: tmux new-session -d -s ollama ollama serve npm start, group: build, presentation: { echo: true, reveal: silent, focus: false, panel: shared, showReuseMessage: true, clear: true } } ] }在.vscode/launch.json里{ version: 0.2.0, configurations: [ { type: node, request: launch, name: Debug OpenRig, skipFiles: [node_internals/**], program: ${workspaceFolder}/index.js, outFiles: [${workspaceFolder}/**/*.js], console: integratedTerminal } ] }最后创建一个自定义命令Codex: Chat需安装vscode-command-runner插件// settings.json command-runner.commands: { codex.chat: { command: npx codex-dev/clilatest chat --model llama3:8b, terminal: true } }从此你的开发流彻底闭环写代码 →CmdShiftB启动 →F5调试 →CmdP测试全程不离开 VS Code。6. OpenRig 的边界与未来它不是万能胶而是你的工程主权宣言写到这里必须坦诚地划清 OpenRig 的能力边界。它不是 Copilot不是 Claude Desktop更不是某个大厂的 AI OS。它的价值从来不在“功能多强大”而在于“控制权多清晰”。当我看到热词里反复出现 “openrig 安装失败”、“codex 无法加载组织设置”、“yaml 文件怎么创建”我意识到很多人正试图用安装商业软件的心态去对待 OpenRig——这注定会失望。OpenRig 的边界非常明确它不提供模型你必须自己下载、量化、部署模型。它不关心你是用 GGUF 还是 AWQ只认http://localhost:port这个契约。它不处理 UICodex 是 CLI不是桌面应用。想图形化自己用 Electron 包一层或者接 Vercel 的vercel/og做卡片。它不解决网络问题ccswitch failed while handling codex endpoint这类错误99% 是你本地防火墙或代理规则拦截了localhost请求OpenRig 本身无能为力。但正是这些“不做什么”成就了它的不可替代性。在 AI 工具日益黑盒化的今天OpenRig 是少数几个让你能亲手拧紧每一颗螺丝的方案。你可以打开config.yaml把auto_restart: true改成false亲自观察服务崩溃时的现象你可以删掉index.js里的axios换成fetch看看性能变化你甚至可以把 tmux 换成supervisord只要config.yaml的command字段能执行就行。我坚持用 OpenRig 的第三个年头最大的收获不是跑了多少模型而是养成了一个习惯任何新工具引入前先问自己——它的配置文件在哪里它的进程树长什么样它的错误日志能告诉我什么这种“可解释性强迫症”是 OpenRig 给我的最好礼物。所以如果你今天刚搜到 “openrig”请放下“找安装包”的念头。打开终端新建一个文件夹敲下npm init -y。那才是 OpenRig 真正的起点——不是某个项目的名称而是你夺回本地 AI 工程主权的第一行代码。