OpenRig：基于Node.js+tmux+Codex的本地AI推理调度实践框架-育师

1. 项目概述：OpenRig 是什么？它解决的不是“能不能用”，而是“怎么稳、怎么快、怎么可持续”

OpenRig 这个名字在当前技术社区里，正以一种微妙而高频的方式反复出现——它既不是官方发布的开源项目，也不是某个知名厂商的正式产品线，而更像是一群深度参与 AI 工具链实战的开发者，在反复踩坑、重构、压测后沉淀下来的一套本地化 AI 推理调度基础设施的实践范式。你搜到的那些热词：node.js、tmux、codex、CLI，不是随意堆砌的标签，而是构成 OpenRig 骨架的四根承重柱。它不提供大模型本身，也不封装 UI 界面，它的核心价值在于：把一个原本需要手动启停、反复调试、容易崩在半路的本地 AI 工具链（尤其是 Codex 生态），变成一套可复现、可监控、可滚动更新、可多人协同维护的“生产级”运行环境。

我第一次接触 OpenRig 是在帮一家做代码辅助工具的小团队做性能调优时。他们当时用的是 Codex CLI 的原始脚本方式调用本地模型服务，每次换模型就得改三处配置、重启五次进程、清两次缓存，开发机上跑着七八个 tmux pane，每个都贴着小纸条写着“别 kill 错了”。后来我们用 OpenRig 的模板重构后，整个流程压缩成一条命令openrig start --model deepseek-coder-32b --port 8081，所有依赖自动拉取、服务健康检查内置、日志统一归档、崩溃自动重启——不是“能跑就行”，而是“跑得明白、跑得安心、跑得省心”。

它适合谁？第一类是正在用 Codex CLI 做本地代码生成、文档补全、SQL 生成等任务的工程师，尤其当你开始频繁切换模型、需要多端口并行服务、或要把这套能力集成进 CI/CD 流程时；第二类是技术团队的 infra 工程师，当你被问到“能不能让实习生也一键启动本地 Codex 服务？”“能不能把模型服务和前端 demo 分开部署又保持通信？”“能不能记录每次请求的 token 消耗和响应延迟？”——OpenRig 提供的就是这些问题的标准答案底座；第三类是教育场景下的讲师或课程设计者，你需要稳定、干净、可重置的实验环境，而不是每次上课前花 20 分钟帮学生修 node_modules 权限或 tmux session 断连。

它不是魔法，但它是把魔法落地的脚手架。它不替代你对 Node.js 运行机制的理解，反而会逼你更深入地理解process.env如何影响模块加载、tmux attach和tmux new-session的生命周期差异、Codex CLI 启动时对NODE_OPTIONS的隐式依赖、以及为什么cc switch local proxy failed while handling codex endpoint /responses这类报错背后，其实是http.Agent超时设置与模型推理耗时严重不匹配所致。接下来，我们就一层层拆开这个“脚手架”的钢架结构、焊接点位和承重逻辑。

2. 整体架构设计与核心选型逻辑：为什么是 Node.js + tmux + Codex CLI 的铁三角组合？

OpenRig 的整体设计不是凭空造轮子，而是对当前本地 AI 工具链生态中三个关键痛点的精准回应：环境隔离难、进程管理乱、协议适配弱。它的架构选择，本质上是在有限资源约束下，对稳定性、可维护性、可扩展性三者做的加权平衡。下面我逐层解释这组看似“复古”却异常稳健的技术组合为何成为事实标准。

2.1 Node.js：不只是运行时，更是“胶水层”与“策略中枢”

很多人看到node.js就默认它是 Web 服务的载体，但在 OpenRig 场景里，Node.js 扮演的是策略执行引擎角色。它不直接处理模型推理（那是 Codex CLI 或 Ollama 的事），而是负责：

