1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟“rig”在英文里常指设备支架、装配架。但在当前 AI 编程助手爆发的语境下openrig 实际上是一个围绕Claude Code、Codex 这类终端 AI 编程工具构建的开源编排与配置管理方案。它的核心价值在于把散落在各处的模型接入配置、终端会话管理、多工具切换逻辑收敛到一套可复用的结构里让你不用每次换模型、换工具都重新折腾一遍环境。我接触 openrig 的契机很直接——手头同时要用 Claude Code 做代码审查、用 Codex 做批量重构还要在本地 LM Studio 跑模型做离线推理。三套工具、三套配置、三种启动方式每次切换都要改环境变量、改配置文件、重启终端一天下来光折腾环境就耗掉不少时间。openrig 这类方案要解决的就是这个痛点统一入口、统一配置、统一会话管理。它适合谁如果你符合下面任意一条openrig 值得花时间研究同时使用 Claude Code 和 Codex需要频繁切换想把 Claude Code 接到本地模型比如 LM Studio 提供的本地推理服务在 Ubuntu 或 Windows 上配置过 Claude Code被 Node.js 版本、环境变量、终端兼容性折腾过需要长时间运行的 AI 编程会话希望用 tmux 保持会话不中断想用第三方 API 接入 DeepSeek、Qwen、GLM 等模型但不想每次都手改配置openrig 的本质是一层“胶水”它不替代 Claude Code 或 Codex而是把它们的配置、启动、会话管理标准化。理解这一点很关键否则你会误以为它能帮你写代码——它管的是“怎么让工具跑起来、跑得稳、切得快”。提示openrig 目前主要面向有一定终端操作基础的用户。如果你连 Node.js 都没装过建议先补上 Node.js 安装和基本命令行操作再来看 openrig。2. 核心依赖拆解Node.js、tmux 与 AI 编程工具的关系2.1 Node.js 是整个链路的地基Claude Code 和 Codex 的 CLI 版本都依赖 Node.js 运行。这不是可选项是硬性前提。当前主流版本要求 Node.js 20 LTS 及以上部分新版本工具甚至要求 22 LTS。我在 Ubuntu 上踩过的坑是系统自带的 Node.js 版本太老比如 18.x装 Claude Code 时直接报错提示版本不满足。安装 Node.js 20 在 Ubuntu 上有几种方式我实测下来最稳的是用 NodeSource 的仓库curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v npm -v装完后node -v应该输出v20.x.x。如果输出的是v18或更低说明系统里还有旧版本残留需要先清理。Windows 用户直接去 Node.js 官网下载 LTS 安装包即可安装时勾选“Add to PATH”省得后面手动配环境变量。这里有个细节很多人忽略npm 的全局安装路径权限。在 Ubuntu 上用sudo npm install -g装 Claude Code 时有时会因为权限问题导致后续更新失败。更稳妥的做法是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样后续npm install -g就不需要 sudo更新工具时也不会遇到权限报错。2.2 tmux让 AI 编程会话不中断tmux 在 openrig 体系里的角色是会话持久化。Claude Code 和 Codex 都是交互式终端工具一旦终端关闭或 SSH 断开会话就没了。如果你在跑一个长时间的代码重构任务中途断线意味着前功尽弃。tmux 的基本用法不复杂但有几个关键操作必须掌握tmux new -s claude-session # 新建名为 claude-session 的会话 tmux detach # 分离会话快捷键 Ctrlb 然后按 d tmux attach -t claude-session # 重新接入会话 tmux ls # 列出所有会话我通常的做法是开一个 tmux 会话专门跑 Claude Code再开一个跑 Codex两个会话互不干扰。即使本地终端崩了重新 SSH 上去tmux attach就能回到原来的状态。这个习惯在远程开发场景下几乎是必备的。注意tmux 默认的快捷键前缀是Ctrlb如果你用惯了Ctrlascreen 的风格可以在~/.tmux.conf里加一行set -g prefix C-a改掉。2.3 Claude Code 与 Codex 的定位差异这两个工具虽然都是终端 AI 编程助手但侧重点不同。Claude Code 更偏向对话式代码理解与修改适合做代码审查、解释复杂逻辑、生成重构方案。Codex 更偏向命令行任务执行适合批量文件操作、脚本生成、自动化任务。openrig 的价值在这里体现得很明显它让你用同一套配置逻辑管理两个工具而不是各配各的。比如模型接入这块Claude Code 和 Codex 都支持通过环境变量或配置文件指定 API 端点openrig 把这部分抽象出来你只需要在一个地方改配置两个工具都能生效。3. openrig 的配置架构与实操落地3.1 配置文件的结构设计openrig 的配置通常围绕几个核心维度展开模型端点、API 密钥、工具特定参数、会话管理策略。一个典型的配置结构大概是这样的{ models: { default: { provider: anthropic, endpoint: https://api.anthropic.com, model: claude-sonnet-4-20250514 }, local: { provider: lmstudio, endpoint: http://localhost:1234/v1, model: local-model-name }, deepseek: { provider: openai-compatible, endpoint: https://api.deepseek.com/v1, model: deepseek-chat } }, tools: { claude-code: { defaultModel: default, envPrefix: ANTHROPIC }, codex: { defaultModel: deepseek, envPrefix: OPENAI } }, session: { tmux: true, sessionPrefix: openrig } }这个结构的设计逻辑是模型定义与工具定义分离。模型是资源工具是消费者。一个模型可以被多个工具引用一个工具也可以切换不同模型。这样当你想把 Claude Code 从官方 API 切到本地 LM Studio 时只需要改tools.claude-code.defaultModel的值不用动模型定义本身。3.2 接入本地 LM Studio 模型的完整步骤把 Claude Code 接到 LM Studio 的本地模型是很多人的需求因为本地推理不消耗 API 额度适合高频调试。完整流程如下第一步在 LM Studio 里启动本地服务器。打开 LM Studio加载一个模型比如 Qwen2.5-Coder-7B然后在“Local Server”标签页点击启动。默认端口是 1234端点地址是http://localhost:1234/v1。第二步验证端点可用性curl http://localhost:1234/v1/models如果返回模型列表 JSON说明服务正常。第三步配置 Claude Code 使用这个端点。Claude Code 支持通过环境变量指定 API 基础地址export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio注意ANTHROPIC_API_KEY这里随便填一个非空值即可LM Studio 不校验密钥。但如果不填Claude Code 会报错说缺少 API key。第四步启动 Claude Code 并测试claude然后在对话里问一个简单问题看是否能正常返回。如果返回的是 LM Studio 里加载的模型输出说明接入成功。提示本地模型的能力和 Claude 官方模型差距明显尤其是在复杂代码理解和长上下文处理上。本地模型适合做简单补全、格式化、注释生成这类轻量任务复杂重构还是建议用官方模型。3.3 Codex 接入第三方 API 的配置要点Codex 接入 DeepSeek、Qwen、GLM 等第三方 API 时核心是配置 OpenAI 兼容端点。以 DeepSeek 为例export OPENAI_BASE_URLhttps://api.deepseek.com/v1 export OPENAI_API_KEYyour-deepseek-api-key然后在 Codex 的配置文件里指定模型名称。Codex 的配置文件通常在~/.codex/config.json或项目根目录的.codex.json。一个最小配置示例{ model: deepseek-chat, provider: openai, baseURL: https://api.deepseek.com/v1 }这里有个常见坑Codex 对模型名称的校验。如果你填的模型名称不在它支持的列表里会报model is not supported错误。解决办法是在配置里加上strictModelCheck: false或者直接用第三方 API 支持的模型名称。另一个坑是组织设置限制。有些用户遇到your organization has disabled claude subscription access这类报错这通常是因为账号层面的权限配置问题不是 openrig 或工具本身的问题。遇到这种情况需要检查账号的订阅状态和组织策略。4. 多工具切换与常见故障排查4.1 用 openrig 管理多模型切换的实操实际工作中我经常需要在不同模型之间切换写复杂逻辑用 Claude 官方模型做批量格式化用本地模型处理中文注释用 DeepSeek。openrig 的切换逻辑可以做成脚本比如#!/bin/bash # switch-model.sh MODEL$1 case $MODEL in claude) export ANTHROPIC_BASE_URLhttps://api.anthropic.com export ANTHROPIC_API_KEY$CLAUDE_KEY ;; local) export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio ;; deepseek) export ANTHROPIC_BASE_URLhttps://api.deepseek.com/v1 export ANTHROPIC_API_KEY$DEEPSEEK_KEY ;; esac echo Switched to $MODEL用的时候source switch-model.sh claude就切过去了。这个脚本可以进一步集成到 tmux 的会话启动命令里做到“开哪个会话就用哪个模型”。4.2 常见报错与排查速查表下面这张表是我在实际使用中整理的高频问题覆盖了 Claude Code、Codex、Node.js、tmux 几个层面报错信息可能原因排查方向解决方案node.js v24.21.0 is not yet releasedNode.js 版本号写错或源不可用检查 Node.js 实际版本改用 LTS 版本如 20.x 或 22.xcc switch local proxy failed本地代理配置冲突检查是否有其他代理占用端口关闭冲突代理或改用直连端点model is not supported模型名称不在支持列表核对模型名称拼写关闭严格校验或改用支持的名称organization has disabled access账号权限或订阅问题检查账号订阅状态联系账号管理员或更换 API 密钥unrecognized configuration setting配置文件有拼写错误逐行检查配置项删除或修正错误配置项tmux 会话丢失终端关闭或 SSH 断开检查 tmux 会话列表用tmux attach重新接入Claude Code 无法执行终端命令权限或配置限制检查工具权限设置在配置中开启命令执行权限4.3 几个我踩过的坑和对应技巧坑一Node.js 版本管理混乱。系统里同时存在 apt 装的 Node.js 和 nvm 装的 Node.js导致which node指向的版本和node -v显示的版本不一致。解决办法是统一用 nvm 管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 20 nvm use 20 nvm alias default 20这样每个项目可以独立指定 Node.js 版本不会互相干扰。坑二tmux 里的环境变量不生效。在.bashrc里 export 的变量在 tmux 新会话里有时读不到。这是因为 tmux 启动的是 login shell加载的是.profile而不是.bashrc。解决办法是在~/.tmux.conf里加set-option -g update-environment ANTHROPIC_API_KEY ANTHROPIC_BASE_URL OPENAI_API_KEY OPENAI_BASE_URL这样每次新建 tmux 会话时这些变量会自动同步进去。坑三VS Code 里的 Claude Code 插件和终端版配置不同步。VS Code 插件有自己的配置入口不会自动读取终端的环境变量。如果你在终端里配好了 openrig但 VS Code 里还是用默认配置就会出现“终端能用、插件不能用”的情况。解决办法是在 VS Code 的settings.json里手动指定{ claude-code.environment: { ANTHROPIC_BASE_URL: http://localhost:1234/v1, ANTHROPIC_API_KEY: lm-studio } }坑四Codex 登录不上。这个问题通常和网络环境或 API 端点配置有关。先确认OPENAI_BASE_URL是否正确再检查 API 密钥是否有效。如果用的是第三方兼容端点确保端点地址末尾不要多加/有些工具对 URL 格式敏感。5. 进阶玩法把 openrig 做成可复用的开发环境5.1 用脚本一键拉起完整环境把前面所有配置串起来可以写一个启动脚本做到“一条命令拉起整个 AI 编程环境”#!/bin/bash # openrig-start.sh # 加载环境变量 source ~/.openrig/env.sh # 创建 tmux 会话 tmux new-session -d -s openrig-claude tmux send-keys -t openrig-claude claude C-m tmux new-session -d -s openrig-codex tmux send-keys -t openrig-codex codex C-m echo Openrig environment started. echo Use tmux attach -t openrig-claude to access Claude Code. echo Use tmux attach -t openrig-codex to access Codex.这个脚本的好处是环境变量统一从~/.openrig/env.sh加载两个工具各自在独立的 tmux 会话里运行互不干扰。关掉终端后重新执行tmux attach就能回到之前的状态。5.2 配置文件的版本管理openrig 的配置文件建议纳入 Git 管理但 API 密钥不要直接写进去。我的做法是~/.openrig/config.json存非敏感配置纳入 Git~/.openrig/env.sh存 API 密钥加入.gitignore提供一个env.sh.example模板方便在新机器上快速配置这样换机器时clone 配置仓库复制env.sh.example为env.sh填入密钥就能快速恢复完整环境。5.3 多项目隔离的实践如果你同时维护多个项目每个项目可能需要不同的模型配置。openrig 支持按项目目录加载不同配置# 在项目根目录放一个 .openrigrc # 启动时自动加载 if [ -f .openrigrc ]; then source .openrigrc fi.openrigrc里可以覆盖全局配置比如指定这个项目用本地模型export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio这样进入项目目录后启动 Claude Code自动就用本地模型不用手动切换。6. 关于 openrig 的一些个人体会我用 openrig 这套思路管理 AI 编程环境大概有几个月了最大的感受是工具本身的能力固然重要但环境配置的稳定性才是决定效率的关键。Claude Code 和 Codex 都是好工具但如果每次用之前都要折腾十分钟环境再好的工具也会被闲置。openrig 这类方案的价值不在于它有多复杂而在于它把重复劳动标准化了。模型切换、会话管理、配置同步这些事做一次和做一百次的成本差异巨大。把它脚本化、配置化之后你才能真正把精力放在代码本身而不是环境上。另外一点体会是不要追求一步到位。我一开始想把所有模型、所有工具、所有场景都塞进一套配置里结果配置文件复杂到我自己都看不懂。后来改成按需扩展——先跑通一个工具加一个模型稳定了再加第二个——反而更顺。openrig 的架构支持渐进式扩展没必要一开始就设计得很完美。最后分享一个小技巧如果你在 Ubuntu 上遇到 Claude Code 或 Codex 的权限问题先检查/usr/local/bin和~/.npm-global/bin这两个路径的权限。很多时候报错不是工具的问题而是 npm 全局安装目录的权限没配对。把 npm prefix 改到用户目录下能省掉一大半莫名其妙的报错。