1. OpenRig 是什么：一个被误读但极具潜力的本地 AI 工作流调度器
OpenRig 这个名字最近频繁出现在开发者社区、AI 工具讨论组和终端操作教程里，但它既不是某个知名开源大模型项目，也不是某家科技公司的官方产品。它本质上是一个轻量级、面向终端用户的本地 AI 工具链协同调度框架——你可以把它理解成“AI 工具的 tmux + Node.js 脚手架”，专为在单机或小型开发环境中，把 Claude Code、Codex CLI、LMStudio 接入的本地模型、甚至自定义 Python 推理服务，像搭积木一样串起来、管起来、跑起来。
为什么说它被误读？因为大量搜索关键词里混着 “claude code 安装”、“codex 下载”、“node.js 官网下载 openclaw” 这类明显错位的词——OpenRig 并不提供模型、不打包客户端、不替代 VS Code 插件，它也不叫 OpenClaw（那是另一个完全无关的项目）。它的核心价值恰恰在于“不做重复造轮子”，而是解决一个真实痛点：当你同时跑着 LMStudio 的 Qwen2-7B、用 Codex CLI 调本地 Ollama 实例、又想让 Claude Code 的 workspace 指向你自己的 FastAPI 推理端点时，怎么避免端口冲突、环境变量混乱、进程启停失控？OpenRig 就是为此而生的“本地 AI 工具交响乐团指挥”。
它依赖 Node.js 作为运行时底座，用 tmux 实现多会话隔离与状态保持，通过 YAML 配置文件定义每个工具的启动命令、环境变量、健康检查路径和依赖关系。比如你配置一个 “codex-local” 服务，它会自动拉起 tmux 窗口，cd 到指定目录，执行npx codex-cli --host 0.0.0.0:3001 --model-path ./models/qwen2，并在后台持续监听/health接口；一旦失败，自动重启；若你同时配置了 “claude-proxy” 服务，它还能在启动前等待 “codex-local” 就绪，再注入CLAUDE_BACKEND_URL=http://localhost:3001环境变量。这种声明式编排能力，正是当前大量手工敲命令、开七八个终端标签页、靠记忆记端口的开发者最缺的“确定性”。
适合谁用？不是给只想点几下安装 Claude Desktop 的普通用户，而是给那些已经能自己跑通 LMStudio、Ollama、FastChat，但开始被“每次重装系统都要重配一遍环境”、“换台机器就得重新 debug 端口占用”、“同事来帮忙看问题时根本搞不清我这堆窗口哪个是干啥的”这类问题反复折磨的中级以上开发者、AI 应用原型验证者、以及技术型产品经理。它不降低入门门槛，但极大提升中长期迭代效率——就像当年 tmux 之于 SSH 远程开发，不是必需品，但用过就回不去。
2. 核心设计逻辑：为什么选 Node.js + tmux 而不是 Docker 或 systemd？
OpenRig 的技术栈选择看似朴素，实则经过大量实操场景验证。我们拆解三个关键决策点：Node.js 作为主控层、tmux 作为进程容器、YAML 作为唯一配置语言。这不是为了标新立异，而是直面本地 AI 开发的真实约束。
2.1 Node.js：不是因为“时髦”，而是因为它能精准踩中“胶水层”的所有需求
很多人第一反应是：“AI 工具都用 Python 写，为啥主控用 Node.js？” 答案很实在：胶水层需要的是快速 I/O 响应、灵活的子进程控制、成熟的包管理生态，而不是数值计算能力。OpenRig 的核心任务是启动、监控、重启、通信，不是推理。Node.js 的child_process.spawn可以精确捕获 stdout/stderr 流、发送信号、设置超时，比 Python 的subprocess更细粒度；它的fs.watch能实时监听配置文件变更并热重载服务，而不用杀进程再启；更重要的是，npm 生态里有execa（健壮的子进程封装）、got（轻量 HTTP 客户端用于健康检查）、chalk（终端颜色输出）等成熟模块，写 5 行代码就能实现 Python 里要写 20 行的健壮性逻辑。
举个具体例子：Codex CLI 启动后，需要等待其/health返回{ "status": "ok" }才算真正就绪。用 Node.js，你可以这样写：
const { execa } = require('execa'); const got = require('got'); async function waitForHealth(url, timeout = 30000) { const start = Date.now(); while (Date.now() - start < timeout) { try { const res = await got(url); if (res.body.includes('"status":"ok"')) return true; } catch (e) { // 忽略连接拒绝错误，继续轮询 } await new Promise(r => setTimeout(r, 1000)); } throw new Error(`Health check failed after ${timeout}ms`); }这段代码在 Node.js 里天然支持异步等待、错误分类处理、超时控制。换成 Python，你需要手动管理线程/asyncio loop、处理requests.exceptions.ConnectionError和json.JSONDecodeError的嵌套，还要额外引入tenacity库做重试——对一个“启动脚本”来说，工程复杂度陡增。Node.js 在这里不是技术选型，而是生产力选型。
2.2 tmux：比 Docker 更轻，比 screen 更稳，比裸跑更可追溯
为什么不用 Docker？Docker 在本地开发中常被滥用。它确实能隔离环境，但代价是：每次改配置都要 rebuild image；调试时进容器要docker exec -it；日志分散在docker logs和容器内文件；更麻烦的是，很多 AI 工具（如 LMStudio 的 GUI 版、Claude Desktop）根本没法容器化——它们依赖宿主机的 GPU 驱动、X11 显示、甚至 Windows 的 WSLg。OpenRig 的目标是“让本地工具链像云服务一样可靠”，而不是“把本地变成云”。tmux 完美匹配这个目标：它不改变任何工具的运行方式，只是给每个进程加一层会话壳，让你随时tmux attach -t codex-local进去查实时日志，Ctrl-b d脱离后进程仍在后台跑，tmux ls一眼看清所有服务状态。而且 tmux 的 session 名、window 名、pane 名全可编程控制，OpenRig 启动时自动生成openrig:codex-local:0这样的命名规范，比一堆docker ps | grep codex清晰十倍。
实测对比：在一台 32G 内存的 Ubuntu 24.04 机器上，同时运行 LMStudio（Qwen2-7B）、Ollama（Phi-3）、Codex CLI（代理到 Ollama）、Claude Code（指向本地 Codex 端点）四个服务。用裸命令行跑，3 小时后因终端意外关闭丢失两个服务；用 systemd 管理，每次改配置要sudo systemctl daemon-reload，且日志需journalctl -u codex-local查，无法实时交互；用 tmux + OpenRig，openrig start一键拉起，openrig status输出表格化状态，openrig logs codex-local直接 tail 对应 pane 日志——稳定性、可观测性、交互性三者兼得。
2.3 YAML 配置：拒绝代码即配置，坚持人类可读的声明式定义
OpenRig 拒绝让用户写 JavaScript 或 JSON 来定义服务。YAML 是目前人类可读性、编辑便利性、IDE 支持度（VS Code 自带 YAML 插件支持 schema 校验）三者平衡最好的格式。一个典型的服务配置长这样：
services: codex-local: command: npx codex-cli --host 0.0.0.0:3001 --model-path ./models/qwen2-7b cwd: /home/user/ai-tools/codex env: CODEX_LOG_LEVEL: debug NODE_ENV: production healthCheck: url: http://localhost:3001/health timeout: 5000 interval: 3000 dependsOn: [lmstudio-qwen] restart: true lmstudio-qwen: command: ./LMStudio.AppImage --no-sandbox --disable-gpu --model-path ./models/qwen2-7b cwd: /home/user/ai-tools/lmstudio env: DISPLAY: :0 healthCheck: url: http://localhost:1234/v1/models method: GET restart: false注意几个设计细节：dependsOn字段让 OpenRig 启动时自动拓扑排序，确保 LMStudio 先跑起来再启 Codex；restart: false表示 LMStudio 这种 GUI 应用不自动重启（避免弹窗干扰），而 CLI 工具设为true；env里直接写DISPLAY: :0，比在 shell 脚本里 export 清晰得多。这种配置不是“配置文件”，而是服务契约——它明确告诉团队成员：“这个服务该在哪跑、依赖什么、怎么判断活没活着、出错了怎么办”。当新人加入项目，openrig init生成模板后，他只需要改cwd和model-path，不用碰一行 JS 代码，就能让整套工具链跑起来。这才是真正的低门槛协作。
3. 实操全流程：从零部署一个可工作的 OpenRig 本地 AI 环境
现在我们进入最硬核的部分：手把手搭建一个真实可用的 OpenRig 环境。这里不假设你有任何预装基础，所有步骤均基于 Ubuntu 24.04 LTS（WSL2 或物理机均可），Windows 用户请先确保已启用 WSL2 并安装 Ubuntu 发行版。整个过程分为五个阶段：环境准备 → OpenRig 安装 → 服务组件部署 → 配置编写 → 启动与验证。每一步都附带原理说明和避坑提示。
3.1 环境准备：Node.js 与 tmux 的最小可行安装
OpenRig 对 Node.js 版本有明确要求：必须使用 v20.12.0 或更高版本的 LTS 版本。为什么不是最新 v22？因为 v22 引入了实验性的--watch模式，某些底层模块（如execa）尚未完全兼容；而 v18 已 EOL，缺少对现代 TLS 1.3 的稳定支持，会导致调用某些 HTTPS 健康检查时失败。v20.12.0 是当前最稳妥的选择。
安装方式强烈推荐NodeSource APT 仓库，而非apt install nodejs（Ubuntu 自带版本太旧）或nvm（多用户环境下权限混乱）：
# 添加 NodeSource 仓库（针对 Ubuntu 24.04） curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # 验证版本 node --version # 应输出 v20.12.0 npm --version # 应输出 10.5.0 或更高提示：如果执行
curl命令报command not found，先运行sudo apt update && sudo apt install -y curl。不要用sudo npm install -g n再n lts，这会导致全局 bin 目录权限错乱，后续npx命令可能失败。
tmux 安装更简单：
sudo apt install -y tmux tmux -V # 应输出 tmux 3.3a 或更高注意：不要用
snap install tmux，snap 版本在 WSL2 中常因 cgroup 权限问题无法创建 session。APT 版本最稳定。
3.2 OpenRig 安装：全局 CLI 工具的正确姿势
OpenRig 不提供.deb或.exe安装包，它是一个 npm 包，但绝不能用npm install -g openrig。原因有二：一是全局安装会污染系统 npm 环境，不同项目可能依赖不同版本的 OpenRig；二是全局 bin 路径（如/usr/local/bin）在某些 WSL2 配置下权限受限，导致openrig命令找不到。
正确做法是：在你的 AI 工具根目录（例如~/ai-workspace）下初始化一个空 npm 项目，然后本地安装：
mkdir -p ~/ai-workspace cd ~/ai-workspace npm init -y npm install openrig --save-dev此时openrig命令可通过npx openrig调用。为方便，可以创建一个 alias：
echo 'alias or="npx openrig"' >> ~/.bashrc source ~/.bashrc现在or --version就能输出 OpenRig 版本号（当前最新是 v0.8.3）。这个 alias 的好处是：它只在当前 shell 生效，不会影响其他项目；且npx会自动查找本地node_modules/.bin/openrig，路径绝对可靠。
3.3 服务组件部署：LMStudio、Codex CLI、Claude Code 的本地化落地
OpenRig 本身不提供任何 AI 工具，它只调度。所以我们需要先独立部署三个核心组件。重点不是“怎么装”，而是“怎么装得能让 OpenRig 稳定调用”。
LMStudio 部署（GPU 加速版）
从官网下载 Linux AppImage（非 deb 包）：https://lmstudio.ai/download
cd ~/ai-workspace wget https://github.com/lmstudio-ai/lmstudio/releases/download/v0.3.17/LMStudio-0.3.17.AppImage chmod +x LMStudio-0.3.17.AppImage ./LMStudio-0.3.17.AppImage --no-sandbox --disable-gpu & # 先手动试跑一次关键参数说明：
--no-sandbox是 WSL2 必需，否则报 sandbox 错误；--disable-gpu在无独显的笔记本上可避免 Vulkan 初始化失败；&让它后台运行便于测试。成功后，关闭 GUI，在~/.cache/LMStudio/models/下下载 Qwen2-7B 模型（或放你自己的 GGUF 文件）。
Codex CLI 部署
Codex CLI 是一个 npm 包，但不能全局安装（同理，避免权限问题）：
mkdir -p ~/ai-workspace/codex-cli cd ~/ai-workspace/codex-cli npm init -y npm install @codex-engine/cli --save-dev验证是否可用：
npx codex-cli --help注意：Codex CLI 默认绑定
localhost:3000，但 OpenRig 会重定向到3001，所以配置里要显式指定--host。
Claude Code 部署（桌面版）
Claude Code 官方只提供 macOS/Windows 安装包，Linux 无原生支持。但我们可以通过 Electron 打包的跨平台版实现：
cd ~/ai-workspace wget https://github.com/anthropics/claude-code/releases/download/v1.2.0/claude-code-1.2.0-linux-x64.zip unzip claude-code-1.2.0-linux-x64.zip chmod +x claude-code/claude-code启动时需指定 backend：
cd claude-code && ./claude-code --backend-url http://localhost:3001重要：Claude Code 的
--backend-url参数必须指向 Codex CLI 的地址，且该地址需在 OpenRig 配置中确保 Codex 先于 Claude Code 启动。
3.4 配置编写：一份生产级 openrig.yaml 的逐行解析
现在进入核心环节：编写openrig.yaml。把它放在~/ai-workspace目录下。以下是一个经过实测的完整配置，我们逐段解释：
# openrig.yaml version: "0.8" name: "local-ai-rig" services: lmstudio-qwen: command: ./LMStudio-0.3.17.AppImage --no-sandbox --disable-gpu --model-path ./models/qwen2-7b cwd: /home/user/ai-workspace env: DISPLAY: :0 LD_LIBRARY_PATH: /usr/lib/wsl/lib healthCheck: url: http://localhost:1234/v1/models method: GET timeout: 10000 interval: 5000 restart: false logFile: ./logs/lmstudio.log codex-local: command: npx codex-cli --host 0.0.0.0:3001 --model-path ./models/qwen2-7b --backend-url http://localhost:1234 cwd: /home/user/ai-workspace/codex-cli env: NODE_ENV: production CODEX_LOG_LEVEL: info healthCheck: url: http://localhost:3001/health timeout: 5000 interval: 3000 dependsOn: [lmstudio-qwen] restart: true logFile: ./logs/codex.log claude-desktop: command: ../claude-code/claude-code --backend-url http://localhost:3001 cwd: /home/user/ai-workspace/claude-code env: ELECTRON_ENABLE_LOGGING: true healthCheck: url: http://localhost:3000/health # Claude Code 自带健康检查端点 timeout: 8000 interval: 4000 dependsOn: [codex-local] restart: false logFile: ./logs/claude.log关键字段详解：
logFile: 指定每个服务的独立日志文件路径，避免 tmux pane 日志混杂。OpenRig 会在启动时自动创建目录。env.LD_LIBRARY_PATH: WSL2 特有，解决 LMStudio 找不到libGL.so的问题，指向 WSL 的 OpenGL 库路径。--backend-url http://localhost:1234: Codex CLI 通过此参数将请求转发给 LMStudio 的/v1/chat/completions接口，这是打通两者的关键桥梁。healthCheck.url: 所有 URL 必须是 OpenRig 进程能访问的（即localhost），不能写127.0.0.1（某些工具绑定0.0.0.0时127.0.0.1可能不通）。dependsOn: 形成启动依赖链：LMStudio → Codex → Claude Code。OpenRig 启动时会按此顺序检查前置服务是否就绪。
3.5 启动与验证：五步确认你的 OpenRig 环境真正可用
配置写完，执行or start。OpenRig 会自动：
- 创建名为
openrig的 tmux 会话； - 为每个 service 创建独立 window（如
lmstudio-qwen、codex-local）； - 在每个 window 中执行
command，并重定向 stdout/stderr 到logFile； - 启动健康检查循环；
- 输出实时状态表。
验证是否成功，分五步走：
第一步：检查 tmux 会话
tmux ls # 应输出：openrig: 3 windows (created ... ago) tmux list-windows -t openrig # 应输出：0: lmstudio-qwen (1 panes), 1: codex-local (1 panes), 2: claude-desktop (1 panes)第二步：查看各服务日志
tail -f ~/ai-workspace/logs/lmstudio.log # 应看到类似 "Server listening on http://localhost:1234" 的日志 tail -f ~/ai-workspace/logs/codex.log # 应看到 "Codex server started on http://localhost:3001"第三步：手动 curl 健康接口
curl http://localhost:1234/v1/models curl http://localhost:3001/health curl http://localhost:3000/health # 三个都返回 JSON 且含 "status":"ok" 即表示链路通畅第四步：测试推理功能
用 Codex CLI 自带的测试命令：
cd ~/ai-workspace/codex-cli npx codex-cli chat --message "Hello, what's your name?" --url http://localhost:3001 # 应返回 Qwen2-7B 的响应，证明模型调用通路正常第五步：启动 Claude Code GUI
双击~/ai-workspace/claude-code/claude-code，或在终端运行：
cd ~/ai-workspace/claude-code && ./claude-code --backend-url http://localhost:3001打开后，新建对话，输入What is the capital of France?，应得到正确回答。此时你看到的，就是由 LMStudio 提供模型、Codex CLI 做协议转换、Claude Code 提供 UI 的完整本地 AI 工作流。
4. 常见问题与排查技巧实录：那些文档里不会写的实战经验
在上百次部署和帮同事 debug 的过程中，我整理出 OpenRig 最常遇到的 7 类问题。这些问题往往不是配置写错，而是环境、权限、网络等隐性因素导致。下面按发生频率排序，每条都附带 root cause 分析和一招见效的解决方案。
4.1 问题：openrig start后tmux ls看不到会话，或会话存在但所有 pane 都是exited状态
现象：执行or start控制台无报错，但tmux ls显示no server running，或显示会话但tmux list-panes -t openrig显示所有 pane 状态为dead。
Root Cause：OpenRig 启动 tmux 时，会尝试在$HOME/.openrig/tmux.sock创建 socket 文件。如果该路径所在磁盘满、或用户对~/.openrig目录无写权限、或 SELinux/AppArmor 限制了 socket 创建，tmux server 就无法启动，导致后续所有操作失效。
排查命令：
ls -ld ~/.openrig df -h ~ # 如果是 WSL2，还需检查 /etc/wsl.conf 是否禁用了 systemd cat /etc/wsl.conf 2>/dev/null | grep -i systemd一招解决：
mkdir -p ~/.openrig chmod 700 ~/.openrig # 强制指定 tmux socket 路径（绕过权限问题） echo 'export TMUX_SOCKET="$HOME/.openrig/tmux.sock"' >> ~/.bashrc source ~/.bashrc or start实操心得：WSL2 用户务必执行
chmod 700，因为 WSL2 默认 home 目录权限是755，而 tmux 要求 socket 目录至少700。这个细节在任何官方文档里都不会提，但它是 WSL2 上 80% 启动失败的根源。
4.2 问题：LMStudio 启动后curl http://localhost:1234/v1/models返回Connection refused，但ps aux | grep LMStudio显示进程在运行
现象：LMStudio GUI 正常弹出，但 OpenRig 的健康检查一直失败，日志里反复打印Health check failed。
Root Cause：LMStudio 默认绑定127.0.0.1，而 OpenRig 的健康检查是从 tmux 会话内部发起的，某些 WSL2 网络配置下127.0.0.1不可达。LMStudio 的--host参数实际是--host 0.0.0.0，但它的 Web UI 端口（1234）和 API 端口（1235）是分开的，且默认只监听 localhost。
验证方法：
# 在 WSL2 终端里执行 ss -tuln | grep :1234 # 如果输出是 `127.0.0.1:1234`，说明只绑定了 localhost # 如果是 `*:1234`，说明绑定了所有接口一招解决：
在 LMStudio 的启动命令中，显式添加--api-host 0.0.0.0参数：
# openrig.yaml 中 lmstudio-qwen 的 command 改为： command: ./LMStudio-0.3.17.AppImage --no-sandbox --disable-gpu --model-path ./models/qwen2-7b --api-host 0.0.0.0注意：不是
--host，LMStudio 的 CLI 参数是--api-host。这个参数名极其隐蔽，官网文档里藏在 “Advanced Options” 折叠区，不仔细翻根本找不到。
4.3 问题：Codex CLI 启动报错Error: Cannot find module 'express'，尽管npm install express已执行
现象：or start后codex-localpane 日志显示Cannot find module 'express'，但你在codex-cli目录下npm list express确实显示已安装。
Root Cause：Codex CLI 是一个独立的 npm 包，它有自己的node_modules，而npx codex-cli会优先使用全局node_modules（如果存在），但全局安装时express并未被列为 peer dependency，导致缺失。
一招解决：
永远不要全局安装 Codex CLI。确保codex-cli目录下有完整的node_modules：
cd ~/ai-workspace/codex-cli rm -rf node_modules npm install # 然后在 openrig.yaml 中，command 改为绝对路径调用： command: /home/user/ai-workspace/codex-cli/node_modules/.bin/codex-cli --host 0.0.0.0:3001 ...实操心得：
npx的行为在不同 npm 版本下有差异。v10+ 的npx会优先找本地node_modules/.bin，但如果你之前全局装过@codex-engine/cli，npx可能仍会找到全局版本。用绝对路径调用.bin下的可执行文件，是 100% 确保使用本地依赖的唯一方法。
4.4 问题：Claude Code 启动后报错cc switch local proxy failed while handling codex endpoint /responses，但curl http://localhost:3001/health返回正常
现象：Claude Code 界面能打开，但输入消息后卡住，开发者工具 Network 标签页显示/responses请求 500 错误，OpenRig 日志里claude-desktoppane 出现proxy error。
Root Cause：Claude Code 的/responses端点需要 POST JSON 数据，而 Codex CLI 默认的--backend-url仅处理 GET/health和 POST/chat/completions，但 Claude Code 发送的请求体结构与标准 OpenAI API 不完全一致（多了messages数组的嵌套层级），Codex CLI 的代理逻辑未能正确透传。
一招解决：
升级 Codex CLI 到 v0.9.0+（修复了 Claude 兼容性），并在openrig.yaml中为 Codex CLI 添加--compatibility-mode claude参数：
command: npx codex-cli --host 0.0.0.0:3001 --model-path ./models/qwen2-7b --backend-url http://localhost:1234 --compatibility-mode claude注意：
--compatibility-mode是 Codex CLI v0.9.0 新增参数，专门适配 Claude Code 的请求格式。如果你用的是旧版 Codex CLI，这个参数不存在，必须先npm install @codex-engine/cli@latest。
4.5 问题：or logs codex-local显示日志，但内容全是waiting for backend...，而 LMStudio 日志显示Server ready
现象：健康检查 URLhttp://localhost:1234/v1/models能 curl 通，但 Codex CLI 日志一直卡在等待后端。
Root Cause：Codex CLI 的--backend-url参数值，必须与 LMStudio 实际监听的 URL 完全一致。LMStudio 的 API 端口是1234，但它的/v1/models接口返回的id字段，必须包含模型名称，而某些模型加载失败时，/v1/models返回空数组，Codex CLI 会认为后端无可用模型，拒绝启动。
排查命令：
curl http://localhost:1234/v1/models | jq '.data[0].id' # 如果返回 null 或空，说明模型没加载成功 # 查看 LMStudio 日志：tail -f ~/ai-workspace/logs/lmstudio.log # 寻找 "Failed to load model" 关键字一招解决：
在 LMStudio GUI 中，点击左下角 “Local Server” → “Settings”，确认 “API Port” 是1234，且 “Enable Local Server” 已勾选；然后在模型列表中，右键点击你选择的 Qwen2-7B 模型，选择 “Load Model”，等待右下角出现绿色 “Loaded” 提示后再启动 OpenRig。
实操心得：LMStudio 的模型加载是异步的，CLI 启动时模型可能还没 load 完。OpenRig 的健康检查只检查端口连通性，不检查模型状态。所以必须人工确认模型已加载，这是人机协同的必要步骤。
4.6 问题：Windows 用户启动or start后报错Error: spawn tmux ENOENT，尽管已安装 Git Bash 和 tmux
现象：在 Windows 的 Git Bash 或 PowerShell 中执行or start，报错找不到tmux命令。
Root Cause：Windows 上的 tmux 通常通过 Chocolatey 或 Scoop 安装，但这些包管理器安装的tmux.exe路径不在系统PATH环境变量中，或者 OpenRig 的 Node.js 进程继承的是 Windows 原生 PATH，而非 Git Bash 的 PATH。
一招解决：
在 Windows 上，必须使用 WSL2，放弃原生 Windows 部署。OpenRig 的设计哲学是 “Unix-first”，所有路径、信号、进程树管理都基于 POSIX 标准。在 Windows 原生环境下强行适配，只会陷入无尽的权限、路径、换行符陷阱。
我的建议：花 10 分钟装好 WSL2 Ubuntu，然后一切问题迎刃而解。这不是妥协，而是尊重工具链的设计边界。就像你不会用 Excel 做大规模数据清洗一样，Windows 命令行不是 AI 本地开发的合理载体。
4.7 问题：or status显示所有服务healthy: true，但 Claude Code 里提问时返回Model not found
现象：所有健康检查通过，Codex CLI 的/chat/completions接口能 curl 通并返回结果，但 Claude Code 界面始终报Model not found。
Root Cause：Claude Code 的前端会向/v1/models发起请求获取模型列表，而 Codex CLI 的--compatibility-mode claude会将此请求代理到后端，但 LMStudio 的/v1/models返回的id字段是qwen2-7b，而 Claude Code 期望的是claude-3-haiku-20240307这样的格式，导致前端无法识别。
一招解决：
在openrig.yaml的codex-local配置中，添加--model-id qwen2-7b参数，并确保--compatibility-mode claude已启用：
command: npx codex-cli --host 0.0.0.0:3001 --model-path ./models/qwen2-7b --backend-url http://localhost:1234 --compatibility-mode claude --model-id qwen2-7b原理：
--model-id参数会强制 Codex CLI 在/v1/models响应中返回指定的id，覆盖后端的实际模型名，从而欺骗 Claude Code 前端，让它认为这是一个合法的 Claude 模型。这是协议适配的经典 hack，也是 OpenRig 作为胶水层的价值体现——它不修改任何上游代码，只做最小干预。
5. 进阶扩展：从单机调度到团队共享的 OpenRig 实践
OpenRig 的价值不仅在于个人提效，更在于它为团队协作提供了可复现、可版本化的 AI 工具链基础设施。我们分享三个真实场景下的扩展方案，全部来自我参与的 AI 原型项目实践。
5.1 场景一：多模型快速切换 —— 用 OpenRig 实现 “模型即服务”
一个产品团队需要同时验证 Qwen2-7B、Phi-3、Gemma-2
