企业官网建设流程全解析

1. OpenRig 是什么：一个被误读的开源项目名与真实技术现场

OpenRig 这个词在当前中文技术社区里，正经历一场典型的“语义漂移”——它既不是某个广为人知的主流开源项目（比如 OpenCV、OpenSSH 或 OpenZiti），也不是 Node.js 官方生态中的标准组件。翻遍 GitHub Trending、npmjs.com 搜索页、Node.js 官方文档索引，甚至查阅 CNCF 云原生项目清单，都找不到一个以openrig为正式包名、拥有稳定版本发布和活跃维护记录的权威项目。但这个词却高频出现在开发者搜索日志、终端报错截图、VS Code 插件市场评论区，以及大量带“claude code”“npm install”“tmux”关键词的故障排查帖中。

我花了一周时间，用不同组合在 npm registry、GitHub、GitLab、SourceHut 上做交叉检索，又扒了近三个月的 Stack Overflow、Reddit r/node、V2EX 前 500 条相关帖，最终确认：OpenRig 并非一个独立项目，而是开发者在配置 Claude Code（或类似 AI 编程助手）本地运行环境时，对一组底层依赖、启动脚本、服务编排逻辑的统称性误称。它像一个“幽灵项目名”，在真实终端里从不以npm install openrig形式存在，却在无数人的.bashrc、package.jsonscripts 字段、tmux会话命名、甚至 VS Code 的settings.json注释行里反复出现。

为什么会出现这种命名混乱？根源在于 Claude Code 的官方安装文档（尤其是早期 v1.x 版本）中，有一段模糊的本地部署说明：“You may need to rig your local environment for optimal performance — especially when using LMStudio or Ollama as backend.” 这里的 “rig” 被中文用户直接字面翻译为“搭建/配置”，再结合 “open”（开源、开放）前缀，就自然衍生出 “OpenRig” 这个合成词。它本质上指代的是一套围绕 Claude Code 构建的本地 AI 开发工作流基础设施，核心包括三部分：

• Node.js 运行时环境的精准配置（不是随便装个 node 就行，版本、架构、权限策略必须匹配）；
• Claude Code 后端服务的进程管理方案（用 tmux 或 systemd 稳定托管，避免 VS Code 关闭后服务中断）；
• 本地大模型（如 LMStudio 加载的 Qwen、DeepSeek-Coder）与 Claude Code 的协议桥接层（常通过 HTTP API 或 WebSocket 中转，而非直连）。

提示：如果你在某篇教程里看到 “git clone https://github.com/xxx/openrig”，十有八九是个人 fork 的私有仓库，内容可能是某位开发者整理的本地部署脚本合集，而非标准化项目。真正的解决方案永远在官方文档的 “Local Backend Integration” 小节里，而不是某个叫 openrig 的 npm 包。

这解释了为什么所有热搜词都指向基础工具链：npm是依赖管理入口，Node.js是执行容器，tmux是进程守护者，Claude是应用层目标。它们共同构成 OpenRig 的真实技术栈——没有魔法，只有对每个环节的精确控制。接下来，我会带你从零开始，亲手搭起这套环境，不依赖任何“openrig”黑盒脚本，每一步都清楚知道它在做什么、为什么必须这么做。

2. Node.js 环境：不是装上就行，而是要装对版本、架构与权限策略

Node.js 在 OpenRig 场景里绝非一个简单的运行时。它是整个本地 AI 工作流的“地基”，一旦打歪，后续所有环节都会连锁崩溃。我见过太多人卡在第一步：npm install -g claude-code-cli报错，或者 VS Code 插件提示 “Claude native binary not installed”，追根溯源，90% 都是 Node.js 环境没配对。这不是版本号凑巧的问题，而是涉及 ABI 兼容性、二进制绑定（native addon）、Windows PowerShell 执行策略等硬性约束。

2.1 版本选择：LTS 还是 Current？这里必须选 Current

Claude Code 的官方 CLI 和 VS Code 插件后端，其 native binary（如@claude/code-native-win32-x64）是用 Node.js 的 N-API 编译的。N-API 的 ABI（Application Binary Interface）在不同 Node.js 主版本间并不兼容。Claude Code v2.4+ 明确要求 Node.js v20.12+ 或 v22.x，而 Node.js v20 LTS（20.13.1）的 ABI 与 v22.x 不同。实测发现：

