ChatGPT 网页版本地 Shell Agent 0.2.1（Windows + WSL）

这套实现把 ChatGPT 官方 Developer Mode 通过 OpenAI Secure MCP Tunnel 接到本机 Shell 与代码 workspace。模型推理只发生在 ChatGPT 网页会话中；服务端代码不会调用 Responses、Chat Completions、Realtime 或其他模型 API。Runtime API key 只交给官方 Tunnel 客户端建立传输链路。

项目没有截图、鼠标、键盘、UI Automation、桌面遥控或浏览器自动化工具，也不会把 chatgpt.com 包装成非官方 API。

能力

• 读取当前用户有权限访问的 Windows / WSL 普通文本文件。
• 保留原有 WSL bubblewrap shell_run：无授权倒计时，随服务长期可用；宿主 home、Windows mounts 与宿主 /var 不可见。
• PowerShell 7 与原生 Windows 可执行文件使用 windows_shell_open → windows_shell_prepare → windows_shell_run；首次本机批准后授权跨 Tunnel、MCP 与登录重启保留，直到显式 windows_shell_close。
• Windows 与 WSL repo 都支持 snapshot、diff、冲突检测、本机确认、原子写回与恢复副本。
• workspace 只复制 Git tracked / untracked nonignored 普通文件；排除 .env、凭据路径、检测到凭据内容的文件、symlink、junction、reparse point、特殊文件及 Git ignored 内容。
• Windows Shell 只继承白名单环境变量，secret-like 环境变量不会传入；输出最多各 2 MiB，并在返回 ChatGPT 前脱敏。
• Windows 子进程放入 kill-on-close Job Object；超时、撤销授权或 Agent 停止时终止命令树。
• 不提权、不调用 UAC。若 Gateway 本身处于提升状态，Windows Shell 会拒绝运行。

Windows snapshot 是可审核副本，不是强安全沙箱。标准用户进程仍可能访问该用户的其他文件，因此所有非严格只读的 Windows 命令都会被当作“可影响宿主”并逐次弹出本机确认。

详细边界见 SECURITY.md。

MCP 工具

文件工具：

system_health
fs_stat / fs_list / fs_search_paths
fs_inspect / fs_read / fs_release

共享 workspace 工具：

workspace_open(executor="wsl" | "windows")
workspace_status
workspace_diff
workspace_apply_back
workspace_close

Shell 工具：

shell_run                         # 只用于 WSL bubblewrap
windows_shell_status
windows_shell_open
windows_shell_prepare
windows_shell_run
windows_shell_close

windows_shell_prepare 会把 shell、完整命令或 argv、cwd、target、用途、超时、环境摘要、网络特征与风险绑定到 5 分钟的一次性 review_id。执行时不能替换字段；重启后 review token 失效，但 Windows Shell 的 DPAPI 持久授权仍有效。

Windows 命令分级

等级	行为
safe_query	Shell 已授权时可执行；接受 AST 可证明为静态只读的扩展 allowlist，包括文件/进程/服务/系统信息、哈希/ACL、PowerShell 元数据，以及 Git status/diff/log/show/rev-parse/ls-files/ls-tree 等查询。
workspace_write	cwd 映射到 Windows snapshot；ChatGPT 工具确认与 Windows 本机逐命令确认。
host_write	直接影响宿主或有网络/状态改变能力；ChatGPT 工具确认与 Windows 本机逐命令确认。
denied	提权、RunAs、EncodedCommand、命令混淆、安全防护关闭、注入、键盘记录、凭据转储或审批绕过。

Shell 永不返回精确凭据。合法任务确实需要原始值时，必须继续走 fs_inspect → fs_release(mode="exact")，并由用户在本机弹窗确认。

ChatGPT 中的用法

WSL workflow：

system_health
workspace_open(platform="windows", path="C:\path\repo", executor="wsl")
shell_run(command="...")
workspace_diff
workspace_apply_back(review_id="...", purpose="具体写回用途")
workspace_close

Windows workflow：

system_health
windows_shell_status
windows_shell_open(purpose="在本机 repo 中构建并运行测试")
workspace_open(platform="windows", path="C:\path\repo", executor="windows")
windows_shell_prepare(
  shell="powershell",
  command="python -m pytest",
  cwd="C:\path\repo",
  target="workspace",
  purpose="运行该 repo 的测试以验证当前修改",
  timeout_seconds=120
)
windows_shell_run(review_id="...")
workspace_diff
workspace_apply_back(review_id="...", purpose="测试通过后写回已审核 diff")
workspace_close

windows_shell_open 的旧 duration_seconds 参数为兼容保留，在 authorization_mode="persistent" 下会被忽略。不要在每次任务结束时调用 windows_shell_close；只有你希望撤销永久授权时才调用它。停止或重启 Tunnel 不会撤销授权。

对宿主做只读查询时使用 target="host"。任何安装、文件写入、注册表修改、进程/服务状态改变或网络传输都会逐命令弹出本机确认。

安装、升级与运行

默认安装位置：

%LOCALAPPDATA%\ChatGPTMCP

全新安装前，先在 OpenAI 控制面创建 Secure MCP Tunnel 和专用 Runtime API key。安装脚本不包含任何预置 Tunnel ID，必须显式传入：

& .\scripts\Install.ps1 -TunnelId 'tunnel_your_id'

默认 Tunnel profile 名为 chatgpt-local-coding-agent。如需自定义：

& .\scripts\Install.ps1 -TunnelId 'tunnel_your_id' -ProfileName 'my-local-coding-agent'

安装脚本会把 profile 名写入本机 config.toml。旧安装若还没有该配置项，Operator CLI 仅在 profiles 目录恰好有一个 YAML 时兼容发现；缺失或多个候选时会拒绝猜测。

从旧版本升级：

& .\scripts\Upgrade.ps1

升级脚本先在 %LOCALAPPDATA%\ChatGPTMCP\backups 保存配置、脚本、已安装包与依赖清单，再安装 0.2.1、运行完整测试；只有测试通过才把 windows_shell.enabled 改为 true 并设置 authorization_mode="persistent"。Runtime key 不会被读取、打印或删除。

常用命令：

& "$env:LOCALAPPDATA\ChatGPTMCP\Doctor.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Start-Agent.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Status-Agent.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Stop-Agent.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Enable-Autostart.ps1" -StartNow
& "$env:LOCALAPPDATA\ChatGPTMCP\Disable-Autostart.ps1"

登录任务只为当前用户注册，RunLevel=Limited，不使用最高权限。Windows Shell 授权记录由当前 Windows 用户的 DPAPI 加密，第一次通过 windows_shell_open 批准后会在登录/Tunnel/MCP 重启时恢复。WSL Shell 没有倒计时。永久授权不等于永久放行命令：Windows 非只读命令、原 repo 写回和精确敏感内容仍逐次本机确认。

ChatGPT 网页自己的工具确认是另一层：OpenAI Developer Mode 对写 action 默认要求确认，网页端“记住”只适用于当前对话，刷新或新对话可能再次询问。本机服务不能也不会绕过这一层。参见 Developer Mode 文档。

部署新工具定义后，到 ChatGPT 的 App/Connector 详情页执行 Refresh，审核新增的五个 Windows Shell actions。OpenAI 不会自动替你启用变更后的工具定义。参见 Developer Mode 文档。

网页额度与 API

本项目不以节省 ChatGPT 网页额度为目标。ChatGPT Plus 的模型使用限制会动态变化，MCP App 调用沿用对应 ChatGPT 会话的限制，不构成额外模型 API 调用；OpenAI API 账户与 ChatGPT 订阅则是独立计费体系。参见 ChatGPT Plus 与 Apps in ChatGPT。

开发验证

通用验证范围见 docs/VALIDATION.md。

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest

测试覆盖文件敏感分级、MCP 工具发现、WSL 无到期状态、Windows DPAPI 持久授权与显式撤销、损坏授权拒绝、Windows snapshot、Git ignored 产物、diff/apply/冲突、扩展只读 allowlist、PowerShell AST、一次性 token、环境隔离、输出脱敏、本机拒绝、超时与多级子进程清理。