chatgpt-web-agent

Capa de pegamento MCP local que permite que la interfaz web de ChatGPT utilice herramientas locales a través del Túnel MCP Seguro de OpenAI.

Esta es una implementación de referencia ejecutable, no un producto listo para instalar con un solo clic; su propósito principal es compartir una vía de integración validada en la práctica, que los usuarios puedan adaptar rápidamente a su propio entorno local con la ayuda de un agente.

La interfaz MCP del proyecto se mantiene estable, y las herramientas reales son proporcionadas por un LocalToolBackend reemplazable. El primer backend reutiliza directamente el SDK del Plugin OpenClaw, sin modificar el código fuente de OpenClaw ni reimplementar las herramientas de archivos, shell, parches y procesos en segundo plano.

Estado actual

P0 proporciona cuatro herramientas de OpenClaw:

• read

• exec

• process

• apply_patch

Opcionalmente, se pueden habilitar herramientas de intercambio de archivos de Google Drive:

• drive_list

• drive_search

• drive_stat

• drive_upload

• drive_download

• drive_export

• drive_mkdir

Por defecto, están habilitadas dos herramientas de solo lectura de OpenClaw Skills:

• skills_list(query?, limit?)

• skill_read(name)

skills_list() devuelve un directorio compacto de nombres de Skills elegibles y visibles para el modelo; con una query en lenguaje natural, puede devolver un pequeño conjunto de nombres y descripciones candidatos a través de una colección QMD independiente. skill_read solo acepta el nombre/clave de la Skill; la ruta canónica SKILL.md siempre se resuelve mediante skills.status de OpenClaw en tiempo real, sin aceptar rutas de archivo proporcionadas por el cliente. Las instrucciones de inicialización de MCP también indicarán al cliente: solo descubrir Skills activamente cuando la tarea claramente pueda depender de herramientas, servicios, flujos de trabajo o normas operativas locales y el contexto actual sea insuficiente; las tareas autónomas comunes no consultan Skills.

Por defecto, solo se permite que las herramientas de archivos y parches accedan al workspace configurado; exec.workdir también debe estar dentro del workspace. Los parámetros internos de host/security/ask/node/elevated de OpenClaw no se exponen al cliente MCP.

Para conectores independientes autorizados solo para un workspace de ChatGPT de confianza, se puede establecer CHATGPT_WEB_AGENT_WORKSPACE_ONLY=false; en este modo, el workspace es solo el punto de referencia para rutas relativas y el cwd predeterminado, y read/apply_patch/exec.workdir puede acceder a rutas absolutas externas. Este modo no es un sandbox de seguridad.

El límite de exec.workdir no es un sandbox de comandos. Un cliente con permiso exec aún puede acceder a otras partes del sistema en el texto del comando; solo se debe autorizar el Túnel a un workspace de ChatGPT de confianza y utilizar las políticas de allowlist/approval de OpenClaw según sea necesario.

Desarrollo

Requiere Node.js 22.22.3 o una versión compatible de OpenClaw Node, y pnpm.

pnpm install
pnpm check
pnpm smoke

Ejecución

export CHATGPT_WEB_AGENT_WORKSPACE=/path/to/workspace
# 可信独立 Connector 如需把 workspace 仅作为默认工作目录：
# export CHATGPT_WEB_AGENT_WORKSPACE_ONLY=false
pnpm build
node dist/cli.js

El servicio utiliza MCP stdio; la salida estándar solo transporta el protocolo MCP.

Configuración

Copia .env.example para ver las variables de entorno disponibles. La lista blanca de herramientas predeterminada es:

read,exec,process,apply_patch

exec usa por defecto allowlist + on-miss. Se puede sobrescribir explícitamente:

export CHATGPT_WEB_AGENT_EXEC_SECURITY=allowlist
export CHATGPT_WEB_AGENT_EXEC_ASK=on-miss

Para una primera prueba de humo local de confianza, se puede usar temporalmente:

