Codex Control Plane MCP

Codex Control Plane MCP

Español | Русский

Automatización fiable de Codex Desktop para tareas largas.

codex-control-plane-mcp convierte Codex Desktop y codex-app-server en un trabajador duradero que un cliente MCP puede manejar de forma segura. Envía una tarea, recibe un operationId o workflowId de inmediato, consulta hasta que el trabajo termine, aprueba Plan Mode cuando sea necesario y luego lee el informe final.

El servidor se encarga de las partes complicadas que los wrappers ligeros suelen dejar al llamante: inicio del servidor de la aplicación, creación de hilos y turnos, seguridad ante reintentos, protección contra prompts duplicados, Plan Mode, aprobaciones, historial local, diagnósticos y reparación.

OpenClaw y Hermes son clientes de primera clase, pero el servidor es útil para cualquier orquestador local que necesite que Codex Desktop realice trabajo de larga duración sin mantener una llamada MCP abierta durante horas.

La versión corta

MCP client / orchestrator
  -> submit a task or start a Plan Mode workflow
  <- receive operationId or workflowId immediately
  -> poll status
  -> answer approvals or approve the plan
  <- read final report, diagnostics, threadId, and turnId

Eso te da un contrato simple:

• sin llamadas MCP de varias horas;
• sin turnos duplicados de Codex después de un reintento del cliente;
• sin envío de tareas a ciegas sin seguimiento;
• un registro local SQLite de operaciones, flujos de trabajo, turnos, hooks y diagnósticos.

¿Por qué no simplemente llamar a Codex directamente?

Capacidad	Wrapper ligero de Codex	Codex Control Plane MCP
Tareas de varias horas	bloqueante / frágil	operación asíncrona duradera
Recuperación ante timeout del cliente	manual	client_request_id seguro ante reintentos
Protección contra turnos duplicados	no	detección activa de prompts
Flujo de trabajo de Plan Mode	humano / manual	estado de flujo de trabajo consultable
Aprobaciones y preguntas	bloqueante / opaco	API de interacciones pendientes
Recuperación tras reinicio	ad hoc	estado de operación persistido
Diagnósticos	solo registros	herramientas de salud, diagnóstico y reparación

Para una guía de decisión más detallada, consulta docs/THIN_WRAPPERS.md.

Soporte actual

• Objetivo completo en vivo: Windows con Codex Desktop y codex-app-server.
• Linux y macOS: solo comprobaciones de protocolo por ahora.
• Local primero: no está pensado para exponerse como servicio de red público.

Modelo de seguridad

Este es un plano de control local primero para entornos confiables de Codex Desktop.

No lo expongas como servicio de red sin autenticación.

Postura recomendada para la primera ejecución:

• usa read-only para repositorios no confiables;
• usa la aprobación on-request al probar nuevos flujos de trabajo;
• Plan Mode nunca se ejecuta con un sandbox read-only. Si un llamante solicita read-only, MCP eleva ese turno a workspace-write e informa el ajuste en la salida de estado;
• mantén privados state/, logs/, .env y .codex/.

Qué hace

• Cola asíncrona duradera para operaciones de escritura de Codex.
• Manejo de client_request_id seguro ante reintentos.
• Detección activa de prompts duplicados.
• Leases y heartbeats SQLite para procesos MCP en competencia.
• Recuperación tras reinicio de MCP durante thread/start o turn/start.
• turn/steer duradero para añadir contexto a un turno activo sin crear un segundo turno.
• thread/fork duradero para ramificar un hilo existente, con o sin mensaje inicial.
• Flujos de trabajo de Plan Mode: iniciar plan, consultar, aprobar, ejecutar, leer informe final.
• Piso de ejecución de Plan Mode: workspace-write, con runtimePolicyAdjusted en estado cuando MCP eleva una solicitud read-only.
• Flujos de trabajo de revisión de código mediante review/start del servidor de la aplicación, con consulta y captura del informe final.
• Informes finales estructurados con output_schema.
• Herramientas de ciclo de vida de hilos para archivar, desarchivar y compactación consultable.
• Sincronización de objetivos de flujo de trabajo con los objetivos de hilo de Codex Desktop.
• Entradas de imagen e imagen local para turnos que se inician mediante turn/start.
• Aprobaciones y preguntas pendientes expuestas como estado MCP consultable.
• Interrupciones de turno por threadId/turnId, operationId o workflowId.
• Inventario de ejecución para modelos, perfiles de permisos, preparación del sandbox, hooks, habilidades, características del proveedor, estado de la cuenta, bandas de uso, estado de límite de velocidad y métodos admitidos del servidor de la aplicación.
• Comprobaciones de salud, diagnósticos, análisis de problemas y reparaciones de prueba.
• Historial de hooks propiedad de MCP en SQLite para búsqueda, resúmenes y lecturas de respaldo.
• Diario de progreso del servidor de la aplicación con redacción para deltas, advertencias, redireccionamientos de modelo y uso de tokens.
• Errores MCP estructurados sobre los que el código de automatización puede ramificar.

