企业官网建设流程全解析

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

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 “rig” 这个词在英文里常指设备支架、矿机架或者实验台。但在当前 AI 编程助手爆发的背景下，openrig 实际上是一个围绕Claude Code、Codex 等命令行 AI 编程工具构建的开源配置管理与运行环境编排方案。它的核心目标很直接：让你在不同机器、不同终端会话、不同模型供应商之间，快速切换和稳定运行这些 AI 编程助手，而不是每次手动改配置、重装依赖、重新登录。

我最初接触 openrig 是因为一个很现实的问题：我在本地同时用 Claude Code 做代码审查，用 Codex 做快速补全和重构，偶尔还要把请求转发到本地模型做离线测试。每换一个项目目录，就要改一遍 YAML 配置；每开一个新终端，就要重新确认环境变量有没有加载；tmux 会话一多，根本记不清哪个窗口跑的是哪个工具。openrig 的出现，本质上是把“AI 编程助手的运行环境”当成一个可声明、可复现、可版本管理的工程问题来处理。

它适合的人群很明确：第一，已经在用或者准备用 Claude Code、Codex 这类 CLI 工具的开发者；第二，需要在多台机器之间同步配置的人；第三，想把本地模型、远程 API、不同供应商统一接入同一套工作流的人；第四，喜欢用 tmux 做多会话管理、追求终端效率的工程师。如果你只是偶尔在网页上问问代码问题，那 openrig 可能有点重；但如果你已经把 AI 编程助手当成日常主力工具，它的价值会非常明显。

从热词分布也能看出来，大家最关心的几个点集中在：Claude Code 安装与使用、Codex 安装与登录、YAML 配置文件怎么写、tmux 怎么配合、本地模型怎么接入、以及各种代理和端点报错怎么排查。openrig 恰好覆盖了这些痛点，它不是某一个单独的工具，而是一层“胶水”和“规范”，把配置、启动、切换、日志、会话管理串起来。

提示：openrig 本身不是模型，也不是 API 供应商。它不提供算力，也不绕过任何官方限制。它做的事情是让你已有的工具和账号在本地跑得更顺、更可管理。

2. openrig 的整体设计思路与核心组件拆解

2.1 为什么选择 YAML 作为配置核心

openrig 用 YAML 作为主要配置格式，这个选择不是随意的。YAML 在 DevOps 和云原生领域已经是事实标准，Kubernetes、GitHub Actions、Docker Compose、Ansible 都在用。它的优势在于：结构清晰、支持嵌套、可读性好、注释方便、几乎所有语言都有成熟解析库。对于 AI 编程助手这种需要描述“多个供应商、多个模型、多个端点、多个环境变量”的场景，YAML 比 JSON 更适合手写，比 TOML 更适合表达层级关系。

一个典型的 openrig 配置会包含几个核心块：providers定义模型供应商，比如官方 API、本地推理服务、第三方兼容端点；agents定义 Claude Code、Codex 等工具的运行参数；sessions定义 tmux 会话布局；env定义环境变量注入规则。这样设计的好处是，你不需要记住每个工具的具体环境变量名，只需要在 YAML 里声明“我要用哪个供应商”，openrig 负责把它翻译成对应工具能识别的格式。

我自己的习惯是把配置分成三层：全局默认配置放在~/.config/openrig/base.yaml，项目级覆盖放在项目根目录的.openrig.yaml，临时实验配置放在~/.config/openrig/experiments/下。这样既保证了常用配置的稳定性，又不会因为一次实验把主环境搞乱。YAML 的合并策略通常是深度合并，但要注意列表类型一般是替换而不是追加，这个后面会详细说。

2.2 Claude Code 与 Codex 的差异化接入

Claude Code 和 Codex 虽然都是命令行 AI 编程助手，但它们的配置方式、认证机制、端点格式并不一样。Claude Code 更偏向于通过环境变量和配置文件来指定 API 端点与密钥，Codex 则有自己的登录流程和 token 管理机制。openrig 的价值就在于把这些差异封装起来，对外提供统一的“启动一个 agent”的接口。