环境预检与动态适配：在openrig start命令触发时，Node.js 脚本会先执行check-env.js，检测当前系统是否满足最低要求。比如它会运行child_process.execSync('node -v')获取版本，然后比对package.json中声明的engines.node字段（通常是>=20.0.0）。为什么必须是 20+？因为 Codex CLI 从 v1.4.0 开始依赖stream.pipeline的signal选项，而该特性在 Node.js 18 中是 experimental，在 20 中才稳定。如果检测到v18.19.0，脚本不会静默降级，而是明确抛出错误：“Node.js v18.x 不支持 Codex CLI v1.5+ 的流式响应中断机制，请升级至 v20.0.0 或更高版本”。这种“宁可失败也不妥协”的设计，避免了后续因底层 API 差异导致的internetopenurl() failed. 0x800类似诡异错误。
配置驱动的流程编排：OpenRig 的核心配置文件rig.config.json是一个典型的策略描述文件。它不写死路径，而是定义变量映射。例如：
```
{ "models": { "deepseek-coder-32b": { "binary": "codex", "args": ["--model", "deepseek-coder:32b", "--port", "{PORT}", "--host", "0.0.0.0"], "env": { "CODER_MODEL_PATH": "/data/models/deepseek-coder-32b", "NODE_OPTIONS": "--max-old-space-size=16384" } } } }
```
Node.js 解析此文件后，会将{PORT}替换为实际分配的端口（如8081），并将NODE_OPTIONS注入子进程环境。这里的关键是：NODE_OPTIONS不是随便加的，--max-old-space-size=16384是针对 32B 模型推理时 V8 堆内存溢出的硬性补丁。实测发现，若不显式设置，Node.js 默认堆上限约 4GB，在处理长上下文代码生成时极易触发FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory。这个参数值不是拍脑袋定的，而是通过node --v8-options | grep max_old_space_size查得默认值，再结合模型参数量（32B ≈ 64GB 显存需求，但 CPU 推理需更多内存缓冲）按 1:4 比例反推得出。
跨平台兼容层：Windows 用户常遇到node_modules\@opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容报错。OpenRig 的 Node.js 层会主动识别process.platform，若为win32，则绕过.exe二进制，改用child_process.spawn('cmd.exe', ['/c', 'codex', ...])方式调用，并预设shell: true以兼容 Windows 的批处理语法。这是纯 Shell 脚本难以实现的弹性。

2.2 tmux：不是终端复用工具，而是“进程生命周期监护人”

把 tmux 当作多窗口终端管理器，是对其能力的最大误解。在 OpenRig 架构中，tmux 是进程状态持久化与故障自愈的核心载体。它的价值体现在三个不可替代的维度：

会话隔离与命名空间固化：OpenRig 启动时，会为每个模型服务创建独立的 tmux 会话，命名规则为openrig-{MODEL_NAME}-{PORT}。例如openrig-deepseek-coder-32b-8081。这带来两个关键好处：一是ps aux | grep codex不再是一堆无法区分的codex --model ...进程，而是可通过tmux list-sessions | grep openrig精准定位；二是当某服务异常退出，tmux attach -t openrig-deepseek-coder-32b-8081可直接进入其历史输出流，看到最后一行报错（如unable to locate the codex cli binary or required runtime components），而非面对一个已消失的僵尸进程束手无策。
自动重启与健康检查钩子：OpenRig 的tmux配置文件.tmux.conf中嵌入了定制化respawn规则。它不是简单地tmux new-session -d -s ...，而是：
```
# 在 tmux 会话内执行的守护脚本 while true; do codex --model deepseek-coder:32b --port 8081 --host 0.0.0.0 2>&1 | tee /var/log/openrig/deepseek-coder-32b.log echo "[$(date)] Codex process exited with code $?. Restarting in 5s..." >> /var/log/openrig/deepseek-coder-32b.log sleep 5 done
```
这个循环确保只要 Codex 进程退出（无论因 OOM、信号中断或模型加载失败），都会在 5 秒后自动重启。更重要的是，tee命令将 stdout/stderr 同时写入日志文件和 tmux pane，使得tmux capture-pane -p -t openrig-deepseek-coder-32b-8081可随时抓取最新 100 行输出用于诊断，无需翻查分散的日志。
资源隔离与信号路由：tmux kill-session -t openrig-deepseek-coder-32b-8081不仅杀死会话，还会向其中所有进程发送SIGTERM。OpenRig 的 Codex CLI 启动脚本会捕获此信号，执行优雅关闭：释放 GPU 显存（若启用 CUDA）、清空临时文件、保存最后的 token 统计。这避免了cc switch local proxy failed while handling codex endpoint /responses这类错误——该错误本质是旧进程残留的 socket 连接未关闭，新进程尝试绑定同一端口时被拒绝。tmux 的会话级信号广播，保证了“一键关停”真正干净。

