企业官网建设流程全解析

1. openrig 到底在解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 “rig” 这个词在装机圈里太常见了。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手，大概率已经隐约感觉到它要解决的是什么问题了——多 AI 编码代理的本地编排与终端会话管理。

我自己的日常工作流里，同时开着 Claude Code 和 Codex 是常态。一个负责大范围重构和代码审查，一个负责快速补全和命令行操作。用久了就会发现几个特别烦人的点：每个工具都要单独开一个终端窗口，切来切去容易乱；会话状态没法统一管理，关掉终端再回来上下文就断了；不同工具的配置散落在各自的家目录里，想统一改个模型端点要翻好几个文件。openrig 这个项目，本质上就是冲着这些痛点来的。

它做的事情可以概括成三句话：把多个 AI 编码代理统一到一个可管理的终端会话体系里，用 tmux 作为底层会话承载，用 Node.js 做编排层，让 Claude Code、Codex 这些工具能在同一个 “工作台” 里协同工作。说白了，它想当的是你本地 AI 编程工具的 “调度中心”，而不是再做一个新的 AI 助手。

适合谁来参考这篇文章？如果你已经在用或者准备用 Claude Code、Codex，并且遇到了多会话管理混乱、配置分散、终端切换成本高的问题，那 openrig 的思路值得你花时间研究。如果你只是偶尔用一下 AI 补全，还没到多代理协同的阶段，可以先收藏，等需求上来了再回头看。下面我会从设计思路、核心细节、实操落地到问题排查，把整个东西拆开讲清楚。

2. 整体设计思路与方案选型拆解

2.1 为什么是 tmux 而不是自己造会话层

openrig 选择 tmux 作为底层会话承载，这个决定我认为是整个项目里最务实的一步。很多人第一反应可能是 “为什么不自己写一个会话管理模块”，毕竟 Node.js 生态里做进程管理并不难。但真做过终端工具的人都知道，终端会话的持久化、分离重连、窗口分屏、滚动缓冲这些能力，自己实现一遍就是几个月的工作量，而且稳定性很难保证。

tmux 在这里扮演的角色，类似于一个 “终端操作系统”。它天然支持会话分离（detach）和重连（attach），这意味着你关掉 SSH 或者合上笔记本，AI 代理的会话还在后台跑着。它还支持窗口和面板切分，你可以左边跑 Claude Code 做代码审查，右边跑 Codex 执行命令，下面再挂一个日志窗口。这些能力如果让 openrig 自己实现，代码量会膨胀好几倍，而且大概率没有 tmux 稳定。

提示：tmux 的会话是独立于终端进程存在的。理解这一点很关键，它意味着 openrig 管理的不是 “窗口”，而是 “会话”，窗口只是会话的一个视图。

从编排层的角度看，openrig 用 Node.js 做胶水，通过子进程调用 tmux 命令来创建、切换、销毁会话。这个选择也有讲究。Node.js 的 child_process 模块处理这类 “调用外部命令并解析输出” 的场景非常顺手，而且 npm 生态里有大量现成的终端字符串处理库。更重要的是，Claude Code 和 Codex 本身很多就是 Node.js 写的或者通过 npm 分发的，用同一套运行时环境可以减少很多环境变量和路径上的坑。

2.2 多代理协同的核心矛盾：隔离还是共享

openrig 在设计上要回答一个根本问题：多个 AI 编码代理之间，应该是完全隔离的，还是共享某些状态？这个问题没有标准答案，取决于你的使用场景。

完全隔离的好处是干净。每个代理有自己的工作目录、自己的配置、自己的会话，互不干扰。但坏处也很明显：你没法让 Claude Code 审查 Codex 刚写的代码，也没法让两个代理看到同一份上下文。共享状态则相反，灵活但容易乱，一个代理改了文件另一个可能不知道。