Las acciones de escritura y control pasan por codex-app-server. El servidor no modifica las bases de datos SQLite internas de Codex ni los archivos de transcripción.

Instalación

Recomendado:

pipx install codex-control-plane-mcp

O ejecuta directamente:

uvx codex-control-plane-mcp

Desde GitHub:

python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"

Para desarrollo local:

git clone https://github.com/aresyn/codex-control-plane-mcp.git
cd codex-control-plane-mcp
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q

Configuración del cliente MCP

Después de la instalación, genera una configuración:

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

Entrada stdio mínima:

{
  "mcpServers": {
    "codex-control-plane": {
      "command": "codex-control-plane-mcp",
      "args": []
    }
  }
}

Hay más ejemplos listos para copiar y pegar para Claude Desktop, Cursor, clientes MCP estilo VS Code, checkouts locales, paquetes instalados y modo de trabajador central en examples/mcp-client-configs.md.

Ejecuta el servidor MCP stdio:

codex-control-plane-mcp

O ejecútalo como módulo:

py -m codex_control_plane_mcp.server

Los antiguos comandos openclaw-codex-mcp y openclaw-codex-mcp-hooks siguen estando disponibles como alias de compatibilidad durante una línea de versión.

Modo de trabajador central

El modo inline predeterminado sigue siendo la configuración más simple: un proceso MCP puede enviar y ejecutar operaciones. Para OpenClaw, Hermes o cualquier configuración con varios clientes MCP, usa un trabajador central en su lugar.

Forma local recomendada:

• cada cliente MCP usa el mismo CODEX_HOME y CODEX_MCP_STATE_DB;
• las entradas de puerta de enlace de OpenClaw se ejecutan con CODEX_MCP_EXECUTION_MODE=client;
• un proceso codex-control-plane-mcp-worker de larga duración es dueño de codex-app-server, leases, espacios de cola y bloqueos de recursos;
• los clientes llaman a codex_submit_task y luego consultan el estado. No ejecutan operaciones en cola ellos mismos.

Comando del trabajador:

$env:CODEX_MCP_EXECUTION_MODE = "worker"
codex-control-plane-mcp-worker

Modo de observación segura, útil antes de cambiar una puerta de enlace en vivo:

codex-control-plane-mcp-worker --observe

Valores predeterminados de concurrencia:

CODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL=4
CODEX_MCP_MAX_ACTIVE_TURNS_PER_PROJECT=3
CODEX_MCP_MAX_ACTIVE_TURNS_PER_AGENT=3
CODEX_MCP_MAX_ACTIVE_TURNS_PER_THREAD=1
CODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT=1
CODEX_MCP_MAX_APP_SERVER_PENDING_REQUESTS=8

Para turnos de escritura en el mismo proyecto, pasa resource_keys a codex_submit_task. Sin ellos, los turnos workspace-write y danger-full-access toman un bloqueo amplio de escritura del proyecto. Con claves disjuntas, el trabajador puede ejecutar varios turnos de escritura en paralelo.

Nuevas herramientas de estado:

• codex_get_worker_status
• codex_get_queue_status
• codex_get_concurrency_status
• codex_get_worker_command_status

