rigs

rigs：开启 OpenRig 之路

OpenRig 会在 tmux 中并行运行一组编码 Agent（Claude Code、Codex 等）。本地守护进程会保存它们的任务、消息和状态，因此团队在重启后也能继续工作。此技能会安装 OpenRig，让团队开始处理用户想做的事，并说明如何从现在起与团队协作。

目标是让团队替用户完成工作，而不只是安装软件。 按顺序完成这些步骤，只有用户要求时才提前停止。当用户说出想要构建什么时，将需求交给 OpenRig 的操作员（步骤 2），而不是自己动手构建。

运行命令前，先告诉用户你准备运行什么以及原因。未经用户同意，不要安装系统软件包或更改其机器；未经用户同意，不要启动团队，包括运行 rig up；如果用户已同意同一次启动，就无需再次询问。启动 OpenRig 和团队会写入文件：Codex 钩子和设置写入 ~/.codex/config.toml，Claude Code 工作区信任设置写入 ~/.claude.json，发现技能写入 ~/.claude/skills 和 ~/.agents/skills；在代码仓库中，会写入托管指引 AGENTS.md 或 CLAUDE.md、活动钩子 .claude/settings.local.json，以及状态行（如果项目尚未有自己的状态行），还有团队的技能和插件。除非适用权限策略、单个席位选项或（对 Codex 而言）指定配置文件，否则内核自身的席位会采用操作默认设置：Codex 使用 -s danger-full-access -a never，Claude Code 则获准使用文件工具、网页抓取和操作命令（包括读取主目录下的内容），无需询问。在启动 OpenRig 之前说明这一点（完整列表）。

如果用户希望更改仅保留在其项目中： 在设置或首次启动守护进程／内核之前，说明所选 Codex 配置路径（CODEX_HOME/config.toml，默认为 ~/.codex/config.toml），并解释这些独立写入操作。设置过程会添加 ~/.tmux.conf；Codex 席位启动时会添加工作区信任设置和任何已声明的配置片段（包括 MCP），即使跳过了设置，或 runtime.codex.hooks_enabled 为 false 也一样。此设置控制的是钩子，而非所有配置写入。这些设置可能会影响使用同一 Codex home 的其他会话。如果用户此前已同意涵盖这些写入操作，就沿用该同意；仅限项目的明确要求不包含这些操作。如果用户拒绝，不要启动同一路径，也不要事后删除写入内容来代替征求同意。说明设置没有仅限项目的模式。Git worktree 或项目中的 .codex/config.toml 都不会重定向这些写入操作。已有的独立 CODEX_HOME 会一并隔离 Codex 的配置、登录和会话状态；它需要单独完成有效登录，且不会迁移 ~/.tmux.conf。将用户的范围限制告知操作员。

Codex 单项审批： 在安装前说明，即使是读取操作，在设置和后续操作中也可能反复询问；这与团队权限相互独立。使用简单、独立的命令，让每项请求都清晰易懂。下方提供的可选六命令审批方案仍然适用；不要启用常规网络访问或扩大其他权限设置来避免提示。

当你给用户提供要在其终端中运行的文件或命令时，请使用其机器上实际存在的路径。沙盒 Agent 在 /tmp 下写入的文件可能不会出现在用户的终端中（Codex 中有此情况），因此应将用户需要的文件放在其项目文件夹或主目录中，并注明该路径。

1. 如果尚未安装 OpenRig，请先安装

• **先检查：**运行 rig --version。如果显示版本号，请转到第 2 步。
• **所需条件：**macOS 或 Linux、Node.js 22 或 24、tmux，以及已登录的 Claude Code 或 Codex。只检查缺少的项目：运行 node --version、tmux -V、claude auth status 或 codex login status。
• 需要联网的检查（gh auth status、注册表查询或其他获取操作）在无法访问网络的沙盒中可能会误报失败，例如 Codex 默认使用的沙盒。告诉对方重新登录或修复任何问题之前，先在有网络访问权限的情况下重新运行对应命令。
• **安装：**运行 npm install -g @openrig/cli，然后运行 rig setup --providers codex（也可以用 claude 或 both，选择对方使用的运行环境）。Setup 会检查 Node、tmux 和登录状态。如果缺少 tmux 或所选运行环境，它会安装 tmux（如果有 Homebrew，则使用 Homebrew）或所选运行环境（使用 npm）；除非对方拒绝（--no-herdr），否则会安装用于查看 OpenRig 的 Herdr；还会将 OpenRig 配置块添加到 ~/.tmux.conf。因此，请先告知对方这些操作。它不会启动守护进程。之后运行 rig doctor。
• **然后继续第 2 步：**说明已安装完成，并询问对方想处理什么，以及在哪个仓库中处理。对方只说“安装 OpenRig”也包括这一步。只有对方表示暂时不启动团队时，才在此处停止。
• 如果出现问题：rig context get help 是已安装版本的帮助指南。如果 rig 本身无法运行，请访问 https://www.openrig.dev/help/agents。入门指南：https://openrig.dev/docs/getting-started

