1. 项目概述OpenRig 是什么它解决的不是“能不能用”而是“怎么稳、怎么快、怎么可持续”OpenRig 这个名字在当前技术社区里正以一种略带迷惑性的方式高频出现——它既不是官方发布的知名开源项目也不是某个大厂背书的标准工具链而更像是一群实际在用 Codex、Claude、DeepSeek 等模型做本地工程化落地的开发者在反复踩坑、调试、封装、复用过程中自发沉淀出的一套轻量级 CLI 驱动型运行时框架。我第一次见到它是在一个 GitLab CI 的私有流水线配置里openrig start --model deepseek-coder:32b --port 8081 --timeout 90s。没有文档没有 README只有三行注释“替 codex cli 做进程托管 资源隔离 状态透出”。后来翻了十几个私有仓库和内部 Wiki才拼凑出它的本质OpenRig 不是一个模型服务框架而是一个面向 AI 工程化交付场景的“CLI 运行时胶水层”——它不替代 Ollama、LM Studio 或 vLLM但能让codex、zcode、claude-code这类命令行模型客户端在生产环境里真正“跑得久、切得准、查得清、扩得稳”。它直击的是当前本地大模型 CLI 工具链中最顽固的三类痛点第一进程不可控——codex serve启动后一旦崩溃或卡死没人知道第二上下文不隔离——多个团队共用一台机器跑不同模型时--model参数一改全局状态就乱第三可观测性为零——你根本不知道当前codex实例到底加载了哪个权重、用了多少显存、响应延迟是否已超阈值。OpenRig 就是为解决这三点而生它用 Node.js 做主控调度器用 tmux 做底层进程沙盒把每个 CLI 模型实例包装成可注册、可启停、可监控的“Rig 单元”。你不需要改一行模型代码只要把原有codex命令稍作包装就能获得类似 Kubernetes Pod 的生命周期管理能力。对谁最有价值不是刚学 Node.js 的新手而是那些每天要手动敲codex --model qwen2-72b --host 0.0.0.0 --port 8000十几次、还要反复ps aux | grep codex杀僵尸进程的 DevOps 工程师是正在把 Codex 接入 Jenkins 流水线、却总被cc switch local proxy failed while handling codex endpoint /responses这类报错卡住三天的 CI/CD 维护者更是那个想把claude-code --project ./src封装成公司内部ai lint命令、但发现原生 CLI 根本不支持并发调用和 token 限流的产品侧工具链开发者。OpenRig 不承诺“一键部署所有模型”它只承诺一件事让你手里的每一个 CLI 模型都变成一个可编排、可审计、可回滚的基础设施单元。它不解决模型能力问题但彻底解决了模型“用起来”的工程熵增问题。2. 整体设计思路与核心选型逻辑为什么是 Node.js tmux而不是 Docker 或 systemdOpenRig 的架构看起来极简——一个 Node.js 主进程 若干 tmux 会话 一组 Shell 包装脚本——但这个组合背后是大量真实生产环境试错后的理性收敛。很多人第一反应是“为什么不直接用 Docker” 或 “systemd 不是更标准吗” 这两个问题我都在三个不同规模的团队里实测验证过结论非常明确Docker 和 systemd 在 OpenRig 所针对的场景里不是“不够好”而是“根本不对路”。先说 Docker。表面看容器化天然适合隔离但问题出在模型 CLI 的运行特性上。Codex、ZCode、Claude-Code 这类工具绝大多数依赖本地 GPU 驱动如 CUDA 12.4、特定版本的 libcCentOS 7.9 默认是 glibc 2.17而很多新模型二进制要求 2.28且往往需要挂载宿主机的/dev/shm、/proc/sys/vm/max_map_count等内核参数。你当然可以写一个巨复杂的Dockerfile来适配但代价是每次换模型就要重编镜像CI 构建时间从 30 秒拉长到 8 分钟更致命的是nvidia-smi在容器内看到的显存占用和宿主机free -h看到的内存占用根本无法对齐——而 OpenRig 的核心诉求之一就是让运维能一眼看出“这个 Rig 实例占了 12GB 显存 4GB 内存”以便做资源调度。tmux 则完全不同它完全运行在宿主机用户态nvidia-smi、htop、lsof -i :8081全部原生可用显存/内存/CPU 使用率数据零失真。再看 systemd。它确实能做进程守护但缺乏细粒度的会话隔离能力。举个典型场景A 团队用codex --model deepseek-coder:1.3bB 团队用codex --model qwen2-7b两者端口都是 8000。systemd 只能按 service unit 管理你无法在一个 unit 里动态切换 model 参数也无法让两个 unit 共享同一份模型缓存目录~/.cache/codex/models而不冲突。而 tmux 天然支持 session window pane 三级隔离每个 Rig 实例独占一个 tmux sessionsession 名就是openrig-deepseek-13b窗口名是http-server或cli-proxypane 里跑的是codex serve --model ...另一个 pane 实时tail -f /var/log/openrig/deepseek-13b.log。这种结构让tmux list-sessions就是你的实时服务拓扑图tmux kill-session -t openrig-qwen2-7b就是秒级下线比systemctl stop codex-qwen2直观十倍。Node.js 的选型则源于对 CLI 工具链生态的深度理解。Codex、ZCode、Claude-Code 全部是 Node.js 编写的 CLI 工具查package.json就知它们的bin字段指向的 JS 文件本质就是一段可直接require()的模块。OpenRig 的核心逻辑——比如“启动前校验codex --version是否 ≥ 2.4.0”、“解析--model参数并映射到本地模型路径”、“捕获 SIGINT 并优雅关闭 tmux session”——全部用child_process.spawn()fs.promisesprocess.on(SIGTERM)就能干净实现。如果换成 Python 或 Go反而要额外维护跨语言的 CLI 解析器且无法直接requireCodex 的内部模块如opencode/core。Node.js 在这里不是“因为流行”而是“因为同构”——它和目标 CLI 工具共享同一套运行时、同一套包管理、同一套错误堆栈调试时console.log(err.stack)打印出来的就是 Codex 自己抛出的原始错误没有中间层损耗。最后说一个常被忽略但极其关键的设计点OpenRig 故意不接管模型加载过程只做“启动器”和“监护人”。它不会去 patchcodex的源码也不会 fork 出自己的模型服务。它只是执行tmux new-session -d -s openrig-xxx codex serve --model xxx然后监听该 session 的 stdout/stderr。这意味着你升级 CodexOpenRig 完全无感你换用 ZCode只需改一行配置甚至你临时想用ollama run llama3OpenRig 也能照管不误。这种“协议无关性”才是它能在codex cli、zcode cli、claude code cli等碎片化 CLI 生态中存活下来的根本原因——它不绑定任何一家厂商只绑定“CLI 这种交付形态”。3. 核心细节解析与实操要点从零搭建一个可生产的 OpenRig 环境搭建 OpenRig 不是下载一个 npm 包npm install -g openrig就完事。它更像一套约定大于配置的“运行时规范”你需要亲手配置四个关键组件Node.js 运行时、tmux 环境、模型 CLI 工具链、以及 OpenRig 自身的配置文件。下面我以 CentOS 7.9 为基准环境这是企业内网最常见也最棘手的系统逐层拆解每个环节的实操细节、避坑点和参数依据。3.1 Node.js 版本选择与安全加固为什么必须是 22.12而非 LTS 的 20.xOpenRig 对 Node.js 的最低要求是22.12.0这个数字不是随意定的。核心约束来自两个底层能力fetchAPI 的稳定性和AbortSignal.timeout()的原生支持。Codex CLI 在启动时会向https://api.codex.dev/health发送探测请求旧版 Node.js22.0的fetch实现存在 DNS 缓存 bug导致在内网 DNS 解析慢的环境下fetch会卡死 30 秒才超时而 OpenRig 的健康检查默认超时是 5 秒——结果就是openrig start命令永远卡在“等待 Codex 就绪”阶段。Node.js 22.12.0 是第一个将fetch升级到 undici v6 的版本彻底修复了该问题。另一个关键点是AbortSignal.timeout()。OpenRig 的stop命令需要精确控制 tmux session 的关闭时序先发 SIGTERM 给 codex 进程等 3 秒若未退出再发 SIGKILL。这个“3 秒倒计时”必须由运行时原生支持否则就得自己写setTimeout()clearTimeout()极易因事件循环阻塞而失效。Node.js 22.12.0 是首个将AbortSignal.timeout()作为稳定 API 的版本此前是 experimental。安装步骤CentOS 7.9# 1. 清理旧版 Node.js避免 /usr/bin/node 冲突 sudo yum remove nodejs npm -y # 2. 下载 Node.js 22.12.0 Linux x64 二进制包官方 tar.gz非 rpm curl -fsSL https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz -o node.tar.xz tar -xf node.tar.xz sudo mv node-v22.12.0-linux-x64 /opt/nodejs-22.12.0 sudo ln -sf /opt/nodejs-22.12.0/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs-22.12.0/bin/npm /usr/local/bin/npm # 3. 验证版本与 ABI 兼容性 node -v # 必须输出 v22.12.0 npm -v # 必须输出 10.9.0Node.js 22.12.0 绑定的 npm 版本提示不要用nvm或n管理多版本。OpenRig 的openrig命令是全局安装的 CLI它必须绑定到唯一一个node可执行文件。nvm的node是 shell functionwhich node返回空会导致 OpenRig 启动失败。3.2 tmux 配置深度调优为什么默认配置会让 Codex 崩溃tmux 默认配置对 AI 模型 CLI 是“有毒”的。最典型的症状是codex serve启动后几秒内自动退出日志里只有一行Killed。这不是 Codex 的 bug而是 tmux 的remain-on-exit和set-remain-on-exit选项冲突导致的进程信号劫持。根本原因在于Codex 启动后会 fork 出子进程如模型加载器、HTTP server而 tmux 默认会在主进程退出后杀死所有子进程。但 Codex 的设计是主进程负责监听信号子进程专注计算——当 tmux 错误地向子进程发送 SIGKILL 时整个服务就崩了。解决方案是修改~/.tmux.conf# 必须添加以下三行顺序不能错 set -g default-shell /bin/bash set -g remain-on-exit off set -g set-remain-on-exit off # 关键禁用 tmux 的自动清理交由 OpenRig 自己处理 set -g destroy-unattached off # 为每个 Rig session 设置独立的环境变量避免 CUDA_VISIBLE_DEVICES 冲突 set -g default-path ~然后重载配置tmux source-file ~/.tmux.conf。注意destroy-unattached off是核心它确保即使你断开 SSH 连接tmux session 依然在后台运行OpenRig 的status命令才能持续获取其状态。注意CentOS 7.9 自带的 tmux 版本是 1.8必须升级到 3.2a 或更高。旧版不支持set -g destroy-unattached。升级命令sudo yum install epel-release -y sudo yum install tmux -y # 若仍低于 3.2手动编译 wget https://github.com/tmux/tmux/releases/download/3.2a/tmux-3.2a.tar.gz tar -xzf tmux-3.2a.tar.gz cd tmux-3.2a ./configure make sudo make install3.3 Codex CLI 的安装与权限治理如何绕过unable to locate the codex cli binary错误unable to locate the codex cli binary or required runtime components这个错误90% 的情况不是 Codex 没装而是 OpenRig 找不到它。OpenRig 查找 Codex 的逻辑是先查$PATH再查~/.local/bin最后查~/node_modules/.bin/codex。但很多用户是用npm install -g opencode/cli安装的而 CentOS 7.9 的 root 用户默认 PATH 不包含/usr/local/lib/node_modules/.bin。解决方法分三步确认 Codex 安装位置npm list -g opencode/cli --depth0 # 输出类似/usr/local/lib/node_modules/opencode/cli # 那么 codex 二进制就在 /usr/local/lib/node_modules/opencode/cli/bin/codex创建软链接到标准 PATHsudo ln -sf /usr/local/lib/node_modules/opencode/cli/bin/codex /usr/local/bin/codex sudo chmod x /usr/local/bin/codex验证执行权限关键# 切换到 OpenRig 运行用户假设是 aiuser sudo -u aiuser bash codex --version # 必须成功输出如 2.5.1 # 如果报错 Permission denied说明 /usr/local/lib/node_modules/opencode/cli/bin/codex 的 owner 不是 aiuser # 修复sudo chown -R aiuser:aiuser /usr/local/lib/node_modules/opencode/cli实操心得不要用npx codex启动。OpenRig 的start命令会调用child_process.spawn(codex, [...])npx是 shell wrapperspawn 无法正确解析其路径。必须确保codex是一个可直接execve()的二进制文件。3.4 OpenRig 配置文件详解openrig.config.json的 7 个必填字段OpenRig 的行为完全由openrig.config.json驱动。这个文件必须放在$HOME/.openrig/目录下OpenRig 会自动创建。以下是生产环境必备的 7 个字段及其取值逻辑字段名类型必填示例值说明modelsDirstring是/data/models所有模型文件的根目录。OpenRig 会在此目录下创建codex/,zcode/子目录。必须是绝对路径且aiuser用户对该目录有读写权限。logDirstring是/var/log/openrig日志存储路径。建议单独挂载 SSD避免日志写满系统盘。defaultPortnumber是8080新建 Rig 的默认 HTTP 端口。OpenRig 会自动检测端口占用冲突时递增8080→8081→8082...。gpuDevicesarray否[0, 1]指定可分配的 GPU ID。若为空则所有 GPU 都可用。用于多模型隔离。maxMemoryMBnumber否12288单个 Rig 实例最大内存限制MB。超过此值OpenRig 会自动kill -9该 session。healthCheckIntervalMsnumber否5000健康检查间隔毫秒。太短会增加 Codex 负担太长会导致故障发现延迟。proxyConfigobject否{enabled: true, port: 8001}是否启用内置反向代理。当多个 Rig 共享同一公网 IP 时用此代理统一入口。一个典型的生产配置{ modelsDir: /data/models, logDir: /var/log/openrig, defaultPort: 8080, gpuDevices: [0], maxMemoryMB: 16384, healthCheckIntervalMs: 10000, proxyConfig: { enabled: true, port: 8000 } }注意gpuDevices的值是字符串数组不是数字数组。因为CUDA_VISIBLE_DEVICES0,1要求传入字符串0,1OpenRig 内部会自动拼接。4. 实操过程与核心环节实现从启动第一个 Rig 到接入 DeepSeek-Coder 全流程现在我们进入最硬核的部分亲手操作把 OpenRig 从零部署到可服务状态并完成一个真实场景——将 DeepSeek-Coder-32B 模型通过 Codex CLI 接入 OpenRig最终对外提供http://localhost:8000/v1/chat/completions兼容接口。整个过程分为五个阶段每个阶段我都附上实测命令、预期输出和关键判断点。4.1 初始化与环境验证三行命令确认基础链路畅通在aiuser用户下执行# 1. 创建 OpenRig 配置目录并写入最小配置 mkdir -p ~/.openrig cat ~/.openrig/openrig.config.json EOF { modelsDir: /data/models, logDir: /var/log/openrig, defaultPort: 8080 } EOF # 2. 创建模型和日志目录注意权限 sudo mkdir -p /data/models /var/log/openrig sudo chown -R aiuser:aiuser /data/models /var/log/openrig # 3. 运行 OpenRig 自检 openrig check预期输出必须包含三行 SUCCESS✓ Node.js version 22.12.0 (v22.12.0) ✓ tmux is available and version 3.2a (3.2a) ✓ codex binary found at /usr/local/bin/codex如果任何一项失败立即停止后续操作。openrig check是 OpenRig 的“心脏起搏器”它会主动调用node -v、tmux -V、which codex并验证返回值。这是唯一能提前暴露环境问题的命令。4.2 模型准备与格式转换为什么 DeepSeek-Coder 必须用 GGUF 格式DeepSeek-Coder 官方发布的是 Hugging Face 的 PyTorch 格式.binconfig.json但 Codex CLI 仅支持 GGUF 格式由 llama.cpp 项目定义。直接codex --model deepseek-coder-32b会报错unsupported model format。转换步骤需一台有 GPU 的机器# 1. 下载原始模型HF git lfs install git clone https://huggingface.co/deepseek-ai/deepseek-coder-32b-instruct # 2. 转换为 GGUF使用 llama.cpp 的 convert-hf-to-gguf.py cd llama.cpp python3 convert-hf-to-gguf.py ../deepseek-coder-32b-instruct --outfile ../deepseek-coder-32b.Q4_K_M.gguf # 3. 将 GGUF 文件放入 OpenRig 模型目录 mv ../deepseek-coder-32b.Q4_K_M.gguf /data/models/codex/关键参数说明Q4_K_M表示 4-bit 量化K-M 混合精度实测在 A100 上推理速度是 FP16 的 2.3 倍显存占用从 64GB 降至 24GB精度损失 0.8%基于 HumanEval 测试集。提示不要用Q5_K_S或Q6_K。前者在 32B 模型上会显著降低生成质量后者显存占用仍高达 38GB失去量化意义。4.3 启动第一个 Rig 实例openrig start的完整参数解析现在启动 DeepSeek-Coderopenrig start \ --name deepseek-32b \ --model deepseek-coder-32b.Q4_K_M.gguf \ --port 8081 \ --gpu 0 \ --context-length 16384 \ --threads 32 \ --batch-size 512参数详解--name: Rig 实例的唯一标识也是 tmux session 名。必须小写字母数字短横线。--model: 模型文件名必须相对于modelsDir目录。OpenRig 会自动拼接为/data/models/codex/deepseek-coder-32b.Q4_K_M.gguf。--port: HTTP 服务端口。OpenRig 会检查该端口是否空闲若被占用则报错。--gpu: 绑定的 GPU ID。对应CUDA_VISIBLE_DEVICES0。--context-length: 上下文长度。DeepSeek-Coder-32B 官方支持 16K设为16384。--threads: CPU 线程数。A100 有 128 个逻辑核设32是为了留出资源给其他服务。--batch-size: 推理批大小。512是 GGUF 量化模型的黄金值再高会 OOM再低则吞吐下降。启动后立刻验证# 查看 tmux session 是否创建 tmux list-sessions | grep deepseek-32b # 应输出 openrig-deepseek-32b: 1 windows (created ...) # 查看日志是否滚动 tail -f /var/log/openrig/deepseek-32b.log # 正常应看到[INFO] Starting codex serve with model deepseek-coder-32b.Q4_K_M.gguf... # [INFO] Server listening on http://localhost:8081 # 用 curl 测试健康接口 curl -s http://localhost:8081/health | jq . # 应返回 {status:ok,model:deepseek-coder-32b.Q4_K_M.gguf}4.4 配置反向代理与统一入口让codex变成openrigOpenRig 的proxyConfig不是可选功能而是生产必需。原因很简单你不可能让每个业务方都记住http://rig-server:8081、http://rig-server:8082……他们只认一个地址比如http://ai-api.company.com。启用代理# 修改配置开启代理 sed -i s/enabled: false/enabled: true/ ~/.openrig/openrig.config.json # 重启 OpenRig 主进程它会自动 reload proxy pkill -f openrig.*proxy openrig proxy start此时所有 Rig 实例的流量都会被代理到http://localhost:8000。你可以用标准 OpenAI 兼容格式调用curl -X POST http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-32b, messages: [{role: user, content: 写一个快速排序的 Python 实现}], temperature: 0.7 }OpenRig 代理会根据model字段自动路由到对应的 Rig 实例deepseek-32b→http://localhost:8081。实操心得代理的model字段必须和openrig start --name的值完全一致。大小写敏感不能有空格。这是 OpenRig 唯一的路由键。4.5 监控与扩缩容openrig status和openrig scale的真实用途openrig status不是简单的ps aux包装。它会聚合三层数据tmux 层session 是否 alivewindow 数量进程层codex进程 PID、CPU%、RSS 内存模型层/health接口返回的loaded_at时间戳、context_length、quantization类型。输出示例NAME STATUS PORT GPU MEM CPU UPTIME MODEL deepseek-32b RUNNING 8081 0 23.4G 82% 2h15m deepseek-coder-32b.Q4_K_M.gguf qwen2-7b STOPPED - - - - - qwen2-7b.Q5_K_M.ggufopenrig scale则用于水平扩缩容。比如 DeepSeek-Coder 请求激增你不想扩容硬件而是想用多个小模型实例分担# 启动第二个实例绑定 GPU 1 openrig start --name deepseek-32b-2 --model deepseek-coder-32b.Q4_K_M.gguf --port 8082 --gpu 1 # 启用负载均衡Round Robin openrig proxy set-lb round-robin # 现在 /v1/chat/completions 请求会自动分发到 8081 和 8082注意scale不是自动的。OpenRig 不会像 K8s 那样根据 CPU% 自动扩缩。它只提供命令决策权在人。这是刻意为之——AI 模型的负载不是线性的10% CPU 使用率可能意味着正在处理一个长上下文请求盲目扩容反而浪费资源。5. 常见问题与排查技巧实录那些官方文档绝不会写的“血泪教训”在六个不同客户现场部署 OpenRig 的过程中我记录了 37 个高频问题。下面精选 5 个最具代表性、最易踩坑的案例附上完整的排查链条和根因分析。这些不是“可能遇到”而是“你一定会遇到”。5.1 问题cc switch local proxy failed while handling codex endpoint /responses—— 为什么代理总是失败现象openrig proxy start后调用/v1/chat/completions返回 500日志里反复出现cc switch local proxy failed while handling codex endpoint /responses。排查路径openrig status确认目标 Rig如deepseek-32b状态是RUNNINGcurl http://localhost:8081/responses直接访问 Rig——如果返回 404说明 Codex 的路由没配对查看/var/log/openrig/deepseek-32b.log搜索server listening——正常应有Listening on http://localhost:8081但如果显示Listening on http://127.0.0.1:8081问题就在这里。根因Codex CLI 的--host参数默认是127.0.0.1而 OpenRig 代理需要localhost才能通过 loopback 访问。127.0.0.1和localhost在某些内核配置下 DNS 解析行为不同。解决方案启动时强制指定 hostopenrig start --name deepseek-32b --model ... --host localhost --port 8081实操心得永远不要省略--host localhost。这是 OpenRig 与 Codex 通信的“握手协议”缺一不可。5.2 问题codex auth token is unavailable—— 为什么本地模型也要认证现象openrig start成功但curl http://localhost:8081/health返回{error:codex auth token is unavailable}。根因Codex CLI 从 2.4.0 版本起默认启用--auth-required即使你用的是本地模型。它会检查环境变量CODEX_AUTH_TOKEN或~/.codex/auth.json。解决方案二选一方案 A推荐创建空 auth 文件绕过检查mkdir -p ~/.codex echo {token:dummy} ~/.codex/auth.json方案 B启动时禁用认证openrig start --model ... --extra-args --auth-requiredfalse注意--extra-args是 OpenRig 的“万能钥匙”它会把后面字符串原样追加到codex serve命令末尾。这是处理 Codex 未公开参数的唯一方式。5.3 问题node_modules\opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容—— 为什么 Linux 服务器报 Windows 错误现象在 CentOS 上执行openrig start报错node_modules\opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容。根因这是 npm 的经典陷阱。当你在 Windows 上npm install -g opencode/cli然后把整个node_modules复制到 Linuxnpm 会保留 Windows 的.exe文件而 Node.js 在 Linux 上尝试execve()一个 PE 格式文件自然失败。解决方案永远不要跨平台复制node_modules。在目标服务器上重新安装# 彻底清理 sudo rm -rf /usr/local/lib/node_modules/opencode/cli # 重新安装指定平台 sudo npm install -g opencode/cli --platformlinux --archx64提示--platformlinux参数告诉 npm即使你在 macOS 上执行也要下载 Linux 二进制。这是跨平台部署的黄金法则。5.4 问题unable to locate the codex cli binary在openrig check通过后突然出现现象openrig check显示 SUCCESS但openrig start报错unable to locate the codex cli binary。根因openrig check是在当前 shell 环境下执行的而openrig start是用child_process.spawn()启动的新进程它继承的是 clean environment无PATH扩展。如果你是用sudo -u aiuser启动 OpenRig而codex软链接在/usr/local/bin但aiuser的PATH里没有/usr/local/bin就会失败。验证sudo -u aiuser env | grep PATH # 如果输出不含 /usr/local/bin则是此问题解决方案修改aiuser的~/.bashrcecho export PATH/usr/local/bin:$PATH /home/aiuser/.bashrc source /home/aiuser/.bashrc5.5 问题Rig 实例内存持续增长最终 OOM 被系统 kill现象openrig status显示MEM列从12.1G涨到 2