ChatGPT Codex Bridge

简体中文 | Seguridad | Contribuir

Un puente MCP local-first que permite a ChatGPT inspeccionar proyectos de Codex registrados, leer el historial de sesiones de Codex y enviar tareas confirmadas a la CLI de Codex local.

[!IMPORTANT] Este es un proyecto comunitario independiente. No es un producto oficial de OpenAI y no está afiliado ni respaldado por OpenAI. ChatGPT, Codex y OpenAI son marcas comerciales de sus respectivos propietarios.

Qué hace

• Descubre proyectos ya registrados en Codex Desktop, sin otorgar acceso a todo el directorio de inicio.

• Ejecuta análisis y planificación en el sandbox de solo lectura de Codex.

• Requiere un token de confirmación de un solo uso y corta duración antes de las escrituras en el espacio de trabajo.

• Lista y lee sesiones de Codex visibles con paginación por cursor y redacción.

• Admite acceso limitado en el tiempo y confirmado por el usuario a sesiones individuales sin proyecto en la sección Recientes de Codex Desktop.

• Construye un contexto de historial de proyecto acotado sin cargar historiales de varios gigabytes en memoria.

• Crea y continúa sesiones persistentes de Codex Desktop mediante el protocolo local de app-server de Codex.

• Entrega el contexto proporcionado por ChatGPT a Codex como texto de referencia no confiable, con detección de secretos.

• Usa trabajos en segundo plano para que las tareas largas de Codex no mantengan abierta una solicitud de túnel MCP.

El puente no expone una herramienta de shell arbitraria y no escucha en un puerto público. El acceso remoto lo proporciona el cliente oficial de OpenAI Secure MCP Tunnel.

Related MCP server: ChatGPT MCP Bridge

Arquitectura

flowchart LR
    A[ChatGPT] -->|MCP connector| B[OpenAI Secure MCP Tunnel]
    B -->|outbound tunnel| C[tunnel-client on your machine]
    C -->|stdio MCP| D[ChatGPT Codex Bridge]
    D -->|sandboxed commands| E[Codex CLI]
    D -->|read-only indexes| F[Codex projects and sessions]
    D -. optional local IPC .-> G[Codex Desktop sidebar refresh]

La ruta opcional de actualización de la barra lateral depende de una extensión privada y no compatible de Codex Desktop y no se incluye en este repositorio. El puente principal funciona sin ella; las sesiones persistentes recién creadas pueden requerir un reinicio de Codex Desktop antes de aparecer en la barra lateral.

Requisitos

• macOS o Linux con Python 3.11+

• Una instalación y inicio de sesión funcionales de la CLI codex

• Codex Desktop para el descubrimiento automático de proyectos y las funciones de historial de sesiones

• Homebrew para la ruta de instalación documentada de Tunnel

• Acceso de la organización de OpenAI a Secure MCP Tunnels

Este proyecto se prueba actualmente en macOS. Windows no es compatible porque la ruta opcional de notificación de Desktop usa sockets Unix.

Inicio rápido

git clone https://github.com/AaAndrew233/chatgpt-codex-bridge.git
cd chatgpt-codex-bridge
./scripts/bootstrap.sh

bootstrap.sh crea un entorno virtual local, instala el bloqueo de dependencias revisado y genera archivos config.json y .mcp.json no rastreados. Nunca sobrescribe la configuración existente.

Abre config.json y elige una fuente de autorización:

{
  "codex_command": "codex",
  "model": null,
  "codex_project_catalog": "~/.codex/.codex-global-state.json",
  "allowed_roots": [],
  "session_access_ttl_seconds": 3600
}

• Mantén model como null para heredar tu configuración actual de Codex.

• Mantén allowed_roots vacío para usar solo proyectos registrados en Codex Desktop.

• Agrega directorios de proyecto específicos a allowed_roots solo cuando el descubrimiento automático no esté disponible.

• session_access_ttl_seconds controla la duración en memoria de una concesión aprobada de sesión sin proyecto y no puede superar las 24 horas.

• Nunca autorices / ni tu directorio de inicio. El puente rechaza ambos.

Ejecuta las comprobaciones locales:

./scripts/check_public_release.py
.venv/bin/python -m unittest discover -s tests -v

Conéctate a través de Secure MCP Tunnel

Instala el cliente oficial:

brew install openai/tools/tunnel-client
tunnel-client --version
tunnel-client help quickstart

Guarda la clave de runtime en un archivo fuera de este repositorio y restringe sus permisos:

