Codex Control Plane MCP

Plano de controle MCP durável para tarefas de longa duração do Codex Desktop.

GitHub
123

Documentação

MseeP.ai Security Assessment Badge

Codex Control Plane MCP

Português | Русский

CI PyPI Python License MCP

Codex Control Plane MCP

Automação confiável do Codex Desktop para tarefas longas.

codex-control-plane-mcp transforma o Codex Desktop e o codex-app-server em um trabalhador durável que um cliente MCP pode conduzir com segurança. Envie uma tarefa, receba um operationId ou workflowId imediatamente, faça polling até o trabalho terminar, aprove o Plan Mode quando necessário e, em seguida, leia o relatório final.

O servidor lida com as partes difíceis que wrappers finos geralmente deixam para o chamador: inicialização do servidor de aplicativos, criação de thread e turno, segurança contra repetição, proteção contra prompts duplicados, Plan Mode, aprovações, histórico local, diagnósticos e reparos.

OpenClaw e Hermes são clientes de primeira classe, mas o servidor é útil para qualquer orquestrador local que precise que o Codex Desktop realize trabalho de longa duração sem manter uma chamada MCP aberta por horas.

Versão resumida

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

Isso oferece um contrato simples:

  • sem chamadas MCP de várias horas;
  • sem turnos duplicados do Codex após uma repetição do cliente;
  • sem envio de tarefas às cegas (fire-and-forget);
  • um registro SQLite local de operações, fluxos de trabalho, turnos, hooks e diagnósticos.

Por que não chamar o Codex diretamente?

RecursoWrapper fino do CodexCodex Control Plane MCP
Tarefas de várias horasbloqueante / frágiloperação assíncrona durável
Recuperação de timeout do clientemanualclient_request_id seguro contra repetição
Proteção contra turnos duplicadosnãodetecção ativa de prompts
Fluxo de trabalho do Plan Modehumano / manualestado de workflow pesquisável
Aprovações e perguntasbloqueante / opacoAPI de interações pendentes
Recuperação após reinícioad hocestado de operação persistido
Diagnósticosapenas logsferramentas de saúde, diagnóstico e reparo

Para um guia de decisão mais detalhado, consulte docs/THIN_WRAPPERS.md.

Suporte atual

  • Alvo completo ao vivo: Windows com Codex Desktop e codex-app-server.
  • Linux e macOS: apenas verificações de protocolo por enquanto.
  • Local-first: não deve ser exposto como um serviço de rede público.

Modelo de segurança

Este é um plano de controle local-first para ambientes confiáveis do Codex Desktop.

Não o exponha como um serviço de rede sem autenticação.

Postura recomendada na primeira execução:

  • use read-only para repositórios não confiáveis;
  • use aprovação on-request ao testar novos fluxos de trabalho;
  • o Plan Mode nunca é executado com sandbox read-only. Se um chamador solicitar read-only, o MCP eleva esse turno para workspace-write e relata o ajuste na saída de status;
  • mantenha state/, logs/, .env e .codex/ privados.

O que ele faz

  • Fila assíncrona durável para operações de escrita do Codex.
  • Tratamento seguro contra repetição para client_request_id.
  • Detecção ativa de prompts duplicados.
  • Leases e heartbeats SQLite para processos MCP concorrentes.
  • Recuperação após reinício do MCP durante thread/start ou turn/start.
  • turn/steer durável para adicionar contexto a um turno ativo sem criar um segundo turno.
  • thread/fork durável para ramificar uma thread existente, com ou sem mensagem inicial.
  • Fluxos de trabalho do Plan Mode: iniciar plano, polling, aprovar, executar, ler relatório final.
  • Piso de execução do Plan Mode: workspace-write, com runtimePolicyAdjusted no status quando o MCP eleva uma solicitação de read-only.
  • Fluxos de revisão de código via app-server review/start, com polling e captura do relatório final.
  • Relatórios finais estruturados com output_schema.
  • Ferramentas de ciclo de vida de threads para arquivar, desarquivar e compactação pesquisável.
  • Sincronização de metas de fluxo de trabalho com metas de threads do Codex Desktop.
  • Entradas de imagem e imagem local para turnos iniciados via turn/start.
  • Aprovações e perguntas pendentes expostas como estado MCP pesquisável.
  • Interrupções de turno por threadId/turnId, operationId ou workflowId.
  • Inventário em tempo de execução para modelos, perfis de permissão, prontidão de sandbox, hooks, habilidades, recursos do provedor, status da conta, faixas de uso, estado de limites de taxa e métodos suportados do app-server.
  • Verificações de saúde, diagnósticos, análise de problemas e reparos em modo simulado (dry-run).
  • Histórico de hooks de propriedade do MCP no SQLite para busca, resumos e leituras de fallback.
  • Diário de progresso do app-server com redação para deltas, avisos, redirecionamentos de modelo e uso de tokens.
  • Erros MCP estruturados nos quais o código de automação pode ramificar.

