openrig 装配指南：Claude Code 与 Codex 的 YAML 配置和 tmux 会话管理

1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“成套装置”“装配好的工作台”比如一台调试好的机器、一套搭好的实验设备。把它放到当下 AI 编程助手的使用场景里我的理解是openrig 想做的是一套开放的、可自由装配的 AI 编码工作台把 Claude Code、Codex 这类命令行智能体连同 YAML 配置、tmux 会话管理这些零散零件组装成一个稳定、可复用、可迁移的开发环境。为什么会有这个需求因为现在用 Claude Code 或 Codex 的人几乎都经历过同一个痛点环境是散的。模型配置散在几个 JSON 里会话管理靠手动开终端任务编排靠脑子记换一台机器就得从头配一遍。你搜“claude code 安装”“codex 安装教程”“vscode 配置 claude code”这些词背后其实都是同一件事——大家想要一个能一次搭好、到处能用的工作台。openrig 这个标题虽然正文和关键词都是空的但从它关联的热搜词能看出它瞄准的正是“AI 编码助手的工程化装配”这个方向。这篇文章我不打算把它写成一份官方文档式的说明而是按一个真实搭过好几套这类环境的人的视角把 openrig 可能涉及的核心环节拆开讲它和 Claude Code、Codex 的关系YAML 在其中扮演什么角色tmux 为什么是绕不开的一环以及从零装配时最容易踩的坑。如果你正在折腾 Claude Code 或 Codex 的本地环境或者想把自己的 AI 编码流程从“能用”提升到“好用且可复制”这篇内容应该能帮你省下不少试错时间。需要先说明一点openrig 目前公开的细节有限下面涉及具体实现的部分我会基于这类工具常见的工程实践做合理推演并明确标注哪些是推断、哪些是通用做法。你照着搭的时候重点理解思路具体参数按自己环境调整。2. openrig 与 Claude Code、Codex 的装配关系2.1 为什么不是“装一个工具”而是“装一套装置”很多人对 Claude Code 和 Codex 的理解停留在“装个命令行工具登录就能用”。这个理解没错但只覆盖了最浅的一层。真正用起来你会发现一个能长期稳定干活的 AI 编码环境至少包含四个部分模型接入层、会话管理层、任务编排层、配置持久层。Claude Code 和 Codex 各自只解决了其中一部分剩下的得你自己拼。openrig 的价值就在于它试图把这四层统一到一个“装置”里。你可以把它想象成一个工具箱Claude Code 和 Codex 是里面的两把电动螺丝刀YAML 是贴在箱盖上的装配图纸tmux 是让多把工具同时干活的工作台。单独拿出一把螺丝刀也能拧螺丝但只有装进箱子、按图纸摆好、配上工作台你才能高效地批量干活。这个类比不是硬凑。我实测过只装 Claude Code 不配 tmux 的情况跑一个长任务时终端一关任务就断了想同时跑两个不同项目的分析得开两个终端窗口来回切上下文还容易串。后来把 tmux 加进来一个会话里分屏跑 Claude Code 和 Codex各自盯一个项目效率完全是两个量级。openrig 想固化的就是这种“装配好之后的状态”。2.2 Claude Code 和 Codex 在装置里的分工既然 openrig 同时关联了 Claude Code 和 Codex那它大概率不是二选一而是让两者协同。这两类工具虽然都是 AI 编码助手但脾气不一样适合的活也不一样。Claude Code 的强项在于长上下文理解和多文件重构。你给它一个稍大的代码库让它梳理调用链、做跨文件的重命名或重构它表现得比较稳。热搜里“claude code 1m 上下文”这个词能说明问题——大家就是冲着大上下文去的。而 Codex 这类工具在单点代码生成、快速补全、局部逻辑实现上响应更利落适合“给我把这个函数写出来”这种颗粒度的任务。在 openrig 的装配思路里合理的分工是用 Claude Code 做“规划与重构”用 Codex 做“执行与补全”。比如你要给一个老项目加新功能先用 Claude Code 通读相关模块、产出改动方案和影响范围再把具体的函数实现交给 Codex 快速生成最后回到 Claude Code 做一致性检查。这个流程我在几个中型项目上跑过比全程用单一工具要顺因为各自都在自己擅长的区间里干活。注意这种分工不是硬性规定。如果你的任务本身很单一比如就是写个脚本那用哪个都行没必要为了“装配”而装配。openrig 的意义在于当你任务复杂时有一套现成的协作框架可以套。2.3 装配关系里最容易被忽略的“接口层”Claude Code 和 Codex 要协同中间需要一个接口层来传递上下文。这个接口层在 openrig 里很可能就是 YAML 配置加一套约定的目录结构。为什么是 YAML 而不是别的因为 YAML 对人类友好缩进即层级写配置像写大纲改起来不用数括号。热搜里“yolov10 yaml 文件怎么创建”“rstudio 的 yaml 在哪里”这些词说明 YAML 已经是各类工具配置的通用语言openrig 顺着这个习惯走是合理的。接口层要解决的核心问题是当 Claude Code 产出一份改动方案后Codex 怎么知道该改哪些文件、按什么顺序改。如果靠人复制粘贴那装配就白做了。合理的做法是把任务描述、目标文件列表、约束条件写进一个 YAML 任务文件两个工具都读这个文件各自认领自己能干的部分。这样整个流程就是可追溯、可复现的换个人接手也能看懂当时是怎么跑的。3. YAML 在 openrig 里到底管什么3.1 配置文件、任务清单、还是两者兼有YAML 在 openrig 里的角色我倾向于认为它同时承担了配置和任务编排两个职责但分在不同的文件里。配置类的 YAML 管“环境长什么样”任务类的 YAML 管“这次要干什么”。把这两者分开很重要否则你改一次任务就得动一次环境配置容易把环境改坏。配置类 YAML 通常包含这些字段模型接入信息用哪个模型、走哪个端点、工具路径Claude Code 和 Codex 的可执行文件在哪、会话参数tmux 会话名、分屏布局、默认工作目录。任务类 YAML 则包含任务目标、涉及的文件或目录、执行步骤、验收标准。下面是一个我按常见实践整理的配置示例字段名是示意性的你按 openrig 实际文档调整# openrig 环境配置示意 workspace: root: ~/projects/myapp default_branch: main tools: claude_code: enabled: true model: claude-sonnet max_context: 200000 codex: enabled: true model: codex-default session: manager: tmux session_name: openrig-main layout: even-horizontal tasks: dir: ./tasks default_task: refactor-auth这个结构的好处是一眼能看出环境由哪几块组成。你要换模型只动tools段要换工作目录只动workspace段。互不干扰。3.2 为什么 YAML 的缩进陷阱在 openrig 里格外致命YAML 最大的坑就是缩进。用空格还是 Tab、缩进几个、层级对不对错一点整个文件就解析失败。在普通场景下这顶多是配置不生效但在 openrig 这种“配置驱动多工具协作”的场景里一个缩进错误可能导致 Claude Code 读到了任务、Codex 没读到结果一个工具在干活、另一个在空转你还以为是模型不响应。我踩过最典型的一次任务 YAML 里steps下面的列表项我用了两个空格缩进但同级另一个字段用了四个空格解析器把本该平级的两个步骤变成了嵌套关系执行顺序全乱了。排查了半天才发现是缩进不一致。所以我的经验是openrig 相关的 YAML 一律用两个空格缩进绝不用 Tab写完用python -c import yaml,sys; yaml.safe_load(open(sys.argv[1])) 文件路径先验证一遍再跑。这个命令能快速告诉你 YAML 是否合法比跑起来报错再回头找要快得多。提示如果你用 VS Code装一个 YAML 插件它会实时标红缩进和语法错误。热搜里“vscode 配置 claude code”和“vscode 安装 claude code”热度很高说明很多人本来就在 VS Code 里干活顺手把 YAML 校验也配上能省很多事。3.3 任务 YAML 怎么写才让两个工具都认任务 YAML 的设计要点是职责清晰。每个步骤要标明由哪个工具执行、输入是什么、输出放哪。这样 Claude Code 和 Codex 各读各的部分不会抢活也不会漏活。一个可参考的任务文件长这样task: refactor-auth-module description: 重构认证模块拆分过长的中间件函数 steps: - id: analyze tool: claude_code action: 通读 auth 目录产出重构方案和影响文件列表 output: ./out/analyze.md - id: implement tool: codex action: 按 analyze.md 的方案逐个文件改写 input: ./out/analyze.md output: ./out/implement.diff - id: verify tool: claude_code action: 检查 implement.diff 的一致性标记风险点 input: ./out/implement.diff output: ./out/verify.md这个结构里tool字段就是分工开关。analyze和verify交给 Claude Code因为它擅长理解和审查implement交给 Codex因为它擅长快速产出代码。input和output字段把步骤串成流水线前一步的产物是后一步的输入整个任务可追溯。实测下来这种写法的好处是任务中断后能续跑。比如implement跑到一半你发现方案有问题改完analyze.md重新触发Codex 会基于新方案重跑而不用从头再来。如果没有这个结构你得手动告诉工具“上次改到哪了”很容易漏。4. tmux 为什么是 openrig 绕不开的一环4.1 没有 tmux多工具协作就是空谈tmux 是一个终端复用器说人话就是它让你在一个终端窗口里开多个“虚拟终端”并且这些终端在你断开连接后还能继续跑。热搜里“tmux”单独作为一个词出现说明它已经是这类工作流的标配。为什么 openrig 离不开它因为 Claude Code 和 Codex 都是长时间运行的任务一个重构任务跑十几分钟很正常你不可能一直盯着终端不动。没有 tmux 的时候我的做法是开两个终端窗口一个跑 Claude Code 一个跑 Codex。问题是关掉窗口任务就没了想同时看两个的输出得来回切笔记本合盖再打开连接断了任务也断了。换成 tmux 之后一个会话里左右分屏左边 Claude Code 右边 Codex各自输出实时可见合盖再打开tmux attach一下全都在。这个体验差距是质的。openrig 把 tmux 纳入装配本质上是把“会话持久化”和“多任务并行”这两个能力固化下来。你不需要每次手动开分屏、起会话配置里写好布局一条命令拉起整个工作台。4.2 会话布局怎么设计才不打架tmux 的布局设计有个原则按任务阶段分屏而不是按工具分屏。新手容易犯的错是“左边永远放 Claude Code右边永远放 Codex”结果某个阶段只用得上一个工具另一个屏就空着浪费。更好的做法是按当前任务的需要动态调整。我常用的两种布局分析阶段上方一个大窗格跑 Claude Code 做代码通读下方一个小窗格跑tail -f盯日志或输出文件。这个阶段 Codex 用不上就不占屏。实现阶段左右等分左边 Codex 跑代码生成右边 Claude Code 待命做即时审查。两个都在干活分屏合理。在 openrig 的配置里这种动态布局可以通过预设几个布局模板来实现任务 YAML 里指定用哪个模板。比如layout: analyze对应上下分屏layout: implement对应左右分屏。这样切换任务时布局自动跟着变不用手动调。注意tmux 的窗格大小是可以用快捷键调的默认Ctrlb然后按方向键或Ctrlb加Alt方向键调整。分屏比例不合适时别硬扛顺手调一下长时间盯着不合适的比例眼睛很累。4.3 tmux 会话命名与恢复的实操细节tmux 会话如果不命名默认叫0、1这种数字时间一长你根本分不清哪个是哪个。openrig 场景下会话多命名必须规范。我的习惯是openrig-项目名-任务类型比如openrig-myapp-refactor。这样tmux ls一列出来一眼就知道每个会话在干嘛。恢复会话是 tmux 最实用的功能。你下班关电脑第二天上班tmux attach -t openrig-myapp-refactor昨天跑到一半的任务原样在那输出、光标位置、甚至正在跑的进程都还在。这个能力对长任务太重要了。但有个坑如果任务已经跑完会话还开着你 attach 进去看到的是静止的输出容易误以为还在跑。我的做法是任务跑完后在会话里留个明显的结束标记比如echo TASK DONE attach 进去一眼就能判断状态。另外tmux 会话不会因为你关终端就消失但机器重启会。所以如果你的任务特别长跨天的那种要么别关机要么把关键中间产物落到文件里重启后从文件恢复而不是指望 tmux 会话还在。5. 从零装配 openrig 的完整流程5.1 环境准备先把地基打平装配之前先把基础环境理清楚。这一步看着简单但坑最多。你需要确认的东西操作系统Linux、macOS 还是 Windows 下的 WSL、包管理器apt、brew 还是别的、Python 或 Node 运行时很多 AI 编码工具依赖它们、以及 tmux 本身。我建议按这个顺序来确认 shell 环境。echo $SHELL看当前用的是 bash 还是 zsh。openrig 的配置脚本通常假设某个 shell不一致时路径可能读不到。装 tmux。Linux 下sudo apt install tmuxmacOS 下brew install tmux。装完tmux -V验证版本太老的版本某些布局参数不支持。装 Claude Code 和 Codex。这两个的安装方式按各自官方指引来热搜里“claude code 安装”“codex 安装教程”“ubuntu 安装 claude code”“windows 安装 claude code”都是高频词说明跨平台安装是普遍需求。装完各自跑一下--version或--help确认可执行文件在 PATH 里。验证 YAML 解析能力。如果你用 Pythonpip install pyyaml用 Node 的话装js-yaml。openrig 读配置靠它。这一步最容易忽略的是PATH 问题。工具装完了但命令找不到八成是 PATH 没配。which claude和which codex能快速定位。如果找不到把安装目录加到~/.bashrc或~/.zshrc的 PATH 里然后source一下。5.2 配置文件的组织方式openrig 的配置文件建议按“环境配置”和“任务配置”分目录放别全堆在一个文件里。我的组织方式openrig/ ├── config/ │ ├── env.yaml # 环境配置工具路径、模型、会话参数 │ └── layouts.yaml # tmux 布局模板 ├── tasks/ │ ├── refactor-auth.yaml │ └── add-feature.yaml └── out/ # 任务产物统一放这这样分的好处是环境配置基本不动任务配置经常增删两者分开互不影响。out/目录统一放产物任务 YAML 里的output字段都指向这里找结果不用满硬盘翻。配置文件的加载顺序也要注意。通常 openrig 会先读env.yaml建立环境再读指定的任务 YAML。如果任务 YAML 里引用了环境里的变量比如工作目录要确保环境先加载。这个顺序在配置里写死别依赖运行时猜测。5.3 第一次跑通的最小验证别一上来就搞复杂任务。第一次跑通用一个最小任务验证整条链路让 Claude Code 读一个文件并输出摘要让 Codex 基于摘要改一行代码再让 Claude Code 检查改动。任务 YAML 就三步文件就一个。这个最小验证能帮你确认四件事YAML 解析对不对、两个工具能不能被正确调用、tmux 会话能不能正常起、产物能不能落到out/。四件事都过了再上真实任务。我见过太多人直接拿大项目试结果一个环节出错排查半天分不清是配置问题还是任务问题。最小验证就是用来隔离变量的。跑通之后把这次成功的配置和任务 YAML 存成模板。以后新项目直接复制模板改路径和任务描述几分钟就能搭好一套新环境。这就是 openrig 这种“装置化”思路最大的价值——把一次性的搭建变成可复制的模板。6. 装配过程中最容易踩的五个坑6.1 模型端点配置错误导致的“假死”热搜里有个词很扎眼“cc switch local proxy failed while handling codex endpoint /responses”。这描述的是一类典型故障本地代理在处理 Codex 的端点请求时失败了。这类问题的表现是工具看起来在跑但半天没输出像死了一样。根因通常是端点地址配错、代理没起、或者模型名写错。排查这类问题我的顺序是先看工具自己的日志通常有--verbose或日志文件确认请求到底发出去没有再确认端点地址和模型名跟配置一致最后确认网络层通不通。别一上来就怀疑模型不行九成是配置问题。提示配置里涉及端点、模型名的地方建议用变量引用而不是硬编码。比如model: ${DEFAULT_MODEL}在环境变量里定义。这样换模型只改一处不会漏改导致某个工具还在用旧配置。6.2 上下文超限与任务拆分Claude Code 的大上下文是优势但不是无限的。热搜里“claude code 1m 上下文”说明大家很关注这个能力但实际用的时候把整个大项目一股脑塞进去效果未必好——上下文越长模型对中间部分的注意力越容易稀释。我的经验是单次任务涉及的文件控制在合理范围内超过就拆。拆分的依据是任务的独立性。比如重构认证模块和重构支付模块两者关联不大就拆成两个任务分别跑。如果强行合成一个任务上下文里混着两套逻辑模型容易串。任务 YAML 的steps结构天然支持这种拆分一个任务一个 YAML互不干扰。6.3 工具版本不匹配引发的诡异报错Claude Code 和 Codex 都在快速迭代版本更新频繁。openrig 的配置如果假设了某个版本的参数格式工具升级后参数变了就会报一些看不懂的错。热搜里“卸载 claude code”“claude code 下载”“codex 下载”这些词一部分就是版本问题导致的反复重装。我的做法是在环境配置里记录每个工具的版本号升级前先看更新日志有没有破坏性变更。如果 openrig 支持版本约束就写上不支持的话至少在自己笔记里记一笔“当前跑通的是哪个版本组合”。出问题时先回退到已知能跑的版本再逐步升级定位。6.4 权限与路径问题Linux 和 macOS 下工具没有执行权限、目录没有写权限都会导致任务失败但报错信息很隐晦。装完工具后chmod x一下可执行文件out/目录确认当前用户可写。Windows 下走 WSL 的话注意 Windows 路径和 Linux 路径的转换/mnt/c/...这种路径在配置里写错一个字符就找不到文件。6.5 会话残留导致的资源占用tmux 会话开多了不关会一直占着内存和进程。尤其是任务跑完但会话没退的情况时间一长机器变卡。我的习惯是每天收工前tmux ls看一眼确认没有僵尸会话有就tmux kill-session -t 会话名清掉。这个习惯能避免很多“机器莫名其妙变慢”的问题。7. 把 openrig 用顺之后的几个进阶思路7.1 任务模板化与参数化跑顺之后你会发现很多任务是重复的加一个 CRUD 接口、重构一个模块、写一批单元测试。这些任务的 YAML 结构几乎一样只是文件路径和具体描述不同。这时候把任务 YAML 模板化用变量占位跑的时候传参就行。比如task: add-crud模板里用${MODULE_NAME}、${FILE_PATH}占位命令行传值生成具体任务文件。这一步做完搭新任务从“写 YAML”变成“填参数”效率又上一个台阶。7.2 产物归档与回溯out/目录里的产物别用完就删。每个任务的analyze.md、implement.diff、verify.md都是宝贵的记录。我按out/日期-任务名/归档过一段时间回头看能清楚知道当时为什么那么改。出问题时diff 文件就是最直接的证据。这个习惯在团队协作里尤其重要别人接手你的任务看归档目录就能还原整个过程。7.3 多项目并行时的会话隔离同时跑多个项目时每个项目一个 tmux 会话会话名带项目前缀。别在一个会话里混跑多个项目上下文容易串输出也乱。openrig 的配置支持按项目切换工作目录和任务目录切换项目就是切换一套配置干净利落。7.4 和编辑器工作流的衔接热搜里“vscode 配置 claude code”“vscode 安装 claude code”热度很高说明很多人希望在编辑器里直接用。openrig 作为命令行侧的装配和编辑器侧并不冲突。我的做法是编辑器里做日常编辑和轻量补全重活大重构、批量任务切到 openrig 的 tmux 会话里跑。两边共享同一个项目目录改动实时同步。这样既享受编辑器的便利又用上命令行工具的编排能力。8. 我在实际装配中攒下的几条经验装配 openrig 这类工作台最深的体会是别追求一次配到完美。我第一版配置写了一百多行想覆盖所有场景结果自己都记不住哪个字段管什么改一处错一处。后来砍到三十行只保留最核心的工具路径、会话参数、任务目录反而稳定了。配置这东西够用就好需要了再加。第二条经验是先手动跑通再自动化。别一上来就写 YAML 编排先手动开 tmux、手动调 Claude Code、手动调 Codex把整个流程走一遍知道每一步的输入输出是什么再把它固化成配置。跳过手动阶段直接写配置等于闭着眼睛画地图画出来的大概率不能用。第三条是给每个环节留可观测的出口。任务跑起来之后你得能知道它跑到哪了、卡在哪了。我的做法是每个步骤都往out/写一个带时间戳的日志文件任务 YAML 里显式指定。出问题时看日志比盯着终端猜要快得多。最后一条也是我觉得最重要的这套东西是给自己用的不是给别人看的。配置丑一点、命名随意一点都没关系关键是你能在三个月后打开它还知道怎么用。所以注释要写目录结构要清晰任务 YAML 的描述字段别偷懒。我吃过这个亏——两个月前配的一套环境回头想复用结果自己都看不懂当时的字段含义只能重配。从那以后我给每个配置字段都写了注释任务 YAML 的description也写清楚背景。这点额外的时间后面能省回来好几倍。