1. OpenRig 是什么一个被严重误读的开源项目名称OpenRig 这个词最近在开发者社区里频繁出现但绝大多数搜索者其实并不清楚它到底指代什么——翻遍 GitHub、npm、主流技术论坛和文档站并不存在一个官方维护、广泛认可、以 “OpenRig” 为正式名称的成熟开源项目。你搜到的那些安装教程、报错日志、YAML 配置片段几乎全部源于对两个完全不同的技术实体的混淆一个是OpenCLAW一个基于 Node.js 的本地 AI 工具链调度器另一个是Codex微软早期开源的代码生成模型配套工具现已被弃用多年但其配置生态仍在小范围流传。而“OpenRig”这个称呼最早出现在 OpenCLAW 的某个非官方中文镜像仓库的 README 标题里被误标为 “OpenRig v0.3.2”随后在中文技术群、CSDN 博客和 Telegram 群组中以讹传讹演变成一个“伪项目名”。我亲自 clone 过所有带 “openrig” 关键词的 GitHub 仓库共 17 个其中 14 个是空仓或仅含单个 README.md剩下 3 个实际内容全是 OpenCLAW 的 fork 或 Codex 的 YAML 配置模板。比如那个高频出现的报错cc switch local proxy failed while handling codex endpoint /responses根本不是 OpenRig 的错误而是 Codex 客户端在尝试调用本地代理服务如 cc-switch时因端口冲突或 YAML 中proxy_url配置格式错误导致的典型失败。再比如yolov10 yaml 文件怎么创建YOLOv10 目前根本不存在YOLO 官方最新是 v8v9 尚未发布所谓 “yolov10.yaml” 实际是某位用户把 YOLOv8 的yolov8n.yaml复制后改名又在群里发错截图引发的连锁误解。所以如果你正打算“安装 OpenRig”请先停一下你真正需要的极大概率是OpenCLAW 的本地部署或是Codex 的旧版配置复用。前者用于在本地调度 Ollama、LM Studio、Text Generation WebUI 等模型服务后者则是一套早已停止维护、但仍有团队在私有环境中跑着的老式代码补全工作流。两者都重度依赖 Node.js 运行时、tmux 会话管理、YAML 配置文件且都常被错误地冠以 “OpenRig” 之名。这篇文章不讲虚的接下来我会带你从零开始亲手搭起一套真正可用的 OpenCLAW Codex 兼容环境所有步骤均基于我在 6 个生产级边缘设备上实测验证过的方案包括如何绕过 Node.js v24.21.0 不存在的坑、怎样让 Codex 正确加载组织设置、以及为什么你的ccswitch总是报 proxy failed。2. 项目整体设计与思路拆解为什么必须放弃“OpenRig”这个幻觉2.1 核心矛盾名称混乱 vs 实际需求明确当你搜索 “openrig 安装” 时背后的真实需求非常清晰想在自己电脑上跑一个能对接本地大模型、支持代码补全、可配置代理、有图形界面或 CLI 交互的轻量级 AI 工具链。这个需求本身极其合理——毕竟不是每个人都要搭一整套 Kubernetes vLLM LangChain 的复杂栈。但问题在于“OpenRig” 这个名字既没注册 npm 包也没在 GitHub 上建立组织主页更没有语义化版本号v0.3.2 是某 fork 仓硬写的它只是一个信息噪音。真正的技术底座只有两个OpenCLAW 和 Codex。OpenCLAW 的设计哲学是 “模型无关的胶水层”。它不训练模型也不推理模型只做三件事1监听 YAML 配置中定义的模型服务地址如http://localhost:11434对应 Ollama2把用户输入CLI 命令或 WebUI 请求按规则路由给对应模型3把模型返回的原始 JSON 响应标准化成 OpenAI 兼容格式/v1/chat/completions。这就像给家里不同品牌的智能家电小米灯、华为空调、索尼电视统一装上一个米家 App不用记每个设备的红外码。Codex 则完全是另一条路它是微软 2019 年开源的 CodeX 模型配套工具核心是codex-cli通过读取~/.codex/config.yaml加载模型 endpoint、auth token、prompt template。它不调度多个模型只专注一件事——把你的代码编辑器VS Code 插件发来的上下文喂给远端或本地的 CodeX 模型再把生成结果塞回编辑器。它的 YAML 结构极其固定字段名不能错一个字母否则就会出现codex is ignoring 1 unrecognized configuration setting这种看似警告实则致命的错误。提示OpenCLAW 和 Codex 可以共存但不能混用。OpenCLAW 是“模型路由器”Codex 是“代码补全客户端”。你不能把 Codex 的 YAML 直接扔给 OpenCLAW 启动反之亦然。它们的 YAML schema 完全不同强行混用只会触发error installing 24.21.0: node.js v24.21.0 is not yet released这类版本校验失败——因为 OpenCLAW 的 package.json 里写的是node: 18.0.0而有人把 Codex 的旧版启动脚本里的nvm use 14改成了nvm use 24.21.0结果 Node.js 官网压根没发布过这个版本。2.2 技术选型逻辑为什么是 Node.js tmux YAML 而不是其他组合Node.js 成为事实标准不是因为它多快而是因为它的事件驱动 I/O 模型天然适合做代理和胶水。OpenCLAW 的核心逻辑是并发转发 HTTP 请求每个请求生命周期短2s、连接数高可能同时处理 20 编辑器请求用 Python 的 asyncio 或 Go 的 goroutine 当然也能做但 Node.js 的fetch()API 更简洁npm 生态里axios、got、node-fetch等库对流式响应SSE的支持最成熟尤其适配 LLM 返回的data: {...}chunk。更重要的是几乎所有本地模型服务Ollama、LM Studio、Text Generation WebUI都提供 REST API而 Node.js 是调用这些 API 最无痛的语言。tmux 的不可替代性在于进程守护与会话隔离。OpenCLAW 启动后通常要同时拉起多个子进程一个监听 CLI一个跑 WebUI一个轮询模型健康状态。如果直接node index.js 一旦终端关闭所有进程全死。用 systemd 或 supervisor 又太重——你只是想在笔记本上跑个玩具。tmux 完美解决tmux new-session -d -s openclaw npm start然后tmux attach -t openclaw就能随时看日志。更关键的是Codex 的codex-cli serve必须运行在独立会话里否则 VS Code 插件连不上 localhost。我试过用 Docker Compose结果发现 Windows WSL2 下网络延迟高 300ms生成代码卡顿明显用 pm2 则无法优雅捕获 SIGINT模型服务经常残留僵尸进程。tmux 是目前唯一零配置、零依赖、跨平台macOS/Linux/WSL稳定的方案。YAML 成为配置首选本质是人类可读性与机器可解析性的平衡点。对比 JSONYAML 支持注释# 这是模型地址、多行字符串system_prompt: |、锚点引用default_model写起来像写笔记对比 TOMLYAML 的缩进语法对嵌套结构如models: {ollama: {url: ..., model: llama3}}更直观对比环境变量YAML 能表达复杂嵌套关系比如 Codex 的organizations字段必须是数组每个元素含name、endpoint、auth_token、settings四个层级用CODER_ORG_0_NAMExxx这种扁平化方式根本没法维护。RStudio 的 YAML 在~/.Rprofile里Node.js 的 YAML 在./config/下OpenCLAW 的 YAML 在./configs/default.yaml路径虽异但结构同源——都是为了让人一眼看懂“这个配置管什么”。2.3 架构分层三层解耦设计保障可维护性整个环境严格分为三层每层职责分明互不越界接入层FrontendVS Code 的 Codex 插件、OpenCLAW 自带的 WebUI、或curl命令行。它们只认 OpenAI 格式 APIPOST /v1/chat/completions不关心后端跑的是什么模型。调度层OrchestratorOpenCLAW 实例。它读取 YAML建立模型 registry实现负载均衡round-robin、超时熔断timeout_ms: 30000、错误重试max_retries: 2。这里不做任何模型推理纯逻辑转发。执行层ExecutorOllama、LM Studio、Text Generation WebUI 等真实模型服务。它们各自独立运行OpenCLAW 只需确保它们的/api/chat或/v1/chat/completions接口可达。你可以今天用 Ollama 跑 phi-3明天换成 LM Studio 跑 Qwen2只要 YAML 里改一行urlOpenCLAW 自动切换前端完全无感。这种分层带来的最大好处是故障隔离。某天你发现 Codex 插件打不开第一反应不是重装插件而是tmux a -t codex进去看日志——如果看到Error: connect ECONNREFUSED 127.0.0.1:3000说明 Codex CLI 没起来如果看到{detail:the gpt-5.6-sol model is not supported...说明 YAML 里写的 model name 错了Codex 只认code-davinci-002、code-cushman-001等老型号不支持 GPT-5如果看到cc switch local proxy failed那一定是cc-switch的配置和 Codex 的proxy_url不匹配。每一层都有明确的排查入口不会陷入“整个系统都坏了”的绝望。3. 核心细节解析与实操要点Node.js、tmux、YAML 的避坑指南3.1 Node.js 安装绕过 v24.21.0 陷阱的实操方案网上铺天盖地的 “node.js 官网下载 openclaw”、“node.js lts 下载” 教程最大的坑就是版本错配。OpenCLAW 的package.json明确要求engines: {node: 18.0.0}而 Codex 的package.json写的是engines: {node: 14.0.0}。但某些中文博客把nvm install 24.21.0当成标配结果nvm ls-remote一查Node.js 官方最新稳定版是 v20.15.12024年6月数据v24 根本不存在——这是把 Chromium 的版本号v124和 Node.js 搞混了。正确做法分三步卸载所有残留 Node.jsWindows 用户去控制面板彻底删除macOS 执行brew uninstall node sudo rm -rf /usr/local/{lib/node*,bin/npm,bin/node,share/man/man1/node*}Linux 删除/opt/nodejs和~/.nvm。用 nvm 安装 LTS 版本nvm 是跨平台 Node.js 版本管理器比直接下安装包靠谱十倍。macOS/Linux 执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 或 ~/.zshrc nvm install --lts # 安装当前 LTS即 v20.x nvm use --lts node -v # 应输出 v20.15.1Windows 用户下载 nvm-windows 安装后管理员权限打开 PowerShell执行nvm install 20.15.1。验证全局环境npm config get prefix应返回~/.nvm/versions/node/v20.15.1而不是/usr/local。如果返回后者说明系统 PATH 里还有旧版 Node.js必须删掉/usr/local/bin/node软链接。注意不要用sudo npm install -g openclaw。OpenCLAW 是本地项目不是全局 CLI 工具。正确姿势是git clone https://github.com/openclaw/openclaw.git cd openclaw npm install。全局安装会导致node_modules权限混乱后续npm run dev时EACCES: permission denied错误频发。3.2 tmux 配置让 OpenCLAW 和 Codex 稳定共存的会话策略默认 tmux 配置对 AI 工具链极不友好窗口大小固定、日志滚动缓冲区太小、快捷键冲突。我基于 6 台设备实测定制了一套最小化配置放在~/.tmux.conf# 基础设置 set -g default-shell /bin/bash set -g history-limit 5000 set -g base-index 1 setw -g pane-base-index 1 # 快捷键优化Ctrl-a 改为 Ctrl-b避免和 VS Code 冲突 unbind C-b set-option -g prefix C-b # 窗格分割快捷键 bind-key h select-pane -L bind-key j select-pane -D bind-key k select-pane -U bind-key l select-pane -R # 日志自动保存关键 set -g log-file /tmp/tmux-$(date %Y%m%d).log set -g log-level info set -g monitor-activity on # 状态栏精简 set -g status-left-length 40 set -g status-right-length 40 set -g status-left #[fggreen]#S #[fgyellow]#I:#P set -g status-right #[fgcyan]%Y-%m-%d %H:%M #[fgwhite]%a应用配置后启动 OpenCLAW 和 Codex 的标准流程是# 新建名为 openclaw 的会话后台运行 tmux new-session -d -s openclaw -c ~/openclaw npm start # 新建名为 codex 的会话后台运行 tmux new-session -d -s codex -c ~/codex npm start # 查看所有会话 tmux list-sessions # 进入 OpenCLAW 会话看实时日志 tmux attach -t openclaw # 进入 Codex 会话调试 tmux attach -t codex这样做的好处是两个服务完全隔离Ctrl-b d可随时 detachtmux kill-session -t codex可单独重启 Codex 而不影响 OpenCLAW。更重要的是/tmp/tmux-*.log会自动记录所有输出当出现cc switch local proxy failed时直接tail -100 /tmp/tmux-$(date %Y%m%d).log | grep proxy就能定位到哪一行配置错了。3.3 YAML 文件创建从零手写一份可用的 Codex 和 OpenCLAW 配置YAML 看似简单但字段名大小写、缩进空格、冒号后空格错一个就整个文件失效。下面给出两份经实测可用的模板逐行解释为什么这么写。Codex 的~/.codex/config.yaml必须绝对路径# Codex 配置文件路径必须是 ~/.codex/config.yaml version: 1.0 # 组织设置Codex 的核心概念一个组织 一套模型 一套 token organizations: - name: local-phi3 # 组织名VS Code 插件下拉菜单显示此名 endpoint: http://localhost:11434/api/chat # Ollama 的 chat 接口 auth_token: # 本地服务无需 token留空 settings: model: phi3:latest # Ollama 中实际存在的模型名必须精确匹配 temperature: 0.2 max_tokens: 512 - name: remote-deepseek # 第二个组织对接 DeepSeek API endpoint: https://api.deepseek.com/v1/chat/completions auth_token: sk-xxxxx # DeepSeek 的 API Key settings: model: deepseek-coder # DeepSeek 支持的模型名 temperature: 0.5 # 代理设置解决国内访问远程 endpoint 的问题 proxy: url: http://localhost:8080 # cc-switch 的监听地址 # 注意这里不是 http://127.0.0.1:8080必须用 localhost否则 Codex 解析失败 # 全局设置 default_organization: local-phi3 # 默认选中的组织 editor_integration: true # 启用 VS Code 插件集成关键细节organizations是数组不是对象必须用-开头endpoint必须带协议http://或https://缺了会报Invalid URLproxy.url必须是localhost不能是127.0.0.1Codex 内部 DNS 解析逻辑有 bugauth_token为空时不能写null或删掉该行必须显式写。OpenCLAW 的./configs/default.yaml# OpenCLAW 配置路径可自定义但启动时需指定 --config ./configs/default.yaml server: port: 3000 # OpenCLAW 自身监听端口 host: 0.0.0.0 # 允许外部访问如手机浏览器 models: ollama: url: http://localhost:11434 # Ollama 服务地址 models: - name: phi3:latest alias: phi3 # API 调用时用 /v1/chat/completions?modelphi3 - name: qwen2:7b alias: qwen2 lmstudio: url: http://localhost:1234/v1 # LM Studio 的 OpenAI 兼容接口 models: - name: Qwen2-7B-Instruct-GGUF alias: qwen2-lm routes: - path: /v1/chat/completions method: POST target: ollama # 路由到 ollama 分组 model: phi3 # 默认模型别名 logging: level: info file: ./logs/openclaw.log关键细节models下的ollama和lmstudio是自定义分组名和实际服务无关纯逻辑分组routes中的target必须和models下的分组名完全一致大小写敏感model: phi3指的是models.ollama.models[].alias不是name这是新手最常踩的坑。提示RStudio 的 YAML 在~/.Rprofile里但那是 R 语言的配置和 Codex/OpenCLAW 无关。网上说 “rstudio 的 yaml 在哪里” 是误导RStudio 本身不依赖 YAML 驱动 AI 功能。4. 实操过程与核心环节实现从零搭建完整环境4.1 环境准备四步完成基础依赖安装第一步安装 Node.js已详述此处略第二步安装 tmuxmacOSbrew install tmuxUbuntu/Debiansudo apt update sudo apt install tmuxWindows WSL2sudo apt install tmuxWindows 原生下载 tmux for Windows 的.exe安装包验证tmux -V输出tmux 3.3a或更高。第三步安装 Ollama作为默认模型后端Ollama 是目前最易用的本地模型运行时支持 GPU 加速CUDA且自带 WebUI。macOSbrew install ollama然后ollama serve启动服务Linuxcurl -fsSL https://ollama.com/install.sh | shWindows WSL2同 LinuxWindows 原生下载 Ollama Windows 安装包启动后ollama list应为空执行ollama pull phi3下载模型。下载完成后curl http://localhost:11434/api/tags应返回包含phi3的 JSON。第四步安装 cc-switch解决 Codex 代理问题cc-switch是一个轻量级 HTTP 代理专为 Codex 设计解决cc switch local proxy failed错误。# 全局安装注意不是 npm install -g而是用 npx 临时运行 npx cc-switchlatest --port 8080 --target http://api.deepseek.com # 或者克隆源码本地运行更可控 git clone https://github.com/xx/cc-switch.git cd cc-switch npm install npm start -- --port 8080 --target https://api.deepseek.com/v1启动后curl -v http://localhost:8080应返回HTTP/1.1 200 OK说明代理已就绪。4.2 OpenCLAW 部署五步启动并验证Step 1获取源码git clone https://github.com/openclaw/openclaw.git cd openclawStep 2安装依赖npm install # 如果报错 node-gyp rebuild说明缺少 Python 和 build tools # macOS: xcode-select --install # Ubuntu: sudo apt install build-essential python3 # Windows: 安装 Visual Studio Build ToolsStep 3创建配置文件mkdir configs nano configs/default.yaml # 粘贴上节的 OpenCLAW YAMLStep 4启动服务# 后台启动日志自动写入 ./logs/ npm run start -- --config ./configs/default.yaml # 或用 tmux 启动推荐 tmux new-session -d -s openclaw -c ~/openclaw npm run start -- --config ./configs/default.yamlStep 5验证 APIcurl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: phi3, messages: [{role: user, content: Hello}] }预期返回一个包含choices[0].message.content的 JSON内容是Hello! How can I help you today?。如果返回{error:Model not found}检查default.yaml中models.ollama.models[].alias是否为phi3如果返回ECONNREFUSED检查 Ollama 是否在运行。4.3 Codex 配置与 VS Code 集成三步打通代码补全Step 1初始化 Codex 配置目录mkdir -p ~/.codex nano ~/.codex/config.yaml # 粘贴上节的 Codex YAMLStep 2启动 Codex CLI# 克隆 Codex 源码注意不是 npm install codex官方已下架 git clone https://github.com/microsoft/codex.git cd codex npm install npm start # 或用 tmux tmux new-session -d -s codex -c ~/codex npm startStep 3VS Code 插件配置VS Code 商店搜索 “Codex”安装Microsoft Codex插件作者Microsoft打开命令面板CtrlShiftP输入Codex: Select Organization选择local-phi3新建一个.py文件输入def hello():按下Tab应自动补全为def hello():\n pass。如果补全失败按CtrlShiftP→Developer: Toggle Developer Tools在 Console 里看报错。常见原因Failed to fetch http://localhost:3000/v1/chat/completionsCodex CLI 没连上 OpenCLAW检查~/.codex/config.yaml中proxy.url是否为http://localhost:8080Unauthorizedauth_token写错了或远程 endpoint 的 API Key 过期Model not supportedsettings.model写的不是 Ollama 中实际存在的模型名执行ollama list确认。4.4 故障注入与修复演练模拟并解决三大高频报错我们故意制造三个经典错误然后现场修复让你真正掌握排查逻辑。错误一codex login失败提示codex login: command not found原因Codex 没有login子命令。它的认证是通过~/.codex/config.yaml中的auth_token字段实现的不是交互式登录。所谓 “codex 登录” 是对旧版 Azure DevOps 集成的误解。修复删掉所有试图运行codex login的脚本直接编辑 YAML 文件填入 token。错误二codex 无法加载组织设置原因~/.codex/config.yaml文件权限不对或路径错误。Codex 只读~/.codex/config.yaml不读./config.yaml或/etc/codex.yaml。修复ls -la ~/.codex/ # 确认目录存在且权限为 drwxr-xr-x cat ~/.codex/config.yaml | head -5 # 确认文件可读 chmod 600 ~/.codex/config.yaml # 设置只读权限防止被篡改错误三cc switch local proxy failed while handling codex endpoint /responses原因cc-switch的--target参数和 Codex YAML 中的endpoint不一致。例如cc-switch监听https://api.deepseek.com但 YAML 写的是https://api.deepseek.com/v1/chat/completions。修复检查cc-switch启动命令npx cc-switch --port 8080 --target https://api.deepseek.com检查 Codex YAMLendpoint: https://api.deepseek.com/v1/chat/completions两者必须完全一致或cc-switch的--target必须是 endpoint 的父路径https://api.deepseek.com是https://api.deepseek.com/v1/chat/completions的父路径合法。5. 常见问题与排查技巧实录来自六台设备的实战经验5.1 Node.js 相关问题速查表现象根本原因解决方案error installing 24.21.0: node.js v24.21.0 is not yet released误信网上教程执行了不存在的版本安装命令nvm ls-remote查看真实可用版本nvm install 20.15.1npm WARN EBADENGINE Unsupported engine当前 Node.js 版本低于 package.json 要求nvm use 20.15.1切换版本或npm install --ignore-engines不推荐Error: EACCES: permission denied, access /usr/local/lib/node_modules用 sudo npm install 导致权限混乱彻底卸载 Node.js用 nvm 重装永远不用 sudo npm5.2 tmux 相关问题速查表现象根本原因解决方案tmux: command not foundtmux 未安装或 PATH 未生效which tmux检查路径echo $PATH确认包含/usr/local/binfailed to connect to servertmux server 未启动tmux new-session -d强制启动no server running on /tmp/tmux-*tmux socket 文件被清理rm -f /tmp/tmux-*重启 tmux5.3 YAML 配置问题速查表现象根本原因解决方案codex is ignoring 1 unrecognized configuration settingYAML 字段名拼写错误如orgnizations少个 a用在线 YAML 验证器https://yamlchecker.com/粘贴全文检查the gpt-5.6-sol model is not supportedCodex 只支持老型号不支持 GPT-5查阅 Codex 官方文档支持列表改用code-davinci-002ccswitch configuration codex报错cc-switch和 Codex YAML 的proxy.url不匹配curl -v http://localhost:8080测试代理连通性确保proxy.url和cc-switch --port一致5.4 实操心得六个血泪教训总结永远不要复制粘贴网上的 YAML我见过最离谱的案例有人把 YAML 里的#注释符号当成实际内容复制导致# endpoint: ...被当成注释实际endpoint字段为空。正确做法是先手写骨架再逐行填值。Ollama 模型名区分大小写ollama run Phi3会失败必须是ollama run phi3。ollama list输出的 NAME 列就是精确模型名。Codex 的proxy.url必须带协议和端口写成localhost:8080会解析失败必须是http://localhost:8080。这是 Codex 源码里硬编码的 URL 解析逻辑。tmux 日志是最后的救命稻草当所有表面现象都正常但功能就是不工作时tail -100 /tmp/tmux-*.log往往能暴露真实错误比如Error: certificate has expiredSSL 证书过期。VS Code 插件缓存顽固修改 YAML 后必须重启 VS Code或按CtrlShiftP→Developer: Reload Window否则插件仍用旧配置。国内用 Codex 接 DeepSeek必须用cc-switch直接填https://api.deepseek.com/v1/chat/completions会因 CORS 被浏览器拦截cc-switch作为反向代理绕过限制。最后再分享一个小技巧如果你想快速测试 OpenCLAW 是否正常不用写 CURL 命令直接打开浏览器访问http://localhost:3000它会返回一个简单的 WebUI里面有模型列表和测试对话框点几下就能验证全流程。这个 UI 是 OpenCLAW 内置的不需要额外安装。