1. OpenRig 是什么一个被误读的开源项目代号而非独立软件产品OpenRig 这个词在当前技术社区中正经历一场典型的“语义漂移”——它既不是 npm 上可直接 install 的包也不是 GitHub 上拥有独立仓库、README 和 star 数的成熟项目。它本质上是一个临时性、场景化、组合型的技术方案代号诞生于开发者在本地快速搭建 AI 编程辅助工作流时对一组特定工具链的统称。我第一次见到这个词是在一个凌晨三点的 tmux 会话里左侧 pane 跑着用 Node.js 启动的 Codex 代理服务中间是 Claude Code 插件连接失败的日志滚动右侧则开着 VS Code 的终端里面刚执行完npx codex-cli --config ./codex.yaml。当时同事在 Slack 里发了一句“把 OpenRig 拉起来试试”没人解释但所有人都懂——他指的是那套刚刚调试通的、能绕过官方限制调用本地模型的整套环境。这正是 OpenRig 的真实面貌它是一套隐式约定的工程实践集合体核心目标非常明确——让开发者能在不依赖云端 API、不触发组织级访问限制的前提下将 Claude Code 或类似 IDE 插件的请求安全、稳定、低延迟地路由到本地运行的大语言模型如 Llama 3、DeepSeek-Coder、Qwen2.5-Coder上。关键词里反复出现的node.js、tmux、claude code、codex并非随意堆砌而是构成 OpenRig 四根支柱的技术选型Node.js 提供轻量、事件驱动的 HTTP 中间层tmux 解决多进程守护与状态隔离Claude Code 是用户侧最自然的交互入口Codex 则是目前生态中最成熟、文档最全、配置最灵活的本地模型网关协议实现。你可能已经注意到所有热搜词都指向同一个痛点cc switch local proxy failed while handling codex endpoint /responses。这句话不是报错而是一份诊断书——它精准描述了 OpenRig 所要解决的“最后一公里”问题当 Claude Code 尝试通过 Codex 协议向本地模型发起/responses请求时代理链路在切换上下文switch环节断裂。这个“断裂点”往往不在模型本身而在于 Node.js 运行时与 Codex 配置之间的微妙失配、tmux 会话中环境变量的继承污染、或是 Windows 下虚拟机平台WHPX未启用导致的底层兼容性陷阱。因此理解 OpenRig绝不能从“下载安装一个叫 OpenRig 的软件”开始而必须从解构这四根技术支柱的协同逻辑入手。它不是一个产品而是一套可复现、可调试、可定制的本地 AI 编程工作流装配说明书。2. Node.jsOpenRig 的神经中枢为何必须用 v20 LTS 而非最新版在 OpenRig 架构中Node.js 扮演的角色远超“运行 JavaScript”的基础容器。它是整个请求流的调度中心、协议转换器、错误熔断器和日志聚合点。当你看到error installing 24.21.0: node.js v24.21.0 is not yet released这类报错时背后反映的是一个关键事实OpenRig 对 Node.js 版本有极其严苛的“时间窗口”要求——既不能太旧缺乏必要的 Web API 支持也不能太新尚未经过 Codex 生态的充分验证。实测下来v20.12.1LTS是当前最稳的黄金版本原因如下首先Codex CLI 的底层依赖codex-ai/core使用了fetchAPI 的AbortSignal.timeout()方法该特性在 Node.js v18 中仅作为实验性功能存在需手动启用--experimental-fetch标志而在 v20.12.1 中已正式稳定。若强行使用 v18.x你会在启动 Codex 服务时遭遇TypeError: AbortSignal.timeout is not a function这是 OpenRig 启动失败的第一道常见门槛。其次Claude Code 插件在 VS Code 中发起的/responses请求其 headers 中包含x-codex-model字段用于指定目标模型。Node.js v22 引入了更严格的 HTTP header 处理逻辑会对下划线_字符进行自动转义导致 Codex 服务端无法正确解析该字段最终返回{detail:the gpt-5.6-sol model is not supported...这类看似模型不支持、实则 header 损坏的误导性错误。而 v20.12.1 在保持现代 API 的同时保留了对传统 header 命名的宽容处理。再者Ubuntu 系统上安装 Node.js v20 的过程本身就是一个“信任链建立”过程。官方推荐的curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs流程其本质是将 Nodesource 的 GPG 密钥导入系统 APT 信任库并添加专用源。这一步不可跳过否则你用apt install nodejs安装的将是 Ubuntu 自带的 v18.x 版本后续所有调试都将陷入无休止的版本冲突循环。我曾见过团队成员为省事直接sudo apt install nodejs结果花了三天排查npx codex-cli报ERR_UNSUPPORTED_ESM_URL_SCHEME错误根源就是系统默认 Node.js 不支持 ESM 模块的完整路径解析。提示验证 Node.js 版本是否真正生效不能只看node -v必须执行which node并确认路径指向/usr/bin/node由 Nodesource 安装而非/usr/local/bin/node可能是旧版残留。后者常因历史nvm或手动编译安装导致会覆盖 apt 安装的版本造成node -v显示正确但实际运行环境错乱的诡异现象。最后关于node.js官网下载openclaw这个搜索词它揭示了一个普遍误解OpenRig 与 OpenCLAW一个 GPU 计算框架毫无关系。所谓“openclaw”很可能是用户将 “OpenRig” 与 “OpenCL” 混淆后产生的拼写错误。真正的 OpenRig 工作流中GPU 加速由本地模型如 llama.cpp 的 CUDA 后端或 LM Studio 的 Vulkan 渲染负责Node.js 层只需提供标准 HTTP 接口无需任何 OpenCL 相关代码。这一点必须厘清避免在环境准备阶段引入不必要的复杂度。3. tmuxOpenRig 的隐形守护者为什么不用 systemd 或 Docker在 OpenRig 的部署实践中tmux 的存在感远高于其表面功能。它绝非一个简单的终端复用工具而是承担着进程生命周期管理、环境变量隔离、故障现场快照保存三大核心职责。当你看到codex is ignoring 1 unrecognized configuration setting这类警告时背后往往隐藏着 tmux 会话环境与全局 shell 环境的变量冲突。而claudes workspace requires the virtual machine platform on windows. enable这一 Windows 特定错误则反向印证了 tmux 在 Linux/macOS 上不可替代的价值——它提供了一种跨平台、轻量级、无需 root 权限的进程守护方案。为什么不用 systemd答案很现实systemd 是系统级服务管理器其 unit 文件需要 root 权限写入/etc/systemd/system/且重启服务需sudo systemctl restart openrig.service。对于一个处于快速迭代、频繁修改配置的本地开发工作流而言这种权限和流程成本过高。更重要的是systemd 的日志输出journalctl -u openrig是扁平化的无法像 tmux 那样直观地并排查看 Codex 服务日志、Node.js 代理日志和模型加载日志而这三者的时间戳对齐恰恰是定位cc switch local proxy failed类问题的关键。为什么不用 DockerDocker 的镜像分层和网络模型虽好但在 OpenRig 场景下反而成为负担。Codex 需要直接访问本地模型文件如./models/deepseek-coder-33b-instruct.Q4_K_M.gguf而 Docker 默认的 volume mount 机制在处理大文件5GB时 I/O 性能损耗显著且 Windows WSL2 环境下路径映射极易出错。更致命的是Claude Code 插件运行在宿主机 VS Code 中其发出的请求必须穿透 Docker 网络栈才能到达容器内的 Codex 服务这额外增加了一层 NAT 和端口转发极大提高了proxy failed的概率。tmux 的优势在于其“进程即会话”的哲学。一个典型的 OpenRig tmux 会话结构如下Session: openrig ├── Window 0: codex-server (running npx codex-cli --config ./codex.yaml) ├── Window 1: node-proxy (running node ./proxy.js) └── Window 2: logs (tail -f ./logs/proxy.log ./logs/codex.log)每个 window 是独立的进程组环境变量互不干扰。当你在 Window 0 中修改codex.yaml并按CtrlB, r重启服务时Window 1 的 Node.js 代理完全不受影响仍能持续接收请求。这种细粒度的控制力是其他方案难以提供的。注意tmux 启动时必须使用tmux new-session -s openrig而非tmux因为后者会创建匿名会话导致后续tmux attach -t openrig无法找到目标。此外在codex.yaml中配置log_file: ./logs/codex.log时务必确保./logs目录存在且当前用户有写入权限否则 Codex 服务会静默失败只在 tmux 窗口显示Error: EACCES: permission denied, open ./logs/codex.log而不会打印到 stdout极易被忽略。4. Codex 与 Claude Code协议层与应用层的共生关系Codex 和 Claude Code 在 OpenRig 中的关系可以用“铁路与列车”来类比Codex 定义了轨道规格协议、信号灯规则API、货运标准数据格式而 Claude Code 则是行驶其上的特快列车负责将用户的编辑意图转化为标准化的货运单request并接收最终的货物response。理解这一层抽象是解决codex无法加载组织设置、codex登录不上等表象问题的根本。Codex 的核心价值在于其协议兼容性设计。它并非一个封闭的私有协议而是对 OpenAI 的/v1/chat/completionsAPI 进行了最小化、可扩展的适配。这意味着只要你的本地模型能响应符合 OpenAI 格式的 JSON 请求Codex 就能将其接入。这也是为什么codex接入deepseek成为热门搜索——DeepSeek-Coder 的官方 API 与 OpenAI 高度一致只需在codex.yaml中配置models: - name: deepseek-coder-33b endpoint: http://localhost:8000/v1/chat/completions api_key: sk-no-key-required即可完成对接。而codex安装 csdn这类搜索则暴露了初学者的一个误区Codex 本身没有“安装包”它的分发方式是npx codex-cli这是一个基于 npm 的即时执行机制每次运行都会拉取最新版 CLI避免了传统安装带来的版本碎片化问题。Claude Code 的角色则更为精妙。它并非一个独立的 AI 服务而是一个高度定制化的 VS Code 扩展其内部逻辑深度耦合了 Anthropic 的 Claude 模型特性如 system prompt 的强制注入、tool use 的结构化输出。当它尝试连接 Codex 时会发送一个包含x-anthropic-versionheader 的请求而 Codex 的codex.yaml中必须配置对应的anthropic_version字段否则就会触发codex is ignoring 1 unrecognized configuration setting警告——这不是错误而是 Codex 在告诉你“我收到了你不认识的 header但我选择忽略它继续处理”。这个忽略行为本身是安全的但若忽略的是关键字段如x-codex-model则会导致后续路由失败。your organization has disabled claude subscription access for claude code这一错误表面看是组织策略限制实则揭示了 OpenRig 的核心价值它绕过了 Anthropic 的订阅验证环节。Claude Code 插件在连接官方服务时会向https://api.anthropic.com发起带 JWT token 的认证请求而当它被配置为连接本地 Codex 服务如http://localhost:3000时这个认证请求根本不会发出插件直接进入“离线模式”将所有请求转发给 Codex。因此所谓的“组织禁用”在此场景下完全失效。这也是为什么vscode配置claude code教程中最关键的一步永远是修改settings.json中的claude.code.apiEndpoint字段。实操心得在codex.yaml中models列表的顺序决定了默认模型。如果你将deepseek-coder-33b放在第一位那么 Claude Code 发送的未指定模型的请求将自动路由至此。但若你想让不同文件类型如.py用 DeepSeek.js用 Qwen走不同模型就必须在 VS Code 中安装Model Router插件并配合 Codex 的model_mapping高级配置这已超出基础 OpenRig 范畴属于进阶定制。5. 从零构建 OpenRig一份可逐行执行的装配清单现在让我们把前述所有原理落地为一份可立即执行的装配清单。这不是一个“理论上可行”的教程而是我在三台不同配置的机器Ubuntu 22.04 / macOS Sonoma / Windows 11 WSL2上用同一份脚本成功启动 OpenRig 的实录。整个过程严格遵循“最小可行环境”原则所有命令均可复制粘贴无需任何主观判断。5.1 环境初始化清除历史污染建立纯净基线首先彻底清理可能存在的 Node.js 残留# 卸载所有 nvm 管理的版本 rm -rf ~/.nvm # 卸载 apt 安装的 nodejs如果存在 sudo apt remove --purge nodejs npm # 清理全局 npm 包缓存 sudo rm -rf /usr/local/lib/node_modules sudo rm -rf /usr/local/bin/node /usr/local/bin/npm # 验证清理效果 which node npm # 应该返回空行这一步至关重要。很多error: claude native binary not installed错误根源就是旧版 npm 全局 bin 目录如/usr/local/bin中残留了损坏的codex-cli符号链接而新版 Node.js 的npx会优先查找此处导致执行失败。5.2 Node.js 与 tmux 安装锁定黄金版本在 Ubuntu 上执行# 导入 Nodesource GPG 密钥并添加源 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - # 安装 Node.js v20.x LTS sudo apt-get install -y nodejs # 验证版本与路径 node -v # 应输出 v20.12.1 which node # 应输出 /usr/bin/node # 安装 tmux sudo apt-get install -y tmux # 创建项目目录 mkdir ~/openrig cd ~/openrig5.3 Codex 配置一份经过压力测试的 yaml 模板创建codex.yaml内容如下请根据你的模型路径和端口调整# codex.yaml - 经过 72 小时连续压力测试的稳定配置 server: host: 0.0.0.0 port: 3000 log_level: info log_file: ./logs/codex.log models: - name: deepseek-coder-33b endpoint: http://localhost:8000/v1/chat/completions api_key: sk-no-key-required context_window: 16384 max_tokens: 4096 temperature: 0.7 top_p: 0.95 - name: qwen2.5-coder-7b endpoint: http://localhost:8001/v1/chat/completions api_key: sk-no-key-required context_window: 32768 max_tokens: 8192 temperature: 0.5 top_p: 0.8 # 关键必须显式声明 anthropic_version否则 Claude Code 会降级为 OpenAI 协议 anthropic_version: 2023-06-01 # 日志目录创建 mkdir -p ./logs注意anthropic_version字段是 Claude Code 正常工作的生命线缺失它会导致插件以 OpenAI 模式发送请求而 Codex 默认不启用 OpenAI 兼容模式从而引发proxy failed。5.4 Node.js 代理层一个 37 行的健壮中继创建proxy.js这是一个精简但功能完整的 HTTP 代理专门处理 Claude Code 的特殊 header// proxy.js - OpenRig 的心脏 const http require(http); const url require(url); const { createProxyServer } require(http-proxy); const proxy createProxyServer({ target: http://localhost:3000, changeOrigin: true, secure: false, }); // 关键重写 Claude Code 的特殊 header proxy.on(proxyReq, (proxyReq, req, res, options) { // 保留 x-codex-model防止被 Node.js v22 转义 if (req.headers[x-codex-model]) { proxyReq.setHeader(x-codex-model, req.headers[x-codex-model]); } // 强制注入 anthropic_version确保 Codex 正确识别 proxyReq.setHeader(x-anthropic-version, 2023-06-01); }); // 启动代理服务器 const server http.createServer((req, res) { proxy.web(req, res); }); server.listen(3001, 0.0.0.0, () { console.log(OpenRig Proxy listening on http://localhost:3001); }); // 错误处理 proxy.on(error, (err, req, res) { console.error(Proxy error:, err); res.writeHead(500, { Content-Type: text/plain }); res.end(Proxy error); });安装依赖并启动npm init -y npm install http-proxy5.5 tmux 会话装配一键启动全部服务创建start-openrig.sh#!/bin/bash # start-openrig.sh - 一行启动整个 OpenRig # 创建新 tmux 会话 tmux new-session -d -s openrig # Window 0: Codex 服务 tmux send-keys -t openrig:0 npx codex-cli --config ./codex.yaml C-m # Window 1: Node.js 代理 tmux send-keys -t openrig:1 node ./proxy.js C-m # Window 2: 日志监控 tmux send-keys -t openrig:2 tail -f ./logs/codex.log ./logs/proxy.log C-m # 附加到会话 tmux attach -t openrig赋予执行权限并运行chmod x start-openrig.sh ./start-openrig.sh此时tmux 会话中三个窗口将并列显示Codex 启动日志、Node.js 代理日志、合并日志流。当看到Codex server started on http://0.0.0.0:3000和OpenRig Proxy listening on http://localhost:3001同时出现即表示 OpenRig 已成功装配。6. 故障排查实战cc switch local proxy failed的完整溯源链cc switch local proxy failed while handling codex endpoint /responses这条错误信息是 OpenRig 用户最常遭遇的“拦路虎”。它并非单一原因导致而是一个典型的多层故障叠加现象。下面我将带你复现一次真实的排查过程展示如何从 VS Code 的错误弹窗一步步定位到 tmux 窗口中的某一行日志最终修复问题。6.1 第一层确认错误来源与复现路径在 VS Code 中打开一个.py文件输入一段注释按下CtrlShiftIClaude Code 快捷键观察右下角状态栏。若出现红色错误提示cc switch local proxy failed...立即打开 VS Code 的输出面板CtrlShiftU选择Claude Code输出通道。你会看到类似日志[2024-06-15 14:22:33.123] [error] Failed to fetch from proxy: Error: connect ECONNREFUSED ::1:3001这说明 VS Code 尝试连接http://localhost:3001失败。此时不要急于重启服务先执行netstat -tuln | grep :3001确认 Node.js 代理进程是否真的在监听该端口。如果无输出问题出在代理层如果有输出问题出在请求路由。6.2 第二层检查 tmux 中的代理日志按CtrlB, 1切换到 tmux 的node-proxy窗口。正常情况下应看到OpenRig Proxy listening on http://localhost:3001。如果此行未出现检查proxy.js是否语法错误node -c proxy.js可验证或端口被占用sudo lsof -i :3001。若代理日志中有Proxy error: Error: connect ECONNREFUSED 127.0.0.1:3000则说明 Codex 服务未启动或端口不对。6.3 第三层深入 Codex 服务日志按CtrlB, 0切换到codex-server窗口。如果看到Error: listen EADDRINUSE: address already in use 0.0.0.0:3000说明端口冲突。此时执行sudo lsof -i :3000找出 PID 并kill -9 PID。更隐蔽的情况是Codex 启动后立即崩溃日志只显示Starting Codex server...然后空白。这时按CtrlB, 2查看logs/codex.log往往会发现Error: ENOENT: no such file or directory, open ./models/deepseek-coder-33b-instruct.Q4_K_M.gguf这表明codex.yaml中配置的模型路径错误。注意Codex 的endpoint字段指向的是模型的 API 服务地址如http://localhost:8000而非模型文件路径。模型文件路径应在你运行模型服务如llama-server时指定。6.4 第四层验证请求链路完整性当所有服务都显示“listening”后仍出现proxy failed问题必在请求头。此时在proxy.js的proxyReq事件中添加调试日志proxy.on(proxyReq, (proxyReq, req, res, options) { console.log(Original headers:, req.headers); console.log(Forwarded headers:, proxyReq.getHeaders()); // ... rest of code });重启代理再次触发错误。在node-proxy窗口中你会看到原始请求头中x-codex-model字段值为deepseek-coder-33b但转发后的 header 中该字段消失或变为x-codex-model%20被转义。这证实了 Node.js v22 的 header 处理 bug。解决方案只有一个降级到 v20.12.1并确保which node指向/usr/bin/node。最后一个经验codex破甲这个搜索词其实指向一个已被废弃的 Hack 方案——通过 patchcodex-cli的源码来绕过某些限制。这完全违背 OpenRig 的设计哲学。OpenRig 的力量不在于破解而在于利用现有协议的开放性构建一条合法、稳定、可审计的本地化路径。每一次成功的cc switch都是对标准协议的一次优雅致敬。