Agente Shell local para la versión web de ChatGPT 0.2.1 (Windows + WSL)

Esta implementación conecta el Developer Mode oficial de ChatGPT a través de OpenAI Secure MCP Tunnel con el Shell local y el workspace de código. La inferencia del modelo ocurre solo en la sesión web de ChatGPT; el código del servidor no llama a Responses, Chat Completions, Realtime ni a otras APIs de modelos. La clave de API de runtime se entrega únicamente al cliente oficial de Tunnel para establecer el enlace de transporte.

El proyecto no incluye capturas de pantalla, mouse, teclado, automatización de UI, control remoto de escritorio ni herramientas de automatización de navegador, y no envuelve chatgpt.com como una API no oficial.

Capacidades

• Lee archivos de texto plano normales de Windows / WSL a los que el usuario actual tiene acceso.

• Conserva el shell_run original de WSL con bubblewrap: sin cuenta regresiva de autorización, disponible a largo plazo con el servicio; el home del host, los montajes de Windows y /var del host no son visibles.

• PowerShell 7 y los ejecutables nativos de Windows usan windows_shell_open → windows_shell_prepare → windows_shell_run; tras la primera aprobación local, la autorización se conserva a través de Tunnel, MCP y reinicios de sesión, hasta que se invoque explícitamente windows_shell_close.

• Los repos de Windows y WSL admiten snapshot, diff, detección de conflictos, confirmación local, escritura atómica y copias de respaldo.

• El workspace solo copia archivos normales rastreados por Git o no rastreados y no ignorados; excluye .env, rutas de credenciales, archivos con contenido de credenciales detectado, symlinks, junctions, reparse points, archivos especiales y contenido ignorado por Git.

• Windows Shell solo hereda variables de entorno de una lista blanca; las variables de entorno con apariencia de secreto no se pasan; la salida se limita a 2 MiB por cada una y se desinfecta antes de devolverla a ChatGPT.

• Los subprocesos de Windows se colocan en un Job Object de kill-on-close; al agotarse el tiempo, revocar la autorización o detener el agente, se termina el árbol de comandos.

• No eleva privilegios ni invoca UAC. Si la puerta de enlace está elevada, Windows Shell se niega a ejecutarse.

El snapshot de Windows es una copia auditable, no un sandbox de seguridad fuerte. Los procesos de usuario estándar aún pueden acceder a otros archivos de ese usuario, por lo que todos los comandos de Windows que no sean estrictamente de solo lectura se tratan como "capaces de afectar al host" y solicitan confirmación local comando por comando.

Los límites detallados se encuentran en SECURITY.md.

Related MCP server: MCP ChatGPT Full PC Dev

Herramientas MCP

Herramientas de archivos:

system_health
fs_stat / fs_list / fs_search_paths
fs_inspect / fs_read / fs_release

Herramientas de workspace compartido:

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

Herramientas de Shell:

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

windows_shell_prepare vincula el shell, el comando completo o argv, cwd, target, propósito, tiempo de espera, resumen de entorno, características de red y riesgo a un review_id de un solo uso de 5 minutos. Al ejecutar no se pueden reemplazar los campos; tras un reinicio, el token de revisión caduca, pero la autorización persistente DPAPI de Windows Shell sigue siendo válida.

Clasificación de comandos de Windows

El Shell nunca devuelve credenciales exactas. Cuando una tarea legítima realmente necesita el valor original, debe continuar con fs_inspect → fs_release(mode="exact") y el usuario debe confirmar en un diálogo local.

Uso en ChatGPT

Flujo de trabajo de WSL:

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

Flujo de trabajo de Windows:

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

El parámetro antiguo duration_seconds de windows_shell_open se conserva por compatibilidad y se ignora bajo authorization_mode="persistent". No llames a windows_shell_close al final de cada tarea; solo llámalo si deseas revocar la autorización permanente. Detener o reiniciar el Tunnel no revoca la autorización.