Ações de escrita e controle passam por codex-app-server. O servidor não modifica bancos de dados SQLite internos do Codex nem arquivos de transcrição.

Instalação

Recomendado:

pipx install codex-control-plane-mcp

Ou execute diretamente:

uvx codex-control-plane-mcp

Do GitHub:

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

Para desenvolvimento 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

Configuração do cliente MCP

Após a instalação, gere uma configuração:

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

Entrada mínima de stdio:

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

Mais exemplos copiáveis para Claude Desktop, Cursor, clientes MCP estilo VS Code, checkouts locais, pacotes instalados e modo de trabalhador central estão disponíveis em examples/mcp-client-configs.md.

Execute o servidor MCP stdio:

codex-control-plane-mcp

Ou execute como módulo:

py -m codex_control_plane_mcp.server

Os comandos antigos openclaw-codex-mcp e openclaw-codex-mcp-hooks permanecem como aliases de compatibilidade por uma linha de versão.

Modo de trabalhador central

O modo padrão inline ainda é a configuração mais simples: um processo MCP pode enviar e executar operações. Para OpenClaw, Hermes ou qualquer configuração com vários clientes MCP, use um trabalhador central.

Forma local recomendada:

  • cada cliente MCP usa o mesmo CODEX_HOME e CODEX_MCP_STATE_DB;
  • entradas de gateway do OpenClaw são executadas com CODEX_MCP_EXECUTION_MODE=client;
  • um processo de longa duração codex-control-plane-mcp-worker possui codex-app-server, leases, slots de fila e locks de recursos;
  • os clientes chamam codex_submit_task e depois fazem polling de status. Eles não executam operações enfileiradas.

Comando do trabalhador:

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

Modo de observação segura, útil antes de alternar um gateway ao vivo:

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

Padrões de concorrência:

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 escrita no mesmo projeto, passe resource_keys para codex_submit_task. Sem eles, turnos de workspace-write e danger-full-access assumem um lock amplo de escrita no projeto. Com chaves disjuntas, o trabalhador pode executar vários turnos de escrita em paralelo.

Novas ferramentas de status:

  • codex_get_worker_status
  • codex_get_queue_status
  • codex_get_concurrency_status
  • codex_get_worker_command_status

codex_get_operation_status também retorna queueState, workerState, slotState e resourceLockState. Um turno em execução tem slotState.claimed=true e um slotClaim com o id do trabalhador, tipo de slot e horário de reivindicação. codex_get_queue_status separa trabalho enfileirado de operações de turno em execução, operações auxiliares, slots de turno ativos e conflitos de lock.

Quando um fluxo de trabalho está aguardando capacidade, codex_get_workflow_status espelha o estado da fila de operações aninhadas em workflowOperationQueueState. Use nextRecommendedAction="wait_for_worker_slot" para pressão de slots e nextRecommendedAction="wait_for_resource_lock" para conflitos de lock de escrita. Não crie outra operação para o mesmo trabalho enquanto qualquer uma dessas ações for retornada.

Primeira configuração

O helper administrativo pode gerar uma configuração de cliente mais completa, instalar hooks e executar um smoke de protocolo:

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

O comando imprime um bloco JSON que você pode copiar para uma configuração de cliente MCP. Ele não imprime segredos ou prompts privados.

Você também pode instalar apenas os hooks do 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

O instalador faz backup de ~/.codex/hooks.json, mescla seus handlers com seus hooks existentes, armazena stateDb como caminho absoluto e grava prompts, texto visível de progresso do agente, respostas finais e status de turno no banco de dados de estado MCP. Chamadas de ferramentas e saídas de comandos não são registradas por padrão. Reinicie o Codex após instalar ou alterar hooks.

