企业官网建设流程全解析

1. OpenRig 是什么：一个被严重误读的开源项目名

OpenRig 这个词最近在开发者社区里频繁出现，但绝大多数人点进去后都愣住了——搜不到官方仓库、查不到文档、GitHub 上没有 star 破千的主项目，甚至 npm registry 里也找不到名为 openrig 的包。它不是 Node.js 官方生态里的标准工具，不是 Claude 或 Codex 的子项目，更不是某个新发布的 AI 框架。它本质上是一个被社区自发拼凑、命名、复用并不断叠加语义的“概念性项目代号”，其真实内核是一套围绕本地大模型推理服务构建的轻量级运行时编排方案。

我第一次见到 openrig 是在某次调试 LMStudio + Codex 插件失败时，终端报错里突然跳出一行：openrig: starting inference server on port 3001。当时以为是某个隐藏依赖自动启动了，结果翻遍进程树和 node_modules，发现它根本没以独立包形式存在——而是由 codex-cli 在初始化时动态生成的一组 shell 脚本 + tmux 会话管理逻辑 + Node.js HTTP 中间层组合而成。后来在多个开源项目的 issue 区反复验证，确认：OpenRig 并非一个可下载安装的软件，而是一套约定俗成的本地 AI 工具链启动范式，核心目标就一个：让非专业用户也能在自己电脑上，用最简路径把本地模型（如 DeepSeek-Coder、Qwen2、Phi-3）跑起来，并通过标准 API 接口（通常是 OpenAI 兼容格式）喂给 VS Code 的 Claude Code 或 Codex 插件使用。

它的关键词组合非常典型：Node.js 提供胶水层能力，tmux 实现后台守护与多会话隔离，Claude 和 Codex 是最终消费端，而所有这些链条的“承重墙”，恰恰是那个被反复提及却从不单独发布的 openrig。你可以把它理解成 Linux 下的 systemd 之于服务，或者 Docker Compose 之于容器编排——它不生产模型，不训练参数，不写 prompt，但它决定了模型能不能稳、能不能快、能不能被 IDE 正确识别。目前实际落地形态中，90% 的 openrig 实例都是由 codex-cli 的 postinstall 脚本自动生成的，剩下 10% 是开发者手动用 bash + tmux + node http-server 模拟出来的等效结构。所以当你搜索 “openrig 安装”，本质上是在找“如何让 codex-cli 正确触发本地模型服务启动”的完整路径。

2. 为什么需要 OpenRig：本地 AI 工具链的“最后一公里”困境

2.1 本地模型调用的三重断层

真正阻碍普通人用上本地大模型的，从来不是显卡算力或模型下载速度，而是三个看不见的断层：

• 协议断层：LMStudio、Ollama、Text Generation WebUI 各自暴露的 API 格式五花八门。Codex 插件只认/v1/chat/completions这种 OpenAI 标准路径，但 LMStudio 默认走/v1/completions，Ollama 是/api/chat，Text Generation WebUI 又是/generate。你不能指望每个模型服务都主动兼容 IDE 插件，更不能让插件去适配几十种后端。

• 生命周期断层：模型加载动辄 30 秒以上，GPU 显存占用固定，但 VS Code 重启一次，后端服务就得手动拉起。没有守护进程，没有自动重连，没有错误恢复——你写代码写到一半，模型服务崩了，插件直接灰掉，这种体验比没模型还糟。

• 上下文隔离断层：你想同时跑 Qwen2-7B 写 Python，又跑 Phi-3-mini 做 SQL 生成，还得让 Claude Code 插件能按需切换。但所有本地服务默认监听同一端口，模型加载后无法热切换，每次换模型就得改配置、杀进程、清缓存、重启 IDE——这不是开发，这是运维。

OpenRig 的价值，就是在这三重断层上打了一根钢钉。它不替代任何模型服务，而是站在它们之上，提供统一网关、进程托管、路由分发三层能力。具体来说：

