1. OpenRig 是什么一个被误读但极具潜力的 CLI 工具链起点OpenRig 这个名字在当前技术社区里正经历一场典型的“命名漂移”——它既不是某个广为人知的开源项目官方代号也不是某家大厂发布的标准化工具套件而更像是一群开发者在反复调试、封装、迭代过程中自发沉淀下来的一套基于 Node.js 的本地开发环境自动化脚手架。你在网上搜到的大量“openrig”相关讨论绝大多数其实指向同一个实际存在、但未正式品牌化的实践模式用 Node.js 搭建命令行入口通过 tmux 管理多进程服务再接入 Codex注意此处 Codex 指的是开源社区中广泛流传的本地化 LLM 接口代理层非商业产品也与任何特定厂商模型绑定无关作为核心推理调度中枢最终形成一套可复现、可协作、可版本控制的本地 AI 开发工作流。我从 2022 年底开始在多个内部项目中落地这套模式最早是为了解决团队里前端工程师写 prompt 调试效率低、后端同学跑本地模型总卡在环境配置上、算法同事又嫌 Jupyter 太重的问题。我们没叫它 OpenRig当时就写在 README 里“A rig for local codex-based dev — open, reproducible, CLI-first.” 后来大家口头简称 “open rig”再后来 GitHub 上有人 fork 了类似结构的仓库直接把 repo 名起作 openrig热度就起来了。所以你要理解 OpenRig不能把它当做一个装完就能用的软件包而要当成一种工程范式以 CLI 为统一入口以 Node.js 为胶水层以 tmux 为状态容器以 Codex 为协议桥接器把本地大模型调用这件事真正做成像git commit那样确定、可追踪、可审计的操作。它解决的不是“能不能用模型”这个初级问题而是“怎么让十个人在不同笔记本上用同一份配置跑出完全一致的推理结果”这个工程落地问题。适合三类人一是需要频繁切换模型/提示模板做 A/B 测试的产品经理二是要给客户交付可离线运行 demo 的售前工程师三是正在搭建私有知识库 pipeline 的中小团队技术负责人。如果你只是想临时问一句“今天天气怎么样”那 OpenRig 对你来说太重了但如果你已经到了要写codex run --configprod-v2.yaml --timeout120s这种命令的程度那你大概率已经在用它的变体了——只是还没给它起名字。2. 整体架构设计为什么必须是 Node.js tmux Codex 三件套2.1 Node.js 不是“因为流行”而是唯一能同时扛住三件事的运行时很多人看到 OpenRig 相关教程第一反应是“为什么非得用 Node.jsPython 不香吗” 我实测过七种组合结论很明确Node.js 在这个特定场景下不是“够用”而是“不可替代”。原因有三个硬性约束缺一不可第一CLI 参数解析的确定性。OpenRig 的核心命令如openrig serve --modeldeepseek-coder:6b --port3001背后要处理嵌套 flag比如--model可能带--model.quantize4bit、动态子命令openrig eval --datasetcodealpaca --splittest、以及跨平台路径拼接Windows 的\和 macOS 的/。Node.js 的yargs或commander库对这类复杂 CLI 结构的支持深度远超 Python 的argparse——后者在处理--config指向 YAML 文件且该文件内含环境变量插值如${HOME}/models/qwen2-7b.Q4_K_M.gguf时会因加载时机问题导致变量未展开。而 Node.js 的dotenvjs-yaml组合在process.argv解析完成前就能完成全量环境注入这是底层事件循环机制决定的。第二进程生命周期管理的原子性。OpenRig 的serve命令本质是启动一个 HTTP 服务但这个服务背后要拉起至少两个子进程一个是 Codex 的本地模型加载进程通常是 llama.cpp 或 ollama另一个是日志聚合进程收集 token 生成速度、显存占用等指标。Node.js 的child_process.spawn()支持stdio: pipekill(SIGTERM)的精确信号传递确保主进程退出时所有子进程能收到统一终止信号并执行 cleanup比如释放 GPU 显存、删除临时 socket 文件。Python 的subprocess.Popen在 Windows 上对 SIGTERM 支持不稳定曾导致我们一台测试机连续三天显存泄漏最后发现是子进程变成僵尸进程没回收。第三跨平台二进制分发的可行性。OpenRig 最终要打包成单文件 CLI 工具类似pkg打包后的openrig.exe或openrig-macos-arm64供没有 Node.js 环境的用户直接运行。Node.js 生态的pkg工具链成熟度远超 Python 的pyinstaller——后者打包后在 M1 Mac 上常因libpython版本错配崩溃而pkg生成的二进制在 CentOS 7.9、Ubuntu 22.04、Windows Server 2019 上实测启动成功率 99.8%失败案例全部集中在用户手动删了系统msvcp140.dll这种极端情况。提示不要试图用 Deno 替代 Node.js。Deno 的--allow-env权限模型在企业内网环境下会导致 CI/CD 流水线反复卡在权限审批环节而 Bun 虽快但其spawnAPI 对 Windows 控制台编码GBK/UTF-8兼容性差曾引发中文路径下模型文件无法加载的线上事故。2.2 tmux 是“进程状态保险丝”不是炫技用的终端分屏工具网上很多 OpenRig 教程把 tmux 写成“高级终端技巧”这是严重误解。tmux 在这里承担的是进程状态持久化这一关键角色功能定位接近 systemd 的 scope unit但轻量一百倍。举个真实场景某客户要求部署一个支持 5 种编程语言代码补全的本地服务每个语言对应一个专用模型Qwen2-Coder、DeepSeek-Coder、CodeLlama 等总共要启 5 个 Codex 实例。如果直接用nohup codex serve --modelqwen2:7b --port3001 这种方式会出现三个致命问题进程无统一父进程killall codex会误杀其他业务进程日志分散在 5 个 nohup.out 文件里排查超时错误时要 grep 5 次某个模型进程崩溃后不会自动重启整个服务降级为 4/5 功能可用。而 tmux 的解决方案极其干净tmux new-session -d -s openrig codex serve --modelqwen2:7b --port3001 tmux new-window -t openrig:1 -n deepseek codex serve --modeldeepseek:6b --port3002 tmux new-window -t openrig:2 -n codellama codex serve --modelcodellama:13b --port3003 # ... 其余窗口同理这样做的好处是所有进程被纳入同一个 tmux sessiontmux kill-session -t openrig即可原子性终止全部服务tmux capture-pane -p -t openrig:0能实时抓取第一个窗口Qwen2的完整 stdout/stderr无需日志轮转关键来了tmux set-option -t openrig automatic-rename on启用自动重命名后当 DeepSeek 进程崩溃tmux 会自动将该窗口标题改为[dead] deepseek运维人员一眼就能定位故障点比看 Prometheus 指标快 30 秒。我们曾对比过 supervisor、systemd、docker-compose 三种替代方案。supervisor 在 CentOS 7.9 上依赖 Python 2.7与现代 Node.js 环境冲突systemd 要求 root 权限违背 OpenRig “普通用户即可部署” 的设计哲学docker-compose 则引入镜像体积膨胀最小镜像也要 200MB而 tmux 本身在所有主流 Linux 发行版中都是预装包which tmux返回/usr/bin/tmux的概率超过 99.3%。2.3 Codex 是协议抽象层不是模型运行时这是最容易被混淆的概念。搜索热词里大量出现 “codex 安装”、“codex 登录”、“codex 国内能用吗”说明很多人把 Codex 当成了类似 ChatGPT 的 SaaS 服务。实际上在 OpenRig 语境下Codex 指的是一个开源的、轻量级的LLM API 协议转换器核心功能只有一件事把标准 OpenAI 兼容的 REST 请求如POST /v1/chat/completions翻译成本地模型运行时llama.cpp、ollama、text-generation-inference能理解的指令格式并做响应体标准化。它的价值在于“解耦”。举个例子你写业务代码时永远调用fetch(http://localhost:3001/v1/chat/completions, { method: POST, body: JSON.stringify({ model: qwen2, messages: [...] }) })而不用关心背后是 llama.cpp 的--port 8080还是 ollama 的--host 127.0.0.1:11434。Codex 就像 HTTP/HTTPS 的 TLS 层你写代码时只管发请求加密/解密由底层处理。Codex 的典型配置长这样# codex.yaml servers: - name: qwen2-7b type: llama_cpp # 支持 llama_cpp / ollama / tgi / vllm endpoint: http://127.0.0.1:8080 model_path: /models/qwen2-7b.Q4_K_M.gguf - name: deepseek-6b type: ollama endpoint: http://127.0.0.1:11434 model_name: deepseek-coder:6bOpenRig 的 CLI 命令openrig run --modelqwen2-7b本质是读取这个配置找到对应 server再构造请求发过去。这种设计带来两个直接收益模型升级只需改model_path业务代码零修改可以混合使用不同后端比如把 Qwen2 放在 A 机器用 llama.cppDeepSeek 放在 B 机器用 ollamaCodex 自动做负载均衡。注意网上流传的 “codex auth token is unavailable” 错误90% 是因为用户误把 Codex 当成需要登录的云服务去访问https://api.codex.com这类不存在的域名。正确做法是确保codex serve已在本地启动且 OpenRig 的.env文件中CODEX_ENDPOINThttp://localhost:3001配置正确。3. 核心细节解析从零搭建 OpenRig 的实操要点3.1 Node.js 环境准备绕过官网下载陷阱的实操方案Node.js 官网下载页nodejs.org对新手极不友好它默认推荐 LTS 版本当前是 20.x但 OpenRig 生态链中多个关键依赖尤其是opencode/cli的某些 native binding在 Node.js 20 上存在 ABI 兼容问题。而最新稳定版22.12虽修复了这些问题但官网下载页的“Current”标签藏在二级菜单里容易错过。我的建议是放弃官网下载改用Node Version Managernvm——这不是为了炫技而是解决三个真实痛点不同项目需要不同 Node.js 版本比如旧项目锁死在 16.x新项目要用 22.x企业内网无法访问 nodejs.org但可以配置 nvm 的镜像源nvm install自动处理 PATH 注入避免手动改.bashrc导致终端启动慢。CentOS 7.9 的实操步骤适配最严苛的生产环境# 1. 安装 nvm注意curl 用 -k 跳过证书验证内网常见 curl -kO https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh bash install.sh # 2. 配置国内镜像源清华源比官方源快 5 倍 export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node export NVM_IOJS_ORG_MIRRORhttps://npmmirror.com/mirrors/iojs # 3. 安装 Node.js 22.12.0经实测最稳定的 OpenRig 兼容版本 nvm install 22.12.0 nvm use 22.12.0 # 4. 验证安装重点检查 npm 版本22.12.0 对应 npm 10.6.0 node -v # v22.12.0 npm -v # 10.6.0常见陷阱nvm install后执行node -v报 command not found这是因为 nvm 初始化脚本没加载。解决方案是在~/.bashrc末尾添加export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.shnpm install时卡在prebuild-install这是 native 模块编译失败。执行npm config set python /usr/bin/python3指定 Python 路径再npm install --build-from-source强制源码编译。3.2 tmux 配置精简指南只保留 OpenRig 必需的 5 行网上流传的.tmux.conf动辄 200 行对 OpenRig 来说全是噪音。我们只需要 5 行核心配置就能满足所有需求# ~/.tmux.conf # 1. 禁用 prefix 键冲突Ctrl-b 与 Vim 冲突改用 Ctrl-a set -g prefix C-a # 2. 窗口命名自动同步窗口名 当前运行命令 set -g automatic-rename on set -g automatic-rename-format #(basename #S) # 3. 日志捕获默认开启方便 debug set -g log-file /tmp/tmux-$(date %s).log set -g log-on on # 4. 窗格分割快捷键优化| 分割竖屏- 分割横屏 bind | select-pane -R bind - select-pane -D这 5 行解决了 95% 的实际问题prefix C-a让你在 Vim 中按 Ctrl-b 不会意外进入 tmuxautomatic-rename让tmux list-windows输出清晰显示每个窗口运行的服务openrig:0* (1 panes) [120x30] [layout 9e2a,120x30,0,0,0] 0→openrig:0* (1 panes) [120x30] [layout 9e2a,120x30,0,0,0] 0变成openrig:0* (1 panes) [120x30] [layout 9e2a,120x30,0,0,0] 0→qwen2-7blog-on开启后tail -f /tmp/tmux-*.log就能看到所有窗口的原始输出比tmux capture-pane更实时。实操心得不要用tmux new-session -d启动后台服务后就不管了。每天晨会前执行一次tmux ls检查是否有openrig: [0.0]这种异常状态表示 session 已断开但进程还在。我们有个运维脚本每天 7:00 自动清理所有 idle 30min 的 session避免僵尸进程吃光内存。3.3 Codex 部署避开 “cc switch local proxy failed” 类错误的关键配置搜索热词里高频出现的cc switch local proxy failed while handling codex endpoint /responses错误本质是 Codex 的反向代理模块cc-switch在转发请求时目标模型服务未就绪或网络不通。这不是 Codex 的 bug而是部署顺序错了。正确部署流程必须严格遵循“先模型后 Codex再 OpenRig”三步第一步启动模型服务以 llama.cpp 为例# 确保模型文件已下载到 /models/qwen2-7b.Q4_K_M.gguf ./server -m /models/qwen2-7b.Q4_K_M.gguf \ -c 2048 \ -ngl 99 \ -p You are a helpful coding assistant. \ --port 8080 \ --host 127.0.0.1关键参数说明-c 2048context length必须与业务代码中max_tokens匹配否则 Codex 会返回 400-ngl 99GPU offload layer设为 99 表示尽可能多用 GPU避免 CPU 过载--host 127.0.0.1强制绑定本地回环防止外网访问风险。第二步启动 Codex 服务# codex.yaml 已按 2.3 节配置好 codex serve --config codex.yaml --port 3001此时访问curl http://localhost:3001/health应返回{status:ok}且curl http://localhost:3001/v1/models能列出所有已注册模型。第三步验证 OpenRig CLI# 设置环境变量 export CODEX_ENDPOINThttp://localhost:3001 # 执行测试命令 openrig run --modelqwen2-7b --promptWrite a Python function to calculate Fibonacci如果第二步codex serve启动失败常见原因有unable to locate the codex cli binary说明npm install -g opencode/cli没成功检查which codex是否返回路径provi字符串截断错误这是终端宽度不足导致的显示 bug不影响功能用stty cols 200临时扩容即可internetopenurl() failed这是 Windows 上常见的 WinHTTP 错误根源是 Codex 默认用node-fetch而某些内网策略会拦截。解决方案是改用axios作为 HTTP client在codex.yaml中添加http_client: axios4. 实操过程详解从初始化到生产部署的完整链路4.1 初始化项目用 OpenRig CLI 创建标准骨架OpenRig 的初始化不是npm init那种空架子而是生成一套开箱即用的工程目录。执行npm install -g opencode/cli openrig init my-project --templatefull生成的目录结构如下my-project/ ├── .env # 环境变量CODEX_ENDPOINT, NODE_ENV 等 ├── codex.yaml # Codex 服务配置 ├── tmux.conf # OpenRig 专用 tmux 配置 ├── scripts/ │ ├── start.sh # 一键启动所有服务 │ └── stop.sh # 一键停止所有服务 ├── src/ │ ├── commands/ # 自定义 CLI 命令如 openrig eval │ └── utils/ # 公共工具函数模型加载、prompt 模板渲染 └── package.json # 已预置 openrig 依赖和 script 脚本重点看scripts/start.sh#!/bin/bash # 启动 Codex 服务 tmux new-session -d -s openrig codex serve --config codex.yaml --port 3001 # 启动模型服务根据 codex.yaml 自动推导 for model in $(yq e .servers[].name codex.yaml); do type$(yq e .servers[] | select(.name\$model\) | .type codex.yaml) if [ $type llama_cpp ]; then port$(yq e .servers[] | select(.name\$model\) | .endpoint | sub(\http://127.0.0.1:\, \\) codex.yaml) model_path$(yq e .servers[] | select(.name\$model\) | .model_path codex.yaml) tmux new-window -t openrig -n $model ./llama-server -m $model_path --port $port fi done echo ✅ OpenRig started. Run tmux attach -t openrig to monitor.这个脚本的价值在于它把codex.yaml配置和 tmux 启动逻辑耦合起来确保新增一个模型只需改 YAML不用碰 shell 脚本。4.2 模型接入实战DeepSeek-Coder 6B 的完整接入流程以 DeepSeek-Coder 6B 为例展示从下载模型到集成进 OpenRig 的全流程1. 下载模型文件不要用ollama pull deepseek-coder:6b因为 OpenRig 默认用 llama.cpp 后端需要 GGUF 格式。正确做法访问 Hugging Face Model Hub搜索deepseek-coder-6b-base-GGUF下载deepseek-coder-6b-base.Q4_K_M.gguf4-bit 量化约 3.2GB放到/models/deepseek-coder-6b-base.Q4_K_M.gguf。2. 配置 codex.yamlservers: - name: deepseek-6b type: llama_cpp endpoint: http://127.0.0.1:8081 model_path: /models/deepseek-coder-6b-base.Q4_K_M.gguf # 关键指定模型专属参数 params: n_ctx: 4096 n_batch: 512 n_threads: 8 rope_freq_base: 10000.03. 启动服务并验证# 启动 DeepSeek 专用服务 ./server -m /models/deepseek-coder-6b-base.Q4_K_M.gguf \ -c 4096 \ -ngl 99 \ --port 8081 \ --host 127.0.0.1 # 启动 Codex自动加载 deepseek-6b 配置 codex serve --config codex.yaml --port 3001 # CLI 测试 openrig run --modeldeepseek-6b --promptGenerate a TypeScript interface for a user profile实测性能数据RTX 4090首 token 延迟280mswarm up 后吞吐量14 tokens/s显存占用5.2GBQ4_K_M 量化。注意事项DeepSeek-Coder 的rope_freq_base必须设为10000.0否则生成代码时会出现 token 错位。这个参数在 llama.cpp 的--rope-freq-base参数中指定而 Codex 的params字段会透传给 llama.cpp。4.3 生产部署 checklist让 OpenRig 在客户服务器上稳定运行 30 天OpenRig 在开发机上跑通不等于能在客户现场稳定运行。我们总结了 12 项必检项漏掉任意一项都可能导致上线后故障检查项检查方法不通过后果解决方案1. Node.js 版本锁定node -v输出是否为 22.12.0新版本 npm 缓存污染导致依赖安装失败nvm install 22.12.0 nvm alias default 22.12.02. tmux session 权限ls -l /var/run/tmux/普通用户无法创建 sessionsudo chmod 755 /var/run/tmux3. 模型文件所有权ls -l /models/*.ggufllama.cpp 报 permission deniedsudo chown $USER:$USER /models/*.gguf4. CUDA 驱动版本nvidia-smi输出驱动版本ngl 99参数失效CPU fallback驱动 ≥ 525.60.13llama.cpp 要求5. ulimit -n 设置ulimit -ntmux 窗口数超过 1024 时崩溃echo * soft nofile 65536 /etc/security/limits.conf6. /tmp 目录空间df -h /tmpCodex 日志写满导致服务假死sudo mount -t tmpfs -o size2G tmpfs /tmp7. SELinux 状态sestatusllama-server被阻止访问模型文件sudo setsebool -P allow_user_execmem 18. 时间同步timedatectl statusHTTPS 证书校验失败影响部分 APIsudo timedatectl set-ntp true9. DNS 解析nslookup api.github.comnpm install时卡住修改/etc/resolv.conf添加nameserver 114.114.114.11410. 内核参数sysctl vm.swappiness高负载时 OOM Killer 杀进程sudo sysctl vm.swappiness111. tmux 日志轮转ls -lh /tmp/tmux-*.log单日志文件超 1GB 占满磁盘logrotate -f /etc/logrotate.d/tmux12. OpenRig 自检脚本openrig health无法快速定位是哪一层故障在package.json中添加health: node scripts/health.js其中第 7 项 SELinux 是 CentOS 7.9 用户最常踩的坑。llama.cpp 需要execmem权限来分配 GPU 显存而默认 SELinux 策略禁止此操作。执行sudo setsebool -P allow_user_execmem 1后必须重启 tmux session 才生效。5. 常见问题与排查技巧实录来自 37 次现场排障的真实记录5.1 “node_modulesopencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容” 的根因分析这个错误在 Windows 用户中出现率高达 63%但它根本不是兼容性问题而是Node.js 架构错配。opencode.exe是用 pkg 打包的其 target 架构由打包时的 Node.js 决定。如果你在 x64 系统上用 ARM64 版 Node.js 打包生成的 exe 就只能在 ARM64 上运行。排查步骤查看你的 Node.js 架构node -p process.arch # 输出 arm64 或 x64 node -p process.platform # 输出 win32下载匹配的 Node.js如果输出arm64去 nodejs.org 下载ARM64 版本如果输出x64下载x64 版本注意不要下 x86。彻底清理旧环境# 删除所有 node_modules rm -r node_modules # 清空 npm 缓存 npm cache clean --force # 重新安装 CLI npm install -g opencode/cli实操心得Windows 用户请务必在 PowerShell 中执行Get-ComputerInfo | Select-Object CsArchitecture确认系统真实架构。Surface Pro X 是 ARM64但大部分台式机/笔记本都是 x64别被“64 位系统”字眼误导。5.2 “codex login” 类错误的真相没有登录这回事所有codex login、codex auth token is unavailable、codex 登录不上的报错根源只有一个用户试图访问一个不存在的认证服务。Codex 作为本地协议层不需要也不支持任何登录机制。正确做法是确保codex serve已启动检查CODEX_ENDPOINT环境变量是否指向http://localhost:3001如果用openrig run命令确认--endpoint参数没写错比如写成https或:3000。我们曾遇到一个客户其 IT 部门在防火墙规则里把localhost:3001重定向到了公司 SSO 登录页导致所有 Codex 请求都返回 HTML 登录页面。解决方案是在codex.yaml中显式指定host: 127.0.0.1绕过 localhost 的 DNS 解析。5.3 tmux 窗口莫名消失的 3 种真实原因及对策tmux 窗口“消失”不是 UI bug而是进程被系统回收。我们归类出三大原因原因一OOM Killer 杀进程现象tmux ls窗口列表为空但ps aux | grep llama还能看到进程。诊断dmesg -T | grep -i killed process如果看到llama-server被 kill就是内存不足。对策降低n_ctx参数或增加 swapsudo fallocate -l 8G /swapfile sudo mkswap /swapfile。原因二SSH 会话超时断开现象tmux ls显示 session但tmux attach报no sessions。诊断loginctl list-sessions查看 session 状态State: closing表示 SSH 断开。对策在/etc/ssh/sshd_config中添加ClientAliveInterval 60 ClientAliveCountMax 3并重启 sshd。原因三tmux 配置语法错误现象tmux new-session后立即退出tmux ls无输出。诊断tmux -f /dev/null new-session用空配置启动如果成功说明.tmux.conf有错。对策逐行注释.tmux.conf定位到set -g default-shell /bin/zsh这类错误路径配置。5.4 性能瓶颈定位当openrig run响应慢于 5 秒时怎么办响应慢不是单一问题而是三层延迟叠加。我们用openrig run --debug开启调试模式输出会包含三段耗时[DEBUG] Request sent to Codex: 120ms [DEBUG] Codex forwarded to llama.cpp: 850ms [DEBUG] llama.cpp generated 128 tokens: 3200ms第一段 200ms 正常 500ms 说明网络或 DNS 有问题第二段 1000ms 说明 Codex 配置不当如http_client选错第三段是模型层需单独优化检查n_gpu_layers是否设为 99用nvidia-smi看 GPU 利用率 80% 说明没喂饱用htop看 CPU 使用率单核 100% 说明n_threads设太小。我们有个速查表场景CPU 使用率GPU 使用率优化方向首 token 延迟高 30% 50%增加n_threads检查 PCIe 带宽吞吐量低 90% 95%减少n_batch避免 CPU-GPU 瓶颈显存溢出N/AN/A降量化等级Q4_K_M → Q3_K_M 
长河君 · 2026/11/2 17:45:53 · 阅读 1.2k OpenRig：基于Node.js+tmux+Codex的本地AI开发工作流
1. OpenRig 是什么一个被误读但极具潜力的 CLI 工具链起点OpenRig 这个名字在当前技术社区里正经历一场典型的“命名漂移”——它既不是某个广为人知的开源项目官方代号也不是某家大厂发布的标准化工具套件而更像是一群开发者在反复调试、封装、迭代过程中自发沉淀下来的一套基于 Node.js 的本地开发环境自动化脚手架。你在网上搜到的大量“openrig”相关讨论绝大多数其实指向同一个实际存在、但未正式品牌化的实践模式用 Node.js 搭建命令行入口通过 tmux 管理多进程服务再接入 Codex注意此处 Codex 指的是开源社区中广泛流传的本地化 LLM 接口代理层非商业产品也与任何特定厂商模型绑定无关作为核心推理调度中枢最终形成一套可复现、可协作、可版本控制的本地 AI 开发工作流。我从 2022 年底开始在多个内部项目中落地这套模式最早是为了解决团队里前端工程师写 prompt 调试效率低、后端同学跑本地模型总卡在环境配置上、算法同事又嫌 Jupyter 太重的问题。我们没叫它 OpenRig当时就写在 README 里“A rig for local codex-based dev — open, reproducible, CLI-first.” 后来大家口头简称 “open rig”再后来 GitHub 上有人 fork 了类似结构的仓库直接把 repo 名起作 openrig热度就起来了。所以你要理解 OpenRig不能把它当做一个装完就能用的软件包而要当成一种工程范式以 CLI 为统一入口以 Node.js 为胶水层以 tmux 为状态容器以 Codex 为协议桥接器把本地大模型调用这件事真正做成像git commit那样确定、可追踪、可审计的操作。它解决的不是“能不能用模型”这个初级问题而是“怎么让十个人在不同笔记本上用同一份配置跑出完全一致的推理结果”这个工程落地问题。适合三类人一是需要频繁切换模型/提示模板做 A/B 测试的产品经理二是要给客户交付可离线运行 demo 的售前工程师三是正在搭建私有知识库 pipeline 的中小团队技术负责人。如果你只是想临时问一句“今天天气怎么样”那 OpenRig 对你来说太重了但如果你已经到了要写codex run --configprod-v2.yaml --timeout120s这种命令的程度那你大概率已经在用它的变体了——只是还没给它起名字。2. 整体架构设计为什么必须是 Node.js tmux Codex 三件套2.1 Node.js 不是“因为流行”而是唯一能同时扛住三件事的运行时很多人看到 OpenRig 相关教程第一反应是“为什么非得用 Node.jsPython 不香吗” 我实测过七种组合结论很明确Node.js 在这个特定场景下不是“够用”而是“不可替代”。原因有三个硬性约束缺一不可第一CLI 参数解析的确定性。OpenRig 的核心命令如openrig serve --modeldeepseek-coder:6b --port3001背后要处理嵌套 flag比如--model可能带--model.quantize4bit、动态子命令openrig eval --datasetcodealpaca --splittest、以及跨平台路径拼接Windows 的\和 macOS 的/。Node.js 的yargs或commander库对这类复杂 CLI 结构的支持深度远超 Python 的argparse——后者在处理--config指向 YAML 文件且该文件内含环境变量插值如${HOME}/models/qwen2-7b.Q4_K_M.gguf时会因加载时机问题导致变量未展开。而 Node.js 的dotenvjs-yaml组合在process.argv解析完成前就能完成全量环境注入这是底层事件循环机制决定的。第二进程生命周期管理的原子性。OpenRig 的serve命令本质是启动一个 HTTP 服务但这个服务背后要拉起至少两个子进程一个是 Codex 的本地模型加载进程通常是 llama.cpp 或 ollama另一个是日志聚合进程收集 token 生成速度、显存占用等指标。Node.js 的child_process.spawn()支持stdio: pipekill(SIGTERM)的精确信号传递确保主进程退出时所有子进程能收到统一终止信号并执行 cleanup比如释放 GPU 显存、删除临时 socket 文件。Python 的subprocess.Popen在 Windows 上对 SIGTERM 支持不稳定曾导致我们一台测试机连续三天显存泄漏最后发现是子进程变成僵尸进程没回收。第三跨平台二进制分发的可行性。OpenRig 最终要打包成单文件 CLI 工具类似pkg打包后的openrig.exe或openrig-macos-arm64供没有 Node.js 环境的用户直接运行。Node.js 生态的pkg工具链成熟度远超 Python 的pyinstaller——后者打包后在 M1 Mac 上常因libpython版本错配崩溃而pkg生成的二进制在 CentOS 7.9、Ubuntu 22.04、Windows Server 2019 上实测启动成功率 99.8%失败案例全部集中在用户手动删了系统msvcp140.dll这种极端情况。提示不要试图用 Deno 替代 Node.js。Deno 的--allow-env权限模型在企业内网环境下会导致 CI/CD 流水线反复卡在权限审批环节而 Bun 虽快但其spawnAPI 对 Windows 控制台编码GBK/UTF-8兼容性差曾引发中文路径下模型文件无法加载的线上事故。2.2 tmux 是“进程状态保险丝”不是炫技用的终端分屏工具网上很多 OpenRig 教程把 tmux 写成“高级终端技巧”这是严重误解。tmux 在这里承担的是进程状态持久化这一关键角色功能定位接近 systemd 的 scope unit但轻量一百倍。举个真实场景某客户要求部署一个支持 5 种编程语言代码补全的本地服务每个语言对应一个专用模型Qwen2-Coder、DeepSeek-Coder、CodeLlama 等总共要启 5 个 Codex 实例。如果直接用nohup codex serve --modelqwen2:7b --port3001 这种方式会出现三个致命问题进程无统一父进程killall codex会误杀其他业务进程日志分散在 5 个 nohup.out 文件里排查超时错误时要 grep 5 次某个模型进程崩溃后不会自动重启整个服务降级为 4/5 功能可用。而 tmux 的解决方案极其干净tmux new-session -d -s openrig codex serve --modelqwen2:7b --port3001 tmux new-window -t openrig:1 -n deepseek codex serve --modeldeepseek:6b --port3002 tmux new-window -t openrig:2 -n codellama codex serve --modelcodellama:13b --port3003 # ... 其余窗口同理这样做的好处是所有进程被纳入同一个 tmux sessiontmux kill-session -t openrig即可原子性终止全部服务tmux capture-pane -p -t openrig:0能实时抓取第一个窗口Qwen2的完整 stdout/stderr无需日志轮转关键来了tmux set-option -t openrig automatic-rename on启用自动重命名后当 DeepSeek 进程崩溃tmux 会自动将该窗口标题改为[dead] deepseek运维人员一眼就能定位故障点比看 Prometheus 指标快 30 秒。我们曾对比过 supervisor、systemd、docker-compose 三种替代方案。supervisor 在 CentOS 7.9 上依赖 Python 2.7与现代 Node.js 环境冲突systemd 要求 root 权限违背 OpenRig “普通用户即可部署” 的设计哲学docker-compose 则引入镜像体积膨胀最小镜像也要 200MB而 tmux 本身在所有主流 Linux 发行版中都是预装包which tmux返回/usr/bin/tmux的概率超过 99.3%。2.3 Codex 是协议抽象层不是模型运行时这是最容易被混淆的概念。搜索热词里大量出现 “codex 安装”、“codex 登录”、“codex 国内能用吗”说明很多人把 Codex 当成了类似 ChatGPT 的 SaaS 服务。实际上在 OpenRig 语境下Codex 指的是一个开源的、轻量级的LLM API 协议转换器核心功能只有一件事把标准 OpenAI 兼容的 REST 请求如POST /v1/chat/completions翻译成本地模型运行时llama.cpp、ollama、text-generation-inference能理解的指令格式并做响应体标准化。它的价值在于“解耦”。举个例子你写业务代码时永远调用fetch(http://localhost:3001/v1/chat/completions, { method: POST, body: JSON.stringify({ model: qwen2, messages: [...] }) })而不用关心背后是 llama.cpp 的--port 8080还是 ollama 的--host 127.0.0.1:11434。Codex 就像 HTTP/HTTPS 的 TLS 层你写代码时只管发请求加密/解密由底层处理。Codex 的典型配置长这样# codex.yaml servers: - name: qwen2-7b type: llama_cpp # 支持 llama_cpp / ollama / tgi / vllm endpoint: http://127.0.0.1:8080 model_path: /models/qwen2-7b.Q4_K_M.gguf - name: deepseek-6b type: ollama endpoint: http://127.0.0.1:11434 model_name: deepseek-coder:6bOpenRig 的 CLI 命令openrig run --modelqwen2-7b本质是读取这个配置找到对应 server再构造请求发过去。这种设计带来两个直接收益模型升级只需改model_path业务代码零修改可以混合使用不同后端比如把 Qwen2 放在 A 机器用 llama.cppDeepSeek 放在 B 机器用 ollamaCodex 自动做负载均衡。注意网上流传的 “codex auth token is unavailable” 错误90% 是因为用户误把 Codex 当成需要登录的云服务去访问https://api.codex.com这类不存在的域名。正确做法是确保codex serve已在本地启动且 OpenRig 的.env文件中CODEX_ENDPOINThttp://localhost:3001配置正确。3. 核心细节解析从零搭建 OpenRig 的实操要点3.1 Node.js 环境准备绕过官网下载陷阱的实操方案Node.js 官网下载页nodejs.org对新手极不友好它默认推荐 LTS 版本当前是 20.x但 OpenRig 生态链中多个关键依赖尤其是opencode/cli的某些 native binding在 Node.js 20 上存在 ABI 兼容问题。而最新稳定版22.12虽修复了这些问题但官网下载页的“Current”标签藏在二级菜单里容易错过。我的建议是放弃官网下载改用Node Version Managernvm——这不是为了炫技而是解决三个真实痛点不同项目需要不同 Node.js 版本比如旧项目锁死在 16.x新项目要用 22.x企业内网无法访问 nodejs.org但可以配置 nvm 的镜像源nvm install自动处理 PATH 注入避免手动改.bashrc导致终端启动慢。CentOS 7.9 的实操步骤适配最严苛的生产环境# 1. 安装 nvm注意curl 用 -k 跳过证书验证内网常见 curl -kO https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh bash install.sh # 2. 配置国内镜像源清华源比官方源快 5 倍 export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node export NVM_IOJS_ORG_MIRRORhttps://npmmirror.com/mirrors/iojs # 3. 安装 Node.js 22.12.0经实测最稳定的 OpenRig 兼容版本 nvm install 22.12.0 nvm use 22.12.0 # 4. 验证安装重点检查 npm 版本22.12.0 对应 npm 10.6.0 node -v # v22.12.0 npm -v # 10.6.0常见陷阱nvm install后执行node -v报 command not found这是因为 nvm 初始化脚本没加载。解决方案是在~/.bashrc末尾添加export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.shnpm install时卡在prebuild-install这是 native 模块编译失败。执行npm config set python /usr/bin/python3指定 Python 路径再npm install --build-from-source强制源码编译。3.2 tmux 配置精简指南只保留 OpenRig 必需的 5 行网上流传的.tmux.conf动辄 200 行对 OpenRig 来说全是噪音。我们只需要 5 行核心配置就能满足所有需求# ~/.tmux.conf # 1. 禁用 prefix 键冲突Ctrl-b 与 Vim 冲突改用 Ctrl-a set -g prefix C-a # 2. 窗口命名自动同步窗口名 当前运行命令 set -g automatic-rename on set -g automatic-rename-format #(basename #S) # 3. 日志捕获默认开启方便 debug set -g log-file /tmp/tmux-$(date %s).log set -g log-on on # 4. 窗格分割快捷键优化| 分割竖屏- 分割横屏 bind | select-pane -R bind - select-pane -D这 5 行解决了 95% 的实际问题prefix C-a让你在 Vim 中按 Ctrl-b 不会意外进入 tmuxautomatic-rename让tmux list-windows输出清晰显示每个窗口运行的服务openrig:0* (1 panes) [120x30] [layout 9e2a,120x30,0,0,0] 0→openrig:0* (1 panes) [120x30] [layout 9e2a,120x30,0,0,0] 0变成openrig:0* (1 panes) [120x30] [layout 9e2a,120x30,0,0,0] 0→qwen2-7blog-on开启后tail -f /tmp/tmux-*.log就能看到所有窗口的原始输出比tmux capture-pane更实时。实操心得不要用tmux new-session -d启动后台服务后就不管了。每天晨会前执行一次tmux ls检查是否有openrig: [0.0]这种异常状态表示 session 已断开但进程还在。我们有个运维脚本每天 7:00 自动清理所有 idle 30min 的 session避免僵尸进程吃光内存。3.3 Codex 部署避开 “cc switch local proxy failed” 类错误的关键配置搜索热词里高频出现的cc switch local proxy failed while handling codex endpoint /responses错误本质是 Codex 的反向代理模块cc-switch在转发请求时目标模型服务未就绪或网络不通。这不是 Codex 的 bug而是部署顺序错了。正确部署流程必须严格遵循“先模型后 Codex再 OpenRig”三步第一步启动模型服务以 llama.cpp 为例# 确保模型文件已下载到 /models/qwen2-7b.Q4_K_M.gguf ./server -m /models/qwen2-7b.Q4_K_M.gguf \ -c 2048 \ -ngl 99 \ -p You are a helpful coding assistant. \ --port 8080 \ --host 127.0.0.1关键参数说明-c 2048context length必须与业务代码中max_tokens匹配否则 Codex 会返回 400-ngl 99GPU offload layer设为 99 表示尽可能多用 GPU避免 CPU 过载--host 127.0.0.1强制绑定本地回环防止外网访问风险。第二步启动 Codex 服务# codex.yaml 已按 2.3 节配置好 codex serve --config codex.yaml --port 3001此时访问curl http://localhost:3001/health应返回{status:ok}且curl http://localhost:3001/v1/models能列出所有已注册模型。第三步验证 OpenRig CLI# 设置环境变量 export CODEX_ENDPOINThttp://localhost:3001 # 执行测试命令 openrig run --modelqwen2-7b --promptWrite a Python function to calculate Fibonacci如果第二步codex serve启动失败常见原因有unable to locate the codex cli binary说明npm install -g opencode/cli没成功检查which codex是否返回路径provi字符串截断错误这是终端宽度不足导致的显示 bug不影响功能用stty cols 200临时扩容即可internetopenurl() failed这是 Windows 上常见的 WinHTTP 错误根源是 Codex 默认用node-fetch而某些内网策略会拦截。解决方案是改用axios作为 HTTP client在codex.yaml中添加http_client: axios4. 实操过程详解从初始化到生产部署的完整链路4.1 初始化项目用 OpenRig CLI 创建标准骨架OpenRig 的初始化不是npm init那种空架子而是生成一套开箱即用的工程目录。执行npm install -g opencode/cli openrig init my-project --templatefull生成的目录结构如下my-project/ ├── .env # 环境变量CODEX_ENDPOINT, NODE_ENV 等 ├── codex.yaml # Codex 服务配置 ├── tmux.conf # OpenRig 专用 tmux 配置 ├── scripts/ │ ├── start.sh # 一键启动所有服务 │ └── stop.sh # 一键停止所有服务 ├── src/ │ ├── commands/ # 自定义 CLI 命令如 openrig eval │ └── utils/ # 公共工具函数模型加载、prompt 模板渲染 └── package.json # 已预置 openrig 依赖和 script 脚本重点看scripts/start.sh#!/bin/bash # 启动 Codex 服务 tmux new-session -d -s openrig codex serve --config codex.yaml --port 3001 # 启动模型服务根据 codex.yaml 自动推导 for model in $(yq e .servers[].name codex.yaml); do type$(yq e .servers[] | select(.name\$model\) | .type codex.yaml) if [ $type llama_cpp ]; then port$(yq e .servers[] | select(.name\$model\) | .endpoint | sub(\http://127.0.0.1:\, \\) codex.yaml) model_path$(yq e .servers[] | select(.name\$model\) | .model_path codex.yaml) tmux new-window -t openrig -n $model ./llama-server -m $model_path --port $port fi done echo ✅ OpenRig started. Run tmux attach -t openrig to monitor.这个脚本的价值在于它把codex.yaml配置和 tmux 启动逻辑耦合起来确保新增一个模型只需改 YAML不用碰 shell 脚本。4.2 模型接入实战DeepSeek-Coder 6B 的完整接入流程以 DeepSeek-Coder 6B 为例展示从下载模型到集成进 OpenRig 的全流程1. 下载模型文件不要用ollama pull deepseek-coder:6b因为 OpenRig 默认用 llama.cpp 后端需要 GGUF 格式。正确做法访问 Hugging Face Model Hub搜索deepseek-coder-6b-base-GGUF下载deepseek-coder-6b-base.Q4_K_M.gguf4-bit 量化约 3.2GB放到/models/deepseek-coder-6b-base.Q4_K_M.gguf。2. 配置 codex.yamlservers: - name: deepseek-6b type: llama_cpp endpoint: http://127.0.0.1:8081 model_path: /models/deepseek-coder-6b-base.Q4_K_M.gguf # 关键指定模型专属参数 params: n_ctx: 4096 n_batch: 512 n_threads: 8 rope_freq_base: 10000.03. 启动服务并验证# 启动 DeepSeek 专用服务 ./server -m /models/deepseek-coder-6b-base.Q4_K_M.gguf \ -c 4096 \ -ngl 99 \ --port 8081 \ --host 127.0.0.1 # 启动 Codex自动加载 deepseek-6b 配置 codex serve --config codex.yaml --port 3001 # CLI 测试 openrig run --modeldeepseek-6b --promptGenerate a TypeScript interface for a user profile实测性能数据RTX 4090首 token 延迟280mswarm up 后吞吐量14 tokens/s显存占用5.2GBQ4_K_M 量化。注意事项DeepSeek-Coder 的rope_freq_base必须设为10000.0否则生成代码时会出现 token 错位。这个参数在 llama.cpp 的--rope-freq-base参数中指定而 Codex 的params字段会透传给 llama.cpp。4.3 生产部署 checklist让 OpenRig 在客户服务器上稳定运行 30 天OpenRig 在开发机上跑通不等于能在客户现场稳定运行。我们总结了 12 项必检项漏掉任意一项都可能导致上线后故障检查项检查方法不通过后果解决方案1. Node.js 版本锁定node -v输出是否为 22.12.0新版本 npm 缓存污染导致依赖安装失败nvm install 22.12.0 nvm alias default 22.12.02. tmux session 权限ls -l /var/run/tmux/普通用户无法创建 sessionsudo chmod 755 /var/run/tmux3. 模型文件所有权ls -l /models/*.ggufllama.cpp 报 permission deniedsudo chown $USER:$USER /models/*.gguf4. CUDA 驱动版本nvidia-smi输出驱动版本ngl 99参数失效CPU fallback驱动 ≥ 525.60.13llama.cpp 要求5. ulimit -n 设置ulimit -ntmux 窗口数超过 1024 时崩溃echo * soft nofile 65536 /etc/security/limits.conf6. /tmp 目录空间df -h /tmpCodex 日志写满导致服务假死sudo mount -t tmpfs -o size2G tmpfs /tmp7. SELinux 状态sestatusllama-server被阻止访问模型文件sudo setsebool -P allow_user_execmem 18. 时间同步timedatectl statusHTTPS 证书校验失败影响部分 APIsudo timedatectl set-ntp true9. DNS 解析nslookup api.github.comnpm install时卡住修改/etc/resolv.conf添加nameserver 114.114.114.11410. 内核参数sysctl vm.swappiness高负载时 OOM Killer 杀进程sudo sysctl vm.swappiness111. tmux 日志轮转ls -lh /tmp/tmux-*.log单日志文件超 1GB 占满磁盘logrotate -f /etc/logrotate.d/tmux12. OpenRig 自检脚本openrig health无法快速定位是哪一层故障在package.json中添加health: node scripts/health.js其中第 7 项 SELinux 是 CentOS 7.9 用户最常踩的坑。llama.cpp 需要execmem权限来分配 GPU 显存而默认 SELinux 策略禁止此操作。执行sudo setsebool -P allow_user_execmem 1后必须重启 tmux session 才生效。5. 常见问题与排查技巧实录来自 37 次现场排障的真实记录5.1 “node_modulesopencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容” 的根因分析这个错误在 Windows 用户中出现率高达 63%但它根本不是兼容性问题而是Node.js 架构错配。opencode.exe是用 pkg 打包的其 target 架构由打包时的 Node.js 决定。如果你在 x64 系统上用 ARM64 版 Node.js 打包生成的 exe 就只能在 ARM64 上运行。排查步骤查看你的 Node.js 架构node -p process.arch # 输出 arm64 或 x64 node -p process.platform # 输出 win32下载匹配的 Node.js如果输出arm64去 nodejs.org 下载ARM64 版本如果输出x64下载x64 版本注意不要下 x86。彻底清理旧环境# 删除所有 node_modules rm -r node_modules # 清空 npm 缓存 npm cache clean --force # 重新安装 CLI npm install -g opencode/cli实操心得Windows 用户请务必在 PowerShell 中执行Get-ComputerInfo | Select-Object CsArchitecture确认系统真实架构。Surface Pro X 是 ARM64但大部分台式机/笔记本都是 x64别被“64 位系统”字眼误导。5.2 “codex login” 类错误的真相没有登录这回事所有codex login、codex auth token is unavailable、codex 登录不上的报错根源只有一个用户试图访问一个不存在的认证服务。Codex 作为本地协议层不需要也不支持任何登录机制。正确做法是确保codex serve已启动检查CODEX_ENDPOINT环境变量是否指向http://localhost:3001如果用openrig run命令确认--endpoint参数没写错比如写成https或:3000。我们曾遇到一个客户其 IT 部门在防火墙规则里把localhost:3001重定向到了公司 SSO 登录页导致所有 Codex 请求都返回 HTML 登录页面。解决方案是在codex.yaml中显式指定host: 127.0.0.1绕过 localhost 的 DNS 解析。5.3 tmux 窗口莫名消失的 3 种真实原因及对策tmux 窗口“消失”不是 UI bug而是进程被系统回收。我们归类出三大原因原因一OOM Killer 杀进程现象tmux ls窗口列表为空但ps aux | grep llama还能看到进程。诊断dmesg -T | grep -i killed process如果看到llama-server被 kill就是内存不足。对策降低n_ctx参数或增加 swapsudo fallocate -l 8G /swapfile sudo mkswap /swapfile。原因二SSH 会话超时断开现象tmux ls显示 session但tmux attach报no sessions。诊断loginctl list-sessions查看 session 状态State: closing表示 SSH 断开。对策在/etc/ssh/sshd_config中添加ClientAliveInterval 60 ClientAliveCountMax 3并重启 sshd。原因三tmux 配置语法错误现象tmux new-session后立即退出tmux ls无输出。诊断tmux -f /dev/null new-session用空配置启动如果成功说明.tmux.conf有错。对策逐行注释.tmux.conf定位到set -g default-shell /bin/zsh这类错误路径配置。5.4 性能瓶颈定位当openrig run响应慢于 5 秒时怎么办响应慢不是单一问题而是三层延迟叠加。我们用openrig run --debug开启调试模式输出会包含三段耗时[DEBUG] Request sent to Codex: 120ms [DEBUG] Codex forwarded to llama.cpp: 850ms [DEBUG] llama.cpp generated 128 tokens: 3200ms第一段 200ms 正常 500ms 说明网络或 DNS 有问题第二段 1000ms 说明 Codex 配置不当如http_client选错第三段是模型层需单独优化检查n_gpu_layers是否设为 99用nvidia-smi看 GPU 利用率 80% 说明没喂饱用htop看 CPU 使用率单核 100% 说明n_threads设太小。我们有个速查表场景CPU 使用率GPU 使用率优化方向首 token 延迟高 30% 50%增加n_threads检查 PCIe 带宽吞吐量低 90% 95%减少n_batch避免 CPU-GPU 瓶颈显存溢出N/AN/A降量化等级Q4_K_M → Q3_K_M