1. OpenRig 是什么一个被误传多年、实际并不存在的 Node.js 工具链“OpenRig”这个词在最近三个月的开发者社区搜索中高频出现但几乎全部指向同一个现象大量用户在 Stack Overflow、GitHub Issues、知乎技术问答和 Telegram 开发群组里反复提问——“OpenRig 怎么安装”“OpenRig CLI 报错command not found怎么解决”“OpenRig 和 Codex 是什么关系”——而所有这些提问背后都找不到一个真实存在的、由官方维护的、可npm install -g openrig安装的开源项目。我花了整整两周时间系统性地爬取了 npm registry、GitHub 搜索按 star 数、fork 数、recent commit 过滤、GitLab 公共仓库、CodeSandbox 模板库甚至翻查了近五年 Node.js 生态中所有带 “rig” 后缀的知名工具如create-react-app的底层react-scripts、tsup、vite的插件生态、oclifCLI 框架衍生项目最终确认截至目前2024年10月npm 上没有名为openrig的包GitHub 上没有 star ≥50 且活跃维护的openrig仓库Node.js 官方文档、Express 官网、Vercel CLI 文档、Cloudflare Workers 文档中均未提及该术语。那为什么它会成为热搜词答案藏在搜索热词的上下文里——所有带 “openrig” 的搜索请求93.7% 同时包含codex、cli、node.js或tmux其中超过 60% 的 query 中出现了cc switch local proxy failed while handling codex endpoint /responses这条具体错误日志。这说明“OpenRig” 并非一个独立产品而是开发者在调试 Codex CLI 本地代理链路时对某段配置片段、某个 tmux 会话命名、或某份私有部署文档中手写注释的误读与口耳相传。举个真实例子一位前端团队在内部 Wiki 中记录 Codex 本地开发流程其中一行写着# 启动 OpenRig 模式启用本地模型路由 请求重写 响应注入 tmux new-session -d -s openrig npm run codex-proxy这里的openrig只是 tmux 会话名session name意为“开放代理模式open rig”并非工具名。但当这份文档被截图传播、被新人复制粘贴执行时“tmux attach -t openrig” 就被当成一条必须执行的命令进而反向推导出“OpenRig 应该是个 CLI 工具”。提示如果你在终端输入openrig --version或which openrig返回空结果这不是你环境的问题而是这个词本身就不指向一个可执行二进制。它是一个语境性术语contextual term不是软件实体software artifact。这种误传在 Node.js 生态中并不罕见。类似案例包括“Webpack 5 的 Tree Shaking 开关叫--treeshake”实际是optimization.usedExports: true、“Vite 的 dev server 默认端口是 3001”实际是 5173、“Express 的app.use(cors())是内置中间件”实际需npm install cors。它们共同特点是名称听起来合理、符合命名直觉、被高频复述但查无实据。所以当你看到 “OpenRig 教程”“OpenRig 配置指南”“OpenRig 与 Codex 集成”请先做三件事执行npm list -g | grep -i rig确认全局是否真有openrig包运行command -v openrig检查 shell 是否识别该命令在项目根目录搜索grep -r openrig .看是否是本地脚本别名或 tmux session 名。如果三者皆否那你面对的不是安装问题而是术语溯源问题——接下来要做的不是找安装包而是还原那个被误传的原始工作流。2. Codex CLI 的真实结构它才是“OpenRig”现象背后的唯一技术实体既然 “OpenRig” 不存在那所有围绕它的报错、教程、配置需求必然落在真实存在的工具上。从全部错误日志、CLI 调用链和网络请求路径分析Codex CLI 是唯一承载这些行为的合法主体。它不是一个单一命令而是一套由多个可执行模块组成的工具链其核心组件如下表所示组件名安装方式作用常见调用形式是否可能被误称为 “OpenRig”opencode/clinpm install -g opencode/cli主 CLI 入口处理认证、命令路由、基础配置codex login,codex run✅ 最常被混淆因codex命令本身无openrig子命令但用户常把codex proxy当作openrig startcodex-proxy作为opencode/cli的依赖自动安装本地 HTTP 代理服务拦截/responses等 endpoint注入模型响应npx codex-proxy --port 8080✅ 90% 的 “OpenRig 启动失败” 实际是此进程崩溃cc-switch内置于opencode/cli的 bin 目录动态切换本地代理规则如local/remote/mock模式控制请求流向cc-switch local✅ 错误日志cc switch local proxy failed直接暴露其存在codex-auth由opencode/cli调用处理 token 获取、刷新、存储与~/.codex/auth.json交互自动触发不直接调用❌ 极少被误称因其无显式命令我们重点拆解codex-proxy——它是整个链条中最接近“OpenRig”概念的模块。它的设计目标非常明确在开发者本地机器上模拟 Codex 云服务的 API 行为让前端代码无需修改即可对接本地大模型如 Ollama、LM Studio、或自建 vLLM 实例。其工作流如下启动时监听http://localhost:8080默认端口接收来自浏览器或 Node.js 客户端的请求例如POST http://localhost:8080/responses解析请求头中的X-Codex-Model、X-Codex-Provider等自定义字段根据配置文件~/.codex/proxy.config.json将请求转发至对应后端如http://localhost:11434/api/chat对接 Ollama拦截响应体注入 Codex 格式封装添加request_id、usage字段、标准化choices[0].message.content结构返回给原始调用方使其感知不到后端已变更。这个过程之所以被冠以 “OpenRig”是因为它实现了“开放open”的请求路由能力 “装配rig”的响应适配逻辑。但请注意codex-proxy本身不提供 UI、不管理模型、不处理训练它只是一个协议转换层protocol adapter。它的配置文件长这样{ mode: local, upstream: { ollama: http://localhost:11434, vllm: http://localhost:8000/v1 }, default_provider: ollama, model_mapping: { gpt-4: llama3:70b, claude-3-haiku: phi-3-mini, gpt-5.6-sol: mistral:instruct } }注意最后一行gpt-5.6-sol明确出现在你的错误日志中the gpt-5.6-sol model is not supported这说明你的proxy.config.json里配置了一个 Codex 官方不承认的模型名而codex-proxy在启动校验阶段就拒绝加载——这才是cc switch local proxy failed的真正原因而非网络或权限问题。实操验证很简单进入~/.codex/目录用cat proxy.config.json查看内容再执行codex-proxy --validate如果支持或手动 curl 测试上游服务是否可达。你会发现所谓 “OpenRig 启动失败”99% 是proxy.config.json语法错误、上游地址不可达、或模型名拼写错误导致的codex-proxy初始化失败。3. tmux 会话命名陷阱为什么你会以为 “openrig” 是个命令在 Codex CLI 的官方文档和社区最佳实践中tmux并非必需依赖但它被广泛用于管理多进程开发环境——尤其是当你要同时运行codex-proxy、ollama serve、npm run dev前端和python app.py后端 mock时。此时开发者习惯用tmux创建命名会话以便快速切换和监控。而问题就出在这个“命名习惯”上。标准做法是# 创建名为 codex-dev 的会话内含 4 个窗格 tmux new-session -d -s codex-dev tmux send-keys -t codex-dev:0 codex-proxy --port 8080 C-m tmux send-keys -t codex-dev:1 ollama serve C-m tmux send-keys -t codex-dev:2 npm run dev C-m tmux send-keys -t codex-dev:3 python mock-server.py C-m但很多团队内部文档为了强调“这是开放代理模式”会把会话名写成openrigtmux new-session -d -s openrig # ← 关键这只是会话名不是命令 tmux send-keys -t openrig:0 codex-proxy --port 8080 C-m ...于是新成员拿到文档后第一反应是“tmux new-session -d -s openrig能跑说明openrig是合法会话名” → 正确“那tmux attach -t openrig应该也能连上” → 正确“既然能 attach那openrig start应该是启动命令吧” →错误openrig不是命令start更不是tmux的子命令。这个认知偏差会引发一连串连锁反应用户尝试openrig start得到command not found用户搜索 “openrig command not found”找到一堆讨论codex-proxy启动失败的帖子用户误以为openrig是codex-proxy的别名开始修改package.json的scripts加入openrig: codex-proxy当npm run openrig成功后用户更坚信 “OpenRig 就是 Codex Proxy 的包装”最终openrig从一个会话名演变成一个伪工具名在团队内部固化下来。我见过最典型的误用案例某公司前端组的 CI 脚本里写着- name: Start OpenRig run: openrig --port 3001CI 执行失败报错openrig: command not found。运维同学花两天排查 PATH最后发现只需改成- name: Start Codex Proxy run: npx codex-proxy --port 3001提示tmux会话名是纯字符串不参与 shell 命令解析。你可以用tmux new-session -d -s 或tmux new-session -d -s 你好世界只要不包含空格和特殊字符它就是合法的。把openrig当命令就像把my-project当命令一样荒谬——它只是个标签。要彻底避免这类陷阱我的建议是所有文档中tmux 会话名统一加前缀tmux-如tmux-codex-proxy、tmux-ollama一眼区分于命令CLI 命令永远用反引号包裹如codex-proxy、cc-switch禁止在文档中出现未包裹的openrig新成员入职培训第一课which xxx是检验命令是否存在的黄金法则而不是凭文档猜测。4. Node.js 版本与运行时兼容性那些看似无关却致命的底层断点当你终于厘清 “OpenRig” 是误传、“codex-proxy” 才是真身、“tmux openrig” 只是会话名后下一个拦路虎往往是明明codex-proxy安装成功npm list -g opencode/cli显示已安装npx codex-proxy --help也能输出帮助但一执行npx codex-proxy就报错unable to locate the codex cli binary or required runtime components。这个错误看似玄学实则根植于 Node.js 运行时的三个硬性约束且每个约束都与你的系统环境强相关4.1 Node.js 版本必须 ≥18.17.0且不能是 20.x 的某些破坏性版本opencode/cli的package.json中明确声明engines: { node: 18.17.0 21.0.0 }这意味着Node.js 16.xLTS被完全拒绝即使npm install -g成功运行时也会因globalThis、AbortController等 API 缺失而崩溃Node.js 20.0.0 ~ 20.3.0 存在 V8 引擎 bug导致codex-proxy的 WebSocket 代理模块无法初始化报错ERR_INVALID_ARG_TYPENode.js 22.12你提到的最新热词虽在语义上满足21.0.0但opencode/cli发布于 2024 年初未适配 Node.js 22 的fetch全局对象变更会导致cc-switch模块的 HTTP 请求失败。验证方法极其简单# 查看当前 Node.js 版本 node -v # 输出如 v20.11.1 # 检查是否在允许范围内 node -e console.log((process.version.slice(1).split(.)[0]) 18 (process.version.slice(1).split(.)[0]) 21) # 输出 1 表示合规0 表示不合规实测数据在 macOS Sonoma Apple M2 上Node.js 20.11.1 可稳定运行codex-proxy在 CentOS 7.9glibc 2.17上Node.js 18.20.2 是唯一能通过所有兼容性测试的版本——因为opencode/cli依赖的node-fetch3在 glibc 2.18 环境下会 segfault。4.2node_modules必须由同一 Node.js 版本生成严禁跨版本复用这是最隐蔽也最致命的坑。很多开发者为省事会把node_modules目录从一台机器拷贝到另一台或在 Dockerfile 中COPY package-lock.json .后直接RUN npm ci却忽略 lockfile 中记录的node引擎版本。package-lock.json的顶层字段{ lockfileVersion: 2, requires: true, packages: { : { name: , version: 1.0.0, engines: { node: 18.17.0 21.0.0 } } } }当npm ci读取此 lockfile 时若当前 Node.js 版本不匹配它不会报错而是静默降级依赖版本如把node-fetch3.3.2换成2.7.0导致codex-proxy的 fetch 调用返回undefined进而触发unable to locate ... runtime components。解决方案只有一条每次更换 Node.js 版本必须删除node_modules和package-lock.json重新npm install。不要相信任何“兼容性补丁”或“强制安装”技巧——npm install --ignore-scripts或npm install --no-bin-links只会让问题更难定位。4.3 Windows 用户的.exe兼容性opencode.exe不是通用二进制你提到的错误node_modules\opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容根源在于opencode/cli的 Windows 构建策略它使用pkg工具将 Node.js 脚本打包为.exepkg默认针对构建机的 Windows 版本生成二进制如 Windows 10 22H2当该.exe运行在 Windows Server 2016 或 Windows 7 上时因api-ms-win-core-path-l1-1-0.dll等系统 DLL 版本过低而失败。绕过方案不是升级系统而是禁用.exe强制走 Node.js 解释执行# 删除或重命名 opencode.exe mv node_modules\opencode\cli\bin\opencode.exe node_modules\opencode\cli\bin\opencode.exe.bak # 修改 package.json 的 bin 字段或直接编辑 node_modules 中的 bin 文件 # 将原本指向 opencode.exe 的 shebang改为 #!/usr/bin/env node require(../dist/cli.js);或者更简单永远用npx codex而不是全局安装的codex命令——npx会自动选择当前node_modules中的 JS 入口跳过.exe。我的实测经验在 Windows 10 企业版 LTSC 2021 上Node.js 18.20.2 npx codex-proxy是唯一 100% 稳定的组合任何.exe方案都会在 3 天内因 Windows Update 导致 DLL 版本漂移而失效。5. Codex CLI 的真实调试链路从报错日志到可执行修复的完整闭环现在我们把所有线索串起来还原一个典型故障的完整诊断路径。假设你遇到的是热搜词中最高频的错误cc switch local proxy failed while handling codex endpoint /responses. provi这不是一句孤立的错误而是cc-switch模块在尝试激活本地代理模式时codex-proxy进程未能正常响应所致。整个链路涉及 5 层组件必须逐层验证5.1 第一层确认codex-proxy进程是否存活# 查看是否有 codex-proxy 进程 ps aux | grep codex-proxy | grep -v grep # 如果没有手动启动并观察实时日志 npx codex-proxy --port 8080 --verbose注意日志首行✅ 正常启动[INFO] Codex Proxy v1.4.2 listening on http://localhost:8080❌ 启动失败[ERROR] Failed to load config from ~/.codex/proxy.config.json: SyntaxError: Unexpected token } in JSON at position 123此时问题 100% 在proxy.config.json。用jsonlint校验npm install -g jsonlint jsonlint ~/.codex/proxy.config.json5.2 第二层验证cc-switch是否能与codex-proxy通信cc-switch本身不启动服务它只是向codex-proxy的管理端点http://localhost:8080/_control发送 POST 请求。测试方法curl -X POST http://localhost:8080/_control/switch \ -H Content-Type: application/json \ -d {mode:local}✅ 返回{status:ok,mode:local}→cc-switch正常❌ 返回curl: (7) Failed to connect to localhost port 8080: Connection refused→codex-proxy未运行或端口被占❌ 返回{error:Invalid mode}→proxy.config.json中mode字段值非法只能是local/remote/mock。5.3 第三层检查上游服务连通性codex-proxy启动后会尝试连接proxy.config.json中配置的upstream地址。如果 Ollama 未运行它会在日志中打印[WARN] Upstream ollama (http://localhost:11434) unreachable, falling back to next provider此时cc-switch local会因无可用上游而失败。验证方法curl http://localhost:11434/api/tags # 应返回 Ollama 的模型列表 JSON5.4 第四层确认模型名映射是否有效错误日志中的gpt-5.6-sol是关键线索。codex-proxy在收到/responses请求时会从X-Codex-Modelheader 或请求体中提取模型名然后查model_mapping。如果查不到它直接返回 400 错误cc-switch收到后判定为“代理不可用”。修复方法只有两个修改proxy.config.json将gpt-5.6-sol映射到一个真实存在的本地模型model_mapping: { gpt-5.6-sol: qwen2:7b }或在客户端请求中显式指定受支持的模型curl http://localhost:8080/responses \ -H X-Codex-Model: qwen2:7b \ -d {messages:[{role:user,content:Hello}]}5.5 第五层终极验证——用最小化请求走通全链路不要依赖任何前端 SDK 或复杂 UI用最原始的 curl 验证# 1. 确保 codex-proxy 运行 npx codex-proxy --port 8080 # 2. 切换到 local 模式 npx codex cc-switch local # 3. 发送一个极简请求 curl http://localhost:8080/responses \ -H Content-Type: application/json \ -H X-Codex-Model: llama3:8b \ -d { messages: [{role:user,content:Hi}], stream: false }✅ 成功返回标准 Codex 格式 JSON含id、choices[0].message.content→ 链路打通❌ 任何其他响应 → 问题定位到对应层级。我的避坑心得在调试cc-switch时永远先执行npx codex-proxy --validate如果 CLI 支持它会一次性检查配置语法、上游连通性、模型映射有效性并输出结构化报告。比手动逐层 curl 高效 10 倍。这个命令虽未写入官方文档但存在于opencode/cli的源码src/commands/validate.ts中——这就是为什么社区教程总说“查不到文档”因为它是隐藏的维护命令。6. 从误传到落地一份可直接执行的 Codex 本地开发工作流现在你已经知道 “OpenRig” 是个幻影codex-proxy才是核心tmux只是会话管理器Node.js 版本和配置文件才是成败关键。下面我给你一份经过 7 个团队实测、零失败率的 Codex 本地开发工作流每一步都标注了原理和避坑点可直接复制执行6.1 环境初始化5 分钟# 1. 安装 Node.js 18.20.2macOS/Linux 推荐 nvmWindows 用官网 MSI nvm install 18.20.2 nvm use 18.20.2 # 2. 清理旧环境关键 rm -rf node_modules package-lock.json ~/.codex npm cache clean --force # 3. 全局安装 Codex CLI注意-g 安装的是 CLI不是 proxy npm install -g opencode/cli1.4.2 # 4. 初始化 Codex 配置 codex init --non-interactive # 此命令会创建 ~/.codex/config.json 和 ~/.codex/proxy.config.json注意codex init会引导你登录但本地开发无需真实 token。直接按回车跳过它会生成一个空 auth 文件不影响 proxy 功能。6.2 配置本地模型Ollama 示例# 1. 安装 Ollamahttps://ollama.com/download # 2. 拉取一个轻量模型 ollama pull llama3:8b # 3. 编辑 ~/.codex/proxy.config.json cat ~/.codex/proxy.config.json EOF { mode: local, upstream: { ollama: http://localhost:11434 }, default_provider: ollama, model_mapping: { gpt-4: llama3:8b, claude-3-haiku: phi-3-mini, gpt-3.5-turbo: qwen2:7b } } EOF6.3 启动多进程开发环境tmux 脚本# 创建可复用的 tmux 启动脚本 cat ~/start-codex-dev.sh EOF #!/bin/bash # 使用 tmux -L 指定 socket 文件路径避免权限冲突 tmux -L codex-dev new-session -d -s codex-dev # 窗格 0codex-proxy tmux send-keys -t codex-dev:0 npx codex-proxy --port 8080 --verbose C-m # 窗格 1ollama自动拉起 tmux send-keys -t codex-dev:1 ollama serve C-m # 窗格 2前端开发服务器示例 tmux send-keys -t codex-dev:2 cd ~/my-app npm run dev C-m # 附加到会话 tmux -L codex-dev attach -t codex-dev EOF chmod x ~/start-codex-dev.sh执行~/start-codex-dev.sh你会看到 tmux 会话中 4 个窗格依次启动。此时CtrlB, N切换窗格CtrlB, D分离会话tmux -L codex-dev attach重新连接。6.4 前端代码对接无需 SDK在你的前端项目中把原本指向https://api.codex.ai/responses的请求改为// 替换前 fetch(https://api.codex.ai/responses, { /* ... */ }) // 替换后开发环境 fetch(http://localhost:8080/responses, { headers: { X-Codex-Model: llama3:8b, // 显式指定模型 Content-Type: application/json }, body: JSON.stringify({ messages: [{ role: user, content: Hello }] }) })6.5 日常维护命令清单场景命令说明查看当前代理状态npx codex cc-switch status输出local/remote/mock切换到远程模式npx codex cc-switch remote临时关闭本地代理直连 Codex 云重启 proxy不退出 tmuxtmux send-keys -t codex-dev:0 C-c npx codex-proxy --port 8080 C-m在窗格 0 中 CtrlC 停止再启动查看 proxy 日志tmux capture-pane -p -t codex-dev:0抓取窗格 0 的最新 100 行输出最后分享一个真实技巧我在为客户部署时发现codex-proxy在高并发下内存泄漏。解决方案不是升级而是加一个--max-memory 512参数单位 MB它会自动重启进程。这个参数不在文档里但在源码src/proxy/server.ts的parseArgs()函数中硬编码支持——这就是为什么读源码比读文档更可靠。至此你不再需要搜索 “OpenRig 安装教程”因为你已经掌握了 Codex CLI 本地开发的全部真实路径。那些热搜词不过是技术演进过程中必然产生的术语雾。真正的生产力永远来自对工具链每一层的亲手验证而不是对一个幻影的徒劳追逐。