openrig 环境搭建指南：Claude Code 与 Codex 协同配置与模型接入

1. 从零认识 openrig：它到底解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 rig 这个词在英文里常指“装备、装置”。但结合 Claude Code、Codex、Node.js、tmux 这几个关键词放在一起，基本可以判断它是一套围绕 AI 编程助手运行环境搭建与管理的工具集或配置方案。简单说，openrig 要解决的核心痛点是：当你同时使用 Claude Code、Codex 这类命令行 AI 编程工具时，如何让它们在一个统一、稳定、可切换的环境里协同工作，而不是每次都要手动折腾配置、切换模型、处理代理转发失败的问题。

我最初接触这类需求，是因为手头同时跑着 Claude Code 和 Codex 两个工具。Claude Code 擅长理解大段代码上下文、执行终端命令、做重构；Codex 在代码补全和特定模型接入上有自己的优势。但两者对 Node.js 版本的要求、对 API 端点的配置方式、对本地模型和第三方模型的支持路径都不一样。每次切换都要改环境变量、重启终端、甚至重装依赖，效率极低。openrig 这类方案的价值就在于把这些重复劳动收敛成一套可复用的配置。

适合读这篇内容的人有三类：第一类是刚接触 Claude Code 或 Codex，连 Node.js 装哪个版本都还没搞清楚的入门者；第二类是已经在用但经常遇到“cc switch local proxy failed while handling codex endpoint /responses”这类报错的中级用户；第三类是想把本地模型（比如通过 LM Studio 跑的模型）接入 Claude Code，或者想把 Codex 接到 DeepSeek、Qwen、GLM 等第三方 API 上的进阶玩家。不管你是哪一类，下面这些实操细节和踩坑记录都能直接拿去用。

提示：openrig 本身不是一个官方大厂产品，更像是一套社区沉淀下来的环境组织思路和配置集合。所以不要指望有完美的官方文档，更多要靠理解原理后自己调优。

2. 环境底座：Node.js 与 tmux 的选型逻辑

2.1 Node.js 版本选择：为什么 20+ 是底线

Claude Code 和 Codex 的 CLI 工具绝大多数是基于 Node.js 运行的。这就意味着 Node.js 的版本直接决定了工具能不能跑起来、跑得稳不稳。热搜词里频繁出现“node.js安装”“node.js LTS下载”“ubuntu安装node.js 20+”“error installing 24.21.0: node.js v24.21.0 is not yet released”，说明版本问题是新手遇到的第一道坎。

我的建议很明确：优先选 Node.js 20 LTS 或 22 LTS，不要盲目追最新版。原因有三点。第一，LTS 版本经过长时间测试，和 npm 生态的兼容性最好，Claude Code 和 Codex 的依赖树在 LTS 上出问题的概率最低。第二，某些第三方 API 接入库对 Node.js 的版本有硬性要求，比如部分 WebSocket 或 fetch 相关的 polyfill 在 18 以下会报错，在 20 以上才稳定。第三，像“node.js v24.21.0 is not yet released”这种报错，通常是因为你用的安装脚本或镜像源指向了一个不存在的版本号，换回 LTS 就能解决。

在 Ubuntu 上安装 Node.js 20+，我习惯用 NodeSource 的源，而不是系统自带的 apt 版本。系统自带的往往太旧，比如 Ubuntu 22.04 默认给的是 Node.js 12，根本跑不了新版 Claude Code。具体操作：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v npm -v

装完之后确认版本号是 v20.x 或更高。如果你在 Windows 上，直接去 Node.js 官网下载 LTS 的 msi 安装包，安装时勾选“Add to PATH”，这样在 PowerShell 或 CMD 里就能直接调用 node 和 npm。

注意：不要用sudo npm install -g去装 Claude Code 或 Codex 的 CLI，除非你明确知道自己在做什么。全局安装权限问题会导致后续更新和切换版本时非常痛苦。推荐用 nvm 管理 Node.js 版本，这样可以在 20 和 22 之间自由切换。

2.2 tmux：让 AI 编程助手在后台稳定运行

tmux 出现在热搜词里不是偶然。Claude Code 和 Codex 这类工具在执行长任务时，比如分析整个代码库、跑测试、执行多轮对话，如果直接挂在当前终端窗口，一旦网络波动或者你不小心关了窗口，任务就断了。tmux 的作用就是创建一个持久化的会话，让这些工具在后台跑，你随时可以 detach 和 reattach。

我通常这样用：

tmux new -s claude-work # 在会话里启动 claude code 或 codex # 按 Ctrl+b 然后按 d 脱离会话 # 下次回来 tmux attach -t claude-work

这样即使 SSH 断线，AI 助手还在后台继续工作。对于需要长时间跑代码生成或重构任务的场景，这个习惯能省下大量重复劳动。而且 tmux 支持分屏，你可以左边开 Claude Code，右边开 Codex，同时对比两个工具对同一段代码的处理结果，效率直接翻倍。

2.3 环境变量与 PATH 的常见坑

Node.js 装好了，tmux 也配了，但很多人还是会遇到“命令找不到”的问题。这通常是 PATH 没配好。比如你用 nvm 装了 Node.js，但 tmux 会话里没有加载 nvm 的环境，导致在 tmux 里执行 claude 或 codex 时报 command not found。解决办法是在 shell 的配置文件里（比如.bashrc或.zshrc）确保 nvm 的初始化脚本在 tmux 启动前就被加载，或者在 tmux 里手动 source 一下。

另一个坑是 npm 全局 bin 目录不在 PATH 里。你可以用npm config get prefix查看全局安装路径，然后把这个路径下的 bin 目录加到 PATH。这些细节看起来琐碎，但实际排查时能卡住半天。

3. Claude Code 与 Codex 的安装配置实操

3.1 Claude Code 安装：从下载到跑通第一条命令

Claude Code 的安装方式随着版本迭代有过变化，但核心逻辑不变：通过 npm 全局安装或者用官方提供的安装脚本。热搜词里“claude code安装”“claude code下载安装”“ubuntu安装claude code”“claude code windows”都指向同一个需求——怎么把它装到本机并跑起来。

我实测下来最稳的方式是用 npm 安装：

npm install -g @anthropic-ai/claude-code

装完之后执行claude命令，它会引导你完成登录和初始化。如果你在 Windows 上，建议在 WSL2 里装，因为 Claude Code 的很多终端交互功能在原生 Windows CMD 或 PowerShell 里体验不好，比如颜色输出、键盘快捷键、终端命令执行等。WSL2 里就是标准的 Linux 环境，和 Ubuntu 上操作一致。

安装完成后，第一次运行会让你选择登录方式。如果你有 Claude 的订阅，直接登录即可。如果遇到“your organization has disabled claude subscription access for claude code”这类提示，说明你的组织账号限制了访问，需要换个人账号或者联系管理员开通权限。

3.2 Codex 安装：CLI 与桌面版的取舍

Codex 的安装路径稍微多一点。热搜词里“codex安装”“codex安装教程”“codex安装包”“codex安装 windows桌面版”“codex cli”说明大家对这个工具的安装方式存在困惑。我的建议是：优先用 CLI 版本，桌面版适合不习惯命令行的用户，但灵活性差很多。

Codex CLI 通常也是通过 npm 安装：

npm install -g @openai/codex

或者根据你使用的具体 Codex 实现，可能是其他包名。装完后执行codex命令，会提示你登录或配置 API Key。如果你遇到“codex登录不上”“codex无法加载组织设置”，大概率是网络问题或者账号权限问题。先确认你的 API Key 是否有效，再检查终端是否能正常访问外部端点。

Codex 的配置文件通常放在用户目录下的.codex文件夹里，里面会有 config 文件。热搜词里“codex is ignoring 1 unrecognized configuration setting. check for typos or d”就是一个典型的配置字段拼写错误导致的警告。遇到这种提示，直接打开配置文件，对照官方文档检查字段名，通常是把model写成了modle之类的低级错误。