Para turnos lançados via codex-app-server, o servidor espelha o prompt aceito, mensagens visíveis do assistente e status do turno no mesmo histórico SQLite. Isso mantém a busca e as leituras de status úteis mesmo quando o app-server não executa hooks do usuário.

Principais fluxos de trabalho

Envie uma tarefa durável:

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

Use o mesmo client_request_id quando um chamador tentar novamente após um timeout de transporte. A repetição retorna a operação existente em vez de criar outro turno.

Anexe screenshots ou outras evidências de imagem:

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"}
  ]
)

Entradas de imagem são aceitas apenas para tipos de operação que iniciam um novo turno: start_chat, send_message, execute_plan e fork_thread com uma mensagem inicial. O MCP envia o caminho ou URL para codex-app-server, mas o status da operação e os diagnósticos retornam apenas metadados seguros, como tipo, detalhe, tamanho, extensão e hashes. Conteúdo binário de imagem, URLs brutos e caminhos completos de imagem local não são armazenados em payloads de status públicos.

Direcione um turno ativo:

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

Use steer_turn apenas enquanto o turno alvo estiver ativo. Para uma thread concluída, use send_message.

Ramifique uma thread:

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

Inicie o trabalho na ramificação imediatamente:

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

Use client_request_id para solicitações de fork seguras contra repetição. Sem ele, cada chamada é tratada como uma nova solicitação de fork. threadId no status da operação é a thread ramificada; a thread de origem é relatada em forkState.sourceThreadId.

Gerencie o ciclo de vida da thread:

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

Arquivar e desarquivar são ações de auditoria em torno de thread/archive e thread/unarchive do app-server. Eles se recusam a executar enquanto a thread tiver um turno ativo ou uma interação pendente. A compactação usa seu próprio actionId leve, porque thread/compact/start é assíncrono. thread/delete público é intencionalmente não exposto.

Solicite um relatório final estruturado:

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 é passado para o turn/start do app-server e é rastreado por um hash de esquema na saída de status. Esquemas de objeto devem usar o formato estrito exigido pelo Codex: defina additionalProperties como false. O MCP armazena a mensagem final do assistente como texto legível e então analisa a saída JSON do objeto em finalReport.structured quando o Codex retorna JSON válido. Texto simples ainda funciona e permanece disponível em finalReport.text.

O MCP não extrai cadeias de pensamento ocultas e não armazena payloads brutos de ferramentas ou saídas de comandos em relatórios finais.

Conduza o 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

O Plan Mode tem um piso de execução. A política de escrita padrão pública ainda é read-only e on-request, mas o Plan Mode precisa de um espaço de trabalho gravável no Windows. Se o chamador ou o padrão do servidor resolver para read-only, o MCP envia workspace-write para codex-app-server e retorna requestedSandbox, effectiveSandbox e runtimePolicyAdjusted no workflow e na operação status.

Espelhe uma meta de workflow no Codex Desktop quando o cliente tiver uma:

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

O MCP grava uma meta de thread apenas quando o cliente passa goal. Metas gerenciadas usam clear após a conclusão por padrão. Use set_complete ou leave quando a meta deve permanecer visível após o fim do workflow. O polling normal do workflow é passivo; use refresh_live_goal=true apenas quando quiser que o MCP chame métodos de meta do app-server ao vivo.

Execute uma revisão de código do 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

Ou deixe o MCP criar uma thread de serviço para um checkout local:

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

Os fluxos de revisão não escrevem arquivos por conta própria. Eles são executados dentro da sandbox e política de aprovação do Codex selecionado. Use client_request_id quando um chamador puder tentar novamente a solicitação de início após um timeout de transporte.

Lide com aprovações e perguntas:

codex_list_pending_interactions
codex_answer_pending_interaction

Inicie diagnósticos com:

codex_get_runtime_capabilities
codex_health_summary
codex_collect_diagnostics
codex_analyze_issue
codex_repair_issue

As ações de reparo têm como padrão dry_run=true.

