1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”这个词在英文里常指设备支架或矿机机架。但在当前 AI 编程工具爆发的语境下openrig 实际上是一个围绕 Claude Code、Codex 这类终端 AI 编程助手构建的开源配置管理与工作流编排工具。它的核心价值用一句话概括让你在多个 AI 编程助手之间自由切换、统一管理配置、复用会话上下文而不是被某一家工具锁死。我最初接触这个领域是因为一个很现实的痛点。团队里有人用 Claude Code有人用 Codex CLI还有人因为网络或成本原因想接入 DeepSeek 这类国产模型。每个人的配置文件散落在不同的目录下YAML 格式各不相同tmux 会话管理也各搞各的。每次换人接手或者换机器部署光是把环境跑通就要折腾大半天。openrig 出现的意义就是把这些碎片化的配置和启动流程收敛到一套可版本控制、可复用的框架里。它适合什么人如果你是刚接触 Claude Code 或 Codex 的新手openrig 能帮你跳过大量手动配置的坑如果你是多工具混用的老手它能帮你把 YAML 配置、tmux 会话、模型端点这些琐事统一管理起来。哪怕你只是想在国内环境下稳定使用 Codex 或 Claude Code理解 openrig 的设计思路也能让你少走很多弯路。提示openrig 本身不是一个模型也不是一个代理工具它是一层“配置编排层”。理解这一点很关键否则很容易把它和各类网络工具混淆。2. openrig 的核心设计思路拆解2.1 为什么需要一层“编排层”Claude Code 和 Codex CLI 这类工具的原生配置方式各有各的逻辑。Claude Code 依赖~/.claude目录下的配置文件Codex 则有自己的~/.codex配置体系。当你同时使用多个工具或者需要在不同项目间切换不同的模型端点时手动改配置就成了噩梦。更麻烦的是很多配置项是互斥的——比如你不可能在同一个终端会话里同时让 Claude Code 和 Codex 都占用默认端口。openrig 的设计思路借鉴了基础设施即代码的理念。它把每个 AI 编程助手的启动配置抽象成一份 YAML 文件通过统一的命令行入口来加载不同的配置组合。这样做的好处是配置可以纳入 Git 版本控制团队可以共享同一套基准配置新人入职只需要 clone 仓库然后执行一条启动命令。我实测下来这种设计最大的优势在于“可复现”。以前帮同事排查 Claude Code 连不上本地模型的问题得让他把配置文件截图发过来一来一回半小时。现在只要让他把 openrig 的配置目录打包发过来我本地一跑就能复现问题。2.2 YAML 作为配置载体的取舍为什么选 YAML 而不是 JSON 或 TOML这个问题我在项目初期也纠结过。JSON 的问题是没法写注释而 AI 编程工具的配置里有大量需要说明的地方比如某个端点为什么这么设、某个环境变量是干什么的。TOML 虽然可读性好但在嵌套结构表达上不如 YAML 直观。YAML 的缩进语法虽然容易出错但配合编辑器的语法检查实际使用中问题不大。openrig 的 YAML 配置通常包含几个核心区块模型端点定义、工具启动参数、环境变量注入、tmux 会话布局。下面是一个典型的配置结构示例# openrig 配置示例 version: 1 profiles: claude-deepseek: tool: claude-code endpoint: https://api.deepseek.com/v1 model: deepseek-chat env: ANTHROPIC_BASE_URL: ${endpoint} ANTHROPIC_API_KEY: ${DEEPSEEK_API_KEY} tmux: session: claude-work windows: - name: editor command: nvim - name: agent command: claude codex-local: tool: codex endpoint: http://localhost:11434/v1 model: qwen2.5-coder:14b env: OPENAI_BASE_URL: ${endpoint} OPENAI_API_KEY: dummy这个配置定义了两个 profile分别对应 Claude Code 接入 DeepSeek 和 Codex 接入本地 Ollama 模型。启动时只需要执行openrig up claude-deepseek工具会自动设置环境变量、创建 tmux 会话、在指定窗口启动对应的 AI 助手。注意YAML 对缩进极其敏感建议统一使用两个空格缩进并在编辑器中开启 YAML 语法校验。我踩过的坑是用 Tab 缩进导致解析失败排查了半天才发现是缩进字符的问题。2.3 tmux 集成的深层考量把 tmux 集成进来不是拍脑袋的决定。AI 编程助手的工作模式决定了它需要长时间运行的会话——你可能让 Claude Code 在一个窗口里持续分析代码库同时在另一个窗口里手动改代码。如果没有 tmux一旦终端关闭会话就断了之前积累的上下文全部丢失。openrig 对 tmux 的封装做了几件实事自动创建命名会话、按配置划分窗口、在指定窗口注入启动命令。这意味着你执行一条命令后直接进入一个已经布局好的工作环境不需要手动tmux new -s然后再Ctrlb c创建窗口。对于需要同时跑多个 AI 助手的场景这种自动化能省下大量重复操作。我个人的习惯是给每个项目建一个独立的 tmux 会话会话名和项目目录名保持一致。openrig 支持从当前目录名自动推导会话名这个细节很贴心避免了手动指定会话名时打错字导致连到错误会话的问题。3. 核心细节解析与实操要点3.1 Claude Code 接入自定义端点的关键参数Claude Code 默认连接官方端点但在国内环境下或者想接入 DeepSeek 这类模型时需要修改端点地址。核心环境变量是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。这里有个容易忽略的细节Claude Code 对端点的响应格式有要求不是所有兼容 OpenAI 格式的端点都能直接对接。我实测下来DeepSeek 的 API 在 Claude Code 下表现稳定但需要确认模型名称映射正确。比如 DeepSeek 的deepseek-chat模型在 Claude Code 的请求格式下能正常响应但如果你填了deepseek-coder可能会遇到模型不存在或格式不匹配的错误。openrig 的配置里允许单独指定模型名称就是为了解决这类映射问题。另一个关键点是超时设置。Claude Code 默认的超时时间对于本地模型来说可能太短尤其是当你用 Ollama 跑 14B 以上参数的模型时首次加载模型可能需要几十秒。openrig 支持在配置中覆盖超时参数建议本地模型场景下把超时设到 120 秒以上。3.2 Codex CLI 的配置要点与常见陷阱Codex CLI 的配置体系和 Claude Code 不同它使用OPENAI_BASE_URL和OPENAI_API_KEY这两个环境变量。但 Codex 有一个特殊之处它会在启动时校验 API Key 的格式如果你填的是本地模型的 dummy key可能会遇到codex auth token is unavailable这类报错。解决方法是确保OPENAI_API_KEY不为空哪怕填一个占位字符串也行。另外 Codex 的配置文件通常位于~/.codex/config.yamlopenrig 在启动 Codex 时会自动生成或覆盖这个文件。这里有个坑如果你之前手动改过 Codex 的配置openrig 的覆盖可能会让你丢失之前的设置。建议在使用 openrig 之前先备份原有的配置文件。关于 Codex 接入 DeepSeek 的场景需要注意 DeepSeek 的 API 路径和 OpenAI 略有不同。Codex 默认请求/v1/chat/completions而 DeepSeek 的兼容端点也是这个路径所以理论上可以直接对接。但实际使用中我发现 Codex 的某些功能比如代码补全的流式响应对端点的实现有额外要求不是所有兼容端点都能完美支持。3.3 YAML 配置文件的组织与复用技巧随着使用的深入配置文件会越来越多。openrig 支持配置继承和变量引用这是保持配置可维护性的关键。比如你可以定义一个base.yaml存放公共的环境变量和 tmux 布局然后在各个 profile 中通过extends关键字继承。# base.yaml common_env: HTTP_PROXY: HTTPS_PROXY: NO_PROXY: localhost,127.0.0.1 tmux_defaults: history_limit: 50000 mouse: true然后在具体 profile 中引用profiles: my-claude: extends: base tool: claude-code env: ANTHROPIC_BASE_URL: https://api.deepseek.com/v1这种组织方式的好处是当你需要修改代理设置或 tmux 行为时只需要改一处所有 profile 都会生效。我建议把敏感信息如 API Key放在单独的secrets.yaml中并通过.gitignore排除避免误提交到仓库。提示openrig 支持从环境变量读取配置值格式为${VAR_NAME}。这意味着你可以把 API Key 放在 shell 的环境变量里而不是写在 YAML 文件中进一步提升安全性。3.4 tmux 会话布局的实战配置tmux 的配置是 openrig 里最灵活也最容易出问题的部分。一个典型的 AI 编程工作流可能需要三个窗口一个跑编辑器、一个跑 AI 助手、一个跑测试或日志监控。openrig 的 tmux 配置支持定义窗口名称、启动命令和布局方向。我常用的布局是左侧大窗口跑编辑器右侧上下分屏上面跑 Claude Code下面跑终端。对应的配置大概是这样tmux: session: dev windows: - name: code command: nvim layout: main-vertical - name: ai command: claude split: horizontal - name: shell command: bash这里有个细节layout参数控制的是 tmux 的窗格布局main-vertical表示主窗格在左侧其他窗格在右侧垂直排列。如果你不指定布局tmux 会使用默认的平铺方式可能不符合你的使用习惯。建议先在 tmux 里手动调整好布局然后用tmux list-windows查看布局名称再填到配置里。4. 完整实操流程从安装到跑通第一个 Profile4.1 环境准备与依赖安装在开始之前需要确保系统里已经安装了以下基础工具Git、tmux版本 3.0 以上、以及至少一个 AI 编程助手Claude Code 或 Codex CLI。如果你用的是 macOS可以通过 Homebrew 安装Ubuntu 用户用 apt 即可。# macOS brew install tmux git # Ubuntu/Debian sudo apt update sudo apt install tmux gitClaude Code 的安装方式取决于你的使用场景。官方提供了 npm 包和桌面版两种形式。如果你习惯终端操作推荐用 npm 安装npm install -g anthropic-ai/claude-codeCodex CLI 的安装类似也是通过 npm 分发。安装完成后先单独运行一次claude --version和codex --version确认工具本身能正常工作再接入 openrig。这一步很重要因为如果工具本身有问题openrig 的报错信息可能会让你误以为是配置问题。4.2 openrig 的获取与初始化openrig 目前通过源码分发直接 clone 仓库即可git clone https://github.com/your-org/openrig.git cd openrig ./install.sh安装脚本会把 openrig 的可执行文件链接到/usr/local/bin或~/.local/bin具体取决于你的系统权限。安装完成后执行openrig init它会在~/.config/openrig下生成默认的配置目录结构~/.config/openrig/ ├── profiles/ │ ├── default.yaml │ └── examples/ ├── secrets.yaml └── openrig.yamlopenrig.yaml是主配置文件定义了默认的 profile 和全局设置。profiles/目录存放各个场景的配置。secrets.yaml用于存放敏感信息默认权限是 600。4.3 编写第一个可用的 Profile假设我们要配置一个 Claude Code 接入 DeepSeek 的 profile。首先在secrets.yaml中填入 API Keydeepseek_api_key: sk-your-key-here然后在profiles/下新建claude-deepseek.yamlname: claude-deepseek tool: claude-code endpoint: https://api.deepseek.com/v1 model: deepseek-chat env: ANTHROPIC_BASE_URL: ${endpoint} ANTHROPIC_API_KEY: ${deepseek_api_key} API_TIMEOUT_MS: 120000 tmux: session: claude-ds windows: - name: agent command: claude这里有几个参数需要解释。API_TIMEOUT_MS设成 120000 毫秒是为了应对 DeepSeek 在高峰期响应较慢的情况。tmux.session指定了会话名称如果不指定openrig 会用 profile 名称作为默认会话名。启动这个 profile 的命令是openrig up claude-deepseek执行后openrig 会做以下几件事加载 secrets、设置环境变量、检查 tmux 会话是否已存在、创建新会话并启动 Claude Code。如果一切正常你会直接进入一个 tmux 会话里面 Claude Code 已经处于运行状态。4.4 验证与调试第一次启动后建议在 Claude Code 里执行一个简单任务来验证端点连通性。比如输入“列出当前目录下的文件”观察是否能正常返回结果。如果遇到连接错误按以下顺序排查检查ANTHROPIC_BASE_URL是否可达可以用curl手动测试端点。确认 API Key 是否正确加载在 tmux 会话里执行echo $ANTHROPIC_API_KEY查看。查看 openrig 的日志文件通常位于~/.local/share/openrig/logs/。我遇到最多的问题是环境变量没有正确注入。openrig 在启动 tmux 时会传递环境变量但如果你在.bashrc或.zshrc里有覆盖操作可能会导致配置失效。建议在 openrig 的配置里显式声明所有需要的环境变量不要依赖 shell 的默认值。5. 常见问题与排查技巧实录5.1 端点连接类问题速查问题现象可能原因排查方法Claude Code 报连接超时端点地址错误或网络不通用 curl 测试端点可达性Codex 报 auth token unavailableAPI Key 为空或格式不对检查环境变量是否注入模型返回格式错误端点不兼容请求格式确认端点是否支持对应 API本地模型首次响应极慢模型加载耗时增大超时参数至 120s 以上tmux 会话创建失败同名会话已存在先tmux kill-session再重试这个表格里的问题我几乎都遇到过。最典型的是 Codex 的 auth token 问题当时排查了很久最后发现是OPENAI_API_KEY在 tmux 会话里没有被正确传递。openrig 的环境变量注入机制依赖于 tmux 的update-environment配置如果你的 tmux 版本较老可能需要手动在.tmux.conf里加上相关设置。5.2 YAML 解析错误的排查思路YAML 的缩进问题是最常见的错误来源。openrig 在解析配置失败时会输出具体的行号和错误类型但有时候错误信息不够直观。我的经验是先用python -c import yaml; yaml.safe_load(open(config.yaml))单独验证 YAML 文件是否合法排除语法问题后再看 openrig 的逻辑错误。另一个容易忽略的点是 YAML 中的特殊字符。比如 API Key 里如果包含:或#需要加引号。我见过有人把 Key 直接写在 YAML 里结果因为 Key 里有冒号导致解析失败。统一用引号包裹字符串值是个好习惯。5.3 tmux 会话管理的避坑经验tmux 会话的生命周期管理是个容易被低估的问题。openrig 默认在启动时检查会话是否存在如果存在就直接 attach不存在才创建。这个逻辑在大多数情况下没问题但如果你修改了 profile 配置后想重新加载就需要先销毁旧会话。我建议在 openrig 的配置里加一个recreate选项或者在命令行加--force参数。目前 openrig 支持openrig down profile来销毁会话然后重新up。养成修改配置后先 down 再 up 的习惯可以避免很多“配置改了但没生效”的困惑。注意销毁 tmux 会话会丢失会话内的所有运行状态包括 AI 助手已经积累的上下文。如果只是微调配置建议先保存重要输出再操作。5.4 多工具混用时的端口与资源冲突同时运行 Claude Code 和 Codex 时如果两者都配置了本地模型端点可能会遇到端口冲突。比如 Ollama 默认监听 11434 端口如果你同时跑两个实例第二个会启动失败。openrig 本身不管理模型服务的端口但可以在配置里通过环境变量指定不同的端点地址。资源方面本地跑大模型对内存和显存的要求较高。14B 参数的模型量化后大约需要 8-10GB 显存如果同时跑两个模型实例16GB 显存的卡也会吃紧。我的建议是同一时间只跑一个本地模型实例多个 AI 助手共享同一个端点。openrig 的 profile 设计支持这种共享模式只需要在不同的 profile 里填相同的端点地址即可。6. 进阶用法配置复用与团队协作6.1 用 Git 管理 openrig 配置把~/.config/openrig目录纳入 Git 管理是提升效率的关键一步。但要注意排除secrets.yaml或者使用 Git 的skip-worktree功能。我的做法是创建一个单独的私有仓库里面只放 profiles 和主配置secrets 通过环境变量注入。团队协作场景下可以建一个共享的配置仓库每个人 clone 后根据自己的环境微调。openrig 支持配置继承团队可以维护一个base.yaml作为基准个人配置通过extends覆盖差异部分。这样当团队决定更换默认模型端点时只需要改 base 配置所有人的环境都会同步更新。6.2 为不同项目创建独立 Profile我习惯给每个长期项目建一个独立的 profile。比如项目 A 用 Claude Code 接入 DeepSeek项目 B 用 Codex 接入本地 Qwen 模型。profile 名称和项目目录名保持一致这样在项目目录下执行openrig up时openrig 会自动匹配同名 profile。这个自动匹配功能需要在主配置里开启auto_match: true match_strategy: directory_name开启后在/home/user/projects/project-a目录下执行openrig up它会自动查找名为project-a的 profile。如果找不到会回退到默认 profile。这个功能在多个项目间切换时特别省事不需要记住每个项目的 profile 名称。6.3 监控与日志了解 AI 助手在做什么openrig 的日志功能可以记录每次启动的详细过程包括环境变量注入、tmux 命令执行、工具启动输出等。日志默认按天分割存放在~/.local/share/openrig/logs/下。当遇到问题时查看日志往往比盲目猜测更有效。我还会在 tmux 配置里加一个日志窗口用tail -f实时监控 openrig 的日志输出。这样在 AI 助手运行过程中出现的警告或错误能第一时间发现。对于需要长时间运行的任务这种实时监控能帮你及时发现问题而不是等任务跑完了才发现中间出了错。7. 我个人在实际操作中的几点体会折腾 openrig 这套东西有大半年了最大的感受是配置管理这件事前期投入的时间会在后期成倍地省回来。一开始手动改配置文件看似快但当你需要在三台机器、五个项目之间切换时没有统一的配置管理简直就是灾难。另一个体会是关于 YAML 的。很多人觉得 YAML 简单但真正写好一份可维护的 YAML 配置需要不少经验。我的建议是配置项命名要统一风格注释要写清楚每个非直观参数的作用敏感信息一律外置。这三点做到了配置的可读性和可维护性会有质的提升。最后分享一个小技巧openrig 的 profile 支持description字段我习惯在每个 profile 里写一句话说明这个配置的用途和适用场景。过几个月回头看的时候这个描述能帮你快速回忆起当时为什么这么配。好记性不如烂笔头在配置管理这件事上尤其如此。
1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”这个词在英文里常指设备支架或矿机机架。但在当前 AI 编程工具爆发的语境下openrig 实际上是一个围绕 Claude Code、Codex 这类终端 AI 编程助手构建的开源配置管理与工作流编排工具。它的核心价值用一句话概括让你在多个 AI 编程助手之间自由切换、统一管理配置、复用会话上下文而不是被某一家工具锁死。我最初接触这个领域是因为一个很现实的痛点。团队里有人用 Claude Code有人用 Codex CLI还有人因为网络或成本原因想接入 DeepSeek 这类国产模型。每个人的配置文件散落在不同的目录下YAML 格式各不相同tmux 会话管理也各搞各的。每次换人接手或者换机器部署光是把环境跑通就要折腾大半天。openrig 出现的意义就是把这些碎片化的配置和启动流程收敛到一套可版本控制、可复用的框架里。它适合什么人如果你是刚接触 Claude Code 或 Codex 的新手openrig 能帮你跳过大量手动配置的坑如果你是多工具混用的老手它能帮你把 YAML 配置、tmux 会话、模型端点这些琐事统一管理起来。哪怕你只是想在国内环境下稳定使用 Codex 或 Claude Code理解 openrig 的设计思路也能让你少走很多弯路。提示openrig 本身不是一个模型也不是一个代理工具它是一层“配置编排层”。理解这一点很关键否则很容易把它和各类网络工具混淆。2. openrig 的核心设计思路拆解2.1 为什么需要一层“编排层”Claude Code 和 Codex CLI 这类工具的原生配置方式各有各的逻辑。Claude Code 依赖~/.claude目录下的配置文件Codex 则有自己的~/.codex配置体系。当你同时使用多个工具或者需要在不同项目间切换不同的模型端点时手动改配置就成了噩梦。更麻烦的是很多配置项是互斥的——比如你不可能在同一个终端会话里同时让 Claude Code 和 Codex 都占用默认端口。openrig 的设计思路借鉴了基础设施即代码的理念。它把每个 AI 编程助手的启动配置抽象成一份 YAML 文件通过统一的命令行入口来加载不同的配置组合。这样做的好处是配置可以纳入 Git 版本控制团队可以共享同一套基准配置新人入职只需要 clone 仓库然后执行一条启动命令。我实测下来这种设计最大的优势在于“可复现”。以前帮同事排查 Claude Code 连不上本地模型的问题得让他把配置文件截图发过来一来一回半小时。现在只要让他把 openrig 的配置目录打包发过来我本地一跑就能复现问题。2.2 YAML 作为配置载体的取舍为什么选 YAML 而不是 JSON 或 TOML这个问题我在项目初期也纠结过。JSON 的问题是没法写注释而 AI 编程工具的配置里有大量需要说明的地方比如某个端点为什么这么设、某个环境变量是干什么的。TOML 虽然可读性好但在嵌套结构表达上不如 YAML 直观。YAML 的缩进语法虽然容易出错但配合编辑器的语法检查实际使用中问题不大。openrig 的 YAML 配置通常包含几个核心区块模型端点定义、工具启动参数、环境变量注入、tmux 会话布局。下面是一个典型的配置结构示例# openrig 配置示例 version: 1 profiles: claude-deepseek: tool: claude-code endpoint: https://api.deepseek.com/v1 model: deepseek-chat env: ANTHROPIC_BASE_URL: ${endpoint} ANTHROPIC_API_KEY: ${DEEPSEEK_API_KEY} tmux: session: claude-work windows: - name: editor command: nvim - name: agent command: claude codex-local: tool: codex endpoint: http://localhost:11434/v1 model: qwen2.5-coder:14b env: OPENAI_BASE_URL: ${endpoint} OPENAI_API_KEY: dummy这个配置定义了两个 profile分别对应 Claude Code 接入 DeepSeek 和 Codex 接入本地 Ollama 模型。启动时只需要执行openrig up claude-deepseek工具会自动设置环境变量、创建 tmux 会话、在指定窗口启动对应的 AI 助手。注意YAML 对缩进极其敏感建议统一使用两个空格缩进并在编辑器中开启 YAML 语法校验。我踩过的坑是用 Tab 缩进导致解析失败排查了半天才发现是缩进字符的问题。2.3 tmux 集成的深层考量把 tmux 集成进来不是拍脑袋的决定。AI 编程助手的工作模式决定了它需要长时间运行的会话——你可能让 Claude Code 在一个窗口里持续分析代码库同时在另一个窗口里手动改代码。如果没有 tmux一旦终端关闭会话就断了之前积累的上下文全部丢失。openrig 对 tmux 的封装做了几件实事自动创建命名会话、按配置划分窗口、在指定窗口注入启动命令。这意味着你执行一条命令后直接进入一个已经布局好的工作环境不需要手动tmux new -s然后再Ctrlb c创建窗口。对于需要同时跑多个 AI 助手的场景这种自动化能省下大量重复操作。我个人的习惯是给每个项目建一个独立的 tmux 会话会话名和项目目录名保持一致。openrig 支持从当前目录名自动推导会话名这个细节很贴心避免了手动指定会话名时打错字导致连到错误会话的问题。3. 核心细节解析与实操要点3.1 Claude Code 接入自定义端点的关键参数Claude Code 默认连接官方端点但在国内环境下或者想接入 DeepSeek 这类模型时需要修改端点地址。核心环境变量是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。这里有个容易忽略的细节Claude Code 对端点的响应格式有要求不是所有兼容 OpenAI 格式的端点都能直接对接。我实测下来DeepSeek 的 API 在 Claude Code 下表现稳定但需要确认模型名称映射正确。比如 DeepSeek 的deepseek-chat模型在 Claude Code 的请求格式下能正常响应但如果你填了deepseek-coder可能会遇到模型不存在或格式不匹配的错误。openrig 的配置里允许单独指定模型名称就是为了解决这类映射问题。另一个关键点是超时设置。Claude Code 默认的超时时间对于本地模型来说可能太短尤其是当你用 Ollama 跑 14B 以上参数的模型时首次加载模型可能需要几十秒。openrig 支持在配置中覆盖超时参数建议本地模型场景下把超时设到 120 秒以上。3.2 Codex CLI 的配置要点与常见陷阱Codex CLI 的配置体系和 Claude Code 不同它使用OPENAI_BASE_URL和OPENAI_API_KEY这两个环境变量。但 Codex 有一个特殊之处它会在启动时校验 API Key 的格式如果你填的是本地模型的 dummy key可能会遇到codex auth token is unavailable这类报错。解决方法是确保OPENAI_API_KEY不为空哪怕填一个占位字符串也行。另外 Codex 的配置文件通常位于~/.codex/config.yamlopenrig 在启动 Codex 时会自动生成或覆盖这个文件。这里有个坑如果你之前手动改过 Codex 的配置openrig 的覆盖可能会让你丢失之前的设置。建议在使用 openrig 之前先备份原有的配置文件。关于 Codex 接入 DeepSeek 的场景需要注意 DeepSeek 的 API 路径和 OpenAI 略有不同。Codex 默认请求/v1/chat/completions而 DeepSeek 的兼容端点也是这个路径所以理论上可以直接对接。但实际使用中我发现 Codex 的某些功能比如代码补全的流式响应对端点的实现有额外要求不是所有兼容端点都能完美支持。3.3 YAML 配置文件的组织与复用技巧随着使用的深入配置文件会越来越多。openrig 支持配置继承和变量引用这是保持配置可维护性的关键。比如你可以定义一个base.yaml存放公共的环境变量和 tmux 布局然后在各个 profile 中通过extends关键字继承。# base.yaml common_env: HTTP_PROXY: HTTPS_PROXY: NO_PROXY: localhost,127.0.0.1 tmux_defaults: history_limit: 50000 mouse: true然后在具体 profile 中引用profiles: my-claude: extends: base tool: claude-code env: ANTHROPIC_BASE_URL: https://api.deepseek.com/v1这种组织方式的好处是当你需要修改代理设置或 tmux 行为时只需要改一处所有 profile 都会生效。我建议把敏感信息如 API Key放在单独的secrets.yaml中并通过.gitignore排除避免误提交到仓库。提示openrig 支持从环境变量读取配置值格式为${VAR_NAME}。这意味着你可以把 API Key 放在 shell 的环境变量里而不是写在 YAML 文件中进一步提升安全性。3.4 tmux 会话布局的实战配置tmux 的配置是 openrig 里最灵活也最容易出问题的部分。一个典型的 AI 编程工作流可能需要三个窗口一个跑编辑器、一个跑 AI 助手、一个跑测试或日志监控。openrig 的 tmux 配置支持定义窗口名称、启动命令和布局方向。我常用的布局是左侧大窗口跑编辑器右侧上下分屏上面跑 Claude Code下面跑终端。对应的配置大概是这样tmux: session: dev windows: - name: code command: nvim layout: main-vertical - name: ai command: claude split: horizontal - name: shell command: bash这里有个细节layout参数控制的是 tmux 的窗格布局main-vertical表示主窗格在左侧其他窗格在右侧垂直排列。如果你不指定布局tmux 会使用默认的平铺方式可能不符合你的使用习惯。建议先在 tmux 里手动调整好布局然后用tmux list-windows查看布局名称再填到配置里。4. 完整实操流程从安装到跑通第一个 Profile4.1 环境准备与依赖安装在开始之前需要确保系统里已经安装了以下基础工具Git、tmux版本 3.0 以上、以及至少一个 AI 编程助手Claude Code 或 Codex CLI。如果你用的是 macOS可以通过 Homebrew 安装Ubuntu 用户用 apt 即可。# macOS brew install tmux git # Ubuntu/Debian sudo apt update sudo apt install tmux gitClaude Code 的安装方式取决于你的使用场景。官方提供了 npm 包和桌面版两种形式。如果你习惯终端操作推荐用 npm 安装npm install -g anthropic-ai/claude-codeCodex CLI 的安装类似也是通过 npm 分发。安装完成后先单独运行一次claude --version和codex --version确认工具本身能正常工作再接入 openrig。这一步很重要因为如果工具本身有问题openrig 的报错信息可能会让你误以为是配置问题。4.2 openrig 的获取与初始化openrig 目前通过源码分发直接 clone 仓库即可git clone https://github.com/your-org/openrig.git cd openrig ./install.sh安装脚本会把 openrig 的可执行文件链接到/usr/local/bin或~/.local/bin具体取决于你的系统权限。安装完成后执行openrig init它会在~/.config/openrig下生成默认的配置目录结构~/.config/openrig/ ├── profiles/ │ ├── default.yaml │ └── examples/ ├── secrets.yaml └── openrig.yamlopenrig.yaml是主配置文件定义了默认的 profile 和全局设置。profiles/目录存放各个场景的配置。secrets.yaml用于存放敏感信息默认权限是 600。4.3 编写第一个可用的 Profile假设我们要配置一个 Claude Code 接入 DeepSeek 的 profile。首先在secrets.yaml中填入 API Keydeepseek_api_key: sk-your-key-here然后在profiles/下新建claude-deepseek.yamlname: claude-deepseek tool: claude-code endpoint: https://api.deepseek.com/v1 model: deepseek-chat env: ANTHROPIC_BASE_URL: ${endpoint} ANTHROPIC_API_KEY: ${deepseek_api_key} API_TIMEOUT_MS: 120000 tmux: session: claude-ds windows: - name: agent command: claude这里有几个参数需要解释。API_TIMEOUT_MS设成 120000 毫秒是为了应对 DeepSeek 在高峰期响应较慢的情况。tmux.session指定了会话名称如果不指定openrig 会用 profile 名称作为默认会话名。启动这个 profile 的命令是openrig up claude-deepseek执行后openrig 会做以下几件事加载 secrets、设置环境变量、检查 tmux 会话是否已存在、创建新会话并启动 Claude Code。如果一切正常你会直接进入一个 tmux 会话里面 Claude Code 已经处于运行状态。4.4 验证与调试第一次启动后建议在 Claude Code 里执行一个简单任务来验证端点连通性。比如输入“列出当前目录下的文件”观察是否能正常返回结果。如果遇到连接错误按以下顺序排查检查ANTHROPIC_BASE_URL是否可达可以用curl手动测试端点。确认 API Key 是否正确加载在 tmux 会话里执行echo $ANTHROPIC_API_KEY查看。查看 openrig 的日志文件通常位于~/.local/share/openrig/logs/。我遇到最多的问题是环境变量没有正确注入。openrig 在启动 tmux 时会传递环境变量但如果你在.bashrc或.zshrc里有覆盖操作可能会导致配置失效。建议在 openrig 的配置里显式声明所有需要的环境变量不要依赖 shell 的默认值。5. 常见问题与排查技巧实录5.1 端点连接类问题速查问题现象可能原因排查方法Claude Code 报连接超时端点地址错误或网络不通用 curl 测试端点可达性Codex 报 auth token unavailableAPI Key 为空或格式不对检查环境变量是否注入模型返回格式错误端点不兼容请求格式确认端点是否支持对应 API本地模型首次响应极慢模型加载耗时增大超时参数至 120s 以上tmux 会话创建失败同名会话已存在先tmux kill-session再重试这个表格里的问题我几乎都遇到过。最典型的是 Codex 的 auth token 问题当时排查了很久最后发现是OPENAI_API_KEY在 tmux 会话里没有被正确传递。openrig 的环境变量注入机制依赖于 tmux 的update-environment配置如果你的 tmux 版本较老可能需要手动在.tmux.conf里加上相关设置。5.2 YAML 解析错误的排查思路YAML 的缩进问题是最常见的错误来源。openrig 在解析配置失败时会输出具体的行号和错误类型但有时候错误信息不够直观。我的经验是先用python -c import yaml; yaml.safe_load(open(config.yaml))单独验证 YAML 文件是否合法排除语法问题后再看 openrig 的逻辑错误。另一个容易忽略的点是 YAML 中的特殊字符。比如 API Key 里如果包含:或#需要加引号。我见过有人把 Key 直接写在 YAML 里结果因为 Key 里有冒号导致解析失败。统一用引号包裹字符串值是个好习惯。5.3 tmux 会话管理的避坑经验tmux 会话的生命周期管理是个容易被低估的问题。openrig 默认在启动时检查会话是否存在如果存在就直接 attach不存在才创建。这个逻辑在大多数情况下没问题但如果你修改了 profile 配置后想重新加载就需要先销毁旧会话。我建议在 openrig 的配置里加一个recreate选项或者在命令行加--force参数。目前 openrig 支持openrig down profile来销毁会话然后重新up。养成修改配置后先 down 再 up 的习惯可以避免很多“配置改了但没生效”的困惑。注意销毁 tmux 会话会丢失会话内的所有运行状态包括 AI 助手已经积累的上下文。如果只是微调配置建议先保存重要输出再操作。5.4 多工具混用时的端口与资源冲突同时运行 Claude Code 和 Codex 时如果两者都配置了本地模型端点可能会遇到端口冲突。比如 Ollama 默认监听 11434 端口如果你同时跑两个实例第二个会启动失败。openrig 本身不管理模型服务的端口但可以在配置里通过环境变量指定不同的端点地址。资源方面本地跑大模型对内存和显存的要求较高。14B 参数的模型量化后大约需要 8-10GB 显存如果同时跑两个模型实例16GB 显存的卡也会吃紧。我的建议是同一时间只跑一个本地模型实例多个 AI 助手共享同一个端点。openrig 的 profile 设计支持这种共享模式只需要在不同的 profile 里填相同的端点地址即可。6. 进阶用法配置复用与团队协作6.1 用 Git 管理 openrig 配置把~/.config/openrig目录纳入 Git 管理是提升效率的关键一步。但要注意排除secrets.yaml或者使用 Git 的skip-worktree功能。我的做法是创建一个单独的私有仓库里面只放 profiles 和主配置secrets 通过环境变量注入。团队协作场景下可以建一个共享的配置仓库每个人 clone 后根据自己的环境微调。openrig 支持配置继承团队可以维护一个base.yaml作为基准个人配置通过extends覆盖差异部分。这样当团队决定更换默认模型端点时只需要改 base 配置所有人的环境都会同步更新。6.2 为不同项目创建独立 Profile我习惯给每个长期项目建一个独立的 profile。比如项目 A 用 Claude Code 接入 DeepSeek项目 B 用 Codex 接入本地 Qwen 模型。profile 名称和项目目录名保持一致这样在项目目录下执行openrig up时openrig 会自动匹配同名 profile。这个自动匹配功能需要在主配置里开启auto_match: true match_strategy: directory_name开启后在/home/user/projects/project-a目录下执行openrig up它会自动查找名为project-a的 profile。如果找不到会回退到默认 profile。这个功能在多个项目间切换时特别省事不需要记住每个项目的 profile 名称。6.3 监控与日志了解 AI 助手在做什么openrig 的日志功能可以记录每次启动的详细过程包括环境变量注入、tmux 命令执行、工具启动输出等。日志默认按天分割存放在~/.local/share/openrig/logs/下。当遇到问题时查看日志往往比盲目猜测更有效。我还会在 tmux 配置里加一个日志窗口用tail -f实时监控 openrig 的日志输出。这样在 AI 助手运行过程中出现的警告或错误能第一时间发现。对于需要长时间运行的任务这种实时监控能帮你及时发现问题而不是等任务跑完了才发现中间出了错。7. 我个人在实际操作中的几点体会折腾 openrig 这套东西有大半年了最大的感受是配置管理这件事前期投入的时间会在后期成倍地省回来。一开始手动改配置文件看似快但当你需要在三台机器、五个项目之间切换时没有统一的配置管理简直就是灾难。另一个体会是关于 YAML 的。很多人觉得 YAML 简单但真正写好一份可维护的 YAML 配置需要不少经验。我的建议是配置项命名要统一风格注释要写清楚每个非直观参数的作用敏感信息一律外置。这三点做到了配置的可读性和可维护性会有质的提升。最后分享一个小技巧openrig 的 profile 支持description字段我习惯在每个 profile 里写一句话说明这个配置的用途和适用场景。过几个月回头看的时候这个描述能帮你快速回忆起当时为什么这么配。好记性不如烂笔头在配置管理这件事上尤其如此。
