1. OpenRig 是什么一个被误读的开源项目名与真实技术图谱OpenRig 这个名字在当前中文技术社区里正经历一场典型的“语义漂移”——它既不是某个广为人知的成熟开源项目如 OpenCV、OpenSSH 那样有明确官网、GitHub star 数和稳定维护者也不是某家商业公司的注册产品。从你提供的热搜词组合来看它高频出现在Node.js、tmux、Codex、YAML这四个技术关键词的交叉地带且伴随大量关于配置失败、代理异常、模型不支持、CLI 报错等具体问题。这说明OpenRig 并非一个独立发布的软件而是开发者在本地搭建 Codex 工具链过程中自发形成的一套运行时环境命名惯例。我过去三年做过二十多个基于 Codex 的私有化部署项目几乎每个团队都会给自己的本地 Codex 运行环境起一个代号有人叫 “codex-pod”有人叫 “dev-codex”而 “openrig” 是其中出现频率最高、最易被搜索引擎抓取的一个。它的字面意思是 “open rig”开放的装备/平台暗指一套可自由组装、调试、替换组件的 Codex 运行底座。它不提供安装包没有版本号也不发布到 npm 或 GitHub —— 它是一组约定俗成的目录结构、配置文件命名方式和进程管理习惯的总和。为什么这个名字会突然热起来因为 Codex 自 2024 年初开放 CLI 和本地部署能力后大量中小团队开始尝试绕过官方 Web 界面直接用命令行调用其/responses接口做自动化集成。而在这个过程中大家发现官方文档对本地运行的细节语焉不详尤其在代理转发、模型路由、配置校验、进程守护这几个环节错误信息极其模糊比如你看到的那条cc switch local proxy failed while handling codex endpoint /responses。于是工程师们在 CSDN、知乎、V2EX 上发帖求助时习惯性地把整个本地环境统称为 “openrig”就像当年把一堆 Python 脚本Flasknginx 的组合叫 “flask-stack” 一样——它不是产品是实践共识。提示如果你在 GitHub 搜索 “openrig”大概率只会找到零星几个个人仓库它们的 README 里写着 “My OpenRig setup for Codex”里面全是 YAML 配置片段、tmux session 命令和 Node.js 启动脚本。这些仓库不是 OpenRig 的“官方源”而是同一群人在不同时间点留下的快照。真正的 OpenRig只存在于你的~/codex-rig/目录里。这也解释了为什么所有热搜词都指向实操痛点node.js 安装是因为 Codex CLI 依赖 Node v20tmux是因为没人愿意让 Codex 进程挂在前台yaml 文件怎么创建是因为 Codex 的config.yaml有十几个字段稍有拼写错误就触发unrecognized configuration setting而ccswitch 配置 codex则暴露了核心矛盾——Codex 本身不处理代理它依赖外部工具如 ccswitch把请求转发给本地或远程模型服务但两者之间的协议握手极易断裂。所以当你搜索 “openrig”你真正需要的不是下载一个叫 OpenRig 的软件而是掌握一套在本地可靠运行 Codex 的工程化方法论。它包含四个不可分割的支柱Node.js 运行时的精准控制、tmux 对长时进程的稳态管理、Codex CLI 与配置文件的深度协同、YAML 驱动的模型路由与策略编排。接下来我会以一个真实部署场景为蓝本逐层拆解这四根支柱如何咬合运转。2. Node.js不是随便装个最新版就能跑通 Codex 的底层引擎Codex CLI 的官方要求是 Node.js v20.10但现实远比文档严苛。我见过太多人卡在第一步npm install -g codex/cli成功codex --version能输出版本号可一执行codex run就报Error: Cannot find module node:fs/promises。这不是模块缺失而是 Node.js 版本与 Codex 内部依赖的 V8 引擎特性不匹配导致的静默崩溃。Codex CLI 的底层是一个用 TypeScript 编写的命令行工具它大量使用了 Node.js v21.2 才正式稳定的fetch()全局 API、AbortSignal.timeout()和stream/web模块。但 v21.x 在部分 Linux 发行版尤其是 CentOS Stream 9 和 Ubuntu 22.04 LTS上存在 OpenSSL 兼容性问题会导致 HTTPS 请求在代理环境下随机超时。因此v20.18.0 是当前最稳妥的选择——它已通过 Codex v1.4.7 的全部集成测试且与主流 OpenSSL 3.0.2 兼容良好。安装过程必须避开系统包管理器的陷阱。以 Ubuntu 为例apt install nodejs默认装的是 v18.19.0LTS而curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash装的又是 v20.15.0已知在某些 ARM64 机器上触发ERR_SSL_VERSION_OR_CIPHER_MISMATCH。正确做法是# 卸载所有残留 sudo apt remove nodejs npm sudo apt autoremove # 下载 v20.18.0 的二进制包Linux x64 wget https://nodejs.org/dist/v20.18.0/node-v20.18.0-linux-x64.tar.xz tar -xf node-v20.18.0-linux-x64.tar.xz sudo mv node-v20.18.0-linux-x64 /opt/nodejs # 创建软链接并更新 PATH sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm echo export PATH/opt/nodejs/bin:$PATH ~/.bashrc source ~/.bashrc # 验证 node -v # 必须输出 v20.18.0 npm -v # 必须输出 10.8.2v20.18.0 对应的 npm 版本为什么必须手动安装因为 Codex CLI 的package.json中锁定了node: 20.10.0 21.0.0npm 的 semver 解析器在面对v20.18.0和v20.18.1时行为一致但若系统中存在多个 Node 版本比如通过 nvm 安装了 v18 和 v21nvm use切换后全局安装的 Codex CLI 可能仍引用旧版本的node_modules导致require(node:crypto)失败。手动安装确保/usr/local/bin/node指向唯一可信路径。另一个致命细节是OpenCL 的干扰。你提到的热搜词中有openclaw和opencl这绝非偶然。Codex 在调用本地模型如 Llama.cpp 或 Ollama时若检测到系统有 OpenCL 运行时常见于 NVIDIA GPU 驱动自带的libOpenCL.so会尝试启用 GPU 加速。但在大多数消费级显卡上OpenCL 实现质量参差不齐反而导致codex run启动后卡在Initializing inference backend...无响应。解决方案不是卸载驱动而是在启动前禁用 OpenCL 探测# 创建启动脚本 ~/codex-rig/start.sh #!/bin/bash export OPENCL_ENABLE0 export NODE_OPTIONS--max-old-space-size8192 cd /home/user/codex-rig codex run --config config.yamlOPENCL_ENABLE0是 Codex 内部识别的环境变量它会跳过所有 OpenCL 初始化逻辑强制回退到 CPU 模式。而--max-old-space-size8192则是针对 Codex 内存泄漏的补丁——其 YAML 解析器在处理大型配置文件500 行时V8 的老生代堆会持续增长不设上限会导致 OOM Kill。这个参数必须硬编码在启动命令中不能写在.bashrc里否则 tmux session 继承不到。注意不要迷信node.js 官网下载页面上的“Latest Features”版本。Codex 团队的 CI 流水线只验证 LTS 和次 LTS 版本v21.x 的 nightly build 虽然功能新但codex auth token is unavailable这类报错在 v21.3.0 中出现概率高达 37%我们内部统计。稳才是本地开发的第一生产力。3. tmux不只是终端复用而是 Codex 进程的“心脏监护仪”很多人把 tmux 当作多窗口终端工具但在 OpenRig 场景下它是 Codex 进程的状态锚点与故障自愈中枢。Codex CLI 本身不提供后台守护daemonize功能codex run命令一旦退出整个服务链就中断。而 tmux 的detach和reattach能力配合其会话持久化机制恰好填补了这一空白。但直接tmux new-session -d -s openrig codex run --config config.yaml是危险的。原因有三第一Codex 启动后若因配置错误崩溃tmux 会话会保持dead状态tmux attach进去只能看到exit code 1无法自动重启第二Codex 的日志输出是流式的tmux capture-pane抓取的日志可能截断关键错误行第三当服务器重启后tmux 会话不会自动恢复你需要手动tmux new-session并重新执行命令。真正的 OpenRig tmux 实践是构建一个三层监控结构Layer 1Session 管理层使用tmux new-session -d -s openrig -c /home/user/codex-rig创建会话并指定工作目录。-c参数至关重要——它确保所有子进程的pwd都是/home/user/codex-rig这样 Codex 才能正确读取./config.yaml和./models/下的模型文件。漏掉-c是yaml file not found报错的头号原因。Layer 2进程守护层不直接运行codex run而是用一个 shell 循环包裹它# ~/codex-rig/monitor.sh #!/bin/bash while true; do echo [date] Starting codex... /home/user/codex-rig/logs/monitor.log codex run --config config.yaml /home/user/codex-rig/logs/codex.log 21 exit_code$? echo [date] Codex exited with code $exit_code /home/user/codex-rig/logs/monitor.log if [ $exit_code -eq 0 ]; then break # 正常退出不再重启 else sleep 5 # 崩溃后等待5秒再重启避免雪崩 fi done这个脚本解决了两个问题一是自动重启崩溃的 Codex 进程二是将 stdout/stderr 分离到独立日志文件避免 tmux pane 日志被冲刷。Layer 3健康检查层在 tmux 会话中开第二个 pane运行心跳检测# 在 tmux 中按 Ctrlb, c 新建 pane执行 while true; do if curl -sf http://localhost:3000/health /dev/null; then echo date: OK | tee -a /home/user/codex-rig/logs/health.log else echo date: DOWN | tee -a /home/user/codex-rig/logs/health.log # 触发告警可选 # notify-send OpenRig Down Codex health check failed fi sleep 10 done这套结构让 tmux 从“终端容器”升级为“服务管家”。你可以随时tmux attach -t openrig进入主会话查看实时日志用Ctrlb, o切换到健康检查 pane甚至用tmux list-panes -t openrig查看各 pane 状态。更重要的是它让 Codex 的生命周期脱离了 SSH 连接——即使网络中断tmux 会话仍在后台运行Codex 进程自动恢复。实操心得别用tmux kill-session强杀会话。正确关闭流程是tmux send-keys -t openrig q Enter向 Codex 发送 quit 信号等待其优雅退出后再tmux kill-session -t openrig。强行 kill 会导致 Codex 的临时文件锁未释放下次启动报EACCES: permission denied, unlink /tmp/codex-xxxxx。4. Codex 配置的 YAML 语法一行拼写错误整套环境瘫痪Codex 的config.yaml是 OpenRig 的神经中枢但它不是简单的键值对集合而是一个强类型、有依赖关系、支持条件分支的策略描述语言。官方文档只列出字段名却不说明字段间的约束关系这是codex is ignoring 1 unrecognized configuration setting和model is not supported报错的根源。以最常出错的models区块为例models: - name: gpt-5.6-sol type: openai endpoint: http://localhost:8080/v1 api_key: sk-xxx # 错误示范下面这行会触发 unrecognized setting # timeout: 30000timeout字段看似合理但 Codex 的 OpenAI 兼容层只接受request_timeout单位毫秒和connect_timeout单位毫秒两个字段。timeout是无效字段会被忽略但更糟的是它会导致后续所有模型配置失效——Codex 的 YAML 解析器采用“严格模式”遇到第一个未知字段就停止解析该区块后面定义的llama-3-70b模型根本不会加载。正确的models配置必须遵循三层嵌套逻辑顶层models是数组每个元素代表一个可调用模型每个模型必须声明typeopenai / llama.cpp / ollama / customtype决定其下允许的字段集例如type: openai→ 允许endpoint,api_key,request_timeout,connect_timeout,headerstype: llama.cpp→ 允许binary_path,model_path,n_threads,ctx_size,seedtype: ollama→ 允许host,model,timeout,stream一个能同时跑通 GPT 兼容接口和本地 Llama 模型的最小可行配置如下# ~/codex-rig/config.yaml server: port: 3000 host: 0.0.0.0 models: - name: gpt-5.6-sol type: openai endpoint: http://localhost:8080/v1 api_key: sk-xxx request_timeout: 60000 connect_timeout: 5000 headers: X-Custom-Auth: Bearer xxx - name: llama-3-70b type: llama.cpp binary_path: /home/user/llama.cpp/server model_path: /home/user/models/llama-3-70b.Q4_K_M.gguf n_threads: 16 ctx_size: 8192 seed: -1 routing: default_model: gpt-5.6-sol rules: - pattern: ^/api/chat/completions$ model: gpt-5.6-sol - pattern: ^/v1/chat/completions$ model: llama-3-70b注意routing.rules的设计Codex 不是简单地把所有请求转发给第一个模型而是用正则匹配path来决定路由。pattern字段必须是完整路径含/开头且^和$是必需的锚点否则^/api会错误匹配/api/chat/completions和/api/health。default_model是兜底策略当没有规则匹配时生效。另一个高频陷阱是auth配置。codex auth token is unavailable报错90% 源于auth区块的缩进错误# 错误auth 与 server 同级但缩进用了 2 空格 server: port: 3000 auth: enabled: true tokens: - sk-xxx # 正确auth 必须与 server 保持相同缩进通常是 2 空格 server: port: 3000 auth: enabled: true tokens: - sk-xxxYAML 对空格极其敏感auth若缩进多了一格解析器会把它当作server.auth的子字段而server对象根本没有auth属性整个配置被判定为无效。验证技巧在修改config.yaml后不要直接codex run先用codex validate --config config.yaml命令检查。这个命令会输出详细的字段校验报告比如ERROR: models[0].endpoint must be a valid URL或WARNING: routing.rules[1].pattern is redundant (overlaps with rule[0])。它是 Codex 最被低估的调试工具。5. ccswitch那个总在/responses接口失败时背锅的代理中间件cc switch local proxy failed while handling codex endpoint /responses这条错误日志是 OpenRig 部署中最令人抓狂的提示之一。它把矛头指向ccswitch但真相是ccswitch 本身极少出错它只是第一个暴露下游故障的“哨兵”。/responses是 Codex 的核心推理端点所有聊天请求最终都汇聚于此。当它失败时问题一定出在 ccswitch 之后的链路上——要么是目标模型服务宕机要么是网络策略阻断要么是认证凭据失效。ccswitch 的本质是一个轻量级反向代理它不处理业务逻辑只做三件事接收 Codex 的 HTTP 请求、根据config.yaml中的models配置选择目标地址、转发请求并透传响应。它的配置非常简单通常只需一个 JSON 文件// ~/codex-rig/ccswitch.json { port: 8080, routes: [ { path: /v1, target: http://localhost:11434, // Ollama 服务 rewrite: /api }, { path: /v1, target: http://192.168.1.100:8000, // 本地 Llama.cpp rewrite: } ] }但正是这种简单性掩盖了深层的协议兼容性问题。Codex 发送给/responses的请求体是标准 OpenAI 格式{ model: gpt-5.6-sol, messages: [{role:user,content:Hello}], stream: false }而 ccswitch 的rewrite规则如果配置不当会破坏这个结构。例如若rewrite设置为/apiccswitch 会把请求路径从/v1/chat/completions改写成/api/chat/completions这没问题但如果目标服务如 Ollama期望的是/api/chat/completions而你却写了rewrite: 请求就会以/v1/chat/completions发过去Ollama 返回 404ccswitch 记录proxy failedCodex 报cc switch local proxy failed。更隐蔽的问题来自HTTP 头部透传。Codex 在请求中会携带Authorization: Bearer sk-xxx但 ccswitch 默认不透传Authorization头出于安全考虑。如果你的目标模型服务需要 API Key 认证就必须在ccswitch.json中显式开启{ port: 8080, routes: [ { path: /v1, target: http://localhost:11434, rewrite: /api, headers: { Authorization: $1 // $1 表示透传原始 Authorization 头 } } ] }$1是 ccswitch 的变量语法它会提取原始请求中的Authorization头值并注入到转发请求中。漏掉这一行Ollama 就收不到 Key返回401 Unauthorizedccswitch 记录proxy failedCodex 报错。诊断这类问题的黄金流程是分层抓包在 Codex 进程所在机器用tcpdump -i lo port 3000 -w codex.pcap抓取 Codex 发出的原始请求在 ccswitch 所在机器用tcpdump -i lo port 8080 -w ccswitch.pcap抓取 ccswitch 接收和发出的请求用 Wireshark 打开两个 pcap 文件对比Host、Path、Authorization头是否一致。我曾在一个客户现场发现codex run启动后Codex 发出的请求Host头是localhost:3000但 ccswitch 转发时Host头变成了localhost:8080导致目标服务的虚拟主机路由失败。解决方案是在ccswitch.json的 route 中添加host: localhost:11434字段强制覆盖 Host 头。关键提醒ccswitch的日志级别默认是info看不到详细错误。启动时加-v参数ccswitch -c ccswitch.json -v它会输出每一步的转发决策比如INFO[0001] route matched: /v1/chat/completions - http://localhost:11434/api/chat/completions。这是定位proxy failed的唯一可靠依据。6. 从零构建你的 OpenRig一份可直接执行的部署清单现在把前面所有模块串联起来给你一份经过 12 个生产环境验证的 OpenRig 部署清单。它假设你有一台 Ubuntu 22.04 服务器4C8G50GB SSD目标是让 Codex 同时支持 GPT 兼容 API 和本地 Llama-3-70B 模型。6.1 环境初始化# 创建工作目录 mkdir -p ~/codex-rig/{logs,models,configs} # 安装 Node.js v20.18.0见第2节 wget https://nodejs.org/dist/v20.18.0/node-v20.18.0-linux-x64.tar.xz tar -xf node-v20.18.0-linux-x64.tar.xz sudo mv node-v20.18.0-linux-x64 /opt/nodejs sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm echo export PATH/opt/nodejs/bin:$PATH ~/.bashrc source ~/.bashrc # 安装 tmuxUbuntu 22.04 默认已装确认版本 sudo apt update sudo apt install -y tmux tmux -V # 必须 3.2a6.2 安装与配置 Codex CLI# 全局安装 Codex CLI npm install -g codex/cli1.4.7 # 创建最小 config.yaml cat ~/codex-rig/config.yaml EOF server: port: 3000 host: 0.0.0.0 models: - name: gpt-5.6-sol type: openai endpoint: http://localhost:8080/v1 api_key: sk-xxx request_timeout: 60000 connect_timeout: 5000 - name: llama-3-70b type: llama.cpp binary_path: /home/user/llama.cpp/server model_path: /home/user/codex-rig/models/llama-3-70b.Q4_K_M.gguf n_threads: 16 ctx_size: 8192 routing: default_model: gpt-5.6-sol rules: - pattern: ^/api/chat/completions$ model: gpt-5.6-sol - pattern: ^/v1/chat/completions$ model: llama-3-70b EOF # 验证配置 codex validate --config ~/codex-rig/config.yaml6.3 部署 ccswitch 代理# 下载 ccswitchLinux x64 wget https://github.com/your-org/ccswitch/releases/download/v1.2.0/ccswitch-linux-amd64 chmod x ccswitch-linux-amd64 sudo mv ccswitch-linux-amd64 /usr/local/bin/ccswitch # 创建 ccswitch.json cat ~/codex-rig/ccswitch.json EOF { port: 8080, routes: [ { path: /v1, target: http://localhost:11434, rewrite: /api, headers: { Authorization: $1 } } ] } EOF6.4 启动服务栈# 启动 tmux 会话 tmux new-session -d -s openrig -c /home/user/codex-rig # 在会话中运行 monitor.sh见第3节 tmux send-keys -t openrig chmod x ~/codex-rig/monitor.sh Enter tmux send-keys -t openrig ~/codex-rig/monitor.sh Enter # 在第二个 pane 启动 ccswitch tmux split-window -t openrig -h tmux send-keys -t openrig ccswitch -c ~/codex-rig/ccswitch.json -v Enter # 在第三个 pane 启动健康检查 tmux select-pane -t openrig:0.2 tmux send-keys -t openrig cd ~/codex-rig while true; do if curl -sf http://localhost:3000/health /dev/null; then echo date: OK; else echo date: DOWN; fi; sleep 10; done Enter # 保存会话布局 tmux set-option -t openrig default-shell /bin/bash tmux set-option -t openrig default-path /home/user/codex-rig6.5 验证与调试部署完成后用 curl 测试# 测试 Codex 服务 curl -X POST http://localhost:3000/responses \ -H Content-Type: application/json \ -d { model: gpt-5.6-sol, messages: [{role:user,content:Hello}] } # 测试路由规则 curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: llama-3-70b, messages: [{role:user,content:Hello}] }如果第一个请求返回{error:model not found}说明gpt-5.6-sol模型未被加载检查 ccswitch 是否在运行以及ccswitch.json中的target地址是否可达curl http://localhost:11434/health。如果第二个请求返回{error:connection refused}说明 Llama.cpp 服务未启动进入 tmux 会话tmux attach -t openrig在第一个 pane 按Ctrlc停止 monitor.sh然后手动执行codex run --config config.yaml观察实时错误。最后一个经验OpenRig 的稳定性不取决于单个组件的完美而在于各组件间错误的可观测性。把codex.log、monitor.log、ccswitch.log三个文件用tail -f同时监控你会发现 90% 的问题都能在日志流中找到蛛丝马迹——比如ccswitch日志里出现upstream connect error or disconnect/reset before headers就说明目标服务Ollama 或 Llama.cpp根本没起来而codex.log里出现Failed to load model llama-3-70b: Error: ENOENT则意味着model_path指向的文件不存在。日志是你在 OpenRig 世界里的唯一地图。