具体来说，Claude Code 常见的配置项包括 API base URL、API key、模型名称、最大上下文长度等。Codex 则涉及 auth token、组织 ID、端点路径等。openrig 在内部为每个 agent 维护一个适配器，把统一的 YAML 字段映射到各自需要的环境变量或配置文件。比如你在 YAML 里写provider: local-deepseek，openrig 会根据当前 agent 是 Claude Code 还是 Codex，分别设置不同的变量名和端点路径。

这里有一个容易踩的坑：不同版本的 Claude Code 和 Codex 对环境变量的命名可能发生变化。openrig 的适配器需要跟随上游更新，所以建议锁定版本，不要盲目追最新。我在实际使用中会把每个 agent 的版本号也写进 YAML，这样换机器时能复现完全一致的环境。

2.3 tmux 在 openrig 中的角色

tmux 是 openrig 的“会话层”。很多人用 tmux 只是为了防止 SSH 断连，但 openrig 把 tmux 用成了多 agent 并行工作的调度台。你可以定义一个 session 叫ai-work，里面开三个 window：一个跑 Claude Code 做代码审查，一个跑 Codex 做补全，一个跑日志监控。openrig 可以根据 YAML 里的sessions配置自动创建这些 window，并注入对应的环境变量。

这样做的好处是，你不需要每次手动开三个终端、cd 到不同目录、export 一堆变量。一条openrig up ai-work就能把整个工作环境拉起来。而且 tmux 的 session 可以 detach 和 reattach，即使本地终端关了，远程机器上的 agent 还在跑。对于需要长时间运行的任务，比如让 Claude Code 扫描整个仓库，这个特性非常实用。

注意：tmux 的 window 和 pane 布局在不同终端尺寸下可能错乱。建议在 YAML 里使用相对布局而不是绝对坐标，openrig 通常会提供layout: even-horizontal或layout: tiled这类选项。

2.4 本地模型与远程 API 的统一抽象

热词里频繁出现“Claude Code 调用 LM Studio 的本地模型”“Codex 接入 DeepSeek”，说明大家很关心如何把不同来源的模型统一接入。openrig 的设计思路是：不管模型跑在本地还是远程，只要它提供兼容的 HTTP 端点，就把它抽象成一个provider。本地 LM Studio 通常暴露http://localhost:1234/v1，DeepSeek 有官方兼容端点，其他开源推理框架也大多支持 OpenAI 风格的接口。

在 YAML 里，你只需要定义 provider 的base_url、api_key、model三个核心字段，openrig 会根据 agent 类型决定如何注入。对于本地模型，api_key 通常可以随便填一个占位符，但有些工具会校验非空，所以不要留空。对于远程 API，密钥建议通过环境变量引用，而不是直接写在 YAML 里，避免误提交到 Git。

这里的关键点是端点路径的拼接。Claude Code 和 Codex 对/v1、/responses、/chat/completions这些路径的处理方式不同。openrig 的适配器需要知道当前 agent 期望的路径格式，必要时做重写。热词里出现的 “cc switch local proxy failed while handling codex endpoint /responses” 就是典型的路径不匹配问题，后面排查章节会详细讲。

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

3.1 YAML 配置文件的结构设计

一个可用的 openrig YAML 配置，我建议至少包含以下顶层字段：

version: 1 providers: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: local-placeholder model: qwen2.5-coder-7b deepseek-remote: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat agents: claude: provider: deepseek-remote extra_env: CLAUDE_CODE_MAX_OUTPUT_TOKENS: "8192" codex: provider: local-lmstudio extra_env: CODEX_MODEL: qwen2.5-coder-7b sessions: ai-work: windows: - name: claude agent: claude cwd: ~/projects/main - name: codex agent: codex cwd: ~/projects/main - name: logs command: tail -f ~/.local/state/openrig/agent.log

这个结构的设计逻辑是：providers和agents解耦，同一个 provider 可以被多个 agent 复用；sessions和agents解耦，同一个 agent 可以出现在多个 session 里。这样当你换模型供应商时，只需要改 provider 的 base_url 和 model，所有引用它的 agent 自动生效。

version字段很重要，openrig 在不同大版本之间可能有配置格式变化。写上版本号可以让工具在加载时做兼容性检查，避免用旧格式跑新版本导致莫名其妙的问题。

3.2 环境变量注入的优先级与陷阱