codex_get_operation_status también devuelve queueState, workerState, slotState y resourceLockState. Un turno en ejecución tiene slotState.claimed=true y un slotClaim con el id del trabajador, tipo de espacio y tiempo de reclamación. codex_get_queue_status separa el trabajo en cola de las operaciones de turno en ejecución, operaciones auxiliares, espacios de turno activos y conflictos de bloqueo.

Cuando un flujo de trabajo está esperando capacidad, codex_get_workflow_status refleja el estado de la cola de operaciones anidada en workflowOperationQueueState. Usa nextRecommendedAction="wait_for_worker_slot" para presión de espacios y nextRecommendedAction="wait_for_resource_lock" para conflictos de bloqueo de escritura. No crees otra operación para el mismo trabajo mientras se devuelva cualquiera de esas acciones.

Primera configuración

El asistente de administración puede generar una configuración de cliente más completa, instalar hooks y ejecutar una prueba de protocolo:

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

El comando imprime un bloque JSON que puedes copiar en una configuración de cliente MCP. No imprime secretos ni prompts privados.

También puedes instalar solo los hooks de Codex:

codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3
codex-control-plane-mcp-hooks status
codex-control-plane-mcp-hooks doctor

El instalador hace una copia de seguridad de ~/.codex/hooks.json, combina sus manejadores con tus hooks existentes, almacena stateDb como ruta absoluta y escribe prompts, texto visible de progreso del agente, respuestas finales y estado de turno en la base de datos de estado MCP. Las llamadas a herramientas y las salidas de comandos no se registran de forma predeterminada. Reinicia Codex después de instalar o cambiar hooks.

Para turnos iniciados mediante codex-app-server, el servidor refleja el prompt aceptado, los mensajes visibles del asistente y el estado del turno en el mismo historial SQLite. Eso mantiene útiles la búsqueda y las lecturas de estado incluso cuando el servidor de la aplicación no ejecuta los hooks de usuario por sí mismo.

Flujos de trabajo principales

Envía una tarea duradera:

codex_submit_task
  -> operationId
codex_get_operation_status(operationId)
  -> queued / running / waiting_for_approval / completed / failed

Usa el mismo client_request_id cuando un llamante reintente después de un timeout de transporte. El reintento devuelve la operación existente en lugar de crear otro turno.

Adjunta capturas de pantalla u otra evidencia de imagen:

codex_submit_task(
  operation_type="start_chat",
  message="Analyze this screen.",
  input_items=[
    {"type": "localImage", "path": ".\\screens\\error.png", "detail": "low"},
    {"type": "image", "url": "https://example.com/screenshot.png", "detail": "high"}
  ]
)

Las entradas de imagen solo se aceptan para tipos de operación que inician un turno nuevo: start_chat, send_message, execute_plan y fork_thread con un mensaje inicial. MCP envía la ruta o URL a codex-app-server, pero el estado de la operación y los diagnósticos devuelven solo metadatos seguros como tipo, detalle, tamaño, extensión y hashes. El contenido binario de la imagen, las URLs sin procesar y las rutas completas de imágenes locales no se almacenan en cargas útiles de estado público.

Dirige un turno activo:

codex_submit_task(operation_type="steer_turn", thread_id=..., expected_turn_id=..., message=...)
  -> operationId
codex_get_operation_status(operationId)
  -> follows the target turn until completed / failed / interrupted

Usa steer_turn solo mientras el turno objetivo esté activo. Para un hilo completado, usa send_message en su lugar.

Ramifica un hilo:

codex_submit_task(operation_type="fork_thread", source_thread_id=...)
  -> operationId
codex_get_operation_status(operationId)
  -> completed, threadId=<forkedThreadId>

Inicia el trabajo en la rama de inmediato:

codex_submit_task(operation_type="fork_thread", source_thread_id=..., message=...)
  -> operationId
codex_get_operation_status(operationId)
  -> follows the first turn in the forked thread

