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 类型 | 官方 token | Bearer 或自定义 | 看提供商文档 |
| 模型名 | 官方命名 | 提供商命名 | 不能混用 |
| 超时 | 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 tmux，macOS 下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 的锚点功能合并；三是接入通知机制，长任务跑完自动发个提醒。
这些扩展都不需要改动核心结构，只是在现有框架上加东西。这也是薄封装路线的好处，扩展点清晰，不会牵一发动全身。我个人在实际操作中的体会是，工具的价值不在于功能多，而在于它能不能让你把注意力放回真正重要的事情上——也就是写代码本身。