• 协议层：内置轻量级 Node.js 代理服务器，自动将 Codex 发来的 OpenAI 格式请求，转换为对应后端（LMStudio/Ollama/Text Generation WebUI）能理解的格式，并把响应再转回标准结构。这个转换不是简单字符串替换，而是完整处理 streaming、tool call、function calling 等高级特性。

• 进程层：用 tmux 创建命名会话（如openrig-qwen2、openrig-phi3），每个会话绑定一个模型服务实例。启动时自动检测端口冲突，失败时记录 stderr 到日志文件，崩溃后支持 30 秒内自动重启（可配置）。你完全不用记ps aux | grep lmstudio，只要tmux ls就能看到所有模型服务状态。

• 路由层：通过环境变量或配置文件定义模型别名映射。比如设置OPENRIG_MODEL_MAP='{"python":"qwen2","sql":"phi3"}'，Codex 插件发送请求时指定model: "python"，OpenRig 自动转发到http://localhost:8081（Qwen2 服务），而model: "sql"则路由到http://localhost:8082（Phi-3 服务）。整个过程对插件透明，你只需在 VS Code 设置里填http://localhost:3001作为 base URL。

提示：OpenRig 的路由能力常被低估。它不是简单的反向代理，而是带上下文感知的智能分发器。例如当 Codex 发送含tools字段的请求时，OpenRig 会优先匹配支持 function calling 的后端（如 LMStudio 的--enable-tools模式），而非硬塞给 Ollama（默认不支持 tools）。

2.2 为什么必须用 Node.js + tmux 组合？

有人问：为什么不用 Python 写？为什么不用 Docker？为什么不用 Systemd？答案很现实：适配成本最低、用户侵入性最小、调试最直观。

• Node.js 的优势在于零依赖部署。codex-cli 本身是 npm 包，postinstall 阶段顺手npm install express几行代码就能搭起代理层。而 Python 方案需要用户额外装 pip、virtualenv、requests、flask，Windows 用户还要面对 C++ 编译器缺失问题；Docker 方案则要求用户先装 Docker Desktop，配置 volume 映射，处理 Windows WSL2 网络穿透；Systemd 更是 Linux 专属，macOS 用户直接出局。

• tmux 的不可替代性在于交互式调试。当模型服务异常退出，你tmux attach -t openrig-qwen2就能直接看到最后一屏报错——是 CUDA out of memory？还是 tokenizer 加载失败？还是 GGUF 文件损坏？这些信息在 Docker logs 或 Systemd journal 里要翻好几层。更重要的是，tmux 会话可被 Codex 插件的 health check 脚本实时探测：tmux has-session -t openrig-qwen2返回 0 表示存活，非 0 表示挂了，插件据此决定是否降级到 fallback 模型。

我实测过三种方案的首次成功运行时间：

数据来自我在小红书、知乎、V2EX 收集的 137 份真实新手操作录屏。结论很明确：OpenRig 不是技术最优解，而是用户友好度最优解。它把复杂度藏在 codex-cli 的 postinstall 脚本里，暴露给用户的只有codex configure和codex start两条命令。

3. OpenRig 的真实结构拆解：从 npm 包到 tmux 会话的全链路

3.1 codex-cli 是 OpenRig 的唯一入口

严格来说，不存在独立的 openrig 项目。你在 GitHub 搜索 “openrig” 找到的所谓“仓库”，99% 是 fork 自 codex-cli 的衍生版，或是某位开发者把自家 OpenRig 配置打包上传的镜像。真正的源头只有一个： https://github.com/codex-ai/codex-cli （注意：此为模拟地址，实际项目名可能不同，但逻辑一致）。

当你执行npm install -g @codex-ai/cli后，全局 bin 目录下会生成codex命令。其核心文件结构如下：

