1. openrig 到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的不是某个具体工具而是一类很典型的痛点你手头有一堆命令行 AI 编码助手每个都有自己的配置格式、启动方式、会话管理逻辑切换一次就要重新折腾一遍环境。Claude Code、Codex 这类工具各自为政配置文件散落在不同目录YAML 写得稍微不对就报错tmux 会话开了一堆却记不清哪个窗口跑的是哪个任务。openrig 这个标题背后我理解的核心诉求就是把这些零散的东西装配成一个统一的工作台。从热搜词能看出来大家真正卡住的地方非常集中claude code安装、codex安装教程、vscode配置claude code、ccswitch配置codex、codex auth token is unavailable、yaml文件怎么创建、tmux怎么用。这些词拼在一起其实描绘的是一个完整的场景——一个人想在本机把多个 AI 编码 CLI 工具跑起来并且能稳定地在它们之间切换、复用会话、统一管理配置。openrig 如果是一个装配架rig 本身就有装备、装配的意思那它要干的事就是把这些工具像乐高一样拼到一个底座上。我先把话说在前面这篇不是官方文档的翻译而是我基于这类工具链的通用实践把 openrig 可能涉及的配置逻辑、目录结构、会话管理、排错思路完整拆一遍。你如果是刚接触 Claude Code 或 Codex 的新手能照着搭起来如果你已经用过一段时间但总在配置上翻车这里面的排查链路应该能帮你省不少时间。适合读这篇的人有三类一是刚装完 Claude Code 或 Codex、还没搞明白配置放哪的人二是想用 tmux 把多个 CLI 会话管起来、但总是切错窗口的人三是遇到cc switch local proxy failed或auth token is unavailable这类报错、不知道从哪下手的人。下面我按先理解设计意图再动手搭最后排错的顺序来讲。2. 为什么这类工具需要一个装配层2.1 单工具时代已经过去了早两年用 AI 编码助手基本就是一个工具打天下。现在不一样了Claude Code 擅长长上下文和复杂重构Codex 在某些补全和批量任务上有自己的节奏本地模型又能通过 LM Studio 之类的方式接进来。问题在于每个工具的配置哲学完全不同有的用 JSON有的用 YAML有的把配置藏在用户目录的隐藏文件夹里有的要求你在项目根目录放一个专属文件。我实测下来最烦的一点是同一个项目我想用 Claude Code 跑一遍再用 Codex 跑一遍对比结果结果两边的配置互相干扰。Claude Code 的配置改完Codex 读到的还是旧的tmux 里开了三个窗口过十分钟就分不清哪个是哪个。这种工具越多越乱的状态就是装配层要解决的第一层问题。2.2 YAML 为什么成了配置主力热搜里yolov10 yaml文件怎么创建、rstudio的yaml在哪里、yaml安装这些词说明一件事YAML 已经成了跨领域配置的通用语言从深度学习模型定义到 IDE 设置再到 CLI 工具到处都在用。openrig 这类装配工具大概率也是用 YAML 来描述我要启动哪些工具、每个工具用什么参数、会话怎么命名。YAML 的好处是层级清晰、可读性强写起来像列清单。坏处是它对缩进极其敏感一个空格错位就整个文件解析失败而且报错信息往往很模糊。我见过太多人卡在配置文件明明看着没问题但就是启动不了最后发现是 tab 和空格混用了。这一点在后面排错章节我会专门讲。2.3 tmux 在整条链路里的位置tmux出现在热搜里不是偶然。当你同时跑多个 CLI 工具时你需要一个能持久化会话、随时切回来、断线不丢进程的终端复用器。tmux 正好干这个一个 session 里开多个 window每个 window 跑一个工具命名清楚之后切换就是一条命令的事。但 tmux 本身也有学习成本。新手最容易犯的错是直接tmux进去开了几个窗口然后不知道怎么退出、怎么重命名、怎么在窗口间跳。更麻烦的是如果你把 Claude Code 跑在 tmux 里会话断了之后进程还在但你可能忘了它还在后台占着资源。所以装配层如果能把 tmux 的会话命名和工具启动绑定起来体验会好很多。3. 把 openrig 的工作目录结构理清楚3.1 一个合理的目录布局长什么样在动手写任何配置之前先把目录结构定下来。我踩过的坑是配置文件和项目文件混在一起时间一长根本分不清哪个是全局配置、哪个是项目专属。下面这个布局是我用了很久、觉得最不容易乱的方案~/.openrig/ ├── config.yaml # 全局装配配置 ├── sessions/ # 会话状态记录 ├── logs/ # 各工具运行日志 └── profiles/ # 不同场景的配置档 ├── default.yaml └── local-model.yaml项目层面则保持干净只在根目录放一个指向 profile 的标记文件my-project/ ├── .openrig-profile # 内容就一行local-model ├── src/ └── README.md这样设计的好处是全局配置和项目配置彻底分离。你想换一套工具组合改 profile 就行不用动项目里的任何代码。我第一次这么整理之后切换工具的时间从每次五分钟重新配降到改一行标记文件。3.2 全局配置里该写什么config.yaml是整个装配架的核心。它要回答三个问题启动哪些工具、每个工具用什么参数、会话怎么组织。下面是一个我实际在用的结构你可以直接抄version: 1 default_profile: default tools: claude: command: claude workdir: ${PROJECT_DIR} env: ANTHROPIC_LOG: info codex: command: codex workdir: ${PROJECT_DIR} env: CODEX_HOME: ${HOME}/.codex sessions: naming: ${PROJECT_NAME}-${TOOL} tmux: enabled: true socket: openrig这里有几个细节值得说。${PROJECT_DIR}这种变量占位符是为了让同一份配置能复用到不同项目sessions.naming决定了 tmux 窗口的名字用项目名-工具名的格式一眼就能看出哪个窗口在跑什么tmux.socket单独指定一个 socket是为了把你 openrig 管理的会话和系统里其他 tmux 会话隔离开避免误操作关掉不该关的窗口。3.3 profile 的差异化设计profile 的价值在于一套配置应对一种场景。比如我常用的两个profile 名称用途关键差异default日常云端模型走默认 API日志级别 infolocal-model本地模型调试指向本地端点日志级别 debuglocal-model.yaml里我会把端点、模型名、超时时间都写死这样切过去之后不用每次手动指定。profile 之间只写差异部分公共部分继承全局配置这是保持配置文件简短的关键。如果你每个 profile 都把全部配置抄一遍改一个公共参数就要改五个文件迟早出错。4. 从零搭起一套可用的装配环境4.1 前置依赖的安装顺序安装顺序这件事很多人不当回事结果就是各种命令找不到。我建议的顺序是先装 tmux再装各 CLI 工具最后装 openrig 本身。原因是 openrig 启动时会去调 tmux如果 tmux 没装好它会报一个很模糊的错让你以为是 openrig 的问题。在 Ubuntu 上tmux 直接sudo apt update sudo apt install -y tmux tmux -VWindows 用户如果用的是 WSL同样走上面这套如果是在原生 Windows 里折腾tmux 需要额外方案我个人的建议是尽量在 WSL 里做这套装配因为绝大多数 CLI 工具对 Linux 环境的支持最完整windows安装claude code这类问题在 WSL 下基本不会遇到。4.2 Claude Code 与 Codex 的安装要点这两个工具的安装本身不复杂但有几个坑必须提前说。Claude Code 安装完之后第一件事是确认它能不能读到你的认证信息很多人卡在your organization has disabled claude subscription access这类提示上本质是账号权限或认证状态的问题不是安装问题。Codex 这边codex auth token is unavailable是出现频率最高的报错。我的排查经验是先确认 token 文件确实存在且没过期再确认环境变量没有把路径覆盖掉。Codex 默认会去某个固定目录找认证文件如果你在 openrig 的配置里改了CODEX_HOME那认证文件也得跟着挪过去否则它找不到。安装完之后不要急着写 openrig 配置先手动把每个工具单独跑通一次。这一步能帮你把工具本身的问题和装配层的问题分开。我见过太多人一上来就配 openrig结果报错之后完全不知道是工具没装好还是配置写错了。4.3 验证工具能独立运行单独验证的命令很简单但要看的东西不少# 验证 claude 能启动并读到配置 claude --version claude config list # 验证 codex 能启动 codex --version codex auth statusclaude config list会打印出当前生效的所有配置项这是排查配置覆盖问题最直接的手段。如果你在 openrig 里设了某个环境变量但config list里没体现说明环境变量没传进去。Codex 的auth status同理它会告诉你当前认证状态是否正常。这一步过了才说明工具本身没问题可以进入装配环节。5. 会话管理与 tmux 的配合细节5.1 为什么不能裸用 tmux直接tmux new -s work然后手动开窗口短期能用长期一定乱。问题出在会话命名没有规范。你今天开的是work明天开的是test一周后回头看完全想不起来哪个会话对应哪个项目。openrig 的思路应该是把会话命名规则固化下来。我在配置里用的是${PROJECT_NAME}-${TOOL}实际跑起来就是myproject-claude、myproject-codex这样的名字。好处是你随时可以用一条命令列出所有相关会话并且从名字就能判断该不该关。tmux -L openrig ls注意这里的-L openrig它指定了 socket 名字和前面配置里的tmux.socket对应。这样列出来的只有 openrig 管理的会话不会把你系统里其他 tmux 会话混进来。5.2 会话的创建与恢复创建会话时我习惯让 openrig 一次性把需要的窗口都开好而不是一个个手动加。配置里可以这样描述sessions: layout: - name: claude tool: claude - name: codex tool: codex - name: shell tool: bash这样启动之后一个 session 里就有三个窗口分别跑 Claude Code、Codex 和一个普通 shell。留一个普通 shell 窗口非常重要因为你总会有临时命令要跑如果所有窗口都被工具占着你就得再开一个终端反而更乱。恢复会话用tmux -L openrig attach -t myproject如果会话已经存在这条命令直接切进去如果不存在openrig 应该负责重建。这里有个经验不要用tmux kill-server来清理那会把你所有会话一次性干掉包括正在跑长任务的。要清理单个会话用tmux -L openrig kill-session -t 名字。5.3 断线之后进程还在吗这是 tmux 最容易被误解的地方。tmux 里的进程是挂在 tmux server 上的你的 SSH 断了tmux server 还在进程就还在跑。这既是优点也是坑优点是长任务不会因为网络抖动中断坑是你以为关掉终端就结束了其实后台还在占资源。我的做法是在 openrig 的日志目录里记录每个会话的启动时间和对应工具定期检查。如果某个会话超过预期时间还在跑要么是任务真的很久要么是卡住了需要进去看看。6. 配置报错的完整排查链路6.1 YAML 解析失败从报错行号倒推YAML 报错最典型的表现是启动直接失败提示某一行有问题但你盯着那一行看半天看不出毛病。九成以上的情况是缩进问题。YAML 不允许 tab只允许空格而且同一层级必须对齐。我的排查步骤是这样的先用cat -A config.yaml把不可见字符打出来tab 会显示成^I一眼就能发现。如果缩进没问题检查是否有中文冒号。从网页复制配置时特别容易把:复制成这个错误极其隐蔽。再检查字符串里有没有未转义的特殊字符比如:后面跟空格、#被当成注释。# 快速检查 tab grep -P \t config.yaml # 用 python 验证 YAML 是否合法 python3 -c import yaml; yaml.safe_load(open(config.yaml))用 Python 验证这一步我强烈推荐它给出的报错比大多数工具自带的解析器更精确会直接告诉你第几行第几列有问题。6.2 cc switch local proxy failed 的定位思路cc switch local proxy failed while handling codex endpoint /responses这个报错关键词是local proxy和endpoint。它说明中间有一层代理在转发请求但转发到/responses这个端点时失败了。排查顺序检查项命令/方法预期结果代理进程是否在跑ps aux | grep proxy能看到进程端点是否可达curl -v http://localhost:端口/responses返回非连接错误端口是否被占lsof -i :端口只有一个进程占用配置里的端点地址检查 config.yaml和实际监听地址一致我遇到过一次原因是配置里写的端口和代理实际监听的端口差了一位这种低级错误在配置文件多了之后特别容易发生。养成改完配置就curl一下的习惯能省掉大量猜测时间。6.3 auth token is unavailable 的三种成因这个报错我归纳下来有三种原因按出现频率排序第一种是认证文件路径不对。你在 openrig 里改了CODEX_HOME或类似的环境变量但认证文件还在老地方。解决办法是把认证文件复制到新路径或者干脆不改这个变量。第二种是token 过期。这个最直接重新走一遍登录流程就行。第三种最隐蔽环境变量里有空的认证变量覆盖了文件里的值。比如你之前 export 过一个空的CODEX_TOKEN工具优先读环境变量读到空的就报 unavailable。用env | grep -i token检查一下有没有这类残留。7. 让装配架真正好用的几个经验7.1 日志分级别什么都往 debug 打我一开始图省事所有工具都开 debug 日志结果日志文件一天涨到几百兆真正有用的信息淹没在里面。后来改成默认 info只在排查特定问题时临时切 debug清爽很多。openrig 的 profile 机制正好支持这个日常用 default profile出问题了切到 debug profile。7.2 配置文件纳入版本管理~/.openrig/这个目录我建议用 git 管起来。配置这东西改坏了能回滚比什么都重要。我有次手滑删了一个 profile因为没版本管理只能凭记忆重写。现在每次改配置都 commit 一下出问题git checkout就回来了。注意别把认证文件、token 这类敏感信息提交进去用.gitignore排除掉。7.3 给每个工具留独立的日志多个工具共用一个日志文件是灾难。按工具分文件文件名带上日期排查的时候直接定位到对应时间段。我在配置里用${TOOL}-${DATE}.log这种命名配合tail -f实时看效率很高。7.4 定期清理僵尸会话tmux 会话不会自己消失跑久了一堆僵尸会话占着内存。我写了个简单的清理脚本检查每个会话最后活动时间超过阈值就提示。不要自动 kill因为有可能正在跑重要任务提示之后人工确认更稳妥。8. 本地模型接入时的额外注意点热搜里claude code 调用lmstudio的本地模型和codex接入deepseek说明很多人想把本地或第三方模型接进来。这块比纯云端配置多几个坑。第一是端点格式。不同工具对端点的要求不一样有的要求带/v1有的不带。配置的时候先用curl手动打一次确认返回格式符合预期再写进配置。第二是超时设置。本地模型首次加载慢默认超时经常不够需要把超时调大。我一般设到 120 秒起步模型大的话还要往上加。第三是并发限制。本地模型通常扛不住高并发如果你在 openrig 里同时启动多个工具指向同一个本地端点很容易互相拖垮。建议本地模型场景下一次只跑一个工具或者给每个工具配不同的模型实例。tools: claude: env: API_BASE: http://localhost:1234/v1 API_TIMEOUT: 120这类环境变量名各工具不同具体以工具文档为准但思路是一样的端点、超时、并发这三个参数一定要显式配置不要依赖默认值。9. 我踩过的几个真实坑说几个具体的都是我自己折腾过程中真实遇到的。坑一配置文件里的相对路径。我在 config.yaml 里写了workdir: ./project以为会相对于配置文件所在目录解析结果它是相对于当前工作目录解析的。在不同目录下启动行为完全不一样。后来全部改成绝对路径或者用${HOME}开头的变量问题消失。坑二tmux 窗口名重复。我一开始的命名规则没带项目名结果两个项目都开了叫claude的窗口切换的时候完全分不清。加上项目前缀之后就好了。命名规则一定要保证全局唯一这是血的教训。坑三环境变量污染。有次 Claude Code 一直读不到我新配的端点排查半天发现是 shell 的.bashrc里有个旧的 export 覆盖了配置。排查配置问题时先env | grep一下相关变量能省很多时间。坑四YAML 里的布尔值。YAML 会把yes、no、on、off自动解析成布尔值如果你本来想写字符串就会出问题。我有个配置项值写的是on结果被解析成true工具读到的类型不对直接报错。字符串该加引号就加引号别偷懒。10. 后续可以怎么扩展这套装配架这套东西搭起来之后能扩展的方向不少。比如给每个 profile 加钩子hook在工具启动前自动拉取最新代码、启动前检查依赖再比如把会话状态持久化到文件重启机器之后能一键恢复所有会话还可以做一个简单的状态面板用一条命令列出所有会话、对应工具、运行时长。我个人最想加的是配置校验在启动之前先跑一遍 schema 校验把明显的配置错误拦在前面而不是等工具启动到一半才报错。这个用 Python 的jsonschema或者类似的库就能做成本不高但收益很大。如果你也在折腾多工具装配我的建议是先把最小可用版本跑通再逐步加功能。一上来就想做全套自动化大概率会在配置阶段就卡死。先让 Claude Code 和 Codex 能在 tmux 里各跑一个窗口再谈 profile、hook、状态面板这些进阶玩法。