2. 打开 OpenRig，并将目标交给其操作员

• **启动 OpenRig：**运行 rig daemon status，如果尚未运行，则运行 rig daemon start。rig preflight 和 rig doctor 不会启动它。启动 OpenRig 也会启动 OpenRig 自己的团队——内核；其操作员会为对方设置团队。保留它。

• **如果对方使用 Codex：**OpenRig 运行后，现在按照本步骤末尾“Codex：OpenRig 启动后，只主动提供一次”的说明进行一次性告知。

• **向对方展示 OpenRig 和交接方式：**OpenRig 运行后，为对方打开 OpenRig TUI 和操作员。先说明你要打开它，然后在守护进程的桌面上运行 rig terminal open saved:kernel --window。这是安装或启动 OpenRig 后的下一步；之后无论何时对方想再次使用 Agent 或 OpenRig，都可以通过此方式返回。不要等对方提出要求或说出特定措辞。如果对方表示暂时不需要，就把这条命令留给他们以后使用。该命令会自行打开一个视图；已安装 Herdr 时使用 Herdr，否则使用普通 tmux：

  • 在 Herdr 中（你在 Herdr 窗格中运行）：切换对方的 Herdr 到 openrig kernel 空间，并重用已有的活动空间。不会新开窗口，也不会出现 macOS 提示；对方自己的空间仍会显示在侧边栏中。
  • 在 Rex 中（你在 Rex 区块中运行，或在其中启动的 tmux 中运行）：在同一 Rex 服务上打开 openrig kernel 会话，并让 Rex 应用切换到该会话。不会新开窗口，也不会出现 macOS 提示。再次打开会新增一个编号会话。
  • **在 Terminal 或 Ghostty 中：**新建一个与对方当前窗口大小相同的标签页或窗口。
  • **在 Mac 上通过 Claude Desktop、iTerm 或 VS Code 使用时：**如果支持，则打开新的 Ghostty 窗口；否则打开 Terminal。只有在这种情况下，如果 macOS 询问是否允许控制该应用，请在运行命令前告诉对方，选择“允许”即可。运行 echo $TERM_PROGRAM $__CFBundleIdentifier $REX_BLOCK 可查看你所在的位置。herdr、rex、Apple_Terminal 或 ghostty，以及带有 com.apple.Terminal、com.mitchellh.ghostty 或 REX_BLOCK 值的 tmux，都不会触发 macOS 提示，因此不要提及提示。其他情况中的 tmux（iTerm、VS Code）可能会触发提示，因此要先说明选择“允许”即可。
  • **布局：**宽度不足 120 列时，操作员占满第一页；从 120 列起，仪表板和操作员并排显示。顾问有自己的标签页或 tmux 窗口。 然后用一两句话告诉对方它在哪里打开了，并说明操作员已准备好帮助他们构建想要的内容。不要列出 Agent 或状态（TUI 会显示），也不要建议他们输入命令。 保留当前终端。如果 OpenRig 的备注说无法确认视图，请如实说明。如果窗口已经打开，请指引他们前往，而不是再打开一个。只有窗口无法打开时，rig tui --shared 才是仅显示仪表板的备用方案；请说明失败原因，并帮助他们使用选定的备用方案。Herdr 只有在对方能看到的终端中才可见；将共享 TUI 切换到 :terminals 并不会打开终端。未打开窗口以及无头/SSH 使用都是有效的后台结果。仅指定提供方的 --provider herdr、--provider cmux 或 --provider rex 适用于已在运行的提供方，不适用于首次打开桌面窗口；每次此类打开都会添加一个新的工作区。