export CHATGPT_WEB_AGENT_EXEC_SECURITY=full
export CHATGPT_WEB_AGENT_EXEC_ASK=off

Arquitectura

ChatGPT Web
  → OpenAI Secure MCP Tunnel
  → chatgpt-web-agent MCP Server
  → LocalToolBackend
      → OpenClawBackend
      → SkillsBackend → OpenClaw Gateway (live status)
                      → QMD MCP (optional semantic discovery)
      → NativeBackend / other backend（后续按需）

El backend de Skills solo realiza descubrimiento/lectura de capacidades; QMD es solo un acelerador de búsqueda de candidatos; el inventario en tiempo real de OpenClaw es siempre la fuente de verdad para elegibilidad, visibilidad del modelo y rutas canónicas de Skills.

Descubrimiento semántico de Skills

Se recomienda colocar el catálogo semántico en un índice QMD nombrado independiente, en lugar de compartir el índice de memoria. El ANN vectorial de QMD 2.5.3 primero toma candidatos de todo el índice y luego aplica el filtro de colección; mezclar unas decenas de Skills entre decenas de miles de documentos de memoria haría que la colección pequeña se viera inundada por candidatos de toda la base.

El despliegue actual utiliza:

local catalog: <workspace>/skills-catalog/
M4 mirror:     ~/qmd-data/skills-chatgpt-web-agent/
QMD index:     skills-chatgpt-web-agent
collection:    skills-chatgpt-web-agent
MCP endpoint:  http://192.168.0.96:8182/mcp

La recuperación usa Qwen3-Embedding-0.6B, solo vectorial, rerank=false, sin query expansion / HyDE. Los aciertos de QMD son solo candidatos; antes de devolverlos, se cruzan con skills.status en vivo. El esquema/inventario del catálogo se invalida por generación mediante catalogHash; cuando QMD no está disponible o el catálogo está obsoleto, se retrocede automáticamente al catálogo de solo nombres en vivo.

Google Drive

Drive es un canal de datos opcional; no realiza sincronización en segundo plano, montaje de disco ni duplicación completa del disco. La implementación utiliza directamente la API v3 de Google Drive; MCP solo expone primitivas pequeñas y estables para operaciones con archivos.

De forma predeterminada, las rutas locales de carga/descarga/exportación de Drive solo pueden estar en:

<CHATGPT_WEB_AGENT_WORKSPACE>/exchange

Esta restricción es independiente de CHATGPT_WEB_AGENT_WORKSPACE_ONLY y sirve para reducir el riesgo de que las herramientas de Drive se utilicen indebidamente como canal de transferencia arbitraria de datos locales. Si es necesario, el implementador puede ajustarlo mediante CHATGPT_WEB_AGENT_DRIVE_LOCAL_ROOT y CHATGPT_WEB_AGENT_DRIVE_LOCAL_ROOT_ONLY.

Configuración OAuth única

1. Habilita la API de Drive en Google Cloud y crea un cliente OAuth de escritorio.

2. Guarda el JSON de OAuth descargado como:

   <workspace>/.credentials/google-drive/credentials.json

   o establece CHATGPT_WEB_AGENT_DRIVE_CREDENTIALS para que apunte a otra ruta local privada.

3. Ejecuta:

   CHATGPT_WEB_AGENT_WORKSPACE=/path/to/workspace pnpm drive:auth

   Después de la autorización en el navegador, se generará un token de usuario autorizado con permisos 0600. El secreto del cliente OAuth y el token de actualización no deben enviarse a Git ni devolverse a través de MCP.

4. Al iniciar el servicio, establece:

   export CHATGPT_WEB_AGENT_DRIVE_ENABLED=true

En las herramientas de Drive, folderId / fileId utilizan directamente los IDs de la API de Drive. Los archivos binarios comunes usan drive_download; los documentos de Google Docs/Sheets/Slides usan drive_export para exportar al tipo MIME especificado.