RepoRelay

RepoRelay 的功能

RepoRelay 是一个本地的一方 MCP 桥，它赋予 ChatGPT 对计算机上恰好一个已批准仓库的受限访问权限——仅此而已。

ChatGPT 通过 RepoRelay 审查你的代码，并可以通过固定的交接文件为单独的本地编码代理（如 Codex 或 Claude）留下结构化任务。RepoRelay 是 ChatGPT 与你的机器之间的安全边界。

ChatGPT reviews/plans
        ↓
RepoRelay
        ↓
Repository reads/searches
+
fixed .ai-handoff writers
        ↓
Codex / another local coding agent implements

Related MCP server: codex-web-bridge

安全模型的工作原理

MCP（模型上下文协议）是让 ChatGPT 调用工具的标准。ChatGPT 是 MCP 客户端。RepoRelay 是本地 MCP 服务器和安全边界：它决定 ChatGPT 可以访问什么，并一次只暴露一个已批准的仓库。tunnel-client 只是将 ChatGPT 流量传输到你的计算机的安全网络管道。

ChatGPT 通过 RepoRelay 可以做什么（正常的 7 工具设置）：

✓ inspect files          open_workspace, list_files, read_file
✓ search the repository  search_files
✓ write to three predetermined handoff targets
                         write_next_task, write_review, update_handoff_state

ChatGPT 不能做什么：

✗ run shell commands
✗ run PowerShell
✗ run Git
✗ launch processes
✗ arbitrarily edit source files
✗ delete files
✗ choose arbitrary write targets
✗ access outside the approved repository

这是 RepoRelay 最强大的差异化特性之一：ChatGPT 可以读取你的代码并制定计划，但它没有执行能力，并且只能写入你控制的几个固定交接文件。

安装前准备

你需要：

• Node.js >=22.19 且 <27（包含 npm）。使用 node --version 检查。

• 一个现有的本地项目或仓库，你想让 ChatGPT 审查。它必须是计算机上的真实文件夹——不能是驱动器根目录或整个用户文件夹。

• OpenAI 安全 MCP 隧道访问权限。 RepoRelay 通过 OpenAI 的安全 MCP 隧道到达 ChatGPT。有关可用性、权限和计划详情，请参阅当前的 OpenAI 安全 MCP 隧道指南。

• 在目标 ChatGPT 工作区中创建/使用自定义 MCP 应用的权限（ChatGPT 开发者模式）。

你不需要下载其他任何东西。RepoRelay 会在 reporelay tunnel setup 期间自动安装官方的 OpenAI tunnel-client。

暂时不用担心交接协议。快速入门会为你设置好工作的交接文件，并在过程中进行解释。

快速设置

Windows 路径。 始终用引号括起完整路径并保留反斜杠：

reporelay quickstart "C:\Users\you\Projects\my-app"

C:\Users\you\Projects\my-app 是正确的。C:Users\you\Projects\my-app 是错误的——反斜杠很重要。

1. 安装 RepoRelay

npm install -g reporelay-mcp@latest

检查安装：

reporelay --version

如果 reporelay 未被识别，请参阅故障排除。

2. 在一个仓库上启动 RepoRelay

reporelay quickstart "C:\Projects\my-app"

将路径替换为你想要暴露的仓库。保持此 PowerShell 窗口打开。

你应该看到：

Ready.
Local MCP: http://127.0.0.1:7676/mcp

正常的快速入门会启用 7 工具交接界面（4 个检查工具 + 3 个固定交接写入器）。RepoRelay 现在会创建一个小的 .ai-handoff 工作区和一个 AGENTS.md 笔记，以便 ChatGPT 可以为单独的本地编码代理留下结构化任务和审查：

.ai-handoff/NEXT_TASK.md
.ai-handoff/REVIEW.md
.ai-handoff/RESULT.md
.ai-handoff/STATE.json
AGENTS.md

为什么 RepoRelay 要创建这些？ ChatGPT 仍然不能运行命令、使用 Git 或任意编辑你的仓库。这些文件只是一个地方，ChatGPT 可以在那里留下任务，而单独的本地编码代理（在你的机器上运行，经你许可）可以留下其结果。更多内容请参见下面的 ChatGPT ↔ 编码代理交接。

