用途
PatchWarden 把 ChatGPT 与本地 AI 编码智能体（Codex CLI、Claude Code、OpenCode 等）连接起来：用户先在 ChatGPT 中讨论想法和方案，再将批准的计划交给本地 Agent 实施。它并不是通用远程 Shell，而是一条受控、可验证、可审计的智能体执行通道，重点解决“让远程 AI 控制本地开发环境”时的安全性、证据与验收问题。
主要能力
PatchWarden 在执行链路中内建多个边界：
- 工作区边界：任务只能在配置的 workspaceRoot 内运行。
- Agent 边界：只调用本机已安装并配置好的 Agent。
- 命令边界：验证命令必须匹配允许列表。
- 真实 Diff：不只依赖 Agent 的自然语言总结。
- 独立验证：验证步骤与任务执行分开记录。
- 审计记录：保留 request / task / lineage / audit 状态。
- 人工验收：最终接受动作绑定到当前证据，而非仅修改 JSON 状态。
它旨在回答这类问题：Agent 说“测试通过”时是否有独立证据？改了哪些文件、是否超出批准范围？最终是谁基于什么证据接受了这次修改？
使用方式
从 Latest Release 下载 Windows x64 安装版或便携版。当前安装包若未代码签名，Windows SmartScreen 可能提示未知发布者，可先用同一 Release 中的 SHA-256 校验文件核对安装包。从源码或 npm 运行时需要 Node.js 20+，建议同时安装 Git 以生成可靠 Diff。
建议不要把磁盘根目录、用户主目录、桌面、下载目录直接作为 workspaceRoot，而应指定一个专门的项目目录。
打开 PatchWarden Desktop 后，至少一个 Agent 应显示可调用；若 CLI 尚未登录，先在独立终端完成登录，再回到 PatchWarden 重新检测。在“开始使用 / 高级控制台”中确认工作区、Agent 和 Core 服务正常。即使尚未连接 ChatGPT，本地执行边界也可先单独验证。
连接 ChatGPT Web：需要通过当前 OpenAI 支持的安全 MCP Tunnel / custom app 方式访问本地 PatchWarden。准备 tunnel-client；创建名为 PatchWarden 的专用 Core Tunnel；使用具备 Tunnels Read + Use 权限的专用 runtime key；在 PatchWarden 的“设置 → MCP 与隧道”中配置并验证；在 ChatGPT Developer mode 中添加 PatchWarden，Authentication 选 No Auth；保留适合工作区风险等级的确认策略。
相关安全提示：runtime key 对应 CONTROL_PLANE_API_KEY，不是普通 OPENAI_API_KEY；OPENAI_ADMIN_KEY 可用于管理 Tunnel，但不应作为长期运行密钥；不要把 runtime key 填进 ChatGPT 的 Authentication 字段；Direct 是可选的第二 Tunnel，只有需要 Direct 工具时才创建；如果直接启用本地 HTTP MCP（不经过 stdio Tunnel），必须先配置 PATCHWARDEN_OWNER_TOKEN，匿名 /healthz 只返回最小状态，详细 health 与 /mcp 都要求 owner token。Tunnel runtime key 是本地秘密，不要写进 README、Prompt、截图或 Git 仓库。
建议第一次只在可丢弃的 Demo 仓库中测试，不要只看 Agent 说“完成了”。审计通过后，任务通常仍是 ready_for_review，权威验收需要在本地 TTY 执行。
适用场景
适合“我已经知道要做什么，现在需要一个受控执行层”的工作流：在 ChatGPT 里规划和监督本地开发任务，继续使用 Codex CLI / Claude Code / OpenCode 作为真正执行者，同时不给远程模型无限制 Shell。
限制与边界
PatchWarden 不替代 Codex / Claude Code / OpenCode；不把所有本地文件自动暴露给 ChatGPT；不把 Agent 的自然语言“测试通过”当成最终证据；也不应被用来绕过原有的本地安全策略。它更适合受控执行，而不是替代完整的需求分析或产品决策流程。
Direct 是可选的受限编辑能力，不是只读验证通道；它提供受工作区边界、敏感路径和确认策略约束的文件编辑能力（包括补丁、创建、移动和删除），只有明确需要时才启用，并保留人工确认。未启用时不要在提示词里引用它。
常见问题：Agent 检测到但不可调用时，先在独立终端运行对应 CLI 完成登录和基础模型配置，再回 PatchWarden 重新检测。Watcher / Core 状态异常时，先通过高级控制台执行正常启动/重启流程，不要直接强杀未知 PID。Tunnel 异常时，先确认本地 PatchWarden 健康，再检查 Tunnel 是否连接到正确 profile，以及 ChatGPT 侧是否使用当前支持的 MCP/custom app 连接方式。命令未命中允许列表时，检查它是否真实存在于项目中并匹配允许命令配置，不要为让任务通过而临时放宽为任意 Shell。
PatchWarden 的核心原则是“能力最小化 + 证据优先”。项目采用 MIT 许可，See LICENSE。PatchWarden 是独立开源项目，与 OpenAI、Anthropic、OpenCode 无关联，也未经其背书。
