企业官网建设流程全解析

orx隐藏的4条命令：plan-gate、mcp-gate、remote-host、publish-branch揭秘

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch

OpenResearch（orx）是一款本地优先的研究智能体工作区，能把 Claude Code、Codex、OpenCode、Cursor 等编码智能体升级为可查文献、做假设、跑实验、产论文的研究智能体。除了orx up、orx runs这些常用命令，它的 CLI 里还藏着 4 条被标记为hide = true的隐藏命令：plan-gate、mcp-gate、remote-host、publish-branch。它们不面向手动调用，却是 OpenResearch 在计划模式审批、无头权限桥接、远程 GPU 托管和 GitHub 静默同步四个关键场景下的"幕后功臣"。本文带你逐一揭秘。

为什么这4条命令藏在--help背后？

在命令定义文件 src/main.rs 中，这 4 条命令都带有#[command(hide = true)]标记，源码注释也直白地写着 "Not a user command"（不是用户命令）。它们的定位是内部协作组件：

• plan-gate：计划模式的 PreToolUse 钩子执行体，由 Claude Code 自动拉起；
• mcp-gate：计划模式的权限桥，由 Claude 以 stdio MCP 子进程身份启动；
• remote-host：持久 SSH 远程主机的控制面，由orx up --remote链路调用；
• publish-branch：GitHub 分支发布的后台 worker，由实验创建/算力提交动作派生。

换句话说：普通用户永远不需要敲出它们的名字，但 OpenResearch 的"计划→执行"安全闭环全靠它们支撑。

1️⃣ plan-gate：计划模式的"只读安检门"

智能体在计划模式（plan mode）下最擅长"先观察、再规划"——但计划模式默认会把所有 Bash 调用当成危险写操作拦截，连orx runs | head -50这种纯查看命令都跑不了。plan-gate就是为此而生的钩子：它从标准输入读取 Claude Code 传来的钩子 JSON，识别出只读命令后打印一条allow决策放行，其余情况保持沉默、交还给计划模式默认拦截，并且永远以退出码 0 结束——钩子出任何错都不能阻塞智能体的一轮对话（见 src/commands/plan_gate.rs）。

它的分类逻辑是严格的白名单制（src/local/harness/plan_gate.rs）：

• ✅ 放行：orx runs、orx logs、orx paper等全只读动词，orx exp status、orx project view等只读子命令，git log、git ls-tree等只读 git 动词，以及head、grep、tail这类纯流消费者，支持;、&&串联和管道组合；
• 🚫 拦截：orx exp run、orx instance create、git push等一切写操作，以及重定向>、反引号、$()、后台&等元字符——只读前缀也绝无可能"夹带"写操作；
• 🔔 特殊处理：ExitPlanMode（退出计划模式）一律返回ask，防止无头模式下智能体"自批自跑"直接开始改代码——退出计划必须由你本人在审批卡片上点确认。

一句话总结：看不看的随便看，动手的必须批。

2️⃣ mcp-gate：把无头审批"搬"回桌面卡片

计划模式下，plan-gate放行了只读操作，但"退出计划、执行实验"这类关键动作需要人来批准。问题是：无头（headless）的 Claude 进程根本没法弹交互提示框。mcp-gate解决的就是这个断点。

它的角色是一个手写的 stdio MCP 服务器：Claude Code 通过--mcp-config拉起它，并在每次权限决策时调用名为approve的工具。mcp-gate拿到请求后，立刻转发到本机正在运行的orx up的127.0.0.1内部接口（见 src/commands/mcp_gate.rs），而桌面端会弹出一张审批卡片并阻塞等待，直到你在界面上点下"允许"或"拒绝"，决策再原路传回 Claude。

这套设计有两个值得称道的细节：

1. 长轮询阻塞 = 桌面式体验：那个被"按住不放"的调用，正是无头计划模式获得桌面版中途审批体验的关键；
2. 失败姿态是"宁拒不误放"：任何传输或orx up侧错误都会返回deny并附带原因；环境变量契约缺失则直接非零退出，计划模式优雅降级为默认拦截。连接本身限时 3 秒，但等待你思考的时长不设限。

3️⃣ remote-host：持久远程主机的"遥控器"

用orx up --remote user@host时，OpenResearch 会把工作区部署到远程 GPU 机器上，你在笔记本浏览器里操作。remote-host就是管理这台持久远程主机的控制面，提供 4 个子命令（src/commands/remote_host.rs）：

安全性设计相当严谨：控制通道走Unix 域套接字，文件权限0o600，且用peer_cred校验连接方必须是同一 uid——其他本机用户一律碰不到；令牌校验用常量时间比较防时序攻击；连 Windows 因无 Unix 套接字会直接拒绝而非"裸奔启动"（src/commands/remote_host.rs）。

4️⃣ publish-branch：静默同步实验分支到 GitHub

OpenResearch 的每个实验变体都跑在独立的orx/前缀 git 分支上。当你为项目开启 GitHub 同步后，实验创建或算力提交（orx exp run）一成功，系统就会派生一个分离后台进程运行publish-branch，把实验分支推送到远端——主流程完全不等待推送结果，推送失败也只是打印一条警告，绝不影响本地实验的创建和运行（调用点见 src/compute.rs）。

它的寻远逻辑也很讲究（src/local/git.rs）：按github→origin→upstream的顺序查找与owner/repo匹配的远端，找到才推，找不到就明确报错提示"先为该项目启用 GitHub 同步"。实际推送动作在 src/local/git.rs 的push_branch中完成。这也呼应了 OpenResearch 的核心理念：发布仓库不是必需的，同步只是"可选项的锦上添花"。

新手需要记住的3件事

1. 不用学、直接受益：这 4 条命令由orx up、计划模式、远程模式、GitHub 同步在背后自动编排，你在界面上点"批准计划"、连远程机器、开 GitHub 同步时，它们都在替你干活；
2. 安全模型是"默认拦截、显式放行"：plan-gate 白名单制、mcp-gate 失败即 deny、remote-host 同 uid 校验，处处体现"宁紧勿松"；
3. 想动手研究源码：从 src/main.rs 的命令定义出发，顺着src/commands/下的 plan_gate.rs、mcp_gate.rs、remote_host.rs 三个文件读，一两个小时就能摸清 OpenResearch 的权限与远程架构。

下次当你的研究智能体在计划模式里"看了一圈证据、弹出一张审批卡片、然后安静地把实验分支同步到远端"——现在你知道，背后正是这 4 条隐藏命令在协作。

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch