OpenRig rig export与import：Agent团队状态跨实例迁移完整流程-二趣网

OpenRig rig export与import：Agent团队状态跨实例迁移完整流程

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig 是一个把 Claude Code 与 Codex 组合成统一系统的多智能体框架（Multi-agent harness）。当你要把一支 Agent 团队从一台机器搬到另一台、或从一个工作区复制给同事时，核心就是rig export与rig import这对命令：前者把正在运行的 Rig（Agent 团队）导出为 YAML 规格文件，后者在新实例上导入并重新启动整套团队。本文带你走通这条"导出 → 迁移 → 导入 → 验证"的完整链路。

为什么需要 export/import

在 OpenRig 中，一个Rig就是一支有明确组织架构的 Agent 团队：它由若干Pod（小组）和Member（具体 Agent 节点）组成，并声明了成员之间的关系（谁委托谁、谁观察谁、谁与谁协作）。团队的"完整状态"并不散落在终端里，而是被抽象为一份RigSpec（YAML 规格）——节点、Agent 引用、运行时（claude-code / codex / terminal）、工作目录、启动动作全部可序列化。

这正是跨实例迁移的基础：

export 是"拍下快照"：从运行中的 daemon 拉取当前 Rig 的规格，落盘成rig.yaml；
import 是"按图纸重建"：在新实例上解析 YAML，完成校验、预检、实例化，重新拉起整套团队。

第一步：rig export 导出团队规格

CLI 命令定义在 export.ts，用法非常简单：

rig export <rigId> -o rig.yaml

第一个参数是Rig ID（用rig ps查看当前所有 Rig）；
-o / --output指定输出文件路径，不传时默认写入rig.yaml；
export 会先检查本地 daemon 是否运行，未启动时会直接提示，不会发出无效请求。

导出的内容就是一份标准的 RigSpec YAML，例如项目自带演示规格的这种结构：

version: "0.2" name: demo-rig culture_file: culture.md pods: - id: orch label: Orchestration members: - id: lead agent_ref: "local:agents/lead" runtime: claude-code

完整示例见 demo/rig.yaml：它声明了 orch（编排）、dev（开发）、rev（评审）三个 Pod，以及delegates_to这类跨 Pod 协作边——这些结构导出后都会完整保留，是迁移后团队"神似"的关键。

💡 小贴士：export 失败时先确认 daemon 健康状态（rig doctor），404 说明 Rig ID 不存在，5xx 则看 daemon 日志。

第二步：在新实例上准备导入环境

导入前，目标实例需要满足三个条件：

daemon 已启动——import 与 export 一样依赖本地 daemon 处理校验与实例化；
Agent 定义可达——RigSpec 中的agent_ref（如local:agents/lead）指向的 Agent 定义文件要随规格一起拷贝过来，演示仓库中的布局是 demo/agents/；
路径一致或已调整——cwd等相对路径在解析时会基于规格文件所在目录或--rig-root，跨机器时注意目标目录是否存在。

第三步：rig import 的四种姿势

导入命令定义在 import.ts，同一个命令通过参数提供从轻到重的四种模式，建议按顺序逐级执行：

模式	命令	作用	何时用
校验	`rig import rig.yaml`	仅校验 YAML 结构	拿到文件后的第一道关
预检	`rig import rig.yaml --preflight`	检查运行环境（名称冲突、依赖可用性等）	实例化前的体检
物化	`rig import rig.yaml --materialize-only [--target-rig <id>]`	只建拓扑、不启动会话	先搭骨架，人工确认后再点火
实例化	`rig import rig.yaml --instantiate`	完整重建团队并启动所有 Agent	正式迁移

几个常用选项：

--target-rig <rigId>：把规格增量物化进已有 Rig（如新增一个 Pod），而不是创建新团队；
--rig-root <root>：Pod 感知规格的根目录，用于解析相对路径；不传时默认取规格文件所在目录；
--cwd <path>：覆盖所有成员的启动工作目录（相对路径会被自动转为绝对路径）。

CLI 内置了互斥保护：--instantiate与--materialize-only不能同用，--workspace-only必须搭配--target-rig，写错参数会立刻报错并退出，不会留下半成品状态。

成功实例化后，终端会逐节点打印状态，并给出接入命令：

Rig created: demo-rig (rig-xxx) orch.lead: launched dev.impl: launched dev.qa: launched Attach: tmux attach -t orch-lead@demo-rig

⏱ 注意：--instantiate会等待所有节点就绪，CLI 为此内置了 120 秒的长时超时预算，成员较多时耐心等它跑完即可。

第四步：迁移后验证三件套

导入完成后，用三个命令确认团队完整落地（完整操作参考 skills/_canonical/core/ 下的 openrig-user 技能文档）：

rig ps --nodes --rig <rigId> # 节点是否全部出现 rig status # daemon 与各节点健康度 rig export <rigId> -o rig2.yaml # 再次导出，与迁移前文件 diff 比对

第三次导出是"黄金验证"：把迁移前的rig.yaml与迁移后的rig2.yaml做文本对比，结构一致即说明团队状态无损迁移。

常见报错速查

现象	原因	解决
`not running`	daemon 未启动	先启动 daemon（`rig up`/ 参考启动文档）
`Cannot read file`	规格文件路径错误	检查相对路径，改用绝对路径
`A rig with this name is already running`	目标实例已有同名 Rig	改规格中的`name`，或用`--target-rig`增量物化
Preflight`not ready`	环境不满足（如名称冲突、依赖缺失）	按输出的 errors 列表逐项修复后重试
导入成功但 Agent 找不到定义	`agent_ref`指向的 agent 文件未随迁	拷贝 demo/agents/ 这类 Agent 定义目录到相同相对位置

小结：两条命令，完整迁移

导出：rig export <rigId> -o rig.yaml—— 把运行中团队的完整规格落盘；
导入：rig import rig.yaml --instantiate—— 在新实例校验、预检后一键重建并启动；
进阶：--materialize-only搭骨架、--target-rig增量合并、--workspace-only只同步工作区声明；
验证：rig ps+ 二次导出 diff，确认状态无损。

配合rig bundle（把规格 + skills + 插件打包成.rigbundle），OpenRig 的 export/import 让"Agent 团队"第一次像代码一样可以备份、版本化和跨实例流转。

企业官网建设流程全解析