As ferramentas de status e diagnóstico também retornam agentGuidance e agentGuidanceText quando o MCP vê um bloqueador, estado com falha, execução obsoleta, interação pendente, prompt duplicado, problema de autenticação, limite de taxa ou loop de recuperação inseguro. Os agentes devem seguir agentGuidance.instructions antes de decidir tentar novamente ou parar. Se agentGuidance.loopGuard.allowed=false, pare a recuperação automática, colete diagnósticos e pergunte a um humano. Não crie um novo client_request_id após um timeout, a menos que a orientação diga explicitamente para iniciar um workflow substituto. Para um fluxo de trabalho do Plan Mode quebrado, use retry_workflow_with_runtime_policy. Ele cria um novo fluxo de trabalho com o sandbox e a política de aprovação selecionados, vincula-o ao fluxo de trabalho antigo por meio de workflowRetryState e não reativa o turno terminal antigo.

codex_health_summary trata da prontidão atual por padrão. Linhas antigas, obsoletas ou órfãs são relatadas em historicalDebt, mas elas não fazem a orquestração recente parecer quebrada quando o worker, a fila e o app-server estão atualmente saudáveis. Use uma limpeza direcionada para essa dívida em vez de bloquear novos trabalhos.

Os payloads de status agora separam sinais de atualização:

  • operationRowAgeSeconds: idade da linha da operação durável;
  • turnFreshness.lastProgressAgeSeconds: idade do último evento de progresso do turno;
  • workerFreshness.heartbeatAgeSeconds: idade do heartbeat do worker;
  • stalenessMeaning="operation_row_age" para o campo de compatibilidade stalenessSeconds.

Os payloads de status públicos são seguros para agentes. O status de operação e fluxo de trabalho retorna requestSummary em vez de request bruto; ele contém ids, política de runtime, intenção de agendamento, estado dos itens de entrada, hash do schema de saída, chaves de recursos e hashes de texto. Ele não inclui o prompt completo, instruções completas, título bruto, URL/caminho de imagem bruto, contagens exatas de tokens, saída bruta de comandos ou caminhos privados. Use seu próprio texto de tarefa armazenado mais requestSummary.*.sha256 para correlação.

codex_get_queue_status só recomenda wait_for_worker_slot quando há trabalho real na fila bloqueado por slots. Se houver turnos em execução, mas queueSummary.queued == 0, a ação de fila é none.

Capacidades de runtime

Use codex_get_runtime_capabilities antes da orquestração ou após a reconexão. Ele inicia o app-server de propriedade do MCP se necessário, chama métodos curtos de inventário de melhor esforço e retorna um snapshot em cache por cinco minutos.

No modo client, o processo cliente não inicia seu próprio app-server para inventário ao vivo. Ele retorna um snapshot passivo gerenciado pelo worker quando um existe. Com refresh=true, ele enfileira um comando do worker e retorna refreshCommandId; consulte codex_get_worker_command_status para ler o inventário atualizado.

A resposta inclui:

  • contagem de modelos, modelo padrão, flags ocultas, modalidades de entrada, esforços de raciocínio e contagem de níveis de serviço;
  • perfis de permissão por id e description;
  • prontidão do sandbox do Windows;
  • capacidades do provedor para busca na web, geração de imagens e ferramentas de namespace;
  • contagens de hooks e skills sem comandos de hook brutos ou caminhos absolutos de skills;
  • status de conta com informações redigidas, faixas de uso aproximadas e estado operacional de limite de taxa;
  • métodos de schema do app-server suportados com fonte, versão e hash compactos.

O inventário da conta é seguro para mostrar a um orquestrador. Ele informa se o Codex está autenticado, o tipo de conta e plano, se existe um e-mail, se os dados de uso estão disponíveis e se um problema de limite de taxa ou créditos está visível. Ele não retorna e-mail bruto, identificadores de conta, saldos de créditos, limites de gastos, gastos exatos usados, buckets de uso diário ou contagens exatas de tokens.

Se um método de inventário expirar ou falhar, a ferramenta ainda retorna ok=true com runtimeCapabilities.status="partial" e um aviso legível por máquina em methodResults. Defina refresh=true para ignorar o cache. codex_health_summary mostra um pequeno subconjunto de runtimeCapabilities do último snapshot coletado e não inicia o app-server por conta própria. Passe include_account=false quando um cliente não precisar de status de conta, uso ou limite de taxa.

Diário de progresso

codex_get_turn_status e codex_get_operation_status incluem um bloco compacto de progressEvents por padrão. Ele captura progresso visível ao app-server, como deltas de texto do assistente, deltas de plano, texto de resumo de raciocínio, uso de tokens, redirecionamentos de modelo e avisos.