要稍后停止 RepoRelay，请在此窗口中按 Ctrl+C。没有 reporelay quickstart --stop 命令。

3. 审计它

快速入门后立即验证 RepoRelay 的实际安全边界：

reporelay audit "C:\Projects\my-app"

你应该看到：

RESULT: PASS

审计会启动自己的临时回环监听器，并执行真实的经过身份验证的 MCP 界面、包含检查和交接限制。它不会修改你的仓库。这会在连接 ChatGPT 之前验证 RepoRelay。

4. 运行 RepoRelay 隧道设置

在第二个 PowerShell 窗口中，运行：

reporelay tunnel setup

这会启动 RepoRelay 设置向导。它会为你完成所有操作：

✓ installs a RepoRelay-supported OpenAI tunnel-client
✓ verifies it (pinned version + official SHA-256)
✓ opens OpenAI tunnel setup
✓ asks for your tunnel ID
✓ opens OpenAI runtime-key setup
✓ securely stores the pasted key
✓ creates the tunnel profile
✓ tests the complete connection

你只需提供两样东西，都在 OpenAI 平台中：

1. 你的安全 MCP 隧道 ID——向导会在浏览器中打开 https://platform.openai.com/settings/organization/tunnels。创建或选择一个隧道，将其关联到你的 ChatGPT 工作区，然后将 tunnel_id 粘贴回终端。

2. 一个运行时 API 密钥——向导会打开 https://platform.openai.com/settings/organization/api-keys。为你与隧道一起使用的项目创建一个密钥，并将其粘贴到终端中。输入是隐藏的：粘贴时不会显示任何内容。此密钥用于向 OpenAI 验证 tunnel-client；它不是 RepoRelay 桥密钥。

创建或编辑隧道需要隧道读取 + 管理权限；运行 tunnel-client 或选择隧道需要隧道读取 + 使用权限。这些是由你的组织所有者或 RBAC 管理员授予的组织级权限。请按照当前的 OpenAI 安全 MCP 隧道指南 获取确切的 UI 和权限详情。

当向导完成时，你应该看到：

Testing connection...
✓ OpenAI runtime credential
✓ RepoRelay reachable
✓ Bridge authentication

Setup complete.

Next:
  reporelay tunnel run

这些检查是真实的：设置会针对 OpenAI 控制平面验证运行时 API 密钥（与 tunnel-client 启动时执行的相同只读隧道查找），并针对实际运行的 RepoRelay 验证桥密钥。错误的、过期的或粘贴错误的密钥会在这里被捕获并显示清晰的消息——而不是在 tunnel run 启动之后。

如果你的 RepoRelay 运行在自定义端口上（例如 --port 7677），快速入门已经记录了实时端点，设置会自动跟随——无需额外标志。

有用的选项：

• reporelay tunnel setup --no-open——不启动浏览器（无头、SSH 或 CI）；URL 仍会打印。

• reporelay tunnel setup --replace-tunnel——提示输入新的隧道 ID。

• reporelay tunnel setup --replace-runtime-key——提示输入新的运行时 API 密钥。

• reporelay tunnel setup --tunnel-client-path "C:\custom\tunnel-client.exe"——高级覆盖用于不常见环境；RepoRelay 不会验证或管理自定义二进制文件。

重新运行 reporelay tunnel setup 会重用你现有的已验证客户端、隧道 ID 和存储的密钥，并重新测试连接，无需再次询问任何内容。

5. 运行隧道

reporelay tunnel run

将此窗口与 RepoRelay 快速入门窗口一起保持打开。完成后按 Ctrl+C 停止。

如果连接停止工作，reporelay tunnel doctor 仍然可以作为独立的故障排除命令使用（一切正常时显示 Ready.；添加 --verbose 可查看经过编辑的诊断信息）。

6. 创建 ChatGPT 应用

在 ChatGPT 中，使用当前的 OpenAI 流程（请参阅 ChatGPT 开发者模式和 MCP 应用指南）：