Usa client_request_id para solicitudes de ramificación seguras ante reintentos. Sin él, cada llamada se trata como una nueva solicitud de ramificación. threadId en el estado de la operación es el hilo ramificado; el hilo de origen se informa en forkState.sourceThreadId.

Gestiona el ciclo de vida de los hilos:

codex_archive_thread(thread_id)
  -> completed
codex_unarchive_thread(thread_id)
  -> completed
codex_start_thread_compaction(thread_id)
  -> actionId
codex_get_thread_compaction_status(actionId)
  -> running / completed / unknown_after_app_server_exit

Archivar y desarchivar son acciones de auditoría alrededor de thread/archive y thread/unarchive del servidor de la aplicación. Se niegan a ejecutarse mientras el hilo tenga un turno activo o una interacción pendiente. La compactación usa su propio actionId ligero porque thread/compact/start es asíncrono. El thread/delete público se expone intencionalmente.

Solicita un informe final estructurado:

codex_submit_task(operation_type="start_chat", message=..., output_schema={...})
codex_approve_plan(workflowId, output_schema={...})
  -> operationId / executionOperationId
codex_get_operation_status(operationId)
codex_get_workflow_status(workflowId)
  -> finalReport.text + finalReport.structured

output_schema se pasa a turn/start del servidor de la aplicación y se rastrea mediante un hash de esquema en la salida de estado. Los esquemas de objetos deben usar la forma estricta requerida por Codex: establece additionalProperties en false. MCP almacena el mensaje final del asistente como texto legible y luego analiza la salida de objetos JSON en finalReport.structured cuando Codex devuelve JSON válido. El texto plano sigue funcionando y permanece disponible en finalReport.text.

MCP no extrae cadenas de pensamiento ocultas y no almacena cargas útiles de herramientas sin procesar ni salidas de comandos en los informes finales.

Dirige Plan Mode:

codex_start_plan_workflow
  -> workflowId
codex_get_workflow_status(workflowId)
  -> wait_plan / review_plan / execute_plan
codex_approve_plan(workflowId)
  -> executionOperationId
codex_get_workflow_status(workflowId)
  -> finalReport

Plan Mode tiene un piso de ejecución. La política de escritura pública predeterminada sigue siendo read-only y on-request, pero Plan Mode necesita un espacio de trabajo escribible en Windows. Si el llamante o el valor predeterminado del servidor se resuelve a read-only, MCP envía workspace-write a codex-app-server y devuelve requestedSandbox, effectiveSandbox y runtimePolicyAdjusted en el estado del flujo de trabajo y de la operación.

Refleja un objetivo de flujo de trabajo en Codex Desktop cuando el cliente tenga uno:

codex_start_plan_workflow(goal="Review the migration plan", goal_completion_action="clear")
codex_get_workflow_status(workflowId, refresh_live_goal=true)
  -> threadGoal.syncState + threadGoal.currentGoal

MCP escribe un objetivo de hilo solo cuando el cliente pasa goal. Los objetivos gestionados usan clear después de la finalización de forma predeterminada. Usa set_complete o leave cuando el objetivo deba permanecer visible después de que termine el flujo de trabajo. La consulta normal del flujo de trabajo es pasiva; usa refresh_live_goal=true solo cuando quieras que MCP llame a métodos de objetivo en vivo del servidor de la aplicación.

Ejecuta una revisión de código de Codex:

codex_start_review_workflow(thread_id=..., target_type="base_branch", base_branch="main")
  -> workflowId
codex_get_workflow_status(workflowId)
  -> wait_review / read_review_report

O deja que MCP cree un hilo de servicio para un checkout local:

codex_start_review_workflow(cwd=..., target_type="uncommitted_changes")
  -> workflowId
codex_get_workflow_status(workflowId)
  -> reviewThreadId + reviewTurnId + finalReport

Los flujos de trabajo de revisión no escriben archivos por sí mismos. Se ejecutan dentro del sandbox de Codex seleccionado y la política de aprobación. Usa client_request_id cuando un llamante pueda reintentar la solicitud de inicio después de un timeout de transporte.

Maneja aprobaciones y preguntas:

codex_list_pending_interactions
codex_answer_pending_interaction