openrig 在启动 agent 时，会按照一定优先级注入环境变量。通常的顺序是：系统环境变量 < 全局 YAML 的env< 项目 YAML 的env< agent 的extra_env< session 的env。后面的覆盖前面的。这个设计让你可以在不同层级做覆盖，但也容易踩坑。

最常见的坑是：你在 shell 里已经 export 了一个OPENAI_API_KEY，但 YAML 里又定义了一个不同的值，结果 agent 用了 YAML 里的，而你以为是 shell 里的。排查这类问题时，可以在 openrig 启动后打印最终生效的环境变量，或者用openrig debug env <agent>这类命令查看。

另一个坑是变量引用。YAML 里写${DEEPSEEK_API_KEY}时，openrig 需要知道从哪里读取这个变量。如果 shell 里没有设置，有些实现会报错，有些会留空字符串。留空字符串更危险，因为 agent 可能带着空密钥去请求，然后返回一个模糊的认证失败。建议在 YAML 里对关键变量做非空校验，或者至少在启动日志里明确提示。

提示：不要把真实密钥直接写进 YAML 并提交到版本控制。用${VAR}引用，配合.env文件或系统密钥管理工具。openrig 通常支持从.env文件加载变量，但要注意.env也要加入.gitignore。

3.3 Claude Code 安装与配置的关键步骤

Claude Code 的安装方式在不同平台上略有差异。常见做法是通过包管理器或安装脚本获取 CLI 二进制，然后配置 API 端点和密钥。openrig 不会替代安装过程，但它可以在安装完成后接管配置管理。

安装完成后，你需要确认几件事：第一，claude命令是否在 PATH 里；第二，版本号是否与 YAML 里声明的一致；第三，默认配置文件位置在哪里。Claude Code 通常会读取用户主目录下的某个配置目录，openrig 在启动时会根据 YAML 生成临时配置或设置环境变量，覆盖默认值。

一个实操技巧是：先用原生方式手动跑通一次 Claude Code，确认账号、端点、模型都能正常工作，然后再把这套配置迁移到 openrig 的 YAML 里。这样如果出问题，你能快速判断是 openrig 的注入逻辑有问题，还是上游工具本身有问题。我见过不少人一上来就全交给 openrig，结果报错时完全不知道是哪一层出的问题。

3.4 Codex 安装与登录的注意事项

Codex 的安装和登录流程相对独立。它通常需要先通过 CLI 完成登录，获取 auth token，然后才能调用模型。openrig 可以管理 token 的存储位置和注入方式，但不能代替你完成首次登录。

热词里出现 “codex auth token is unavailable” 和 “codex 登录”，说明 token 管理是高频问题。常见原因有几个：token 过期、token 存储路径不对、环境变量没有正确传递、或者多台机器之间 token 没有同步。openrig 的做法通常是把 token 文件路径写进 YAML，启动时检查文件是否存在且未过期，如果过期则提示重新登录。

另一个注意点是 Codex 的端点路径。有些兼容端点使用/responses而不是/chat/completions，如果 openrig 的适配器没有正确重写路径，就会报 “local proxy failed while handling codex endpoint /responses” 这类错误。解决方法是确认 provider 的 base_url 是否包含了正确的版本前缀，以及 agent 适配器是否知道当前 Codex 版本期望的路径格式。

3.5 tmux 会话布局的实操配置

tmux 会话配置是 openrig 里最容易出效果、也最容易出问题的部分。一个实用的布局是：左侧一个大 pane 跑主 agent，右侧上下两个小 pane，一个跑日志，一个跑辅助命令。openrig 的 YAML 里可以用layout字段描述这种结构。

实际操作中，我建议先用 tmux 手动搭一次你想要的布局，然后用tmux list-windows和tmux display-message -p查看具体的 pane 划分参数，再把这些参数写进 YAML。这样比凭空想象布局要靠谱得多。另外，tmux 的remain-on-exit选项建议打开，这样 agent 崩溃时 pane 不会立刻关闭，你能看到最后的错误信息。

还有一个细节：openrig 启动 session 时，如果同名 session 已经存在，是复用还是重建？不同实现策略不同。我倾向于配置成“如果存在则 attach，不存在则创建”，避免误杀正在运行的任务。如果需要强制重建，应该有一个显式的--force参数。

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