ChatGPT
→ Apps / developer features
→ create custom MCP app
→ connection: Tunnel
→ choose RepoRelay's tunnel
→ authentication: No authentication
→ Scan Tools
→ verify 7 tools
→ create/use the app
→ start a new chat

按照以下顺序操作：

1. 创建自定义 MCP 应用。

2. 选择隧道连接。

3. 选择 RepoRelay/OpenAI 安全 MCP 隧道。

4. 当 ChatGPT 要求身份验证时，选择无身份验证。

5. 保存或创建应用。

6. 运行扫描工具。

7. 验证预期的 RepoRelay 工具出现。

8. 开始新的聊天并选择 RepoRelay 应用。

身份验证：无身份验证。 RepoRelay 已经通过隧道使用的受保护 X-RepoRelay-Bridge-Secret 对本地桥进行了身份验证。不要配置 OAuth 或其他 ChatGPT 端的身份验证方法。

切勿将 127.0.0.1、localhost、RepoRelay 桥密钥或 OpenAI 运行时 API 密钥粘贴到 ChatGPT 中。隧道连接处理所有网络通信。

7. 扫描并验证 7 个 RepoRelay 工具

在 ChatGPT 应用流程中，运行扫描工具并确认 RepoRelay 恰好暴露以下七个工具：

open_workspace
list_files
read_file
search_files
write_next_task
write_review
update_handoff_state

这是预期的正常界面。如果扫描工具显示 shell、Git、进程执行、通用文件编辑、删除、修补或任何其他意外功能，请停止并调查后再使用该应用——运行 reporelay audit "C:\Projects\my-app" --json 并确认工具列表。

8. 测试它

开始新的聊天，选择 RepoRelay 应用，然后尝试：

Open the approved repository and list its top-level files.

然后测试边界：

Try to read .env.

第二个请求应该被阻止。

你已连接——现在呢？

你现在已经让 ChatGPT 通过经过验证的安全边界审查你的仓库。有用的提示：

Read README.md and explain how this project starts.

Search the repository for "authentication".

Review src/server.ts for error-handling issues and write your findings.

ChatGPT ↔ 编码代理交接

正常的 RepoRelay 设置让 ChatGPT 进行规划和审查，而单独的本地编码代理（Codex、Claude 或其他）执行实现。RepoRelay 通过一个小的 .ai-handoff 工作区协调它们：

.ai-handoff/
├── NEXT_TASK.md   ChatGPT writes the task here
├── RESULT.md      the local coding agent writes its result here
├── REVIEW.md      ChatGPT writes its review here
└── STATE.json     coordinates the cycle

概念上：

ChatGPT
  ↓ writes NEXT_TASK.md

Codex / local coding agent
  ↓ implements
  ↓ writes RESULT.md

ChatGPT
  ↓ reviews result
  ↓ writes REVIEW.md

STATE.json 协调周期。RepoRelay 本身不运行 Codex 或 Claude——它们是独立的本地应用程序，你需要自己启动。交接文件只是一个结构化的地方，用于来回传递工作。

ChatGPT 只能写入 NEXT_TASK.md、REVIEW.md 和 STATE.json。实现者拥有的 RESULT.md 永远不能被 ChatGPT 写入。

详见 docs/handoff-cycle.md 了解详细协议，以及 examples/ 中的审阅者和实施者提示。

日常使用

一次性设置完成后，无需重新创建隧道或 ChatGPT 应用。每天：

1. 启动 RepoRelay：

   reporelay quickstart "C:\Projects\my-app"

2. 启动隧道（在第二个窗口中）：

   reporelay tunnel run

3. 打开 ChatGPT，开始新的对话，并选择现有的 RepoRelay 应用。

使用应用时保持两个窗口打开。如果连接中断，请再次运行 reporelay tunnel doctor。

切换仓库

RepoRelay 一次只暴露一个仓库。

1. 在 RepoRelay 终端中按 Ctrl+C。

2. 为新仓库启动 RepoRelay：

   reporelay quickstart "C:\Projects\another-repo"

3. 保持 tunnel-client 运行。它会自动重新连接到重启后的 RepoRelay（相同的端口和受保护的 bridge-secret 文件）。如果你使用了不同的端口，托管隧道会自动跟随。