Inicia diagnósticos con:

codex_get_runtime_capabilities
codex_health_summary
codex_collect_diagnostics
codex_analyze_issue
codex_repair_issue

Las acciones de reparación se predeterminan a dry_run=true.

Las herramientas de estado y diagnóstico también devuelven agentGuidance y agentGuidanceText cuando MCP detecta un bloqueador, estado fallido, ejecución obsoleta, interacción pendiente, prompt duplicado, problema de autenticación, límite de velocidad o bucle de recuperación inseguro. Los agentes deben seguir agentGuidance.instructions antes de decidir reintentar o detenerse. Si agentGuidance.loopGuard.allowed=false, detén la recuperación automática, recopila diagnósticos y pregunta a un humano. No crees un nuevo client_request_id después de un timeout a menos que la guía diga explícitamente que inicies un flujo de trabajo de reemplazo. Para un flujo de trabajo de Plan Mode roto, usa retry_workflow_with_runtime_policy. Crea un nuevo flujo de trabajo con el sandbox y la política de aprobación seleccionados, lo vincula al flujo de trabajo anterior mediante workflowRetryState, y no revive el turno terminal anterior.

codex_health_summary trata sobre la preparación actual de forma predeterminada. Las filas antiguas obsoletas o huérfanas se reportan en historicalDebt, pero no hacen que la orquestación reciente parezca rota cuando el worker, la cola y el servidor de aplicaciones están actualmente sanos. Usa una limpieza dirigida para esa deuda en lugar de bloquear trabajo nuevo.

Los payloads de estado ahora separan las señales de frescura:

• operationRowAgeSeconds: antigüedad de la fila de operación duradera;
• turnFreshness.lastProgressAgeSeconds: antigüedad del último evento de progreso del turno;
• workerFreshness.heartbeatAgeSeconds: antigüedad del heartbeat del worker;
• stalenessMeaning="operation_row_age" para el campo de compatibilidad stalenessSeconds.

Los payloads de estado públicos son seguros para agentes. El estado de operación y flujo de trabajo devuelve requestSummary en lugar del request crudo; contiene ids, política de ejecución, intención de programación, estado de los elementos de entrada, hash del esquema de salida, claves de recursos y hashes de texto. No incluye el prompt completo, las instrucciones completas, el título crudo, la URL/ruta de imagen cruda, los conteos exactos de tokens, la salida de comandos cruda ni las rutas privadas. Usa tu propio texto de tarea almacenado junto con requestSummary.*.sha256 para la correlación.

codex_get_queue_status solo recomienda wait_for_worker_slot cuando hay trabajo real en cola bloqueado por slots. Si hay turnos en ejecución pero queueSummary.queued == 0, la acción de cola es none.

Capacidades de ejecución

Usa codex_get_runtime_capabilities antes de la orquestación o después de reconectar. Inicia el servidor de aplicaciones propiedad de MCP si es necesario, llama a métodos de inventario breves de mejor esfuerzo y devuelve una instantánea en caché durante cinco minutos.

En el modo client, el proceso cliente no inicia su propio servidor de aplicaciones para el inventario en vivo. Devuelve una instantánea pasiva administrada por el worker cuando existe una. Con refresh=true, pone en cola un comando de worker y devuelve refreshCommandId; consulta codex_get_worker_command_status para leer el inventario actualizado.

La respuesta incluye:

• cantidad de modelos, modelo predeterminado, banderas ocultas, modalidades de entrada, esfuerzos de razonamiento y cantidad de niveles de servicio;
• perfiles de permisos por id y description;
• preparación del sandbox de Windows;
• capacidades del proveedor para búsqueda web, generación de imágenes y herramientas de namespace;
• conteos de hooks y skills sin comandos de hook crudos ni rutas absolutas de skills;
• estado de cuenta redactado, bandas de uso aproximadas y estado operativo de límite de tasa;
• métodos de esquema del servidor de aplicaciones compatibles con una fuente, versión y hash compactos.