3.3 VS Code 集成：让 AI 助手住在编辑器里

“vscode配置claude code”“claude code for vs code”“vscode接入claude code”这些热搜词说明很多人希望直接在 VS Code 里用 Claude Code，而不是切到终端。目前 Claude Code 有 VS Code 扩展，装完之后可以在编辑器内直接调用。配置的关键是确保 VS Code 的终端能识别到 claude 命令，并且扩展的设置里填对了路径。

我自己的习惯是：VS Code 里开集成终端，在终端里跑 Claude Code，而不是完全依赖扩展的 UI。因为 Claude Code 的强项是执行终端命令和操作文件系统，在终端里它的能力最完整。VS Code 扩展更多是提供一个快捷入口，真正干活还是在终端会话里。

Codex 在 VS Code 里也有对应的扩展或集成方式，但同样建议以终端为主。你可以把 VS Code 的默认终端设置为 tmux 会话，这样在编辑器里就能直接 attach 到后台运行的 AI 助手。

4. 模型接入：本地模型与第三方 API 的配置细节

4.1 Claude Code 调用 LM Studio 本地模型

“claude code 调用lmstudio的本地模型”是一个高频需求。很多人想在本地跑模型，既省 API 费用又保护隐私。LM Studio 提供了一个本地推理服务，默认监听http://localhost:1234。要让 Claude Code 调用它，核心是配置 API 端点。

Claude Code 默认走的是 Anthropic 的官方端点，要让它转向本地，需要设置环境变量或者修改配置文件。通常的做法是设置ANTHROPIC_BASE_URL指向本地服务，同时把 API Key 设成任意非空值（本地服务通常不校验）。但这里有个关键点：Claude Code 使用的 API 格式和 LM Studio 默认提供的 OpenAI 兼容格式可能不完全一致。如果直接指过去报错，可能需要一个中间转换层，比如用 LiteLLM 或者自己写一个简单的代理做格式转换。

我实测下来，LM Studio 的 OpenAI 兼容接口在部分场景下能直接工作，但 Claude Code 的一些高级功能（比如工具调用、流式响应）可能需要额外适配。如果你只是做简单的代码问答，直接配通常能跑；如果要完整功能，建议先用官方端点跑通，再逐步替换。

4.2 Codex 接入 DeepSeek、Qwen、GLM 等第三方模型

“codex接入deepseek”“使用cc switch 接入 deepseek v4, qwen, glm等模型”“第三方api使用技巧”这些热搜词指向一个共同需求：怎么让 Codex 用上非 OpenAI 的模型。Codex 本身支持自定义模型端点，你可以在配置文件里指定base_url和model名称。

以接入 DeepSeek 为例，DeepSeek 提供 OpenAI 兼容的 API，所以配置起来相对直接。在 Codex 的 config 文件里，把端点改成 DeepSeek 的 API 地址，填入对应的 API Key，模型名写成 DeepSeek 支持的模型标识。但要注意，不同模型对 function calling、JSON mode 的支持程度不一样。如果 Codex 依赖这些特性，而目标模型不支持，就会出现“the 'gpt-5.6-sol' model is not supported when using codex with a”这类报错。解决办法是换一个支持所需特性的模型，或者调整 Codex 的调用参数，关掉不兼容的功能。

cc switch 是一个用来切换 Claude Code 后端模型的工具，热搜词里“cc switch local proxy failed while handling codex endpoint /responses”说明它在处理 Codex 端点时出过问题。这个报错的本质是代理层在转发请求到/responses路径时失败了。排查思路：先确认代理服务是否正常运行，再检查目标端点的 URL 拼接是否正确，最后看请求体格式是否符合目标 API 的要求。很多时候是路径多了或少了斜杠，或者请求头里的 Content-Type 不对。

4.3 模型切换的稳定方案

同时用多个模型时，频繁改配置文件很容易出错。我的做法是准备多份配置文件，用环境变量或者启动参数来指定用哪一份。比如：

# 用 DeepSeek 跑 Codex CODEX_CONFIG=~/.codex/deepseek.yaml codex # 用本地模型跑 Claude Code ANTHROPIC_BASE_URL=http://localhost:1234 claude

