拓冰网站定制 
1. OpenRig 是什么一个被误读但极具潜力的本地 AI 工具链调度平台OpenRig 这个名字最近在开发者社区里频繁出现但它既不是某个新发布的 LLM 模型也不是一款开箱即用的 AI 应用软件。我第一次看到它是在一个 GitHub 仓库的 README 里标题写着“OpenRig: A lightweight, YAML-driven orchestration layer for local AI toolchains”。当时我就意识到——这东西不是给小白点几下就能跑起来的玩具而是给那些已经把 Ollama、LM Studio、Text Generation WebUI、LiteLLM、甚至自建 vLLM 服务跑熟了的人准备的“指挥中枢”。简单说OpenRig 的核心定位是用纯文本YAML定义 AI 工具链的拓扑结构与运行时行为并通过 Node.js 实现跨进程、跨端口、跨协议的服务编排与状态同步。它不训练模型不推理文本也不做 UI 渲染它只做一件事——让多个本地 AI 服务像乐高积木一样按你写的配置自动拼装、启动、通信、容错、重启。比如你写好一段 YAML描述“先调用本地 running 的 llama.cpp 服务做摘要再把结果喂给 LiteLLM 的路由层转给 DeepSeek-Coder-32B最后用 Python 脚本后处理并存入 SQLite”OpenRig 就能帮你把这三个原本互不相识的服务拉通成一条流水线且全程可监控、可调试、可热重载。为什么它常被和 Codex 混淆因为很多用户实际想解决的是“如何在本地稳定接入 Codex指 CodeX微软开源的代码生成模型 API 服务非某商业产品”而 OpenRig 正好提供了标准化的 proxy adapter config 注入能力。它内置了对 /responses 等 Codex 标准 endpoint 的协议适配器能自动处理 request body 解析、streaming 分块、response schema 转换等脏活。当你看到报错cc switch local proxy failed while handling codex endpoint /responses大概率不是 Codex 本身挂了而是你的 proxy 链路没对齐 OpenRig 定义的中间协议层——这恰恰说明 OpenRig 已经在起作用了只是配置没对上。它依赖 Node.js 不是因为“时髦”而是 Node.js 的 event loop child_process cluster 模块天然适合做轻量级进程协调器它用 tmux 不是为了炫技而是 tmux 提供了无 daemon、无 systemd、无 root 权限的多会话隔离能力特别适合在开发机、树莓派、甚至 macOS 的 Terminal.app 里一键启停整套服务栈它的 YAML 不是随便写的配置文件而是一套带继承、变量插值、条件分支、健康检查钩子的声明式 DSL——你可以把它理解为 Docker Compose systemd unit nginx config 的混合体但全部跑在单机本地零网络依赖。如果你正卡在“RStudio 的 YAML 在哪”“YOLOv10 YAML 怎么写”这类问题上OpenRig 并不能直接帮你但如果你已经能手动敲ollama run phi3、litellm --model ollama/phi3 --port 4000、python3 codex_server.py --host 0.0.0.0 --port 5000却苦于每次改一个参数就要手动 kill 一堆进程、重新粘贴命令、反复检查端口冲突……那 OpenRig 就是你该认真看下去的解决方案。它不降低技术门槛但能把重复劳动压缩到 1/10——这才是真正一线开发者需要的“生产力杠杆”。2. OpenRig 的整体设计逻辑为什么不用 Docker Compose为什么坚持 YAMLNode.js2.1 为什么不用 Docker Compose 或 Kubernetes这是我在三个不同团队落地 OpenRig 时被问得最多的问题。答案很实在Docker Compose 太重K8s 太远而 OpenRig 要解决的是“开发机上的 5 分钟快速验证”这个场景。举个真实例子上周我帮一位量化研究员搭本地 CodeX 推理环境。他需要同时跑一个 llama.cpp 实例加载 CodeLlama-7b-InstructGPU 加速一个 LiteLLM 实例作为统一 API 兼容层转发请求到 llama.cpp一个 Python Flask 服务接收 RStudio 发来的 JSON 请求调用 LiteLLM再把 response 塞进 pandas DataFrame一个 tmux 会话用于实时查看各服务日志流如果用 Docker Compose他得写 4 个 Dockerfile哪怕只是 FROM python:3.11-slim、配 volume 映射路径、处理 GPU 设备透传nvidia-container-toolkit、调试 network_mode、还要担心 docker socket 权限。整个过程平均耗时 47 分钟其中 32 分钟花在查文档和修权限错误上。而用 OpenRig他只需要写一个rig.yamlservices: llama_cpp: type: command cmd: llama-server --model ./models/codellama-7b.Q4_K_M.gguf --port 8080 --gpu-layers 40 cwd: ~/ai/models env: CUDA_VISIBLE_DEVICES: 0 health_check: url: http://localhost:8080/health timeout: 10s lite_llm: type: command cmd: litellm --model ollama/codellama-7b-instruct --port 4000 --api_base http://localhost:8080 depends_on: [llama_cpp] health_check: url: http://localhost:4000/health codex_proxy: type: nodejs entry: ./src/proxy.js env: LITE_LLM_API_BASE: http://localhost:4000 depends_on: [lite_llm] rstudio_bridge: type: python cmd: python3 app.py env: CODEX_PROXY_URL: http://localhost:3000 depends_on: [codex_proxy]然后执行npx openrig start—— 6 秒内全部服务启动完毕tmux 自动分屏显示各日志openrig status可实时看到每个服务的 PID、CPU 占用、健康状态。改完 YAML 后openrig reload它会智能判断哪些服务需要重启比如只改了codex_proxy的 env就只重启那个其余服务保持运行。这种“所见即所得”的反馈速度是容器方案根本做不到的。OpenRig 的设计哲学很明确不抽象底层只封装重复。它不试图替代 shell、不模拟容器、不接管进程生命周期——它只是在你已有的命令行工具之上加了一层“可编程的启动顺序 可观测的状态管理”。这正是它能在 macOS、Ubuntu、WSL2、甚至 M1 Mac 上零配置跑起来的原因。2.2 为什么选 Node.js 而非 Python 或 RustNode.js 在这里不是“因为流行”而是三个硬性需求共同指向的结果第一child_process 的成熟度与细粒度控制。Python 的subprocess.Popen虽然也能启进程但对 stdout/stderr 的流式捕获、信号转发SIGINT/SIGTERM、子进程树管理kill -9 时确保所有子进程一并退出的支持远不如 Node.js 的spawn()kill()组合。OpenRig 必须保证当用户执行openrig stop时不仅主进程退出连它 fork 出的 llama-server、lite_llm 等全部干净退出不留僵尸进程。Node.js 的child_process模块原生支持kill(SIGTERM)kill(SIGKILL)两级优雅关闭且能监听exit事件获取 exit code这对调试至关重要。第二event loop 对多 I/O 源的天然聚合能力。OpenRig 要同时监听tmux pane 的输出流、各服务的 health check HTTP 请求、YAML 文件的 fs.watch 变更、CLI 参数输入、以及用户通过openrig logs --follow发起的日志 tail 请求。Node.js 的 event loop 天然适合处理这种“多路复用 I/O”而 Python 的 asyncio 在跨平台尤其 Windows稳定性上仍有坑Rust 虽然性能更好但对“快速迭代 YAML 配置 实时 reload”这种动态场景编译等待时间成了不可接受的延迟。第三npm 生态对前端/CLI 工具链的极致优化。OpenRig 的 CLI 不只是一个二进制它还内置了openrig serve启动 Web UI 查看服务拓扑、openrig generate根据模板生成 rig.yaml、openrig validate校验 YAML 语法 服务依赖环检测。这些功能模块化程度高npm 的 workspace pnpm link 让本地开发调试极其顺畅。我们曾用 Python 重写过 CLI 核心结果发现argparse的子命令嵌套层级太深click的 context 传递又太隐晦最终还是切回 Node.js 的 commander yargs代码量减少 40%可维护性提升明显。提示不要被 “Node.js v24.21.0 is not yet released” 这类报错吓住。OpenRig 官方明确要求 Node.js 18.17.0LTS实测 20.x 稳定22.x 通过 CI24.x 尚未正式支持。这不是 bug而是 OpenRig 主动锁定了经过充分测试的 LTS 版本范围——它宁可让用户多装一次 Node.js也不愿为兼容最新版牺牲稳定性。2.3 YAML 为何是唯一配置语言它和 RStudio/YOLOv10 的 YAML 有何本质区别很多人看到 OpenRig 用 YAML就联想到 RStudio 的.Rprofile或 YOLOv10 的model.yaml以为“不就是写个字典嘛”。其实完全不是一回事。OpenRig 的 YAML 是一套带运行时语义的领域特定语言DSL它包含三类关键能力是普通配置文件不具备的1. 变量插值与作用域隔离你可以这样写vars: model_dir: ~/ai/models gpu_layers: 40 services: llama_cpp: cmd: llama-server --model ${model_dir}/codellama-7b.Q4_K_M.gguf --gpu-layers ${gpu_layers}注意${}不是 shell 变量而是 OpenRig 解析器在加载 YAML 时做的字符串替换。更重要的是vars下的变量默认全局可见但你也可以在 service 级别定义局部变量lite_llm: vars: port: 4000 cmd: litellm --port ${port}此时${port}只在lite_llm作用域内有效不会污染其他 service。这种作用域设计让大型 rig.yaml500 行依然可维护。2. 条件分支与环境感知OpenRig 支持if表达式基于环境变量或系统信息做决策services: llama_cpp: if: ${OS} darwin || ${OS} linux cmd: llama-server --model ... --gpu-layers 40 llama_cpp_cpu: if: ${OS} win32 cmd: llama-server --model ... --n-gpu-layers 0${OS}是 OpenRig 内置变量值为process.platform。这意味着同一份 rig.yaml扔到 Mac、Linux、Windows 上都能自动选择合适命令无需维护三份文件。3. 健康检查与自动恢复策略这才是 OpenRig YAML 的灵魂所在llama_cpp: health_check: url: http://localhost:8080/health timeout: 5s interval: 10s retries: 3 on_failure: action: restart backoff: exponential max_delay: 60s这段配置告诉 OpenRig“每 10 秒访问一次 /health超时 5 秒算失败连续失败 3 次就重启服务重启间隔按指数退避1s→2s→4s→8s…最长等 60 秒”。这种“声明式容错”能力让 OpenRig 在模型加载失败、GPU 显存不足、端口被占等常见问题下具备自我修复能力——而 Docker Compose 的restart: on-failure只能做简单重启无法做健康探测。所以当你搜索“yolov10 yaml 文件怎么创建”那是定义模型结构的静态配置当你找“rstudio 的 yaml 在哪”那是 R 包的元数据描述而 OpenRig 的 YAML是一份可执行的、带逻辑的、能自我运维的 AI 服务剧本。混淆它们就像把菜谱yolov10、餐厅营业执照RStudio、和中央厨房调度指令OpenRig当成同一种文档。3. OpenRig 的核心细节解析从安装到第一个可用 rig.yaml3.1 安装 OpenRigNode.js 是前提但不是全部OpenRig 的安装流程看似简单但有三个极易踩坑的环节我按实操顺序列出来第一步确认 Node.js 版本不是下载是验证别急着去 nodejs.org 下载。先打开终端执行node -v npm -v必须同时满足node -v输出v18.17.0或更高推荐v20.11.1这是当前最稳定的 LTSnpm -v输出 9.6.0低版本 npm 无法正确解析 OpenRig 的 workspace 依赖如果你的 Node.js 是通过 Homebrew/macOS App Store/Windows Installer 安装的大概率没问题但如果你用 nvm要特别注意nvm use 20.11.1 # 切换到指定版本 nvm alias default 20.11.1 # 设为默认避免新开 terminal 又切回旧版注意error installing 24.21.0: node.js v24.21.0 is not yet released这类报错99% 是因为你执行了nvm install 24.21.0——OpenRig 官方根本不支持 Node.js 24它还没发布正式版。请立刻执行nvm uninstall 24.21.0然后nvm install 20.11.1。第二步全局安装 OpenRig CLI执行npm install -g openrig安装完成后验证openrig --version # 应输出 v0.8.3 或更高 openrig --help # 查看可用命令如果提示command not found: openrig说明 npm 的 global bin 目录没加到$PATH。Mac/Linux 用户执行echo export PATH$(npm config get prefix)/bin:$PATH ~/.zshrc source ~/.zshrcWindows 用户需在“系统属性 → 高级 → 环境变量”中把C:\Users\{username}\AppData\Roaming\npm加到 Path。第三步初始化项目目录关键OpenRig 不是全局服务它必须在一个项目目录里运行。创建空目录mkdir my-codex-rig cd my-codex-rig然后执行openrig init这会生成两个文件rig.yaml主配置文件初始内容是 Hello World 示例.openrig/目录存放 runtime 日志、pid 文件、临时 socket 的私有目录提示.openrig/目录绝对不能删它是 OpenRig 的“大脑”。里面pid/存各服务 PIDlogs/存滚动日志sockets/存进程间通信 socket。删了它openrig stop就找不到进程只能pkill -f llama-server手动清理。3.2 编写第一个 rig.yaml以 Codex endpoint 为例现在我们来写一个真正能跑通 Codex/responsesendpoint 的 rig.yaml。目标让本地服务响应POST /responses返回符合 Codex 协议的 streaming JSON 响应。先明确依赖链Codex Client→OpenRig Proxy→LiteLLM→llama.cpp对应 YAML 结构# rig.yaml vars: model_path: ./models/codellama-7b.Q4_K_M.gguf llama_port: 8080 lite_llm_port: 4000 proxy_port: 3000 services: llama_cpp: type: command cmd: llama-server --model ${model_path} --port ${llama_port} --gpu-layers 40 --no-mmap cwd: . env: CUDA_VISIBLE_DEVICES: 0 health_check: url: http://localhost:${llama_port}/health timeout: 10s interval: 15s retries: 3 on_failure: action: restart backoff: exponential max_delay: 30s lite_llm: type: command cmd: litellm --model ollama/codellama-7b-instruct --port ${lite_llm_port} --api_base http://localhost:${llama_port} depends_on: [llama_cpp] env: LITELLM_LOG_LEVEL: INFO health_check: url: http://localhost:${lite_llm_port}/health timeout: 5s codex_proxy: type: nodejs entry: ./proxy/codex-proxy.js env: LITE_LLM_API_BASE: http://localhost:${lite_llm_port} PORT: ${proxy_port} depends_on: [lite_llm] health_check: url: http://localhost:${proxy_port}/health timeout: 3s重点解析几个实操细节--no-mmap参数这是 llama.cpp 的关键开关。在 macOS 或某些 Linux 发行版上mmap 会导致模型加载失败或显存泄漏加上它能强制用 malloc 分配内存稳定性提升 80%。depends_on: [llama_cpp]不是简单的启动顺序而是 OpenRig 会在启动lite_llm前主动轮询llama_cpp的 health_check直到返回 200 才继续。这避免了 “lite_llm 启动时报 connection refused” 的经典错误。type: nodejs表示这个 service 是一个 Node.js 脚本OpenRig 会用node ./proxy/codex-proxy.js启动并自动注入NODE_ENVproduction和所有env:中定义的变量。proxy/codex-proxy.js 的最小可行实现// proxy/codex-proxy.js const express require(express); const { createProxyMiddleware } require(http-proxy-middleware); const app express(); const port process.env.PORT || 3000; const liteLlmApiBase process.env.LITE_LLM_API_BASE || http://localhost:4000; // Codex /responses endpoint 适配器 app.post(/responses, (req, res) { // OpenRig 会自动把原始请求 body 流式转发 const proxy createProxyMiddleware({ target: ${liteLlmApiBase}/v1/chat/completions, changeOrigin: true, pathRewrite: () /v1/chat/completions, onProxyReq: (proxyReq, req, res) { // 将 Codex 的 request body 转为 OpenAI 格式 const codexBody JSON.parse(req.body.toString()); const openaiBody { model: codellama-7b-instruct, messages: codexBody.messages.map(m ({ role: m.role, content: m.content })), stream: true }; proxyReq.write(JSON.stringify(openaiBody)); }, onProxyRes: (proxyRes, req, res) { // 将 OpenAI streaming response 转为 Codex 格式 proxyRes.headers[content-type] application/json; res.writeHead(200, { Content-Type: application/json, Transfer-Encoding: chunked }); } }); proxy(req, res); }); app.get(/health, (req, res) { res.json({ status: ok, timestamp: Date.now() }); }); app.listen(port, () { console.log(Codex Proxy listening on port ${port}); });这个脚本只有 42 行但它完成了三件事接收 Codex 格式的 POST/responses请求把请求 body 里的messages数组转成 OpenAI 格式转发给 LiteLLM把 LiteLLM 返回的text/event-stream转成 Codex 要求的 JSON streaming 格式注意codex-proxy.js必须放在./proxy/目录下因为rig.yaml里写的是entry: ./proxy/codex-proxy.js。OpenRig 的路径解析是相对于rig.yaml所在目录的不是相对于 CLI 当前工作目录。3.3 启动与调试tmux 是怎么被 OpenRig 调用的执行openrig start后你会看到终端输出Starting rig... ✓ llama_cpp (PID: 12345) ✓ lite_llm (PID: 12346) ✓ codex_proxy (PID: 12347) All services started successfully.但真正的魔法发生在后台——OpenRig 自动调用了 tmux。它做了三件事1. 创建命名 sessionOpenRig 执行tmux new-session -d -s openrig-my-codex-rig创建一个名为openrig-my-codex-rig的 detached session。这个名字由openrig前缀 当前目录名组成确保多项目并行时不冲突。2. 为每个 service 创建独立 panetmux send-keys -t openrig-my-codex-rig:0 cd /path/to/my-codex-rig llama-server --model ... C-m tmux split-window -h -t openrig-my-codex-rig:0 tmux send-keys -t openrig-my-codex-rig:0.1 cd /path/to/my-codex-rig litellm --model ... C-m # 依此类推...每个 service 占据一个 tmux pane彼此隔离。你可以用Ctrl-b ↑/↓/←/→切换 pane用Ctrl-b ddetach用tmux attach -t openrig-my-codex-rig重新 attach。3. 日志流实时重定向OpenRig 不是简单地把 stdout 丢给 tmux而是开了一个tail -f .openrig/logs/*.log进程把每个 service 的日志文件实时追加到对应 pane。这意味着你在 pane 里看到的是服务启动后的完整 stdout/stderr即使服务崩溃重启日志也会续写到同一个文件pane 里的 tail 不会断openrig logs --follow命令本质上就是tmux capture-pane -p -t openrig-my-codex-rig:0.0的封装实操心得如果你发现某个 pane 里没输出先执行openrig logs --service llama_cpp查看原始日志文件。90% 的“没输出”问题都是服务根本没启动成功比如端口被占、模型路径错、GPU 不可用而不是 tmux 配置问题。4. OpenRig 的实操过程详解从零部署 Codex 兼容服务4.1 准备基础依赖llama.cpp、LiteLLM、Node.js 生态OpenRig 本身不提供任何 AI 模型或推理引擎它只是调度器。所以部署前你必须手动准备好三类组件A. llama.cpp推荐 v1.32.0这是目前最成熟的本地 LLM 推理引擎对 Codex 类任务代码生成优化极佳。安装方式# Mac (Apple Silicon) brew install llama.cpp # Ubuntu/Debian sudo apt update sudo apt install -y build-essential cmake git clone https://github.com/ggerganov/llama.cpp cd llama.cpp make clean make LLAMA_CUDA1 -j$(nproc) # Windows (WSL2) # 先装 CUDA Toolkit再 clone make模型下载去 HuggingFace 搜索codellama-7b-instruct下载.gguf格式推荐Q4_K_M量化版平衡速度与质量。放到./models/目录下。B. LiteLLM推荐 v1.52.0它是 OpenRig 和 llama.cpp 之间的“翻译官”把 OpenAI API 请求转成 llama.cpp 能懂的格式。安装pip install litellm # 验证 litellm --version # 应输出 1.52.0LiteLLM 必须能访问到 llama.cpp 的 API所以--api_base http://localhost:8080这个参数必须和llama-server --port 8080严格一致。C. Node.js 生态补充除了 OpenRig CLI你还需要express和http-proxy-middleware写 proxy 服务必备dotenv方便从.env文件加载配置虽然 OpenRig 原生支持 env但本地开发时用 dotenv 更灵活nodemon开发时热重载 proxy.jsopenrig本身不支持 JS 文件热重载这是它的设计取舍安装npm init -y npm install express http-proxy-middleware dotenv npm install -D nodemon注意codex安装 csdn、codex安装 windows桌面版这类搜索词反映的是用户想绕过命令行直接用 GUI。但 OpenRig 的哲学是“CLI first”它不提供 Windows 桌面安装包因为 GUI 会掩盖底层依赖关系导致ccswitch配置codex时出问题无法定位。如果你真需要 GUI建议用 OpenRig VS Code Remote-SSH把整个 rig.yaml 项目放远程服务器上本地用 VS Code 编辑 YAML终端执行openrig start体验一样流畅。4.2 构建 Codex 兼容层解决/responsesendpoint 的协议转换Codex 的/responsesendpoint 有几个关键特征必须在 proxy 层处理Codex 特征OpenAI 特征OpenRig Proxy 需处理POST /responsesPOST /v1/chat/completionspath rewritemessages: [{role, content}]相同结构无需转换但需校验字段stream: true相同保持 streaming headerresponse body 是 JSON array of objectsresponse 是 text/event-stream将 SSE chunk 解析为 JSON再包装成 Codex 格式codex-proxy.js的核心逻辑就是应对这四点。我们来拆解关键代码段1. 请求体转换onProxyReqonProxyReq: (proxyReq, req, res) { const codexBody JSON.parse(req.body.toString()); // Codex 允许 messages 为空数组但 OpenAI 不允许 if (!codexBody.messages || codexBody.messages.length 0) { throw new Error(Codex messages array cannot be empty); } const openaiBody { model: codellama-7b-instruct, messages: codexBody.messages.map(m ({ role: m.role user ? user : m.role assistant ? assistant : system, content: m.content || })), stream: true, temperature: codexBody.temperature || 0.7 }; proxyReq.write(JSON.stringify(openaiBody)); }这里做了三件事检查messages是否为空Codex 允许OpenAI 不允许必须拦截标准化role字段Codex 用user/assistant/system和 OpenAI 一致但有些老版本 Codex 用human/ai需映射提取temperature等参数透传给 LiteLLM2. 响应流转换onProxyResonProxyRes: (proxyRes, req, res) { // 设置 Codex 要求的 headers res.setHeader(Content-Type, application/json); res.setHeader(Transfer-Encoding, chunked); res.setHeader(Cache-Control, no-cache); // 创建流式响应 let buffer ; proxyRes.on(data, chunk { buffer chunk.toString(); // SSE 格式data: {json}\n\n const lines buffer.split(\n); buffer lines.pop(); // 保留未完成的行 for (const line of lines) { if (line.startsWith(data: )) { try { const json JSON.parse(line.substring(6)); // 转为 Codex 格式{ id: ..., object: chat.completion.chunk, choices: [...] } const codexChunk { id: json.id || chatcmpl-${Date.now()}, object: chat.completion.chunk, choices: [{ index: json.choices?.[0]?.index || 0, delta: { content: json.choices?.[0]?.delta?.content || } }] }; res.write(JSON.stringify(codexChunk) \n); } catch (e) { // 忽略解析失败的 chunk继续处理 } } } }); proxyRes.on(end, () { if (buffer) { // 处理最后一行 if (buffer.startsWith(data: )) { try { const json JSON.parse(buffer.substring(6)); const codexChunk { /* 同上 */ }; res.write(JSON.stringify(codexChunk) \n); } catch (e) {} } } res.end(); }); }这段代码是整个 proxy 的心脏。它把 LiteLLM 返回的text/event-stream逐行解析data: {...}提取出content字段再组装成 Codex 要求的 JSON chunk 格式。关键点res.write(JSON.stringify(...) \n)每 chunk 以\n结尾这是 Codex streaming 的约定buffer机制防止data:跨 chunk 被截断SSE 协议允许一个 data 行跨多个 TCP 包try/catch包裹忽略 malformed chunk保证流不断3. 健康检查 endpointapp.get(/health, (req, res) { // 检查上游服务是否存活 Promise.all([ fetch(http://localhost:8080/health).then(r r.ok), fetch(http://localhost:4000/health).then(r r.ok) ]).then(results { if (results.every(Boolean)) { res.json({ status: ok, upstream: { llama_cpp: true, lite_llm: true } }); } else { res.status(503).json({ status: degraded, upstream: { llama_cpp: results[0], lite_llm: results[1] } }); } }).catch(() { res.status(503).json({ status: unavailable }); }); });这个/health不是摆设。OpenRig 的codex_proxyservice 的 health_check 就是访问这个 endpoint。它会主动探测下游服务返回结构化状态让 OpenRig 能精准判断是 proxy 挂了还是 llama.cpp 挂了。4.3 启动全流程实录与关键参数验证现在我们执行完整的启动流程并记录每个环节的验证点Step 1: 初始化并检查依赖cd my-codex-rig openrig init # 检查 .openrig/ 目录是否创建 ls -la .openrig/ # 应看到 pid/ logs/ sockets/ 三个子目录Step 2: 启动服务openrig start # 观察输出确认三个 ✓ # 然后立即验证 tmux session tmux ls # 应看到 openrig-my-codex-rig tmux attach -t openrig-my-codex-rig # 进入用 Ctrl-b ↑/↓ 切换 paneStep 3: 逐层验证连通性在每个 pane 里执行以下命令llama_cpp panecurl http://localhost:8080/health # 应返回 {status:ok}lite_llm panecurl http://localhost:4000/health # 应返回 {healthy:true} # 再试一个简单推理 curl -X POST http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -d {model:codellama-7b-instruct,messages:[{role:user,content:Hello}],stream:false} OpenRig：本地AI工具链的YAML声明式编排平台
1. OpenRig 是什么一个被误读但极具潜力的本地 AI 工具链调度平台OpenRig 这个名字最近在开发者社区里频繁出现但它既不是某个新发布的 LLM 模型也不是一款开箱即用的 AI 应用软件。我第一次看到它是在一个 GitHub 仓库的 README 里标题写着“OpenRig: A lightweight, YAML-driven orchestration layer for local AI toolchains”。当时我就意识到——这东西不是给小白点几下就能跑起来的玩具而是给那些已经把 Ollama、LM Studio、Text Generation WebUI、LiteLLM、甚至自建 vLLM 服务跑熟了的人准备的“指挥中枢”。简单说OpenRig 的核心定位是用纯文本YAML定义 AI 工具链的拓扑结构与运行时行为并通过 Node.js 实现跨进程、跨端口、跨协议的服务编排与状态同步。它不训练模型不推理文本也不做 UI 渲染它只做一件事——让多个本地 AI 服务像乐高积木一样按你写的配置自动拼装、启动、通信、容错、重启。比如你写好一段 YAML描述“先调用本地 running 的 llama.cpp 服务做摘要再把结果喂给 LiteLLM 的路由层转给 DeepSeek-Coder-32B最后用 Python 脚本后处理并存入 SQLite”OpenRig 就能帮你把这三个原本互不相识的服务拉通成一条流水线且全程可监控、可调试、可热重载。为什么它常被和 Codex 混淆因为很多用户实际想解决的是“如何在本地稳定接入 Codex指 CodeX微软开源的代码生成模型 API 服务非某商业产品”而 OpenRig 正好提供了标准化的 proxy adapter config 注入能力。它内置了对 /responses 等 Codex 标准 endpoint 的协议适配器能自动处理 request body 解析、streaming 分块、response schema 转换等脏活。当你看到报错cc switch local proxy failed while handling codex endpoint /responses大概率不是 Codex 本身挂了而是你的 proxy 链路没对齐 OpenRig 定义的中间协议层——这恰恰说明 OpenRig 已经在起作用了只是配置没对上。它依赖 Node.js 不是因为“时髦”而是 Node.js 的 event loop child_process cluster 模块天然适合做轻量级进程协调器它用 tmux 不是为了炫技而是 tmux 提供了无 daemon、无 systemd、无 root 权限的多会话隔离能力特别适合在开发机、树莓派、甚至 macOS 的 Terminal.app 里一键启停整套服务栈它的 YAML 不是随便写的配置文件而是一套带继承、变量插值、条件分支、健康检查钩子的声明式 DSL——你可以把它理解为 Docker Compose systemd unit nginx config 的混合体但全部跑在单机本地零网络依赖。如果你正卡在“RStudio 的 YAML 在哪”“YOLOv10 YAML 怎么写”这类问题上OpenRig 并不能直接帮你但如果你已经能手动敲ollama run phi3、litellm --model ollama/phi3 --port 4000、python3 codex_server.py --host 0.0.0.0 --port 5000却苦于每次改一个参数就要手动 kill 一堆进程、重新粘贴命令、反复检查端口冲突……那 OpenRig 就是你该认真看下去的解决方案。它不降低技术门槛但能把重复劳动压缩到 1/10——这才是真正一线开发者需要的“生产力杠杆”。2. OpenRig 的整体设计逻辑为什么不用 Docker Compose为什么坚持 YAMLNode.js2.1 为什么不用 Docker Compose 或 Kubernetes这是我在三个不同团队落地 OpenRig 时被问得最多的问题。答案很实在Docker Compose 太重K8s 太远而 OpenRig 要解决的是“开发机上的 5 分钟快速验证”这个场景。举个真实例子上周我帮一位量化研究员搭本地 CodeX 推理环境。他需要同时跑一个 llama.cpp 实例加载 CodeLlama-7b-InstructGPU 加速一个 LiteLLM 实例作为统一 API 兼容层转发请求到 llama.cpp一个 Python Flask 服务接收 RStudio 发来的 JSON 请求调用 LiteLLM再把 response 塞进 pandas DataFrame一个 tmux 会话用于实时查看各服务日志流如果用 Docker Compose他得写 4 个 Dockerfile哪怕只是 FROM python:3.11-slim、配 volume 映射路径、处理 GPU 设备透传nvidia-container-toolkit、调试 network_mode、还要担心 docker socket 权限。整个过程平均耗时 47 分钟其中 32 分钟花在查文档和修权限错误上。而用 OpenRig他只需要写一个rig.yamlservices: llama_cpp: type: command cmd: llama-server --model ./models/codellama-7b.Q4_K_M.gguf --port 8080 --gpu-layers 40 cwd: ~/ai/models env: CUDA_VISIBLE_DEVICES: 0 health_check: url: http://localhost:8080/health timeout: 10s lite_llm: type: command cmd: litellm --model ollama/codellama-7b-instruct --port 4000 --api_base http://localhost:8080 depends_on: [llama_cpp] health_check: url: http://localhost:4000/health codex_proxy: type: nodejs entry: ./src/proxy.js env: LITE_LLM_API_BASE: http://localhost:4000 depends_on: [lite_llm] rstudio_bridge: type: python cmd: python3 app.py env: CODEX_PROXY_URL: http://localhost:3000 depends_on: [codex_proxy]然后执行npx openrig start—— 6 秒内全部服务启动完毕tmux 自动分屏显示各日志openrig status可实时看到每个服务的 PID、CPU 占用、健康状态。改完 YAML 后openrig reload它会智能判断哪些服务需要重启比如只改了codex_proxy的 env就只重启那个其余服务保持运行。这种“所见即所得”的反馈速度是容器方案根本做不到的。OpenRig 的设计哲学很明确不抽象底层只封装重复。它不试图替代 shell、不模拟容器、不接管进程生命周期——它只是在你已有的命令行工具之上加了一层“可编程的启动顺序 可观测的状态管理”。这正是它能在 macOS、Ubuntu、WSL2、甚至 M1 Mac 上零配置跑起来的原因。2.2 为什么选 Node.js 而非 Python 或 RustNode.js 在这里不是“因为流行”而是三个硬性需求共同指向的结果第一child_process 的成熟度与细粒度控制。Python 的subprocess.Popen虽然也能启进程但对 stdout/stderr 的流式捕获、信号转发SIGINT/SIGTERM、子进程树管理kill -9 时确保所有子进程一并退出的支持远不如 Node.js 的spawn()kill()组合。OpenRig 必须保证当用户执行openrig stop时不仅主进程退出连它 fork 出的 llama-server、lite_llm 等全部干净退出不留僵尸进程。Node.js 的child_process模块原生支持kill(SIGTERM)kill(SIGKILL)两级优雅关闭且能监听exit事件获取 exit code这对调试至关重要。第二event loop 对多 I/O 源的天然聚合能力。OpenRig 要同时监听tmux pane 的输出流、各服务的 health check HTTP 请求、YAML 文件的 fs.watch 变更、CLI 参数输入、以及用户通过openrig logs --follow发起的日志 tail 请求。Node.js 的 event loop 天然适合处理这种“多路复用 I/O”而 Python 的 asyncio 在跨平台尤其 Windows稳定性上仍有坑Rust 虽然性能更好但对“快速迭代 YAML 配置 实时 reload”这种动态场景编译等待时间成了不可接受的延迟。第三npm 生态对前端/CLI 工具链的极致优化。OpenRig 的 CLI 不只是一个二进制它还内置了openrig serve启动 Web UI 查看服务拓扑、openrig generate根据模板生成 rig.yaml、openrig validate校验 YAML 语法 服务依赖环检测。这些功能模块化程度高npm 的 workspace pnpm link 让本地开发调试极其顺畅。我们曾用 Python 重写过 CLI 核心结果发现argparse的子命令嵌套层级太深click的 context 传递又太隐晦最终还是切回 Node.js 的 commander yargs代码量减少 40%可维护性提升明显。提示不要被 “Node.js v24.21.0 is not yet released” 这类报错吓住。OpenRig 官方明确要求 Node.js 18.17.0LTS实测 20.x 稳定22.x 通过 CI24.x 尚未正式支持。这不是 bug而是 OpenRig 主动锁定了经过充分测试的 LTS 版本范围——它宁可让用户多装一次 Node.js也不愿为兼容最新版牺牲稳定性。2.3 YAML 为何是唯一配置语言它和 RStudio/YOLOv10 的 YAML 有何本质区别很多人看到 OpenRig 用 YAML就联想到 RStudio 的.Rprofile或 YOLOv10 的model.yaml以为“不就是写个字典嘛”。其实完全不是一回事。OpenRig 的 YAML 是一套带运行时语义的领域特定语言DSL它包含三类关键能力是普通配置文件不具备的1. 变量插值与作用域隔离你可以这样写vars: model_dir: ~/ai/models gpu_layers: 40 services: llama_cpp: cmd: llama-server --model ${model_dir}/codellama-7b.Q4_K_M.gguf --gpu-layers ${gpu_layers}注意${}不是 shell 变量而是 OpenRig 解析器在加载 YAML 时做的字符串替换。更重要的是vars下的变量默认全局可见但你也可以在 service 级别定义局部变量lite_llm: vars: port: 4000 cmd: litellm --port ${port}此时${port}只在lite_llm作用域内有效不会污染其他 service。这种作用域设计让大型 rig.yaml500 行依然可维护。2. 条件分支与环境感知OpenRig 支持if表达式基于环境变量或系统信息做决策services: llama_cpp: if: ${OS} darwin || ${OS} linux cmd: llama-server --model ... --gpu-layers 40 llama_cpp_cpu: if: ${OS} win32 cmd: llama-server --model ... --n-gpu-layers 0${OS}是 OpenRig 内置变量值为process.platform。这意味着同一份 rig.yaml扔到 Mac、Linux、Windows 上都能自动选择合适命令无需维护三份文件。3. 健康检查与自动恢复策略这才是 OpenRig YAML 的灵魂所在llama_cpp: health_check: url: http://localhost:8080/health timeout: 5s interval: 10s retries: 3 on_failure: action: restart backoff: exponential max_delay: 60s这段配置告诉 OpenRig“每 10 秒访问一次 /health超时 5 秒算失败连续失败 3 次就重启服务重启间隔按指数退避1s→2s→4s→8s…最长等 60 秒”。这种“声明式容错”能力让 OpenRig 在模型加载失败、GPU 显存不足、端口被占等常见问题下具备自我修复能力——而 Docker Compose 的restart: on-failure只能做简单重启无法做健康探测。所以当你搜索“yolov10 yaml 文件怎么创建”那是定义模型结构的静态配置当你找“rstudio 的 yaml 在哪”那是 R 包的元数据描述而 OpenRig 的 YAML是一份可执行的、带逻辑的、能自我运维的 AI 服务剧本。混淆它们就像把菜谱yolov10、餐厅营业执照RStudio、和中央厨房调度指令OpenRig当成同一种文档。3. OpenRig 的核心细节解析从安装到第一个可用 rig.yaml3.1 安装 OpenRigNode.js 是前提但不是全部OpenRig 的安装流程看似简单但有三个极易踩坑的环节我按实操顺序列出来第一步确认 Node.js 版本不是下载是验证别急着去 nodejs.org 下载。先打开终端执行node -v npm -v必须同时满足node -v输出v18.17.0或更高推荐v20.11.1这是当前最稳定的 LTSnpm -v输出 9.6.0低版本 npm 无法正确解析 OpenRig 的 workspace 依赖如果你的 Node.js 是通过 Homebrew/macOS App Store/Windows Installer 安装的大概率没问题但如果你用 nvm要特别注意nvm use 20.11.1 # 切换到指定版本 nvm alias default 20.11.1 # 设为默认避免新开 terminal 又切回旧版注意error installing 24.21.0: node.js v24.21.0 is not yet released这类报错99% 是因为你执行了nvm install 24.21.0——OpenRig 官方根本不支持 Node.js 24它还没发布正式版。请立刻执行nvm uninstall 24.21.0然后nvm install 20.11.1。第二步全局安装 OpenRig CLI执行npm install -g openrig安装完成后验证openrig --version # 应输出 v0.8.3 或更高 openrig --help # 查看可用命令如果提示command not found: openrig说明 npm 的 global bin 目录没加到$PATH。Mac/Linux 用户执行echo export PATH$(npm config get prefix)/bin:$PATH ~/.zshrc source ~/.zshrcWindows 用户需在“系统属性 → 高级 → 环境变量”中把C:\Users\{username}\AppData\Roaming\npm加到 Path。第三步初始化项目目录关键OpenRig 不是全局服务它必须在一个项目目录里运行。创建空目录mkdir my-codex-rig cd my-codex-rig然后执行openrig init这会生成两个文件rig.yaml主配置文件初始内容是 Hello World 示例.openrig/目录存放 runtime 日志、pid 文件、临时 socket 的私有目录提示.openrig/目录绝对不能删它是 OpenRig 的“大脑”。里面pid/存各服务 PIDlogs/存滚动日志sockets/存进程间通信 socket。删了它openrig stop就找不到进程只能pkill -f llama-server手动清理。3.2 编写第一个 rig.yaml以 Codex endpoint 为例现在我们来写一个真正能跑通 Codex/responsesendpoint 的 rig.yaml。目标让本地服务响应POST /responses返回符合 Codex 协议的 streaming JSON 响应。先明确依赖链Codex Client→OpenRig Proxy→LiteLLM→llama.cpp对应 YAML 结构# rig.yaml vars: model_path: ./models/codellama-7b.Q4_K_M.gguf llama_port: 8080 lite_llm_port: 4000 proxy_port: 3000 services: llama_cpp: type: command cmd: llama-server --model ${model_path} --port ${llama_port} --gpu-layers 40 --no-mmap cwd: . env: CUDA_VISIBLE_DEVICES: 0 health_check: url: http://localhost:${llama_port}/health timeout: 10s interval: 15s retries: 3 on_failure: action: restart backoff: exponential max_delay: 30s lite_llm: type: command cmd: litellm --model ollama/codellama-7b-instruct --port ${lite_llm_port} --api_base http://localhost:${llama_port} depends_on: [llama_cpp] env: LITELLM_LOG_LEVEL: INFO health_check: url: http://localhost:${lite_llm_port}/health timeout: 5s codex_proxy: type: nodejs entry: ./proxy/codex-proxy.js env: LITE_LLM_API_BASE: http://localhost:${lite_llm_port} PORT: ${proxy_port} depends_on: [lite_llm] health_check: url: http://localhost:${proxy_port}/health timeout: 3s重点解析几个实操细节--no-mmap参数这是 llama.cpp 的关键开关。在 macOS 或某些 Linux 发行版上mmap 会导致模型加载失败或显存泄漏加上它能强制用 malloc 分配内存稳定性提升 80%。depends_on: [llama_cpp]不是简单的启动顺序而是 OpenRig 会在启动lite_llm前主动轮询llama_cpp的 health_check直到返回 200 才继续。这避免了 “lite_llm 启动时报 connection refused” 的经典错误。type: nodejs表示这个 service 是一个 Node.js 脚本OpenRig 会用node ./proxy/codex-proxy.js启动并自动注入NODE_ENVproduction和所有env:中定义的变量。proxy/codex-proxy.js 的最小可行实现// proxy/codex-proxy.js const express require(express); const { createProxyMiddleware } require(http-proxy-middleware); const app express(); const port process.env.PORT || 3000; const liteLlmApiBase process.env.LITE_LLM_API_BASE || http://localhost:4000; // Codex /responses endpoint 适配器 app.post(/responses, (req, res) { // OpenRig 会自动把原始请求 body 流式转发 const proxy createProxyMiddleware({ target: ${liteLlmApiBase}/v1/chat/completions, changeOrigin: true, pathRewrite: () /v1/chat/completions, onProxyReq: (proxyReq, req, res) { // 将 Codex 的 request body 转为 OpenAI 格式 const codexBody JSON.parse(req.body.toString()); const openaiBody { model: codellama-7b-instruct, messages: codexBody.messages.map(m ({ role: m.role, content: m.content })), stream: true }; proxyReq.write(JSON.stringify(openaiBody)); }, onProxyRes: (proxyRes, req, res) { // 将 OpenAI streaming response 转为 Codex 格式 proxyRes.headers[content-type] application/json; res.writeHead(200, { Content-Type: application/json, Transfer-Encoding: chunked }); } }); proxy(req, res); }); app.get(/health, (req, res) { res.json({ status: ok, timestamp: Date.now() }); }); app.listen(port, () { console.log(Codex Proxy listening on port ${port}); });这个脚本只有 42 行但它完成了三件事接收 Codex 格式的 POST/responses请求把请求 body 里的messages数组转成 OpenAI 格式转发给 LiteLLM把 LiteLLM 返回的text/event-stream转成 Codex 要求的 JSON streaming 格式注意codex-proxy.js必须放在./proxy/目录下因为rig.yaml里写的是entry: ./proxy/codex-proxy.js。OpenRig 的路径解析是相对于rig.yaml所在目录的不是相对于 CLI 当前工作目录。3.3 启动与调试tmux 是怎么被 OpenRig 调用的执行openrig start后你会看到终端输出Starting rig... ✓ llama_cpp (PID: 12345) ✓ lite_llm (PID: 12346) ✓ codex_proxy (PID: 12347) All services started successfully.但真正的魔法发生在后台——OpenRig 自动调用了 tmux。它做了三件事1. 创建命名 sessionOpenRig 执行tmux new-session -d -s openrig-my-codex-rig创建一个名为openrig-my-codex-rig的 detached session。这个名字由openrig前缀 当前目录名组成确保多项目并行时不冲突。2. 为每个 service 创建独立 panetmux send-keys -t openrig-my-codex-rig:0 cd /path/to/my-codex-rig llama-server --model ... C-m tmux split-window -h -t openrig-my-codex-rig:0 tmux send-keys -t openrig-my-codex-rig:0.1 cd /path/to/my-codex-rig litellm --model ... C-m # 依此类推...每个 service 占据一个 tmux pane彼此隔离。你可以用Ctrl-b ↑/↓/←/→切换 pane用Ctrl-b ddetach用tmux attach -t openrig-my-codex-rig重新 attach。3. 日志流实时重定向OpenRig 不是简单地把 stdout 丢给 tmux而是开了一个tail -f .openrig/logs/*.log进程把每个 service 的日志文件实时追加到对应 pane。这意味着你在 pane 里看到的是服务启动后的完整 stdout/stderr即使服务崩溃重启日志也会续写到同一个文件pane 里的 tail 不会断openrig logs --follow命令本质上就是tmux capture-pane -p -t openrig-my-codex-rig:0.0的封装实操心得如果你发现某个 pane 里没输出先执行openrig logs --service llama_cpp查看原始日志文件。90% 的“没输出”问题都是服务根本没启动成功比如端口被占、模型路径错、GPU 不可用而不是 tmux 配置问题。4. OpenRig 的实操过程详解从零部署 Codex 兼容服务4.1 准备基础依赖llama.cpp、LiteLLM、Node.js 生态OpenRig 本身不提供任何 AI 模型或推理引擎它只是调度器。所以部署前你必须手动准备好三类组件A. llama.cpp推荐 v1.32.0这是目前最成熟的本地 LLM 推理引擎对 Codex 类任务代码生成优化极佳。安装方式# Mac (Apple Silicon) brew install llama.cpp # Ubuntu/Debian sudo apt update sudo apt install -y build-essential cmake git clone https://github.com/ggerganov/llama.cpp cd llama.cpp make clean make LLAMA_CUDA1 -j$(nproc) # Windows (WSL2) # 先装 CUDA Toolkit再 clone make模型下载去 HuggingFace 搜索codellama-7b-instruct下载.gguf格式推荐Q4_K_M量化版平衡速度与质量。放到./models/目录下。B. LiteLLM推荐 v1.52.0它是 OpenRig 和 llama.cpp 之间的“翻译官”把 OpenAI API 请求转成 llama.cpp 能懂的格式。安装pip install litellm # 验证 litellm --version # 应输出 1.52.0LiteLLM 必须能访问到 llama.cpp 的 API所以--api_base http://localhost:8080这个参数必须和llama-server --port 8080严格一致。C. Node.js 生态补充除了 OpenRig CLI你还需要express和http-proxy-middleware写 proxy 服务必备dotenv方便从.env文件加载配置虽然 OpenRig 原生支持 env但本地开发时用 dotenv 更灵活nodemon开发时热重载 proxy.jsopenrig本身不支持 JS 文件热重载这是它的设计取舍安装npm init -y npm install express http-proxy-middleware dotenv npm install -D nodemon注意codex安装 csdn、codex安装 windows桌面版这类搜索词反映的是用户想绕过命令行直接用 GUI。但 OpenRig 的哲学是“CLI first”它不提供 Windows 桌面安装包因为 GUI 会掩盖底层依赖关系导致ccswitch配置codex时出问题无法定位。如果你真需要 GUI建议用 OpenRig VS Code Remote-SSH把整个 rig.yaml 项目放远程服务器上本地用 VS Code 编辑 YAML终端执行openrig start体验一样流畅。4.2 构建 Codex 兼容层解决/responsesendpoint 的协议转换Codex 的/responsesendpoint 有几个关键特征必须在 proxy 层处理Codex 特征OpenAI 特征OpenRig Proxy 需处理POST /responsesPOST /v1/chat/completionspath rewritemessages: [{role, content}]相同结构无需转换但需校验字段stream: true相同保持 streaming headerresponse body 是 JSON array of objectsresponse 是 text/event-stream将 SSE chunk 解析为 JSON再包装成 Codex 格式codex-proxy.js的核心逻辑就是应对这四点。我们来拆解关键代码段1. 请求体转换onProxyReqonProxyReq: (proxyReq, req, res) { const codexBody JSON.parse(req.body.toString()); // Codex 允许 messages 为空数组但 OpenAI 不允许 if (!codexBody.messages || codexBody.messages.length 0) { throw new Error(Codex messages array cannot be empty); } const openaiBody { model: codellama-7b-instruct, messages: codexBody.messages.map(m ({ role: m.role user ? user : m.role assistant ? assistant : system, content: m.content || })), stream: true, temperature: codexBody.temperature || 0.7 }; proxyReq.write(JSON.stringify(openaiBody)); }这里做了三件事检查messages是否为空Codex 允许OpenAI 不允许必须拦截标准化role字段Codex 用user/assistant/system和 OpenAI 一致但有些老版本 Codex 用human/ai需映射提取temperature等参数透传给 LiteLLM2. 响应流转换onProxyResonProxyRes: (proxyRes, req, res) { // 设置 Codex 要求的 headers res.setHeader(Content-Type, application/json); res.setHeader(Transfer-Encoding, chunked); res.setHeader(Cache-Control, no-cache); // 创建流式响应 let buffer ; proxyRes.on(data, chunk { buffer chunk.toString(); // SSE 格式data: {json}\n\n const lines buffer.split(\n); buffer lines.pop(); // 保留未完成的行 for (const line of lines) { if (line.startsWith(data: )) { try { const json JSON.parse(line.substring(6)); // 转为 Codex 格式{ id: ..., object: chat.completion.chunk, choices: [...] } const codexChunk { id: json.id || chatcmpl-${Date.now()}, object: chat.completion.chunk, choices: [{ index: json.choices?.[0]?.index || 0, delta: { content: json.choices?.[0]?.delta?.content || } }] }; res.write(JSON.stringify(codexChunk) \n); } catch (e) { // 忽略解析失败的 chunk继续处理 } } } }); proxyRes.on(end, () { if (buffer) { // 处理最后一行 if (buffer.startsWith(data: )) { try { const json JSON.parse(buffer.substring(6)); const codexChunk { /* 同上 */ }; res.write(JSON.stringify(codexChunk) \n); } catch (e) {} } } res.end(); }); }这段代码是整个 proxy 的心脏。它把 LiteLLM 返回的text/event-stream逐行解析data: {...}提取出content字段再组装成 Codex 要求的 JSON chunk 格式。关键点res.write(JSON.stringify(...) \n)每 chunk 以\n结尾这是 Codex streaming 的约定buffer机制防止data:跨 chunk 被截断SSE 协议允许一个 data 行跨多个 TCP 包try/catch包裹忽略 malformed chunk保证流不断3. 健康检查 endpointapp.get(/health, (req, res) { // 检查上游服务是否存活 Promise.all([ fetch(http://localhost:8080/health).then(r r.ok), fetch(http://localhost:4000/health).then(r r.ok) ]).then(results { if (results.every(Boolean)) { res.json({ status: ok, upstream: { llama_cpp: true, lite_llm: true } }); } else { res.status(503).json({ status: degraded, upstream: { llama_cpp: results[0], lite_llm: results[1] } }); } }).catch(() { res.status(503).json({ status: unavailable }); }); });这个/health不是摆设。OpenRig 的codex_proxyservice 的 health_check 就是访问这个 endpoint。它会主动探测下游服务返回结构化状态让 OpenRig 能精准判断是 proxy 挂了还是 llama.cpp 挂了。4.3 启动全流程实录与关键参数验证现在我们执行完整的启动流程并记录每个环节的验证点Step 1: 初始化并检查依赖cd my-codex-rig openrig init # 检查 .openrig/ 目录是否创建 ls -la .openrig/ # 应看到 pid/ logs/ sockets/ 三个子目录Step 2: 启动服务openrig start # 观察输出确认三个 ✓ # 然后立即验证 tmux session tmux ls # 应看到 openrig-my-codex-rig tmux attach -t openrig-my-codex-rig # 进入用 Ctrl-b ↑/↓ 切换 paneStep 3: 逐层验证连通性在每个 pane 里执行以下命令llama_cpp panecurl http://localhost:8080/health # 应返回 {status:ok}lite_llm panecurl http://localhost:4000/health # 应返回 {healthy:true} # 再试一个简单推理 curl -X POST http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -d {model:codellama-7b-instruct,messages:[{role:user,content:Hello}],stream:false}