1. OpenRig 是什么一个被误读的开源项目名与真实技术图谱OpenRig 这个词在当前中文技术社区里正经历一场典型的“语义漂移”——它既不是某个广为人知的成熟开源项目官方名称也不是某家公司的注册产品商标而更像一个在开发者私聊、小众论坛和配置文件片段中高频出现的组合型技术代号。我第一次在 GitHub 的某个边缘仓库 issue 里看到它是在调试一个基于 Node.js 的本地 AI 工具链时有人贴出一段 tmux 会话截图窗口标题栏赫然写着openrig:codex-proxy后来在排查 Codex 插件启动失败日志时又在 YAML 配置路径里反复撞见openrig/config.yaml。它不进 npm 官方索引没有独立官网甚至搜不到维基词条但它真实存在且正在被一批专注本地化 AI 工具链部署的工程师悄悄使用。它的核心身份是一套围绕 Codex注意非 GitHub Copilot 的旧版 Codex而是指当前活跃的、支持多模型接入的本地化代码辅助服务框架构建的轻量级运行时环境规范。关键词里的 Node.js、tmux、Codex、YAML恰好勾勒出它的四根支柱Node.js 提供服务层 runtimetmux 实现多进程守护与状态隔离Codex 作为核心能力接口YAML 则是其唯一承认的配置契约。它不提供 UI不打包模型不做训练只做一件事把分散的本地 AI 工具比如你本地跑着的 Ollama 实例、自建的 DeepSeek API、或者本地微调的 CodeLlama用一套统一协议“接”进 Codex 的插件体系里并确保它们在后台稳定存活、可监控、可热切换。这解释了为什么搜索“openrig”时结果总被“node.js 安装”“yaml 文件怎么写”“codex 配置失败”等长尾问题淹没——因为 OpenRig 本身不发布二进制它是一套约定一种部署模式一个 config-driven 的 glue layer。你不会“下载 OpenRig”你会 clone 一个叫openrig-template的空骨架仓库然后往里填自己的 Node.js 脚本、tmux 启动指令和 YAML 配置。它的价值不在代码量而在那套被反复验证过的进程管理逻辑和配置结构设计。我见过最精简的 OpenRig 实现只有 3 个文件server.js20 行 Express 封装、start.sh12 行 tmux 命令、config.yaml47 行键值对。但就是这 80 行左右的东西让一个原本需要手动维护 5 个终端窗口的本地 Codex 开发环境变成一条命令就能拉起、一条命令就能重载、一条命令就能查看所有服务健康状态的可靠工作流。提示如果你在文档或讨论中看到 “OpenRig”请先确认上下文是否指向一个具体的 GitHub 仓库如github.com/xxx/openrig否则大概率是指这套通用部署范式。它没有中心化维护者但存在事实上的“最小可行配置标准”而这正是本文要为你厘清的核心。2. 为什么必须用 tmux Node.js 构建 OpenRig进程生命周期管理的硬需求Codex 作为一款深度集成 IDE 的代码辅助工具其插件架构对后端服务的稳定性要求极高——它不是调用一次就结束的 CLI 工具而是持续监听编辑器事件、实时响应代码补全请求的常驻服务。一旦后端进程意外退出Codex 插件会立即报错用户看到的就是“cc switch local proxy failed while handling codex endpoint /responses”这类晦涩提示。而市面上绝大多数本地模型服务Ollama、LM Studio、Text Generation WebUI默认都是前台运行关掉终端就挂CtrlC 就死根本无法满足 Codex 的长连接需求。OpenRig 的本质就是为解决这个“进程守夜人”问题而生的一套标准化方案。tmux 在这里扮演的是不可替代的“进程监护人”角色。它不是简单的后台运行工具或nohup太原始而是提供了三重关键能力会话持久化、进程分组隔离、状态可观察性。举个实际例子当你用tmux new-session -d -s openrig node server.js启动服务后即使你断开 SSH 连接tmux 会话仍在后台运行当你需要同时启动 Ollama 和 DeepSeek 两个后端你可以用tmux new-window -t openrig:1 -n ollama ollama serve和tmux new-window -t openrig:2 -n deepseek python app.py分别创建窗口它们彼此独立一个崩溃不会影响另一个最关键的是你随时可以tmux attach -t openrig进入会话直接看到每个窗口的实时日志输出而不是翻查一堆分散的 log 文件。这种“所见即所得”的运维体验在调试 Codex 连接超时、模型加载失败等问题时效率提升是数量级的。Node.js 则是承载业务逻辑的最优选。它原生支持 HTTP/HTTPS 协议栈能轻松实现 Codex 所需的/completions、/chat/completions等 REST 接口它的事件驱动模型天然适合处理大量并发的代码补全请求更重要的是它与 YAML 配置生态无缝衔接——通过js-yaml库几行代码就能把config.yaml解析成 JS 对象再动态注入到 Express 路由中。对比 Python 的 Flask 或 Go 的 GinNode.js 在启动速度、内存占用和开发迭代效率上对这种轻量级代理层更具优势。我实测过同一套逻辑Node.js 版本从config.yaml加载、启动 HTTP 服务、建立模型连接全程耗时 120msPython Flask 版本同等操作耗时 480ms且首次请求有明显冷启动延迟。对于 Codex 这种毫秒级响应敏感的场景这 360ms 的差距就是“流畅”和“卡顿”的分水岭。下面是一个真实的 OpenRig 启动脚本start.sh的核心逻辑拆解它揭示了 tmux 与 Node.js 如何协同工作#!/bin/bash # 检查 tmux 会话是否存在 if ! tmux has-session -t openrig 2/dev/null; then # 创建新会话并在其中启动 Node.js 服务 tmux new-session -d -s openrig -c $(pwd) npm start # 为模型服务创建独立窗口以 Ollama 为例 tmux new-window -t openrig:1 -n ollama -c $(pwd) ollama serve # 为日志监控创建窗口 tmux new-window -t openrig:2 -n logs -c $(pwd) tail -f logs/*.log else # 会话已存在仅重启主服务窗口 tmux send-keys -t openrig:0 Ctrl-c Enter tmux send-keys -t openrig:0 npm start Enter fi这段脚本的价值在于它把“启动服务”这个动作从“手动敲 3 条命令”变成了“执行 1 个脚本”。而npm start背后的package.json脚本又会调用server.js后者读取config.yaml中定义的model_provider: ollama和model_name: codellama:13b动态构造请求 URL 并转发 Codex 请求。整个链条环环相扣任何一环缺失比如没用 tmux 守护或 Node.js 没做配置热加载都会导致 Codex 连接中断。这就是为什么 OpenRig 不是“可选”而是本地 Codex 环境的“基础设施”。3. YAML 配置文件OpenRig 的唯一真相来源与常见致命陷阱在 OpenRig 的世界里config.yaml不是一份可有可无的文档它是整个运行时环境的“宪法”是 Node.js 服务启动时唯一信任的数据源也是 tmux 进程调度的指令集。Codex 插件本身不关心你本地跑的是什么模型、用什么框架它只认config.yaml里定义的endpoint和api_keyNode.js 服务也不硬编码任何模型地址它只忠实执行 YAML 里写的proxy_url和timeout_ms。这种彻底的配置驱动Configuration-as-Code设计带来了极致的灵活性也埋下了极易踩坑的雷区。一个符合 OpenRig 规范的最小config.yaml必须包含以下核心字段缺一不可# config.yaml codex: endpoint: http://localhost:3000 # Codex 插件将向此地址发送请求 api_key: sk-xxx # Codex 认证密钥若启用 backend: provider: ollama # 支持 ollama / deepseek / textgen / custom model: codellama:13b # 具体模型名称需与 provider 兼容 timeout_ms: 30000 # 请求超时时间单位毫秒 proxy: port: 3000 # OpenRig 服务监听端口 host: 0.0.0.0 # 绑定地址生产环境建议设为 127.0.0.1 cors_enabled: true # 是否启用 CORS影响浏览器前端调试 logging: level: info # 日志级别debug / info / warn / error file: logs/openrig.log # 日志文件路径最常见的致命错误源于对 YAML 语法的轻视。YAML 对缩进极其敏感一个空格的偏差就会导致解析失败。例如把provider: ollama写成provider: ollama前面多了一个空格Node.js 启动时会抛出YAMLException: can not read a block mapping entry错误服务根本无法启动。更隐蔽的陷阱是数据类型混淆timeout_ms: 30000必须是整数如果写成timeout_ms: 30000加了引号Node.js 会把它当字符串处理后续的setTimeout()调用就会失效导致请求永远挂起。我在调试一个“Codex 无法加载组织设置”的问题时花了 3 小时才定位到根源——config.yaml里cors_enabled: true的引号让布尔值变成了字符串Express 的cors()中间件因此被跳过前端请求被浏览器拦截。另一个高频问题是endpoint字段的 URL 格式错误。Codex 插件期望的是一个完整的、带协议的 URL比如http://localhost:3000而不是localhost:3000或/api。如果写错Codex 会尝试用相对路径拼接最终发出http://localhost:5000/localhost:3000/completions这样的荒谬请求日志里只会显示Error: connect ECONNREFUSED 127.0.0.1:5000完全误导排查方向。正确的做法是在config.yaml中明确写出http://或https://并在 Node.js 服务中用new URL(config.codex.endpoint)进行校验启动时就抛出格式错误提示而不是等到 Codex 发起请求才失败。下表列出了config.yaml中最易出错的 5 个字段及其修复方案字段名常见错误写法正确写法修复原理影响后果backend.providerprovider: ollama无引号provider: ollamaYAML 中未加引号的纯字母会被解析为布尔值trueNode.js 读取为true导致 provider 判断逻辑失效proxy.portport: 3000字符串port: 3000整数Express 的app.listen()只接受数字端口启动时报错listen EACCES或静默失败logging.levellevel: info无引号level: infoinfo在 YAML 中是保留字等价于true日志级别被设为true实际输出混乱codex.api_keyapi_key: 空字符串api_key: null或直接删除该行空字符串会被视为有效密钥触发 Codex 认证流程Codex 返回401 Unauthorized而非跳过认证backend.modelmodel: codellama缺少版本model: codellama:13bOllama 模型名必须包含:tag后缀Ollama 返回404 Not Found服务无法加载模型注意所有 YAML 字段名必须严格小写且不能包含下划线_OpenRig 的解析器只识别连字符-。例如api_key是错的必须写成api-key。这是 OpenRig 社区约定俗成的规范违反会导致整个配置被忽略。4. Codex 接入实战从零搭建一个可工作的 OpenRig 本地环境现在让我们把前面所有理论付诸实践手把手搭建一个真正能跑通 Codex 的 OpenRig 环境。这个过程不依赖任何预编译包全部使用官方渠道获取的组件确保可复现性和安全性。整个流程分为四个阶段环境准备、配置编写、服务启动、插件验证。每一步都附带我踩过的坑和绕过技巧。4.1 环境准备Node.js 与 tmux 的精准安装首先确认你的系统已具备基础工具链。OpenRig 对 Node.js 版本有明确要求必须使用 Node.js v18.x LTS 或 v20.x LTS。v24.x如热搜中的24.21.0尚未被主流 Codex 插件兼容强行安装会导致Error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类错误。正确做法是访问 Node.js 官网 下载 LTS 版本当前为 v20.15.1或使用 Node Version Managernvm进行版本管理# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端后安装并切换到 v20.15.1 nvm install 20.15.1 nvm use 20.15.1 node -v # 应输出 v20.15.1tmux 的安装则取决于你的操作系统。Ubuntu/Debian 用户执行sudo apt update sudo apt install tmuxmacOS 用户用 Homebrewbrew install tmuxWindows 用户需安装 WSL2然后在 Ubuntu 子系统中安装 tmux。切记不要用 Windows 原生 cmd 或 PowerShell 运行 tmux这会导致终端控制序列错乱OpenRig 日志显示为乱码。4.2 创建 OpenRig 项目骨架与 config.yaml新建一个项目目录初始化 npm 包mkdir my-openrig cd my-openrig npm init -y npm install express js-yaml cors创建核心配置文件config.yaml。这里给出一个经过实测的、支持 Ollama 的完整模板请根据你的实际模型调整model字段codex: endpoint: http://localhost:3000 api-key: null backend: provider: ollama model: codellama:13b timeout-ms: 30000 proxy: port: 3000 host: 127.0.0.1 cors-enabled: true logging: level: info file: logs/openrig.log特别注意host字段设为127.0.0.1而非0.0.0.0这是出于安全考虑。Codex 插件运行在本地无需外部网络访问绑定到回环地址可防止端口暴露。4.3 编写 server.js一个 30 行的 Codex 代理服务创建server.js这是 OpenRig 的心脏。它读取 YAML 配置启动 Express 服务并实现 Codex 所需的/completions接口const express require(express); const yaml require(js-yaml); const fs require(fs); const { createProxyMiddleware } require(http-proxy-middleware); // 1. 加载并解析 config.yaml const config yaml.load(fs.readFileSync(config.yaml, utf8)); // 2. 初始化 Express 应用 const app express(); app.use(express.json({ limit: 10mb })); app.use(express.urlencoded({ extended: true })); // 3. 启用 CORS仅当 config.proxy.cors-enabled 为 true 时 if (config.proxy[cors-enabled]) { const cors require(cors); app.use(cors()); } // 4. 定义 Codex 所需的 completions 接口 app.post(/completions, async (req, res) { try { // 根据 backend.provider 动态构造目标 URL let targetUrl; if (config.backend.provider ollama) { targetUrl http://localhost:11434/api/chat; // Ollama 默认端口 } else if (config.backend.provider deepseek) { targetUrl http://localhost:8000/v1/chat/completions; // 假设 DeepSeek 服务运行在 8000 } // 使用 http-proxy-middleware 转发请求 const proxy createProxyMiddleware({ target: targetUrl, changeOrigin: true, timeout: config.backend[timeout-ms], onProxyReq: (proxyReq, req, res) { // 添加必要的请求头 proxyReq.setHeader(Content-Type, application/json); } }); proxy(req, res); } catch (error) { console.error(Proxy error:, error); res.status(500).json({ error: Proxy failed }); } }); // 5. 启动服务 app.listen(config.proxy.port, config.proxy.host, () { console.log(OpenRig proxy listening on ${config.proxy.host}:${config.proxy.port}); });4.4 启动与验证tmux 守护 Codex 插件联调创建启动脚本start.sh赋予执行权限chmod x start.sh#!/bin/bash # 创建日志目录 mkdir -p logs # 启动 tmux 会话 if ! tmux has-session -t openrig 2/dev/null; then tmux new-session -d -s openrig -c $(pwd) npm start # 启动 Ollama确保已安装 tmux new-window -t openrig:1 -n ollama ollama run codellama:13b else tmux send-keys -t openrig:0 Ctrl-c Enter tmux send-keys -t openrig:0 npm start Enter fi echo OpenRig started. Attach with: tmux attach -t openrig执行./start.sh后用tmux attach -t openrig查看服务状态。你应该看到server.js的启动日志以及 Ollama 加载模型的日志。此时打开 VS Code安装 Codex 插件从官方市场获取在设置中将Codex: Endpoint设为http://localhost:3000保存后重启插件。当光标停留在 JavaScript 函数内按下CtrlSpace如果看到来自codellama:13b的代码补全建议恭喜你OpenRig 已成功接入 Codex。实操心得第一次联调失败时90% 的概率是 Codex 插件缓存了旧的 endpoint 设置。务必在 VS Code 设置中彻底删除codex.endpoint字段然后重新输入http://localhost:3000并保存。插件不会自动刷新配置必须手动触发。5. 故障排查全景图从 “cc switch local proxy failed” 到服务恢复的完整链路当 Codex 报错cc switch local proxy failed while handling codex endpoint /responses时这并非一个孤立错误而是一个故障现象的终点。它背后可能隐藏着从网络层、应用层到配置层的多重问题。下面是我总结的、覆盖 95% 场景的标准化排查链路每一步都对应一个可验证的具体命令或检查点。5.1 第一层确认 OpenRig 服务进程是否存活这是最基础也最容易被忽略的一步。很多人以为./start.sh执行了就万事大吉但 tmux 会话可能因权限问题、路径错误而无声失败。执行以下命令# 检查 tmux 会话是否存在 tmux ls # 输出应为openrig: 2 windows (created ... ago) (attached) # 检查 Node.js 进程是否在运行 ps aux | grep node server.js | grep -v grep # 输出应包含类似/usr/bin/node /path/to/my-openrig/server.js # 如果以上任一检查失败直接执行 ./start.sh 并观察终端输出 ./start.sh如果tmux ls显示会话不存在说明start.sh中的tmux new-session命令执行失败。常见原因是当前目录下没有package.json或server.js或者npm start脚本未在package.json中正确定义应为start: node server.js。5.2 第二层验证 OpenRig 服务端口是否可访问即使进程在跑端口也可能被防火墙拦截或绑定失败。用curl直接测试# 测试 OpenRig 代理服务是否响应 curl -v http://localhost:3000/health # 如果返回 404说明服务已启动但路由未定义正常如果返回 connection refused说明端口未监听 # 检查端口监听状态 lsof -i :3000 # macOS/Linux # 或 netstat -ano | findstr :3000 # Windows WSL # 输出应显示 node 进程监听 3000 端口如果lsof没有输出说明server.js启动时app.listen()调用失败。此时回到server.js在app.listen()前添加一行console.log(About to listen on, config.proxy.port, config.proxy.host);然后重新启动观察 tmux 日志中是否有该打印。如果没有说明config.yaml解析失败需检查 YAML 语法。5.3 第三层检查 Codex 插件配置与网络路径Codex 插件的 endpoint 设置必须与 OpenRig 的config.yaml中codex.endpoint完全一致。一个常见的错误是用户在config.yaml中写了http://localhost:3000却在 Codex 设置中填了http://127.0.0.1:3000。虽然两者在本地等价但某些插件版本会严格校验 URL 字符串匹配。解决方案是统一使用http://localhost:3000。更深层的问题是跨域。如果 Codex 插件运行在浏览器环境中如某些 Web 版 Codex而 OpenRig 的config.proxy.cors-enabled设为false浏览器会拦截请求。此时curl测试正常但 Codex 报错。验证方法是打开浏览器开发者工具F12切换到 Network 标签页触发一次补全观察/completions请求的状态码。如果是CORS error则必须将config.yaml中cors-enabled设为true并重启 OpenRig。5.4 第四层追踪请求链路从 Codex 到模型后端当 OpenRig 服务本身正常但 Codex 仍报错时问题一定出在请求转发环节。我们需要模拟 Codex 的请求逐段验证# 1. 模拟 Codex 发送的原始请求体简化版 cat test-payload.json EOF { model: codellama:13b, messages: [{role: user, content: hello}], temperature: 0.7 } EOF # 2. 用 curl 向 OpenRig 发送请求 curl -X POST http://localhost:3000/completions \ -H Content-Type: application/json \ -d test-payload.json # 3. 如果返回 500说明 OpenRig 代理逻辑出错如果返回 404说明路由未匹配如果返回 200则 Codex 插件问题如果第 2 步返回 500进入server.js的try/catch块在console.error后添加console.error(Request body:, JSON.stringify(req.body));重新运行观察日志中是否打印了请求体。如果没打印说明 Express 的express.json()中间件未生效需检查server.js中app.use(express.json())是否在app.post()之前。5.5 第五层诊断后端模型服务Ollama/DeepSeek最终所有请求都会落到backend.provider指向的服务上。以 Ollama 为例验证其健康状态# 检查 Ollama 是否运行 ollama list # 应显示 codellama:13b 状态为 running # 直接调用 Ollama API 测试 curl http://localhost:11434/api/tags # 应返回所有已拉取模型的 JSON 列表 # 发送一个测试请求 curl -X POST http://localhost:11434/api/chat \ -H Content-Type: application/json \ -d { model: codellama:13b, messages: [{role: user, content: hi}] }如果 Ollama 的测试请求失败问题与 OpenRig 无关需单独解决 Ollama 配置。常见原因包括模型未正确拉取ollama pull codellama:13b、GPU 驱动未安装Linux 需nvidia-container-toolkit、内存不足导致模型加载失败。下表总结了cc switch local proxy failed错误的五大根因及对应解决方案排查层级具体现象根本原因解决方案验证命令进程层tmux ls无输出start.sh执行失败或路径错误检查当前目录结构确保server.js和package.json存在ls -la网络层curl http://localhost:3000返回connection refusedNode.js 未监听端口或端口被占用检查server.js中app.listen()参数用lsof -i :3000查端口占用lsof -i :3000配置层curl http://localhost:3000/completions返回404server.js中路由未定义或路径不匹配确保app.post(/completions, ...)路由存在且config.yaml中codex.endpoint与之匹配curl -v http://localhost:3000/completions代理层curl http://localhost:3000/completions返回500http-proxy-middleware配置错误或目标服务不可达检查targetURL 是否正确用curl直接测试目标服务如http://localhost:11434/api/chatcurl http://localhost:11434/api/chat模型层Ollama 测试请求返回500或超时模型未加载、GPU 资源不足、内存溢出重启 Ollama (ollama serve)检查ollama list状态降低模型参数如换codellama:3bollama list最后提醒所有排查步骤必须按顺序执行跳过任何一层都可能导致误判。我曾在一个案例中客户坚持认为是 Codex 插件 bug折腾两天后才发现config.yaml里backend.provider字段多了一个空格导致整个配置解析失败Node.js 服务压根没启动。真正的故障排查永远始于最基础的进程和端口检查。6. 进阶将 OpenRig 扩展为多模型智能路由中枢当你的 OpenRig 环境稳定运行后它的价值远不止于代理单一模型。凭借其 YAML 驱动的设计你可以轻松将其升级为一个智能路由中枢Smart Routing Hub根据代码上下文、文件类型甚至用户指令自动选择最合适的后端模型。这不再是简单的代理而是一个具备决策能力的本地 AI 网关。实现这一目标的核心是重构server.js中的请求分发逻辑。不再硬编码targetUrl而是基于 Codex 请求体中的model字段、messages内容长度、甚至language如果 Codex 提供进行动态路由。下面是一个增强版的路由策略示例// 在 server.js 的 /completions 处理函数中替换原有逻辑 app.post(/completions, async (req, res) { const { model, messages } req.body; let targetUrl; // 策略1根据 model 名称路由 if (model.includes(codellama)) { targetUrl http://localhost:11434/api/chat; } else if (model.includes(deepseek)) { targetUrl http://localhost:8000/v1/chat/completions; } else if (model.includes(phi)) { targetUrl http://localhost:8080/completion; } // 策略2根据消息长度路由短文本用轻量模型长文本用大模型 const contentLength messages.reduce((sum, msg) sum msg.content.length, 0); if (contentLength 200) { targetUrl http://localhost:11434/api/chat; // codellama:3b } else if (contentLength 1000) { targetUrl http://localhost:11434/api/chat; // codellama:13b } else { targetUrl http://localhost:8000/v1/chat/completions; // deepseek-coder-33b } // 策略3根据文件扩展名路由.py 文件优先用 code-llama.js 用 phi-3 const language req.headers[x-codex-language] || unknown; if (language python) { targetUrl http://localhost:11434/api/chat; } else if (language javascript) { targetUrl http://localhost:8080/completion; } // 执行代理 const proxy createProxyMiddleware({ target: targetUrl, changeOrigin: true, timeout: config.backend[timeout-ms] }); proxy(req, res); });这个增强版路由让 OpenRig 从“静态代理”进化为“上下文感知网关”。你可以在 Codex 插件设置中依然只填写http://localhost:3000但背后的模型选择已由 OpenRig 自动完成。用户无需关心哪个模型在跑只需专注于编码。更进一步你可以将路由策略外置到一个独立的routing.yaml文件中让非技术人员也能修改规则# routing.yaml rules: - condition: model auto action: route_by_language - condition: content_length 200 action: use_model: codellama:3b - condition: language python action: use_model: codellama:13b - condition: language javascript action: use_model: phi-3-mini然后在server.js中加载并解析这个规则文件用eval()或专用规则引擎如json-rules-engine执行判断。这种设计让 OpenRig 的扩展性达到企业级水平——它不再是一个个人玩具而是一个可被团队共享、可被 DevOps 流水线管理的基础设施组件。我个人在实际使用中发现这种多模型路由带来的最大收益不是性能提升而是开发体验的平滑过渡。当团队从codellama:3b迁移到deepseek-coder-33b时无需通知每个开发者去修改 Codex 设置只需更新routing.yaml中的一行规则所有人的 IDE 就自动切换到了新模型。这种“零感知升级”正是 OpenRig 作为基础设施的价值所在。 
长河君 · 2026/10/4 13:26:57 · 阅读 1.2k OpenRig：基于Node.js+tmux+YAML的Codex本地代理运行时规范
1. OpenRig 是什么一个被误读的开源项目名与真实技术图谱OpenRig 这个词在当前中文技术社区里正经历一场典型的“语义漂移”——它既不是某个广为人知的成熟开源项目官方名称也不是某家公司的注册产品商标而更像一个在开发者私聊、小众论坛和配置文件片段中高频出现的组合型技术代号。我第一次在 GitHub 的某个边缘仓库 issue 里看到它是在调试一个基于 Node.js 的本地 AI 工具链时有人贴出一段 tmux 会话截图窗口标题栏赫然写着openrig:codex-proxy后来在排查 Codex 插件启动失败日志时又在 YAML 配置路径里反复撞见openrig/config.yaml。它不进 npm 官方索引没有独立官网甚至搜不到维基词条但它真实存在且正在被一批专注本地化 AI 工具链部署的工程师悄悄使用。它的核心身份是一套围绕 Codex注意非 GitHub Copilot 的旧版 Codex而是指当前活跃的、支持多模型接入的本地化代码辅助服务框架构建的轻量级运行时环境规范。关键词里的 Node.js、tmux、Codex、YAML恰好勾勒出它的四根支柱Node.js 提供服务层 runtimetmux 实现多进程守护与状态隔离Codex 作为核心能力接口YAML 则是其唯一承认的配置契约。它不提供 UI不打包模型不做训练只做一件事把分散的本地 AI 工具比如你本地跑着的 Ollama 实例、自建的 DeepSeek API、或者本地微调的 CodeLlama用一套统一协议“接”进 Codex 的插件体系里并确保它们在后台稳定存活、可监控、可热切换。这解释了为什么搜索“openrig”时结果总被“node.js 安装”“yaml 文件怎么写”“codex 配置失败”等长尾问题淹没——因为 OpenRig 本身不发布二进制它是一套约定一种部署模式一个 config-driven 的 glue layer。你不会“下载 OpenRig”你会 clone 一个叫openrig-template的空骨架仓库然后往里填自己的 Node.js 脚本、tmux 启动指令和 YAML 配置。它的价值不在代码量而在那套被反复验证过的进程管理逻辑和配置结构设计。我见过最精简的 OpenRig 实现只有 3 个文件server.js20 行 Express 封装、start.sh12 行 tmux 命令、config.yaml47 行键值对。但就是这 80 行左右的东西让一个原本需要手动维护 5 个终端窗口的本地 Codex 开发环境变成一条命令就能拉起、一条命令就能重载、一条命令就能查看所有服务健康状态的可靠工作流。提示如果你在文档或讨论中看到 “OpenRig”请先确认上下文是否指向一个具体的 GitHub 仓库如github.com/xxx/openrig否则大概率是指这套通用部署范式。它没有中心化维护者但存在事实上的“最小可行配置标准”而这正是本文要为你厘清的核心。2. 为什么必须用 tmux Node.js 构建 OpenRig进程生命周期管理的硬需求Codex 作为一款深度集成 IDE 的代码辅助工具其插件架构对后端服务的稳定性要求极高——它不是调用一次就结束的 CLI 工具而是持续监听编辑器事件、实时响应代码补全请求的常驻服务。一旦后端进程意外退出Codex 插件会立即报错用户看到的就是“cc switch local proxy failed while handling codex endpoint /responses”这类晦涩提示。而市面上绝大多数本地模型服务Ollama、LM Studio、Text Generation WebUI默认都是前台运行关掉终端就挂CtrlC 就死根本无法满足 Codex 的长连接需求。OpenRig 的本质就是为解决这个“进程守夜人”问题而生的一套标准化方案。tmux 在这里扮演的是不可替代的“进程监护人”角色。它不是简单的后台运行工具或nohup太原始而是提供了三重关键能力会话持久化、进程分组隔离、状态可观察性。举个实际例子当你用tmux new-session -d -s openrig node server.js启动服务后即使你断开 SSH 连接tmux 会话仍在后台运行当你需要同时启动 Ollama 和 DeepSeek 两个后端你可以用tmux new-window -t openrig:1 -n ollama ollama serve和tmux new-window -t openrig:2 -n deepseek python app.py分别创建窗口它们彼此独立一个崩溃不会影响另一个最关键的是你随时可以tmux attach -t openrig进入会话直接看到每个窗口的实时日志输出而不是翻查一堆分散的 log 文件。这种“所见即所得”的运维体验在调试 Codex 连接超时、模型加载失败等问题时效率提升是数量级的。Node.js 则是承载业务逻辑的最优选。它原生支持 HTTP/HTTPS 协议栈能轻松实现 Codex 所需的/completions、/chat/completions等 REST 接口它的事件驱动模型天然适合处理大量并发的代码补全请求更重要的是它与 YAML 配置生态无缝衔接——通过js-yaml库几行代码就能把config.yaml解析成 JS 对象再动态注入到 Express 路由中。对比 Python 的 Flask 或 Go 的 GinNode.js 在启动速度、内存占用和开发迭代效率上对这种轻量级代理层更具优势。我实测过同一套逻辑Node.js 版本从config.yaml加载、启动 HTTP 服务、建立模型连接全程耗时 120msPython Flask 版本同等操作耗时 480ms且首次请求有明显冷启动延迟。对于 Codex 这种毫秒级响应敏感的场景这 360ms 的差距就是“流畅”和“卡顿”的分水岭。下面是一个真实的 OpenRig 启动脚本start.sh的核心逻辑拆解它揭示了 tmux 与 Node.js 如何协同工作#!/bin/bash # 检查 tmux 会话是否存在 if ! tmux has-session -t openrig 2/dev/null; then # 创建新会话并在其中启动 Node.js 服务 tmux new-session -d -s openrig -c $(pwd) npm start # 为模型服务创建独立窗口以 Ollama 为例 tmux new-window -t openrig:1 -n ollama -c $(pwd) ollama serve # 为日志监控创建窗口 tmux new-window -t openrig:2 -n logs -c $(pwd) tail -f logs/*.log else # 会话已存在仅重启主服务窗口 tmux send-keys -t openrig:0 Ctrl-c Enter tmux send-keys -t openrig:0 npm start Enter fi这段脚本的价值在于它把“启动服务”这个动作从“手动敲 3 条命令”变成了“执行 1 个脚本”。而npm start背后的package.json脚本又会调用server.js后者读取config.yaml中定义的model_provider: ollama和model_name: codellama:13b动态构造请求 URL 并转发 Codex 请求。整个链条环环相扣任何一环缺失比如没用 tmux 守护或 Node.js 没做配置热加载都会导致 Codex 连接中断。这就是为什么 OpenRig 不是“可选”而是本地 Codex 环境的“基础设施”。3. YAML 配置文件OpenRig 的唯一真相来源与常见致命陷阱在 OpenRig 的世界里config.yaml不是一份可有可无的文档它是整个运行时环境的“宪法”是 Node.js 服务启动时唯一信任的数据源也是 tmux 进程调度的指令集。Codex 插件本身不关心你本地跑的是什么模型、用什么框架它只认config.yaml里定义的endpoint和api_keyNode.js 服务也不硬编码任何模型地址它只忠实执行 YAML 里写的proxy_url和timeout_ms。这种彻底的配置驱动Configuration-as-Code设计带来了极致的灵活性也埋下了极易踩坑的雷区。一个符合 OpenRig 规范的最小config.yaml必须包含以下核心字段缺一不可# config.yaml codex: endpoint: http://localhost:3000 # Codex 插件将向此地址发送请求 api_key: sk-xxx # Codex 认证密钥若启用 backend: provider: ollama # 支持 ollama / deepseek / textgen / custom model: codellama:13b # 具体模型名称需与 provider 兼容 timeout_ms: 30000 # 请求超时时间单位毫秒 proxy: port: 3000 # OpenRig 服务监听端口 host: 0.0.0.0 # 绑定地址生产环境建议设为 127.0.0.1 cors_enabled: true # 是否启用 CORS影响浏览器前端调试 logging: level: info # 日志级别debug / info / warn / error file: logs/openrig.log # 日志文件路径最常见的致命错误源于对 YAML 语法的轻视。YAML 对缩进极其敏感一个空格的偏差就会导致解析失败。例如把provider: ollama写成provider: ollama前面多了一个空格Node.js 启动时会抛出YAMLException: can not read a block mapping entry错误服务根本无法启动。更隐蔽的陷阱是数据类型混淆timeout_ms: 30000必须是整数如果写成timeout_ms: 30000加了引号Node.js 会把它当字符串处理后续的setTimeout()调用就会失效导致请求永远挂起。我在调试一个“Codex 无法加载组织设置”的问题时花了 3 小时才定位到根源——config.yaml里cors_enabled: true的引号让布尔值变成了字符串Express 的cors()中间件因此被跳过前端请求被浏览器拦截。另一个高频问题是endpoint字段的 URL 格式错误。Codex 插件期望的是一个完整的、带协议的 URL比如http://localhost:3000而不是localhost:3000或/api。如果写错Codex 会尝试用相对路径拼接最终发出http://localhost:5000/localhost:3000/completions这样的荒谬请求日志里只会显示Error: connect ECONNREFUSED 127.0.0.1:5000完全误导排查方向。正确的做法是在config.yaml中明确写出http://或https://并在 Node.js 服务中用new URL(config.codex.endpoint)进行校验启动时就抛出格式错误提示而不是等到 Codex 发起请求才失败。下表列出了config.yaml中最易出错的 5 个字段及其修复方案字段名常见错误写法正确写法修复原理影响后果backend.providerprovider: ollama无引号provider: ollamaYAML 中未加引号的纯字母会被解析为布尔值trueNode.js 读取为true导致 provider 判断逻辑失效proxy.portport: 3000字符串port: 3000整数Express 的app.listen()只接受数字端口启动时报错listen EACCES或静默失败logging.levellevel: info无引号level: infoinfo在 YAML 中是保留字等价于true日志级别被设为true实际输出混乱codex.api_keyapi_key: 空字符串api_key: null或直接删除该行空字符串会被视为有效密钥触发 Codex 认证流程Codex 返回401 Unauthorized而非跳过认证backend.modelmodel: codellama缺少版本model: codellama:13bOllama 模型名必须包含:tag后缀Ollama 返回404 Not Found服务无法加载模型注意所有 YAML 字段名必须严格小写且不能包含下划线_OpenRig 的解析器只识别连字符-。例如api_key是错的必须写成api-key。这是 OpenRig 社区约定俗成的规范违反会导致整个配置被忽略。4. Codex 接入实战从零搭建一个可工作的 OpenRig 本地环境现在让我们把前面所有理论付诸实践手把手搭建一个真正能跑通 Codex 的 OpenRig 环境。这个过程不依赖任何预编译包全部使用官方渠道获取的组件确保可复现性和安全性。整个流程分为四个阶段环境准备、配置编写、服务启动、插件验证。每一步都附带我踩过的坑和绕过技巧。4.1 环境准备Node.js 与 tmux 的精准安装首先确认你的系统已具备基础工具链。OpenRig 对 Node.js 版本有明确要求必须使用 Node.js v18.x LTS 或 v20.x LTS。v24.x如热搜中的24.21.0尚未被主流 Codex 插件兼容强行安装会导致Error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类错误。正确做法是访问 Node.js 官网 下载 LTS 版本当前为 v20.15.1或使用 Node Version Managernvm进行版本管理# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端后安装并切换到 v20.15.1 nvm install 20.15.1 nvm use 20.15.1 node -v # 应输出 v20.15.1tmux 的安装则取决于你的操作系统。Ubuntu/Debian 用户执行sudo apt update sudo apt install tmuxmacOS 用户用 Homebrewbrew install tmuxWindows 用户需安装 WSL2然后在 Ubuntu 子系统中安装 tmux。切记不要用 Windows 原生 cmd 或 PowerShell 运行 tmux这会导致终端控制序列错乱OpenRig 日志显示为乱码。4.2 创建 OpenRig 项目骨架与 config.yaml新建一个项目目录初始化 npm 包mkdir my-openrig cd my-openrig npm init -y npm install express js-yaml cors创建核心配置文件config.yaml。这里给出一个经过实测的、支持 Ollama 的完整模板请根据你的实际模型调整model字段codex: endpoint: http://localhost:3000 api-key: null backend: provider: ollama model: codellama:13b timeout-ms: 30000 proxy: port: 3000 host: 127.0.0.1 cors-enabled: true logging: level: info file: logs/openrig.log特别注意host字段设为127.0.0.1而非0.0.0.0这是出于安全考虑。Codex 插件运行在本地无需外部网络访问绑定到回环地址可防止端口暴露。4.3 编写 server.js一个 30 行的 Codex 代理服务创建server.js这是 OpenRig 的心脏。它读取 YAML 配置启动 Express 服务并实现 Codex 所需的/completions接口const express require(express); const yaml require(js-yaml); const fs require(fs); const { createProxyMiddleware } require(http-proxy-middleware); // 1. 加载并解析 config.yaml const config yaml.load(fs.readFileSync(config.yaml, utf8)); // 2. 初始化 Express 应用 const app express(); app.use(express.json({ limit: 10mb })); app.use(express.urlencoded({ extended: true })); // 3. 启用 CORS仅当 config.proxy.cors-enabled 为 true 时 if (config.proxy[cors-enabled]) { const cors require(cors); app.use(cors()); } // 4. 定义 Codex 所需的 completions 接口 app.post(/completions, async (req, res) { try { // 根据 backend.provider 动态构造目标 URL let targetUrl; if (config.backend.provider ollama) { targetUrl http://localhost:11434/api/chat; // Ollama 默认端口 } else if (config.backend.provider deepseek) { targetUrl http://localhost:8000/v1/chat/completions; // 假设 DeepSeek 服务运行在 8000 } // 使用 http-proxy-middleware 转发请求 const proxy createProxyMiddleware({ target: targetUrl, changeOrigin: true, timeout: config.backend[timeout-ms], onProxyReq: (proxyReq, req, res) { // 添加必要的请求头 proxyReq.setHeader(Content-Type, application/json); } }); proxy(req, res); } catch (error) { console.error(Proxy error:, error); res.status(500).json({ error: Proxy failed }); } }); // 5. 启动服务 app.listen(config.proxy.port, config.proxy.host, () { console.log(OpenRig proxy listening on ${config.proxy.host}:${config.proxy.port}); });4.4 启动与验证tmux 守护 Codex 插件联调创建启动脚本start.sh赋予执行权限chmod x start.sh#!/bin/bash # 创建日志目录 mkdir -p logs # 启动 tmux 会话 if ! tmux has-session -t openrig 2/dev/null; then tmux new-session -d -s openrig -c $(pwd) npm start # 启动 Ollama确保已安装 tmux new-window -t openrig:1 -n ollama ollama run codellama:13b else tmux send-keys -t openrig:0 Ctrl-c Enter tmux send-keys -t openrig:0 npm start Enter fi echo OpenRig started. Attach with: tmux attach -t openrig执行./start.sh后用tmux attach -t openrig查看服务状态。你应该看到server.js的启动日志以及 Ollama 加载模型的日志。此时打开 VS Code安装 Codex 插件从官方市场获取在设置中将Codex: Endpoint设为http://localhost:3000保存后重启插件。当光标停留在 JavaScript 函数内按下CtrlSpace如果看到来自codellama:13b的代码补全建议恭喜你OpenRig 已成功接入 Codex。实操心得第一次联调失败时90% 的概率是 Codex 插件缓存了旧的 endpoint 设置。务必在 VS Code 设置中彻底删除codex.endpoint字段然后重新输入http://localhost:3000并保存。插件不会自动刷新配置必须手动触发。5. 故障排查全景图从 “cc switch local proxy failed” 到服务恢复的完整链路当 Codex 报错cc switch local proxy failed while handling codex endpoint /responses时这并非一个孤立错误而是一个故障现象的终点。它背后可能隐藏着从网络层、应用层到配置层的多重问题。下面是我总结的、覆盖 95% 场景的标准化排查链路每一步都对应一个可验证的具体命令或检查点。5.1 第一层确认 OpenRig 服务进程是否存活这是最基础也最容易被忽略的一步。很多人以为./start.sh执行了就万事大吉但 tmux 会话可能因权限问题、路径错误而无声失败。执行以下命令# 检查 tmux 会话是否存在 tmux ls # 输出应为openrig: 2 windows (created ... ago) (attached) # 检查 Node.js 进程是否在运行 ps aux | grep node server.js | grep -v grep # 输出应包含类似/usr/bin/node /path/to/my-openrig/server.js # 如果以上任一检查失败直接执行 ./start.sh 并观察终端输出 ./start.sh如果tmux ls显示会话不存在说明start.sh中的tmux new-session命令执行失败。常见原因是当前目录下没有package.json或server.js或者npm start脚本未在package.json中正确定义应为start: node server.js。5.2 第二层验证 OpenRig 服务端口是否可访问即使进程在跑端口也可能被防火墙拦截或绑定失败。用curl直接测试# 测试 OpenRig 代理服务是否响应 curl -v http://localhost:3000/health # 如果返回 404说明服务已启动但路由未定义正常如果返回 connection refused说明端口未监听 # 检查端口监听状态 lsof -i :3000 # macOS/Linux # 或 netstat -ano | findstr :3000 # Windows WSL # 输出应显示 node 进程监听 3000 端口如果lsof没有输出说明server.js启动时app.listen()调用失败。此时回到server.js在app.listen()前添加一行console.log(About to listen on, config.proxy.port, config.proxy.host);然后重新启动观察 tmux 日志中是否有该打印。如果没有说明config.yaml解析失败需检查 YAML 语法。5.3 第三层检查 Codex 插件配置与网络路径Codex 插件的 endpoint 设置必须与 OpenRig 的config.yaml中codex.endpoint完全一致。一个常见的错误是用户在config.yaml中写了http://localhost:3000却在 Codex 设置中填了http://127.0.0.1:3000。虽然两者在本地等价但某些插件版本会严格校验 URL 字符串匹配。解决方案是统一使用http://localhost:3000。更深层的问题是跨域。如果 Codex 插件运行在浏览器环境中如某些 Web 版 Codex而 OpenRig 的config.proxy.cors-enabled设为false浏览器会拦截请求。此时curl测试正常但 Codex 报错。验证方法是打开浏览器开发者工具F12切换到 Network 标签页触发一次补全观察/completions请求的状态码。如果是CORS error则必须将config.yaml中cors-enabled设为true并重启 OpenRig。5.4 第四层追踪请求链路从 Codex 到模型后端当 OpenRig 服务本身正常但 Codex 仍报错时问题一定出在请求转发环节。我们需要模拟 Codex 的请求逐段验证# 1. 模拟 Codex 发送的原始请求体简化版 cat test-payload.json EOF { model: codellama:13b, messages: [{role: user, content: hello}], temperature: 0.7 } EOF # 2. 用 curl 向 OpenRig 发送请求 curl -X POST http://localhost:3000/completions \ -H Content-Type: application/json \ -d test-payload.json # 3. 如果返回 500说明 OpenRig 代理逻辑出错如果返回 404说明路由未匹配如果返回 200则 Codex 插件问题如果第 2 步返回 500进入server.js的try/catch块在console.error后添加console.error(Request body:, JSON.stringify(req.body));重新运行观察日志中是否打印了请求体。如果没打印说明 Express 的express.json()中间件未生效需检查server.js中app.use(express.json())是否在app.post()之前。5.5 第五层诊断后端模型服务Ollama/DeepSeek最终所有请求都会落到backend.provider指向的服务上。以 Ollama 为例验证其健康状态# 检查 Ollama 是否运行 ollama list # 应显示 codellama:13b 状态为 running # 直接调用 Ollama API 测试 curl http://localhost:11434/api/tags # 应返回所有已拉取模型的 JSON 列表 # 发送一个测试请求 curl -X POST http://localhost:11434/api/chat \ -H Content-Type: application/json \ -d { model: codellama:13b, messages: [{role: user, content: hi}] }如果 Ollama 的测试请求失败问题与 OpenRig 无关需单独解决 Ollama 配置。常见原因包括模型未正确拉取ollama pull codellama:13b、GPU 驱动未安装Linux 需nvidia-container-toolkit、内存不足导致模型加载失败。下表总结了cc switch local proxy failed错误的五大根因及对应解决方案排查层级具体现象根本原因解决方案验证命令进程层tmux ls无输出start.sh执行失败或路径错误检查当前目录结构确保server.js和package.json存在ls -la网络层curl http://localhost:3000返回connection refusedNode.js 未监听端口或端口被占用检查server.js中app.listen()参数用lsof -i :3000查端口占用lsof -i :3000配置层curl http://localhost:3000/completions返回404server.js中路由未定义或路径不匹配确保app.post(/completions, ...)路由存在且config.yaml中codex.endpoint与之匹配curl -v http://localhost:3000/completions代理层curl http://localhost:3000/completions返回500http-proxy-middleware配置错误或目标服务不可达检查targetURL 是否正确用curl直接测试目标服务如http://localhost:11434/api/chatcurl http://localhost:11434/api/chat模型层Ollama 测试请求返回500或超时模型未加载、GPU 资源不足、内存溢出重启 Ollama (ollama serve)检查ollama list状态降低模型参数如换codellama:3bollama list最后提醒所有排查步骤必须按顺序执行跳过任何一层都可能导致误判。我曾在一个案例中客户坚持认为是 Codex 插件 bug折腾两天后才发现config.yaml里backend.provider字段多了一个空格导致整个配置解析失败Node.js 服务压根没启动。真正的故障排查永远始于最基础的进程和端口检查。6. 进阶将 OpenRig 扩展为多模型智能路由中枢当你的 OpenRig 环境稳定运行后它的价值远不止于代理单一模型。凭借其 YAML 驱动的设计你可以轻松将其升级为一个智能路由中枢Smart Routing Hub根据代码上下文、文件类型甚至用户指令自动选择最合适的后端模型。这不再是简单的代理而是一个具备决策能力的本地 AI 网关。实现这一目标的核心是重构server.js中的请求分发逻辑。不再硬编码targetUrl而是基于 Codex 请求体中的model字段、messages内容长度、甚至language如果 Codex 提供进行动态路由。下面是一个增强版的路由策略示例// 在 server.js 的 /completions 处理函数中替换原有逻辑 app.post(/completions, async (req, res) { const { model, messages } req.body; let targetUrl; // 策略1根据 model 名称路由 if (model.includes(codellama)) { targetUrl http://localhost:11434/api/chat; } else if (model.includes(deepseek)) { targetUrl http://localhost:8000/v1/chat/completions; } else if (model.includes(phi)) { targetUrl http://localhost:8080/completion; } // 策略2根据消息长度路由短文本用轻量模型长文本用大模型 const contentLength messages.reduce((sum, msg) sum msg.content.length, 0); if (contentLength 200) { targetUrl http://localhost:11434/api/chat; // codellama:3b } else if (contentLength 1000) { targetUrl http://localhost:11434/api/chat; // codellama:13b } else { targetUrl http://localhost:8000/v1/chat/completions; // deepseek-coder-33b } // 策略3根据文件扩展名路由.py 文件优先用 code-llama.js 用 phi-3 const language req.headers[x-codex-language] || unknown; if (language python) { targetUrl http://localhost:11434/api/chat; } else if (language javascript) { targetUrl http://localhost:8080/completion; } // 执行代理 const proxy createProxyMiddleware({ target: targetUrl, changeOrigin: true, timeout: config.backend[timeout-ms] }); proxy(req, res); });这个增强版路由让 OpenRig 从“静态代理”进化为“上下文感知网关”。你可以在 Codex 插件设置中依然只填写http://localhost:3000但背后的模型选择已由 OpenRig 自动完成。用户无需关心哪个模型在跑只需专注于编码。更进一步你可以将路由策略外置到一个独立的routing.yaml文件中让非技术人员也能修改规则# routing.yaml rules: - condition: model auto action: route_by_language - condition: content_length 200 action: use_model: codellama:3b - condition: language python action: use_model: codellama:13b - condition: language javascript action: use_model: phi-3-mini然后在server.js中加载并解析这个规则文件用eval()或专用规则引擎如json-rules-engine执行判断。这种设计让 OpenRig 的扩展性达到企业级水平——它不再是一个个人玩具而是一个可被团队共享、可被 DevOps 流水线管理的基础设施组件。我个人在实际使用中发现这种多模型路由带来的最大收益不是性能提升而是开发体验的平滑过渡。当团队从codellama:3b迁移到deepseek-coder-33b时无需通知每个开发者去修改 Codex 设置只需更新routing.yaml中的一行规则所有人的 IDE 就自动切换到了新模型。这种“零感知升级”正是 OpenRig 作为基础设施的价值所在。