Usa target="host" para consultas de solo lectura al host. Cualquier instalación, escritura de archivos, modificación del registro, cambio de estado de procesos/servicios o transferencia de red solicitará confirmación local comando por comando.

Instalación, actualización y ejecución

Ubicación de instalación predeterminada:

%LOCALAPPDATA%\ChatGPTMCP

Antes de una instalación nueva, crea un Secure MCP Tunnel y una clave de API de runtime dedicada en el panel de control de OpenAI. El script de instalación no incluye ningún ID de Tunnel preestablecido; debe pasarse explícitamente:

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

El perfil de Tunnel predeterminado se llama chatgpt-local-coding-agent. Para personalizarlo:

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

El script de instalación escribe el nombre del perfil en el config.toml local. Si una instalación anterior aún no tiene esa configuración, el CLI de Operator solo realiza descubrimiento compatible si hay exactamente un YAML en el directorio de perfiles; si hay varios o ninguno, se niega a adivinar.

Actualización desde una versión anterior:

& .\scripts\Upgrade.ps1

El script de actualización primero guarda la configuración, los scripts, los paquetes instalados y el manifiesto de dependencias en %LOCALAPPDATA%\ChatGPTMCP\backups, luego instala 0.2.1 y ejecuta las pruebas completas; solo si las pruebas pasan, cambia windows_shell.enabled a true y establece authorization_mode="persistent". La clave de runtime no se lee, imprime ni elimina.

Comandos comunes:

& "$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"

La tarea de inicio de sesión se registra solo para el usuario actual, con RunLevel=Limited, sin privilegios elevados. El registro de autorización de Windows Shell está cifrado con DPAPI del usuario actual de Windows; tras la primera aprobación mediante windows_shell_open, se restaura en los reinicios de sesión/Tunnel/MCP. El Shell de WSL no tiene cuenta regresiva. La autorización permanente no significa permiso permanente para comandos: los comandos de Windows que no son de solo lectura, la escritura de vuelta al repo original y el contenido sensible exacto siguen requiriendo confirmación local comando por comando.

La confirmación de herramientas de la propia página web de ChatGPT es otra capa: el Developer Mode de OpenAI requiere confirmación por defecto para acciones de escritura, y el "recordar" en la página web solo se aplica a la conversación actual; al actualizar o iniciar una nueva conversación, puede volver a preguntar. El servicio local no puede ni intentará eludir esta capa. Consulta la documentación de Developer Mode.

Después de implementar nuevas definiciones de herramientas, ve a la página de detalles de App/Connector en ChatGPT y ejecuta Refresh para revisar las cinco acciones nuevas de Windows Shell. OpenAI no habilita automáticamente las definiciones de herramientas modificadas. Consulta la documentación de Developer Mode.

Cuota web y API

Este proyecto no tiene como objetivo ahorrar cuota web de ChatGPT. Los límites de uso del modelo de ChatGPT Plus cambian dinámicamente; las llamadas de la App MCP siguen los límites de la sesión de ChatGPT correspondiente y no constituyen llamadas adicionales a la API de modelos; la cuenta de API de OpenAI y la suscripción de ChatGPT son sistemas de facturación independientes. Consulta ChatGPT Plus y Apps in ChatGPT.

Validación de desarrollo

El alcance de validación general se encuentra en docs/VALIDATION.md.

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

Las pruebas cubren la clasificación de sensibilidad de archivos, el descubrimiento de herramientas MCP, el estado sin caducidad de WSL, la autorización persistente DPAPI de Windows y su revocación explícita, el rechazo de autorizaciones corruptas, el snapshot de Windows, los artefactos ignorados por Git, diff/apply/conflictos, la lista blanca extendida de solo lectura, el AST de PowerShell, los tokens de un solo uso, el aislamiento de entorno, la desinfección de salida, el rechazo local, el tiempo de espera y la limpieza de subprocesos de múltiples niveles.