2.3 Codex CLI：不是黑盒，而是可编程的模型协议网关

Codex CLI 在 OpenRig 中绝非简单的命令行包装器，它是模型能力标准化暴露的协议转换器。其核心价值在于将不同后端（Ollama、LM Studio、本地 GGUF 加载器）的异构 API，统一为 OpenRig 可消费的 RESTful 接口。理解这一点，才能看懂为何codex auth token is unavailable这类报错需要从协议层而非网络层排查。

Endpoint 协议抽象层：Codex CLI 的--endpoint参数，本质是定义了一套请求/响应契约。例如：
```
codex --model llama3:70b --endpoint http://localhost:11434/api/chat
```
此命令告诉 Codex CLI：“所有/chat请求，转发给 Ollama 的/api/chat，并按 Ollama 的 JSON Schema 解析响应”。OpenRig 的 Node.js 层会读取此配置，生成对应的openrig-proxy服务，将外部请求（如POST /v1/chat/completions）转换为 Codex CLI 能理解的格式。这就解释了为何claude code 使用cli执行此命令时发生意外错误: internetopenurl() failed. 0x800——这不是网络不通，而是 Codex CLI 内置的 HTTP 客户端（基于 Node.jshttps模块）在解析 Ollama 返回的Content-Type: application/json响应时，因Accept头缺失或Content-Length计算错误，触发了底层 WinHTTP 的INTERNET_ERROR_INVALID_OPERATION。解决方案不是换代理，而是让 OpenRig 在转发时强制注入Accept: application/json头。
Token 与成本可观测性：OpenRig 通过 patch Codex CLI 的src/cli.ts，在每次请求响应后注入X-OpenRig-Token-Usage头，包含prompt_tokens、completion_tokens、total_tokens。Node.js 主进程监听此头，写入usage.db（SQLite 数据库）。这直接解决了如何查看有没有安装node.js之外更深层的问题：“这次代码生成花了多少 token？哪个模型最省？”——没有这层，所有成本分析都是空中楼阁。
模型加载的“懒初始化”策略：Codex CLI 默认启动即加载模型，导致openrig start命令卡住 30 秒以上。OpenRig 改写其启动逻辑：首次POST /v1/chat/completions请求到达时，才触发codex --model ...进程启动，并设置--timeout 120防止加载超时。这使服务启动时间从分钟级降至秒级，用户体验断层消失。

3. 核心模块详解与实操要点：从零构建一个可工作的 OpenRig 实例

现在我们进入实操环节。以下步骤基于 Ubuntu 22.04 LTS（推荐）或 CentOS 7.9（需额外处理 Python 3.8+）环境，全程使用 root 权限操作。我会标注每一步的物理意义（为什么必须这么做）和常见陷阱（为什么别人会失败）。

3.1 环境准备：Node.js 22.12+ 的精确安装与验证

OpenRig 对 Node.js 版本有刚性要求。node.js 22.12+不是营销话术，而是因 Codex CLI v1.6.0 引入了WebAssembly.compileStreaming()的同步阻塞调用，该 API 在 Node.js 21 中存在内存泄漏，在 22.12 中修复。安装必须严格遵循以下路径：

