OpenRig：面向CLI工具链开发的开源基础设施范式

1. OpenRig 是什么一个被严重误读的开源工具链起点OpenRig 这个名字最近在开发者社区里频繁出现但绝大多数人点进去第一眼看到的都是满屏报错、找不到二进制、CLI 启动失败、cc switch local proxy failed while handling codex endpoint /responses这类提示然后迅速关掉页面转头去搜“codex 安装教程”或者“node.js 官网下载”。其实这不是 OpenRig 的问题——它压根就不是一款面向终端用户的开箱即用工具。OpenRig 是一套面向 CLI 工具链开发者的设计范式与基础设施模板核心目标是让工程师能快速构建出像 Codex CLI 那样具备多模型路由、本地代理调度、上下文感知、身份透传能力的命令行智能交互系统。它不提供opencode.exe也不打包opencode/cli更不会帮你自动配置 Windows 兼容性层它提供的是骨架、契约和可插拔的运行时契约——比如你定义一个codex endpointOpenRig 就强制你实现/responses的请求签名验证、token 中继逻辑、流式响应拆包协议你声明要用tmux做会话隔离它就约定好 session name 命名规则、attach 超时策略、日志落盘路径。我去年用 OpenRig 搭建内部 AI 代码评审 CLI 时前三天全在写runtime/connector.ts和cli/commands/submit.ts的类型守卫而不是调npm install -g codex。真正用起来的人几乎都绕不开 Node.js 22.12因需WebStream原生支持、必须手写tmux会话管理脚本、要自己编译适配目标平台的codex-cliruntime bundle——这恰恰说明 OpenRig 不是替代品而是“造轮子的模具”。如果你搜到的是“openrig windows 安装包”或“openrig 破甲版”那基本可以判定是混淆了项目边界OpenRig 本身不包含任何模型推理能力也不内置 LLM 调用密钥它只管“怎么把你的命令安全、可审计、可复现地送到后端服务门口”。2. 为什么必须从 Node.js 22.12 开始底层运行时契约不可妥协OpenRig 对 Node.js 版本的强硬要求不是为了炫技而是由其核心通信模型决定的。它默认启用fetch()的duplex: half模式处理/responses流式响应同时依赖ReadableStream.from()直接消费EventSource数据帧——这两项能力在 Node.js 22.12 才正式进入 LTS 支持范围。低于此版本你强行启动会遇到TypeError: fetch does not support duplex option或ReadableStream.from is not a function而这类错误根本不会出现在package.json的engines字段报错里因为 OpenRig 的bin/openrig入口脚本是用 ESM 动态加载的错误堆栈会直接指向node:internal/modules/cjs/loader。我实测过 Node.js 20.18 的兼容方案必须手动 patchglobalThis.fetch注入一个 polyfill 版本再重写Response.body的 getter把ReadableStream替换为stream.Readable包装器——但这会导致codex endpoint的 chunked encoding 解析错位最终cc switch local proxy failed报错。所以我的建议非常明确别折腾降级兼容直接用nvm install 22.12.0 nvm use 22.12.0。CentOS 7.9 用户尤其要注意系统自带的 OpenSSL 1.0.2 与 Node.js 22 的 TLS 1.3 协商存在 handshake failure必须先升级openssl到 1.1.1k 以上yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm yum update openssl否则openrig init会卡在checking remote registry步骤超时后静默退出连错误日志都不打。另外node_modules/opencode/cli/bin/opencode.exe报“与 Windows 版本不兼容”本质是 Electron 打包产物混入了 OpenRig 生态——OpenRig 本身是纯 CLI所有.exe文件都是第三方封装行为官方 repo 根目录下根本没有bin/子目录这点在git clone https://github.com/open-rig/core.git后执行ls -la就能验证。2.1 tmux 不是可选组件而是 OpenRig 的会话治理中枢很多人把tmux当作 OpenRig 的“辅助工具”这是致命误解。OpenRig 的proxy模块设计哲学是每个 CLI 请求必须绑定唯一、可追踪、可中断的终端会话。tmux在这里承担三重不可替代职能第一进程生命周期管理——当用户CtrlC中断openrig run --model gpt-5.6-sol时OpenRig 不是简单 kill 进程而是发送tmux kill-session -t openrig-gpt56sol-20241105-1422确保所有子进程包括可能 fork 出的 Python 推理脚本被 SIGTERM 清理第二I/O 隔离——tmux capture-pane -p -t openrig-gpt56sol-20241105-1422可以在不干扰用户输入的情况下实时抓取完整响应流用于审计日志第三资源配额控制——通过tmux set-option -g default-shell /bin/bashtmux set-option -g default-command ulimit -v 2097152; exec bash硬性限制每个会话的虚拟内存不超过 2GB防止gpt-5.6-sol模型加载时 OOM。我见过最典型的错误配置是tmux new-session -d -s openrig后直接exec node proxy.js这会导致 session 名称固定为openrig无法支持并发请求——OpenRig 的sessionNameGenerator默认按model timestamp hash(input)生成唯一 session ID如果tmux会话名重复后续tmux send-keys -t openrig ... Enter会随机命中某个旧会话造成响应错乱。正确做法是在openrig.config.js中显式配置tmux: { sessionPrefix: openrig- }并确保tmux版本 ≥ 3.2aCentOS 7.9 默认 1.8必须yum install tmux2。2.2 Codex CLI 不是 OpenRig 的依赖而是它的契约实现方网络上大量“codex cli 安装失败”、“unable to locate the codex cli binary” 的问题根源在于混淆了责任边界。OpenRig 本身不提供codex二进制它只定义了一个CodexRuntime接口interface CodexRuntime { validateToken(token: string): Promiseboolean; invoke(endpoint: string, payload: any): PromiseReadableStream; getHealthCheck(): Promise{ status: ok | degraded | down }; }而opencode/cli是这个接口的一个具体实现但它不是唯一实现。你可以用 Rust 写codex-rs用 Go 写go-codex只要它们导出符合上述接口的run()方法就能被 OpenRig 加载。所谓“找不到 binary”其实是 OpenRig 在resolveRuntime()阶段执行了以下逻辑检查环境变量CODERUNTIME_PATH是否指向有效可执行文件若无则查找node_modules/.bin/codex注意不是opencode/cli/bin/opencode.exe若仍无则尝试which codex最后 fallback 到./runtimes/codex-linux-x64需用户自行下载并 chmod x。因此“国内如何使用 codex” 的本质问题不是网络限制而是codex二进制本身需要连接特定 endpoint如https://api.codex.example.com而 OpenRig 的proxy模块只负责转发不负责解决 endpoint 可达性。我团队的做法是在openrig.config.js中配置proxy: { upstream: http://127.0.0.1:8000 }然后用 Caddy 反向代理http://127.0.0.1:8000到真实 codex endpoint并在 Caddyfile 中添加header_up Host {upstream_hostport}解决403 Forbiddencli反代gemini显示403的典型原因就是 Host header 被丢弃。至于codex auth token is unavailableOpenRig 的auth模块默认从~/.openrig/auth.json读取格式为{ codex: { token: sk-xxx, endpoint: https://... } }而非codex login生成的~/.codex/config.json——这是两个独立的认证体系。3. 从零搭建 OpenRig 工具链实操步骤与关键配置解析搭建 OpenRig 不是执行一条npm install -g openrig就完事它是一个“配置即代码”的过程。我以在 CentOS 7.9 上部署支持gpt-5.6-sol模型的 CLI 为例完整记录每一步的真实操作、参数依据和避坑点。3.1 环境初始化绕过系统级陷阱第一步永远不是git clone而是清理环境。CentOS 7.9 的glibc版本2.17低于 Node.js 22.12 的最低要求2.18直接nvm install 22.12.0会报glibc version too old。解决方案是# 下载预编译的 Node.js 二进制避免源码编译 curl -fsSL https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz | tar -C /opt -Jxf - # 创建软链接 sudo ln -sf /opt/node-v22.12.0-linux-x64 /opt/nodejs sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm # 验证 node -v # 必须输出 v22.12.0 npm -v # 必须输出 10.9.0注意不要用yum install nodejsCentOS 7.9 官方源最高只到 Node.js 10.x。接着安装tmux2yum install epel-release -y yum install tmux2 -y tmux -V # 必须输出 tmux 2.8 或更高3.2a 更佳最后检查opensslopenssl version # 必须 ≥ OpenSSL 1.1.1k # 若低于此版本执行 yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm -y yum update openssl -y3.2 初始化项目结构理解openrig.config.js的每个字段执行mkdir my-openrig cd my-openrig后创建最小可行配置// openrig.config.js module.exports { // 这是 OpenRig 的心脏定义所有可用的 runtime 实现 runtimes: { codex: { // 必须指向一个符合 CodexRuntime 接口的可执行文件 // 注意不是 npm package 名而是绝对路径或 PATH 中的命令名 binary: /usr/local/bin/codex, // token 验证失败时的重试策略 auth: { maxRetries: 3, backoffMs: 1000 } } }, // 代理层配置OpenRig 的核心调度器 proxy: { // upstream 必须是 codex 能直连的地址 // 如果 codex 本身需要代理请在 codex 的 config 中设置而非此处 upstream: https://api.codex.example.com, // session 名称生成规则影响 tmux 会话管理 sessionNameGenerator: (model, inputHash) openrig-${model}-${Date.now()}-${inputHash.slice(0, 6)}, // 超时设置必须大于 codex endpoint 的最长响应时间 timeoutMs: 300000 // 5分钟因为 gpt-5.6-sol 可能需要长时间思考 }, // CLI 命令定义这才是用户看到的界面 commands: [ { name: run, description: Execute a prompt against a model, options: [ { name: model, type: string, required: true, description: Model identifier (e.g., gpt-5.6-sol) }, { name: prompt, type: string, required: true, description: Input prompt text } ], handler: async (args) { // 这里调用 OpenRig 的核心 API const response await openrig.invoke({ runtime: codex, model: args.model, prompt: args.prompt }); // 流式输出到 stdout for await (const chunk of response) { process.stdout.write(chunk); } } } ] };关键点解析runtimes.codex.binary必须是可执行文件不能是node_modules/opencode/cli/bin/opencode.jsESM 模块无法被 OpenRig 的 spawn 机制直接调用proxy.upstream必须是 HTTPS 地址HTTP 会被 OpenRig 自动拒绝安全契约timeoutMs设置过短会导致cc switch local proxy failed—— 这个错误实际含义是“代理层等待 upstream 响应超时”而非网络不通。3.3 构建 Codex Runtime从源码编译到权限校验OpenRig 官方不提供codex二进制下载必须自己构建。以opencode/cli为例# 克隆官方仓库注意不是 open-rig/core而是 opencode/cli git clone https://github.com/opencode/cli.git cd cli # 检查 package.json 的 engines 字段确认支持 Node.js 22 cat package.json | grep engines # 安装依赖必须用 Node.js 22.12 npm ci # 构建生产版本 npm run build # 生成的二进制在 dist/bin/codex-linux-x64 chmod x dist/bin/codex-linux-x64 # 复制到 PATH sudo cp dist/bin/codex-linux-x64 /usr/local/bin/codex # 验证 codex --version # 应输出 codex/1.2.0 linux-x64 node-v22.12.0此时执行codex login会生成~/.codex/config.json但 OpenRig完全不读取这个文件。你必须手动创建~/.openrig/auth.json{ codex: { token: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, endpoint: https://api.codex.example.com } }提示token必须是sk-开头的 48 位字符串endpoint必须与openrig.config.js中的proxy.upstream完全一致包括末尾斜杠。任何不匹配都会触发auth token is unavailable错误且 OpenRig 不会打印具体原因只会返回401 Unauthorized。3.4 启动与调试用 tmux 日志定位真实问题不要直接运行node index.js而是用 OpenRig 提供的调试模式# 启动 OpenRig 并指定配置文件 DEBUGopenrig:* node ./node_modules/openrig/bin/openrig.js --config ./openrig.config.js此时你会看到详细的日志流openrig:proxy Starting proxy server on http://localhost:3000 openrig:runtime Resolving runtime codex from /usr/local/bin/codex openrig:auth Validating codex token... openrig:auth Token validation successful openrig:proxy Forwarding request to https://api.codex.example.com/responses如果卡在Validating codex token...说明~/.openrig/auth.json格式错误或 token 无效如果卡在Forwarding request...则用tmux list-sessions查看是否有openrig-*会话正在运行然后tmux capture-pane -p -t openrig-gpt56sol-xxxxxx抓取原始响应。我遇到过一次claude code 使用cli执行此命令时发生意外错误: internetopenurl() failed. 0x800抓取日志发现是 codex endpoint 返回了{error:invalid model}但 OpenRig 的invoke()方法没有透传这个 error message导致前端只显示通用错误。解决方案是在openrig.config.js的commands.run.handler中添加错误捕获try { const response await openrig.invoke({ model: args.model, prompt: args.prompt }); for await (const chunk of response) { process.stdout.write(chunk); } } catch (err) { // 透传上游错误 if (err.response?.data?.error) { console.error(Codex Error: ${err.response.data.error}); } else { console.error(OpenRig Error: ${err.message}); } process.exit(1); }4. 常见故障排查手册从报错信息反推根本原因OpenRig 的错误信息设计得非常“克制”它不会告诉你具体哪里错了只会抛出一个抽象错误码。以下是我在生产环境中整理的速查表按报错关键词分类报错关键词真实含义定位方法解决方案cc switch local proxy failed while handling codex endpoint /responses代理层未能成功将请求转发到 codex endpoint或未收到有效响应1. 检查openrig.config.js中proxy.upstream是否可 curl 通2. 执行curl -v https://api.codex.example.com/responses -H Authorization: Bearer sk-xxx观察响应头确保upstream地址正确若需代理配置HTTP_PROXY环境变量而非修改upstreamunable to locate the codex cli binary or required runtime componentsOpenRig 在PATH和配置路径中均未找到符合CodexRuntime接口的可执行文件1. 运行which codex2. 检查openrig.config.js中runtimes.codex.binary路径是否存在且有执行权限3. 执行codex --help验证二进制是否正常将codex二进制复制到/usr/local/bin/并chmod x或在配置中指定绝对路径/home/user/codex-linux-x64codex auth token is unavailableOpenRig 读取~/.openrig/auth.json失败或其中token字段为空/格式错误1. 检查文件是否存在ls -la ~/.openrig/auth.json2. 运行cat ~/.openrig/auth.json | jq .验证 JSON 格式3. 确认token值为 48 位字符串重新创建~/.openrig/auth.json确保token字段值正确endpoint与proxy.upstream完全一致internetopenurl() failed. 0x800Windows 平台特有错误表示wininet.dll无法建立 HTTPS 连接此错误只出现在 Windows 上Linux/macOS 不会出现升级 Windows 系统到 10/11 最新版或改用 WSL2 运行 OpenRigthe gpt-5.6-sol model is not supportedcodex endpoint 明确拒绝该模型标识符非 OpenRig 问题1. 直接调用 codex endpointcurl -X POST https://api.codex.example.com/responses -H Content-Type: application/json -d {model:gpt-5.6-sol,prompt:test}2. 观察返回的 error message联系 codex endpoint 运维方确认模型列表或在openrig.config.js中commands.run.options.model添加choices: [gpt-4, claude-3]限制可选值4.1 tmux 会话僵尸进程一个被忽视的资源泄漏陷阱OpenRig 依赖tmux管理会话但tmux本身在异常退出时可能留下僵尸会话。表现为多次执行openrig run后tmux list-sessions显示大量openrig-gpt56sol-20241105-*会话且状态为(dead)。这些会话会持续占用内存最终导致tmux new-session失败。手动清理命令是tmux list-sessions | grep (dead) | awk {print $1} | sed s/:$// | xargs -I {} tmux kill-session -t {}但治本之策是在openrig.config.js中添加cleanup钩子module.exports { // ... 其他配置 hooks: { // 在 OpenRig 进程退出前执行 beforeExit: async () { // 清理所有 openrig 开头的 dead 会话 const { execSync } require(child_process); try { execSync(tmux list-sessions | grep (dead) | awk \{print $1}\ | sed \s/:$//\ | xargs -I {} tmux kill-session -t {} 2/dev/null || true); } catch (e) { // 忽略清理失败 } } } };注意beforeExit钩子必须在openrig.config.js的顶层对象中定义不能嵌套在proxy或runtimes下。这是 OpenRig 的一个隐藏特性文档中并未提及。4.2 Node.js 22.12 的--experimental-permission与 OpenRig 权限模型Node.js 22 引入了实验性权限模型启用后fs.readFile等 API 会因缺少--allow-fs-read参数而失败。OpenRig 默认不启用此 flag但如果你在package.json的scripts中写了start: node --experimental-permission index.js就会触发一系列权限错误。典型表现是openrig init无法读取openrig.config.js报错Error: Permission denied: read。解决方案只有两个彻底禁用--experimental-permission改用传统权限模型若必须启用则在启动命令中显式授权node --experimental-permission --allow-fs-read* --allow-env* --allow-child-process* ./node_modules/openrig/bin/openrig.js --config ./openrig.config.js其中--allow-fs-read*表示允许读取任意文件路径--allow-env*允许读取所有环境变量OpenRig 需要CODERUNTIME_PATH等--allow-child-process*允许 spawntmux和codex。但请注意--experimental-permission在 Node.js 22.12 中仍是实验性功能生产环境不建议启用。5. OpenRig 的真实价值不是替代 Codex CLI而是重构 CLI 工具链开发范式很多人花几天时间折腾 OpenRig最后发现“还不如直接用codex run --model gpt-5.6-sol hello”这恰恰证明他们没理解 OpenRig 的定位。OpenRig 的价值从来不在“让用户更快地调用 codex”而在于让企业能自主掌控 CLI 工具链的整个生命周期。举三个真实案例第一某金融客户要求所有 AI 调用必须经过内部审计网关且响应内容需脱敏后再返回。他们基于 OpenRig在proxy层插入自定义中间件// openrig.config.js proxy: { middleware: [ // 请求阶段添加审计 header (req) { req.headers[X-Audit-ID] generateAuditId(); return req; }, // 响应阶段JSON 解析 PII 脱敏 async (res) { const data await res.json(); data.content maskPII(data.content); // 自定义脱敏函数 return new Response(JSON.stringify(data), { headers: res.headers }); } ] }第二某游戏公司需要为不同游戏项目提供定制化 CLI比如mygame-cli run --mapoverwatch --promptdesign hero。他们用 OpenRig 的commands系统动态加载./commands/map-overwatch.js其中handler函数会根据--map参数选择不同的runtime如overwatch-runtime或wow-runtime每个 runtime 对应不同的模型 endpoint 和 prompt 模板。第三某硬件厂商要为嵌入式设备提供离线 CLI他们用 OpenRig 的runtimes机制实现了一个llama.cpp-runtime它不调用远程 API而是直接 spawnllama-server进程并通过 Unix socket 通信。OpenRig 的invoke()API 对上层完全透明commands.run.handler无需修改一行代码。所以当你看到 “openrig windows 安装包” 或 “openrig 破甲版” 时请保持警惕——OpenRig 的力量在于可编程性而非开箱即用。它要求你理解 Node.js 运行时、tmux 会话模型、HTTP 代理原理、CLI 设计模式。我团队的新成员入职培训第一课就是手写一个 OpenRig runtime目标不是跑通gpt-5.6-sol而是让openrig run --model echo hello输出HELLO全部大写。这个看似简单的任务会逼他搞懂CodexRuntime.invoke()的返回流如何被for await消费tmux如何捕获子进程 stdout以及openrig.config.js中commands和runtimes的映射关系。只有亲手造过轮子才真正懂得轮子为何这样设计。