ChatGPT Codex Bridge

简体中文 | Seguridad | Contribuciones

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

[!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 personal.

• 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.

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

• 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.

• Utiliza 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 Secure MCP Tunnel de OpenAI.

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 escritorio utiliza 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": []
}

• 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.

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

Ejecuta las comprobaciones locales:

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

Conectar 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 en segundo plano 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.

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.

• 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, 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 del proyecto.

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.