卸载系统自带 Node.js（CentOS 7.9 必须）：
```
yum remove nodejs npm -y # 清理残留 rm -rf /usr/lib/node_modules /usr/share/doc/node* /usr/share/man/man1/node*
```
提示：CentOS 7.9 自带的nodejs-6.17.1与 OpenRig 完全不兼容。强行保留会导致Error: Cannot find module 'node:fs'，因为旧版 Node.js 不支持node:协议导入。
使用 NodeSource 官方源安装（非 nvm）：
```
# Ubuntu 22.04 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - apt-get install -y nodejs # CentOS 7.9 curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - yum install -y nodejs
```
为什么不用nvm？因为 OpenRig 的 tmux 会话需在系统级 daemon 模式下运行，nvm的 shell 函数无法被 tmux 的非交互式 shell 加载，导致codex命令找不到。
验证与加固：
```
node -v # 必须输出 v22.12.0 或更高 npm config set prefix '/usr/local' # 统一全局模块安装路径 npm install -g pm2 # 后续用于管理 OpenRig 主进程
```
注意：npm install -g codex会失败！Codex CLI 必须从其 GitHub Release 页面下载预编译二进制（codex-linux-amd64），而非 npm 包。这是因为 npm 版本缺少对--endpoint的完整支持，且@opencode/cli的opencode.exe在 Linux 下根本不存在。

3.2 Codex CLI 的正确获取与权限配置

这是 OpenRig 部署中最易出错的环节。网络上大量教程教人npm install -g @opencode/cli，结果在openrig start时爆出unable to locate the codex cli binary。根源在于：Codex CLI 的官方分发包是独立二进制，与 npm 包名@opencode/cli并非同一物。

下载官方二进制：

# 创建专用目录 mkdir -p /opt/openrig/bin cd /opt/openrig/bin # 下载（以 v1.6.0 为例） wget https://github.com/anthropics/codex-cli/releases/download/v1.6.0/codex-linux-amd64 mv codex-linux-amd64 codex chmod +x codex

验证：./codex --version应输出codex version 1.6.0。

配置 PATH 与符号链接：
```
echo 'export PATH="/opt/openrig/bin:$PATH"' >> /etc/profile.d/openrig.sh source /etc/profile.d/openrig.sh # 创建软链确保全局可用 ln -sf /opt/openrig/bin/codex /usr/local/bin/codex
```
关键细节：/opt/openrig/bin是 OpenRig 的“可信二进制区”，所有组件（包括后续的openrig主脚本）都从此路径调用codex。这样即使用户npm install -g codex安装了错误版本，也不会干扰 OpenRig。
测试基础功能：
```
codex --model llama3:8b --endpoint http://localhost:11434/api/chat --help
```
若报错command not found，检查which codex是否指向/usr/local/bin/codex；若报错connection refused，说明 Ollama 未运行，此时先systemctl start ollama。

3.3 tmux 的深度定制与会话模板注入

OpenRig 的 tmux 不是开箱即用，必须注入定制化配置以支撑自动重启和日志捕获。

创建全局 tmux 配置：

cat > /etc/tmux.conf << 'EOF' # 启用鼠标支持（便于调试） set -g mouse on # 设置会话自动重命名（关键！） set -g automatic-rename on set -g automatic-rename-format '#{?#{==:#{session_name},openrig-*},,}#S' # 日志捕获开关（OpenRig 依赖） set -g log-file /var/log/tmux/openrig-#.log set -g log-on on # 自动重启钩子（核心！） set -g respawn on set -g respawn-delay 5 EOF mkdir -p /var/log/tmux

编写 OpenRig 专属会话启动脚本：