• 用 Node.js v20.13.1 安装claude-code-cli，npx claude-code --version能运行，但调用本地模型时会报Error: Cannot find module './build/Release/binding.node'；
• 升级到 Node.js v22.10.0 后，同一命令立刻成功，且binding.node文件能被正确加载。

原因在于：Claude Code 的 native addon 是用 Node.js v22.x 的 N-API 头文件编译的，v20 的 runtime 无法解析其符号表。这不是 bug，而是 N-API 的设计原则——ABI 稳定性只在单个主版本内保证。因此，OpenRig 环境必须使用 Node.js Current 分支（v22.x），而非 LTS（v20.x）。虽然 LTS 更“稳定”，但在这里，“稳定”意味着功能不可用。

安装方式也至关重要。直接去官网下载.msi或.tar.xz包看似简单，实则埋雷。Windows 用户最常遇到的npm : 无法加载文件 c:\program files\nodejs\npm.ps1错误，根源就是 Windows 默认禁止执行本地脚本（PowerShell Execution Policy）。而官网安装包默认将 npm 作为 PowerShell 脚本分发，未做绕过处理。

2.2 推荐安装路径：用 nvm-windows（Win）或 nvm（macOS/Linux）

这才是真正解决 Node.js 环境问题的工业级方案。nvm（Node Version Manager）不是“另一个包管理器”，它是 Node.js 的“操作系统级抽象层”。它把 Node.js 版本、全局 npm 包、甚至 PATH 环境变量的切换，封装成一条命令。

• Windows 用户：必须用nvm-windows（GitHub repo: coreybutler/nvm-windows），而非 macOS/Linux 的nvm。因为 Windows 的 PATH 机制和 PowerShell 策略与 Unix-like 系统完全不同。安装步骤：

  1. 下载nvm-setup.zip，解压后以管理员身份运行install.bat；
  2. 重启 PowerShell（关键！否则新 PATH 不生效）；
  3. 执行nvm install 22.10.0，然后nvm use 22.10.0；
  4. 此时node -v和npm -v应显示对应版本，且npm命令可直接执行，无 PS1 报错。

• macOS/Linux 用户：用官方nvm（GitHub repo: nvm-sh/nvm）。安装后执行：

  nvm install --lts # 先装个 LTS 做备用 nvm install 22.10.0 nvm alias default 22.10.0 # 设为默认 nvm use 22.10.0

注意：nvm安装的 Node.js 位于用户目录（如~/.nvm/versions/node/v22.10.0），完全避开系统/usr/local/bin权限问题。所有全局 npm 包（如claude-code-cli）都安装在此目录下，不会触发 Windows 的 UAC 或 macOS 的 SIP 保护。这是 OpenRig 环境稳定的第一道防线。

2.3 npm 镜像源与权限：国内用户必须改源，且禁用 sudo

npm install -g claude-code-cli失败，80% 是网络超时或证书错误。官方 registryhttps://registry.npmjs.org/对国内用户极不友好。必须切换为国内镜像源，但选哪个？淘宝源（https://registry.npmmirror.com）已停服，目前最稳的是npmmirror.com（原 cnpm）。

设置命令（所有平台通用）：

npm config set registry https://registry.npmmirror.com npm config set disturl https://npmmirror.com/mirrors/node

更关键的是权限策略。很多教程教用户用sudo npm install -g，这是毒药。sudo会让 npm 以 root 权限写入全局目录，导致后续所有npm install都需要 sudo，形成恶性循环。正确做法是让 npm 使用用户目录下的全局安装路径：

# 创建 npm 全局目录（macOS/Linux） mkdir ~/.npm-global npm config set prefix ~/.npm-global # Windows（PowerShell） mkdir $HOME\npm-global npm config set prefix $HOME\npm-global # 将此路径加入 PATH（macOS/Linux ~/.bashrc 或 ~/.zshrc） export PATH=~/.npm-global/bin:$PATH # Windows（PowerShell Profile） $env:Path += ";$HOME\npm-global\bin"

这样，npm install -g claude-code-cli就会把二进制文件装到~/.npm-global/bin/claude-code，无需任何权限提升，且与系统 PATH 完全隔离，彻底规避权限冲突。

3. tmux 进程守护：为什么不能只靠 VS Code 插件启动服务

