PatchWarden

English · 简体中文

让 ChatGPT 规划，本地 Agent 执行，但别把整台电脑直接交给它。

PatchWarden 把 ChatGPT 和 Codex CLI、Claude Code、OpenCode 等本地 Agent 连起来，只在你批准的工作区和验证边界内执行，并留下可检查的 Diff、验证和审计证据。

它不是通用远程 Shell，而是一条 受控、可验证、可审计的 Agent 执行通道。

下载最新 Windows 版本 · 快速开始 · 连接 ChatGPT · 安全边界

_{真实工作流演示。敏感信息已遮挡。}

为什么需要 PatchWarden

直接让远程 AI 控制本地开发环境，最难的不是“能不能执行”，而是：

• 它到底能访问哪些目录？
• 能不能随便跑命令？
• Agent 说“测试通过”时，有没有独立证据？
• 改了哪些文件，是否超出批准范围？
• 最终是谁、基于什么证据接受了这次修改？

PatchWarden 把这些问题放进执行链路本身：

ChatGPT
   ↓  任务 + 约束
PatchWarden
   ↓  工作区 / Agent / 命令边界
Local coding agent
   ↓
Workspace changes
   ↓
Verification + diff + audit + lineage
   ↓
Human acceptance

你能得到什么

• 工作区边界：任务只能在配置的 workspaceRoot 内运行。
• Agent 边界：只调用你本机已经安装并配置好的 Agent。
• 命令边界：验证命令必须匹配允许列表。
• 真实 Diff：不只相信 Agent 的自然语言总结。
• 独立验证：验证步骤和任务执行分开记录。
• 审计记录：保留 request / task / lineage / audit 状态。
• 人工验收：最终接受动作绑定到当前证据，而不是简单改一个 JSON 状态。

适合谁

如果你想：

• 在 ChatGPT 里规划和监督本地开发任务；
• 继续使用 Codex CLI / Claude Code / OpenCode 作为真正执行者；
• 又不想给远程模型一个无限制 Shell；
• 希望每次修改都有可复查证据；

PatchWarden 就是为这种工作流做的。

5 分钟快速上手

1. 下载

从 Latest Release 下载 Windows x64 安装版或便携版。

当前安装包若未代码签名，Windows SmartScreen 可能提示未知发布者。请先用同一 Release 中的 SHA-256 校验文件核对安装包。

PowerShell：

Get-FileHash .\PatchWarden-Setup-*-x64.exe -Algorithm SHA256

2. 准备本地 Agent

至少安装并登录一个：

• Codex CLI
• Claude Code
• OpenCode

从源码或 npm 运行时需要 Node.js 20+；建议同时安装 Git 以生成可靠 Diff。

3. 选一个专用工作区

不要把磁盘根目录、用户主目录、桌面、下载目录直接作为 workspaceRoot。

建议给 PatchWarden 一个专门的项目目录，只放你明确允许它操作的仓库。

4. 检测 Agent

打开 PatchWarden Desktop：

设置 → 本地 Agent 与模型

至少一个 Agent 应显示可调用。如果 CLI 尚未登录，先在独立终端完成登录，再回到 PatchWarden 重新检测。

5. 确认本地健康状态

在 开始使用 / 高级控制台 中确认工作区、Agent 和 Core 服务正常。

到这里，即使还没连接 ChatGPT，PatchWarden 的本地执行边界也已经可以先单独验证。

连接 ChatGPT

ChatGPT Web 需要通过当前 OpenAI 支持的安全 MCP Tunnel / custom app 连接方式访问本地 PatchWarden。

典型流程：

1. 准备 tunnel-client；
2. 创建名为 PatchWarden 的专用 Core Tunnel；
3. 使用具备 Tunnels Read + Use 权限的专用 runtime key；
4. 在 PatchWarden 的 设置 → MCP 与隧道 中配置并验证；
5. 在 ChatGPT Developer mode 中添加 PatchWarden，Authentication 选 No Auth；
6. 保留适合你工作区风险等级的确认策略。

连接时请保持这些边界：

• 这个 runtime key 对应 CONTROL_PLANE_API_KEY，不是普通 OPENAI_API_KEY；
• OPENAI_ADMIN_KEY 可以用于管理 Tunnel，但不应作为长期运行密钥；
• 不要把 runtime key 填进 ChatGPT 的 Authentication 字段；
• Direct 是可选的第二 Tunnel，只有需要 Direct 工具时才创建；
• Direct 不是只读通道。它提供受工作区边界、敏感路径和确认策略约束的文件编辑能力（包括补丁、创建、移动和删除）；只有明确需要时才启用，并保留人工确认；
• 如果直接启用本地 HTTP MCP（不经过 stdio Tunnel），必须先配置 PATCHWARDEN_OWNER_TOKEN。匿名 /healthz 只返回最小状态，详细 health 与 /mcp 都要求 owner token。