O diário ajuda na orquestração e na solução de problemas. Ele não extrai cadeias de pensamento ocultas. Ele também não armazena payloads brutos de ferramentas, saída de comandos ou diffs unificados completos por padrão. Eventos de diff são reduzidos a contagens seguras, como contagem de linhas alteradas e tamanho do diff.

Use progress_events=0 quando um cliente quiser o formato de status mais antigo, somente com mensagens. Use progress_max_chars para limitar o texto de progresso retornado.

O status público retorna uso de tokens como faixas aproximadas, não contagens exatas de tokens. Superfícies de auditoria brutas podem manter payloads de eventos redigidos para depuração, mas os orquestradores devem tratar tokenUsage.totalTokensBand e campos de faixa relacionados como o contrato público.

Superfície de ferramentas

Ferramentas estáveis de orquestração:

  • 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

Ferramentas de compatibilidade e leitura:

  • 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

Clientes novos devem usar operações duráveis e fluxos de trabalho. Ferramentas de escrita de baixo nível permanecem disponíveis para compatibilidade.

Chamadas de leitura e diagnóstico são limitadas para loops de agentes. codex_list_projects usa por padrão saída compacta em cache, codex_search_chats pode retornar timeBudgetExhausted=true em vez de bloquear em uma atualização completa, e leituras de chat preferem histórico de turno rastreado e de hooks antes do fallback legado de KB. Os diagnósticos são priorizados por escopo: scopedFindings orientam a próxima ação, enquanto backgroundFindings são contexto histórico.

Consulte docs/API_CONTRACT.md para schemas, formato de erro, grupos de ferramentas estáveis e regras de versionamento.

Contrato de resultado

Toda ferramenta declara um outputSchema e retorna MCP structuredContent.

Sucesso:

{"ok": true}

Erro de domínio ou ferramenta:

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

Chame codex_health_summary na inicialização e na reconexão. O bloco version contém serverName, serverVersion, contractVersion, toolSurfaceHash, guideHash, guideVersion, ferramentas de inicialização/escrita recomendadas e listas de ferramentas estáveis/compatíveis.

Os agentes podem descobrir o contrato operacional sem ler este README. tools/list inclui:

  • codexMcpGuide: guia compacto legível por máquina com capacidades, fluxos, regras globais e limites de runtime;
  • toolGroups: grupos ordenados de ferramentas preferidas;
  • recommendedStartupTool="codex_health_summary";
  • recommendedPrimaryWriteTool="codex_submit_task".

Toda ferramenta também tem annotations.codexMcp com sua função, ferramentas de acompanhamento, regra de idempotência, flag de leitura passiva e flag mayStartTurn. Se uma biblioteca cliente ocultar campos tools/list de nível superior, chame codex_get_agent_contract(detail="compact") ou codex_get_agent_contract(detail="full", include_examples=true).

Configuração

A configuração pode vir de variáveis de ambiente ou de um arquivo JSON referenciado por CODEX_CONTROL_PLANE_MCP_CONFIG. O nome antigo OPENCLAW_CODEX_MCP_CONFIG ainda é aceito como fallback.

