English · 简体中文
[](https://github.com/jiezeng2004-design/PatchWarden/releases/latest) [](https://nodejs.org/) [](https://github.com/jiezeng2004-design/PatchWarden/releases/latest) [](LICENSE) > **让 ChatGPT 规划，本地 Agent 执行，但别把整台电脑直接交给它。** > > PatchWarden 把 ChatGPT 和 Codex CLI、Claude Code、OpenCode 等本地 Agent 连起来，只在你批准的工作区和验证边界内执行，并留下可检查的 Diff、验证和审计证据。 它不是通用远程 Shell，而是一条 **受控、可验证、可审计的 Agent 执行通道**。 [下载最新 Windows 版本](https://github.com/jiezeng2004-design/PatchWarden/releases/latest) · [快速开始](#5-分钟快速上手) · [连接 ChatGPT](#连接-chatgpt) · [安全边界](#安全边界)
真实工作流演示。敏感信息已遮挡。
## 为什么需要 PatchWarden 直接让远程 AI 控制本地开发环境，最难的不是“能不能执行”，而是： - 它到底能访问哪些目录？ - 能不能随便跑命令？ - Agent 说“测试通过”时，有没有独立证据？ - 改了哪些文件，是否超出批准范围？ - 最终是谁、基于什么证据接受了这次修改？ PatchWarden 把这些问题放进执行链路本身： ```text 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](https://github.com/jiezeng2004-design/PatchWarden/releases/latest) 下载 Windows x64 安装版或便携版。 当前安装包若未代码签名，Windows SmartScreen 可能提示未知发布者。请先用同一 Release 中的 SHA-256 校验文件核对安装包。 PowerShell： ```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： ```text 设置 → 本地 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 仓库。 连接完成后，先做只读检查： ```text 请调用 PatchWarden： 1. health_check 2. list_agents 只返回服务状态和可调用 Agent，不修改任何文件。 ``` ## 第一个可审计任务 建议第一次只在可丢弃的 Demo 仓库中测试： ```text 请通过 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 执行： ```text patchwarden-attest