openrig 的做法我理解是 “会话隔离、工作区共享”。每个 AI 代理跑在独立的 tmux 窗口或面板里，拥有独立的进程空间和配置加载路径，但它们默认指向同一个项目工作目录。这样你可以在一个窗口里让 Codex 生成代码，切到另一个窗口让 Claude Code 直接审查刚生成的文件，不需要手动复制粘贴。这个设计取舍很符合实际工作流——大多数时候你要的是 “同一个项目上的多个视角”，而不是 “多个互不相干的项目”。

2.3 配置层为什么要做统一抽象

Claude Code 和 Codex 的配置格式、环境变量、模型端点设置方式都不一样。Claude Code 有自己的 settings 文件和环境变量体系，Codex 也有自己的 config 文件。如果你同时用多个模型提供商，比如本地跑的 LM Studio、远程的 DeepSeek、或者官方端点，每个工具的配置方式都要单独学一遍。

openrig 在配置层做了一层抽象，把 “模型端点”、“API 密钥”、“工作目录”、“启动参数” 这些共性配置抽出来，再映射到各个工具自己的配置格式上。这个思路类似于 Docker Compose 对多个容器的编排——你写一份声明式的配置，由编排层负责翻译成各个工具能理解的参数。

这样做的好处是，当你需要切换模型端点时，只改一个地方，所有代理同步生效。坏处是抽象层本身需要维护，如果某个工具更新了配置格式，抽象层要跟着改。但对于同时用多个工具的人来说，这个维护成本远低于每次手动改多个配置文件。

3. 核心细节解析与实操要点

3.1 Node.js 环境准备：版本选择与安装避坑

openrig 跑在 Node.js 上，所以第一步是把 Node.js 环境弄好。这里有个很常见的坑：网上很多教程让你直接装最新版，但 AI 编码工具链对 Node.js 版本往往有要求。比如有些工具要求 Node.js 18 以上，有些在 Node.js 22 上会有兼容性问题。

我的建议是优先用 LTS 版本。截至我写这篇文章的时候，Node.js 20 LTS 和 22 LTS 是比较稳妥的选择。如果你在 Ubuntu 上，不要直接用 apt 里的 Node.js，那个版本通常很旧。推荐用 NodeSource 的仓库或者 nvm 来管理版本。

# 用 nvm 安装和管理 Node.js 版本（推荐） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 node -v

如果你在 Windows 上，直接从 Node.js 官网下载 LTS 版本的安装包就行。安装时注意勾选 “Add to PATH”，否则后面在终端里调 node 命令会找不到。安装完成后开一个新的终端窗口，运行node -v和npm -v确认版本。

注意：如果你看到类似 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这样的报错，说明你指定的版本号不存在或者还没发布。去 Node.js 官网确认当前可用的 LTS 版本号，不要凭记忆写版本。

3.2 tmux 的安装与基础会话管理

tmux 在大多数 Linux 发行版的仓库里都有，Ubuntu 上直接sudo apt install tmux就行。macOS 上用 Homebrew 安装。Windows 上原生没有 tmux，但如果你用 WSL，可以在 WSL 里装。

装好之后，先熟悉几个最基础的命令，这些是 openrig 底层会调用的：

# 创建一个名为 work 的会话 tmux new-session -d -s work # 列出所有会话 tmux ls # 连接到 work 会话 tmux attach -t work # 在 work 会话里创建一个新窗口 tmux new-window -t work -n claude # 向指定窗口发送命令 tmux send-keys -t work:claude 'claude' Enter

理解 tmux 的 “会话-窗口-面板” 三层结构很重要。一个会话可以包含多个窗口，一个窗口可以切分成多个面板。openrig 通常会为每个 AI 代理创建一个窗口，然后在窗口里跑对应的命令。你可以在会话之间自由切换，而所有代理进程都在后台持续运行。

提示：tmux 的默认前缀键是 Ctrl+b。所有 tmux 快捷键都要先按前缀键再按功能键。如果你觉得别扭，可以在 ~/.tmux.conf 里改成 Ctrl+a。