4.1 环境准备与依赖安装

在开始配置 openrig 之前，你需要先准备好基础环境。以常见的 Linux 或 macOS 开发机为例，核心依赖包括：一个可用的 shell（bash 或 zsh）、tmux、Git、以及 Claude Code 和 Codex 的 CLI 本体。如果你打算接入本地模型，还需要一个本地推理服务，比如 LM Studio 或其他兼容 OpenAI 接口的运行时。

安装顺序建议是：先装 tmux 和 Git，再装 Claude Code 和 Codex，最后装 openrig。每装完一个，都手动验证一下命令是否可用。比如tmux -V、claude --version、codex --version。这样能把问题隔离在单个组件里，而不是等到 openrig 启动时一起爆发。

openrig 本身的安装方式取决于它的发布形式。如果是 Go 或 Rust 写的二进制，通常直接下载对应平台的可执行文件放到 PATH 即可；如果是 Node 或 Python 写的，可能需要包管理器。安装完成后，运行openrig --version和openrig doctor做一次自检。doctor命令通常会检查依赖是否齐全、配置文件是否可解析、关键环境变量是否存在。

注意：如果你在 Windows 上使用，建议通过 WSL 运行这套工具链。原生 Windows 下 tmux 不可用，Claude Code 和 Codex 的某些行为也可能不一致。WSL 能提供接近 Linux 的体验，减少兼容性问题。

4.2 编写第一份 openrig YAML 配置

第一份配置不要追求大而全，先跑通一个 agent、一个 provider、一个 session。我建议从本地模型开始，因为本地模型不依赖网络和远程密钥，排查起来最简单。

假设你用 LM Studio 在本地启动了推理服务，监听http://127.0.0.1:1234，加载了一个代码模型。那么最小配置可以这样写：

version: 1 providers: local: base_url: http://127.0.0.1:1234/v1 api_key: local model: your-local-model-name agents: claude: provider: local sessions: test: windows: - name: claude agent: claude

保存到~/.config/openrig/base.yaml，然后运行openrig up test。如果一切正常，你会进入一个 tmux session，里面有一个 window 跑着 Claude Code，并且已经指向本地模型。这时候你可以问它一个简单的代码问题，看是否能正常返回。

如果报错，先看 openrig 的启动日志，确认它注入的环境变量是什么，再手动在 shell 里 export 同样的变量，直接跑claude命令，对比行为。这一步能快速定位是 openrig 的问题还是上游工具的问题。

4.3 接入远程 API 与密钥管理

本地跑通后，再接入远程 API。以 DeepSeek 为例，你需要在环境里设置DEEPSEEK_API_KEY，然后在 YAML 里新增一个 provider：

providers: deepseek: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-chat

然后把 agent 的 provider 改成deepseek。重启 session 后，Claude Code 或 Codex 就会通过 DeepSeek 的端点来请求模型。

这里的关键是密钥不要硬编码。用${DEEPSEEK_API_KEY}引用，并在 shell 的配置文件里 export，或者用.env文件加载。如果你在多台机器上工作，建议用统一的密钥管理方式，比如系统钥匙串或加密的 dotfiles 仓库。openrig 本身不负责密钥加密，它只负责读取和注入。

一个实操心得是：为不同的 agent 使用不同的密钥或不同的 provider 别名。比如deepseek-for-claude和deepseek-for-codex，即使它们指向同一个端点。这样当某个 agent 出问题时，你能快速切换而不影响另一个。

4.4 多 agent 并行会话的搭建

当你需要同时跑 Claude Code 和 Codex 时，session 配置就派上用场了。一个实用的双 agent 布局：

sessions: dual: windows: - name: claude agent: claude cwd: ~/projects/app - name: codex agent: codex cwd: ~/projects/app - name: shell command: bash cwd: ~/projects/app

启动openrig up dual后，你会得到三个 window。用Ctrl-b n在 window 之间切换。Claude Code 可以用来做整体架构审查和复杂重构，Codex 可以用来做快速补全和单元测试生成。两者共享同一个项目目录，但各自有独立的会话状态。