chmod 600 /ABSOLUTE/PATH/TO/runtime-key

Crea un runtime de fondo administrado. Reemplaza todos los valores de marcador de posición:

tunnel-client runtimes connect \
  --alias codex-bridge \
  --profile codex-bridge \
  --tunnel-id '<YOUR_TUNNEL_ID>' \
  --runtime-api-key 'file:/ABSOLUTE/PATH/TO/runtime-key' \
  --mcp-command '/ABSOLUTE/PATH/TO/chatgpt-codex-bridge/scripts/run_server.sh'

Verifica que el runtime administrado esté en ejecución, sea saludable y esté listo:

tunnel-client runtimes status codex-bridge --json

Luego crea o actualiza el conector en configuración de conectores de ChatGPT. La guía oficial de incorporación de Tunnel es la fuente de verdad para los roles de organización, los ID de túnel, las claves de runtime y los comandos actuales: openai/tunnel-client/docs/onboarding.md.

No uses una clave de administrador para el runtime de larga duración. No confirmes claves de runtime, ID de túnel, perfiles generados, config.json ni .mcp.json.

Primera prueba en ChatGPT

Inicia una nueva conversación de ChatGPT con el conector habilitado y pregunta:

Call codex_status. Show only whether the bridge is healthy, the available tool names,
and the registered project names. Do not modify files.

Luego prueba una tarea de solo lectura:

Use codex_analyze on <PROJECT_PATH> to summarize the project structure and identify
the three highest-risk areas. Poll the job until it finishes and retrieve every output page.
Do not modify files.

Para una escritura, ChatGPT primero debe llamar a codex_prepare_apply, mostrarte el plan exacto, obtener tu confirmación explícita y solo entonces llamar a codex_apply con el token devuelto.

Para una sesión sin proyecto en Recientes, ChatGPT primero llama a codex_list_sessions(include_unassigned=true). El resultado expone solo metadatos de la barra lateral redactados. Luego debe llamar a codex_prepare_session_access, mostrarte el título de la sesión, el directorio de trabajo canónico, el modo de acceso y la solicitud de escritura exacta cuando corresponda, y esperar la aprobación explícita. El token de acceso devuelto activa una concesión en memoria solo para esa sesión. Las escrituras en el espacio de trabajo además requieren el token de confirmación de solicitud exacta devuelto por la misma llamada de preparación.

Herramientas MCP

Modelo de seguridad

El límite de confianza es intencionalmente estrecho:

• El acceso a proyectos se limita a raíces de proyectos de Codex validadas o raíces específicas explícitas.

• Las sesiones de Recientes sin proyecto permanecen ocultas de forma predeterminada y requieren una concesión de corta duración vinculada a una sesión, un directorio canónico y un modo.

• Los directorios sensibles como .ssh, .aws, .gnupg, .kube, .config y Library se rechazan durante el descubrimiento automático.

• Los subprocesos de Codex reciben un entorno mínimo y se ejecutan con modos de sandbox explícitos.

• Los tokens de escritura expiran, son de un solo uso y están vinculados al proyecto y la solicitud exactos.

• La salida de la sesión se filtra a mensajes visibles para el usuario y se redacta antes de salir de la máquina.

• Los límites de solicitud, salida, escaneo, concurrencia, retención y tiempo de espera están acotados.

• El contexto de ChatGPT se trata como entrada no confiable y no puede anular la política local.

Lee docs/security-model.md antes de exponer el puente a un equipo. Los informes de vulnerabilidad deben seguir SECURITY.md.

Límites operativos

Los límites predeterminados están documentados en config.example.json y se aplican al inicio. Los valores predeterminados importantes incluyen dos trabajos concurrentes, retención de trabajos completados de 30 minutos, una concesión de sesión de una hora, un límite de solicitud de 120 000 caracteres, salida de trabajo paginada de 100 000 caracteres y escaneos de transmisión acotados para el historial de proyectos.

scan_complete responde si el escaneo de fuente configurado finalizó. context_complete responde por separado si todo el texto escaneado cabe en el presupuesto de contexto devuelto. Un escaneo completo no es lo mismo que una exportación sin límites.

Desarrollo

./scripts/bootstrap.sh
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q \
  bridge_core.py conversation_catalog.py desktop_assignment.py \
  desktop_sessions.py project_context.py server.py

Consulta CONTRIBUTING.md para las reglas de contribución y docs/architecture.md para los límites de los módulos.

Licencia

Apache License 2.0. Consulta LICENSE.