1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的不是某个具体软件而是一种“把散装工具串成一条流水线”的直觉。rig 在英文里有“装配、搭台子”的意思open 则点明了它的开放属性。结合最近圈子里反复被提到的 Claude Code、Codex、YAML、tmux 这几个关键词我基本能判断出openrig 想做的事情是给命令行 AI 编程助手搭一套可复用、可切换、可编排的“工作台”。为什么这件事值得单独拿出来讲因为现在用 Claude Code 或 Codex 的人越来越多但大多数人的用法还停留在“打开终端、敲一句、等结果”的阶段。一旦你同时用两个以上的助手或者需要在本地模型和云端模型之间来回切问题就来了配置散落在不同文件里、会话状态没法复用、换个项目就要重新配一遍。openrig 这类工具的价值就是把这些重复劳动收敛成一份声明式的配置让你用 YAML 描述“我要什么”而不是每次手动敲“我怎么做”。这篇文章适合三类人看。第一类是刚接触 Claude Code 或 Codex、还在纠结怎么安装和配置的新手我会把环境准备和常见报错讲透。第二类是已经在用、但被多工具切换折磨的中级用户我会重点讲 YAML 编排和 tmux 会话管理的组合拳。第三类是喜欢折腾本地模型接入的玩家Codex 接 DeepSeek、Claude Code 调 LM Studio 这类场景我也会覆盖。全文基于我自己的实操经验参数和步骤都可以直接抄。2. 整体设计思路为什么是 YAML 加 tmux 这套组合2.1 声明式配置为什么比一堆脚本更靠谱我早期管理 AI 编程助手的方式很原始写几个 shell 脚本每个脚本里硬编码模型名、API 地址、启动参数。用了不到两周就崩了原因是脚本里的变量太多改一个地方要动三个文件而且没法版本化管理。后来我转向 YAML最大的感受是“配置和逻辑分离”带来的清爽。YAML 的核心优势在于它是纯数据描述不掺杂执行逻辑。你可以把“用哪个模型”“走哪个端点”“超时设多少”“要不要开日志”全部写成键值对工具负责解析你负责声明意图。这样做的好处有三个一是可读性强新人接手看一眼就懂二是可 diff改了什么一目了然三是可复用同一份配置换个环境变量就能跑在不同机器上。提示YAML 对缩进极其敏感Tab 和空格混用是最常见的翻车原因。我建议统一用两个空格并且在编辑器里打开“显示空白字符”能省掉大量排查时间。2.2 tmux 在 AI 编程工作流里的真实定位很多人以为 tmux 只是个“终端复用器”用来防止 SSH 断线。但在 AI 编程场景里tmux 的作用远不止于此。它真正解决的是“长任务与会话保持”的问题。Claude Code 和 Codex 在处理大项目时一次对话可能跑好几分钟如果终端一关就前功尽弃体验会非常糟糕。tmux 的第二个价值是“多窗口并行”。我通常会在一个 tmux 会话里开三个窗口窗口 0 跑 Claude Code窗口 1 跑 Codex窗口 2 用来查看日志和跑测试。这样切换成本几乎为零而且每个窗口的历史输出都保留着回头查问题很方便。第三个价值是“脚本化”tmux 支持用命令批量创建窗口和面板这正好和 YAML 配置形成互补——YAML 描述“要什么”tmux 命令负责“搭出来”。2.3 openrig 的抽象层次它不该做什么在动手之前我想先划一条边界。openrig 这类工具不应该去接管模型推理本身也不应该去重新实现一个终端。它的职责是“编排”和“适配”把不同助手的启动方式统一成一套接口把配置从散落状态收敛成一份文件把会话管理交给 tmux 这种成熟工具。想清楚这一点后面选型和排错都会顺畅很多。我见过一些项目试图自己实现终端渲染和会话管理结果 bug 一堆维护成本极高。openrig 走的是“薄封装”路线这个方向我认为是对的。薄封装意味着它依赖底层工具的稳定性自己只做粘合层出问题时排查范围也小。3. 核心细节解析Claude Code 与 Codex 的配置要点3.1 Claude Code 安装与配置的完整路径Claude Code 的安装方式在不同系统上略有差异。Windows 用户我建议走桌面版或者 WSL纯原生终端偶尔会有路径问题。Ubuntu 和 macOS 用户直接用包管理器或者官方脚本就行。安装完成后第一件事是确认版本第二件事是配置认证。认证这块是新手最容易卡住的地方。常见的报错包括“your organization has disabled claude subscription access”这类提示本质上是账号权限或订阅状态的问题不是安装本身的问题。遇到这种情况先确认账号状态再检查配置文件里的认证字段是否写对。我一般会把认证信息放在环境变量里而不是硬编码进 YAML这样换机器时只需要重新导出变量。配置文件的典型结构是这样的claude: model: claude-sonnet endpoint: https://api.example.com timeout: 120 max_tokens: 8192 log_level: info这里每个字段都有讲究。timeout 设太短长任务会被中断设太长卡死时你也不知道。我实测 120 秒是个比较平衡的值。max_tokens 要根据你的实际需求调写代码场景 8192 通常够用但如果让它读大文件可能需要往上加。3.2 Codex 安装与接入第三方模型的注意事项Codex 的安装包和桌面版在国内的获取渠道比较杂我建议优先走官方渠道避免来路不明的包。安装完成后Codex 默认走官方端点但很多人想接 DeepSeek 或其他模型来降低成本。这个操作本身可行但有几个坑要提前知道。第一个坑是端点格式。不同模型提供商的 API 路径不一样Codex 的配置文件里 endpoint 字段必须写完整路径少一段就会报“cc switch local proxy failed while handling codex endpoint /responses”这类错误。第二个坑是认证 token 的格式有些提供商要求 Bearer 前缀有些不要写错了会一直提示“codex auth token is unavailable”。我整理了一份常见配置对照配置项官方端点第三方端点注意事项endpoint官方地址提供商地址必须含完整路径auth 类型官方 tokenBearer 或自定义看提供商文档模型名官方命名提供商命名不能混用超时60-120s视网络情况跨境要加长3.3 YAML 文件创建与校验的实操细节YAML 文件的创建看起来简单但细节决定成败。我习惯把配置文件放在项目根目录的.config文件夹下命名用openrig.yaml这样工具默认就能找到。文件开头不要加 BOM某些编辑器会偷偷加导致解析失败。校验 YAML 有个小技巧用 Python 的 yaml 库跑一遍safe_load能提前发现缩进和语法问题。命令很简单python3 -c import yaml; yaml.safe_load(open(openrig.yaml))没报错就说明语法没问题。这一步我强烈建议加进你的工作流比等到工具启动时报错再回头查要高效得多。另外YAML 里的布尔值写法要注意yes、no、on、off在某些解析器里会被当成布尔如果你想要字符串记得加引号。4. 实操过程从零搭一套可切换的 AI 编程工作台4.1 环境准备与依赖安装开始之前先确认三样东西终端环境、包管理器、以及 tmux。Linux 和 macOS 自带终端够用Windows 建议用 WSL2。tmux 的安装很简单Ubuntu 下apt install tmuxmacOS 下brew install tmux。装完后跑tmux -V确认版本建议 3.0 以上。接下来装 Claude Code 和 Codex。这两个工具的安装顺序无所谓但我建议先装 Claude Code因为它的配置相对简单能帮你快速建立信心。安装完成后分别跑一次--version和--help确认命令可用。如果提示找不到命令多半是 PATH 没配好检查一下安装路径有没有加进环境变量。注意不要在同一个终端里同时导出两个工具的环境变量容易互相覆盖。我建议用 direnv 或者手动在 tmux 窗口里分别设置。4.2 编写 openrig.yaml 配置文件配置文件是整个工作台的核心。我下面给出一份经过实测的模板你可以直接改version: 1 session: name: openrig windows: - name: claude command: claude-code --config ./claude.yaml - name: codex command: codex --config ./codex.yaml - name: logs command: tail -f ./logs/app.log claude: model: claude-sonnet timeout: 120 max_tokens: 8192 codex: model: deepseek-coder endpoint: https://api.example.com/v1/responses timeout: 180 auth: ${CODEX_TOKEN}这份配置里session段描述 tmux 会话结构claude和codex段描述各自的参数。注意auth字段用了环境变量引用这样敏感信息不会写进文件。endpoint我特意写了完整路径避免前面提到的那个报错。4.3 用 tmux 拉起会话并验证配置写好后用一条命令拉起整个会话tmux new-session -d -s openrig -n claude tmux new-window -t openrig -n codex tmux new-window -t openrig -n logs tmux attach -t openrig这三条命令分别创建会话、添加窗口、附加进去。实际使用时我会把这些命令封装成一个脚本配合 YAML 解析自动生成这样改配置就不用改脚本。验证阶段重点看两件事每个窗口的命令是否正常启动以及日志窗口有没有报错。如果 Claude Code 窗口卡住不动先检查认证如果 Codex 窗口报端点错误回头核对 endpoint 路径。4.4 本地模型接入的实操记录把 Claude Code 接到 LM Studio 的本地模型是我最近折腾比较多的场景。核心思路是把 endpoint 指向本机的 LM Studio 服务端口通常是 1234。配置大概长这样claude: model: local-model endpoint: http://localhost:1234/v1 timeout: 300 max_tokens: 4096本地模型的响应速度取决于你的硬件超时要设得比云端长。我实测在 16G 内存的机器上跑 7B 模型简单代码补全没问题但复杂重构会明显变慢。这里有个经验本地模型适合做“隐私敏感”或“离线可用”的场景不适合追求极致质量的任务。两者搭配用才是合理的工作流。5. 常见问题与排查技巧实录5.1 安装与认证类问题速查新手阶段遇到的问题八成集中在安装和认证上。我整理了一份速查表现象可能原因解决方向命令找不到PATH 未配置检查安装路径并导出认证失败token 过期或格式错重新生成并核对前缀订阅不可用账号权限问题确认账号状态端点报错路径不完整补全 API 路径启动卡住网络或超时加长 timeout 并查日志这张表覆盖了我遇到的大部分情况。特别说一下“端点报错”很多人以为是自己配置写错了其实是提供商改了 API 路径。遇到这种情况先去提供商文档确认最新路径再改配置。5.2 多工具切换时的冲突排查同时跑 Claude Code 和 Codex 时最常见的冲突是端口占用和环境变量覆盖。端口方面如果两个工具都默认监听同一个本地端口第二个启动的会失败。解决办法是在配置里显式指定不同端口。环境变量方面两个工具可能都读同一个变量名导致行为异常。我的做法是在 tmux 每个窗口启动前单独 export而不是在全局设置。还有一个隐蔽的冲突是配置文件路径。如果两个工具都默认读当前目录的某个文件而你恰好把两份配置放在一起就会互相干扰。我建议给每个工具单独的配置目录路径写绝对路径避免歧义。5.3 我踩过的三个坑和对应经验第一个坑是 YAML 缩进。我曾经因为一个键多缩进了一个空格排查了半小时。后来养成习惯写完先跑校验命令再启动工具。第二个坑是 tmux 会话名冲突。如果你之前有个同名会话没关掉新建会失败。我现在的做法是启动脚本里先tmux kill-session -t openrig再新建保证干净。第三个坑是本地模型的内存占用。跑大模型时如果同时开多个窗口内存容易爆。我的经验是本地模型场景下tmux 窗口数量控制在两个以内留足内存给模型本身。提示排查问题时先看日志再看配置。日志里通常有明确的错误码和路径信息比盲目改配置高效得多。6. 工具选型与扩展思路6.1 为什么我最终选了这套组合市面上类似的编排工具不少我最终选 YAML 加 tmux 这套组合理由很实际。YAML 的生态成熟几乎所有语言都有解析库未来想扩展成其他形式也容易。tmux 足够稳定十几年没出过大问题而且几乎每台服务器都预装。相比之下一些新兴的编排工具虽然功能花哨但依赖多、更新快今天能用的配置明天可能就失效了。另一个考虑是学习成本。YAML 和 tmux 都是通用技能学会了不只能用在 AI 编程场景日常运维也用得上。这种“投资回报率”是我做技术选型时很看重的一点。6.2 后续可以怎么扩展这套工作台搭好之后扩展空间很大。我目前想到几个方向一是加一个健康检查窗口定时 ping 各个端点提前发现服务不可用二是把配置拆成“基础配置”和“项目配置”两层基础配置放通用参数项目配置放项目特有参数用 YAML 的锚点功能合并三是接入通知机制长任务跑完自动发个提醒。这些扩展都不需要改动核心结构只是在现有框架上加东西。这也是薄封装路线的好处扩展点清晰不会牵一发动全身。我个人在实际操作中的体会是工具的价值不在于功能多而在于它能不能让你把注意力放回真正重要的事情上——也就是写代码本身。