01 · 开始前
准备好账号、工作区与本地 Agent
不要从真实生产仓库开始。先准备一个专用 Demo 工作区，并确认你能使用 OpenAI Tunnels 和 ChatGPT 自定义插件。
- Windows 10/11 与最新版 PatchWarden Desktop
- 可使用自定义 Plugins/Apps 的 ChatGPT 账号
- 一个专用代码目录，不能是磁盘根目录、用户主目录、桌面、下载或文档目录
- Codex CLI、Claude Code 或 OpenCode 至少一个，且已登录
- OpenAI Organization 中的 Tunnels Read + Use 权限
Core 负责受控任务、验证和审计。Direct 提供更直接的文件操作能力，建议在理解权限边界后再单独启用。
02 · 本地准备
安装 PatchWarden，选择安全工作区
运行安装包后选择“ChatGPT Tunnel”。工作区必须是实际包含项目的专用目录，PatchWarden 会把任务限制在这里。
- 1
下载并运行最新版桌面安装包。
- 2
首次启动选择 ChatGPT Tunnel；仅完全本地使用时选择本地 MCP。
- 3
点击文件夹按钮，选择你的专用 Demo 工作区。
- 4
进入“设置 → 本地 Agent 与模型”，确认至少一个 Agent 显示可用。
- 5
若 Agent 一启动就退出，在独立终端运行其 CLI，完成登录后回到 PatchWarden 重新检测。
检测到 CLI 不代表账号一定可用。Agent 立即退出时，优先检查 CLI 登录、许可和模型配置。
当前 Windows 安装包尚未代码签名，SmartScreen 可能显示未知发布者。安装前请用同一 Release 的 SHA-256 校验文件核对下载包。
03 · Tunnel
创建 runtime key，并连接 Core Tunnel
创建一个专用于 Tunnel 的运行时密钥。它只在创建时完整显示，请安全保存，永远不要放进截图、提示词、README 或仓库。
- 在 Organization API keys 页面创建专用 secret key。
- 确认创建者具有 Tunnels Read + Use 权限。
- 在 Tunnels 页面创建 PatchWarden（Core）Tunnel，并保存完整 Tunnel ID。
- 需要 Direct 时，再创建独立的 PatchWarden Direct Tunnel。
- 从 Tunnels 页面下载受支持的 tunnel-client。
- 打开“设置 → MCP 与隧道”，定位 tunnel-client.exe。
- 在 Core Profile 填写 Core Tunnel ID 与 runtime key，点击“配置并验证 Core”。
- 需要 Direct 时启用 Direct profile，并在 Direct Profile 单独填写凭据。
- 没有代理就选择“不使用代理”；本地代理 URL 不应含账号密码。
- 打开高级控制台，点击“全部启动”，等待 Core、Watcher、Tunnel 全部健康。
PatchWarden Tunnel 使用 CONTROL_PLANE_API_KEY 对应的 runtime key，不是普通 OPENAI_API_KEY。OPENAI_ADMIN_KEY 仅用于管理 Tunnel，不应作为长期运行密钥。
04 · ChatGPT
开启开发者模式，分别创建两个插件
ChatGPT 界面可能显示 Plugins、Apps 或旧称 Connectors。开发者模式允许添加未经审核的自定义 MCP，只应连接你自己的 PatchWarden。
- 1
打开 ChatGPT 设置 → Plugins/Apps（旧版可能叫 Connectors）。
- 2
找到并开启 Developer mode，阅读风险提示。
- 3
创建 PatchWarden：Connection 选 Tunnel，选择 Core Tunnel，Authentication 选 No Auth。
- 4
需要 Direct 时另建 PatchWarden Direct，选择 Direct Tunnel，同样使用 No Auth。
- 5
日常使用建议保留逐次确认，尤其是 Direct、文件修改和高风险动作。
这里询问 MCP Server 是否还需要额外 OAuth/Bearer 认证。当前 PatchWarden 已通过 Secure MCP Tunnel 连接，没有再加一层插件 OAuth。不要把 runtime key 粘贴到 Authentication 字段。
health_check
第一次连接检查
新建 ChatGPT 会话，同时选择 @PatchWarden 与可选的 @PatchWarden Direct，然后运行下面的只读检查。
@PatchWarden @PatchWarden Direct
请依次调用：
1. health_check
2. list_agents
返回 server_version、watcher.status、Core/Direct tool_profile、tool_count，
并列出 invocation_ready=true 的 Agent。不要执行任何文件修改。升级后看见旧工具？刷新两个插件
更新 PatchWarden 后，旧 ChatGPT 会话可能缓存旧工具目录。分别打开 PatchWarden 和 PatchWarden Direct，点击 Refresh，然后新建会话并再次调用 health_check。
核对 server_version、tool_profile、tool_count、catalog_consistent、watcher.status 与 tool_manifest_sha256。
05 · 第一个任务
先跑只读 Demo，再运行修改任务
第一次只验证连接、Agent 与真实测试命令，不改文件、不发布。确认闭环后，再扩大到明确允许的文件。
真实工作流演示
53 秒精简版 · 已遮挡敏感信息@PatchWarden @PatchWarden Direct
请对我的 Demo 工作区做一次只读连接测试：
1. 调用 health_check
2. 调用 list_agents
3. 选择 invocation_ready=true 的 Agent
4. 只读取 README.md 与 package.json
5. 运行 package.json 中真实存在的 npm test
6. 禁止修改文件，禁止 commit、push、tag、publish、release 或部署
7. 返回 task_id、lineage_id、verification、audit 和 changed_files_total只运行 package.json 中真实存在的验证命令；如果没有 npm test，就先让 Agent 报告可用脚本，不要猜。
06 · 验收
不要只相信“已完成”，要看证据
Agent 进程结束只说明它停止了。真正完成还需要独立 verification、范围检查、audit verdict 与最终 lineage 状态。
- task_id / lineage_id
- 任务与工作流的唯一证据
- verification passed
- 真实验证命令成功
- changed_files_total
- 实际修改文件数量
- out_of_scope_changes_total
- 范围外修改数量，预期为 0
- audit ACCEPTED
- 独立审计接受本次结果
- lineage accepted
- 工作流到达最终可接受状态
07 · 排障
最常见的五个问题
先判断是哪一段链路不健康，再处理。不要通过结束未知 PID 的方式强行恢复。
Watcher heartbeat is stale
先在高级控制台点击“全部启动”；仍未恢复时点击“全部重启”，等待状态变为 healthy。随后重新运行 health_check。
更新后仍显示旧工具
确认本地版本已更新，分别 Refresh 两个插件，关闭旧会话并新建会话，再比较 server_version 与 tool_manifest_sha256。
ChatGPT 看不到 Tunnel
确认 Tunnel 位于正确的 Organization/Workspace，key 创建者有 Tunnels Read + Use，tunnel-client 与 PatchWarden 都在运行。新 Tunnel 可能需要短暂传播。
Agent 显示可用，但任务立即失败
在终端直接运行 Agent CLI，确认登录与模型配置；回到 PatchWarden 重新检测，并查看 failure_reason、provider_error_reference 与日志。
创建插件时需要 Authentication 吗？
当前 Secure MCP Tunnel 配置选择 No Auth。runtime key 留在本地 PatchWarden/tunnel-client 中，不应填入 ChatGPT 插件。
08 · 安全
第一次演示也要守住边界
PatchWarden 帮你约束执行，但任务范围仍应由你明确写出。
- 永远不要公开 API Key、Token、Cookie、.env、SSH Key 或 Authorization Header。
- 公开截图建议遮挡 Tunnel ID、App ID、Version ID、用户名与私有仓库名。
- 使用专用 Demo 仓库，不要用生产仓库录制首次教程。
- 明确允许文件、验证命令和禁止操作。
- 演示任务禁止自动 commit、push、tag、publish、release 或部署。
- Direct 权限更直接，日常使用建议保留人工确认。
Links
官方入口
界面与深层链接可能调整；失效时从对应产品的 Settings 进入。