openrig 实战：Claude Code 与 Codex 环境搭建及本地模型接入-北京尧图网络

1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟 rig 在英文里有“装配、支架”的意思。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程工具就会明白它其实是一个围绕终端 AI 编码工作流做整合的开源工具集。简单说openrig 想做的事情是把 Claude Code、Codex 这些独立的 AI 编码代理和 tmux、Node.js 环境、本地模型服务串成一条顺手的流水线让你在一个终端窗口里就能完成从代码生成、命令执行到会话管理的全部动作。我最初接触它是因为同时装了 Claude Code 和 Codex两个工具各有各的配置文件、各有各的登录方式切换起来特别烦。openrig 的核心价值就在于把这些零散的东西收拢到一套可复用的配置骨架里。它不是一个全新的 AI 模型也不是要替代谁而是一层“编排层”——帮你管理多个 AI 编码代理的启动、会话保持和本地模型接入。适合读这篇的人大概分三类一是刚装完 Node.js、准备上手 Claude Code 或 Codex 的新手想知道怎么把环境搭得干净二是已经在用这些工具但被多工具切换、会话丢失、本地模型接入折腾过的老手三是想在自己的开发机上跑一套稳定 AI 编码环境的运维向开发者。不管你是哪一类下面这些内容都是我在实际搭建和长期使用中踩出来的经验不是照搬官方文档。需要先说明一点openrig 本身还在演进不同版本的行为可能有差异。我下面讲的是基于常见实践的一套可靠方案具体参数以你本地实际版本为准。核心思路是通用的环境隔离、会话持久化、模型接入可切换。2. 环境底座Node.js 与 tmux 的选型逻辑2.1 为什么 Node.js 版本是第一个坑Claude Code 和 Codex 这类 CLI 工具绝大多数是 Node.js 写的通过 npm 全局安装。这就意味着你的 Node.js 版本直接决定了工具能不能跑起来。我见过太多人卡在error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错上本质原因是版本号写错了或者用了非 LTS 的奇数版本。选型上我的建议很明确用 LTS 版本不要追最新。当前稳定线是 Node.js 20.x 和 22.x这两个都是长期支持版本。为什么不用 24因为很多 AI CLI 工具的依赖链还没完全跟上你装了最新版反而会遇到原生模块编译失败。在 Ubuntu 上装 Node.js 20我推荐用 NodeSource 的源而不是系统自带的 apt 版本系统自带的往往太旧。# 以 Ubuntu 为例添加 NodeSource 源并安装 Node.js 20 LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证版本 node -v # 应输出 v20.x.x npm -vWindows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包就行安装时勾选“自动安装必要工具”那个选项能省掉后面编译原生模块时缺 Python 和 Visual Studio Build Tools 的麻烦。Mac 用户用nvm管理多版本最舒服nvm install 20 nvm use 20两行搞定。注意如果你机器上已经有多个 Node 版本务必确认which node指向的是你期望的那个。我遇到过 npm 全局包装到了 A 版本但终端默认走 B 版本结果命令找不到的诡异情况。2.2 tmux 在 AI 编码工作流里的真实作用很多人不理解为什么 AI 编码工具要和 tmux 扯上关系。tmux 是个终端复用器它的核心能力是会话持久化。你想想这个场景你让 Claude Code 跑一个耗时的重构任务中途网络抖了一下或者你手滑关了终端窗口会话就断了任务白跑。用 tmux 把 AI 代理跑在独立会话里断线重连后tmux attach回去一切还在。openrig 把 tmux 作为编排层的一部分逻辑就在这里。它帮你把每个 AI 代理会话放到独立的 tmux window 或 pane 里你可以同时开 Claude Code 一个窗口、Codex 一个窗口互不干扰还能随时切回去看进度。# 安装 tmux sudo apt-get install -y tmux # Ubuntu/Debian brew install tmux # macOS # 创建一个名为 ai-work 的会话 tmux new -s ai-work # 在会话里分屏左边跑 Claude Code右边跑 Codex # Ctrlb 然后 % 是垂直分屏Ctrlb 然后是水平分屏我自己的习惯是给 tmux 配一套顺手的快捷键把前缀键从默认的Ctrlb改成Ctrla因为 b 离手太远。再配上鼠标支持滚动和点选 pane 都方便。这些配置写在~/.tmux.conf里一次配好长期受益。2.3 环境隔离别让全局安装污染你的系统新手最容易犯的错就是所有东西都npm install -g全局装。装到后面全局包互相冲突升级一个坏一片。我的做法是核心 CLI 工具用全局装但项目相关的依赖一律走本地。如果工具本身支持优先考虑用npx临时调用或者用独立的 Node 版本管理器给不同项目分环境。openrig 这类编排工具理想状态下应该帮你把“哪个工具用哪个 Node 版本”这件事管起来。如果你的 openrig 版本还不支持那就手动用 nvm 的.nvmrc机制在项目目录放一个版本声明文件进目录自动切版本。3. Claude Code 与 Codex 的安装配置实操3.1 Claude Code 安装与首次登录Claude Code 的安装本身不复杂难的是登录和权限。安装命令通常是全局 npm 包npm install -g anthropic-ai/claude-code # 或者用官方推荐的安装脚本装完之后第一次运行claude它会引导你登录。这里有个高频坑your organization has disabled claude subscription access for claude code。这个报错的意思是你当前账号所属的组织关闭了 Claude Code 的订阅访问权限。解决办法要么是让组织管理员在后台开启要么换一个个人账号登录。这不是安装问题是账号策略问题很多人在这里折腾半天以为是环境坏了。登录成功后Claude Code 会在你的用户目录下生成配置。我建议你第一时间去确认配置文件的位置和内容因为后面接本地模型、改端点都要动它。Windows 上路径通常在%USERPROFILE%\.claude之类的地方Linux/Mac 在~/.claude。VS Code 用户可以直接装 Claude Code 的官方扩展在编辑器里就能调用。但要注意扩展和 CLI 是两套东西扩展底层还是调 CLI所以 CLI 没配好扩展也用不了。我一般先用 CLI 把登录和模型跑通再上扩展。3.2 Codex 安装与登录排障Codex 的安装路径和 Claude Code 类似也是 npm 全局包。装完之后codex命令启动。Codex 登录不上是搜索里出现频率极高的问题常见原因有几个一是网络到认证服务不通二是本地时间不同步导致 token 校验失败三是配置文件里有残留的旧凭证。排查顺序我建议这样先codex --version确认装上了再检查系统时间date时间偏差超过几分钟就同步一下。然后看配置目录里有没有陈旧的登录态文件有就清掉重新登录。Codex 还有个典型报错codex is ignoring 1 unrecognized configuration setting. check for typos这是配置文件里写了它不认识的键通常是版本升级后旧配置没清理。找到那个键删掉或者改成新版本支持的写法就行。codex无法加载组织设置这个报错和 Claude 的组织权限问题类似属于账号层面的策略限制不是本地环境能修的。遇到这种先确认账号状态别在本地瞎折腾。3.3 两个工具共存时的配置隔离Claude Code 和 Codex 各有各的配置目录正常情况下不冲突。但如果你用 openrig 做统一编排就要注意别让它们的配置互相覆盖。我的做法是给每个工具单独的环境变量文件启动时按需 source。比如~/.config/ai-tools/claude.env和~/.config/ai-tools/codex.env里面放各自的 API 端点、密钥、模型名。openrig 启动对应工具时加载对应文件干净利落。提示密钥这类敏感信息不要直接写进会提交到 git 的文件里。用.env加.gitignore或者用系统级的密钥管理工具。4. 本地模型接入让 Claude Code 调用 LM Studio4.1 为什么要接本地模型用云端模型有成本也有隐私顾虑。很多人的代码不方便发到外部服务这时候本地模型就派上用场。LM Studio 是个很友好的本地模型运行工具图形界面支持多种开源模型还能暴露一个兼容 OpenAI 接口的本地端点。Claude Code 和 Codex 都支持自定义端点把它们指向 LM Studio就能用本地模型干活。这个组合的价值在于零 API 成本、数据不出本机、断网也能用。代价是本地模型的能力通常不如云端旗舰模型复杂任务上差距明显。所以我的建议是分工——简单补全、格式化、写测试用本地模型复杂架构设计、大重构还是交给云端。4.2 LM Studio 端点配置与对接先在 LM Studio 里加载一个模型然后在“Local Server”标签页启动服务默认端口通常是 1234。启动后它会暴露一个 OpenAI 兼容的/v1/chat/completions端点。记下这个地址比如http://localhost:1234/v1。接下来配置 Claude Code 指向这个端点。具体做法是设置环境变量把 API base 指向本地API key 随便填一个非空值本地服务通常不校验。模型名要填 LM Studio 里实际加载的模型标识。# 示例让 Claude Code 走本地端点 export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlocal-no-key export ANTHROPIC_MODELyour-local-model-nameCodex 接入本地模型的思路一样改它的 base URL 和模型配置。搜索里提到的codex接入deepseek本质也是这个套路——把端点指向 DeepSeek 的兼容接口模型名换成 deepseek 的模型标识。4.3 第三方 API 与模型切换的注意事项用第三方 API 或者本地模型时有几个坑必须提前知道。第一接口兼容性不是 100%。OpenAI 的接口规范是一回事各家实现是另一回事有些工具依赖的字段第三方可能没实现导致报错。第二模型名必须精确匹配。搜索里那个the gpt-5.6-sol model is not supported when using codex with a...就是模型名不被支持导致的换成服务端实际提供的模型名即可。第三流式输出可能有问题。本地模型服务在高并发或长上下文时容易卡住遇到卡顿先降低并发、缩短上下文试试。关于cc switch local proxy failed while handling codex endpoint /responses这类代理转发失败通常是代理层没正确转发/responses这个路径。检查你的代理配置有没有把 Codex 需要的端点路径完整透传别只转发了/v1/chat/completions却漏了/responses。5. 常见问题速查与避坑经验5.1 安装类问题速查表报错关键词大概率原因处理方向node.js v24.21.0 is not yet released版本号写错或源里没有改用 LTS 20/22检查源error installing 24.21.0同上追新导致降级到 LTScodex无法加载组织设置账号策略限制联系管理员或换账号your organization has disabled...组织关闭了订阅访问同上非本地问题codex is ignoring 1 unrecognized configuration setting配置有旧键清理配置文件model is not supported模型名不匹配换成服务端支持的模型名这张表是我自己遇到和帮别人排查时总结的覆盖了搜索热词里出现频率最高的几类。核心判断原则是先分清是环境问题还是账号问题。环境问题本地能修账号问题本地修不了别浪费时间。5.2 会话管理与命令执行技巧Claude Code 有个很实用的能力是直接执行终端命令。搜索里有人问claude code如何直接执行终端命令这其实是它的核心功能之一——你让它跑个ls或者git status它会真的执行并把结果读回来。用好这个能力的关键是给它清晰的边界比如明确告诉它“只读操作不要改文件”避免它自作主张删东西。配合 tmux 用的时候我习惯把 AI 代理放在一个 pane把实际的项目终端放在另一个 pane。AI 生成命令后我先在项目终端里手动确认一遍再执行。这个“人在回路”的习惯能挡掉不少 AI 的想当然操作。5.3 我踩过的三个真实坑第一个坑是全局包版本冲突。有次我同时装了新旧两个版本的某个 CLI结果which指向的和npm ls -g显示的对不上排查了半小时。后来养成习惯装完立刻which xxx加xxx --version双重确认。第二个坑是本地模型上下文超限。本地模型上下文窗口通常比云端小我拿一个长文件让它分析直接爆了上下文报错还很不直观。后来学会先切分文件或者用支持长上下文的模型。第三个坑是tmux 会话里的环境变量丢失。我在.bashrc里设的环境变量在 tmux 新会话里没生效因为 tmux 启动的是非登录 shell。解决办法是在.tmux.conf里显式 source 环境文件或者用tmux new -s name -d加send-keys的方式注入。6. 把 openrig 用顺手的几个进阶思路openrig 这类工具真正的价值不在于它帮你装了什么而在于它帮你固化了一套可复用的工作流。我现在的做法是把它当成一个“环境声明”来用新机器上拉下配置一条命令把 Node 版本、tmux 布局、Claude Code 和 Codex 的配置、本地模型端点全部就位。这比每次手动装一遍省太多事。进阶用法上我建议把常用的 AI 编码任务做成 tmux 的预设布局脚本。比如一个“重构布局”左边 Claude Code右边 Codex下面一个测试终端。一个“调试布局”上面日志下面 AI 代理。用脚本一键起布局比每次手动分屏快得多。另外模型切换这件事值得单独做一层封装。云端模型和本地模型各有适用场景与其每次改环境变量不如写个小脚本ai-use local切本地ai-use cloud切云端脚本内部改好端点、密钥、模型名。这样切换成本降到最低你才会真的愿意按场景选模型而不是图省事一直用同一个。最后分享一个我长期用下来觉得最值钱的习惯给每个 AI 代理会话留一份操作日志。tmux 可以配置pipe-pane把 pane 的输出自动写到文件这样 AI 干了什么、执行了哪些命令事后都能回溯。出问题的时候这份日志比任何记忆都靠谱。

openrig 实战：Claude Code 与 Codex 环境搭建及本地模型接入

相关推荐

Realtek网卡驱动重装全攻略：从Windows到Linux的深度排错

ponytail插件：一键将杂乱文本整理为结构化内容

Godot编辑器移植鸿蒙PC：三层依赖与四级可行性解析

更多资讯

superpowers技能包实战：从安装到团队协作的AI编程助手扩展指南

Agent-Reach：面向开发者的跨平台API数据采集CLI调度器

Superpowers：浏览器端实时协作IDE的安装部署与实战

Java OA自动化办公系统源码落地：从部署到审批流跑通

Windows下codex cli报错os error 5拒绝访问的排查与修复方案

ponytail插件完全指南：从安装配置到skill编写与自动化实战

今日更新

Agent Skills 完全指南：原理、写法、安装与实战避坑

Agent Skills 实战：从 Genkit 定义到 GKE 部署与排查

Agent Skills 实战：从设计到调试的完整指南

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？