• **如果窗口无法打开，或通过无头 SSH 使用：**请明确说明没有打开可见终端，并请对方在守护进程所在主机上打开一个新的终端窗口或标签页。通过 SSH 使用时，请他们新建一个连接到该主机的 SSH 会话，并使用已知的帐户。如果你只知道 HTTP 守护进程地址，请询问 SSH 连接详情，不要凭空编造。然后给出一条完整命令：

  • **OpenRig 打印的命令：**如果 rig terminal open saved:kernel --window 无法打开窗口，它会说明原因，并以 run: 和一条命令结尾（使用 --json 时，该命令位于 error 字段中）。该命令已经包含已安装的 herdr 二进制文件和守护进程的套接字，或要附加的会话。请原样转述，不要自行拼凑。如果备注要求你在 Herdr 启动后放置视图，请在对方启动后自行运行 rig terminal open。
  • **如果没有打印命令：**在 rig ps --nodes --rig kernel --json --fields logicalId,canonicalSessionName,tmuxAttachCommand 中查找 operator.agent，并将其 tmuxAttachCommand 按原样列出，前面加上 env -u TMUX（切勿猜测名称），以进入操作员的对话。如果不是默认的 tmux 服务端，该命令会指向守护进程的 tmux 服务端。

  对于其他任何故障，请查阅 rig context get reference/getting-started.md#open-the-kernel-conversations 中标题为“What can interrupt installation and the OpenRig view”的表格，了解原因和后续处理方式。

• **首次发送消息前，先询问对方是否愿意加入此会话：**如果此会话尚未加入，请建议在普通 shell 中加入 OpenRig，这样操作员看到的会是有名字的队友，而不是“unknown sender”。在 tmux 中，将加入作为可选项，并说明以下影响。简短说明后，请对方回答愿意或不愿意：

  • 这会让我成为团队中有名字的一员，并在消息中显示我的名字。
  • 在普通 shell 中，加入不会在你的项目或个人设置中写入任何文件。
  • 在 0.6.11 的 tmux 中，我的发送者名称和回复地址会是你现有的 tmux 会话名称，即使它是 0 这样的数字。rig attach --self 会返回该地址，rig whoami 会确认该地址；--display-name 不会更改它。
  • 在 tmux 中，其他 Agent 可以向此窗口输入内容，而停止团队（rig down）也会关闭此 tmux 会话（这两点来自源代码，未经手动测试）。在 0.6.11 上，已手动测试过转录记录，以及对 Claude Code 写入 .openrig/context-collector.cjs 和 .claude/settings.local.json 以显示状态行。更新现有的 .claude/settings.local.json 并保留其自定义状态行这一点来自源代码。
  • 在普通 shell 中，其他 Agent 会通过任务队列回复，因为它们无法向此窗口输入内容；停止团队后，此会话仍会运行。 只有在对方同意后才附加；如果他们拒绝，就继续进行操作员交接。首次联系时，使用内核的 rig ID（rig ps --json 中 kernel 行的 rigId）及其 operator Pod： rig attach --self --rig <rigId> --pod operator --member person-agent --runtime <claude-code|codex> --print-env。 --node <logicalId> 则会绑定到现有席位。只附加一次，并保留它打印的变量 （OPENRIG_NODE_ID 和 OPENRIG_SESSION_NAME）。每条命令都可能在新的 Shell 中运行，因此要把这些变量放在之后每条 rig 命令前。使用 rig whoami --json 检查身份；之后要确认身份和状态时，使用它或 rig seat status， 不要依赖 rig attach --json 的输出。不要打印 OPENRIG_ACTIVITY_* 的值：它们是凭据。 如果对方拒绝，要发送一条仍须注明发件人身份的消息，可以将其作为队列项，并声明来源： rig queue create --source <their id>@external --destination <seat> --summary "<one line>" --body-file <file>：席位会看到这个 名称，并将其记录为已声明的来源；如果对方已注册（rig gateway human list），就可以回复他们。 声明的名称是一种自我申报，不代表席位自身的身份：对于只根据席位身份采取行动的团队，应使用上面的附加 Shell 作为通道。