这样不用每次手动改文件，切换成本极低。另外，把常用的配置写成 shell 别名，比如alias codex-ds='CODEX_CONFIG=~/.codex/deepseek.yaml codex'，用起来更顺手。

提示：第三方 API 的稳定性参差不齐，建议在 tmux 里跑长任务，并且配置好重试逻辑。很多 API 在高峰期会超时或限流，没有重试机制的话任务会直接中断。

5. 常见报错与排查技巧实录

5.1 安装类报错速查

5.2 运行类报错排查

“cc switch local proxy failed while handling codex endpoint /responses”这个报错我遇到过几次。第一次是因为代理服务的版本太旧，不支持 Codex 新的端点格式。升级代理工具后解决。第二次是因为目标 API 的 URL 末尾多了斜杠，导致拼接出来的路径变成//responses，服务端不识别。去掉多余斜杠后正常。第三次是请求头里的Authorization格式不对，第三方 API 要求Bearer前缀，而配置里漏了。

“the 'gpt-5.6-sol' model is not supported when using codex with a”这个报错通常出现在你指定的模型名不被当前端点支持时。比如你在 Codex 配置里写了某个模型名，但目标 API 并没有这个模型，或者该模型不支持 Codex 需要的调用方式。解决办法是查目标 API 的模型列表，换成实际存在的、且支持所需功能的模型。

“codex登录不上”多数是网络连通性问题。先确认终端能正常访问外部网络，再检查 API 端点是否可达。如果用的是第三方 API，确认其服务状态是否正常。有时候是 DNS 解析问题，换一个 DNS 或者直接在配置里写 IP 地址能绕过。

5.3 独家避坑经验

第一个坑：不要在 root 用户下装全局 npm 包。权限问题会导致后续更新和卸载都很麻烦，而且有些工具在 root 下运行会有安全警告。用普通用户加 sudo 只在必要的时候用。

第二个坑：tmux 会话里的环境变量和外部不一致。如果你在.bashrc里配了 API Key，但 tmux 启动时没有加载这个文件，会话里就找不到 Key。解决办法是在 tmux 配置文件里显式 source 你的 shell 配置，或者用tmux show-environment检查环境变量。

第三个坑：本地模型的端口冲突。LM Studio 默认用 1234，如果你同时跑了其他服务占用了这个端口，Claude Code 就连不上。用lsof -i :1234检查端口占用情况，必要时改 LM Studio 的监听端口。

第四个坑：第三方 API 的速率限制。很多第三方 API 有每分钟请求数限制，跑长任务时容易触发限流。建议在配置里加上重试和退避策略，或者把任务拆小，分批次执行。

6. 我的日常使用流与工具组合建议

经过一段时间的折腾，我目前的工作流是这样的：Ubuntu 主机上装 Node.js 20 LTS，用 nvm 管理版本；tmux 常驻一个会话专门跑 AI 编程任务；Claude Code 和 Codex 都通过 npm 全局安装，但用不同的配置文件区分模型端点；VS Code 通过 Remote-SSH 连到 Ubuntu，在集成终端里 attach 到 tmux 会话。

这样一套组合下来，切换模型只需要改一个环境变量，长任务不怕断线，本地模型和第三方 API 都能灵活接入。对于刚入门的朋友，我的建议是先把 Node.js 和 tmux 这两个底座搭稳，再装 Claude Code 或 Codex，跑通官方端点后再尝试接本地模型或第三方 API。不要一上来就追求全功能，一步一步来，遇到报错先看日志，多数问题都能在配置层面解决。

最后分享一个小技巧：把常用的启动命令写成 shell 函数，放在.bashrc里。比如：

claude-local() { ANTHROPIC_BASE_URL=http://localhost:1234 claude "$@" } codex-ds() { CODEX_CONFIG=~/.codex/deepseek.yaml codex "$@" }

这样每次用的时候直接敲claude-local或codex-ds，不用记那些环境变量，效率提升非常明显。