El inventario de cuenta es seguro de mostrar a un orquestador. Reporta si Codex está autenticado, el tipo de cuenta y plan, si existe un correo electrónico, si los datos de uso están disponibles y si hay un problema visible de límite de tasa o créditos. No devuelve correo electrónico crudo, identificadores de cuenta, saldos de créditos, límites de gasto, gasto exacto usado, buckets de uso diario ni conteos exactos de tokens.

Si un método de inventario agota el tiempo de espera o falla, la herramienta aún devuelve ok=true con runtimeCapabilities.status="partial" y una advertencia legible por máquina en methodResults. Establece refresh=true para omitir la caché. codex_health_summary muestra un subconjunto pequeño de runtimeCapabilities de la última instantánea recopilada y no inicia el servidor de aplicaciones por sí solo. Pasa include_account=false cuando un cliente no necesita el estado de cuenta, uso o límite de tasa.

Diario de progreso

codex_get_turn_status y codex_get_operation_status incluyen un bloque compacto progressEvents de forma predeterminada. Captura el progreso visible por el servidor de aplicaciones, como deltas de texto del asistente, deltas de plan, texto de resumen de razonamiento, uso de tokens, redirecciones de modelo y advertencias.

El diario ayuda con la orquestación y la resolución de problemas. No extrae cadenas de pensamiento ocultas. Tampoco almacena payloads de herramientas crudos, salida de comandos ni diffs unificados completos de forma predeterminada. Los eventos de diff se reducen a conteos seguros, como la cantidad de líneas cambiadas y el tamaño del diff.

Usa progress_events=0 cuando un cliente quiera la forma de estado anterior, solo de mensajes. Usa progress_max_chars para limitar el texto de progreso devuelto.

El estado público devuelve el uso de tokens como bandas aproximadas, no conteos exactos de tokens. Las superficies de auditoría crudas pueden mantener payloads de eventos redactados para depuración, pero los orquestadores deben tratar tokenUsage.totalTokensBand y los campos de banda relacionados como el contrato público.

Superficie de herramientas

Herramientas de orquestación estables:

• codex_submit_task
• codex_get_operation_status
• codex_start_plan_workflow
• codex_start_review_workflow
• codex_get_workflow_status
• codex_approve_plan
• codex_list_pending_interactions
• codex_answer_pending_interaction
• codex_interrupt_turn
• codex_archive_thread
• codex_unarchive_thread
• codex_start_thread_compaction
• codex_get_thread_compaction_status
• codex_get_runtime_capabilities
• codex_health_summary
• codex_collect_diagnostics
• codex_repair_issue

Herramientas de compatibilidad y lectura:

• codex_start_chat
• codex_send_message
• codex_execute_plan
• codex_list_projects
• codex_list_project_chats
• codex_list_active_chats
• codex_search_chats
• codex_get_chat_status
• codex_get_chat
• codex_get_turn_status
• codex_restart_app_server
• codex_get_app_server_status
• codex_get_diagnostic_logs
• codex_analyze_issue

Los clientes nuevos deben usar operaciones y flujos de trabajo duraderos. Las herramientas de escritura de bajo nivel siguen disponibles para compatibilidad.

Las llamadas de lectura y diagnóstico están limitadas para bucles de agentes. codex_list_projects usa de forma predeterminada salida compacta en caché, codex_search_chats puede devolver timeBudgetExhausted=true en lugar de bloquearse en una actualización completa, y las lecturas de chat prefieren el historial de turnos y hooks rastreados antes del fallback de KB heredado. Los diagnósticos están limitados por alcance primero: scopedFindings impulsan la siguiente acción, mientras que backgroundFindings son contexto histórico.

Consulta docs/API_CONTRACT.md para esquemas, forma de error, grupos de herramientas estables y reglas de versionado.

Contrato de resultados

Cada herramienta declara un outputSchema y devuelve MCP structuredContent.

Éxito:

{"ok": true}

Error de dominio o herramienta:

{
  "ok": false,
  "error": {
    "code": "CODEX_ERROR_CODE",
    "message": "Human readable message",
    "details": {},
    "retryable": false
  }
}