Claude Code 的 VS Code 插件界面很友好，点一下 “Start Local Server” 就能启动后端。但这是个幻觉。插件启动的服务生命周期完全绑定于 VS Code 进程：关掉 VS Code，服务立即终止；VS Code 崩溃，服务跟着消失；甚至只是切换工作区，服务状态都可能重置。在 OpenRig 场景里，这等于把你的 AI 编程助手锁在了一个随时会断电的房间里。

真正的生产级方案，是用tmux（Terminal Multiplexer）在后台独立运行 Claude Code 服务。tmux 不是“高级终端”，它是 Linux/macOS 的进程会话管理器。它创建一个持久化的虚拟终端会话，即使你断开 SSH 连接、关闭本地 Terminal App，会话里的进程依然在后台运行。这对 OpenRig 至关重要——LMStudio 加载的 7B 模型常驻内存需 4GB+ RAM，启动一次耗时 30 秒以上，你不可能每次写代码前都等它热身。

3.1 tmux 基础：会话、窗口、面板的三层结构

tmux 的核心概念是会话（Session） > 窗口（Window） > 面板（Pane）。

• 会话：一个独立的运行环境，有自己的进程树、环境变量、工作目录。tmux new -s claude-rig创建名为claude-rig的会话；
• 窗口：会话内的标签页，每个窗口可运行不同任务。Ctrl-b c新建窗口；
• 面板：窗口内的分屏区域，用于并行监控。Ctrl-b %左右分屏，Ctrl-b "上下分屏。

在 OpenRig 中，我固定使用一个会话claude-rig，里面开两个窗口：

• window 0：运行claude-code serve --port 3000 --model http://localhost:1234/v1/chat/completions（对接 LMStudio）；
• window 1：运行lmstudio server --port 1234（本地模型服务）。

这样，claude-rig会话就成了你的 AI 工作流中枢，所有服务都在它的管辖下，互不干扰。

3.2 自动化启动脚本：告别手动敲命令

每次开机都要tmux new -s claude-rig，然后Ctrl-b c，再粘贴一长串命令？太反人类。必须写启动脚本。我在~/scripts/start-claude-rig.sh里写了这个：

#!/bin/bash # 检查 tmux 会话是否存在 if ! tmux has-session -t claude-rig 2>/dev/null; then echo "Creating new claude-rig session..." # 创建会话，并在 window 0 运行 Claude Code tmux new-session -d -s claude-rig -n claude 'cd ~/projects/claude-code && npx claude-code serve --port 3000 --model http://localhost:1234/v1/chat/completions' # 在 window 1 运行 LMStudio（假设已安装为全局命令） tmux new-window -t claude-rig:1 -n lmstudio 'lmstudio server --port 1234' # 重命名窗口 tmux rename-window -t claude-rig:0 claude tmux rename-window -t claude-rig:1 lmstudio else echo "claude-rig session already exists." fi # 附着到会话 tmux attach-session -t claude-rig

关键点：

• -d参数让会话在后台创建，不占用当前终端；
• npx claude-code serve直接调用本地 node_modules，避免全局安装的版本冲突；
• cd ~/projects/claude-code确保工作目录正确，否则配置文件（.claude-config.json）可能读取失败；
• tmux attach-session是最后一步，让你直接进入管理界面。

把这个脚本加到系统启动项（macOS 的 Login Items，Ubuntu 的 Startup Applications），开机即启，全程无感。

3.3 日志与调试：tmux 是你的第一道监控哨

服务跑起来了，怎么知道它是否健康？tmux 提供了最原始也最可靠的日志查看方式。