需要注意的是，两个 agent 同时修改同一个文件可能冲突。建议在分工上明确：一个负责读和审查，一个负责写和补全；或者在不同的 Git 分支上工作。openrig 不解决并发编辑冲突，这是工作流层面要设计的事情。

4.5 日志、监控与状态查看

openrig 运行过程中，日志是排查问题的第一手资料。建议在 session 里专门开一个 window 跑日志监控，比如tail -f ~/.local/state/openrig/agent.log。日志里应该包含：启动时间、加载的配置文件、生效的 provider、注入的环境变量（密钥要脱敏）、agent 的退出码。

如果 openrig 支持状态命令，比如openrig status，可以查看当前有哪些 session 在跑、每个 session 里有哪些 agent、它们分别用的什么 provider。这个在多个项目并行时特别有用，避免你忘了某个 session 还在跑，占着本地模型或者消耗远程额度。

提示：日志文件建议做轮转，避免长期运行后占满磁盘。可以用系统的 logrotate，或者在 openrig 配置里设置最大日志大小和保留份数。

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

5.1 端点路径不匹配导致的代理失败

热词里 “cc switch local proxy failed while handling codex endpoint /responses” 是一个典型问题。它的根源通常是：Codex 期望的请求路径是/responses，但本地代理或 provider 的 base_url 配置成了/v1，导致最终请求路径变成/v1/responses或者/responses/v1，服务端不认识。

排查步骤：第一，确认 provider 的 base_url 是否包含了正确的版本前缀；第二，确认 agent 适配器是否对路径做了重写；第三，用curl手动请求目标端点，看服务端实际接受什么路径。比如：

curl -v http://127.0.0.1:1234/v1/responses \ -H "Content-Type: application/json" \ -d '{"model":"your-model","input":"hello"}'

如果返回 404，说明路径不对；如果返回 401，说明路径对了但认证有问题；如果返回 200，说明路径和认证都没问题，那问题就在 openrig 的注入逻辑上。

5.2 认证失败与 token 不可用

“codex auth token is unavailable” 通常意味着 Codex 找不到有效的 token。可能原因包括：token 文件不存在、token 过期、环境变量没有传递、或者 token 存储路径与 Codex 期望的不一致。

解决思路：先手动运行codex的登录命令，确认能正常登录并生成 token。然后找到 token 文件的实际路径，把它写进 openrig 的 YAML。如果 Codex 支持通过环境变量传递 token，优先用环境变量，因为这样 openrig 的注入更直接。注意不要在有日志输出的地方打印完整 token，只打印前几位和后几位用于确认。

5.3 本地模型连接失败

本地模型连接失败常见于几种情况：推理服务没有启动、端口不对、模型名称不对、或者防火墙拦截。先用curl确认服务可达，再确认模型名称与 LM Studio 里加载的一致。有些推理服务要求model字段必须精确匹配，差一个字符都会报错。

另一个坑是api_key留空。虽然本地服务通常不校验密钥，但某些客户端库会检查非空。填一个占位符比如local就能绕过。如果 openrig 的 YAML 里写的是${LOCAL_API_KEY}而环境变量没设置，最终会变成空字符串，也可能触发这个问题。

5.4 tmux 会话异常与恢复

tmux 会话异常通常表现为：session 创建失败、window 数量不对、pane 布局错乱、或者 agent 启动后立刻退出。排查时先用tmux ls看 session 是否存在，再用tmux attach -t <name>进去看具体状态。

如果 agent 启动后立刻退出，多半是环境变量或配置有问题。可以在 session 里手动跑一次 agent 命令，看报错信息。如果 pane 布局错乱，检查 YAML 里的 layout 参数是否与当前终端尺寸兼容。必要时先用简单布局跑通，再逐步调整。

5.5 常见问题速查表

5.6 独家避坑经验

第一个经验：永远先手动跑通，再交给 openrig。openrig 是一层封装，封装会隐藏细节，也会隐藏错误。手动跑通意味着你知道正确的命令、正确的环境变量、正确的端点，这样 openrig 出问题时你能快速对比。

第二个经验：YAML 里的列表合并要小心。很多配置合并工具对列表是替换而不是追加。如果你在项目级 YAML 里写了一个windows列表，它可能会完全覆盖全局的windows列表，而不是追加。需要追加时，用显式的合并键或者分开命名。

