openrig：用YAML和tmux编排Claude Code与Codex的本地AI编程工作流

1. 从openrig这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是open加rig——开放式的装备架、工具台。结合热搜词里那一串 Claude Code、Codex、YAML、tmux基本可以判断这不是什么硬件项目而是一个围绕 AI 编程助手Coding Agent搭建的本地工作台/编排层。说白了就是给 Claude Code、Codex 这类命令行 AI 编程工具做一层外骨骼让它们能在一个统一的环境里跑起来、被管理、被复用。为什么会有这种需求因为现在用 Claude Code 和 Codex 的人越来越多但绝大多数人停留在装完、跑起来、能用的阶段。真正每天拿它写代码的人会遇到一堆现实问题多个项目要切换、不同模型要切换、会话要持久化、配置散落在各个隐藏目录里、tmux 窗口开了一堆分不清哪个是哪个、YAML 配置文件改错一个缩进就整个跑不起来。openrig 这类工具的价值就是把这些零碎的东西收拢到一个可配置、可版本化、可复现的框架里。我自己的使用场景很典型手头同时有三四个仓库有的用 Claude Code 跑重构有的用 Codex 跑单元测试补全还有的在做本地模型接入的实验。以前每次切换都要重新 cd、重新起会话、重新确认配置一天下来光环境准备就耗掉不少精力。后来我开始用 YAML 把每个项目的启动参数固化下来再用 tmux 做会话管理整个流程才顺起来。openrig 这个标题指向的本质上就是把这套土办法产品化、标准化。这篇文章适合三类人看第一类是刚装完 Claude Code 或 Codex、还在摸索怎么把它用顺的新手第二类是已经在用、但配置管理一团乱、想找一套可复现方案的中级用户第三类是想自己搭一套本地 AI 编程工作流、对 YAML 配置和 tmux 会话管理感兴趣的人。下面我会从核心概念、配置设计、会话管理、踩坑排查几个角度把 openrig 这类工具背后的逻辑讲透让你看完能自己动手搭一套。2. openrig 的核心抽象把 AI 编程助手当成可编排的进程2.1 为什么不是装个插件那么简单很多人对 Claude Code、Codex 的理解停留在一个命令行工具装完就完事。但只要你认真用上一周就会发现它更像一个长期运行的进程而不是一次性命令。它会持有会话状态、会读写项目文件、会调用外部模型接口、会在终端里持续输出。这就带来一个根本问题进程怎么管传统的做法是每个项目开一个终端窗口手动敲命令启动。项目一多窗口就乱终端一关会话就断换个机器配置全丢。openrig 这类工具的核心抽象就是把启动一个 AI 编程助手这件事从手动敲命令变成声明式配置 进程编排。你用 YAML 描述我要在哪个目录、用哪个模型、带哪些参数、开几个会话工具负责把这些变成实际运行的进程。这个思路其实和 Docker Compose 很像。Compose 用 YAML 描述一组容器openrig 用 YAML 描述一组 AI 编程会话。区别在于容器是隔离的而 AI 编程助手需要直接操作你的代码仓库所以它不能完全隔离只能在可控和可用之间找平衡。2.2 YAML 在这里扮演的角色热搜词里yolov10 yaml文件怎么创建rstudio的yaml在哪里yaml安装这些说明很多人对 YAML 本身就不熟。但在 openrig 场景里YAML 不是可选项而是核心。原因很简单AI 编程助手的启动参数太多了——模型选择、API 端点、上下文长度、工作目录、环境变量、超时设置、日志级别这些用命令行参数传会又长又容易错用 YAML 写就清晰得多。一个典型的 openrig 配置大概长这样version: 1 defaults: model: claude-sonnet context_window: 200000 workdir: ~/projects sessions: - name: refactor-core tool: claude-code workdir: ~/projects/core model: claude-opus env: LOG_LEVEL: info tmux: window: refactor persist: true - name: test-gen tool: codex workdir: ~/projects/core model: gpt-5-codex env: LOG_LEVEL: warn tmux: window: testgen persist: true这段配置描述了两个会话一个用 Claude Code 跑重构一个用 Codex 跑测试生成都在同一个仓库里但用不同的模型和日志级别。工具读这份配置就能自动起两个 tmux 窗口各自跑各自的助手。注意YAML 对缩进极其敏感用空格不用 Tab两个空格一级是社区最通用的约定。我见过太多人因为一个 Tab 导致整个配置解析失败排查半天。2.3 tmux 为什么是天然的搭档热搜词里tmux单独出现说明它本身就是个高频关注点。tmux 的核心能力是会话持久化你关掉终端tmux 里的进程还在跑你重新连上会话原样恢复。这对 AI 编程助手来说太重要了——一个重构任务可能跑十几分钟你不可能一直盯着终端。openrig 把 tmux 作为底层会话载体逻辑上非常顺每个 AI 编程会话对应一个 tmux window整个项目对应一个 tmux session。这样你tmux attach进去就能看到所有正在跑的助手切换窗口就能切换任务。比起开一堆终端标签页tmux 的方案在远程场景下优势更明显——SSH 断了重连会话还在。我自己的习惯是给每个仓库建一个 tmux sessionsession 名就是仓库名里面按任务分 window。openrig 如果能把这套约定固化到配置里就省去了每次手动tmux new -s的麻烦。3. 配置文件的字段设计哪些参数必须显式声明3.1 模型与端点最容易踩坑的地方热搜词里claude code 调用lmstudio的本地模型codex接入deepseekclaude code接入deepseek这些说明大量用户在做模型端点替换。这恰恰是配置里最容易出问题的部分。Claude Code 默认走官方端点Codex 默认走另一套一旦你要换成本地模型或第三方兼容端点就得改配置。在 openrig 的 YAML 里模型和端点应该分开声明model: name: claude-sonnet provider: anthropic endpoint: https://api.example.com/v1 api_key_env: ANTHROPIC_API_KEY把api_key_env写成环境变量名而不是直接写密钥是基本的安全习惯。我见过有人把密钥直接写进 YAML 然后提交到 Git后果不用多说。用环境变量引用配置文件可以放心版本化。提示切换端点后一定要先跑一个最小请求验证连通性不要直接上大任务。端点不通的时候AI 助手往往不会立刻报错而是卡在那里等超时浪费你十几分钟。3.2 工作目录与上下文边界workdir这个字段看着简单其实决定了 AI 助手能看到哪些文件。Claude Code 和 Codex 都会基于工作目录做文件检索如果 workdir 设成了 home 目录它可能会去扫描一堆无关文件既慢又不安全。正确做法是每个会话的 workdir 精确到具体仓库根目录。还有一个容易被忽略的点是上下文窗口。热搜词里claude code 1m上下文说明大家很关注这个。但上下文不是越大越好——窗口越大单次请求越慢、越贵。我的经验是重构类任务给大窗口因为要理解整个模块补全类任务给小窗口只看当前文件就够。在 YAML 里按会话分别配置比全局设一个大值更合理。3.3 环境变量与日志级别环境变量这块openrig 应该支持三层覆盖全局 defaults、会话级、以及运行时注入。优先级从低到高。这样你可以把通用配置放全局把敏感或特殊的放会话级。日志级别建议默认设info排查问题时临时调到debug。但要注意debug级别下 AI 助手会输出大量请求细节如果日志里包含代码内容别随手贴到公开渠道。这是很多人忽略的安全细节。字段是否必填建议值说明name是语义化命名会话标识tmux window 名默认取这个tool是claude-code / codex决定用哪个助手workdir是仓库根目录影响文件检索范围model.name是按任务选重构用强模型补全用快模型context_window否按任务默认继承全局env否键值对敏感值用环境变量引用tmux.persist否true是否持久化会话这张表是我自己配了十几个会话之后总结出来的基本覆盖了日常会用到的字段。字段不在多在于每个都有明确用途。4. 会话生命周期管理从启动到回收的完整链路4.1 启动阶段幂等性是关键openrig 启动一个会话时最重要的一点是幂等。也就是说重复执行启动命令不应该产生重复的 tmux window 或重复的进程。实现方式通常是先检查目标 window 是否存在存在就 attach不存在才创建。这个逻辑听起来简单但实际写起来要考虑几种情况tmux server 没起、session 存在但 window 不存在、window 存在但里面的进程已经挂了。我踩过的坑是window 还在但里面的 AI 助手进程因为网络问题退出了这时候 attach 进去看到的是一个空 shell容易误以为助手还在跑。所以启动逻辑里应该加一步进程健康检查。4.2 运行阶段怎么知道助手还活着AI 编程助手不像普通服务那样有标准的健康检查接口。我的做法是在 tmux window 里跑一个 wrapper 脚本助手进程退出时脚本能捕获退出码并写到一个状态文件。openrig 读这个状态文件就知道会话是否健康。另一个实用技巧是给每个会话配一个心跳日志。助手每次处理完一个请求wrapper 就往日志里追加一行时间戳。超过一定时间没有新行就说明可能卡住了。这个机制在跑长任务时特别有用能帮你及时发现端点不通或模型无响应的问题。4.3 回收阶段别让僵尸会话堆积会话用完要回收否则 tmux 里会堆一堆死 window时间长了根本分不清。openrig 应该提供stop和clean两个操作stop优雅停止单个会话发信号让助手保存状态再退出clean批量清理已退出的会话。我自己的习惯是每天收工前跑一次 clean把当天跑完的会话清掉。周末再整体检查一遍配置把不再用的会话从 YAML 里删掉。配置文件和实际运行的会话保持一致是长期维护的关键。注意优雅停止很重要。直接 kill 进程可能导致 AI 助手正在写的文件处于半完成状态。虽然大多数助手有原子写入保护但别赌这个。5. 多助手协同Claude Code 和 Codex 怎么在同一个仓库里共存5.1 分工而不是竞争热搜词里 Claude Code 和 Codex 出现频率都很高很多人纠结到底用哪个。我的答案是不用二选一让它们分工。Claude Code 在长上下文理解和跨文件重构上表现好Codex 在单文件补全和测试生成上响应快。同一个仓库里让 Claude Code 负责架构级改动Codex 负责局部填充效率比单用一个高不少。openrig 的价值在这里就体现出来了它让两个助手共享同一个 workdir但各自独立运行、独立配置。你不需要为它们分别准备环境配置里声明清楚就行。5.2 避免文件冲突的实际做法两个助手同时操作同一个仓库最大的风险是文件冲突。A 助手在改utils.pyB 助手也在改后写的覆盖先写的。避免方法有几个按目录划分职责Claude Code 管src/coreCodex 管tests物理上不重叠。用 Git 分支隔离每个助手在自己的分支上跑完成后人工合并。配置里加文件锁openrig 在启动会话时检查目标目录是否已被其他会话占用。我实际用的是第一种加第二种的组合目录划分做粗隔离Git 分支做细隔离。这样即使两个助手同时跑也不会互相踩。5.3 共享配置与差异化配置的边界多助手场景下配置管理要分清哪些共享、哪些独立。共享的通常是API 端点、代理设置、日志格式、Git 用户信息。独立的通常是模型选择、上下文窗口、工作目录、任务参数。在 YAML 里用defaults加会话级覆盖就能实现。但要注意覆盖是浅合并还是深合并不同工具行为不一样。浅合并下会话级只要写了model字段整个model对象都会被替换而不是只替换model.name。这个细节不搞清楚很容易出现我明明只改了模型名端点怎么也跟着变了的问题。6. 踩坑实录那些配置报错背后的真实原因6.1 cc switch local proxy failed 这类报错的排查思路热搜词里有一条很长的报错cc switch local proxy failed while handling codex endpoint /responses。这类报错看着吓人其实拆开看就三层cc switch切换工具、local proxy本地代理层、codex endpoint /responses目标端点路径。问题出在本地代理层转发到 Codex 端点时失败了。排查顺序应该是先确认端点地址是否可达用 curl 直接打一下再确认代理层配置的路径映射是否正确/responses有没有被正确转发最后确认认证信息有没有透传。我遇到过一次是代理层把 Authorization header 吃掉了导致端点返回 401但报错信息里没提认证绕了很久。6.2 codex auth token is unavailable 的几种成因这个报错在热搜里也出现了。成因通常有三种token 环境变量没设、token 过期、token 设了但进程读不到比如 tmux 会话启动时环境没继承。第三种最隐蔽因为你在当前 shell 里echo $TOKEN是有值的但 tmux 里没有。解决办法是在 openrig 配置里显式声明需要的环境变量启动会话时主动注入而不是依赖 shell 继承。这样无论从哪个终端启动环境都一致。6.3 YAML 缩进和编码的隐形坑前面提过缩进这里补充编码问题。YAML 文件如果带 BOM字节顺序标记某些解析器会直接报错。Windows 上编辑过的文件尤其容易带 BOM。用file命令或十六进制查看器确认一下有 BOM 就用工具去掉。还有一个坑是中文注释。YAML 支持 UTF-8 注释但如果文件编码不是 UTF-8注释里的中文会导致解析失败。统一用 UTF-8 无 BOM 保存是最省心的做法。报错关键词最可能原因快速验证方法local proxy failed端点不可达或路径映射错curl 直接打端点auth token unavailable环境变量未注入tmux 内 echo 变量yaml parse error缩进或 BOM十六进制查看文件头session not foundtmux window 名不匹配tmux list-windows这张表是我自己整理的速查表遇到报错先对号入座能省不少时间。7. 从零搭一套 openrig 风格工作流的实操步骤7.1 环境准备先确认基础工具到位动手之前先确认三样东西tmux、YAML 解析器大多数语言自带、以及你要用的 AI 编程助手本体。Claude Code 和 Codex 的安装方式各有不同热搜里claude code安装codex安装教程ubuntu 安装claude codewindows安装claude code说明跨平台需求很普遍。我的建议是先在裸终端里把助手跑通确认能正常对话、能读写文件再考虑用 openrig 包装。跳过这一步直接上编排出问题时分不清是助手本身的问题还是编排层的问题。7.2 写第一份配置从单会话开始不要一上来就配五个会话。先写一个最简单的version: 1 sessions: - name: hello tool: claude-code workdir: ~/projects/demo model: name: claude-sonnet跑通这个确认 tmux window 起来了、助手能响应再逐步加字段、加会话。增量式配置的好处是每一步都可验证出问题能快速定位到刚加的那个字段。7.3 验证与迭代把配置纳入版本管理配置跑通后第一件事是git init把它管起来。每次改配置都提交出问题能回滚。我还会在配置里加一个version字段方便未来做配置格式升级时做兼容判断。迭代节奏上我建议每周回顾一次配置哪些会话常用、哪些字段从没改过、哪些报错反复出现。把不用的删掉把反复出现的报错对应的字段加上默认值。配置是活的不是写完就不管。8. 一些长期使用后的个人体会用这套东西一年多最大的感受是工具的价值不在于功能多而在于稳定和可预期。openrig 这类编排层的意义不是让 AI 编程助手变得更强而是让它的行为变得可复现。你今天怎么跑明天还怎么跑换台机器还是怎么跑。这种确定性在长期项目里比任何单点功能都重要。另一个体会是配置要写得笨一点。别追求花哨的继承和覆盖能显式写清楚的就显式写。YAML 的灵活性是双刃剑过度抽象会让三个月后的你自己都看不懂。我现在每个会话的配置都尽量自包含宁可重复几行也不搞复杂的引用链。最后分享一个小技巧给每个会话的 tmux window 名加上日期前缀比如0715-refactor。这样一眼就能看出哪些是今天的、哪些是上周遗留的。配合每天的 clean 操作tmux 里永远清清爽爽。这个习惯看着小但坚持下来能省掉大量这个窗口是干嘛的的困惑。