4. 开始新的 ChatGPT 对话，并选择 RepoRelay 应用。

5. 请求 ChatGPT 打开新仓库。

不要仅仅因为批准的仓库发生了变化就重新扫描工具。只有在工具定义发生变化或 ChatGPT 要求你这样做时才重新扫描。

故障排除

对于其他任何情况，请运行 reporelay doctor。它会打印配置和安全状态，而不显示秘密值。

可选的只读模式

正常的RepoRelay体验是上述的7工具交接界面，这是推荐的初学者设置。如果你特别想让ChatGPT仅检查——无交接文件，无任何写入——请从以下开始：

reporelay quickstart "C:\Projects\my-app" --no-handoff-writes

在这种可选模式下，RepoRelay精确暴露四个工具：

open_workspace
list_files
read_file
search_files

只读模式不会创建 .ai-handoff，不会创建或修改 AGENTS.md，并保持已批准的仓库不变。所有隔离、认证和安全检查仍然适用。使用匹配的审计标志：

reporelay audit "C:\Projects\my-app" --no-handoff-writes

当你使用此模式时，在扫描工具中会看到4个工具而不是7个。

安全性

RepoRelay强制执行的边界包括：

• 仅回环绑定且需要认证；

• 确切存在一个规范批准的根目录；

• 敏感路径被阻止，包括 .env、VCS元数据、凭证存储和私钥格式；

• 遍历、绝对外部根路径、符号链接/连接点/重解析点逃逸以及硬链接绕过被阻止；

• 有界读取、搜索、结果和交接内容；

• 没有shell、PowerShell、Git、进程、通用写入、补丁、删除、工件、工作树、技能、子代理或本地代理工具；

• 交接写入仅限于三个固定的预先存在的目标。

RepoRelay是最小权限的应用边界，而不是针对已经以相同本地用户身份运行的恶意软件的操作系统沙箱。外部Secure MCP Tunnel是一个独立的安全边界，必须独立保护。请谨慎选择已批准的仓库。

请参阅 SECURITY.md 了解完整的安全模型和 reporelay audit 文档。

高级配置

大多数用户从不需要这些。当你需要时：

• Configuration — REPORELAY_* 环境变量，桥接认证，端口，日志和交接模式。

• ChatGPT Web setup details — 完整的隧道和应用参考。

• Windows operations — 生命周期脚本，计划任务和托管Windows设置。

• .env.example — 仅占位配置。切勿在其中放入真实的桥接密钥或隧道凭证。

• Local MCP clients — 如果你的MCP客户端与RepoRelay运行在同一台计算机上，则不需要隧道：将其指向快速启动打印的本地MCP URL，并发送从受保护文件加载的 X-RepoRelay-Bridge-Secret 头。

查看配置和安全状态而不打印秘密值：

reporelay doctor

要求和平台支持

• Node.js >=22.19 <27（包含npm）；

• Git用于基于克隆的安装——如果你下载ZIP包则是可选的。

此README中的快速入门适用于Windows、macOS和Linux。Windows 10/11是完全验证的生命周期和操作平台，包括PowerShell脚本和隧道管理的运行手册。

限制

• 一次只暴露一个已批准的仓库。

• RepoRelay不是操作系统沙箱。

• ChatGPT Web需要外部OpenAI Secure MCP Tunnel基础设施才能到达私有本地桥接。

• Windows是完全验证的生命周期平台；其他平台没有相同的PowerShell/隧道操作。

• Codex、Claude和其他编码代理是独立的本地应用程序，不是RepoRelay的组件。

文档

• ChatGPT Web setup

• Security model

• Configuration

• Windows operations

• Setup notes

• Handoff cycle

• Handoff examples

• Contributing

许可证和项目传承

RepoRelay根据MIT许可证发布。该项目保留所需的上游归属，并不捆绑Codex、Claude或其他实现者的SDK或运行时。

开发

npm ci
npm run typecheck
npm test
npm run verify:release
npm audit --audit-level=low
npm pack --dry-run --json
git diff --check