1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的不是某个具体工具而是一种把散装零件拼成一台整机的直觉。rig 在英文里本意是装配、索具、钻井平台在工程语境里常指把一堆独立部件按某种规范组装成一套可运转的系统。前面加个 open意思就很明确了这是一套开放的、可自定义的装配方案而不是一个封闭的黑盒产品。结合热搜词里高频出现的 Claude Code、Codex、YAML、tmux 这几个关键词我基本能判断出 openrig 的定位——它大概率是一套围绕 AI 编程助手Claude Code、Codex 这类 CLI 工具的工作流编排与配置管理方案。为什么这么说因为这几个词凑在一起指向的是一个非常具体的痛点场景Claude Code 和 Codex 都是命令行形态的 AI 编程助手各自有独立的配置体系、认证方式、会话管理逻辑YAML 是它们最常用的配置文件格式用来定义模型、端点、权限、工具链tmux 是终端复用器用来在多个会话之间切换、保持长任务不中断。把这三样东西放在一起本质上就是在解决一个问题当你要同时管理多个 AI 编程助手、多套配置、多个并行任务时怎么让它们不打架、不丢状态、不重复劳动。我自己在实际使用中深有体会。最早我只是单独跑一个 Claude Code配置简单改改 YAML 就能用。后来开始同时用 Codex 做代码审查、用 Claude Code 做重构问题就来了两个工具抢终端、配置文件互相覆盖、会话一关就丢上下文、切换模型要手动改一堆参数。这时候你需要的不是再装一个工具而是一套装配规范——把工具、配置、会话、任务按统一的方式组织起来。openrig 要做的我理解就是这件事。提示openrig 目前公开资料极少本文基于标题语义、关联热词和同类工具的通用实践进行合理推演重点在于把多 AI 编程助手协同工作流这件事讲透具体命令和配置请以你实际拿到的版本为准。这篇文章适合三类人看一是刚开始接触 Claude Code 或 Codex、还在被 YAML 配置折磨的新手二是已经在用但被多工具切换、会话丢失、配置冲突搞烦了的进阶用户三是想搭一套可复用、可迁移的 AI 编程环境、不想每次换机器都重来一遍的工程型选手。下面我会从核心概念、配置体系、会话管理、实操步骤、踩坑经验几个维度把 openrig 这类方案该有的样子完整拆一遍。2. openrig 的核心构成工具、配置、会话三层结构要理解 openrig 这类方案先得把它的三层结构拆开看。很多人一上来就急着敲命令结果配置改乱了、会话丢了、工具冲突了回头还得重装。我建议先把这三层的关系理清楚后面操作会顺很多。2.1 工具层Claude Code 与 Codex 的角色分工Claude Code 和 Codex 虽然都是 AI 编程助手但它们的定位和使用习惯其实有差异。Claude Code 更偏向对话式编程——你在终端里跟它聊它帮你读代码、改文件、跑命令交互感强适合探索性任务和重构。Codex 更偏向任务式执行——你给它一个明确目标它去完成适合批量处理、代码审查、生成测试这类结构化工作。在实际工作流里我通常这样分工工具典型场景交互特点配置重点Claude Code代码重构、架构讨论、调试排查多轮对话、上下文长模型端点、上下文长度、工具权限Codex代码审查、测试生成、批量修改单次任务、结果导向认证方式、任务模板、输出格式openrig 在工具层的价值就是让这两个工具共存而不冲突。具体来说它需要解决几个问题两个工具的命令别名不能撞车各自的配置目录要隔离认证信息要分开管理日志和会话记录要能区分来源。这些看起来是小事但真到多工具并行的时候一个别名冲突就能让你排查半小时。2.2 配置层YAML 作为统一描述语言YAML 出现在热搜词里不是偶然。Claude Code 和 Codex 的配置基本都是 YAML 格式因为它可读性好、层级清晰、支持注释比 JSON 适合手写比 TOML 表达力强。openrig 如果要做统一配置管理YAML 几乎是必然选择。一个典型的 AI 编程助手配置通常包含这几块# 模型与端点配置 model: provider: anthropic name: claude-sonnet endpoint: https://api.example.com/v1 max_tokens: 200000 # 工具权限配置 tools: allow_file_write: true allow_shell: true allowed_paths: - ./src - ./tests # 会话配置 session: persist: true history_dir: ~/.openrig/sessions max_history: 100这里有几个容易踩的坑。第一endpoint的写法各家不一样有的要带/v1有的不带写错了就是 404 或者认证失败。第二max_tokens不是越大越好超过模型实际支持的上限会直接报错而且有些端点对上下文长度有限制。第三allowed_paths如果配得太宽AI 可能改到你不想让它碰的文件配得太窄它又干不了活。我的经验是从最小权限开始按需放开而不是一上来就全开。2.3 会话层tmux 撑起的持久化工作台tmux 出现在这里说明 openrig 的会话管理是建立在终端复用之上的。为什么不用普通的终端窗口因为 AI 编程任务经常是长任务——一次重构可能跑十几分钟一次代码审查可能涉及几十个文件。如果终端一关任务就断那体验是灾难性的。tmux 解决的就是这个问题它让会话与终端窗口解耦。你关掉窗口会话还在后台跑你换台机器连上来attach 回去就能看到进度。对于 openrig 这类多工具协同的场景tmux 还能做到一个窗口管理多个工具会话# 创建一个名为 openrig 的会话 tmux new -s openrig # 在会话内分屏左边跑 Claude Code右边跑 Codex # Ctrlb % 垂直分屏 # Ctrlb 水平分屏 # 脱离会话任务继续在后台跑 # Ctrlb d # 重新连接 tmux attach -t openrig这套组合下来你的工作台就变成了一个 tmux 会话里面若干分屏每个分屏跑一个 AI 工具或一个任务配置由 YAML 统一管理会话状态持久保存。这就是 openrig 这类方案想达到的效果。3. 配置文件的写法与常见报错排查配置是 openrig 这类方案最容易出问题的地方也是新手最容易卡住的地方。我见过太多人因为一个缩进、一个字段名、一个端点地址写错折腾半天以为工具坏了。这一节我把配置的写法、校验方法和常见报错拆开讲。3.1 YAML 配置的字段设计与缩进陷阱YAML 对缩进极其敏感而且不允许用 Tab只能用空格。这是新手第一大坑。我建议统一用 2 个空格缩进并且在编辑器里开启显示空白字符这样能一眼看出是空格还是 Tab。一个完整的 openrig 风格配置我通常会这样组织version: 1 profiles: default: tool: claude-code model: provider: anthropic name: claude-sonnet endpoint: https://api.example.com max_tokens: 200000 session: persist: true dir: ~/.openrig/sessions/default review: tool: codex model: provider: openai name: gpt-codex endpoint: https://api.example.com max_tokens: 128000 session: persist: false dir: ~/.openrig/sessions/review active_profile: default这里profiles下面挂了多个配置档每个档对应一个工具和一套参数active_profile指定当前用哪个。这种设计的好处是你可以在不同任务之间快速切换不用每次手动改参数。比如做重构时切到default做代码审查时切到review。字段命名上我建议保持一致性。max_tokens不要一会儿写成maxTokens一会儿写成max_tokensYAML 是大小写敏感的写错了就是静默失效或者直接报错。endpoint的末尾不要多加斜杠很多 API 对/v1和/v1/的处理不一样。3.2 端点与认证那些让人抓狂的 401 和 404配置里最容易出问题的就是端点endpoint和认证auth。热搜词里出现了cc switch local proxy failed while handling codex endpoint /responses和codex auth token is unavailable这两个报错我太熟悉了。auth token is unavailable的意思是工具找不到认证令牌。可能的原因有几个环境变量没设置或者设置的名字不对令牌过期了配置文件里引用的环境变量名拼错了令牌文件权限不对工具读不到。排查顺序我一般是这样的先确认环境变量存在echo $YOUR_API_KEY看有没有输出确认变量名和配置里引用的一致注意大小写确认令牌没过期重新生成一个试试确认文件权限chmod 600一下。local proxy failed while handling endpoint /responses这类报错通常是本地代理层的问题。可能是代理没启动、端口被占用、或者请求路径和代理配置不匹配。我的做法是先用curl直接打端点确认网络和认证没问题再让工具走代理。这样能把问题范围缩小到是工具配置问题还是是网络/代理问题。注意排查端点问题时永远先用最原始的方式curl 或浏览器验证端点可达再去查工具配置。跳过这一步你会在配置里绕很久。3.3 配置校验写完之后先别急着跑配置写完别急着启动工具。先做几步校验能省掉大量返工。第一步用 YAML 解析器验证语法python3 -c import yaml; yaml.safe_load(open(config.yaml))没报错说明语法没问题。第二步检查关键字段是否齐全我一般会写个小脚本import yaml required [version, profiles, active_profile] cfg yaml.safe_load(open(config.yaml)) for key in required: assert key in cfg, f缺少字段: {key} active cfg[active_profile] assert active in cfg[profiles], factive_profile {active} 不存在 print(配置校验通过)第三步确认引用的路径都存在比如session.dir指向的目录、allowed_paths里的路径。路径不存在的话有的工具会自动创建有的会直接报错行为不一致最好提前确认。4. 用 tmux 把多工具会话管起来配置搞定之后接下来就是怎么把 Claude Code、Codex 这些工具在 tmux 里组织起来。这一节讲的是工作台搭建是 openrig 这类方案真正提升效率的地方。4.1 会话布局一个窗口装下所有工具我的习惯是建一个主会话然后按任务类型分窗口。比如# 创建主会话 tmux new -s openrig -n main # 新建窗口跑 Claude Code tmux new-window -t openrig -n claude # 新建窗口跑 Codex tmux new-window -t openrig -n codex # 新建窗口看日志 tmux new-window -t openrig -n logs这样openrig会话下有四个窗口main放通用命令claude跑 Claude Codecodex跑 Codexlogs看输出。切换用Ctrlb加窗口号非常快。如果某个任务需要同时看两个工具的输出可以在一个窗口里分屏# 在 claude 窗口里垂直分屏 tmux split-window -h -t openrig:claude # 左边跑 Claude Code右边跑 Codex分屏的好处是上下文不丢。你在左边跟 Claude Code 讨论重构方案右边 Codex 在跑代码审查两边互不干扰但都在同一个视野里。4.2 会话持久化关掉终端任务也不断tmux 最大的价值就是会话持久化。你Ctrlb d脱离会话任务继续在后台跑你关掉 SSH 连接任务还在你换台机器重新连上来tmux attach -t openrig就回到原来的状态。这对 AI 编程任务特别重要。因为一次重构、一次批量修改可能跑很久你不可能一直盯着。我的做法是启动长任务后直接脱离会话去干别的事过一会儿 attach 回来看结果。有个细节要注意tmux 会话默认不会在系统重启后保留。如果你需要跨重启持久化得配合tmux-resurrect这类插件或者把关键状态写到文件里。openrig 如果做了会话管理应该会在 YAML 里配置session.persist和session.dir把会话记录落盘。4.3 多工具并行的资源与冲突管理同时跑多个 AI 工具资源冲突是绕不开的。我遇到过几种典型情况端口冲突两个工具都想用同一个本地端口做代理结果后启动的失败配置目录冲突两个工具默认读同一个配置目录互相覆盖认证冲突两个工具用同一个环境变量名但需要不同的令牌CPU/内存争抢同时跑大任务机器卡死。openrig 这类方案要解决的就是把这些冲突在配置层就隔离掉。具体做法冲突类型隔离方案端口每个 profile 指定不同端口配置目录每个 profile 独立config_dir认证每个 profile 引用不同环境变量名资源限制并发任务数错峰执行我在实际使用中的经验是不要贪多。同时跑两个大任务机器就吃不消了而且你自己也看不过来。一般一个主任务加一个轻量任务比如代码审查就够了。5. 从零搭一套 openrig 风格工作流的完整步骤前面讲的是原理和结构这一节给一套可以直接抄的步骤。假设你在一台干净的 Linux 或 macOS 机器上从零开始搭。5.1 环境准备与依赖安装先装基础依赖。tmux 是必须的Python 用来做配置校验git 用来管理配置版本。# Ubuntu/Debian sudo apt update sudo apt install -y tmux python3 python3-pip git # macOS brew install tmux python3 git然后装 YAML 解析库pip3 install pyyaml接着装 Claude Code 和 Codex。这两个工具的安装方式各家版本不一样常见的是通过包管理器或者官方脚本。装完之后确认命令可用claude --version codex --version如果命令找不到检查 PATH 有没有包含安装目录。这一步看着简单但很多人卡在这里以为是安装失败其实是 PATH 没配。5.2 目录结构与配置初始化我建议建一个统一的工作目录把所有配置、会话、日志都放进去mkdir -p ~/.openrig/{config,sessions,logs} cd ~/.openrig然后在config下建主配置文件openrig.yaml内容参考第 3 节的示例。建好之后跑一遍校验脚本确认语法和字段都没问题。目录结构大概长这样~/.openrig/ ├── config/ │ └── openrig.yaml ├── sessions/ │ ├── default/ │ └── review/ └── logs/ ├── claude.log └── codex.log这种结构的好处是清晰配置、会话、日志各归各的备份的时候整个目录打包带走就行换机器直接恢复。5.3 启动脚本与一键拉起手动敲一堆命令太累我一般会写个启动脚本#!/bin/bash # ~/.openrig/start.sh SESSIONopenrig # 如果会话已存在直接 attach if tmux has-session -t $SESSION 2/dev/null; then tmux attach -t $SESSION exit 0 fi # 创建会话和窗口 tmux new-session -d -s $SESSION -n main tmux new-window -t $SESSION -n claude tmux new-window -t $SESSION -n codex tmux new-window -t $SESSION -n logs # 在对应窗口启动工具 tmux send-keys -t $SESSION:claude claude C-m tmux send-keys -t $SESSION:codex codex C-m # attach 到主窗口 tmux select-window -t $SESSION:main tmux attach -t $SESSION给脚本加执行权限chmod x ~/.openrig/start.sh以后每次开工只要跑~/.openrig/start.sh整个工作台就起来了。这个脚本我用了很久实测下来很稳尤其是会话已存在就直接 attach这个判断避免了重复创建。5.4 验证跑通第一个任务环境搭好之后跑个简单任务验证一下。在claude窗口里让它读一个文件、改一行代码看能不能正常执行。在codex窗口里让它审查一个文件看输出是否正常。验证的时候重点看几件事工具能不能正常认证不报 401能不能读到配置文件不报配置错误会话记录有没有落盘sessions目录下有没有新文件日志有没有正常写入logs目录下有没有内容。这四件事都正常说明工作流跑通了。有一件不对就回到对应章节排查。6. 实操中踩过的坑与经验总结这一节是我自己用下来最有价值的部分都是文档里不会写、但实际会遇到的坑。6.1 配置热更新的坑改了不生效怎么办很多人改完 YAML 配置直接重启工具结果发现改动没生效。原因通常是工具在启动时把配置读进内存了运行中不会重新读。解决办法有两个一是改完配置后完全退出工具再启动二是看工具支不支持热重载信号比如SIGHUP。我自己的习惯是改配置前先脱离 tmux 会话改完再重新 attach 并重启工具。这样能确保读到的是最新配置。另外有些工具会缓存配置到临时目录改完不生效的时候清一下缓存目录试试。6.2 会话丢失的几种典型场景会话丢失是最让人崩溃的。我遇到过几种tmux 会话被系统清理有些系统会定期清理长时间不活跃的会话或者重启后会话全没工具自己崩了AI 工具跑大任务时内存爆了进程被杀会话状态没保存误操作 kill 了会话手滑tmux kill-session全没了。应对办法重要任务开始前先确认session.persist开着会话目录有写权限长任务定期检查进度别等跑完才发现崩了给 tmux 会话起明确的名字别用默认的0、1避免误杀。6.3 多工具切换时的认证串号问题这个坑很隐蔽。你同时配了 Claude Code 和 Codex如果它们用同一个环境变量名存令牌切换工具的时候可能读到对方的令牌导致认证失败或者更糟——用错账号跑了任务。我的做法是每个工具用独立的环境变量名。比如 Claude Code 用CLAUDE_API_KEYCodex 用CODEX_API_KEY配置里明确引用各自的变量。这样即使两个工具同时跑也不会串号。提示如果你发现切换工具后报认证错误第一件事就是检查环境变量有没有串。这个坑我踩过排查了半天才发现是变量名撞了。6.4 长任务的中断与恢复策略AI 编程任务跑一半中断了怎么恢复这取决于工具本身支不支持断点续跑。如果不支持我的策略是把大任务拆成小任务每个小任务独立可跑中断了只重跑当前小任务不用从头来。具体做法是在配置里定义任务模板每个模板对应一个可独立执行的小任务。比如重构任务拆成读代码生成方案应用修改验证四步每步单独跑结果落盘。这样即使中断也能从落盘的结果继续。这套策略用下来长任务的可靠性提升很多。虽然前期拆任务麻烦一点但比起跑一半崩了从头来还是划算的。7. 关于 openrig 后续可以怎么扩展openrig 这类方案的价值在于可装配所以它的扩展空间很大。我自己在用的过程中往几个方向做过延伸分享出来供参考。第一个方向是配置版本化。把~/.openrig/config用 git 管起来每次改配置都提交出问题了直接回滚。这个习惯帮我省了好几次重装的时间。第二个方向是任务模板库。把常用的任务代码审查、测试生成、重构做成模板放在配置目录下需要的时候直接引用。这样不用每次重新描述任务效率高很多。第三个方向是日志聚合。多个工具的日志分散在不同文件里排查问题时来回翻很麻烦。我写了个小脚本把日志按时间合并出问题的时候一眼就能看到哪个工具在什么时候报了什么错。第四个方向是跨机器同步。把整个~/.openrig目录同步到多台机器配置、会话、模板都跟着走换机器不用重新搭。这个用 git 或者同步工具都能做关键是目录结构要设计好别把机器相关的路径写死在配置里。这些扩展都不复杂但组合起来能让整套工作流顺手很多。openrig 本身如果做了这些事那它就不只是一个配置工具而是一套完整的 AI 编程工作台方案。我在实际使用中的体会是工具本身的功能是一方面更重要的是你围绕它建立起来的工作习惯和目录规范那才是真正提升效率的东西。
openrig 多AI编程助手协同工作流：Claude Code与Codex的YAML配置与tmux会话管理
1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的不是某个具体工具而是一种把散装零件拼成一台整机的直觉。rig 在英文里本意是装配、索具、钻井平台在工程语境里常指把一堆独立部件按某种规范组装成一套可运转的系统。前面加个 open意思就很明确了这是一套开放的、可自定义的装配方案而不是一个封闭的黑盒产品。结合热搜词里高频出现的 Claude Code、Codex、YAML、tmux 这几个关键词我基本能判断出 openrig 的定位——它大概率是一套围绕 AI 编程助手Claude Code、Codex 这类 CLI 工具的工作流编排与配置管理方案。为什么这么说因为这几个词凑在一起指向的是一个非常具体的痛点场景Claude Code 和 Codex 都是命令行形态的 AI 编程助手各自有独立的配置体系、认证方式、会话管理逻辑YAML 是它们最常用的配置文件格式用来定义模型、端点、权限、工具链tmux 是终端复用器用来在多个会话之间切换、保持长任务不中断。把这三样东西放在一起本质上就是在解决一个问题当你要同时管理多个 AI 编程助手、多套配置、多个并行任务时怎么让它们不打架、不丢状态、不重复劳动。我自己在实际使用中深有体会。最早我只是单独跑一个 Claude Code配置简单改改 YAML 就能用。后来开始同时用 Codex 做代码审查、用 Claude Code 做重构问题就来了两个工具抢终端、配置文件互相覆盖、会话一关就丢上下文、切换模型要手动改一堆参数。这时候你需要的不是再装一个工具而是一套装配规范——把工具、配置、会话、任务按统一的方式组织起来。openrig 要做的我理解就是这件事。提示openrig 目前公开资料极少本文基于标题语义、关联热词和同类工具的通用实践进行合理推演重点在于把多 AI 编程助手协同工作流这件事讲透具体命令和配置请以你实际拿到的版本为准。这篇文章适合三类人看一是刚开始接触 Claude Code 或 Codex、还在被 YAML 配置折磨的新手二是已经在用但被多工具切换、会话丢失、配置冲突搞烦了的进阶用户三是想搭一套可复用、可迁移的 AI 编程环境、不想每次换机器都重来一遍的工程型选手。下面我会从核心概念、配置体系、会话管理、实操步骤、踩坑经验几个维度把 openrig 这类方案该有的样子完整拆一遍。2. openrig 的核心构成工具、配置、会话三层结构要理解 openrig 这类方案先得把它的三层结构拆开看。很多人一上来就急着敲命令结果配置改乱了、会话丢了、工具冲突了回头还得重装。我建议先把这三层的关系理清楚后面操作会顺很多。2.1 工具层Claude Code 与 Codex 的角色分工Claude Code 和 Codex 虽然都是 AI 编程助手但它们的定位和使用习惯其实有差异。Claude Code 更偏向对话式编程——你在终端里跟它聊它帮你读代码、改文件、跑命令交互感强适合探索性任务和重构。Codex 更偏向任务式执行——你给它一个明确目标它去完成适合批量处理、代码审查、生成测试这类结构化工作。在实际工作流里我通常这样分工工具典型场景交互特点配置重点Claude Code代码重构、架构讨论、调试排查多轮对话、上下文长模型端点、上下文长度、工具权限Codex代码审查、测试生成、批量修改单次任务、结果导向认证方式、任务模板、输出格式openrig 在工具层的价值就是让这两个工具共存而不冲突。具体来说它需要解决几个问题两个工具的命令别名不能撞车各自的配置目录要隔离认证信息要分开管理日志和会话记录要能区分来源。这些看起来是小事但真到多工具并行的时候一个别名冲突就能让你排查半小时。2.2 配置层YAML 作为统一描述语言YAML 出现在热搜词里不是偶然。Claude Code 和 Codex 的配置基本都是 YAML 格式因为它可读性好、层级清晰、支持注释比 JSON 适合手写比 TOML 表达力强。openrig 如果要做统一配置管理YAML 几乎是必然选择。一个典型的 AI 编程助手配置通常包含这几块# 模型与端点配置 model: provider: anthropic name: claude-sonnet endpoint: https://api.example.com/v1 max_tokens: 200000 # 工具权限配置 tools: allow_file_write: true allow_shell: true allowed_paths: - ./src - ./tests # 会话配置 session: persist: true history_dir: ~/.openrig/sessions max_history: 100这里有几个容易踩的坑。第一endpoint的写法各家不一样有的要带/v1有的不带写错了就是 404 或者认证失败。第二max_tokens不是越大越好超过模型实际支持的上限会直接报错而且有些端点对上下文长度有限制。第三allowed_paths如果配得太宽AI 可能改到你不想让它碰的文件配得太窄它又干不了活。我的经验是从最小权限开始按需放开而不是一上来就全开。2.3 会话层tmux 撑起的持久化工作台tmux 出现在这里说明 openrig 的会话管理是建立在终端复用之上的。为什么不用普通的终端窗口因为 AI 编程任务经常是长任务——一次重构可能跑十几分钟一次代码审查可能涉及几十个文件。如果终端一关任务就断那体验是灾难性的。tmux 解决的就是这个问题它让会话与终端窗口解耦。你关掉窗口会话还在后台跑你换台机器连上来attach 回去就能看到进度。对于 openrig 这类多工具协同的场景tmux 还能做到一个窗口管理多个工具会话# 创建一个名为 openrig 的会话 tmux new -s openrig # 在会话内分屏左边跑 Claude Code右边跑 Codex # Ctrlb % 垂直分屏 # Ctrlb 水平分屏 # 脱离会话任务继续在后台跑 # Ctrlb d # 重新连接 tmux attach -t openrig这套组合下来你的工作台就变成了一个 tmux 会话里面若干分屏每个分屏跑一个 AI 工具或一个任务配置由 YAML 统一管理会话状态持久保存。这就是 openrig 这类方案想达到的效果。3. 配置文件的写法与常见报错排查配置是 openrig 这类方案最容易出问题的地方也是新手最容易卡住的地方。我见过太多人因为一个缩进、一个字段名、一个端点地址写错折腾半天以为工具坏了。这一节我把配置的写法、校验方法和常见报错拆开讲。3.1 YAML 配置的字段设计与缩进陷阱YAML 对缩进极其敏感而且不允许用 Tab只能用空格。这是新手第一大坑。我建议统一用 2 个空格缩进并且在编辑器里开启显示空白字符这样能一眼看出是空格还是 Tab。一个完整的 openrig 风格配置我通常会这样组织version: 1 profiles: default: tool: claude-code model: provider: anthropic name: claude-sonnet endpoint: https://api.example.com max_tokens: 200000 session: persist: true dir: ~/.openrig/sessions/default review: tool: codex model: provider: openai name: gpt-codex endpoint: https://api.example.com max_tokens: 128000 session: persist: false dir: ~/.openrig/sessions/review active_profile: default这里profiles下面挂了多个配置档每个档对应一个工具和一套参数active_profile指定当前用哪个。这种设计的好处是你可以在不同任务之间快速切换不用每次手动改参数。比如做重构时切到default做代码审查时切到review。字段命名上我建议保持一致性。max_tokens不要一会儿写成maxTokens一会儿写成max_tokensYAML 是大小写敏感的写错了就是静默失效或者直接报错。endpoint的末尾不要多加斜杠很多 API 对/v1和/v1/的处理不一样。3.2 端点与认证那些让人抓狂的 401 和 404配置里最容易出问题的就是端点endpoint和认证auth。热搜词里出现了cc switch local proxy failed while handling codex endpoint /responses和codex auth token is unavailable这两个报错我太熟悉了。auth token is unavailable的意思是工具找不到认证令牌。可能的原因有几个环境变量没设置或者设置的名字不对令牌过期了配置文件里引用的环境变量名拼错了令牌文件权限不对工具读不到。排查顺序我一般是这样的先确认环境变量存在echo $YOUR_API_KEY看有没有输出确认变量名和配置里引用的一致注意大小写确认令牌没过期重新生成一个试试确认文件权限chmod 600一下。local proxy failed while handling endpoint /responses这类报错通常是本地代理层的问题。可能是代理没启动、端口被占用、或者请求路径和代理配置不匹配。我的做法是先用curl直接打端点确认网络和认证没问题再让工具走代理。这样能把问题范围缩小到是工具配置问题还是是网络/代理问题。注意排查端点问题时永远先用最原始的方式curl 或浏览器验证端点可达再去查工具配置。跳过这一步你会在配置里绕很久。3.3 配置校验写完之后先别急着跑配置写完别急着启动工具。先做几步校验能省掉大量返工。第一步用 YAML 解析器验证语法python3 -c import yaml; yaml.safe_load(open(config.yaml))没报错说明语法没问题。第二步检查关键字段是否齐全我一般会写个小脚本import yaml required [version, profiles, active_profile] cfg yaml.safe_load(open(config.yaml)) for key in required: assert key in cfg, f缺少字段: {key} active cfg[active_profile] assert active in cfg[profiles], factive_profile {active} 不存在 print(配置校验通过)第三步确认引用的路径都存在比如session.dir指向的目录、allowed_paths里的路径。路径不存在的话有的工具会自动创建有的会直接报错行为不一致最好提前确认。4. 用 tmux 把多工具会话管起来配置搞定之后接下来就是怎么把 Claude Code、Codex 这些工具在 tmux 里组织起来。这一节讲的是工作台搭建是 openrig 这类方案真正提升效率的地方。4.1 会话布局一个窗口装下所有工具我的习惯是建一个主会话然后按任务类型分窗口。比如# 创建主会话 tmux new -s openrig -n main # 新建窗口跑 Claude Code tmux new-window -t openrig -n claude # 新建窗口跑 Codex tmux new-window -t openrig -n codex # 新建窗口看日志 tmux new-window -t openrig -n logs这样openrig会话下有四个窗口main放通用命令claude跑 Claude Codecodex跑 Codexlogs看输出。切换用Ctrlb加窗口号非常快。如果某个任务需要同时看两个工具的输出可以在一个窗口里分屏# 在 claude 窗口里垂直分屏 tmux split-window -h -t openrig:claude # 左边跑 Claude Code右边跑 Codex分屏的好处是上下文不丢。你在左边跟 Claude Code 讨论重构方案右边 Codex 在跑代码审查两边互不干扰但都在同一个视野里。4.2 会话持久化关掉终端任务也不断tmux 最大的价值就是会话持久化。你Ctrlb d脱离会话任务继续在后台跑你关掉 SSH 连接任务还在你换台机器重新连上来tmux attach -t openrig就回到原来的状态。这对 AI 编程任务特别重要。因为一次重构、一次批量修改可能跑很久你不可能一直盯着。我的做法是启动长任务后直接脱离会话去干别的事过一会儿 attach 回来看结果。有个细节要注意tmux 会话默认不会在系统重启后保留。如果你需要跨重启持久化得配合tmux-resurrect这类插件或者把关键状态写到文件里。openrig 如果做了会话管理应该会在 YAML 里配置session.persist和session.dir把会话记录落盘。4.3 多工具并行的资源与冲突管理同时跑多个 AI 工具资源冲突是绕不开的。我遇到过几种典型情况端口冲突两个工具都想用同一个本地端口做代理结果后启动的失败配置目录冲突两个工具默认读同一个配置目录互相覆盖认证冲突两个工具用同一个环境变量名但需要不同的令牌CPU/内存争抢同时跑大任务机器卡死。openrig 这类方案要解决的就是把这些冲突在配置层就隔离掉。具体做法冲突类型隔离方案端口每个 profile 指定不同端口配置目录每个 profile 独立config_dir认证每个 profile 引用不同环境变量名资源限制并发任务数错峰执行我在实际使用中的经验是不要贪多。同时跑两个大任务机器就吃不消了而且你自己也看不过来。一般一个主任务加一个轻量任务比如代码审查就够了。5. 从零搭一套 openrig 风格工作流的完整步骤前面讲的是原理和结构这一节给一套可以直接抄的步骤。假设你在一台干净的 Linux 或 macOS 机器上从零开始搭。5.1 环境准备与依赖安装先装基础依赖。tmux 是必须的Python 用来做配置校验git 用来管理配置版本。# Ubuntu/Debian sudo apt update sudo apt install -y tmux python3 python3-pip git # macOS brew install tmux python3 git然后装 YAML 解析库pip3 install pyyaml接着装 Claude Code 和 Codex。这两个工具的安装方式各家版本不一样常见的是通过包管理器或者官方脚本。装完之后确认命令可用claude --version codex --version如果命令找不到检查 PATH 有没有包含安装目录。这一步看着简单但很多人卡在这里以为是安装失败其实是 PATH 没配。5.2 目录结构与配置初始化我建议建一个统一的工作目录把所有配置、会话、日志都放进去mkdir -p ~/.openrig/{config,sessions,logs} cd ~/.openrig然后在config下建主配置文件openrig.yaml内容参考第 3 节的示例。建好之后跑一遍校验脚本确认语法和字段都没问题。目录结构大概长这样~/.openrig/ ├── config/ │ └── openrig.yaml ├── sessions/ │ ├── default/ │ └── review/ └── logs/ ├── claude.log └── codex.log这种结构的好处是清晰配置、会话、日志各归各的备份的时候整个目录打包带走就行换机器直接恢复。5.3 启动脚本与一键拉起手动敲一堆命令太累我一般会写个启动脚本#!/bin/bash # ~/.openrig/start.sh SESSIONopenrig # 如果会话已存在直接 attach if tmux has-session -t $SESSION 2/dev/null; then tmux attach -t $SESSION exit 0 fi # 创建会话和窗口 tmux new-session -d -s $SESSION -n main tmux new-window -t $SESSION -n claude tmux new-window -t $SESSION -n codex tmux new-window -t $SESSION -n logs # 在对应窗口启动工具 tmux send-keys -t $SESSION:claude claude C-m tmux send-keys -t $SESSION:codex codex C-m # attach 到主窗口 tmux select-window -t $SESSION:main tmux attach -t $SESSION给脚本加执行权限chmod x ~/.openrig/start.sh以后每次开工只要跑~/.openrig/start.sh整个工作台就起来了。这个脚本我用了很久实测下来很稳尤其是会话已存在就直接 attach这个判断避免了重复创建。5.4 验证跑通第一个任务环境搭好之后跑个简单任务验证一下。在claude窗口里让它读一个文件、改一行代码看能不能正常执行。在codex窗口里让它审查一个文件看输出是否正常。验证的时候重点看几件事工具能不能正常认证不报 401能不能读到配置文件不报配置错误会话记录有没有落盘sessions目录下有没有新文件日志有没有正常写入logs目录下有没有内容。这四件事都正常说明工作流跑通了。有一件不对就回到对应章节排查。6. 实操中踩过的坑与经验总结这一节是我自己用下来最有价值的部分都是文档里不会写、但实际会遇到的坑。6.1 配置热更新的坑改了不生效怎么办很多人改完 YAML 配置直接重启工具结果发现改动没生效。原因通常是工具在启动时把配置读进内存了运行中不会重新读。解决办法有两个一是改完配置后完全退出工具再启动二是看工具支不支持热重载信号比如SIGHUP。我自己的习惯是改配置前先脱离 tmux 会话改完再重新 attach 并重启工具。这样能确保读到的是最新配置。另外有些工具会缓存配置到临时目录改完不生效的时候清一下缓存目录试试。6.2 会话丢失的几种典型场景会话丢失是最让人崩溃的。我遇到过几种tmux 会话被系统清理有些系统会定期清理长时间不活跃的会话或者重启后会话全没工具自己崩了AI 工具跑大任务时内存爆了进程被杀会话状态没保存误操作 kill 了会话手滑tmux kill-session全没了。应对办法重要任务开始前先确认session.persist开着会话目录有写权限长任务定期检查进度别等跑完才发现崩了给 tmux 会话起明确的名字别用默认的0、1避免误杀。6.3 多工具切换时的认证串号问题这个坑很隐蔽。你同时配了 Claude Code 和 Codex如果它们用同一个环境变量名存令牌切换工具的时候可能读到对方的令牌导致认证失败或者更糟——用错账号跑了任务。我的做法是每个工具用独立的环境变量名。比如 Claude Code 用CLAUDE_API_KEYCodex 用CODEX_API_KEY配置里明确引用各自的变量。这样即使两个工具同时跑也不会串号。提示如果你发现切换工具后报认证错误第一件事就是检查环境变量有没有串。这个坑我踩过排查了半天才发现是变量名撞了。6.4 长任务的中断与恢复策略AI 编程任务跑一半中断了怎么恢复这取决于工具本身支不支持断点续跑。如果不支持我的策略是把大任务拆成小任务每个小任务独立可跑中断了只重跑当前小任务不用从头来。具体做法是在配置里定义任务模板每个模板对应一个可独立执行的小任务。比如重构任务拆成读代码生成方案应用修改验证四步每步单独跑结果落盘。这样即使中断也能从落盘的结果继续。这套策略用下来长任务的可靠性提升很多。虽然前期拆任务麻烦一点但比起跑一半崩了从头来还是划算的。7. 关于 openrig 后续可以怎么扩展openrig 这类方案的价值在于可装配所以它的扩展空间很大。我自己在用的过程中往几个方向做过延伸分享出来供参考。第一个方向是配置版本化。把~/.openrig/config用 git 管起来每次改配置都提交出问题了直接回滚。这个习惯帮我省了好几次重装的时间。第二个方向是任务模板库。把常用的任务代码审查、测试生成、重构做成模板放在配置目录下需要的时候直接引用。这样不用每次重新描述任务效率高很多。第三个方向是日志聚合。多个工具的日志分散在不同文件里排查问题时来回翻很麻烦。我写了个小脚本把日志按时间合并出问题的时候一眼就能看到哪个工具在什么时候报了什么错。第四个方向是跨机器同步。把整个~/.openrig目录同步到多台机器配置、会话、模板都跟着走换机器不用重新搭。这个用 git 或者同步工具都能做关键是目录结构要设计好别把机器相关的路径写死在配置里。这些扩展都不复杂但组合起来能让整套工作流顺手很多。openrig 本身如果做了这些事那它就不只是一个配置工具而是一套完整的 AI 编程工作台方案。我在实际使用中的体会是工具本身的功能是一方面更重要的是你围绕它建立起来的工作习惯和目录规范那才是真正提升效率的东西。
