1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架或者开源机械臂项目。实际上结合它周边的关键词——Claude Code、Codex、Node.js、tmux——可以判断出openrig 是一个面向 AI 编程助手尤其是 Claude Code 和 Codex 这类 CLI 工具的本地运行环境编排与配置管理方案。它的核心价值在于把原本散落在各个终端窗口、配置文件、环境变量里的 AI 编程工具统一到一个可复用、可切换、可管理的框架里。我自己是从去年开始重度使用 Claude Code 和 Codex 的。最开始的时候每换一个项目就要重新配一遍环境API key 散落在.bashrc、.zshrc、项目根目录的.env里模型切换靠手动改配置终端会话一关上下文全丢。后来接触到 openrig 这个思路才意识到问题的本质不是工具不好用而是缺少一层统一的编排层。openrig 要做的就是这层编排。它适合什么人三类人最需要第一类是在多个项目之间频繁切换、每个项目用不同模型和 API 端点的开发者第二类是需要在远程服务器上跑 Claude Code 或 Codex、但希望本地终端体验一致的运维人员第三类是想把 AI 编程助手接入本地模型比如通过 LM Studio 跑的模型或者第三方 API 端点但被各种配置项绕晕的折腾党。提示openrig 本身不是一个官方产品名更像是一个社区里约定俗成的叫法指的是一套围绕 AI 编程 CLI 工具的本地编排实践。你在搜索时可能找不到一个叫 openrig 的 npm 包但你能找到大量关于 Claude Code 配置、Codex 接入、tmux 会话管理的零散内容。这篇文章要做的就是把这些碎片拼成一个完整的方案。2. 整体设计思路为什么是 Node.js tmux 配置层2.1 技术选型背后的逻辑Claude Code 和 Codex 这两个工具本质上都是 Node.js 写的 CLI 应用。Claude Code 通过 npm 全局安装Codex 也有对应的 npm 包和独立安装包。这意味着你的机器上必须有一个可用的 Node.js 运行时。这不是随便选的而是因为这两个工具都依赖 Node.js 的异步 I/O 和子进程管理能力来跟终端交互、调用外部命令、维护会话状态。那为什么是 tmux因为 AI 编程助手的工作模式是长会话。你不可能每问一个问题就重启一次进程那样上下文全丢了。tmux 提供的是持久化终端会话你关掉 SSH 连接、关掉本地终端窗口会话还在服务器上跑着下次连上去tmux attach就能接着用。这个特性对于在远程开发机上跑 Claude Code 的人来说是刚需。配置层则是 openrig 思路的核心。Claude Code 和 Codex 都支持通过环境变量和配置文件来指定 API 端点、模型名称、认证信息。但它们的配置格式不一样Claude Code 用~/.claude/settings.json或者环境变量Codex 用~/.codex/config.toml或者环境变量。openrig 的做法是抽象出一层统一的配置管理让你用同一套逻辑管理多个工具、多个模型、多个端点。2.2 分层架构拆解我把 openrig 的架构分成四层来理解层级职责关键组件运行时层提供 Node.js 执行环境Node.js LTS、npm/pnpm会话层持久化终端会话管理tmux、终端复用配置层统一管理 API 端点、模型、密钥环境变量、配置文件、切换脚本工具层实际的 AI 编程助手Claude Code、Codex CLI这个分层的好处是每一层都可以独立替换或升级。比如你不想用 tmux可以用 screen 或者 zellij 替代你不想用 Node.js 原生安装可以用 nvm 或者 fnm 管理多版本。openrig 的思路不是绑定某个具体工具而是提供一套可组合的编排模式。2.3 为什么不直接用官方安装方式官方安装方式当然能用npm install -g anthropic-ai/claude-code一行命令就装好了。但问题出在多环境管理上。假设你手上有三个项目项目 A 用 Claude Code 接官方 API项目 B 用 Codex 接第三方端点项目 C 用 Claude Code 接本地 LM Studio 跑的模型。官方方式下你需要手动切换环境变量、手动改配置文件、手动重启会话。openrig 的思路是把这个切换过程自动化、脚本化。我实测下来用 openrig 这套思路管理五个以上项目时效率提升非常明显。以前切换项目要花两三分钟改配置、验证连通性现在一条命令切换十秒钟搞定。3. 环境准备Node.js 安装与版本管理3.1 Node.js 安装的坑与正确姿势Node.js 的安装看起来简单但坑不少。热搜词里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这就是典型的版本号写错导致的。Node.js 的版本号是主版本.次版本.补丁版本比如20.11.1。你写24.21.0这种不存在的版本nvm 或者 fnm 就会报这个错。正确的做法是先去 Node.js 官网查 LTS 版本号或者直接用nvm install --lts让工具自己选。我个人的习惯是用 fnmFast Node Manager它比 nvm 快很多而且是 Rust 写的跨平台支持好。# 安装 fnm以 Ubuntu 为例 curl -fsSL https://fnm.vercel.app/install | bash # 重新加载 shell 配置 source ~/.bashrc # 安装最新的 LTS 版本 fnm install --lts # 设为默认版本 fnm default lts-latest # 验证 node -v npm -v如果你在 Windows 上fnm 也支持 PowerShell 和 winget 安装。装完之后fnm use可以在不同项目间切换 Node.js 版本这对同时维护老项目和新项目的人来说很实用。注意不要用系统自带的包管理器比如 apt装 Node.js版本通常很旧而且升级麻烦。用 fnm 或 nvm 这类版本管理器升级和切换都是一条命令的事。3.2 npm 全局安装的权限问题装完 Node.js 之后下一步是装 Claude Code 和 Codex。但很多人会卡在权限上npm install -g报EACCES错误。这是因为 npm 默认的全局目录需要 root 权限。解决方案有两个一是改 npm 的全局目录到用户目录下二是用 nvm/fnm 管理的 Node.js它们天然把全局包放在用户目录里不会有权限问题。我推荐第二种因为更干净。# 查看 npm 全局目录 npm config get prefix # 如果是 /usr/local 或 /usr说明需要改 # 用 fnm 的话这个路径会自动指向 ~/.local/share/fnm/...3.3 tmux 的安装与基础配置tmux 在 Ubuntu/Debian 上直接apt install tmux在 macOS 上brew install tmux。装完之后建议改一下默认前缀键默认是Ctrlb我习惯改成Ctrla因为更顺手。# ~/.tmux.conf set -g prefix C-a unbind C-b bind C-a send-prefix # 开启鼠标支持 set -g mouse on # 设置窗口编号从 1 开始 set -g base-index 1 setw -g pane-base-index 1 # 设置历史滚动行数 set -g history-limit 10000这几行配置看起来简单但实际用起来体验差别很大。鼠标支持让你可以直接点击切换窗格窗口编号从 1 开始符合直觉历史滚动行数调大之后可以往回翻很久之前的输出。4. Claude Code 与 Codex 的安装配置实战4.1 Claude Code 安装与首次配置Claude Code 的安装命令是npm install -g anthropic-ai/claude-code装完之后在项目目录下直接运行claude就会启动。首次启动会引导你登录或者配置 API key。如果你用的是官方 API直接按引导走就行。但如果你想接入第三方端点或者本地模型就需要手动配置。Claude Code 支持通过环境变量指定 API 端点export ANTHROPIC_BASE_URLhttps://your-endpoint.com export ANTHROPIC_API_KEYyour-key这两个环境变量是 openrig 配置层的核心。你可以把它们写在一个脚本里切换项目时 source 一下就行。提示热搜词里有一条your organization has disabled claude subscription access for claude code这说明你的组织账号没有开通 Claude Code 的访问权限。这种情况要么找管理员开通要么用自己的个人账号要么接入第三方端点。4.2 Codex 安装与配置要点Codex 的安装方式取决于你用的是哪个版本。如果是 OpenAI 官方的 Codex CLI安装命令是npm install -g openai/codexCodex 的配置文件和 Claude Code 不一样它用的是 TOML 格式默认路径是~/.codex/config.toml。一个典型的配置长这样[model] provider openai name gpt-4 [provider.openai] base_url https://api.openai.com/v1 api_key_env OPENAI_API_KEY如果你想接入 DeepSeek 或者其他兼容 OpenAI 接口的端点就把base_url改掉api_key_env指向对应的环境变量。热搜词里有一条codex is ignoring 1 unrecognized configuration setting. check for typos or d这是 Codex 在告诉你配置文件里有它不认识的字段。通常是拼写错误或者用了旧版本的配置项。解决办法是查官方文档确认字段名或者直接删掉那个字段。4.3 用 cc switch 实现多模型切换热搜词里提到了cc switch和使用cc switch 接入 deepseek v4, qwen, glm等模型。cc switch 是一个社区工具用来在多个 Claude Code 配置之间快速切换。它的思路很简单把不同的配置存成不同的 profile切换时把对应的环境变量和配置文件软链接过去。我自己实现了一个更轻量的版本用一个 shell 函数搞定# ~/.bashrc 或 ~/.zshrc openrig_switch() { local profile$1 local config_dir$HOME/.openrig/profiles/$profile if [ ! -d $config_dir ]; then echo Profile $profile not found return 1 fi # 加载环境变量 if [ -f $config_dir/env.sh ]; then source $config_dir/env.sh fi # 切换 Claude Code 配置 if [ -f $config_dir/claude-settings.json ]; then ln -sf $config_dir/claude-settings.json $HOME/.claude/settings.json fi # 切换 Codex 配置 if [ -f $config_dir/codex-config.toml ]; then ln -sf $config_dir/codex-config.toml $HOME/.codex/config.toml fi echo Switched to profile: $profile }用的时候就是openrig_switch deepseek或者openrig_switch local-lmstudio。每个 profile 目录下放对应的环境变量脚本和配置文件切换就是改软链接和 source 环境变量。这个方案的好处是透明、可调试。出问题了直接看软链接指向哪里看环境变量是什么不用去猜某个工具的内部逻辑。5. tmux 会话管理与 openrig 的整合5.1 为什么 AI 编程助手需要 tmuxClaude Code 和 Codex 都是交互式 CLI它们的工作模式是你输入一个问题它思考然后输出结果可能还会调用工具、读写文件。这个过程可能持续几十秒甚至几分钟。如果你在 SSH 会话里直接跑网络一抖或者你不小心关了终端整个会话就没了上下文全丢。tmux 解决的就是这个问题。它把终端会话和你的 SSH 连接解耦。SSH 断了tmux 会话还在服务器上跑着。你重新连上去tmux attach -t claude就能回到之前的会话Claude Code 还在那里等着你。我自己的习惯是每个项目开一个 tmux 会话会话名就是项目名。会话里开三个窗格一个跑 Claude Code一个跑 Codex一个跑普通的 shell 用来执行命令和看日志。5.2 tmux 会话的自动化创建手动创建 tmux 会话和窗格很麻烦尤其是项目多的时候。我写了一个脚本根据项目目录自动创建会话#!/bin/bash # openrig-session.sh PROJECT_NAME$(basename $PWD) SESSION_NAMEopenrig-$PROJECT_NAME # 检查会话是否已存在 tmux has-session -t $SESSION_NAME 2/dev/null if [ $? ! 0 ]; then # 创建新会话第一个窗口跑 Claude Code tmux new-session -d -s $SESSION_NAME -n claude tmux send-keys -t $SESSION_NAME:claude cd $PWD claude C-m # 第二个窗口跑 Codex tmux new-window -t $SESSION_NAME -n codex tmux send-keys -t $SESSION_NAME:codex cd $PWD codex C-m # 第三个窗口跑普通 shell tmux new-window -t $SESSION_NAME -n shell tmux send-keys -t $SESSION_NAME:shell cd $PWD C-m # 默认选中第一个窗口 tmux select-window -t $SESSION_NAME:claude fi # 附加到会话 tmux attach -t $SESSION_NAME把这个脚本放到~/bin/openrig-session加个别名alias orsopenrig-session以后进项目目录直接敲ors就自动创建或附加到对应的 tmux 会话。5.3 会话持久化与日志记录tmux 会话虽然持久但输出内容默认不会保存到文件。如果你想事后回看 Claude Code 和 Codex 的对话记录需要额外配置日志。tmux 支持 pipe-pane 功能可以把窗格的输出重定向到文件# 在 tmux 会话里执行 tmux pipe-pane -t $SESSION_NAME:claude -o cat ~/.openrig/logs/$PROJECT_NAME-claude.log这样 Claude Code 的所有输出都会追加到日志文件里。配合logrotate或者定时清理脚本可以保留最近一段时间的记录。注意日志文件可能会包含敏感信息比如 API key 的片段、代码内容等。如果你在共享服务器上跑记得把日志目录权限设成 700只让自己能读。6. 接入本地模型与第三方端点的实操细节6.1 用 LM Studio 跑本地模型并接入 Claude Code热搜词里有claude code 调用lmstudio的本地模型这是一个很典型的场景。LM Studio 可以在本地跑各种开源模型并提供一个兼容 OpenAI 接口的本地端点。Claude Code 虽然默认走 Anthropic 的接口但通过设置ANTHROPIC_BASE_URL可以指向任何兼容的端点。LM Studio 默认的本地端点是http://localhost:1234/v1。但 Claude Code 用的是 Anthropic 的接口格式不是 OpenAI 格式。所以你需要一个转换层把 Anthropic 格式的请求转成 OpenAI 格式。社区里有现成的工具比如claude-code-proxy或者anthropic-proxy。# 安装转换代理 npm install -g claude-code-proxy # 启动代理指向 LM Studio claude-code-proxy --target http://localhost:1234/v1 --port 8080 # 配置 Claude Code 指向代理 export ANTHROPIC_BASE_URLhttp://localhost:8080 export ANTHROPIC_API_KEYdummy-key这样 Claude Code 的请求就会先到代理代理转成 OpenAI 格式发给 LM Studio再把结果转回 Anthropic 格式返回给 Claude Code。实测下来本地模型跑 Claude Code 的体验取决于模型能力和硬件。7B 级别的模型基本只能做简单的代码补全13B 以上才能勉强处理多轮对话。如果你有 32GB 以上内存和一张不错的显卡跑 34B 的模型体验会好很多。6.2 Codex 接入 DeepSeek 的配置Codex 接入 DeepSeek 相对简单因为 DeepSeek 的 API 兼容 OpenAI 格式。你只需要改~/.codex/config.toml[model] provider deepseek name deepseek-coder [provider.deepseek] base_url https://api.deepseek.com/v1 api_key_env DEEPSEEK_API_KEY然后设置环境变量export DEEPSEEK_API_KEYyour-deepseek-keyCodex 就会用 DeepSeek 的模型来处理你的请求。DeepSeek 的代码能力在开源模型里算是第一梯队的而且 API 价格比官方便宜不少适合日常大量使用。6.3 端点切换的自动化脚本把上面的配置整合成一个切换脚本#!/bin/bash # openrig-endpoint.sh case $1 in official) export ANTHROPIC_BASE_URLhttps://api.anthropic.com export ANTHROPIC_API_KEY$ANTHROPIC_OFFICIAL_KEY ;; deepseek) export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEY$DEEPSEEK_API_KEY ;; local) export ANTHROPIC_BASE_URLhttp://localhost:8080 export ANTHROPIC_API_KEYdummy ;; *) echo Usage: openrig-endpoint [official|deepseek|local] return 1 ;; esac echo Endpoint switched to: $1这个脚本可以放在~/.openrig/目录下需要切换时 source 一下就行。7. 常见问题与排查技巧实录7.1 安装类问题速查问题现象可能原因解决方法error installing 24.21.0: node.js v24.21.0 is not yet released版本号写错用fnm install --lts让工具选版本npm install -g报 EACCES全局目录权限不足用 fnm/nvm 管理 Node.js或改 npm prefixclaude: command not foundnpm 全局 bin 目录不在 PATH检查npm config get prefix把 bin 目录加入 PATHcodex is ignoring 1 unrecognized configuration setting配置文件有拼写错误或旧字段对照官方文档检查字段名7.2 连接类问题排查cc switch local proxy failed while handling codex endpoint /responses这个错误说明代理在处理 Codex 的/responses端点时失败了。通常是因为代理不支持 Codex 用的接口格式。Codex 用的是 OpenAI 的 Responses API而不是 Chat Completions API。你需要确认代理是否支持这个端点。排查步骤先用curl直接测试端点是否可达curl -X POST http://localhost:8080/v1/responses \ -H Content-Type: application/json \ -d {model:gpt-4,input:hello}如果 curl 也失败说明代理本身有问题检查代理日志。如果 curl 成功但 Codex 失败说明 Codex 的配置有问题检查config.toml里的base_url是否包含了正确的路径前缀。7.3 会话类问题处理tmux 会话卡死或者 Claude Code 进程无响应是常见问题。我的处理流程是先按CtrlC尝试中断当前操作。如果没反应按CtrlB然后D脱离会话重新tmux attach看看。如果还是不行在另一个窗格里ps aux | grep claude找到进程 IDkill -9掉。重启 Claude Code 之前先检查日志文件看有没有报错信息。提示Claude Code 和 Codex 都会在本地缓存会话状态。如果你 kill 掉进程后重启发现上下文丢了可以看看~/.claude/和~/.codex/目录下有没有会话缓存文件。有些情况下可以手动恢复。7.4 我踩过的几个坑第一个坑是环境变量污染。我在.bashrc里 export 了ANTHROPIC_BASE_URL结果所有终端会话都受影响。后来改成只在需要的时候 source 切换脚本问题解决。第二个坑是tmux 会话名冲突。我用项目名做会话名结果两个不同路径下的同名项目冲突了。后来改成用完整路径的 hash 做会话名或者手动指定会话名。第三个坑是代理端口冲突。我同时跑了多个代理端口撞了。后来给每个代理分配固定端口写死在配置里避免冲突。8. 进阶玩法把 openrig 做成可移植的配置包8.1 配置目录结构设计把 openrig 的所有配置集中到一个目录下方便备份和迁移~/.openrig/ ├── profiles/ │ ├── official/ │ │ ├── env.sh │ │ ├── claude-settings.json │ │ └── codex-config.toml │ ├── deepseek/ │ │ ├── env.sh │ │ ├── claude-settings.json │ │ └── codex-config.toml │ └── local/ │ ├── env.sh │ ├── claude-settings.json │ └── codex-config.toml ├── scripts/ │ ├── openrig-switch.sh │ ├── openrig-session.sh │ └── openrig-endpoint.sh ├── logs/ └── README.md这个结构清晰、可移植。换一台机器把~/.openrig/目录拷过去再在.bashrc里 source 一下scripts/下的脚本环境就恢复了。8.2 用 Git 管理配置版本~/.openrig/目录可以直接用 Git 管理。但要注意不要把 API key 提交到仓库里。我的做法是env.sh里只写变量名和默认值实际的 key 放在~/.openrig/secrets/目录下这个目录加到.gitignore里。# env.sh 示例 export ANTHROPIC_BASE_URL${ANTHROPIC_BASE_URL:-https://api.anthropic.com} export ANTHROPIC_API_KEY${ANTHROPIC_API_KEY:-} # 从 secrets 目录加载实际的 key if [ -f $HOME/.openrig/secrets/anthropic.key ]; then export ANTHROPIC_API_KEY$(cat $HOME/.openrig/secrets/anthropic.key) fi这样配置可以安全地同步到 Git 仓库key 只存在本地。8.3 跨机器同步的注意事项如果你在多台机器上用 openrig配置同步要注意几点不同机器的 Node.js 版本可能不一样tmux 版本可能不一样本地模型的端点地址可能不一样。我的建议是把跟机器相关的配置抽出来放在一个local.sh文件里这个文件不纳入 Git 管理每台机器单独维护。# local.sh 示例每台机器不同 export LOCAL_MODEL_ENDPOINThttp://192.168.1.100:1234/v1 export PROXY_PORT8080env.sh里引用这些变量这样核心配置可以共享机器相关的差异隔离在local.sh里。9. 性能调优与资源占用控制9.1 Node.js 内存限制调整Claude Code 和 Codex 在处理大项目时可能会吃很多内存。Node.js 默认的老生代内存上限在 64 位系统上是 2GB 左右对于大项目可能不够。你可以通过NODE_OPTIONS调整export NODE_OPTIONS--max-old-space-size4096这会把老生代内存上限调到 4GB。如果你的机器内存充足可以调得更大。但要注意调太大可能导致 GC 停顿时间变长反而影响响应速度。我实测 4GB 是一个比较平衡的值。9.2 tmux 会话数量控制tmux 会话开太多会占用不少内存。每个会话至少有一个 shell 进程加上 Claude Code 和 Codex 的 Node.js 进程一个会话可能占几百 MB。如果你同时开十几个会话内存压力就上来了。我的做法是只给正在活跃开发的项目开会话不活跃的项目先 detach需要时再 attach。另外可以写个定时脚本自动清理超过一定时间没有活动的会话。#!/bin/bash # 清理超过 24 小时没有活动的 tmux 会话 tmux list-sessions -F #{session_name} #{session_activity} | while read name activity; do now$(date %s) if [ $((now - activity)) -gt 86400 ]; then tmux kill-session -t $name echo Killed session: $name fi done9.3 代理层的性能考量如果你用了转换代理比如把 Anthropic 格式转成 OpenAI 格式代理本身也会消耗资源。Node.js 写的代理在高并发下可能成为瓶颈。我的建议是代理只在本机跑不要暴露到公网如果有多个人用考虑用 Go 或 Rust 写的代理性能会好很多。另外代理的日志级别要调好。debug 级别的日志会输出大量内容既占磁盘又影响性能。生产环境下用 info 或 warn 级别就够了。10. 安全实践密钥管理与访问控制10.1 密钥存储的最佳实践API key 绝对不能硬编码在代码里也不能提交到 Git 仓库。我的做法是本地开发key 存在~/.openrig/secrets/目录下文件权限 600。服务器环境用环境变量注入或者用系统的密钥管理服务。团队协作用共享的密钥管理工具每个人有自己的访问凭证。# 设置 secrets 目录权限 chmod 700 ~/.openrig/secrets chmod 600 ~/.openrig/secrets/*.key10.2 网络访问控制如果你在服务器上跑 openrig要注意网络访问控制。Claude Code 和 Codex 需要访问外部 API但你不希望服务器上的其他服务也能随便访问这些端点。可以用防火墙规则限制出站流量只允许特定的域名和端口。另外tmux 会话如果多人共用一台服务器要注意会话隔离。tmux 默认的 socket 权限是 700只有创建者能访问。但如果你用了共享的 socket 路径就要小心了。我的建议是每个用户用自己的 tmux socket不要共用。10.3 日志脱敏前面提到过tmux 的 pipe-pane 日志可能包含敏感信息。除了设置文件权限还可以在写入日志前做脱敏处理。比如用sed把 API key 替换成***tmux pipe-pane -t $SESSION_NAME:claude -o sed s/sk-[a-zA-Z0-9]*/sk-***/g ~/.openrig/logs/$PROJECT_NAME-claude.log这个 sed 命令会把所有以sk-开头的字符串替换掉覆盖大部分 API key 的格式。当然更稳妥的做法是根本不在日志里输出 key这需要配置 Claude Code 和 Codex 的日志级别。11. 我个人的使用体会与后续扩展方向这套 openrig 的思路我用了大半年最大的感受是AI 编程助手的效率瓶颈往往不在模型本身而在环境配置和会话管理上。模型再强如果你每次用之前要花十分钟配环境实际效率也高不到哪里去。把配置层和会话层做扎实才能让 AI 编程助手真正融入日常开发流程。后续我打算在这几个方向继续折腾一是把配置切换做成 TUI 界面用fzf或者gum做个交互式选择器不用记 profile 名字二是把会话日志接入本地的检索工具方便事后搜索历史对话三是研究一下怎么把多个 AI 助手的输出做交叉验证比如同一个问题同时问 Claude Code 和 Codex对比它们的回答。最后分享一个小技巧如果你经常需要在不同项目间切换可以在 tmux 里用Ctrla加s打开会话选择器配合fzf做模糊搜索切换速度比敲命令快很多。这个组合我用了之后基本回不去了。