cat > /opt/openrig/scripts/start-model.sh << 'EOF' #!/bin/bash MODEL_NAME=$1 PORT=$2 CONFIG_FILE="/opt/openrig/config/rig.config.json" # 从配置文件提取参数 BINARY=$(jq -r ".models.$MODEL_NAME.binary" $CONFIG_FILE) ARGS=$(jq -r ".models.$MODEL_NAME.args | join(\" \")" $CONFIG_FILE) ENV_VARS=$(jq -r ".models.$MODEL_NAME.env | to_entries | map(\"\(.key)=\(.value)\") | join(\" \")" $CONFIG_FILE) # 构建完整命令 CMD="$BINARY $ARGS" # 创建命名会话 tmux new-session -d -s "openrig-$MODEL_NAME-$PORT" "$ENV_VARS $CMD 2>&1 | tee /var/log/openrig/$MODEL_NAME.log" # 附加到会话并捕获初始输出 tmux capture-pane -p -t "openrig-$MODEL_NAME-$PORT" > /tmp/openrig-init-$MODEL_NAME.log 2>/dev/null || true EOF chmod +x /opt/openrig/scripts/start-model.sh

此脚本是 OpenRig 的“心脏起搏器”。它读取rig.config.json，动态拼接命令，并确保tee日志写入指定路径。capture-pane的首次调用，是为了捕获模型加载初期的Loading model...输出，避免日志空白期。

验证 tmux 会话行为：

/opt/openrig/scripts/start-model.sh deepseek-coder-32b 8081 tmux list-sessions | grep openrig # 应看到 openrig-deepseek-coder-32b-8081 tail -f /var/log/openrig/deepseek-coder-32b.log # 应实时滚动模型加载日志

若tail无输出，检查/var/log/openrig/目录权限是否为755且属主为root。

3.4 OpenRig 主程序部署与配置文件精解

OpenRig 的主程序是一个轻量级 Node.js CLI 工具，其灵魂在于rig.config.json的设计。

克隆并安装主程序：

git clone https://github.com/openrig-org/core.git /opt/openrig cd /opt/openrig npm install --production # 仅安装生产依赖 npm link # 创建全局命令 openrig

创建生产级配置文件：
```
mkdir -p /opt/openrig/config cat > /opt/openrig/config/rig.config.json << 'EOF' { "server": { "port": 3000, "host": "0.0.0.0", "cors": ["http://localhost:5173"] }, "models": { "deepseek-coder-32b": { "binary": "codex", "args": ["--model", "deepseek-coder:32b", "--port", "{PORT}", "--host", "0.0.0.0", "--endpoint", "http://localhost:11434/api/chat"], "env": { "CODER_MODEL_PATH": "/data/models/deepseek-coder-32b", "NODE_OPTIONS": "--max-old-space-size=16384 --stack-size=4096" }, "health_check": { "url": "http://localhost:{PORT}/health", "timeout": 30000, "interval": 10000 } } } } EOF
```
此配置的关键字段解读：
- server.cors: 允许前端（如 VS Code 插件）跨域访问，http://localhost:5173是 Vite 开发服务器默认端口。
- models.*.health_check: OpenRig 主进程会每 10 秒向http://localhost:8081/health发送 GET 请求。若 30 秒内无响应，则触发tmux kill-session并重启。这是防止cc switch local proxy failed类错误的主动防御。
- NODE_OPTIONS中新增--stack-size=4096: 解决 Codex CLI 在处理超长函数签名时的RangeError: Maximum call stack size exceeded，将栈大小从默认 984KB 提升至 4MB。

启动 OpenRig 服务：

# 以后台服务方式启动 pm2 start /opt/openrig/bin/openrig.js --name "openrig-main" -- -c /opt/openrig/config/rig.config.json pm2 startup # 生成开机启动脚本 pm2 save

验证：curl http://localhost:3000/api/status应返回 JSON 包含deepseek-coder-32b的status: "running"。

4. 实操全流程与关键环节实现：一次完整的模型服务上线实录

