1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目或者机械臂相关的工具毕竟“rig”这个词在工程领域通常指代设备支架或测试台架。但如果你最近在折腾 Claude Code、Codex 这类 AI 编程助手并且被各种配置文件、终端会话管理、代理转发搞得头大那你大概率已经隐约感觉到市面上缺一个能把这一切串起来的东西。openrig 就是冲着这个缺口来的。简单来说openrig 是一个面向 AI 编程助手工作流的开源编排工具。它的核心思路是把 Claude Code、Codex 这类 CLI 工具的配置管理、会话保持、代理转发、多模型切换等琐碎但关键的环节统一收敛到一套 YAML 配置和 tmux 会话管理里。你不需要再手动去改每个工具的配置文件也不需要每次开新终端都重新设置一遍环境变量更不需要在多个模型供应商之间来回切换时手忙脚乱。这个项目适合谁如果你满足以下任意一条openrig 就值得你花时间研究你同时使用 Claude Code 和 Codex并且希望它们共享同一套配置逻辑你在国内环境下需要接入 DeepSeek 或其他本地模型来替代默认的云端服务你经常需要在不同项目之间切换每个项目对模型、代理、上下文长度的要求都不一样你受够了每次重启终端后 tmux 会话丢失、代理配置失效、认证 token 过期的循环折磨。我最初接触 openrig 是因为一个很具体的痛点我在 Ubuntu 上跑 Claude Code 做 STM32 嵌入式项目的代码辅助同时又在 Windows 桌面版 Codex 上处理一些文档和脚本任务。两边的配置文件格式不同、认证方式不同、代理设置不同每次切换都要重新折腾一遍。更麻烦的是Claude Code 的 1M 上下文模式需要特定的环境变量组合而 Codex 的 auth token 又经常莫名其妙失效。openrig 的出现让我看到了把这些碎片统一管理的可能性。注意openrig 本身不是一个模型也不是一个代理服务。它不提供任何网络转发能力也不包含任何绕过限制的功能。它只是一个配置编排层帮你把已有的工具和资源组织得更合理。2. 核心设计思路拆解为什么是 YAML 加 tmux2.1 配置即代码YAML 作为统一入口的合理性openrig 选择 YAML 作为核心配置格式这个决策背后有很实际的考量。Claude Code 和 Codex 各自的配置文件格式并不统一Claude Code 偏向 JSON 风格的配置Codex 则有自己的 TOML 或环境变量体系。如果你同时用这两个工具再加上可能需要接入的本地模型服务比如 LM Studio 或 DeepSeek 的 API配置文件的数量会迅速膨胀到难以维护的程度。YAML 的优势在于它的表达力和可读性平衡得比较好。相比 JSONYAML 支持注释这对配置文件来说太重要了——你可以直接在配置里写明“这个参数是为了开启 1M 上下文模式”或者“这个代理地址只在公司内网有效”。相比 TOMLYAML 的嵌套结构更灵活适合表达 openrig 这种需要描述多工具、多环境、多模型映射关系的场景。我实测下来一个典型的 openrig 配置文件大概长这样version: 1 defaults: model: deepseek-chat context_window: 128000 proxy: http://127.0.0.1:7890 tools: claude-code: enabled: true model_override: claude-sonnet extra_env: CLAUDE_CODE_MAX_CONTEXT: 1000000 CLAUDE_CODE_THEME: dark codex: enabled: true auth_mode: token endpoint: /responses model_map: default: deepseek-coder fast: deepseek-chat sessions: - name: stm32-dev tools: [claude-code] workdir: ~/projects/stm32-firmware env: TARGET_BOARD: stm32f407 - name: doc-writing tools: [codex] workdir: ~/docs env: LANG: zh_CN.UTF-8这个配置文件的结构很直观defaults 定义全局默认值tools 定义每个工具的个性化配置sessions 定义具体的工作会话。你不需要记住每个工具的环境变量名openrig 会帮你做映射和注入。2.2 tmux 作为会话容器的不可替代性为什么是 tmux 而不是其他终端复用工具这个问题我被问过很多次。screen 太老功能有限zellij 虽然现代但生态还不够成熟至于各种终端模拟器自带的标签页功能它们解决不了“会话持久化”这个核心问题。tmux 的关键价值在于它让 AI 编程助手的会话变成了可以随时挂起、恢复、切换的独立单元。你可以在一个 tmux 会话里跑 Claude Code 做代码审查在另一个会话里跑 Codex 生成测试用例然后随时 detach 去处理别的事情回来再 attach 继续。对于需要长时间运行的 AI 任务比如让 Claude Code 分析整个代码库这个能力是刚需。openrig 在 tmux 基础上做了一层封装它根据 YAML 配置自动创建和管理会话。你不需要手动敲tmux new-session -s xxx然后再 cd 到工作目录再设置环境变量再启动工具。openrig 把这些步骤全部自动化了。我试过在配置里定义五个不同的会话然后一条命令就把它们全部拉起来每个会话都在正确的工作目录、带着正确的环境变量、运行着正确的工具。提示tmux 的会话在服务器重启后会丢失这是它的设计使然。如果你需要跨重启保持会话需要配合其他持久化方案但那是另一个话题了。2.3 代理转发的边界与定位热词里出现了“cc switch local proxy failed while handling codex endpoint /responses”这样的报错信息这说明很多用户在使用类似工具时遇到了代理转发层面的问题。openrig 在这个环节的定位需要说清楚它不实现代理协议也不修改任何网络请求的内容。它做的是配置管理——帮你把正确的代理地址、端点路径、认证信息注入到对应工具的环境变量或配置文件中。Codex 的/responses端点报错通常是因为代理配置和工具期望的端点格式不匹配。openrig 的做法是在 YAML 里显式定义每个工具的 endpoint 和 proxy 字段然后在启动时做一致性校验。如果配置里写的 proxy 地址无法连通openrig 会在启动会话前给出警告而不是等到工具运行到一半才报错。这个设计思路很务实把问题暴露在最早的时间点。3. 实操环境搭建从安装到第一个会话3.1 基础依赖的安装与验证openrig 本身是一个命令行工具它的运行依赖几个基础组件。在 Ubuntu 或 Debian 系的环境下你需要先确保这些依赖就位# 更新包索引 sudo apt update # 安装 tmux 和 Python 环境 sudo apt install -y tmux python3 python3-pip python3-venv # 验证 tmux 版本建议 3.0 以上 tmux -V # 验证 Python 版本建议 3.10 以上 python3 --version如果你在 Windows 上情况会稍微复杂一些。Windows 桌面版 Claude Code 和 Codex 的安装方式不同openrig 在 Windows 上需要通过 WSL2 来运行。我个人的建议是如果你主要在 Windows 上工作先在 WSL2 里装一个 Ubuntu 环境然后在 WSL2 里按照 Linux 的方式安装 openrig。这样配置文件和会话管理都在 Linux 侧Windows 侧只需要一个终端模拟器比如 Windows Terminal来连接 WSL2 即可。macOS 用户相对简单用 Homebrew 安装依赖brew install tmux python3安装完基础依赖后验证一下 tmux 是否能正常工作tmux new-session -d -s test-session tmux ls tmux kill-session -t test-session如果这几条命令都没有报错说明 tmux 环境是健康的。3.2 openrig 的获取与初始化openrig 目前主要通过源码方式分发。你可以从项目的代码仓库克隆到本地git clone https://github.com/your-org/openrig.git cd openrig python3 -m venv .venv source .venv/bin/activate pip install -e .安装完成后运行初始化命令openrig init这个命令会在~/.config/openrig/目录下生成一个默认的配置文件模板。你可以直接编辑这个文件也可以把它复制到项目目录下做项目级配置。openrig 的配置查找顺序是当前目录下的openrig.yaml 用户配置目录下的config.yaml 内置默认值。这个优先级设计让你可以轻松地为不同项目定制不同的配置。注意如果你之前已经手动配置过 Claude Code 或 Codex 的环境变量建议先把那些配置备份一下。openrig 在启动会话时会覆盖部分环境变量虽然它尽量做了兼容处理但备份总是没错的。3.3 第一个最小化配置不要一上来就写一个几百行的配置文件。我的经验是先用最小化配置跑通一个工具确认整个链路没有问题再逐步添加更多工具和会话。一个最小化的 Claude Code 配置version: 1 tools: claude-code: enabled: true model_override: claude-sonnet sessions: - name: hello-claude tools: [claude-code] workdir: ~/projects保存为openrig.yaml然后运行openrig up hello-claude如果一切正常你会看到 tmux 会话被创建Claude Code 在指定目录下启动。你可以用tmux attach -t hello-claude进入会话或者用openrig attach hello-claude这个封装命令。我第一次跑通这个流程的时候发现 Claude Code 启动后提示“your organization has disabled claude subscription access for claude code”。这个报错说明认证层面有问题和 openrig 本身无关。你需要确保 Claude Code 的认证信息已经正确配置。openrig 不会帮你处理认证它只负责把工具启动起来。4. 多工具协同与模型接入的实战细节4.1 Claude Code 与 Codex 的配置差异处理Claude Code 和 Codex 虽然都是 AI 编程助手但它们的配置哲学完全不同。Claude Code 倾向于通过环境变量来控制行为比如CLAUDE_CODE_MAX_CONTEXT控制上下文窗口大小CLAUDE_CODE_THEME控制界面主题。Codex 则更依赖配置文件它的auth token和endpoint设置通常写在~/.codex/config.toml或类似位置。openrig 在处理这个差异时采用了一种“适配器”模式。在 YAML 配置里你只需要声明你想要的效果openrig 会根据工具类型自动选择正确的注入方式。比如你想让 Claude Code 使用 1M 上下文只需要写tools: claude-code: extra_env: CLAUDE_CODE_MAX_CONTEXT: 1000000而如果你想让 Codex 接入 DeepSeek配置会是这样tools: codex: endpoint: https://api.deepseek.com/v1 model_map: default: deepseek-coder auth: token_env: DEEPSEEK_API_KEYopenrig 会在启动 Codex 会话时把DEEPSEEK_API_KEY从你的环境变量中读取出来注入到 Codex 期望的位置。这个设计的好处是你的 API key 不需要写在 YAML 文件里避免了密钥泄露的风险。4.2 本地模型接入以 LM Studio 为例热词里出现了“claude code 调用 lmstudio 的本地模型”这说明很多用户希望在本地运行模型来替代云端服务。openrig 对本地模型的支持是通过标准的 OpenAI 兼容接口来实现的。LM Studio 默认在http://localhost:1234/v1提供 OpenAI 兼容的 API你只需要在 openrig 配置里把 endpoint 指向这个地址即可。tools: claude-code: enabled: true endpoint: http://localhost:1234/v1 model_override: local-model extra_env: OPENAI_API_KEY: lm-studio OPENAI_BASE_URL: http://localhost:1234/v1这里有一个细节需要注意Claude Code 原生并不支持 OpenAI 兼容接口它使用的是自己的 API 格式。所以如果你想让 Claude Code 调用 LM Studio 的本地模型中间需要一个转换层。openrig 本身不做这个转换但它的配置管理能力可以帮你把转换层的地址和参数管理起来。我实测下来比较稳妥的方案是使用一个轻量的 API 转换工具把 OpenAI 格式的请求转换成 Claude Code 期望的格式然后 openrig 负责把这个转换工具的地址注入到 Claude Code 的环境变量里。提示本地模型的上下文窗口通常比云端模型小很多。如果你在配置里写了CLAUDE_CODE_MAX_CONTEXT: 1000000但本地模型只支持 32K实际运行时会被截断。建议根据本地模型的实际能力来设置这个参数。4.3 多会话并行管理的最佳实践openrig 的 sessions 配置支持定义多个会话每个会话可以指定不同的工具组合、工作目录和环境变量。这个能力在实际工作中非常有用。我通常会同时开三个会话第一个是code-review会话只启用 Claude Code工作目录指向当前正在开发的代码库环境变量里设置CLAUDE_CODE_MAX_CONTEXT为较大值用于做深度的代码审查。第二个是quick-fix会话只启用 Codex工作目录相同但模型映射到更快的模型比如 deepseek-chat用于处理一些简单的代码修改和脚本生成。第三个是doc-gen会话同时启用 Claude Code 和 Codex工作目录指向文档目录用于生成项目文档和注释。这三个会话在 tmux 里是独立运行的我可以随时在它们之间切换每个会话的状态都会被保留。openrig 提供了一个openrig ls命令来列出所有活跃会话以及openrig attach name来快速切换。# 列出所有 openrig 管理的会话 openrig ls # 输出示例 # NAME TOOLS WORKDIR STATUS # code-review claude-code ~/projects/main running # quick-fix codex ~/projects/main running # doc-gen claude-code,codex ~/docs running这个表格化的输出让我一眼就能看到每个会话的状态比手动敲tmux ls再自己去对应要方便得多。5. 常见问题排查与避坑经验5.1 代理配置相关的典型报错“cc switch local proxy failed while handling codex endpoint /responses”这个报错我在早期测试中遇到过。问题的根源通常是Codex 期望的 endpoint 路径和代理实际提供的路径不一致。Codex 默认会向/responses路径发送请求但有些代理工具默认只转发/v1/chat/completions这类路径。排查这个问题的第一步是确认代理工具本身是否支持/responses路径。你可以用 curl 直接测试curl -X POST http://127.0.0.1:7890/responses \ -H Content-Type: application/json \ -d {model: test, input: hello}如果这个请求返回 404说明代理工具没有配置/responses的路由。你需要在代理工具的配置里添加这个路径的转发规则。openrig 能帮你做的是在 YAML 里显式声明 endpoint 路径并在启动会话前做一次连通性检查。tools: codex: endpoint: http://127.0.0.1:7890/responses health_check: enabled: true timeout: 5开启 health_check 后openrig 会在启动 Codex 会话前先发一个测试请求如果失败会给出明确的错误提示而不是让 Codex 启动后再报一堆看不懂的错。5.2 认证失效与 token 管理“codex auth token is unavailable”是另一个高频问题。Codex 的认证 token 有时效性过期后需要重新获取。openrig 本身不管理 token 的生命周期但它提供了一个机制你可以在 YAML 里指定 token 从哪个环境变量读取然后自己用一个外部脚本来定期刷新这个环境变量。我的做法是写一个简单的 shell 脚本在每天开始工作前运行一次刷新 token 并写入一个临时文件然后 openrig 从那个文件读取。这个方案不优雅但很实用。#!/bin/bash # refresh-token.sh NEW_TOKEN$(curl -s -X POST https://auth.example.com/token \ -d grant_typerefresh_tokenrefresh_token$REFRESH_TOKEN | jq -r .access_token) echo export CODEX_AUTH_TOKEN$NEW_TOKEN ~/.openrig/env.sh source ~/.openrig/env.sh然后在 openrig 配置里tools: codex: auth: token_env: CODEX_AUTH_TOKENopenrig 启动会话时会自动 source~/.openrig/env.sh这样 token 就是最新的。5.3 会话丢失与恢复策略tmux 会话在系统重启后会丢失这是无法避免的。但 openrig 的 YAML 配置是持久化的所以恢复起来并不麻烦。我的做法是把openrig up命令写进 shell 的启动脚本里每次登录后自动执行。# 在 ~/.bashrc 或 ~/.zshrc 中添加 if command -v openrig /dev/null; then openrig up --all --detached fi--all参数会启动配置文件中定义的所有会话--detached让它们在后台运行不占用当前终端。这样每次登录后所有会话都会自动恢复我只需要 attach 到需要的那一个即可。注意如果你的会话里有正在运行的长时间任务比如让 Claude Code 分析整个代码库系统重启会导致这些任务中断。对于这类场景建议把任务输出重定向到文件这样即使会话丢失结果也不会丢。5.4 常见问题速查表问题现象可能原因排查步骤解决方案Claude Code 启动后提示订阅被禁用认证信息未配置或已过期检查~/.claude/下的认证文件重新登录 Claude Code 完成认证Codex 报/responses端点错误代理不支持该路径用 curl 直接测试端点连通性在代理配置中添加/responses路由auth token unavailabletoken 过期或环境变量未注入检查echo $CODEX_AUTH_TOKEN刷新 token 并重新 source 环境变量tmux 会话启动后立即退出工作目录不存在或权限不足检查 YAML 中的 workdir 路径确保目录存在且有读写权限本地模型响应超时模型加载慢或上下文过长检查 LM Studio 的日志减小上下文窗口或等待模型加载完成YAML 解析报错缩进错误或特殊字符未转义用python3 -c import yaml; yaml.safe_load(open(openrig.yaml))验证修正缩进对特殊字符加引号这个表格是我在实际使用中逐步积累的基本上覆盖了 80% 以上的常见问题。遇到新问题时我会先对照这个表格排查大部分情况下都能快速定位。6. 进阶玩法把 openrig 融入日常开发流6.1 与 VS Code 的联动配置很多人的开发环境是 VS Code 加终端。openrig 可以和 VS Code 的集成终端很好地配合。你可以在 VS Code 的settings.json里配置一个自定义终端 profile直接启动 openrig 会话{ terminal.integrated.profiles.linux: { openrig-claude: { path: bash, args: [-c, openrig attach code-review || openrig up code-review] } } }这样你在 VS Code 里打开终端时可以直接选择openrig-claudeprofile它会自动 attach 到已有的会话如果会话不存在则创建一个新的。这个流程把“打开终端”和“进入 AI 编程助手环境”合并成了一个动作省去了中间的手动步骤。对于 Windows 上的 VS Code 用户如果你用的是 WSL2 环境配置方式类似只需要确保 VS Code 的终端默认使用 WSL2 的 shell 即可。6.2 项目级配置的版本管理openrig 支持项目级配置文件这意味着你可以把openrig.yaml提交到项目的代码仓库里。团队成员克隆项目后只需要运行openrig up就能获得一致的 AI 编程助手环境。这个能力对于团队协作来说很有价值。但这里有一个坑项目级配置里不应该包含任何密钥或个人信息。我的做法是在项目级配置里只写工具和会话的结构把敏感信息通过环境变量引用# 项目级 openrig.yaml可以安全提交 tools: codex: auth: token_env: CODEX_AUTH_TOKEN # 从环境变量读取不写死 endpoint: ${CODEX_ENDPOINT} # 从环境变量读取然后在个人的~/.openrig/env.sh里设置这些环境变量的实际值。这样项目配置可以共享个人密钥不会泄露。6.3 多模型切换的自动化脚本openrig 的 YAML 配置支持变量替换你可以利用这个特性写一些自动化脚本。比如我经常需要在 DeepSeek 和本地模型之间切换就写了一个小脚本#!/bin/bash # switch-model.sh MODEL$1 if [ $MODEL local ]; then export OPENRIG_MODEL_OVERRIDElocal-model export OPENRIG_ENDPOINThttp://localhost:1234/v1 else export OPENRIG_MODEL_OVERRIDEdeepseek-coder export OPENRIG_ENDPOINThttps://api.deepseek.com/v1 fi openrig restart --all然后在 YAML 里用${OPENRIG_MODEL_OVERRIDE}和${OPENRIG_ENDPOINT}来引用这些变量。运行./switch-model.sh local就能把所有会话切换到本地模型运行./switch-model.sh deepseek就切回云端。这个方案让我在不同网络环境和不同任务需求之间切换时只需要一条命令。提示openrig restart会重启所有会话正在运行的任务会中断。建议在切换前确认没有正在执行的重要任务。6.4 日志与审计追踪 AI 助手的使用情况openrig 会在~/.openrig/logs/目录下记录每个会话的启动和停止事件。这些日志对于了解自己的 AI 助手使用模式很有帮助。你可以用简单的命令分析这些日志# 统计本周各工具的使用时长 openrig logs --since 7 days ago --format json | \ jq -r .[] | \(.tool) \(.duration) | \ awk {sum[$1]$2} END {for (t in sum) print t, sum[t]}这个分析让我发现自己在 Codex 上花的时间比预期多而在 Claude Code 上的时间偏少。于是我调整了工作流把更多代码审查任务交给 Claude Code利用它的长上下文能力做更深入的分析。这种基于数据的调整比凭感觉优化要有效得多。7. 一些踩过的坑和最后的建议openrig 的 YAML 配置里workdir字段不支持~符号的自动展开这是一个我踩过的坑。如果你写workdir: ~/projectsopenrig 会把它当成一个字面量路径而不是展开成/home/username/projects。正确的写法是使用绝对路径或者用${HOME}变量sessions: - name: my-session workdir: ${HOME}/projects # 正确写法另一个坑是 tmux 的默认 shell 问题。openrig 启动会话时使用的是系统默认 shell如果你在.bashrc里设置了很多环境变量但 tmux 启动的是一个非交互式 shell那些环境变量可能不会被加载。解决方案是在 openrig 配置里显式指定 shelldefaults: shell: /bin/bash shell_args: [-l] # -l 表示 login shell会加载 .bash_profile-l参数让 bash 以 login shell 模式启动这样.bash_profile和.profile里的配置都会被加载。这个细节在官方文档里没有写是我调试了两个小时才发现的。关于 Codex 的“破甲”问题热词里出现了这个词但我需要说明openrig 不涉及任何绕过安全限制的功能。如果你遇到 Codex 的某些功能无法使用正确的做法是检查你的账号权限和认证状态而不是寻找所谓的“破甲”方案。任何声称能绕过官方限制的工具或方法都存在安全风险不建议尝试。最后分享一个实用技巧openrig 的openrig doctor命令可以检查你的环境是否满足所有依赖要求并给出修复建议。我在新机器上部署时第一件事就是跑这个命令它能帮我省去很多手动排查的时间。openrig doctor # 输出示例 # [OK] tmux 3.3a # [OK] python 3.11.6 # [OK] config file found at ~/.config/openrig/config.yaml # [WARN] CODEX_AUTH_TOKEN not set in environment # [WARN] proxy at 127.0.0.1:7890 not reachable # [INFO] 2 sessions defined, 0 currently running这个命令的输出很直观OK 表示正常WARN 表示需要注意INFO 提供额外信息。我通常会在每次修改配置后跑一次openrig doctor确保没有引入新的问题。我个人在实际操作中的体会是openrig 的价值不在于它做了什么惊天动地的事情而在于它把那些琐碎但必要的配置管理工作收敛到了一个地方。你不需要再记住每个工具的环境变量名不需要手动管理 tmux 会话不需要在多个配置文件之间来回切换。这些节省下来的时间和精力可以真正用在写代码和解决问题上。对于同时使用多个 AI 编程助手的开发者来说这种效率提升是实实在在的。