Variáveis comuns:

  • CODEX_HOME: diretório home do Codex. O padrão é %USERPROFILE%\.codex.
  • CODEX_PROJECTS_ROOT: raiz do projeto varrida por ferramentas de catálogo e leitura.
  • CODEX_ALLOWED_ROOTS: lista de permissão de caminhos separada por ponto e vírgula.
  • CODEX_PROJECTS_REGISTRY: registro de projetos JSON opcional.
  • CODEX_MCP_STATE_DB: banco de dados de estado local do MCP.
  • CODEX_CONTROL_PLANE_MCP_LOG: caminho do arquivo de log.
  • CODEX_MCP_HOOK_HISTORY_ENABLED: ativa o histórico de hooks SQLite. O padrão é true.
  • CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS: limite de captura de hooks por mensagem.
  • CODEX_KB_HISTORY_PROJECTS_ROOT: raiz opcional de histórico de KB legado normalizado.
  • CODEX_BINARY_PATH: caminho opcional e explícito do binário do Codex.
  • CODEX_MCP_DEFAULT_SANDBOX: sandbox de escrita padrão. O padrão é read-only.
  • CODEX_MCP_DEFAULT_APPROVAL_POLICY: política de aprovação de escrita padrão. O padrão é on-request.
  • CODEX_MCP_DEFAULT_MODEL: modelo padrão do Codex passado ao app-server.
  • CODEX_MCP_DEFAULT_EFFORT: nível de esforço padrão.
  • CODEX_MCP_MAX_IMAGE_INPUT_ITEMS: máximo de anexos de imagem por codex_submit_task. O padrão é 10.
  • CODEX_MCP_MAX_IMAGE_INPUT_BYTES: máximo de bytes para uma entrada de imagem local. O padrão é 20000000.
  • CODEX_MCP_TURN_STALL_TIMEOUT_SECONDS: limite de inatividade para relatório de turnos travados. O padrão é 900.
  • CODEX_MCP_STALLED_TURN_ACTION: política de turnos travados. O padrão é diagnose_only.
  • CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS: tempo limite de interação pendente.
  • DEEPSEEK_ENV_PATH: arquivo .env opcional para configurações de resumo do DeepSeek.
  • DEEPSEEK_SUMMARY_ENABLED: ativa ou desativa chamadas de resumo remotas.

Os valores da política de escrita são padrões, não limites rígidos. Uma chamada de cliente pode passar sandbox ou approval_policy explicitamente quando um fluxo de trabalho confiável precisar de uma postura diferente.

O Plan Mode é a exceção ao comportamento de passagem pura: read-only é tratado como restritivo demais para o Plan Mode no Windows e é elevado para workspace-write. Valores por chamada mais permissivos, como workspace-write, são passados diretamente.

Exemplo:

$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

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

Modelo de confiabilidade

O servidor foi criado para falhas comuns de orquestração local:

  • Timeout do cliente MCP após o envio da tarefa.
  • Envio repetido com o mesmo client_request_id.
  • Envio repetido sem chave de idempotência, mas com o mesmo prompt ativo.
  • Reinício do processo MCP entre o thread/start e o turn/start do app-server.
  • Dois processos MCP compartilhando um banco de dados de estado SQLite.
  • Saída do app-server enquanto um turno está ativo.
  • Aprovação pendente vinculada a uma geração antiga do app-server.
  • Lacunas no app-server ou no transcript em que o histórico de hooks ainda capturou o prompt, o texto visível do agente, a resposta final e o status de conclusão.

Esses casos são armazenados no estado de operação durável, fluxo de trabalho, turno, hook e interação pendente. Status terminais são explícitos. unknown_after_app_server_exit não é tratado como sucesso.

Segurança

  • Prompts de teste ao vivo devem incluir MCP LIVE TEST / DO NOT MODIFY FILES.
  • Reparos usam dry_run=true por padrão.
  • Reinício forçado do app-server pode marcar turnos ativos como desconhecidos ou órfãos. Prefira restart_app_server_idle.

Verificações

Verificações locais rápidas:

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

Smoke de MCP somente de protocolo:

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

Smoke ao vivo seguro com Codex Desktop/app-server real:

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

Regressão ao vivo completa:

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

Cliente MCP externo para desenvolvimento e testes longos ao vivo:

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

Use o cliente externo quando precisar testar o checkout atual como um cliente MCP real sem reiniciar o Codex Desktop. Ele executa um daemon independente, mantém seu próprio subprocesso stdio MCP e pode reiniciar apenas esse subprocesso após mudanças de código. Os resultados de testes ao vivo são gravados em corrective_action_plan.md; relatórios anteriores podem ser arquivados com --archive-report.

Consulte docs/EXTERNAL_MCP_CLIENT.md para os comandos do daemon e os cenários ao vivo disponíveis.

Consulte docs/RELEASE_CHECKLIST.md. Para posicionamento de lançamento público, consulte docs/PUBLICATION_GUIDE.md.

Empacotamento

Compile localmente:

python -m pip install build
python -m build

O wheel inclui o servidor MCP, o instalador de hooks, o helper administrativo e o módulo de hook do Codex incluído.

O caminho normal de instalação é:

pipx install codex-control-plane-mcp

ou:

uvx codex-control-plane-mcp

Contribuindo

Leia CONTRIBUTING.md e SECURITY.md antes de abrir issues que incluam diagnósticos.

Bons tópicos do GitHub para este repositório:

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.