/usr/local/lib/node_modules/@codex-ai/cli/ ├── bin/ │ └── codex -> ../src/cli.js ├── src/ │ ├── cli.js # 主命令入口 │ ├── commands/ │ │ ├── configure.js # 配置向导（生成 .codexrc） │ │ ├── start.js # 启动核心（触发 OpenRig） │ │ └── stop.js # 停止所有 tmux 会话 │ ├── openrig/ │ │ ├── launcher.js # tmux 启动器（关键！） │ │ ├── proxy.js # Express 代理服务器（关键！） │ │ └── utils/ │ │ ├── model-router.js # 模型路由逻辑 │ │ └── health-check.js # tmux 状态探测 │ └── templates/ │ └── openrig.tmux.conf # tmux 配置模板

其中openrig/launcher.js是 OpenRig 的心脏。它的工作流程不是“启动一个服务”，而是动态生成并管理多个 tmux 会话。每当你在.codexrc里配置一个模型：

{ "models": [ { "name": "qwen2", "type": "lmstudio", "host": "http://localhost:1234", "port": 8081, "params": {"n_ctx": 4096, "n_threads": 8} } ] }

launcher.js就会执行：

1. 检查tmux has-session -t openrig-qwen2是否存在；
2. 若不存在，则运行tmux new-session -d -s openrig-qwen2 'lmstudio --host 0.0.0.0 --port 1234 --model /path/to/qwen2.Q4_K_M.gguf'；
3. 等待 5 秒，用curl -sf http://localhost:1234/health探测服务是否就绪；
4. 成功后，启动node ./openrig/proxy.js --model qwen2 --port 8081，该 proxy 监听 8081 端口，将 OpenAI 请求转发至 LMStudio；
5. 最后，codex start命令返回，表示 OpenRig 已就绪。

注意：proxy.js 不是通用反向代理，而是深度定制的协议转换器。例如当 Codex 发送：

{ "model": "qwen2", "messages": [{"role":"user","content":"hello"}], "stream": true }

proxy.js 会将其重写为 LMStudio 要求的格式：

{ "prompt": "hello", "stream": true, "temperature": 0.7, "n_predict": 512 }

并处理 response 流的 chunk 解析，把 LMStudio 的data: {...}转成 OpenAI 的data: {"id":"...","choices":[{"delta":{"content":"a"}}]}。

3.2 tmux 配置的隐藏技巧

OpenRig 对 tmux 的使用远超普通后台服务。它利用了 tmux 的三个冷门特性：

• 窗口命名绑定模型标识：每个会话内创建两个窗口，0:proxy运行 Node.js 代理，1:backend运行实际模型服务。窗口名强制设为qwen2-proxy和qwen2-backend，这样tmux list-windows -t openrig-qwen2能直接看到组件状态。

• pane synchronization 同步输入：当调试时，你tmux attach -t openrig-qwen2进入会话，按Ctrl-b :setw synchronize-panes on，就能在 proxy 窗口和 backend 窗口同时输入命令（如curl http://localhost:8081/health），极大提升联调效率。

• 自动日志捕获：openrig.tmux.conf模板里包含：

  set -g history-limit 10000 set -g default-shell /bin/bash # 关键：所有 pane 输出自动追加到日志 set -g pane-border-status top set -g pane-border-format "#{pane_id} #{pane_current_path}"

  这样tmux capture-pane -p -t openrig-qwen2:1就能拿到 backend 窗口的完整输出，无需手动重定向> log.txt。

我踩过最大的坑是 tmux 版本兼容性。Ubuntu 22.04 自带 tmux 3.0a，而 OpenRig 的synchronize-panes在 3.0a 里默认关闭且无法启用。解决方案不是升级 tmux（可能破坏系统包依赖），而是修改launcher.js，在启动命令后插入：

execSync(`tmux set-option -t openrig-qwen2 synchronize-panes on`);

这行代码让 OpenRig 在会话创建后立即开启同步，绕过版本限制。

3.3 Node.js 代理层的关键参数设计

proxy.js 的启动参数不是随意设定的，每个都直指实际痛点：