Llama a codex_health_summary al inicio y al reconectar. El bloque version contiene serverName, serverVersion, contractVersion, toolSurfaceHash, guideHash, guideVersion, herramientas recomendadas de inicio/escritura y listas de herramientas estables/compatibilidad.

Los agentes pueden descubrir el contrato operativo sin leer este README. tools/list incluye:

• codexMcpGuide: guía compacta legible por máquina con capacidades, flujos, reglas globales y límites de ejecución;
• toolGroups: grupos ordenados de herramientas preferidas;
• recommendedStartupTool="codex_health_summary";
• recommendedPrimaryWriteTool="codex_submit_task".

Cada herramienta también tiene annotations.codexMcp con su rol, herramientas de seguimiento, regla de idempotencia, bandera de lectura pasiva y bandera mayStartTurn. Si una biblioteca cliente oculta los campos de nivel superior tools/list, llama a codex_get_agent_contract(detail="compact") o codex_get_agent_contract(detail="full", include_examples=true).

Configuración

La configuración puede provenir de variables de entorno o de un archivo JSON referenciado por CODEX_CONTROL_PLANE_MCP_CONFIG. El nombre antiguo OPENCLAW_CODEX_MCP_CONFIG todavía se acepta como respaldo.

Variables comunes:

• CODEX_HOME: directorio de inicio de Codex. Usa %USERPROFILE%\.codex de forma predeterminada.
• CODEX_PROJECTS_ROOT: raíz del proyecto escaneada por herramientas de catálogo y lectura.
• CODEX_ALLOWED_ROOTS: lista de permitidos de rutas separadas por punto y coma.
• CODEX_PROJECTS_REGISTRY: registro de proyectos JSON opcional.
• CODEX_MCP_STATE_DB: base de datos de estado MCP local.
• CODEX_CONTROL_PLANE_MCP_LOG: ruta del archivo de registro.
• CODEX_MCP_HOOK_HISTORY_ENABLED: habilita el historial de hooks SQLite. Usa true de forma predeterminada.
• CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS: límite de captura de hooks por mensaje.
• CODEX_KB_HISTORY_PROJECTS_ROOT: raíz de historial KB normalizado heredado opcional.
• CODEX_BINARY_PATH: ruta binaria de Codex explícita opcional.
• CODEX_MCP_DEFAULT_SANDBOX: sandbox de escritura predeterminado. Usa read-only de forma predeterminada.
• CODEX_MCP_DEFAULT_APPROVAL_POLICY: política de aprobación de escritura predeterminada. Usa on-request de forma predeterminada.
• CODEX_MCP_DEFAULT_MODEL: modelo de Codex predeterminado pasado al servidor de aplicaciones.
• CODEX_MCP_DEFAULT_EFFORT: nivel de esfuerzo predeterminado.
• CODEX_MCP_MAX_IMAGE_INPUT_ITEMS: máximo de adjuntos de imagen por codex_submit_task. Usa 10 de forma predeterminada.
• CODEX_MCP_MAX_IMAGE_INPUT_BYTES: máximo de bytes para una entrada de imagen local. Usa 20000000 de forma predeterminada.
• CODEX_MCP_TURN_STALL_TIMEOUT_SECONDS: umbral de inactividad para reportar turnos detenidos. Usa 900 de forma predeterminada.
• CODEX_MCP_STALLED_TURN_ACTION: política de turnos detenidos. Usa diagnose_only de forma predeterminada.
• CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS: tiempo de espera de interacción pendiente.
• DEEPSEEK_ENV_PATH: archivo .env opcional para configuraciones de resumen de DeepSeek.
• DEEPSEEK_SUMMARY_ENABLED: habilita o deshabilita llamadas de resumen remoto.

Los valores de política de escritura son predeterminados, no límites estrictos. Una llamada de cliente puede pasar sandbox o approval_policy explícitamente cuando un flujo de trabajo confiable necesita una postura diferente.

Plan Mode es la excepción al comportamiento de paso directo puro: read-only se trata como demasiado restrictivo para Plan Mode en Windows y se eleva a workspace-write. Los valores por llamada más permisivos, como workspace-write, se pasan directamente.

