OpenRig 跨主机文件传输安全指南：rig file 五层防护机制完整教程

【免费下载链接】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 是一个开源的 AI Agent 团队编排工具，你只用一个rig.yaml文件就能定义自己的 Agent 团队，并用rig file copy命令在多台主机之间安全传输文件。本文带你了解 OpenRig 的 rig file 文件传输语法、跨主机文件操作方式，以及它内建的"五层安全防护墙"是如何防止路径穿越、命令注入和敏感目录误伤的。

什么是 OpenRig 的 rig file（团队定义文件）

rig file 就是描述"你的 Agent 团队长什么样"的 YAML 文件。它声明了每个成员的agent_ref、运行器（claude-code、codex或terminal）、工作目录和成员之间的协作关系（edges）。项目自带的完整示例可以直接参考：demo/rig.yaml

pods: - id: dev label: Development members: - id: impl agent_ref: "local:agents/impl" runtime: claude-code cwd: .

rig 起来之后，你可以在共享 TUI 里看到整个团队的拓扑结构：每个座位（seat）对应一个 Agent，标注了运行器、模型和当前状态。

为什么文件传输必须和 rig file 绑定

Agent 团队常常分布在不同机器上：一台本地工作站跑 Claude Code，一台 VPS 跑 Codex。此时"把一个文件从本地拷到远端"就是高频操作。OpenRig 把这件事收敛成一个显式动词——rig file copy，并且把源、目标、策略全部写在命令行里，绝不从当前目录或环境变量里"猜"。

rig file copy 命令怎么用

命令入口在 packages/cli/src/commands/file.ts，基本用法：

三条关键规则，新手最容易踩坑：

1. <主机ID>:<绝对路径>才表示远端。裸路径永远是本机文件；路径以/、./、../、~开头时，即使含冒号也按本地处理。
2. 远端路径必须是绝对路径，且只允许字母、数字和._/-这些字符。
3. 目标文件已存在会被覆盖——v0 版本是明确的覆盖语义，所以强烈建议先加--dry-run预览一次。

跨主机操作前：先注册主机

远端的"主机ID"来自主机注册表（hosts.yaml），而不是任意字符串。通过 packages/cli/src/commands/host.ts 提供的rig host add / list / doctor管理条目，只有ssh传输类型的主机才能参与文件拷贝。

五层安全防护墙：拒绝发生在任何进程启动之前

安全核心在 packages/cli/src/lib/file-transfer.ts，代码注释里自称"SECURITY CELL"。它不是单点检查，而是五道互相独立的关卡，任何一道失败都会"响亮地报错、绝不静默降级"：

1. 语法层（fail-closed）：路径是不是远端，只看有没有显式的<hostId>:前缀；前缀长得像主机 ID 但注册表里查不到，直接失败，绝不悄悄退回本地路径。
2. 归一化层：本地路径先展开~再解析；远端路径在任何归一化之前就检查..段——因为绝对路径里的..会被 normalize 悄悄折叠，事后检查是死代码。
3. 远端字符集墙：只放行 POSIX shell 惰性字符，空格、$、~、通配符统统拒绝。远端 shell 拿到的路径"没有东西可以解释"，从构造上杜绝命令注入。
4. --操作数固定位：构造 rsync 参数时，--永远插在两个路径之前，形如选项的路径不可能被误读成开关。
5. 本地无 shell：本地直接以参数数组 spawn rsync，全程不经过 shell 解释。

默认拒绝的敏感目录清单

无论源还是目标，凡是落进以下目录的请求一律拒绝（DENIED_SEGMENTS）：

• ~/.openrig：OpenRig 自身的运行状态，误传会破坏崩溃恢复
• ~/.ssh、~/.codex、~/.claude：凭据与 Agent 主目录，属于"凭据类"
• 远端侧采取保守从严策略：路径中任何位置出现.ssh等段名都拒绝，误报可以申诉，漏报就是数据泄露

这套契约不是口头承诺，而是由属性测试持续断言的——删除类标志位不可达、--位置固定、所有拒绝都先于 spawn，见 packages/cli/test/file-transfer.test.ts。

安全跨主机文件操作检查清单

给新手一份可以直接照着做的清单 ✅：

• 先rig host doctor <主机ID>确认远端可达、认证正常
• 首次传输必加--dry-run，它会打印精确的计划（源、目标、主机、文件数/字节数）但什么都不移动
• 需要脚本化处理时用--json，输出包含完整 rsync 参数，方便 Agent 审计
• 需要"远端→远端"中转？v0 不支持直接中转，请老老实实"先拉后推"，两次显式传输
• 失败时看failedStep分类：rsync-missing（没装 rsync）、permission-gate（SSH 认证问题）、ssh-unreachable（网络不通），报错自带修复提示

小结

OpenRig 把 rig file 文件传输做成了"显式、封闭、可审计"的系统：一个copy动词、一份默认拒绝清单、五层纵深检查，外加--dry-run这道护栏。对新手来说，记住三件事就够了——远端用主机ID:绝对路径表达、传输前先看 dry-run 预览、敏感目录碰不到。这样你的跨主机 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