现在，我们将以部署deepseek-coder-32b模型为例，走一遍从零到生产可用的全流程。这不是理论演示，而是我上周在客户现场的真实操作记录，包含所有命令、输出片段和决策依据。

4.1 第一步：准备模型文件与存储路径

OpenRig 不下载模型，它只调度已存在的模型。因此，首要任务是让deepseek-coder-32b的 GGUF 文件就位。

确认模型文件格式与路径：

# 检查 Ollama 是否已拉取（推荐方式） ollama list | grep deepseek-coder # 若无，执行 ollama pull deepseek-coder:32b # 查找模型实际路径（Ollama 2.0+） ollama show deepseek-coder:32b --modelfile | grep -A5 "FROM" # 输出类似：FROM /home/user/.ollama/models/blobs/sha256-abc123...

实操心得：不要手动下载 GGUF 文件！Ollama 的pull命令会自动处理量化、校验和路径注册。手动放置文件到/data/models/会导致 Codex CLI 无法识别，报错model not found。

创建模型路径并授权：
```
mkdir -p /data/models/deepseek-coder-32b chown -R ollama:ollama /data/models/deepseek-coder-32b chmod -R 755 /data/models/deepseek-coder-32b
```
为什么是ollama:ollama？因为 Codex CLI 以ollama用户身份运行（由 systemd 服务定义），若权限不足，会报错permission denied读取模型文件。

4.2 第二步：启动 Codex CLI 服务并注入 OpenRig 管理

这是最关键的衔接点。我们必须让 Codex CLI 在 tmux 中运行，并被 OpenRig 主进程识别。

执行 OpenRig 启动命令：
```
openrig start --model deepseek-coder-32b --port 8081
```
此命令内部执行：
- 读取rig.config.json，获取deepseek-coder-32b的args和env；
- 调用/opt/openrig/scripts/start-model.sh deepseek-coder-32b 8081；
- tmux 创建会话并执行codex --model deepseek-coder:32b --port 8081 --host 0.0.0.0 --endpoint http://localhost:11434/api/chat。

实时监控启动过程：

# 查看 tmux 会话输出 tmux attach -t openrig-deepseek-coder-32b-8081

你会看到类似输出：

INFO[0000] Starting Codex server... INFO[0001] Loading model from Ollama endpoint... INFO[0045] Model loaded successfully. Listening on http://0.0.0.0:8081

若卡在Loading model...超过 60 秒，立即Ctrl+b d退出 tmux，然后：

# 检查 Ollama 服务状态 systemctl status ollama # 查看 Ollama 日志 journalctl -u ollama -n 50 --no-pager

常见问题：failed to load model: context deadline exceeded—— 这是 Ollama 加载 32B 模型超时，需在/etc/ollama/ollama.conf中增加OLLAMA_CONTEXT_TIMEOUT=300。

验证服务可达性：

# 从 OpenRig 主进程视角测试 curl -X POST http://localhost:3000/api/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-coder-32b", "messages": [{"role": "user", "content": "Hello"}] }'

成功响应应包含choices[0].message.content字段。若返回503 Service Unavailable，检查 OpenRig 主进程日志：pm2 logs openrig-main，常见原因是 health check 失败。

4.3 第三步：集成前端与 CLI 工具链

OpenRig 的价值最终要落到开发者日常工具中。我们以 VS Code 插件和自定义 CLI 为例。

VS Code 插件配置（OpenRig Extension）：
- 安装插件后，在settings.json中添加：
```
"openrig.endpoint": "http://localhost:3000", "openrig.model": "deepseek-coder-32b"
```
- 插件会自动将Ctrl+Shift+I（代码补全）请求转发至http://localhost:3000/api/v1/chat/completions。

构建个人 CLI 工具（mycodex）：