第三个经验：版本锁定。Claude Code、Codex、openrig 本身都在快速迭代，今天能用的配置明天可能因为上游改名而失效。在生产环境或主力工作流里，锁定版本号，升级前先在实验环境验证。

第四个经验：日志脱敏。openrig 的日志里可能包含环境变量，如果直接打印，密钥会泄露。确保日志组件对KEY、TOKEN、SECRET这类变量名做脱敏处理，只显示前后几位。

6. 进阶用法与工作流扩展

6.1 多项目配置继承与覆盖

当你同时维护多个项目时，配置继承能大幅减少重复。做法是：全局 YAML 定义通用 provider 和 agent 模板，项目级 YAML 只写差异部分。比如全局定义deepseekprovider，项目 A 覆盖 model 为deepseek-chat，项目 B 覆盖 model 为deepseek-coder。

openrig 的合并策略需要明确：标量覆盖，映射深度合并，列表替换。理解这个规则后，你就能设计出清晰的配置层级。我通常把项目级配置控制在 20 行以内，只写真正不同的部分，其余全部继承全局。

6.2 结合 Git 做配置版本管理

把 openrig 的 YAML 配置纳入 Git 管理，能带来几个好处：配置变更可追溯、多机器同步方便、出问题能回滚。但要注意密钥不能进 Git。做法是：YAML 里只写${VAR}引用，真实密钥放在.env文件或系统密钥管理里，.env加入.gitignore。

如果团队多人使用，可以维护一个共享的配置仓库，每个人用自己的.env覆盖密钥。这样 provider 定义、agent 参数、session 布局都能统一，减少“我这里能跑你那里不能跑”的问题。

6.3 与编辑器和工作流的衔接

openrig 管的是终端里的 agent 运行环境，但你的日常工作可能还在 VS Code 或其他编辑器里。一个实用的衔接方式是：在 VS Code 的集成终端里 attach 到 openrig 创建的 tmux session，这样编辑器里就能直接看到 agent 的输出，同时保留 tmux 的会话管理能力。

另一个方式是：用 openrig 启动 agent 后，把 agent 的输出日志写到固定文件，然后在编辑器里用 tail 插件实时查看。这样你不需要切换窗口，就能看到 Claude Code 或 Codex 的实时反馈。

6.4 资源占用与性能调优

同时跑多个 agent 和本地模型时，资源占用会明显上升。本地模型吃 GPU 和内存，多个 agent 吃 CPU 和网络。建议根据机器配置限制并行数量。比如 16GB 内存的机器，本地模型加两个 agent 可能就到极限了。

openrig 层面可以做的优化包括：延迟启动非关键 agent、复用同一个 provider 连接、限制日志写入频率。如果本地模型响应慢，可以考虑换更小的量化模型，或者把非关键任务切到远程 API。

7. 我个人的使用体会与几个实用建议

我用 openrig 管理 Claude Code 和 Codex 的工作流已经有一段时间了，最大的感受是：它把“配置”从一件每次都要重新想的事情，变成了一件写一次就能反复用的事情。以前换机器要折腾半天，现在把 YAML 和.env同步过去，基本就能复现。

几个我觉得特别值得做的习惯：第一，给每个 provider 起一个有意义的名字，不要用provider1、provider2，用local-qwen、deepseek-chat这种一看就懂的。第二，session 名字用项目名或用途名，比如app-review、lib-refactor，不要用test1、test2。第三，定期清理不再使用的 provider 和 session 配置，避免 YAML 越来越臃肿。

还有一个小心得：openrig 的配置文件本身也值得写注释。YAML 支持#注释，把你为什么选这个模型、为什么用这个端点、这个参数是干什么的，简单写一句。过几个月回头看，你会感谢自己。

最后再分享一个排查技巧：当 openrig 启动失败但报错信息很模糊时，用openrig --dry-run或者类似的调试模式，让它只打印将要执行的操作和将要注入的环境变量，而不真正启动 agent。这样你能在不产生副作用的情况下，看清 openrig 到底做了什么。这个技巧帮我省了很多次反复启动和退出的时间。