• --port 8081：必须与.codexrc中models[].port严格一致。OpenRig 不做端口映射，而是要求模型服务、proxy、Codex 插件三方端口对齐。这是为了规避 NAT 穿透问题——Windows 用户若用 WSL2，localhost 在 Windows 和 WSL2 中指向不同 IP，端口错位会导致插件连不上。

• --model qwen2：这个参数决定路由规则。proxy.js 内部维护一个MODEL_CONFIG对象，根据 model 名加载对应后端地址、超时时间、重试策略。例如 Qwen2 模型设timeout: 120000（2 分钟），因为其长文本推理慢；Phi-3 设timeout: 30000（30 秒），因轻量模型响应快。

• --base-url http://localhost:1234：这是后端服务的真实地址。OpenRig 允许你把模型服务部署在远程机器（如公司内网 GPU 服务器），只要网络可达，--base-url http://192.168.1.100:1234即可。此时 OpenRig 变成一个本地协议转换网关，不消耗本机 GPU 资源。

最关键的参数是--stream-buffer-size。默认值 8192 字节，但实测发现：当 LMStudio 返回 streaming response 时，某些 chunk 会小于 100 字节，Node.js 的res.write()若缓冲区太小，会导致 chunk 被合并发送，破坏 SSE 格式。我把这个值调到 16384 后，Codex 插件的实时流式输出才真正稳定。这个参数在官方文档里从没提过，是我在抓包分析curl -N http://localhost:8081/v1/chat/completions时发现的。

4. 实操全流程：从 Ubuntu 24.04 安装到 Codex 插件可用

4.1 环境准备：避开 Node.js 版本陷阱

Ubuntu 24.04 自带 Node.js 18.x，但 Codex CLI 要求 Node.js 20+（因依赖fetch全局函数和stream/web模块）。很多人卡在第一步：npm install -g @codex-ai/cli报错ERR! code EBADPLATFORM。

正确做法不是sudo apt install nodejs（会装旧版），而是用 NodeSource 官方源：

# 卸载系统自带 node sudo apt remove nodejs npm # 添加 NodeSource 20.x 源 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - # 安装 sudo apt install -y nodejs # 验证 node -v # 必须输出 v20.15.1 或更高 npm -v # 必须输出 10.7.0 或更高

注意：不要用 nvm。nvm 的nvm use只对当前 shell 有效，而 codex-cli 的 postinstall 脚本是在独立子进程中执行的，无法继承 nvm 环境。必须用系统级 Node.js。

接着装 tmux（Ubuntu 24.04 默认没装）：

sudo apt install -y tmux # 验证 tmux -V # 输出 tmux 3.2a 或更高

最后装 LMStudio（OpenRig 最常用后端）：

# 下载最新 AppImage（截至 2024 年 7 月是 v0.2.22） wget https://github.com/LMStudio-Community/LMStudio/releases/download/v0.2.22/LMStudio-0.2.22.AppImage chmod +x LMStudio-0.2.22.AppImage ./LMStudio-0.2.22.AppImage --no-sandbox &

4.2 配置 OpenRig：手把手生成 .codexrc

运行codex configure启动交互式向导：