cat > /usr/local/bin/mycodex << 'EOF' #!/bin/bash # 封装 OpenRig API 调用 if [ "$1" = "chat" ]; then curl -s -X POST http://localhost:3000/api/v1/chat/completions \ -H "Content-Type: application/json" \ -d "{\"model\":\"deepseek-coder-32b\",\"messages\":[{\"role\":\"user\",\"content\":\"$2\"}]}" | jq -r '.choices[0].message.content' else echo "Usage: mycodex chat 'your prompt'" fi EOF chmod +x /usr/local/bin/mycodex

测试：mycodex chat "write a python function to calculate fibonacci"—— 应立即返回代码。

4.4 第四步：生产环境加固与监控体系搭建

上线不等于完成。真正的 OpenRig 部署，必须包含可观测性和容灾能力。

日志集中化：

# 配置 rsyslog 转发 OpenRig 日志 cat > /etc/rsyslog.d/50-openrig.conf << 'EOF' template(name="OpenRigFormat" type="string" string="%TIMESTAMP% %HOSTNAME% openrig: %msg%\n") if $programname == 'openrig-main' then /var/log/openrig/main.log;OpenRigFormat if $programname == 'openrig-deepseek-coder-32b' then /var/log/openrig/deepseek-coder-32b.log;OpenRigFormat EOF systemctl restart rsyslog

Prometheus 监控指标暴露： OpenRig 主程序内置/metrics端点。在 Prometheus 配置中添加：
```
- job_name: 'openrig' static_configs: - targets: ['localhost:3000']
```
Grafana 仪表盘可监控：openrig_model_up{model="deepseek-coder-32b"}（1=健康）、openrig_token_total{model="deepseek-coder-32b"}（累计 token 数）、openrig_request_duration_seconds_bucket（P95 延迟）。
自动清理 WinsXS（Windows 用户专属）：网络热词中清理winsxs cli高频出现。OpenRig 为 Windows 版本提供了openrig cleanup winsxs命令，其原理是调用DISM /Online /Cleanup-Image /StartComponentCleanup，而非第三方工具。它会在C:\Windows\WinSxS占用超过 80% 时触发，避免磁盘爆满导致 Codex CLI 启动失败。

5. 常见问题与排查技巧实录：那些让你熬夜的报错，其实都有固定解法

在部署 OpenRig 的上百个项目中，90% 的问题集中在以下五个类别。我把它们整理成速查表，并附上唯一有效的解决方案（不是“试试这个”，而是“必须这样做”）。

报错信息（精确匹配）	根本原因	一招解决法	为什么有效
`cc switch local proxy failed while handling codex endpoint /responses`	Codex CLI 进程残留 socket 未释放，新进程绑定端口失败	`tmux kill-session -t openrig-* && pkill -f "codex --model"`	tmux 会话杀掉所有子进程，`pkill`清理可能逃逸的孤儿进程，双保险确保端口干净
`unable to locate the codex cli binary or required runtime components`	`PATH`未正确注入 tmux 会话，或`codex`二进制权限不足	`chmod +x /opt/openrig/bin/codex && echo 'export PATH="/opt/openrig/bin:$PATH"' >> /etc/profile.d/openrig.sh && source /etc/profile.d/openrig.sh`	tmux 非交互式 shell 不读取`~/.bashrc`，必须写入`/etc/profile.d/`全局生效
`internetopenurl() failed. 0x800`(Windows)	Codex CLI 内置 WinHTTP 客户端证书验证失败	`set NODE_TLS_REJECT_UNAUTHORIZED=0`仅限内网环境，或`certutil -addstore -f "ROOT" your-ca.crt`	绕过 TLS 验证是最快方案，但生产环境必须导入 CA 证书到系统根存储
`codex auth token is unavailable`	OpenRig 配置中`--endpoint`指向了需要 Auth Token 的私有 API，但未提供	在`rig.config.json`的`models.*.env`中添加`"CODER_AUTH_TOKEN": "your-token-here"`	Codex CLI 会自动将 `COD