3.3 Claude Code 与 Codex 的安装要点

Claude Code 和 Codex 的安装方式各有不同，这里分别说一下我实测下来比较稳的路径。

Claude Code 通常通过 npm 全局安装：

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

安装完成后，在项目目录下运行claude就能启动。第一次启动会引导你完成认证。如果你在 VS Code 里用，也可以装对应的扩展，然后在 VS Code 的终端里直接调用。

Codex 的安装类似，也是 npm 全局包：

npm install -g @openai/codex

安装完成后运行codex启动。Codex 的配置通常在~/.codex/config或者项目目录下的配置文件里。如果你要接入第三方模型端点，比如 DeepSeek 或者本地 LM Studio，需要在这里配置 base URL 和 API key。

注意：安装全局 npm 包时如果遇到权限错误，不要直接用 sudo。正确做法是配置 npm 的全局目录到用户目录下，或者用 nvm 管理 Node.js，这样全局包会装在用户空间里，不需要提权。

3.4 配置统一抽象的具体做法

openrig 的配置抽象层，我理解核心是一份 YAML 或 JSON 格式的声明文件，里面定义了每个代理的启动参数、环境变量、工作目录和模型端点。然后由 Node.js 脚本读取这份配置，生成对应的 tmux 命令和工具配置文件。

一个简化的配置结构大概长这样：

agents: claude: tool: claude-code workdir: ~/projects/myapp model_endpoint: http://localhost:1234/v1 env: ANTHROPIC_BASE_URL: http://localhost:1234/v1 codex: tool: codex workdir: ~/projects/myapp model_endpoint: https://api.deepseek.com/v1 env: OPENAI_BASE_URL: https://api.deepseek.com/v1

这个配置的好处是，当你需要把 Claude Code 从本地 LM Studio 切到远程端点时，只改model_endpoint和对应的环境变量就行，不需要去翻 Claude Code 自己的配置文件。Codex 那边同理。

实际操作中要注意，不同工具对环境变量的读取时机不一样。有些工具在启动时读一次，有些在每次请求时都读。如果你在会话运行中改了配置，可能需要重启对应的代理进程才能生效。

4. 实操过程与核心环节实现

4.1 从零搭建 openrig 工作流的完整步骤

假设你现在什么都没有，想从零把 openrig 这套工作流跑起来，下面是我实测下来比较顺的步骤。

第一步，确认系统环境。你需要一个类 Unix 终端环境，Linux、macOS、WSL 都行。Windows 原生终端虽然也能跑 Node.js，但 tmux 支持不好，建议用 WSL。

第二步，安装 Node.js LTS 和 tmux。前面已经讲过具体命令，这里不重复。装完后确认node -v、npm -v、tmux -V都能正常输出版本号。

第三步，安装 Claude Code 和 Codex。用 npm 全局安装，确认claude --version和codex --version能正常输出。

第四步，创建 openrig 的工作目录和配置文件。我习惯在~/openrig下放配置，在~/projects下放实际项目。

mkdir -p ~/openrig cd ~/openrig npm init -y npm install js-yaml

第五步，写一个最简的编排脚本。这个脚本读取配置，创建 tmux 会话，为每个代理开一个窗口并启动对应命令。

// openrig.js const { execSync } = require('child_process'); const yaml = require('js-yaml'); const fs = require('fs'); const config = yaml.load(fs.readFileSync('./agents.yaml', 'utf8')); const sessionName = 'openrig'; // 创建会话（如果已存在则跳过） try { execSync(`tmux new-session -d -s ${sessionName}`); } catch (e) { // 会话已存在 } // 为每个代理创建窗口并启动 Object.entries(config.agents).forEach(([name, agent]) => { const cmd = agent.tool === 'claude-code' ? 'claude' : 'codex'; const envStr = Object.entries(agent.env || {}) .map(([k, v]) => `${k}=${v}`) .join(' '); execSync(`tmux new-window -t ${sessionName} -n ${name}`); execSync(`tmux send-keys -t ${sessionName}:${name} 'cd ${agent.workdir}' Enter`); execSync(`tmux send-keys -t ${sessionName}:${name} '${envStr} ${cmd}' Enter`); }); console.log(`openrig 会话已启动，运行 tmux attach -t ${sessionName} 进入`);