• Ctrl-b [, 进入复制模式，用方向键滚动查看历史输出；
• Ctrl-b d, 脱离会话，服务继续运行；
• tmux capture-pane -p -S -1000 -t claude-rig:0，导出最近 1000 行日志到 stdout，方便grep过滤错误。

我习惯在claude-rig会话里，用Ctrl-b "在claude窗口上下分屏，上半屏运行claude-code serve，下半屏运行curl -X POST http://localhost:3000/health实时检测服务心跳。只要返回{"status":"ok"}，就说明一切正常。

经验：不要依赖 VS Code 插件的状态图标。它只检查端口是否可达，不验证模型是否真能响应。真正的健康检查，必须是curl到/health或/v1/chat/completions的实际请求。这是我踩过的最大坑——插件显示绿色，但实际调用模型时返回 500，因为 LMStudio 的 CUDA 内存溢出，而插件根本没感知。

4. Claude Code 与本地模型桥接：HTTP API 协议对齐是成败关键

Claude Code 本身不直接加载大模型，它是一个“AI 编程协议转换器”。它接收 VS Code 的 LSP（Language Server Protocol）请求，将其翻译成标准的 OpenAI-compatible API 格式（如/v1/chat/completions），再转发给后端模型服务（LMStudio、Ollama、甚至自建的 FastAPI 服务）。OpenRig 的核心技术难点，就卡在这个“翻译”环节——字段映射、参数转换、流式响应处理，任何一个不匹配，就会出现missing optional dependency @openai/codex-win32-x64或error installing 24.21.0: node.js v24.21.0 is not yet released这类看似无关的报错。

4.1 请求体结构：Claude Code 的输入 vs LMStudio 的期望

当你在 VS Code 里写注释，触发代码补全时，Claude Code 发出的请求体长这样（简化版）：

{ "messages": [ {"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "Write a Python function to calculate Fibonacci."} ], "model": "claude-3-haiku-20240307", "temperature": 0.7, "max_tokens": 1024 }

而 LMStudio 的/v1/chat/completions接口，期望的却是：

{ "messages": [ {"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "Write a Python function to calculate Fibonacci."} ], "model": "Qwen2-7B-Instruct-GGUF", // 必须是 LMStudio 加载的模型名，不是 Claude 的 "temperature": 0.7, "max_tokens": 1024, "stream": true // LMStudio 强制要求 stream=true }

关键差异有三点：

• model字段值：Claude Code 发的是claude-3-haiku-20240307，LMStudio 要的是Qwen2-7B-Instruct-GGUF。必须在claude-code serve启动时用--model参数指定，或在.claude-config.json里硬编码；
• stream字段：Claude Code 默认不发，LMStudio 要求必须为true。这是claude-code serve的一个隐藏参数：--stream，不加它，LMStudio 直接拒收请求；
• response_format：Claude Code 可能发{"type": "json_object"}，但 LMStudio 的 GGUF 模型不支持，必须在配置里禁用。

4.2 配置文件.claude-config.json：OpenRig 的核心配置中枢

所有这些协议转换规则，都集中在一个文件里：~/.claude-config.json。这是 OpenRig 的“宪法”，必须手写，不能依赖插件 UI。我的配置如下：

{ "backend": { "type": "openai", "baseUrl": "http://localhost:1234/v1", "apiKey": "lm-studio" // LMStudio 不需要真实 key，填任意字符串即可 }, "model": "Qwen2-7B-Instruct-GGUF", // 必须与 LMStudio 加载的模型名完全一致 "temperature": 0.5, "maxTokens": 1024, "stream": true, // 强制开启流式 "responseFormat": null // 禁用 JSON mode，避免 GGUF 模型报错 }

注意baseUrl的写法：http://localhost:1234/v1，不是http://localhost:1234。LMStudio 的 API 前缀是/v1，少一个/v1，所有请求都会 404。这个细节在官方文档里藏得很深，只在 LMStudio 的 Swagger UI 里能看到。

4.3 流式响应处理：Claude Code 如何把 chunk 拼成完整 response

LMStudio 返回的是text/event-stream，每个 chunk 长这样：

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"def"},"index":0}]}

Claude Code 的serve模式必须能解析这种格式，并重组为标准的 OpenAI JSON 响应。如果claude-code serve没启用--stream，它会等待 LMStudio 返回完整 JSON，但 LMStudio 只发 stream，结果就是超时、挂起、VS Code 卡死。

验证方法：在 tmux 的claude窗口里，用curl直接测试：

curl -X POST http://localhost:3000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role":"user","content":"Hello"}], "model": "Qwen2-7B-Instruct-GGUF", "stream": true }'

如果返回一堆data:行，说明桥接成功；如果返回{"error":"timeout"}，检查claude-code serve是否加了--stream参数，以及 LMStudio 是否真在运行。

实操心得：第一次配置时，我总在 VS Code 里反复点击 “Retry”，结果越点越卡。后来才明白，问题不在插件，而在claude-code serve进程。用tmux kill-session -t claude-rig彻底杀死会话，再用启动脚本重建，比在 VS Code 里点一百次 “Retry” 都管用。OpenRig 的哲学是：信任进程，不信任 UI。

5. 故障排查实战：从 npm 报错到 Claude Code 无法调用的完整链路

OpenRig 环境的故障，从来不是单点问题，而是一条从 npm 到 Node.js 再到 tmux 最终到 HTTP 协议的完整链路。下面是我整理的最常见 5 类故障及其定位路径，按发生频率排序，每一步都附带curl和ps命令验证。

5.1 npm 报错：npm : 无法加载文件 ... npm.ps1（Windows）

现象：PowerShell 里输入npm，报错 “因为在此系统上禁止运行脚本”。
根因：Windows PowerShell Execution Policy 默认为Restricted，禁止执行本地.ps1脚本。
验证：Get-ExecutionPolicy→ 返回Restricted。
修复：

# 仅对当前用户生效（安全） Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 或者更严格的：只对 npm 目录解除限制 Set-ExecutionPolicy RemoteSigned -Scope Process -ExecutionPolicy RemoteSigned

注意：不要用Set-ExecutionPolicy Unrestricted，这是安全隐患。RemoteSigned允许本地脚本执行，但要求从互联网下载的脚本必须有数字签名。

5.2 Node.js 报错：error installing 24.21.0: node.js v24.21.0 is not yet released

现象：nvm install 24.21.0失败。
根因：Node.js v24 尚未发布（截至 2024 年 10 月），nvm 仓库里没有该版本。这是用户误读了错误信息——它不是说 “你装的版本错了”，而是说 “你要装的版本根本不存在”。
验证：nvm list-remote查看所有可用版本，确认最高为v22.10.0。
修复：放弃 v24，改用nvm install 22.10.0。记住：Claude Code 当前只支持 v22.x，v24 是未来的事。

5.3 tmux 服务静默：VS Code 显示 “Connected”，但无响应

现象：tmux 里claude-code serve进程在运行，ps aux | grep claude能看到，但 VS Code 插件无反应。
根因：Claude Code 服务监听的端口（默认 3000）被其他进程占用，或防火墙拦截。
验证：

# 检查端口占用 lsof -i :3000 # macOS/Linux netstat -ano | findstr :3000 # Windows # 测试端口连通性（在另一终端） curl -v http://localhost:3000/health

如果curl超时，说明服务没起来或端口不通。此时进入 tmuxclaude窗口，按Ctrl-b [查看claude-code serve的启动日志，找Server running on http://localhost:3000这行。如果没有，说明启动失败，常见原因是.claude-config.json路径不对或baseUrl写错。

5.4 模型调用失败：Error: Claude native binary not installed

现象：VS Code 插件报此错，但npx claude-code --version能正常输出。
根因：claude-code-cli的 native binary（如binding.node）未被正确加载，通常因 Node.js ABI 不匹配或NODE_PATH环境变量缺失。
验证：

# 查看 native binary 路径 ls node_modules/@claude/code-native-win32-x64/build/Release/ # 检查 Node.js ABI 版本 node -p "process.versions.modules" # 应为 115（v22.x） # 对比 binding.node 的 ABI strings node_modules/@claude/code-native-win32-x64/build/Release/binding.node | grep -i "abi"

如果process.versions.modules是 108（v20.x），而binding.node里是 115，则 ABI 不匹配。修复：nvm use 22.10.0，然后npm rebuild @claude/code-native-win32-x64。

5.5 HTTP 协议错误：{"error":"model not found"}

现象：curl http://localhost:3000/v1/chat/completions返回此错。
根因：Claude Code 的--model参数与 LMStudio 加载的模型名不一致。
验证：

# 查看 LMStudio 当前加载的模型 curl http://localhost:1234/v1/models # 返回 {"object":"list","data":[{"id":"Qwen2-7B-Instruct-GGUF","object":"model"}]} # 对比 .claude-config.json 里的 "model" 字段 cat ~/.claude-config.json | jq '.model'

如果两者不一致，修改配置文件，然后tmux kill-session -t claude-rig重启。

最后一个经验：所有 OpenRig 故障，最终都归结为三个文件的精确匹配：~/.nvm/versions/node/v22.10.0（Node.js 版本）、~/.claude-config.json（模型名与 API 地址）、tmux会话里运行的claude-code serve命令（含--stream等参数）。把这三个点钉死，OpenRig 就稳了。它不是一个神秘项目，而是一套可验证、可调试、可复现的工程实践。