Ejemplo:

$env:CODEX_CONTROL_PLANE_MCP_CONFIG = Join-Path (Get-Location) "examples\codex-control-plane-mcp.config.json"
$env:CODEX_MCP_DEFAULT_SANDBOX = "read-only"
$env:CODEX_MCP_DEFAULT_APPROVAL_POLICY = "on-request"
py -m codex_control_plane_mcp.server

Consulta examples/codex-control-plane-mcp.config.json.

Modelo de confiabilidad

El servidor está diseñado para fallas comunes de orquestación local:

• Tiempo de espera del cliente MCP después del envío de tareas.
• Envío repetido con el mismo client_request_id.
• Envío repetido sin clave de idempotencia pero con el mismo prompt activo.
• Reinicio del proceso MCP entre el thread/start del servidor de aplicaciones y turn/start.
• Dos procesos MCP compartiendo una base de datos de estado SQLite.
• Salida del servidor de aplicaciones mientras un turno está activo.
• Aprobación pendiente vinculada a una generación antigua del servidor de aplicaciones.
• Brechas del servidor de aplicaciones o transcripción donde el historial de hooks aún capturó el prompt, texto visible del agente, respuesta final y estado de finalización.

Estos casos se almacenan en el estado de operación duradera, flujo de trabajo, turno, hook e interacción pendiente. Los estados terminales son explícitos. unknown_after_app_server_exit no se trata como éxito.

Seguridad

• Los prompts de smoke en vivo deben incluir MCP LIVE TEST / DO NOT MODIFY FILES.
• Las reparaciones usan dry_run=true de forma predeterminada.
• El reinicio forzado del servidor de aplicaciones puede marcar turnos activos como desconocidos o huérfanos. Prefiere restart_app_server_idle.

Verificaciones

Verificaciones locales rápidas:

python -m pytest -q
python -m compileall -q openclaw_codex_mcp codex_control_plane_mcp tests scripts
git diff --check

Smoke MCP solo de protocolo:

python .\scripts\mcp_live_smoke.py --scenario protocol

Smoke en vivo seguro con Codex Desktop/servidor de aplicaciones real:

python .\scripts\mcp_live_smoke.py --scenario safe-operation --cwd <PROJECT_ROOT>

Regresión en vivo completa:

python .\scripts\mcp_live_smoke.py --scenario full --safe-restart --cwd <PROJECT_ROOT>

Cliente MCP externo para desarrollo y pruebas en vivo largas:

python .\scripts\external_mcp_client.py daemon-start
python .\scripts\external_mcp_client.py daemon-restart-mcp --reason after_code_change
python .\scripts\external_mcp_client.py run-live-test --scenario full --archive-report

Usa el cliente externo cuando necesites probar el checkout actual como un cliente MCP real sin reiniciar Codex Desktop. Ejecuta un daemon independiente, mantiene su propio subproceso MCP stdio y puede reiniciar solo ese subproceso después de cambios de código. Los hallazgos de pruebas en vivo se escriben en corrective_action_plan.md; los informes anteriores se pueden archivar con --archive-report.

Consulta docs/EXTERNAL_MCP_CLIENT.md para los comandos del daemon y los escenarios en vivo disponibles.

Consulta docs/RELEASE_CHECKLIST.md. Para el posicionamiento de lanzamiento público, consulta docs/PUBLICATION_GUIDE.md.

Empaquetado

Compila localmente:

python -m pip install build
python -m build

La rueda incluye el servidor MCP, el instalador de hooks, el asistente de administración y el módulo de hooks de Codex incluido.

La ruta de instalación normal es:

pipx install codex-control-plane-mcp

o:

uvx codex-control-plane-mcp

Contribuciones

Lee CONTRIBUTING.md y SECURITY.md antes de abrir problemas que incluyan diagnósticos.

Buenos temas de GitHub para este repositorio:

python, mcp, mcp-server, model-context-protocol, openai-codex, codex, codex-desktop, agent-tools, ai-agents, developer-tools, automation, orchestration, agentic-workflows, long-running-tasks, openclaw, hermes, hermes-agent.