第六步，运行脚本并进入会话。

node openrig.js tmux attach -t openrig

进入后你应该能看到多个窗口，每个窗口里跑着一个 AI 代理。用 Ctrl+b 加数字键可以在窗口之间切换。

4.2 模型端点接入的实操细节

接入本地 LM Studio 或者远程模型端点，是很多人用 openrig 的核心诉求。这里以 LM Studio 为例说一下关键点。

LM Studio 启动本地服务后，默认监听http://localhost:1234/v1。你需要在 Claude Code 和 Codex 的配置里把 base URL 指过去。Claude Code 通过环境变量ANTHROPIC_BASE_URL控制，Codex 通过OPENAI_BASE_URL控制。

但这里有个容易踩的坑：不同工具对 API 格式的要求不一样。Claude Code 用的是 Anthropic 的 API 格式，Codex 用的是 OpenAI 的 API 格式。如果你的本地模型只支持其中一种，另一个工具可能连不上。LM Studio 通常两种格式都支持，但你要确认加载的模型和配置的端点路径匹配。

注意：如果你看到 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错，通常是代理层在转发请求时路径或格式不对。检查你的 base URL 是否包含了正确的路径前缀，以及代理是否支持目标 API 格式。

4.3 会话持久化与断线重连的实操

openrig 用 tmux 做会话承载，最大的好处就是持久化。你可以在笔记本上跑着代理，合上盖子去开会，回来打开终端tmux attach就能接着用。但有几个细节要注意。

第一，tmux 会话默认在服务器重启后会丢失。如果你需要跨重启保留，得用 tmux 的插件或者自己写脚本在启动时恢复。第二，长时间运行的会话里，AI 代理的上下文可能会变得很大，响应变慢。定期重启代理进程是个好习惯。第三，如果你通过 SSH 连到远程机器上跑 openrig，确保 SSH 配置里没有设置过短的超时，否则连接断了虽然 tmux 会话还在，但重连体验会受影响。

# 在 ~/.ssh/config 里加长超时 Host myserver ServerAliveInterval 60 ServerAliveCountMax 10

4.4 多代理协同的实际工作流示例

说一个我日常用得最多的场景。假设我在开发一个新功能，需要先让 Codex 根据需求生成代码骨架，然后让 Claude Code 审查代码质量，最后我自己在终端里跑测试。

在 openrig 会话里，我切到 codex 窗口，输入需求描述，让它生成代码。生成完成后，切到 claude 窗口，让它读取刚生成的文件并给出审查意见。两个窗口共享同一个工作目录，所以 Claude Code 能直接看到 Codex 写的文件，不需要我手动传递。

如果审查发现问题，我再切回 codex 窗口让它修改。整个过程都在一个 tmux 会话里完成，窗口切换用 Ctrl+b 加数字键，非常快。这比开多个终端窗口然后 Alt+Tab 切换要顺手得多，尤其是在全屏终端环境下。

5. 常见问题与排查技巧实录

5.1 安装与启动阶段的典型报错

这个阶段的问题大多和环境有关。我整理了一个速查表，覆盖了我遇到过和社区里反馈比较多的几种情况。

提示：遇到 “command not found” 时，先运行npm bin -g看看全局 bin 目录在哪，然后确认这个目录在 PATH 里。这是最高频的问题，没有之一。

5.2 模型接入阶段的连接问题

模型接入的问题通常表现为请求超时、返回格式错误、或者认证失败。排查顺序建议是：先确认端点本身可达，再确认 API 格式匹配，最后确认认证信息正确。

