1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里就是“装配、设备”的意思。但翻了一圈社区讨论和实际代码之后才明白它其实是一个围绕 AI 编程助手做“编排”和“环境隔离”的工具层。简单说openrig 解决的是这样一个问题当你同时用 Claude Code、Codex 这类命令行 AI 编程工具时它们各自有各自的配置、各自的会话状态、各自的模型接入方式混在一起用很容易互相打架。openrig 就是把这些东西统一管起来的那一层。它适合谁如果你只是偶尔用一下 Claude Code 写个小脚本那确实用不上。但如果你像我一样日常要在多个项目之间切换一会儿用 Claude Code 调本地模型一会儿用 Codex 接第三方 API还要保证每个项目的配置互不污染那 openrig 这类工具的价值就出来了。它本质上是一个“多 AI 编程助手的运行时管理器”核心能力包括会话隔离、配置切换、模型端点路由以及和 tmux 这类终端复用器的深度集成。我之所以关注到它是因为热词里反复出现cc switch local proxy failed while handling codex endpoint /responses这类报错。这个报错的本质是你在用某个切换工具把 Claude Code 的请求转发到 Codex 的端点时代理层没有正确处理/responses这个路径。openrig 要解决的正是这类“多工具混用时的路由与状态管理”问题。理解了这一点后面所有的配置和排查就都有了主线。2. 核心设计思路与方案选型拆解2.1 为什么要做“运行时隔离”而不是“配置合并”很多人第一反应是我直接把 Claude Code 和 Codex 的配置写在一个文件里不就行了我试过结论是短期可行长期必炸。原因在于这两个工具的配置模型根本不一样。Claude Code 的配置偏向于“会话级”的它关心的是当前这个终端会话用哪个模型、走哪个端点、有没有开启自动执行终端命令。而 Codex 的配置更偏向于“项目级”和“组织级”的它涉及登录态、组织设置、模型白名单这些东西。你把它们塞进同一个配置文件就会出现热词里那种codex is ignoring 1 unrecognized configuration setting的警告甚至更严重的your organization has disabled claude subscription access这类权限冲突。openrig 的思路是不合并而是隔离。每个工具、每个项目、甚至每个会话都可以有自己独立的配置命名空间需要的时候再通过一个统一的入口去切换。这就像你不会把 Python 的虚拟环境和 Node.js 的 node_modules 混在一个目录里道理是一样的。2.2 为什么选 tmux 作为底层会话载体openrig 和 tmux 的绑定非常深这不是偶然的。tmux 的核心能力是“会话持久化”和“窗口分屏”而 AI 编程助手的使用场景恰好需要这两点。你想想你让 Claude Code 跑一个重构任务它可能要执行十几条终端命令中间你如果关掉终端任务就断了。但如果你把它跑在 tmux 会话里即使你断开 SSH任务还在后台跑着回来tmux attach就能看到完整输出。更重要的是tmux 的 session 和 window 天然就是隔离单元。openrig 可以利用 tmux 的 session 来隔离不同项目的 AI 助手实例用 window 来区分 Claude Code 和 Codex 的不同任务流。这种设计比自己去实现一套进程管理要稳得多因为 tmux 本身已经经过了十几年的实战检验。我在 Ubuntu 上实测下来用 tmux 承载 openrig 的会话稳定性明显好于直接裸跑。2.3 模型端点路由的设计取舍热词里有个很关键的报错cc switch local proxy failed while handling codex endpoint /responses。这说明 openrig 在路由层需要同时处理 Claude 风格的端点和 Codex 风格的端点。Claude Code 默认走的是 Anthropic 的 messages 接口格式而 Codex 走的是/responses这种更接近 OpenAI 风格的接口。这两套协议在请求体结构、流式返回格式、错误码定义上都有差异。openrig 的选择是在中间加一层轻量代理做协议转换和路径重写。这个代理不做复杂的业务逻辑只做三件事识别目标工具、重写端点路径、透传认证信息。这样做的好处是代理层足够薄出问题容易排查坏处是如果路径匹配规则写错了就会出现上面那种failed while handling endpoint的报错。我的经验是代理规则一定要用精确匹配而不是模糊匹配否则/responses很容易被错误地转发到 Claude 的端点上去。3. 环境准备与核心依赖安装实操3.1 Node.js 版本选择与安装避坑openrig 本身是 Node.js 写的所以第一步就是把 Node.js 装对。热词里有个很典型的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错说明有人试图安装一个还不存在的版本。我的建议是直接用 LTS 版本不要追最新的奇数版本。截至我写这篇内容的时候Node.js 20 LTS 是最稳的选择。在 Ubuntu 上安装 Node.js 20我不推荐用系统自带的 apt 源因为版本通常太老。我习惯用 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 开头的版本就说明装对了。这里有个坑如果你之前用 apt 装过旧版本可能会出现node和nodejs两个命令指向不同版本的情况。用which node和which nodejs确认一下如果指向不同路径用sudo update-alternatives统一一下。3.2 Claude Code 与 Codex 的安装顺序这两个工具的安装顺序其实有讲究。我的建议是先装 Claude Code再装 Codex。原因是 Claude Code 的安装脚本会检查一些全局的 npm 配置而 Codex 的安装过程相对独立。如果你先装 Codex有时候会出现 npm 全局路径被修改导致 Claude Code 安装时找不到正确的 bin 目录。Claude Code 的安装官方推荐的方式是通过 npm 全局安装npm install -g anthropic-ai/claude-codeCodex 的安装类似npm install -g openai/codex装完之后两个命令都应该能在终端里直接调用。如果提示command not found大概率是 npm 的全局 bin 目录没有加到 PATH 里。用npm config get prefix看一下全局前缀然后把对应的 bin 目录加到.bashrc或.zshrc里。3.3 tmux 的配置要点tmux 虽然可以直接用默认配置但为了配合 openrig 做会话隔离我建议至少改两个地方。第一是开启鼠标支持方便在多个 window 之间点击切换set -g mouse on第二是调整历史滚动缓冲区大小因为 AI 编程助手的输出往往很长默认的 2000 行不够用set -g history-limit 50000这两个配置写在~/.tmux.conf里然后tmux source-file ~/.tmux.conf生效。别小看这两行我在排查一个会话输出被截断的问题时最后发现就是 history-limit 太小导致的。4. openrig 核心配置与多工具接入实战4.1 配置文件结构设计openrig 的配置文件我建议分成三层全局层、工具层、项目层。全局层放一些通用的设置比如默认的 tmux 会话前缀、日志级别。工具层分别放 Claude Code 和 Codex 的接入参数。项目层则是每个项目独立的覆盖配置。一个典型的工具层配置大概长这样{ tools: { claude: { endpoint: http://localhost:8080/v1/messages, model: claude-sonnet, autoExecute: false }, codex: { endpoint: http://localhost:8080/v1/responses, model: gpt-5.6-sol, organization: default } } }这里要注意autoExecute这个参数。Claude Code 有一个能力是直接执行终端命令热词里也有人问claude code如何直接执行终端命令。我的建议是在 openrig 里默认关掉这个能力需要的时候再针对具体项目打开。因为自动执行命令在隔离环境里风险可控但如果你在宿主机上直接跑一个错误的rm命令就可能造成不可逆的损失。4.2 接入本地模型与第三方 API热词里提到claude code 调用lmstudio的本地模型和codex接入deepseek这两个场景我都实测过。核心思路是一样的把 openrig 的代理层指向本地或第三方的端点然后让 Claude Code 和 Codex 以为自己在跟官方端点通信。以接入本地模型为例假设你的本地模型服务跑在http://127.0.0.1:1234你需要在 openrig 的代理配置里加一条路由规则{ routes: [ { match: /v1/messages, target: http://127.0.0.1:1234/v1/chat/completions, transform: claude-to-openai } ] }这里的transform字段是关键它告诉 openrig 需要做协议转换。因为本地模型服务通常只支持 OpenAI 风格的接口而 Claude Code 发出来的是 Anthropic 风格的请求。这个转换层如果写得不严谨就会出现请求体字段丢失或者流式返回解析错误的问题。4.3 用 cc switch 做多模型切换的注意事项热词里反复出现cc switch和使用cc switch 接入 deepseek v4, qwen, glm等模型。cc switch 本质上是一个模型切换器它和 openrig 的关系是互补的openrig 管的是工具级别的隔离cc switch 管的是模型级别的切换。我在用 cc switch 的时候踩过一个坑如果你在 openrig 的会话里直接调用 cc switch它可能会修改全局的模型配置导致其他 tmux 会话里的模型也跟着变了。正确的做法是让 cc switch 在 openrig 的项目级配置里生效而不是全局生效。具体来说就是在项目目录下放一个.cc-switch配置文件openrig 启动会话时会优先读取这个文件。5. 常见报错排查与稳定性优化5.1 端点路由类报错速查热词里那个cc switch local proxy failed while handling codex endpoint /responses是最典型的。我把这类报错整理成了一个速查表报错关键词可能原因排查方向failed while handling endpoint /responses代理路由规则未匹配到 Codex 端点检查 routes 里是否有/v1/responses的精确匹配model is not supported when using codex模型名不在 Codex 的白名单里确认模型名拼写检查组织设置里的模型权限ignoring unrecognized configuration setting配置文件里有 Codex 不认识的字段把 Claude 专属字段从 Codex 的配置块里移走organization has disabled claude subscription access组织级权限限制检查登录态确认当前账号有对应工具的访问权限这个表里的每一行都是我实际遇到过的。特别是第一行我一开始以为是代理服务挂了后来才发现是路由规则里写的是/responses但实际请求路径是/v1/responses差了一个前缀就匹配不上。5.2 登录态与组织设置问题codex登录不上和codex无法加载组织设置这两个问题经常一起出现。我的经验是Codex 的登录态是存在本地的一个凭证文件里的如果你在多个环境之间同步了配置文件但没同步凭证就会出现登录态失效。解决办法是重新走一遍登录流程不要试图手动复制凭证文件。另外如果你在用第三方 API 接入 Codex组织设置这一块可能会报错因为第三方端点通常没有“组织”这个概念。这时候需要在 openrig 的配置里把组织相关的检查关掉或者给一个默认的组织标识。5.3 会话稳定性优化最后说几个提升稳定性的实操技巧。第一给 tmux 会话设置一个合理的超时时间避免长时间空闲的会话占用资源。第二openrig 的日志级别建议设为info而不是debugdebug 级别在长时间运行后会产生大量日志拖慢会话响应。第三如果你在 Ubuntu 上跑建议把 openrig 的进程用 systemd 管理起来这样即使终端断开代理层也不会挂掉。我在实际使用中发现把 openrig 的代理层和 tmux 会话分开管理是最稳的架构。代理层作为一个常驻服务跑着tmux 会话按需创建和销毁。这样即使某个会话崩了代理层还在重新 attach 或者新建会话就能恢复工作不用每次都重启整个环境。这个架构我跑了几个月除了偶尔因为模型端点网络波动需要重连之外没有出现过整体不可用的情况。 
长河君 · 2026/10/8 23:04:48 · 阅读 1.2k openrig 多 AI 编程助手运行时隔离与端点路由实战
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里就是“装配、设备”的意思。但翻了一圈社区讨论和实际代码之后才明白它其实是一个围绕 AI 编程助手做“编排”和“环境隔离”的工具层。简单说openrig 解决的是这样一个问题当你同时用 Claude Code、Codex 这类命令行 AI 编程工具时它们各自有各自的配置、各自的会话状态、各自的模型接入方式混在一起用很容易互相打架。openrig 就是把这些东西统一管起来的那一层。它适合谁如果你只是偶尔用一下 Claude Code 写个小脚本那确实用不上。但如果你像我一样日常要在多个项目之间切换一会儿用 Claude Code 调本地模型一会儿用 Codex 接第三方 API还要保证每个项目的配置互不污染那 openrig 这类工具的价值就出来了。它本质上是一个“多 AI 编程助手的运行时管理器”核心能力包括会话隔离、配置切换、模型端点路由以及和 tmux 这类终端复用器的深度集成。我之所以关注到它是因为热词里反复出现cc switch local proxy failed while handling codex endpoint /responses这类报错。这个报错的本质是你在用某个切换工具把 Claude Code 的请求转发到 Codex 的端点时代理层没有正确处理/responses这个路径。openrig 要解决的正是这类“多工具混用时的路由与状态管理”问题。理解了这一点后面所有的配置和排查就都有了主线。2. 核心设计思路与方案选型拆解2.1 为什么要做“运行时隔离”而不是“配置合并”很多人第一反应是我直接把 Claude Code 和 Codex 的配置写在一个文件里不就行了我试过结论是短期可行长期必炸。原因在于这两个工具的配置模型根本不一样。Claude Code 的配置偏向于“会话级”的它关心的是当前这个终端会话用哪个模型、走哪个端点、有没有开启自动执行终端命令。而 Codex 的配置更偏向于“项目级”和“组织级”的它涉及登录态、组织设置、模型白名单这些东西。你把它们塞进同一个配置文件就会出现热词里那种codex is ignoring 1 unrecognized configuration setting的警告甚至更严重的your organization has disabled claude subscription access这类权限冲突。openrig 的思路是不合并而是隔离。每个工具、每个项目、甚至每个会话都可以有自己独立的配置命名空间需要的时候再通过一个统一的入口去切换。这就像你不会把 Python 的虚拟环境和 Node.js 的 node_modules 混在一个目录里道理是一样的。2.2 为什么选 tmux 作为底层会话载体openrig 和 tmux 的绑定非常深这不是偶然的。tmux 的核心能力是“会话持久化”和“窗口分屏”而 AI 编程助手的使用场景恰好需要这两点。你想想你让 Claude Code 跑一个重构任务它可能要执行十几条终端命令中间你如果关掉终端任务就断了。但如果你把它跑在 tmux 会话里即使你断开 SSH任务还在后台跑着回来tmux attach就能看到完整输出。更重要的是tmux 的 session 和 window 天然就是隔离单元。openrig 可以利用 tmux 的 session 来隔离不同项目的 AI 助手实例用 window 来区分 Claude Code 和 Codex 的不同任务流。这种设计比自己去实现一套进程管理要稳得多因为 tmux 本身已经经过了十几年的实战检验。我在 Ubuntu 上实测下来用 tmux 承载 openrig 的会话稳定性明显好于直接裸跑。2.3 模型端点路由的设计取舍热词里有个很关键的报错cc switch local proxy failed while handling codex endpoint /responses。这说明 openrig 在路由层需要同时处理 Claude 风格的端点和 Codex 风格的端点。Claude Code 默认走的是 Anthropic 的 messages 接口格式而 Codex 走的是/responses这种更接近 OpenAI 风格的接口。这两套协议在请求体结构、流式返回格式、错误码定义上都有差异。openrig 的选择是在中间加一层轻量代理做协议转换和路径重写。这个代理不做复杂的业务逻辑只做三件事识别目标工具、重写端点路径、透传认证信息。这样做的好处是代理层足够薄出问题容易排查坏处是如果路径匹配规则写错了就会出现上面那种failed while handling endpoint的报错。我的经验是代理规则一定要用精确匹配而不是模糊匹配否则/responses很容易被错误地转发到 Claude 的端点上去。3. 环境准备与核心依赖安装实操3.1 Node.js 版本选择与安装避坑openrig 本身是 Node.js 写的所以第一步就是把 Node.js 装对。热词里有个很典型的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错说明有人试图安装一个还不存在的版本。我的建议是直接用 LTS 版本不要追最新的奇数版本。截至我写这篇内容的时候Node.js 20 LTS 是最稳的选择。在 Ubuntu 上安装 Node.js 20我不推荐用系统自带的 apt 源因为版本通常太老。我习惯用 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 开头的版本就说明装对了。这里有个坑如果你之前用 apt 装过旧版本可能会出现node和nodejs两个命令指向不同版本的情况。用which node和which nodejs确认一下如果指向不同路径用sudo update-alternatives统一一下。3.2 Claude Code 与 Codex 的安装顺序这两个工具的安装顺序其实有讲究。我的建议是先装 Claude Code再装 Codex。原因是 Claude Code 的安装脚本会检查一些全局的 npm 配置而 Codex 的安装过程相对独立。如果你先装 Codex有时候会出现 npm 全局路径被修改导致 Claude Code 安装时找不到正确的 bin 目录。Claude Code 的安装官方推荐的方式是通过 npm 全局安装npm install -g anthropic-ai/claude-codeCodex 的安装类似npm install -g openai/codex装完之后两个命令都应该能在终端里直接调用。如果提示command not found大概率是 npm 的全局 bin 目录没有加到 PATH 里。用npm config get prefix看一下全局前缀然后把对应的 bin 目录加到.bashrc或.zshrc里。3.3 tmux 的配置要点tmux 虽然可以直接用默认配置但为了配合 openrig 做会话隔离我建议至少改两个地方。第一是开启鼠标支持方便在多个 window 之间点击切换set -g mouse on第二是调整历史滚动缓冲区大小因为 AI 编程助手的输出往往很长默认的 2000 行不够用set -g history-limit 50000这两个配置写在~/.tmux.conf里然后tmux source-file ~/.tmux.conf生效。别小看这两行我在排查一个会话输出被截断的问题时最后发现就是 history-limit 太小导致的。4. openrig 核心配置与多工具接入实战4.1 配置文件结构设计openrig 的配置文件我建议分成三层全局层、工具层、项目层。全局层放一些通用的设置比如默认的 tmux 会话前缀、日志级别。工具层分别放 Claude Code 和 Codex 的接入参数。项目层则是每个项目独立的覆盖配置。一个典型的工具层配置大概长这样{ tools: { claude: { endpoint: http://localhost:8080/v1/messages, model: claude-sonnet, autoExecute: false }, codex: { endpoint: http://localhost:8080/v1/responses, model: gpt-5.6-sol, organization: default } } }这里要注意autoExecute这个参数。Claude Code 有一个能力是直接执行终端命令热词里也有人问claude code如何直接执行终端命令。我的建议是在 openrig 里默认关掉这个能力需要的时候再针对具体项目打开。因为自动执行命令在隔离环境里风险可控但如果你在宿主机上直接跑一个错误的rm命令就可能造成不可逆的损失。4.2 接入本地模型与第三方 API热词里提到claude code 调用lmstudio的本地模型和codex接入deepseek这两个场景我都实测过。核心思路是一样的把 openrig 的代理层指向本地或第三方的端点然后让 Claude Code 和 Codex 以为自己在跟官方端点通信。以接入本地模型为例假设你的本地模型服务跑在http://127.0.0.1:1234你需要在 openrig 的代理配置里加一条路由规则{ routes: [ { match: /v1/messages, target: http://127.0.0.1:1234/v1/chat/completions, transform: claude-to-openai } ] }这里的transform字段是关键它告诉 openrig 需要做协议转换。因为本地模型服务通常只支持 OpenAI 风格的接口而 Claude Code 发出来的是 Anthropic 风格的请求。这个转换层如果写得不严谨就会出现请求体字段丢失或者流式返回解析错误的问题。4.3 用 cc switch 做多模型切换的注意事项热词里反复出现cc switch和使用cc switch 接入 deepseek v4, qwen, glm等模型。cc switch 本质上是一个模型切换器它和 openrig 的关系是互补的openrig 管的是工具级别的隔离cc switch 管的是模型级别的切换。我在用 cc switch 的时候踩过一个坑如果你在 openrig 的会话里直接调用 cc switch它可能会修改全局的模型配置导致其他 tmux 会话里的模型也跟着变了。正确的做法是让 cc switch 在 openrig 的项目级配置里生效而不是全局生效。具体来说就是在项目目录下放一个.cc-switch配置文件openrig 启动会话时会优先读取这个文件。5. 常见报错排查与稳定性优化5.1 端点路由类报错速查热词里那个cc switch local proxy failed while handling codex endpoint /responses是最典型的。我把这类报错整理成了一个速查表报错关键词可能原因排查方向failed while handling endpoint /responses代理路由规则未匹配到 Codex 端点检查 routes 里是否有/v1/responses的精确匹配model is not supported when using codex模型名不在 Codex 的白名单里确认模型名拼写检查组织设置里的模型权限ignoring unrecognized configuration setting配置文件里有 Codex 不认识的字段把 Claude 专属字段从 Codex 的配置块里移走organization has disabled claude subscription access组织级权限限制检查登录态确认当前账号有对应工具的访问权限这个表里的每一行都是我实际遇到过的。特别是第一行我一开始以为是代理服务挂了后来才发现是路由规则里写的是/responses但实际请求路径是/v1/responses差了一个前缀就匹配不上。5.2 登录态与组织设置问题codex登录不上和codex无法加载组织设置这两个问题经常一起出现。我的经验是Codex 的登录态是存在本地的一个凭证文件里的如果你在多个环境之间同步了配置文件但没同步凭证就会出现登录态失效。解决办法是重新走一遍登录流程不要试图手动复制凭证文件。另外如果你在用第三方 API 接入 Codex组织设置这一块可能会报错因为第三方端点通常没有“组织”这个概念。这时候需要在 openrig 的配置里把组织相关的检查关掉或者给一个默认的组织标识。5.3 会话稳定性优化最后说几个提升稳定性的实操技巧。第一给 tmux 会话设置一个合理的超时时间避免长时间空闲的会话占用资源。第二openrig 的日志级别建议设为info而不是debugdebug 级别在长时间运行后会产生大量日志拖慢会话响应。第三如果你在 Ubuntu 上跑建议把 openrig 的进程用 systemd 管理起来这样即使终端断开代理层也不会挂掉。我在实际使用中发现把 openrig 的代理层和 tmux 会话分开管理是最稳的架构。代理层作为一个常驻服务跑着tmux 会话按需创建和销毁。这样即使某个会话崩了代理层还在重新 attach 或者新建会话就能恢复工作不用每次都重启整个环境。这个架构我跑了几个月除了偶尔因为模型端点网络波动需要重连之外没有出现过整体不可用的情况。