Tunnel runtime key 是运行连接所需的本地秘密，不要写进 README、Prompt、截图或 Git 仓库。

连接完成后，先做只读检查：

请调用 PatchWarden：
1. health_check
2. list_agents

只返回服务状态和可调用 Agent，不修改任何文件。

第一个可审计任务

建议第一次只在可丢弃的 Demo 仓库中测试：

请通过 PatchWarden 执行一次受控任务：
- 只在我指定的 Demo 工作区内工作；
- 使用 invocation_ready=true 的本地 Agent；
- 只修改我明确允许的文件；
- 只运行项目中真实存在且已允许的验证命令；
- 禁止 commit、push、tag、publish、release、deploy；
- 最后返回 Diff、verification、audit 和 lineage 状态。

不要只看 Agent 说“完成了”

一次可靠的任务结果至少应该能回答：

证据	你要确认什么
task_id / lineage_id	这次工作能否唯一追踪
changed files	是否只改了批准范围
verification	真实验证命令是否通过
out-of-scope changes	是否为 0
audit	独立审计是否接受
local attestation	是否用 patchwarden-attest 对当前证据做了人工验收
final lineage	整条工作流是否完整结束

审计通过后，任务通常仍是 ready_for_review。权威验收需要在本地 TTY 执行：

patchwarden-attest <task_id> --accept

PatchWarden 的目标不是让 Agent “更会说自己做对了”，而是让你能检查它到底做了什么。

安全边界

PatchWarden 的核心原则：能力最小化 + 证据优先。

• 工作区必须显式配置；
• 不把任意本机路径默认暴露给远程模型；
• 验证命令受允许列表限制；
• Direct 是可选的受限编辑能力，不是只读验证通道；它应保持更严格的工作区边界、敏感路径和确认策略，未启用时不要在提示词里引用它；
• 本地 HTTP MCP 的敏感接口要求 owner token；
• 本地 HTTP MCP 的详细 health 与 /mcp 都要求 PATCHWARDEN_OWNER_TOKEN；
• 日志、截图和诊断不应暴露 API Key / Tunnel ID /账号秘密；
• 最终人工 attestation 绑定当前证据摘要，而不是只相信任务目录里的状态文件；
• 对高风险操作，应继续保留人工确认。

PatchWarden 不是什么

• 不是通用远程桌面；
• 不是无限制远程 Shell；
• 不替代 Codex / Claude Code / OpenCode；
• 不把所有本地文件自动暴露给 ChatGPT；
• 不把 Agent 的自然语言“测试通过”当成最终证据；
• 不应该用来绕过你原本的本地安全策略。

支持的工作流

PatchWarden 当前重点围绕：

Plan in ChatGPT
      ↓
Execute with a local coding agent
      ↓
Verify independently
      ↓
Audit actual changes
      ↓
Accept with evidence

它更适合“我已经知道要做什么，现在需要一个受控执行层”，而不是替代完整的需求分析或产品决策流程。

常见排障

Agent 检测到了但不可调用

在独立终端直接运行对应 CLI，先完成登录和基础模型配置，再回到 PatchWarden 重新检测。

Watcher / Core 状态异常

先通过高级控制台执行正常的启动/重启流程。不要直接强杀未知 PID。

ChatGPT 无法连接

先确认本地 PatchWarden 健康，再检查 Tunnel 是否连接到正确 profile，以及 ChatGPT 侧是否使用了当前支持的 MCP/custom app 连接方式。

验证命令被拒绝

检查它是否真的存在于项目中，并且是否匹配 PatchWarden 的允许命令配置。不要为了让任务通过而临时放宽为任意 Shell。

开发与审计理念

PatchWarden 更关心这些问题：

• 执行权属于谁？
• 工作区边界在哪里？
• 结果能不能独立验证？
• 证据是否能追溯到这一次具体任务？
• 人工最终接受是否绑定到当前证据？

如果这些边界比“少一次确认”更重要，这个项目就有价值。

License

MIT. See LICENSE.

---

PatchWarden is an independent open-source project and is not affiliated with or endorsed by OpenAI, Anthropic, or OpenCode.