# 测试端点是否可达 curl http://localhost:1234/v1/models # 测试 API 格式（以 OpenAI 格式为例） curl http://localhost:1234/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"your-model","messages":[{"role":"user","content":"hi"}]}'

如果 curl 能通但工具连不上，大概率是工具侧的配置问题。检查环境变量是否在正确的时机被读取，以及是否有其他配置文件覆盖了你的设置。

5.3 会话管理中的常见坑

tmux 会话管理这块，我踩过的坑主要有几个。一是窗口命名冲突，如果你用同一个名字创建多个窗口，tmux 会自动加后缀，导致脚本里按名字定位窗口时找不到。二是 send-keys 发送命令时，如果命令里有特殊字符，可能被 tmux 解释成快捷键。三是会话里的工作目录不会自动继承，每个新窗口都要手动 cd。

针对第一个问题，我的做法是在脚本里用窗口索引而不是名字来定位。针对第二个问题，发送复杂命令时用send-keys -l参数，让 tmux 按字面量处理。针对第三个问题，可以在创建窗口时直接用-c参数指定起始目录。

# 创建窗口时指定工作目录 tmux new-window -t openrig -n codex -c ~/projects/myapp # 按字面量发送命令，避免特殊字符被解释 tmux send-keys -t openrig:codex -l 'echo "hello world"' tmux send-keys -t openrig:codex Enter

5.4 性能与资源占用的观察

同时跑多个 AI 代理，资源占用是绕不开的话题。我的实测是，两个代理同时空闲时，内存占用大概在几百 MB 级别，主要看 Node.js 运行时本身的开销。但如果代理正在处理大文件或者长上下文，内存会明显上升。

如果你在资源有限的机器上跑，建议不要同时开太多代理。另外，tmux 的滚动缓冲默认是 2000 行，如果你跑了很多输出，可以适当调大，但也会占内存。在~/.tmux.conf里设置set-option -g history-limit 10000可以调到一万行。

还有一个容易被忽略的点：AI 代理的日志文件。有些工具会把详细日志写到磁盘上，跑久了可能占几个 GB。定期清理日志目录是个好习惯，或者配置日志轮转。

5.5 我个人的几条避坑经验

第一条，不要在生产环境的机器上直接跑 openrig 的实验性配置。先在本地或者测试机上跑通，再迁移到常用环境。第二条，配置文件一定要纳入版本管理，这样改坏了能回滚。第三条，tmux 会话名和窗口名用有意义的命名，别用默认的 0、1、2，过两天你自己都忘了哪个是哪个。第四条，如果某个工具更新后 openrig 的编排脚本失效了，先去看工具的更新日志，大概率是启动参数或者配置格式变了。第五条，遇到问题先看日志，AI 代理工具通常会把详细错误写到日志文件里，比终端上显示的那一行信息有用得多。

6. 后续可以怎么扩展这套工作流

openrig 这套思路跑通之后，能扩展的方向其实不少。比如你可以加一个 “任务队列” 层，把需要 AI 处理的任务写到一个队列里，让多个代理轮流消费。也可以加一个简单的 Web 界面，用浏览器查看各个会话的状态和输出。还可以把常用的提示词模板化，在启动代理时自动注入。

我目前在做的一个扩展是给 openrig 加一个 “健康检查” 功能，定期检查每个代理进程是否还活着，如果挂了就自动重启。这个用 Node.js 的定时任务加 tmux 的会话检测就能实现，代码量不大但很实用。另一个想法是把 openrig 的配置和 dotfiles 管理结合起来，这样换机器的时候一套配置直接同步过去，不用重新搭环境。

这套东西的价值不在于它有多复杂，而在于它把多个 AI 编码代理的日常使用体验理顺了。你不用再记每个工具各自的启动方式和配置位置，也不用在多个终端窗口之间反复横跳。一个 tmux 会话，几个窗口，所有代理各就各位，该干活干活，该审查审查。这种 “工作台” 式的体验，用惯了之后很难回去。