1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”这个词在英文里常指设备支架、装配架。但在当前 AI 编程工具爆发的语境下openrig 实际上是一个围绕Claude Code、Codex 等命令行 AI 编程助手构建的开源配置管理与工作流编排工具。它的核心价值可以用一句话概括把散落在各个配置文件、环境变量、终端会话里的 AI 编程工具配置统一收拢到一套可版本控制、可复用、可切换的 YAML 体系里。为什么这件事值得单独做一个工具因为过去大半年里我身边几乎所有重度使用 Claude Code 和 Codex 的开发者都遇到了同一个痛点配置碎片化。你在 Windows 上装 Claude Code需要配环境变量、配 API 端点、配模型名称你在 Ubuntu 上装 Codex又要重新来一遍你想在 VS Code 里用 Claude Code还得再配一套你想让 Codex 接入 DeepSeek 或者让 Claude Code 调用 LM Studio 的本地模型又是一堆参数。更别提 tmux 会话管理、多项目切换、不同模型端点的快速切换这些日常操作。openrig 要做的就是把这些东西标准化。它用 YAML 作为配置描述语言把每个 AI 编程工具的启动参数、环境变量、模型端点、工作目录、tmux 会话布局全部声明式地写在一个文件里。你换机器、换项目、换模型只需要改 YAML 或者切换 profile不用再手动 export 一堆变量、改一堆 JSON。这篇文章适合三类人看第一类是完全没接触过 Claude Code 或 Codex 的新手想搞清楚这些工具怎么装、怎么配、怎么用第二类是用过但配置管理很乱的中级用户想找一套系统化的管理方案第三类是已经在用 tmux、YAML 做自动化编排的老手想看看 openrig 的设计思路能不能借鉴到自己的流程里。我会从核心概念讲起然后拆解 YAML 配置结构再给出一套可以直接抄的实操流程最后把我踩过的坑和排查经验整理出来。提示openrig 本身是一个配置编排层它不替代 Claude Code 或 Codex 的安装而是管理这些工具的运行配置。你需要先确保基础工具能正常运行再用 openrig 来统一管理。2. 核心设计思路拆解为什么是 YAML tmux Profile2.1 为什么选 YAML 而不是 JSON 或 TOML配置格式的选择看似小事实际上直接影响日常使用体验。openrig 选 YAML 有几个很实际的理由。JSON 不支持注释你没法在配置里写“这行是给 DeepSeek 用的”“这个端点在公司网络下要改”过两周回来看就忘了。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述 tmux 的窗口布局、多个模型的端点列表时TOML 的[[array.of.tables]]写法可读性会明显下降。YAML 的优势在于支持注释、缩进表达层级、天然适合描述列表和嵌套字典。比如你要配三个模型端点YAML 里就是一个清晰的列表每个端点下面挂 name、base_url、api_key_env、model 几个字段一眼就能看懂。而且 YAML 在 DevOps 生态里太常见了Docker Compose、GitHub Actions、Kubernetes 都在用学习成本几乎为零。但 YAML 也有坑最大的坑就是缩进必须用空格不能用 Tab。我见过至少五个人因为复制粘贴时混入了 Tab 导致解析失败报错信息还特别隐晦只告诉你“mapping values are not allowed here”根本不提 Tab 的事。所以用 openrig 的第一条铁律就是编辑器里把 Tab 自动转空格打开缩进统一用 2 个空格。2.2 tmux 在 openrig 里扮演什么角色很多人第一次用 Claude Code 或 Codex 是在普通终端里直接跑跑一个任务还行但同时开三四个项目、每个项目又要看日志、又要改代码、又要跑测试的时候终端窗口就彻底乱了。tmux 解决的就是这个问题它让你在一个终端窗口里管理多个会话、多个窗口、多个面板而且会话可以断开后继续在后台运行。openrig 把 tmux 集成进来的逻辑是每个项目 profile 对应一个 tmux 会话会话里的窗口布局由 YAML 定义。比如你可以定义一个“全栈开发”profiletmux 会话里自动开三个窗口第一个窗口跑 Claude Code 做代码生成第二个窗口跑 Codex 做代码审查第三个窗口跑测试和日志监控。你openrig up fullstack一下整个工作环境就起来了不用手动开窗口、切目录、敲命令。这个设计的好处是环境可复现。你今天配好的布局明天换台机器只要 YAML 文件在一条命令就能还原。团队协作时你把 YAML 提交到仓库同事拉下来就能用同一套工作流不用再写文档告诉他“你先开三个终端第一个 cd 到哪第二个 export 什么变量”。2.3 Profile 机制一套配置管理多个场景openrig 的 profile 概念类似于“配置档案”。你可能有多个使用场景日常开发用 Claude Code 接官方端点做敏感项目时用 Codex 接本地 LM Studio 模型做实验时用 Claude Code 接 DeepSeek。这些场景的配置差异很大但又有大量重复部分。openrig 的做法是支持profile 继承和覆盖。你可以定义一个 base profile里面放通用配置比如工作目录、日志级别、tmux 基础布局。然后定义多个子 profile只写差异部分。子 profile 继承 base 的所有字段同时可以覆盖任意字段。这样你改一个通用配置所有 profile 都生效不用一个个改。这个机制在实际使用中非常省事。我自己的配置里有一个 base profile 定义了通用的 tmux 布局和日志路径然后claude-official、claude-deepseek、codex-local三个子 profile 分别只写了模型端点和 API key 环境变量名。切换场景时只需要openrig switch claude-deepseek其他东西自动继承。3. YAML 配置结构深度解析与实操要点3.1 一个完整的 openrig YAML 长什么样先看一个最小可用的配置示例我把它拆成几个部分来讲。这个配置定义了一个使用 Claude Code 接官方端点的 profile以及一个使用 Codex 接本地模型的 profile。version: 1 defaults: workdir: ~/projects log_dir: ~/.openrig/logs tmux: socket: openrig history_limit: 50000 profiles: claude-official: tool: claude-code env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} ANTHROPIC_BASE_URL: https://api.anthropic.com model: claude-sonnet-4-20250514 tmux: session: claude-official windows: - name: code command: claude - name: shell command: bash codex-local: tool: codex env: OPENAI_API_KEY: dummy OPENAI_BASE_URL: http://localhost:1234/v1 model: local-model tmux: session: codex-local windows: - name: codex command: codex - name: logs command: tail -f ~/.openrig/logs/codex.log这个配置里defaults段定义全局默认值profiles段定义具体场景。每个 profile 里tool指定用哪个 AI 编程工具env定义环境变量model指定模型tmux定义会话布局。注意${ANTHROPIC_API_KEY}这种写法表示从当前 shell 环境读取变量不要把真实 key 直接写进 YAML 提交到仓库。openrig 支持环境变量插值这是安全实践的基本要求。3.2 环境变量管理的关键细节环境变量是配置里最容易出问题的部分。Claude Code 和 Codex 各自认的环境变量名不一样而且不同版本可能有变化。Claude Code 主要认ANTHROPIC_API_KEY和ANTHROPIC_BASE_URLCodex 主要认OPENAI_API_KEY和OPENAI_BASE_URL。如果你要让 Codex 接入 DeepSeek就需要把OPENAI_BASE_URL指向 DeepSeek 的兼容端点OPENAI_API_KEY填 DeepSeek 的 key。openrig 处理环境变量的逻辑是先加载defaults.env再加载 profile 的envprofile 里的同名变量覆盖 defaults。同时支持从.env文件加载也支持从系统环境读取。这个优先级顺序很重要我建议的实践是敏感 key 放系统环境或.env文件非敏感的端点地址和模型名放 YAML。这样 YAML 可以安全地提交到 git.env加到.gitignore里。还有一个细节是变量插值的时机。openrig 在启动 tmux 会话之前会解析所有变量如果某个变量没定义默认行为是报错退出而不是静默传空字符串。这个设计很关键因为如果 API key 为空Claude Code 启动后会一直报认证失败你排查半天才发现是变量没加载。openrig 直接启动前就告诉你“ANTHROPIC_API_KEY is not set”省了大量排查时间。3.3 tmux 窗口布局的配置技巧tmux 配置是 openrig 里最能体现效率的部分。YAML 里的windows列表对应 tmux 的窗口每个窗口可以指定name和command。但实际使用中你往往需要更复杂的布局比如一个窗口里左右分屏左边跑 Claude Code右边跑 shell。openrig 支持在窗口级别定义panes每个 pane 可以指定命令和大小比例。比如tmux: session: dev windows: - name: main panes: - command: claude size: 70 - command: bash size: 30 split: horizontal这个配置会创建一个叫dev的会话里面有一个main窗口窗口里左右分屏左边 70% 跑 Claude Code右边 30% 跑 bash。split: horizontal表示水平分割也就是左右分。如果要上下分用split: vertical。实操中我发现一个很有用的技巧给日志窗口设置remain-on-exit。默认情况下tmux 窗口里的命令执行完窗口就关了。如果你跑一个测试命令跑完窗口消失你就看不到输出。在 openrig 的窗口配置里加remain_on_exit: true命令结束后窗口保留你可以回看输出。这个在调试 Codex 的认证问题时特别有用因为 Codex 启动失败会打印错误然后退出没有这个设置你根本看不到错误信息。4. 完整实操流程从安装到跑通第一个 Profile4.1 基础环境准备与工具安装在装 openrig 之前你需要先把基础工具装好。顺序很重要因为 openrig 依赖它们。第一步是装 tmux。Ubuntu 下sudo apt install tmuxmacOS 下brew install tmuxWindows 下建议用 WSL2然后在 WSL 里按 Ubuntu 的方式装。装完后tmux -V确认版本建议 3.0 以上。第二步是装 Claude Code 或 Codex。Claude Code 的安装方式通常是 npm 全局安装npm install -g anthropic-ai/claude-code装完claude --version确认。Codex 的安装类似具体包名以官方文档为准。这里要注意 Node.js 版本Claude Code 通常要求 Node 18 以上版本太低会报奇怪的语法错误。第三步是装 openrig 本身。如果它是通过包管理器分发按对应命令装如果是源码分发clone 下来后按 README 操作。装完openrig --version确认。提示Windows 用户强烈建议走 WSL2 路线。原生 Windows 下 tmux 支持很差Claude Code 和 Codex 的终端交互也可能出问题。WSL2 里就是标准 Linux 环境所有工具都能正常跑。4.2 编写第一个可用的 YAML 配置环境准备好后在~/.openrig/config.yaml创建配置文件。我建议从最小配置开始先跑通一个 profile再逐步加复杂度。第一个配置就用前面示例里的claude-official但把 API key 改成从环境读取。写完后用openrig validate检查配置语法。这个命令会解析 YAML、检查必填字段、验证变量是否存在。如果报缩进错误检查是不是混了 Tab如果报变量未定义检查 shell 里有没有 export 对应的 key。验证通过后openrig up claude-official启动。这个命令会创建 tmux 会话按配置开窗口在每个窗口里执行对应命令。你会看到终端切换到 tmux 界面里面已经有 Claude Code 在跑了。4.3 多 Profile 切换与日常使用节奏跑通一个之后再加第二个 profile。比如加一个codex-local接本地 LM Studio。LM Studio 默认端点是http://localhost:1234/v1模型名填你在 LM Studio 里加载的模型标识。配置写好后openrig up codex-local如果 LM Studio 没启动Codex 会报连接失败这时候去 LM Studio 里点一下启动服务就行。日常使用中我通常是这样操作的早上到工位openrig up claude-official开始写代码下午要做代码审查openrig switch codex-local切到 Codex晚上跑实验再切到接 DeepSeek 的 profile。openrig switch会保留当前 tmux 会话只切换环境变量和模型配置不用重新开窗口。这里有个细节switch和up的区别。up是新建会话如果同名会话已存在会报错。switch是在已有会话里切换 profile会重新加载环境变量。如果你改了 YAML 配置需要先openrig reload再switch否则用的还是旧配置。4.4 把配置纳入版本控制配置跑通后把~/.openrig/config.yaml复制到你的 dotfiles 仓库里用符号链接指回去。这样换机器时 clone dotfiles 仓库建个软链配置就恢复了。.env文件不要提交但可以提交一个.env.example里面写清楚需要哪些变量名不写真实值。团队协作时可以把项目相关的 profile 放在项目仓库的.openrig/目录下openrig 支持从项目目录加载配置并覆盖全局配置。这样每个项目可以有自己独立的 AI 工具配置互不干扰。5. 常见问题与排查技巧实录5.1 Claude Code 和 Codex 的典型报错处理实际使用中遇到最多的问题集中在认证和端点配置上。下面这张表整理了我遇到过的高频问题和解决方法。报错信息可能原因排查步骤解决方法API key not set环境变量未加载echo $ANTHROPIC_API_KEY检查确认.env文件路径正确或手动 exportConnection refused本地模型服务未启动curl localhost:1234/v1/models启动 LM Studio 或对应本地服务Model not found模型名拼写错误对照服务商文档检查模型标识修正 YAML 里的model字段YAML parse error缩进混用 Tab用cat -A查看不可见字符统一用 2 空格缩进tmux session exists同名会话未关闭tmux ls查看openrig down name或tmux kill-sessionCodex auth token unavailable认证配置缺失检查 Codex 的 auth 配置文件重新执行 Codex 登录流程这张表里的每一条我都实际踩过。特别是YAML parse error有次我从网页复制配置缩进里混了 Tab排查了二十分钟才发现。后来养成习惯配置写完先openrig validate能省很多时间。5.2 tmux 会话管理的避坑经验tmux 用久了会遇到会话堆积的问题。每次openrig up都建新会话时间长了tmux ls列出一堆。我的做法是给 openrig 配一个openrig down --all命令一键清理所有 openrig 管理的会话。手动清理的话tmux kill-server会杀掉所有会话包括你可能不想杀的其他 tmux 会话所以要谨慎。另一个坑是 tmux 的 socket 配置。openrig 默认用独立的 socket这样不会和你手动开的 tmux 会话混在一起。但如果你在 openrig 会话里再手动开 tmux可能会因为 socket 不同而看不到之前的会话。理解 socket 隔离机制后操作就清晰了openrig 管自己的会话你手动开的走默认 socket两边互不干扰。5.3 模型端点切换的实战心得让 Claude Code 调用 LM Studio 本地模型或者让 Codex 接入 DeepSeek核心都是改BASE_URL和API_KEY。但这里有个容易忽略的点不同模型对 API 格式的兼容程度不一样。Claude Code 期望的是 Anthropic 格式的 API如果你把ANTHROPIC_BASE_URL指向一个只兼容 OpenAI 格式的端点请求会失败。解决办法是用一个格式转换层或者确认目标端点同时兼容两种格式。LM Studio 较新版本支持 Anthropic 兼容模式DeepSeek 也有兼容端点。配置前先查清楚目标服务支持哪种 API 格式能避免大量调试时间。注意切换模型端点后建议先用一个简单请求测试连通性再跑正式任务。比如curl一下端点的/models接口确认能返回模型列表再去启动 Claude Code 或 Codex。5.4 配置继承与覆盖的调试方法Profile 继承用多了有时候会搞不清某个字段最终生效的值是哪个。openrig 提供了openrig show profile命令会打印出该 profile 合并所有继承后的最终配置。这个命令在调试时非常有用能直接看到最终生效的env、model、tmux配置。如果发现某个字段没按预期覆盖检查两点一是子 profile 里的字段名拼写是否和父 profile 一致YAML 是大小写敏感的二是覆盖的层级是否正确比如env下面的变量是整体覆盖还是逐键合并。openrig 默认是逐键合并子 profile 里没写的键会继承父 profile 的值写了就覆盖。6. 进阶玩法把 openrig 融入日常开发流6.1 结合项目目录的自动化配置openrig 支持在项目根目录放.openrig/profile.yaml进入项目目录后执行openrig up会自动加载项目级配置。这个特性适合做项目专属的 AI 工作流。比如一个前端项目配置里可以定义 tmux 布局左边跑 Claude Code 写组件右边跑npm run dev看效果下面跑测试监听。项目级配置和全局配置的合并规则是项目级覆盖全局级。这样你可以把通用配置放全局项目特有的放项目目录。团队协作时项目级配置提交到仓库新同事 clone 下来就能用同一套工作流。6.2 用 openrig 管理多模型对比实验做模型对比实验时openrig 的 profile 机制特别好用。你可以定义exp-claude、exp-codex、exp-deepseek三个 profile每个接不同模型然后写个脚本依次openrig up跑同一组任务收集输出做对比。因为所有配置都是声明式的实验条件容易控制不会因为手动改环境变量引入差异。我自己的做法是给每个实验 profile 配独立的日志目录跑完后直接对比日志文件。openrig 的log_dir配置支持按 profile 覆盖所以每个实验的输出自动分开不用手动整理。6.3 配置模板化与团队共享如果你在团队里推广 openrig建议做一个配置模板仓库里面放几个典型场景的 profile 模板官方端点版、本地模型版、兼容端点版。团队成员按需复制修改不用从零写。模板里把需要改的地方用注释标出来比如# 改成你的 API key 环境变量名降低上手门槛。共享配置时要注意脱敏。YAML 里不要出现真实 key、真实内部端点地址。用环境变量插值把敏感信息留在各人自己的.env里。这样配置可以安全地在团队内流转。7. 我踩过的那些坑和最后的小技巧说几个文档里不会写、但实际用起来很关键的点。第一个是tmux 的history-limit要调大。默认 tmux 只保留 2000 行滚动历史跑 AI 编程工具时输出量很大2000 行几下就滚没了。在 openrig 的defaults.tmux里设history_limit: 50000回看输出时从容很多。第二个是Claude Code 和 Codex 的工作目录要显式设置。它们默认在当前目录找项目文件如果 tmux 窗口启动时的目录不对工具会找不到项目。openrig 的workdir配置会在启动命令前自动cd到指定目录确保工具在正确的项目根目录下运行。第三个是API key 的加载顺序。openrig 加载变量的顺序是系统环境 →.env文件 → YAML 里的env段。后面的覆盖前面的。如果你在系统环境里 export 了一个旧 key又在.env里写了新 key最终生效的是.env里的。这个顺序要记清楚否则会出现“我明明改了 key 怎么还是报认证失败”的情况。最后分享一个提高效率的小习惯给常用的 profile 起短别名。比如openrig up co对应claude-officialopenrig up cl对应codex-local。openrig 支持在配置里定义aliases段把长名字映射到短名字。每天敲命令少打十几个字符累积下来省不少时间。这套东西我用了几个月最大的感受是配置管理这件事早做早省心。一开始觉得写 YAML 麻烦但当你第三次换机器、第五次切模型端点的时候就会庆幸当初把配置标准化了。openrig 不是唯一解但它把 YAML、tmux、profile 这几个成熟概念组合得比较顺手值得花一个下午跑通。