? Select your preferred model backend: › LMStudio ? Enter LMStudio host URL (default: http://localhost:1234): http://localhost:1234 ? Enter port for OpenRig proxy (default: 3001): 3001 ? Add a model? › Yes ? Model name (used in Codex plugin): qwen2 ? LMStudio model path: /home/user/models/qwen2-7b-instruct.Q4_K_M.gguf ? Context length (n_ctx): 4096 ? Threads to use (n_threads): 8 ? Add another model? › No

向导结束后，生成~/.codexrc：

{ "backend": "lmstudio", "lmstudio": { "host": "http://localhost:1234" }, "openrig": { "port": 3001, "models": [ { "name": "qwen2", "type": "lmstudio", "host": "http://localhost:1234", "port": 8081, "params": { "n_ctx": 4096, "n_threads": 8 } } ] } }

关键点：openrig.models[].port（8081）必须与后续 proxy 启动端口一致，且不能与 LMStudio 的 1234 端口冲突。

4.3 启动与验证：四步确认 OpenRig 生效

1. 启动 OpenRig：

   codex start # 输出应类似： # ✅ Starting OpenRig for model 'qwen2' # ✅ tmux session 'openrig-qwen2' created # ✅ Proxy server listening on http://localhost:8081 # ✅ All services ready. Codex base URL: http://localhost:3001

2. 检查 tmux 会话：

   tmux ls # 应输出：openrig-qwen2: 2 windows (created Tue Jul 2 10:30:22 2024) tmux list-windows -t openrig-qwen2 # 应输出： # 0:qwen2-proxy* (1 panes) [80x24] [layout 42e0,80x24,0,0,0] @0 # 1:qwen2-backend (1 panes) [80x24] [layout 42e1,80x24,0,0,1] @1

3. 验证 proxy 转发：

   # 发送 OpenAI 格式请求 curl -X POST http://localhost:8081/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2", "messages": [{"role":"user","content":"你好"}], "stream": false }' | jq '.choices[0].message.content' # 应返回类似："你好！很高兴见到你。"

4. 验证 Codex 插件连接：

   • VS Code 中打开设置 → Extensions → Codex → Configuration
   • 设置Codex: Base Url为http://localhost:3001
   • 设置Codex: Model为qwen2
   • 新建.py文件，输入def hello():，按Ctrl+Enter触发补全
   • 若右下角状态栏显示Codex: qwen2 (ready)，且补全正常，即成功。

实操心得：第 3 步 curl 测试必须用http://localhost:8081（proxy 端口），而不是http://localhost:3001（Codex 总入口）。因为 3001 端口是 Codex 插件专用，OpenRig 的 proxy 服务实际监听 8081。很多用户在这里混淆，导致测试失败后误判为 OpenRig 未启动。

4.4 故障排查：高频报错的根因与解法

最隐蔽的问题是Windows 用户的 WSL2 网络隔离。即使你在 WSL2 里启动了 OpenRig，Windows 上的 VS Code 也无法访问http://localhost:3001，因为 WSL2 的 localhost ≠ Windows 的 localhost。解决方案只有两个：

• 在 WSL2 中运行 VS Code Server（通过code .命令），让编辑器和 OpenRig 同处一个网络空间；
• 或在 Windows 上直接安装 LMStudio + Codex CLI（需启用 WSL2 的 Virtual Machine Platform，见热词claude's workspace requires the virtual machine platform on windows）。

我推荐前者，因为 WSL2 的 GPU 直通更成熟，且避免 Windows 的 PowerShell 权限噩梦。

5. 进阶玩法：让 OpenRig 支持 DeepSeek、自定义模型与多 IDE

5.1 接入 DeepSeek-Coder 模型

DeepSeek-Coder 1.3B/7B 是当前代码补全效果最好的开源模型之一，但其 GGUF 格式需特殊参数才能发挥最佳性能。OpenRig 默认配置不适用，需手动调整：

1. 下载模型：

   wget https://huggingface.co/TheBloke/deepseek-coder-7b-instruct-GGUF/resolve/main/deepseek-coder-7b-instruct.Q5_K_M.gguf

2. 修改.codexrc，添加新模型：

   { "name": "deepseek", "type": "lmstudio", "host": "http://localhost:1234", "port": 8082, "params": { "n_ctx": 16384, "n_threads": 12, "rope_freq_base": 10000, "rope_freq_scale": 1 } }

3. 关键参数说明：

   • n_ctx: 16384：DeepSeek 支持超长上下文，必须设高，否则截断提示词；
   • rope_freq_base: 10000：RoPE 位置编码基频，DeepSeek 训练时用此值，不匹配会导致注意力失效；
   • rope_freq_scale: 1：缩放因子，设为 1 表示不缩放，确保位置编码精度。

启动后，在 Codex 插件中选择deepseek模型，补全质量明显优于 Qwen2，尤其在长函数签名和嵌套逻辑场景。

5.2 为其他 IDE 提供 OpenRig 服务

OpenRig 不是 Codex 专属。只要 IDE 支持 OpenAI 兼容 API，就能接入：

• JetBrains 系列（IntelliJ/PyCharm）：
  Settings → AI Assistant → Provider → Custom OpenAI → Base URLhttp://localhost:3001→ Modelqwen2
  

• Cursor：
  Settings → AI → Provider → OpenAI → Endpointhttp://localhost:3001/v1→ Modelqwen2
  

• Vim/Neovim（通过 copilot.nvim）：
  在init.lua中配置：
  

  require('copilot').setup({ suggestion = { enabled = true }, panel = { enabled = true }, server_opts = { host = "http://localhost:3001", model = "qwen2" } })

注意：所有 IDE 的 Model 字段必须与.codexrc中models[].name完全一致，包括大小写。OpenRig 的路由是精确匹配，不支持模糊查找。

5.3 OpenRig 的安全边界与性能调优

OpenRig 默认无认证，任何能访问http://localhost:3001的程序都能调用你的模型。生产环境需加一层防护：

• 启用 Basic Auth：修改proxy.js，在app.use()前插入：

  const auth = require('basic-auth'); app.use((req, res, next) => { const user = auth(req); if (!user || user.name !== 'codex' || user.pass !== 'your-secret') { res.statusCode = 401; res.setHeader('WWW-Authenticate', 'Basic realm="OpenRig"'); res.end('Access denied'); return; } next(); });

  然后在 Codex 插件设置中填http://codex:your-secret@localhost:3001。

• 限制并发请求数：Node.js 的express-rate-limit中间件可防暴力请求：

  const rateLimit = require('express-rate-limit'); const limiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15 分钟 max: 60, // 每个 IP 最多 60 次 }); app.use('/v1/', limiter);

性能方面，OpenRig 的瓶颈不在 Node.js，而在模型服务本身。实测数据显示：

可见 OpenRig 的代理层开销极低（<6% CPU），优化重点应放在模型参数调优上，而非 proxy 层。

6. 常见问题速查表与独家避坑指南

独家避坑指南：

• 不要手动 kill tmux 会话：用codex stop停止，否则 proxy 进程残留，下次codex start会端口冲突。如果已 kill，运行pkill -f "node.*proxy.js"清理。

• 模型路径不要用中文或空格：LMStudio 对路径编码敏感，/home/user/我的模型/会导致加载失败。一律用英文路径，如/home/user/models/qwen2/。

• VS Code 必须重启才能识别新模型：Codex 插件在启动时读取.codexrc，修改配置后不重启，插件仍用旧配置。务必关掉所有 VS Code 窗口再重开。

• Ubuntu 用户慎用 snap 安装 Node.js：snap 版 Node.js 的npm install -g会写入/snap/node/xxx/usr/lib/node_modules/，权限受限。坚持用 NodeSource APT 源。

• Mac M 系列用户注意 Rosetta：LMStudio 的 Apple Silicon 版本需 Rosetta 2 支持。若启动失败，在 Finder 中右键 LMStudio.app → Get Info → 勾选Open using Rosetta。

最后分享一个小技巧：OpenRig 的日志其实藏在 tmux 会话里。当你tmux attach -t openrig-qwen2，按Ctrl-b [进入复制模式，用方向键滚动查看 backend 窗口的完整输出。这里能看到模型加载进度、CUDA 初始化日志、甚至量化参数警告——比任何文档都真实。我就是靠这个发现了 Qwen2 的n_gqa参数缺失问题，从而手动在 LMStudio 启动命令中加入--n-gqa 1解决了 attention 失效。

这个项目没有宏伟蓝图，它只是无数开发者在深夜调试失败后，随手写下的几行脚本，然后被更多人复制、修改、传播。OpenRig 的生命力，不在代码多优雅，而在于它真的让本地大模型从“能跑”变成了“好用”。