Codex harness
Runtime do mecanismo do Codex
Esta página documenta o contrato de runtime para turnos do harness do Codex. Para configuração e roteamento, comece com harness do Codex. Para campos de configuração, consulte referência do harness do Codex.
Visão geral
O modo Codex não é PI com uma chamada de modelo diferente por baixo. O Codex controla mais do loop nativo do modelo, e o OpenClaw adapta suas superfícies de plugin, ferramenta, sessão e diagnóstico em torno desse limite.
O OpenClaw ainda controla roteamento de canais, arquivos de sessão, entrega de mensagens visíveis, ferramentas dinâmicas do OpenClaw, aprovações, entrega de mídia e um espelho de transcrição. O Codex controla a thread nativa canônica, o loop nativo do modelo, a continuação nativa de ferramentas e a compactação nativa.
Vinculações de threads e mudanças de modelo
Quando uma sessão do OpenClaw é anexada a uma thread existente do Codex, o próximo turno
envia novamente ao app-server o modelo OpenAI selecionado no momento, a política de aprovação,
o sandbox e a camada de serviço. Mudar de openai/gpt-5.5 para
openai/gpt-5.2 mantém a vinculação da thread, mas pede ao Codex que continue com o
modelo recém-selecionado.
Respostas visíveis e heartbeats
Quando um turno de chat de origem passa pelo harness do Codex, as respostas visíveis usam por padrão
a ferramenta message do OpenClaw se a implantação não tiver configurado explicitamente
messages.visibleReplies. O agente ainda pode finalizar seu turno do Codex privadamente;
ele só publica no canal quando chama message(action="send"). Defina
messages.visibleReplies: "automatic" para manter as respostas finais de chats diretos no
caminho legado de entrega automática.
Turnos de heartbeat do Codex também recebem heartbeat_respond no catálogo pesquisável de
ferramentas do OpenClaw por padrão, para que o agente possa registrar se o despertar deve permanecer
silencioso ou notificar, sem codificar esse fluxo de controle no texto final.
A orientação de iniciativa específica de heartbeat é enviada como uma instrução de desenvolvedor do modo de colaboração do Codex no próprio turno de heartbeat. Turnos comuns de chat restauram o modo Padrão do Codex em vez de carregar a filosofia de heartbeat em seu prompt de runtime normal.
Limites de hooks
O harness do Codex tem três camadas de hooks:
| Camada | Proprietário | Finalidade |
|---|---|---|
| Hooks de plugins do OpenClaw | OpenClaw | Compatibilidade de produto/plugin entre os harnesses PI e Codex. |
| Middleware de extensão do app-server do Codex | Plugins incluídos do OpenClaw | Comportamento de adaptador por turno em torno das ferramentas dinâmicas do OpenClaw. |
| Hooks nativos do Codex | Codex | Ciclo de vida de baixo nível do Codex e política de ferramentas nativas da configuração do Codex. |
O OpenClaw não usa arquivos hooks.json de projeto ou globais do Codex para rotear
comportamento de plugins do OpenClaw. Para a ponte compatível de ferramentas nativas e permissões,
o OpenClaw injeta configuração do Codex por thread para PreToolUse, PostToolUse,
PermissionRequest e Stop.
Quando as aprovações do app-server do Codex estão habilitadas, ou seja, approvalPolicy não é
"never", a configuração nativa padrão de hook injetado omite PermissionRequest, para que
o revisor do app-server do Codex e a ponte de aprovação do OpenClaw tratem escalonamentos reais
após a revisão. Operadores podem adicionar explicitamente permission_request a
nativeHookRelay.events quando precisarem do relay de compatibilidade.
Outros hooks do Codex, como SessionStart e UserPromptSubmit, continuam sendo controles
no nível do Codex. Eles não são expostos como hooks de plugins do OpenClaw no contrato v1.
Para ferramentas dinâmicas do OpenClaw, o OpenClaw executa a ferramenta depois que o Codex solicita a chamada, então o OpenClaw aciona o comportamento de plugin e middleware que controla no adaptador do harness. Para ferramentas nativas do Codex, o Codex controla o registro canônico da ferramenta. O OpenClaw pode espelhar eventos selecionados, mas não pode reescrever a thread nativa do Codex a menos que o Codex exponha essa operação por meio do app-server ou de callbacks de hooks nativos.
As notificações de itens do app-server do Codex também fornecem observações assíncronas
after_tool_call para conclusões de ferramentas nativas que ainda não são cobertas pelo
relay nativo PostToolUse. Essas observações servem apenas para telemetria e compatibilidade
de plugins; elas não podem bloquear, atrasar ou alterar a chamada nativa da ferramenta.
Projeções de compactação e ciclo de vida de LLM vêm das notificações do app-server do Codex
e do estado do adaptador do OpenClaw, não de comandos de hooks nativos do Codex.
Os eventos before_compaction, after_compaction, llm_input e
llm_output do OpenClaw são observações no nível do adaptador, não capturas byte a byte
da requisição interna do Codex ou dos payloads de compactação.
As notificações hook/started e hook/completed nativas do Codex no app-server são
projetadas como eventos de agente codex_app_server.hook para trajetória e depuração.
Elas não invocam hooks de plugins do OpenClaw.
Contrato de suporte v1
Com suporte no runtime v1 do Codex:
| Superfície | Suporte | Motivo |
|---|---|---|
| Loop do modelo OpenAI via Codex | Suportado | O app-server do Codex controla o turno OpenAI, a retomada da thread nativa e a continuação nativa de ferramentas. |
| Roteamento e entrega de canais do OpenClaw | Suportado | Telegram, Discord, Slack, WhatsApp, iMessage e outros canais ficam fora do runtime do modelo. |
| Ferramentas dinâmicas do OpenClaw | Suportado | O Codex pede que o OpenClaw execute essas ferramentas, então o OpenClaw permanece no caminho de execução. |
| Plugins de prompt e contexto | Suportado | O OpenClaw constrói sobreposições de prompt e projeta contexto no turno do Codex antes de iniciar ou retomar a thread. |
| Ciclo de vida do mecanismo de contexto | Suportado | Montagem, ingestão, manutenção pós-turno e coordenação de compactação do mecanismo de contexto são executadas para turnos do Codex. |
| Hooks de ferramentas dinâmicas | Suportado | before_tool_call, after_tool_call e middleware de resultado de ferramenta são executados em torno de ferramentas dinâmicas controladas pelo OpenClaw. |
| Hooks de ciclo de vida | Suportado como observações do adaptador | llm_input, llm_output, agent_end, before_compaction e after_compaction disparam com payloads honestos do modo Codex. |
| Gate de revisão de resposta final | Suportado por meio do relay de hook nativo | O Stop do Codex é retransmitido para before_agent_finalize; revise pede ao Codex mais uma passagem de modelo antes da finalização. |
| Bloqueio ou observação de shell, patch e MCP nativos | Suportado por meio do relay de hook nativo | PreToolUse e PostToolUse do Codex são retransmitidos para superfícies nativas de ferramentas comprometidas, incluindo payloads MCP no app-server do Codex 0.125.0 ou mais recente. O bloqueio é suportado; a reescrita de argumentos não. |
| Política nativa de permissões | Suportada por aprovações do app-server do Codex e relay de hook nativo de compatibilidade | Solicitações de aprovação do app-server do Codex são roteadas pelo OpenClaw após a revisão do Codex. O relay do hook nativo PermissionRequest é opt-in para modos de aprovação nativos porque o Codex o emite antes da revisão do guardião. |
| Captura de trajetória do app-server | Suportado | O OpenClaw registra a requisição que enviou ao app-server e as notificações do app-server que recebe. |
Sem suporte no runtime v1 do Codex:
| Superfície | Limite v1 | Caminho futuro |
|---|---|---|
| Mutação de argumentos de ferramentas nativas | Hooks nativos pré-ferramenta do Codex podem bloquear, mas o OpenClaw não reescreve argumentos de ferramentas nativas do Codex. | Requer suporte de hook/esquema do Codex para entrada substituta de ferramenta. |
| Histórico editável de transcrição nativa do Codex | O Codex controla o histórico canônico da thread nativa. O OpenClaw controla um espelho e pode projetar contexto futuro, mas não deve alterar internals sem suporte. | Adicionar APIs explícitas do app-server do Codex se cirurgia de thread nativa for necessária. |
tool_result_persist para registros de ferramentas nativas do Codex |
Esse hook transforma escritas de transcrição controladas pelo OpenClaw, não registros de ferramentas nativas do Codex. | Poderia espelhar registros transformados, mas a reescrita canônica precisa de suporte do Codex. |
| Metadados ricos de compactação nativa | O OpenClaw observa o início e a conclusão da compactação, mas não recebe uma lista estável de itens mantidos/removidos, delta de tokens ou payload de resumo. | Precisa de eventos de compactação mais ricos do Codex. |
| Intervenção na compactação | Os hooks atuais de compactação do OpenClaw são de nível de notificação no modo Codex. | Adicionar hooks pré/pós-compactação do Codex se plugins precisarem vetar ou reescrever a compactação nativa. |
| Captura byte a byte da requisição da API do modelo | O OpenClaw pode capturar requisições e notificações do app-server, mas o core do Codex constrói internamente a requisição final da API OpenAI. | Precisa de um evento de rastreamento de requisição de modelo do Codex ou API de depuração. |
Permissões nativas e elicitações MCP
Para PermissionRequest, o OpenClaw só retorna decisões explícitas de permissão ou negação
quando a política decide. Um resultado sem decisão não é uma permissão. O Codex o trata como
nenhuma decisão de hook e segue para seu próprio caminho de guardião ou aprovação do usuário.
Os modos de aprovação do app-server do Codex omitem esse hook nativo por padrão. Esse comportamento
se aplica quando permission_request é incluído explicitamente em
nativeHookRelay.events ou quando um runtime de compatibilidade o instala.
Quando um operador escolhe allow-always para uma solicitação de permissão nativa do Codex,
o OpenClaw lembra essa impressão digital exata de provedor/sessão/entrada da ferramenta/cwd por uma
janela de sessão limitada. A decisão lembrada é intencionalmente apenas de correspondência exata:
um comando, argumentos, payload da ferramenta ou cwd alterado cria uma nova
aprovação.
As elicitações de aprovação de ferramenta MCP do Codex são roteadas pelo fluxo de
aprovação de Plugin do OpenClaw quando o Codex marca _meta.codex_approval_kind como
"mcp_tool_call". Os prompts request_user_input do Codex são enviados de volta ao
chat de origem, e a próxima mensagem de acompanhamento enfileirada responde a essa solicitação
do servidor nativo em vez de ser direcionada como contexto extra. Outras solicitações de elicitação
MCP falham fechadas.
Direcionamento de fila
O direcionamento de fila em execução ativa é mapeado para turn/steer do app-server do Codex. Com o
padrão messages.queue.mode: "steer", o OpenClaw agrupa mensagens de chat enfileiradas
durante a janela de silêncio configurada e as envia como uma solicitação turn/steer em
ordem de chegada. O modo legado queue envia solicitações turn/steer separadas.
Turnos de revisão e Compaction manual do Codex podem rejeitar o direcionamento no mesmo turno. Nesse caso, o OpenClaw usa a fila de acompanhamento quando o modo selecionado permite fallback. Veja Fila de direcionamento.
Upload de feedback do Codex
Quando /diagnostics [note] é aprovado para uma sessão usando o harness nativo do Codex,
o OpenClaw também chama feedback/upload do app-server do Codex para threads relevantes
do Codex. O upload solicita que o app-server inclua logs para cada thread listada
e subthreads do Codex geradas quando disponíveis.
O upload passa pelo caminho normal de feedback do Codex para os servidores da OpenAI. Se o feedback
do Codex estiver desativado nesse app-server, o comando retorna o erro do app-server.
A resposta de diagnósticos concluída lista os canais, ids de sessão do OpenClaw,
ids de thread do Codex e comandos locais codex resume <thread-id> para as threads
que foram enviadas.
Se você negar ou ignorar a aprovação, o OpenClaw não imprime esses ids do Codex e não envia feedback do Codex. O upload não substitui a exportação local de diagnósticos do Gateway. Veja Exportação de diagnósticos para o comportamento de aprovação, privacidade, pacote local e chat em grupo.
Use /codex diagnostics [note] somente quando você quiser especificamente o upload de
feedback do Codex para a thread anexada atualmente sem o pacote completo de diagnósticos do
Gateway.
Compaction e espelho de transcrição
Quando o modelo selecionado usa o harness do Codex, a Compaction de thread nativa é
delegada ao app-server do Codex. O OpenClaw mantém um espelho de transcrição para histórico
de canal, busca, /new, /reset e futuras trocas de modelo ou harness.
O espelho inclui o prompt do usuário, o texto final do assistente e registros leves de raciocínio ou plano do Codex quando o app-server os emite. Hoje, o OpenClaw registra apenas sinais nativos de início e conclusão de Compaction. Ele ainda não expõe um resumo de Compaction legível por humanos ou uma lista auditável de quais entradas o Codex manteve após a Compaction.
Como o Codex possui a thread nativa canônica, tool_result_persist atualmente não
reescreve registros de resultado de ferramenta nativos do Codex. Ele só se aplica quando
o OpenClaw está gravando um resultado de ferramenta de transcrição de sessão pertencente ao OpenClaw.
Mídia e entrega
O OpenClaw continua responsável pela entrega de mídia e pela seleção de provedor de mídia. Imagem,
vídeo, música, PDF, TTS e entendimento de mídia usam configurações correspondentes de provedor/modelo
como agents.defaults.imageGenerationModel, videoGenerationModel,
pdfModel e messages.tts.
Texto, imagens, vídeo, música, TTS, aprovações e saída de ferramenta de mensagem continuam
pelo caminho normal de entrega do OpenClaw. A geração de mídia não exige PI.
Quando o Codex emite um item nativo de geração de imagem com um savedPath, o OpenClaw
encaminha exatamente esse arquivo pelo caminho normal de mídia de resposta, mesmo que o turno do Codex
não tenha texto de assistente.