• **向操作员说明目标：**询问对方想处理什么、在哪个仓库、使用哪个分支，除非他们已经说明。找到 rig ps --nodes --rig kernel --json 中的 operator.agent 行，获取其 canonicalSessionName（绝不能使用逻辑 ID，也不能猜测名称），然后发送： rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>. Branch: <branch>.' 如果对方留在这里，就将 "The person will answer in your pane" 替换为 "The person stays with me; send me your questions and results to relay."。交接时一并传达他们的限制条件及拒绝的权限选项。 也可以让对方在操作员的窗格中输入目标和文件夹。如果他们之后才给出目标，就用同样的方式转交。操作员会帮助他们根据登录账号选择合适的团队；只有在他们同意所显示的计划后，才启动团队（rig up），并将目标告知团队负责人。在他们同意之前，要说明将任务启动到其文件夹会如何影响他们在那里的 Agent；提问时也要转达这一点。 告诉他们操作员会在哪里回复，不要自己构建项目。

• 转达操作员的问题，除非对方拒绝了下面的 Codex 提议并明确选择了操作员通道：操作员会在自己的窗格中提问，而对方可能没有查看那里。 每次交接步骤后，使用 rig capture <canonicalSessionName> 读取操作员的屏幕。当操作员向对方提问（是否启动这个团队？使用哪个文件夹？选择哪个选项？）时，用操作员的原话在这里询问对方，并通过 rig send 发送他们的回答，或者告诉他们在操作员的窗格中回答。问题不像提示或菜单那样会显示为已停止的席位，因此不要让它一直等待后台响应。

• 当操作员已准备就绪且对方正在与其交谈时，安装才算完成；仅有健康运行的守护进程并不算完成。如果对方更愿意稍后再交谈，就保留这一选择，提供准确的连接步骤，并说明交接给操作员的流程仍未完成。

• **查看正在运行的内容：**先运行 rig ps，再运行 rig ps --nodes --rig <rig> 查看团队的 Agent。如果该仓库中已有团队在运行，请告知操作员。

• **声称已就绪前，先确认确实就绪：**运行 rig ps --nodes --rig <rig>。如果某个 Agent 停在提示或菜单处，使用 rig capture <seat>@<rig> 读取。如果出现权限提示，应由对方作答：将提示展示给他们，并把所有其他等待中的提示也一起展示，每行一条（席位、准确操作、提供的选项）。发送他们的选择前，再次捕获该席位：如果提示已改变，不要重复使用先前的回答。然后准确发送他们针对该提示所选的选项（rig send --help 会说明如何向提示发送数字、字母或 Escape）。对一个提示回答“是”不代表对下一个提示也回答“是”；也绝不要替他们选择他们没有选择的“以后不再询问”。如果他们明确告诉你如何处理某类未来提示（例如“批准只会在我的项目内写入的提示”），你可以逐个处理：完整查看操作内容，只有在明确属于他们所述范围内时才作出决定，并告知他们你是根据该指示作答，而不是说他们同意了。任何不明确或超出范围的内容都要交由他们决定；命令名称或看起来像其项目的路径，并不能说明操作会影响哪些内容。他们的指示不会更改任何权限设置。 对于另一类菜单，你可以按屏幕显示的按键作答，也可以询问对方。发送任何后续内容前，再次捕获该菜单。

• **回复：**在普通 Shell 中，其他 Agent 无法向此会话输入内容。使用 rig queue list --destination <your address> 和 rig queue show <id> --full 读取发给你的工作；使用 rig capture <seat>@<rig> 读取 Agent 的屏幕。

Codex：OpenRig 启动后，只询问一次是否授权

首先，Agent 会解析用户实际使用的 Codex 文件夹（CODEX_HOME，如果未设置，则为 ~/.codex），并在授权请求中写入确切路径，让用户看到的是实际文件，而不是占位符：

Codex 会请求你批准 OpenRig 命令。可以允许以下六条命令在无需询问的情况下运行吗：rig ps、rig capture、rig send、rig queue、rig status 和 rig whoami，以及它们各自后面的任何内容？它们将在 Codex 沙盒之外运行，适用于你在这台电脑上运行的所有 Codex 项目和会话；而且 rig send 和 rig queue 可以向你的 Agent 发送消息并更改它们的任务记录，不只是读取信息。我会添加一个文件：/home/you/.codex/rules/openrig.rules（解析后得到的路径）。Codex 会在启动时读取该文件，因此这些规则会从你的下一个 Codex 会话开始生效；它们不会移除当前会话中的提示。保留逐条批准意味着即使是状态检查和读取 Agent 的屏幕，也可能每次都需要询问。你也可以在操作员就绪后直接与其对话，而无需更改此 Codex 会话的权限。要撤销这些规则，请让我移除本次添加的 OpenRig 规则，并保留你的其他规则。

