1. 从“openrig”说起一个被低估的本地AI编码环境编排思路第一次看到“openrig”这个词我下意识地把它拆成了“open”和“rig”两部分。rig在英文里有“装配、搭建、临时组合一套设备”的意思比如广播行业里把一套完整的录制设备组合叫rig卡车司机把整台车的改装配置也叫rig。所以openrig这个词本质上指向的是一件事用开放、可组合的方式把一套AI编码工具链装配起来。结合热搜词里高频出现的Claude Code、Codex、YAML、tmux这几个关键词我基本能判断出openrig要解决的核心问题在本地或自有服务器上把多个AI编码助手Claude Code、Codex CLI等通过配置文件YAML和终端复用工具tmux编排成一套可切换、可并行、可持久化的工作环境。它不是某一个具体的软件而是一种“装配思路”——就像你不会把工具箱里的每一把螺丝刀都焊死在一张桌子上而是需要一个可以随时取用、随时替换的挂架。这套东西适合谁三类人最需要第一类是在国内网络环境下想稳定使用Claude Code和Codex的开发者第二类是需要在多个AI编码助手之间频繁切换对比效果的工程师第三类是希望把AI编码能力接入本地模型比如通过LM Studio跑本地模型的技术玩家。如果你只是偶尔用网页版问几个问题那openrig这套思路对你来说太重了但如果你每天有大量编码任务要交给AI处理一套装配良好的本地环境能省下你大量重复配置的时间。我自己的使用场景是这样的白天写业务代码时用Claude Code做代码审查和重构建议晚上跑实验性项目时切到Codex做快速原型生成同时还要在tmux里保持几个会话不中断。如果没有一套统一的编排思路光是切换工具、重配环境、恢复会话就能把人的耐心磨光。openrig要解决的就是这种“工具多了反而更累”的问题。2. 核心组件拆解Claude Code、Codex、YAML、tmux各自扮演什么角色2.1 Claude Code终端里的结对编程搭档Claude Code是Anthropic推出的终端AI编码工具它和网页版Claude最大的区别在于它直接跑在你的终端里能读写你本地的文件能执行命令能理解你整个项目的上下文。你可以把它理解成一个坐在你旁边、能直接操作你键盘的结对编程搭档而不是一个只能聊天的顾问。安装Claude Code的方式在不同系统上略有差异。Ubuntu和macOS下通常通过npm全局安装npm install -g anthropic-ai/claude-codeWindows下则建议在WSL2环境里操作因为Claude Code对Unix风格的路径和权限管理依赖较重。安装完成后第一次运行claude命令会引导你完成认证。这里有个坑要注意如果你所在的组织禁用了Claude订阅访问你会看到“your organization has disabled claude subscription access for claude code”这类提示这时候你需要用API key的方式认证而不是订阅账号登录。Claude Code的核心能力包括读取项目文件、执行shell命令、生成和修改代码、运行测试、解释报错。它最让我满意的一点是1M上下文窗口的支持这意味着你可以把整个中型项目的关键文件都塞给它它能在全局视角下给出建议而不是像某些工具那样只能看单个文件。2.2 Codex另一条技术路线的编码助手Codex是OpenAI推出的编码工具有CLI版本也有桌面版。它和Claude Code的定位类似但风格不同。Codex在代码补全和快速生成方面反应更快适合做“写一个函数”“生成一个组件”这类短平快的任务Claude Code则在长上下文理解和复杂重构上更有优势。Codex的安装方式npm install -g openai/codex或者从官网下载桌面版安装包。国内使用Codex需要注意网络问题这里不展开。Codex的认证方式支持API key和登录两种如果遇到“codex auth token is unavailable”的报错通常是认证信息过期或环境变量没配好重新执行codex login或者检查OPENAI_API_KEY环境变量即可。Codex还有一个很实用的能力接入DeepSeek等第三方模型。通过配置base URL和API key你可以让Codex CLI调用DeepSeek的接口这在成本和效果之间提供了一个不错的平衡点。配置方式通常是在~/.codex/config.yaml里指定provider和model。2.3 YAML整个编排体系的“接线图”YAML在这个体系里扮演的是配置文件的角色。Claude Code、Codex、以及各种周边工具都通过YAML文件来定义行为。比如Claude Code的项目级配置可以放在.claude/settings.yaml里定义允许执行的命令、忽略的文件、默认模型等。Codex的配置放在~/.codex/config.yaml定义provider、model、temperature等参数。tmux的会话布局可以用YAML描述然后通过脚本加载。YAML的好处是人类可读、结构清晰、易于版本控制。你可以把整套openrig的配置放在一个git仓库里换机器时clone下来就能恢复工作环境。这比记一堆命令行参数靠谱得多。一个典型的Codex配置示例model: gpt-4-codex provider: openai temperature: 0.2 max_tokens: 4096如果要接入DeepSeekmodel: deepseek-coder provider: custom base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY}注意${DEEPSEEK_API_KEY}这种写法它表示从环境变量读取避免把密钥硬编码在配置文件里。这是基本的安全习惯。2.4 tmux让AI会话“永不掉线”的容器tmux是终端复用工具它的核心价值是会话持久化。你开一个tmux会话在里面跑Claude Code然后关掉终端窗口会话依然在后台运行。下次连上来tmux attach就能恢复现场。对于需要长时间运行的AI任务比如让Claude Code重构一个大模块这个特性太重要了。tmux的基本操作tmux new -s claude-session # 新建名为claude-session的会话 tmux ls # 列出所有会话 tmux attach -t claude-session # 重新接入会话 tmux kill-session -t claude-session # 结束会话在openrig的编排思路里tmux通常和YAML配合使用用YAML定义窗口布局和启动命令用脚本一键创建整个工作环境。比如你可以定义一个三窗口布局窗口1跑Claude Code窗口2跑Codex窗口3跑本地模型服务。3. 装配实操从零搭建一套可切换的AI编码环境3.1 环境准备与依赖安装在开始装配之前先确认基础环境。我推荐Ubuntu 22.04或macOSWindows用户建议用WSL2。需要的基础组件Node.js 18Claude Code和Codex CLI都依赖npm或pnpmtmux 3.0git安装命令# Ubuntu sudo apt update sudo apt install -y nodejs npm tmux git # macOS brew install node tmux gitNode.js版本建议用nvm管理方便切换curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 20 nvm use 20安装完基础环境后分别安装Claude Code和Codexnpm install -g anthropic-ai/claude-code npm install -g openai/codex验证安装claude --version codex --version如果这两个命令都能输出版本号说明基础环境就绪。3.2 用YAML定义统一配置接下来是openrig的核心用YAML把配置统一管理起来。我建议在~/openrig/目录下建立如下结构~/openrig/ ├── configs/ │ ├── claude.yaml │ ├── codex.yaml │ └── tmux.yaml ├── scripts/ │ ├── start-claude.sh │ ├── start-codex.sh │ └── start-all.sh └── README.mdclaude.yaml示例model: claude-sonnet-4-20250514 max_tokens: 8192 allowed_commands: - git - npm - python - ls - cat ignore_patterns: - *.log - node_modules/ - .git/codex.yaml示例model: gpt-4-codex temperature: 0.2 max_tokens: 4096 provider: openaitmux.yaml用来描述会话布局session: openrig windows: - name: claude command: claude - name: codex command: codex - name: shell command: bash这个YAML不是tmux原生支持的格式而是我自己的约定通过脚本解析后生成对应的tmux命令。这样做的好处是配置集中、可读性强。3.3 编写一键启动脚本start-all.sh的核心逻辑#!/bin/bash SESSIONopenrig # 如果会话已存在直接接入 tmux has-session -t $SESSION 2/dev/null if [ $? -eq 0 ]; then tmux attach -t $SESSION exit 0 fi # 创建新会话第一个窗口跑Claude Code tmux new-session -d -s $SESSION -n claude tmux send-keys -t $SESSION:claude claude C-m # 第二个窗口跑Codex tmux new-window -t $SESSION -n codex tmux send-keys -t $SESSION:codex codex C-m # 第三个窗口留作普通shell tmux new-window -t $SESSION -n shell # 默认选中第一个窗口 tmux select-window -t $SESSION:claude # 接入会话 tmux attach -t $SESSION这个脚本做了几件事检查会话是否存在、创建三个窗口、在每个窗口里启动对应的工具、最后接入会话。你可以把它放到~/.local/bin/下加个别名alias rigbash ~/openrig/scripts/start-all.sh以后敲一个rig就能进入完整工作环境。3.4 配置切换与本地模型接入如果你需要在Claude Code和Codex之间切换或者让它们接入本地模型比如通过LM Studio跑的模型YAML配置就体现出价值了。以Claude Code接入本地模型为例你需要设置环境变量export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlocal-model然后在claude.yaml里指定model为本地模型的名称。LM Studio默认监听1234端口启动后在界面里加载模型即可。Codex接入DeepSeek的配置前面已经提过核心是base_url和api_key两项。这里有个经验DeepSeek的API在代码生成任务上表现不错但响应格式和OpenAI不完全一致偶尔会出现解析错误。如果遇到这种情况检查Codex版本是否支持自定义provider或者用中间层做格式转换。4. 常见问题与排查技巧实录4.1 安装与认证类问题问题一Claude Code安装后运行报权限错误Ubuntu下常见原因是npm全局目录权限不对。解决方法mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到~/.bashrc里重新source一下。问题二Codex提示“auth token is unavailable”这个报错通常有三种原因API key没设置、key过期、或者环境变量没被正确读取。排查顺序检查echo $OPENAI_API_KEY是否有输出检查~/.codex/config.yaml里的provider配置重新执行codex login走一遍认证流程问题三组织禁用了Claude订阅访问如果你看到“your organization has disabled claude subscription access for claude code”说明你的账号所属组织限制了订阅方式访问。这时候需要用API key认证在claude.yaml里配置api_key字段或者设置ANTHROPIC_API_KEY环境变量。4.2 运行与性能类问题问题四tmux会话里的AI工具输出乱码这通常是终端类型不匹配导致的。在~/.tmux.conf里加上set -g default-terminal screen-256color然后重启tmux会话。问题五Claude Code处理大项目时响应慢1M上下文虽然强大但塞太多文件进去也会拖慢响应。我的做法是用.claudeignore文件排除无关目录比如node_modules/、dist/、*.log。只把核心源码目录暴露给Claude Code响应速度会明显提升。问题六Codex接入本地模型后输出格式错乱本地模型尤其是量化版本在指令遵循上不如云端大模型稳定。解决方法是在YAML里把temperature调低到0.1以下并且在prompt里明确要求“只输出代码不要解释”。如果还是不行考虑换一个指令遵循能力更强的本地模型。4.3 配置管理类问题问题七YAML缩进错误导致配置不生效YAML对缩进极其敏感tab和空格混用会直接报错。建议在编辑器里设置“tab转空格”并且用yamllint做校验pip install yamllint yamllint ~/openrig/configs/问题八多台机器之间同步配置把~/openrig/目录做成git仓库.gitignore里排除包含密钥的文件用环境变量或单独的secrets.yaml不纳入版本控制管理敏感信息。换机器时clone下来装好依赖基本能一键恢复。4.4 常见问题速查表问题现象可能原因排查方向Claude Code报权限错误npm全局目录权限不对重设npm prefixCodex提示auth token unavailableAPI key未设置或过期检查环境变量和config.yaml组织禁用订阅访问账号组织策略限制改用API key认证tmux输出乱码终端类型不匹配设置default-terminal大项目响应慢上下文塞太多文件配置ignore规则本地模型输出格式错乱指令遵循能力不足降低temperature明确promptYAML配置不生效缩进错误用yamllint校验多机同步困难配置散落各处统一到git仓库管理5. 进阶玩法把openrig思路扩展到更多场景5.1 多模型并行对比openrig的编排思路不限于Claude Code和Codex。你可以在tmux里开四个窗口分别跑Claude Code、Codex、本地LM Studio模型、以及DeepSeek接入的Codex同一个问题同时抛给四个工具对比输出质量。这种做法在选型阶段特别有用——与其看别人的评测不如用自己的真实任务跑一遍。具体操作在tmux.yaml里定义四个窗口每个窗口的启动命令不同。比如窗口4的启动命令是export OPENAI_BASE_URLhttps://api.deepseek.com/v1 export OPENAI_API_KEY${DEEPSEEK_API_KEY} codex --model deepseek-coder这样四个窗口各自独立互不干扰你可以随时切换查看。5.2 与VS Code的联动虽然Claude Code和Codex都是终端工具但你可以把它们和VS Code结合起来用。一种做法是在VS Code的集成终端里跑tmux会话这样编辑器里就能直接看到AI工具的输出。另一种做法是用VS Code的任务系统tasks.json调用openrig的启动脚本一键拉起整个环境。VS Code配置Claude Code的关键是确保集成终端的环境变量和外部终端一致。有时候在外部终端能跑的配置在VS Code里报错就是因为VS Code没有加载~/.bashrc。解决方法是在VS Code设置里把terminal.integrated.inheritEnv设为true或者直接在tasks.json里显式设置环境变量。5.3 会话持久化与远程接入tmux最大的价值在于会话持久化。你可以在家里的服务器上跑一个openrig会话然后从公司电脑通过SSH接入。具体流程服务器上执行rig启动会话公司电脑SSH到服务器执行tmux attach -t openrig恢复现场这样你的AI编码环境就变成了一个“常驻服务”不管换哪台电脑接上来就能继续之前的工作。对于需要长时间运行的AI任务比如让Claude Code批量重构几十个文件这个特性几乎是刚需。5.4 配置版本化与团队共享如果你在团队里推广这套工具可以把openrig配置做成模板仓库。新成员clone下来改一下secrets.yaml里的个人密钥执行安装脚本就能获得一致的工作环境。这比口头传授“你先装这个再装那个”高效得多。模板仓库里应该包含YAML配置模板、启动脚本、安装脚本、README说明、以及一个secrets.yaml.example示例文件。.gitignore里排除secrets.yaml和任何包含真实密钥的文件。6. 我踩过的坑与实操心得先说一个最容易被忽略的坑tmux里的环境变量和外部shell不一定一致。我有一次在外部终端配好了ANTHROPIC_API_KEY进tmux跑Claude Code却提示认证失败。排查了半天才发现tmux会话是在配置环境变量之前创建的它继承的是旧的环境。解决方法要么是重建会话要么在tmux里手动export一遍。后来我在启动脚本里加了显式的环境变量加载这个问题就再没出现过。第二个坑是关于YAML的。我一开始把Claude Code的配置写在项目根目录的.claude.yaml里结果怎么都不生效。后来查文档才发现Claude Code读取的是.claude/settings.yaml路径不对。不同工具对配置文件的路径和命名要求不一样一定要查清楚再写。Codex是~/.codex/config.yamlClaude Code是.claude/settings.yamltmux是~/.tmux.conf三者互不通用。第三个坑是本地模型的端口冲突。我在LM Studio里加载了模型默认监听1234端口同时另一个服务也占了1234导致Claude Code连不上。跑本地模型之前先用lsof -i :1234检查端口占用这个习惯能省很多排查时间。第四个坑是关于Codex接入第三方模型的。DeepSeek的API返回格式和OpenAI有细微差异Codex CLI在某些版本里会解析失败。我的做法是先用curl手动测试API返回格式确认没问题再配到Codex里。如果格式确实不兼容考虑用one-api这类中间层做转换。最后一个心得不要把openrig搞得太复杂。我一开始想把所有工具、所有模型、所有配置都塞进一套YAML里结果配置文件比代码还长维护成本极高。后来我做了减法只保留最常用的两个工具Claude Code和Codex配置只写必要的字段其余用默认值。这套精简后的配置反而更稳定换机器恢复也更快。工具是拿来用的不是拿来供着的。
openrig：用YAML和tmux编排Claude Code与Codex本地AI编码环境
1. 从“openrig”说起一个被低估的本地AI编码环境编排思路第一次看到“openrig”这个词我下意识地把它拆成了“open”和“rig”两部分。rig在英文里有“装配、搭建、临时组合一套设备”的意思比如广播行业里把一套完整的录制设备组合叫rig卡车司机把整台车的改装配置也叫rig。所以openrig这个词本质上指向的是一件事用开放、可组合的方式把一套AI编码工具链装配起来。结合热搜词里高频出现的Claude Code、Codex、YAML、tmux这几个关键词我基本能判断出openrig要解决的核心问题在本地或自有服务器上把多个AI编码助手Claude Code、Codex CLI等通过配置文件YAML和终端复用工具tmux编排成一套可切换、可并行、可持久化的工作环境。它不是某一个具体的软件而是一种“装配思路”——就像你不会把工具箱里的每一把螺丝刀都焊死在一张桌子上而是需要一个可以随时取用、随时替换的挂架。这套东西适合谁三类人最需要第一类是在国内网络环境下想稳定使用Claude Code和Codex的开发者第二类是需要在多个AI编码助手之间频繁切换对比效果的工程师第三类是希望把AI编码能力接入本地模型比如通过LM Studio跑本地模型的技术玩家。如果你只是偶尔用网页版问几个问题那openrig这套思路对你来说太重了但如果你每天有大量编码任务要交给AI处理一套装配良好的本地环境能省下你大量重复配置的时间。我自己的使用场景是这样的白天写业务代码时用Claude Code做代码审查和重构建议晚上跑实验性项目时切到Codex做快速原型生成同时还要在tmux里保持几个会话不中断。如果没有一套统一的编排思路光是切换工具、重配环境、恢复会话就能把人的耐心磨光。openrig要解决的就是这种“工具多了反而更累”的问题。2. 核心组件拆解Claude Code、Codex、YAML、tmux各自扮演什么角色2.1 Claude Code终端里的结对编程搭档Claude Code是Anthropic推出的终端AI编码工具它和网页版Claude最大的区别在于它直接跑在你的终端里能读写你本地的文件能执行命令能理解你整个项目的上下文。你可以把它理解成一个坐在你旁边、能直接操作你键盘的结对编程搭档而不是一个只能聊天的顾问。安装Claude Code的方式在不同系统上略有差异。Ubuntu和macOS下通常通过npm全局安装npm install -g anthropic-ai/claude-codeWindows下则建议在WSL2环境里操作因为Claude Code对Unix风格的路径和权限管理依赖较重。安装完成后第一次运行claude命令会引导你完成认证。这里有个坑要注意如果你所在的组织禁用了Claude订阅访问你会看到“your organization has disabled claude subscription access for claude code”这类提示这时候你需要用API key的方式认证而不是订阅账号登录。Claude Code的核心能力包括读取项目文件、执行shell命令、生成和修改代码、运行测试、解释报错。它最让我满意的一点是1M上下文窗口的支持这意味着你可以把整个中型项目的关键文件都塞给它它能在全局视角下给出建议而不是像某些工具那样只能看单个文件。2.2 Codex另一条技术路线的编码助手Codex是OpenAI推出的编码工具有CLI版本也有桌面版。它和Claude Code的定位类似但风格不同。Codex在代码补全和快速生成方面反应更快适合做“写一个函数”“生成一个组件”这类短平快的任务Claude Code则在长上下文理解和复杂重构上更有优势。Codex的安装方式npm install -g openai/codex或者从官网下载桌面版安装包。国内使用Codex需要注意网络问题这里不展开。Codex的认证方式支持API key和登录两种如果遇到“codex auth token is unavailable”的报错通常是认证信息过期或环境变量没配好重新执行codex login或者检查OPENAI_API_KEY环境变量即可。Codex还有一个很实用的能力接入DeepSeek等第三方模型。通过配置base URL和API key你可以让Codex CLI调用DeepSeek的接口这在成本和效果之间提供了一个不错的平衡点。配置方式通常是在~/.codex/config.yaml里指定provider和model。2.3 YAML整个编排体系的“接线图”YAML在这个体系里扮演的是配置文件的角色。Claude Code、Codex、以及各种周边工具都通过YAML文件来定义行为。比如Claude Code的项目级配置可以放在.claude/settings.yaml里定义允许执行的命令、忽略的文件、默认模型等。Codex的配置放在~/.codex/config.yaml定义provider、model、temperature等参数。tmux的会话布局可以用YAML描述然后通过脚本加载。YAML的好处是人类可读、结构清晰、易于版本控制。你可以把整套openrig的配置放在一个git仓库里换机器时clone下来就能恢复工作环境。这比记一堆命令行参数靠谱得多。一个典型的Codex配置示例model: gpt-4-codex provider: openai temperature: 0.2 max_tokens: 4096如果要接入DeepSeekmodel: deepseek-coder provider: custom base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY}注意${DEEPSEEK_API_KEY}这种写法它表示从环境变量读取避免把密钥硬编码在配置文件里。这是基本的安全习惯。2.4 tmux让AI会话“永不掉线”的容器tmux是终端复用工具它的核心价值是会话持久化。你开一个tmux会话在里面跑Claude Code然后关掉终端窗口会话依然在后台运行。下次连上来tmux attach就能恢复现场。对于需要长时间运行的AI任务比如让Claude Code重构一个大模块这个特性太重要了。tmux的基本操作tmux new -s claude-session # 新建名为claude-session的会话 tmux ls # 列出所有会话 tmux attach -t claude-session # 重新接入会话 tmux kill-session -t claude-session # 结束会话在openrig的编排思路里tmux通常和YAML配合使用用YAML定义窗口布局和启动命令用脚本一键创建整个工作环境。比如你可以定义一个三窗口布局窗口1跑Claude Code窗口2跑Codex窗口3跑本地模型服务。3. 装配实操从零搭建一套可切换的AI编码环境3.1 环境准备与依赖安装在开始装配之前先确认基础环境。我推荐Ubuntu 22.04或macOSWindows用户建议用WSL2。需要的基础组件Node.js 18Claude Code和Codex CLI都依赖npm或pnpmtmux 3.0git安装命令# Ubuntu sudo apt update sudo apt install -y nodejs npm tmux git # macOS brew install node tmux gitNode.js版本建议用nvm管理方便切换curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 20 nvm use 20安装完基础环境后分别安装Claude Code和Codexnpm install -g anthropic-ai/claude-code npm install -g openai/codex验证安装claude --version codex --version如果这两个命令都能输出版本号说明基础环境就绪。3.2 用YAML定义统一配置接下来是openrig的核心用YAML把配置统一管理起来。我建议在~/openrig/目录下建立如下结构~/openrig/ ├── configs/ │ ├── claude.yaml │ ├── codex.yaml │ └── tmux.yaml ├── scripts/ │ ├── start-claude.sh │ ├── start-codex.sh │ └── start-all.sh └── README.mdclaude.yaml示例model: claude-sonnet-4-20250514 max_tokens: 8192 allowed_commands: - git - npm - python - ls - cat ignore_patterns: - *.log - node_modules/ - .git/codex.yaml示例model: gpt-4-codex temperature: 0.2 max_tokens: 4096 provider: openaitmux.yaml用来描述会话布局session: openrig windows: - name: claude command: claude - name: codex command: codex - name: shell command: bash这个YAML不是tmux原生支持的格式而是我自己的约定通过脚本解析后生成对应的tmux命令。这样做的好处是配置集中、可读性强。3.3 编写一键启动脚本start-all.sh的核心逻辑#!/bin/bash SESSIONopenrig # 如果会话已存在直接接入 tmux has-session -t $SESSION 2/dev/null if [ $? -eq 0 ]; then tmux attach -t $SESSION exit 0 fi # 创建新会话第一个窗口跑Claude Code tmux new-session -d -s $SESSION -n claude tmux send-keys -t $SESSION:claude claude C-m # 第二个窗口跑Codex tmux new-window -t $SESSION -n codex tmux send-keys -t $SESSION:codex codex C-m # 第三个窗口留作普通shell tmux new-window -t $SESSION -n shell # 默认选中第一个窗口 tmux select-window -t $SESSION:claude # 接入会话 tmux attach -t $SESSION这个脚本做了几件事检查会话是否存在、创建三个窗口、在每个窗口里启动对应的工具、最后接入会话。你可以把它放到~/.local/bin/下加个别名alias rigbash ~/openrig/scripts/start-all.sh以后敲一个rig就能进入完整工作环境。3.4 配置切换与本地模型接入如果你需要在Claude Code和Codex之间切换或者让它们接入本地模型比如通过LM Studio跑的模型YAML配置就体现出价值了。以Claude Code接入本地模型为例你需要设置环境变量export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlocal-model然后在claude.yaml里指定model为本地模型的名称。LM Studio默认监听1234端口启动后在界面里加载模型即可。Codex接入DeepSeek的配置前面已经提过核心是base_url和api_key两项。这里有个经验DeepSeek的API在代码生成任务上表现不错但响应格式和OpenAI不完全一致偶尔会出现解析错误。如果遇到这种情况检查Codex版本是否支持自定义provider或者用中间层做格式转换。4. 常见问题与排查技巧实录4.1 安装与认证类问题问题一Claude Code安装后运行报权限错误Ubuntu下常见原因是npm全局目录权限不对。解决方法mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到~/.bashrc里重新source一下。问题二Codex提示“auth token is unavailable”这个报错通常有三种原因API key没设置、key过期、或者环境变量没被正确读取。排查顺序检查echo $OPENAI_API_KEY是否有输出检查~/.codex/config.yaml里的provider配置重新执行codex login走一遍认证流程问题三组织禁用了Claude订阅访问如果你看到“your organization has disabled claude subscription access for claude code”说明你的账号所属组织限制了订阅方式访问。这时候需要用API key认证在claude.yaml里配置api_key字段或者设置ANTHROPIC_API_KEY环境变量。4.2 运行与性能类问题问题四tmux会话里的AI工具输出乱码这通常是终端类型不匹配导致的。在~/.tmux.conf里加上set -g default-terminal screen-256color然后重启tmux会话。问题五Claude Code处理大项目时响应慢1M上下文虽然强大但塞太多文件进去也会拖慢响应。我的做法是用.claudeignore文件排除无关目录比如node_modules/、dist/、*.log。只把核心源码目录暴露给Claude Code响应速度会明显提升。问题六Codex接入本地模型后输出格式错乱本地模型尤其是量化版本在指令遵循上不如云端大模型稳定。解决方法是在YAML里把temperature调低到0.1以下并且在prompt里明确要求“只输出代码不要解释”。如果还是不行考虑换一个指令遵循能力更强的本地模型。4.3 配置管理类问题问题七YAML缩进错误导致配置不生效YAML对缩进极其敏感tab和空格混用会直接报错。建议在编辑器里设置“tab转空格”并且用yamllint做校验pip install yamllint yamllint ~/openrig/configs/问题八多台机器之间同步配置把~/openrig/目录做成git仓库.gitignore里排除包含密钥的文件用环境变量或单独的secrets.yaml不纳入版本控制管理敏感信息。换机器时clone下来装好依赖基本能一键恢复。4.4 常见问题速查表问题现象可能原因排查方向Claude Code报权限错误npm全局目录权限不对重设npm prefixCodex提示auth token unavailableAPI key未设置或过期检查环境变量和config.yaml组织禁用订阅访问账号组织策略限制改用API key认证tmux输出乱码终端类型不匹配设置default-terminal大项目响应慢上下文塞太多文件配置ignore规则本地模型输出格式错乱指令遵循能力不足降低temperature明确promptYAML配置不生效缩进错误用yamllint校验多机同步困难配置散落各处统一到git仓库管理5. 进阶玩法把openrig思路扩展到更多场景5.1 多模型并行对比openrig的编排思路不限于Claude Code和Codex。你可以在tmux里开四个窗口分别跑Claude Code、Codex、本地LM Studio模型、以及DeepSeek接入的Codex同一个问题同时抛给四个工具对比输出质量。这种做法在选型阶段特别有用——与其看别人的评测不如用自己的真实任务跑一遍。具体操作在tmux.yaml里定义四个窗口每个窗口的启动命令不同。比如窗口4的启动命令是export OPENAI_BASE_URLhttps://api.deepseek.com/v1 export OPENAI_API_KEY${DEEPSEEK_API_KEY} codex --model deepseek-coder这样四个窗口各自独立互不干扰你可以随时切换查看。5.2 与VS Code的联动虽然Claude Code和Codex都是终端工具但你可以把它们和VS Code结合起来用。一种做法是在VS Code的集成终端里跑tmux会话这样编辑器里就能直接看到AI工具的输出。另一种做法是用VS Code的任务系统tasks.json调用openrig的启动脚本一键拉起整个环境。VS Code配置Claude Code的关键是确保集成终端的环境变量和外部终端一致。有时候在外部终端能跑的配置在VS Code里报错就是因为VS Code没有加载~/.bashrc。解决方法是在VS Code设置里把terminal.integrated.inheritEnv设为true或者直接在tasks.json里显式设置环境变量。5.3 会话持久化与远程接入tmux最大的价值在于会话持久化。你可以在家里的服务器上跑一个openrig会话然后从公司电脑通过SSH接入。具体流程服务器上执行rig启动会话公司电脑SSH到服务器执行tmux attach -t openrig恢复现场这样你的AI编码环境就变成了一个“常驻服务”不管换哪台电脑接上来就能继续之前的工作。对于需要长时间运行的AI任务比如让Claude Code批量重构几十个文件这个特性几乎是刚需。5.4 配置版本化与团队共享如果你在团队里推广这套工具可以把openrig配置做成模板仓库。新成员clone下来改一下secrets.yaml里的个人密钥执行安装脚本就能获得一致的工作环境。这比口头传授“你先装这个再装那个”高效得多。模板仓库里应该包含YAML配置模板、启动脚本、安装脚本、README说明、以及一个secrets.yaml.example示例文件。.gitignore里排除secrets.yaml和任何包含真实密钥的文件。6. 我踩过的坑与实操心得先说一个最容易被忽略的坑tmux里的环境变量和外部shell不一定一致。我有一次在外部终端配好了ANTHROPIC_API_KEY进tmux跑Claude Code却提示认证失败。排查了半天才发现tmux会话是在配置环境变量之前创建的它继承的是旧的环境。解决方法要么是重建会话要么在tmux里手动export一遍。后来我在启动脚本里加了显式的环境变量加载这个问题就再没出现过。第二个坑是关于YAML的。我一开始把Claude Code的配置写在项目根目录的.claude.yaml里结果怎么都不生效。后来查文档才发现Claude Code读取的是.claude/settings.yaml路径不对。不同工具对配置文件的路径和命名要求不一样一定要查清楚再写。Codex是~/.codex/config.yamlClaude Code是.claude/settings.yamltmux是~/.tmux.conf三者互不通用。第三个坑是本地模型的端口冲突。我在LM Studio里加载了模型默认监听1234端口同时另一个服务也占了1234导致Claude Code连不上。跑本地模型之前先用lsof -i :1234检查端口占用这个习惯能省很多排查时间。第四个坑是关于Codex接入第三方模型的。DeepSeek的API返回格式和OpenAI有细微差异Codex CLI在某些版本里会解析失败。我的做法是先用curl手动测试API返回格式确认没问题再配到Codex里。如果格式确实不兼容考虑用one-api这类中间层做转换。最后一个心得不要把openrig搞得太复杂。我一开始想把所有工具、所有模型、所有配置都塞进一套YAML里结果配置文件比代码还长维护成本极高。后来我做了减法只保留最常用的两个工具Claude Code和Codex配置只写必要的字段其余用默认值。这套精简后的配置反而更稳定换机器恢复也更快。工具是拿来用的不是拿来供着的。