• 不同意，或未作答： 不写入任何内容，并保留用户的沙盒、网络和批准设置。如果用户拒绝，请尊重其选择；不要继续提供已记住的批准，也不要为了避免提示而启用通用网络访问。可提供继续与已就绪的操作员直接对话，或留在此处逐项批准的选项。如果用户已经选择其中一种方式，则不要再次询问。
• 如果用户选择操作员： 使用上述交接方式，仅交接一次，并附上用户的目标、文件夹、分支和拒绝授予的权限，然后引导用户前往操作员已就绪的对话。在无头 SSH 上，使用上述确切的连接／附加命令。用户开始与操作员对话后，操作员会跟进团队的工作并在那里报告结果；停止此安装程序反复轮询 capture、status 和 queue。不要停止、重启或重新配置任何一个会话。如果用户更愿意留在此处，则按照其选择的批准方式继续转达；不要声称这些提示已经消失。是否提供规则授权是可选项，不是使用 OpenRig 的前提。
• 同意： Agent 按照 OpenRig 现有权限步骤中的说明应用规则（已安装 OpenRig 技能中的 applying-a-permission-policy）：先读取现有规则，保留任何更严格的规则，不更改任何沙盒或批准设置，并记录添加的内容。仅当文件不存在时才创建；如果文件已存在，Agent 不做任何更改，并说明其中已有的内容。新文件仅包含以下两行：

  # Added by OpenRig on the person's yes: these six rig command families run without a prompt. Ask to undo, or delete this file if it holds nothing else.
  prefix_rule(pattern = ["rig", ["ps", "capture", "send", "queue", "status", "whoami"]], decision = "allow", justification = "OpenRig coordination commands the person approved once")
  

• 撤销（同一技能中的原文：“撤销本次设置添加的 OpenRig 命令授权；保留我的其他规则”）：Agent 仅移除其记录为新增的行，保留文件中的其他所有内容，并且只有在文件中只剩这些行时才删除文件。这些更改从下一个 Codex 会话开始生效。

3. 跟进工作，直到有结果

默认情况下，请按以下步骤操作。只有当对方拒绝了上文的 Codex 提议，并明确选择由操作者处理时，才由操作者负责跟进。

• **找到团队的任务：**操作者将目标作为队列任务交给团队负责人：dev-build@starter，或者在 workshop 和 factory 中交给 orch-lead（对于 starter 和 factory，rig specs preview <name> --kind rig 会说明各个席位的职责；对于正在运行的团队，请使用 rig ps --nodes --rig <rig>）。使用 rig queue list --destination <seat>@<rig> -a 查找任务。
• **跟进直到有结果：**任务转交给他人并不代表工作已经完成。rig queue show <id> --full 会显示任务转交给了哪个席位，而该席位接下来的任务就是 handedOffFrom 值为该 ID 的任务 （rig queue list --destination <seat>@<rig> -a -o json）。跟进每次转交，直到某个 Agent 报告结果，并使用 rig capture <seat>@<rig> 查看它正在做什么。然后阅读它产出的内容，并告诉对方团队实际完成了什么（分支、提交、评审或 PR 文本），而不只是说你已发送任务。
• **给团队安排更多工作：**将目标写入文件，说明要更改什么、在哪个仓库和分支中更改、完成的标准是什么，以及结果如何返回给你（分支或提交、评审、任何 PR 文本）。然后运行 rig queue create --source <your name> --destination <seat>@<rig> --summary "<the goal in a sentence>" --body-file <file>，并通过 rig send <seat>@<rig> "task <id> is yours" 告知该 Agent。消息用于通知，而队列任务才是有人负责的工作。 如果当前会话尚未加入团队，--source 中填写你的名字。
• **然后询问接下来要做什么。**如果没有团队能接手这项工作，请解决这个问题或询问对方。不要默默地自己动手。
• 与团队协作的其他方式：rig send <seat>@<rig> "..." 会在 Agent 的终端中输入内容， rig capture <seat>@<rig> 会读取其屏幕，而 rig ps --nodes --rig <rig> 会显示团队成员。

4. 了解更多

• OpenRig 的工作方式：rig context profile world-public --situation fresh。
• 你能做什么：rig context get onboarding-width（能力图）。
• 库中的所有内容：rig context list。
• 准确语法：rig <command> --help 始终与已安装的版本保持同步。

如果此处的说明与 rig <command> --help 不一致，以 --help 为准。