Plugins do ambiente de execução do agente

Um harness de agente é o executor de baixo nível de um turno preparado de agente do OpenClaw. Ele não é um provedor de modelos, nem um canal, nem um registro de ferramentas. Para o modelo mental voltado ao usuário, consulte Runtimes de agentes.

Use esta superfície somente para plugins nativos incluídos ou confiáveis. O contrato ainda é experimental porque os tipos de parâmetros espelham intencionalmente o executor incorporado atual.

Quando usar um harness

Registre um harness de agente quando uma família de modelos tiver seu próprio runtime de sessão nativo e o transporte normal de provedores do OpenClaw for a abstração inadequada:

• um servidor nativo de agente de programação que gerencia threads e Compaction
• uma CLI ou um daemon local que precisa transmitir eventos nativos de plano/raciocínio/ferramentas
• um runtime de modelo que precisa de seu próprio ID de retomada além da transcrição da sessão do OpenClaw

Não registre um harness apenas para adicionar uma nova API de LLM. Para APIs de modelo HTTP ou WebSocket normais, crie um plugin de provedor.

O que o núcleo ainda gerencia

Antes que um harness seja selecionado, o OpenClaw já terá resolvido:

• provedor e modelo
• estado de autenticação do runtime, a menos que o harness declare que gerencia a inicialização da autenticação
• nível de raciocínio e orçamento de contexto
• o arquivo de transcrição/sessão do OpenClaw
• espaço de trabalho, sandbox e política de ferramentas
• callbacks de resposta do canal e callbacks de streaming
• política de fallback e troca de modelo em tempo real

Um harness executa uma tentativa preparada; ele não escolhe provedores, substitui a entrega do canal nem troca modelos silenciosamente.

Inicialização de autenticação gerenciada pelo harness

Por padrão, o núcleo resolve as credenciais do provedor antes de chamar um harness. Um harness confiável que possa se autenticar por meio de seu próprio runtime nativo pode definir authBootstrap: "harness" em seu registro estático de AgentHarness. Nesse caso, o núcleo ignora sua inicialização genérica das credenciais do provedor e a falha por credenciais ausentes em todas as tentativas assumidas por esse harness.

O núcleo ainda encaminha um perfil de autenticação compatível, explicitamente selecionado ou ordenado, do OpenClaw e seu armazenamento com escopo quando existirem. O harness deve resolver esse perfil ou suas credenciais nativas antes de emitir solicitações ao modelo, manter os segredos restritos à tentativa e apresentar falhas de autenticação que indiquem ações corretivas. Não defina esse recurso em um harness que gerencia a autenticação apenas em alguns casos.

Artefatos verificados do runtime de configuração

Um harness local que possa fornecer inferência para a configuração da primeira execução deve atestar a implementação que concluiu a sondagem. Quando params.captureRuntimeArtifact for true, retorne um result.runtimeArtifact opaco com um ID estável e uma impressão digital do conteúdo. Registre um recurso runtimeArtifact.validate(...) correspondente que verifique novamente esse vínculo sem carregar outro harness nem examinar plugins não relacionados.

As continuações verificadas do Crestodian também passam params.expectedRuntimeArtifact. O harness deve compará-lo com o processo nativo exato que adquiriu e falhar antes de iniciar ou retomar uma thread nativa se forem diferentes. Turnos comuns de agentes omitem ambos os campos, portanto o hashing de conteúdo fica fora do caminho crítico normal das solicitações. Harnesses remotos/WebSocket precisam de um contrato de atestação do servidor antes de poderem participar; uma string de versão, por si só, não é uma identidade de artefato.

A tentativa preparada também inclui params.runtimePlan, um pacote de políticas gerenciado pelo OpenClaw para decisões de runtime que devem permanecer compartilhadas entre o OpenClaw e harnesses nativos:

• runtimePlan.tools.normalize(...) e runtimePlan.tools.logDiagnostics(...) para a política de esquema de ferramentas ciente do provedor
• runtimePlan.transcript.resolvePolicy(...) para a política de sanitização da transcrição e reparo de chamadas de ferramentas
• runtimePlan.delivery.isSilentPayload(...) para a supressão compartilhada de entrega de NO_REPLY e mídia
• runtimePlan.outcome.classifyRunResult(...) para a classificação do fallback de modelo
• runtimePlan.observability para metadados resolvidos de provedor/modelo/harness

Os harnesses podem usar o plano para decisões que precisem corresponder ao comportamento do OpenClaw, mas devem tratá-lo como estado da tentativa gerenciado pelo host: não o modifique nem o use para trocar provedores/modelos dentro de um turno.

Contrato de transporte de solicitações

supports(ctx) recebe o transporte de modelo resolvido em ctx.modelProvider. Dois fatos sem segredos e gerenciados pelo provedor descrevem a rota selecionada:

• runtimePolicy.compatibleIds lista os IDs de runtime que o provedor declara como compatíveis com essa rota específica. A ausência de uma política significa que o provedor não declarou compatibilidade no nível da rota; isso não é permissão para presumir suporte.
• requestTransportOverrides: "none" significa que nenhuma substituição de solicitação criada pelo autor para o provedor/modelo precisa ser reproduzida. "present" significa que existem cabeçalhos, transporte de autenticação, proxy, TLS, comportamento de serviço local ou rede privada, ou parâmetros de solicitação definidos pelo autor. O fato não expõe esses valores.

Retorne { supported: false, reason } quando o harness não puder reproduzir o transporte preparado. Não deduza o suporte lendo a configuração bruta após a seleção. Quando a preparação da autenticação produzir várias rotas de nova tentativa, um único harness deverá oferecer suporte a todas elas antes do despacho. A seleção implícita usa o OpenClaw se nenhum plugin puder gerenciar o conjunto completo; uma seleção de plugin explícita ou persistida falha de maneira fechada.

Registrar um harness

Importação: openclaw/plugin-sdk/agent-harness

  const myHarness: AgentHarness = {  id: "my-harness",  label: "Meu harness de agente nativo",   supports(ctx) {    const routeSupportsHarness =      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest      ? { supported: true, priority: 100 }      : { supported: false, reason: "a rota efetiva não é compatível com o harness" };  },   async runAttempt(params) {    // Inicie ou retome sua thread nativa.    // Use params.prompt, params.tools, params.images, params.onPartialReply,    // params.onAgentEvent e os outros campos preparados da tentativa.    return await runMyNativeTurn(params);  },}; export default definePluginEntry({  id: "my-native-agent",  name: "Meu agente nativo",  description: "Executa modelos selecionados por meio de um daemon de agente nativo.",  register(api) {    api.registerAgentHarness(myHarness);  },});

authBootstrap está intencionalmente ausente deste exemplo genérico. Adicione authBootstrap: "harness" somente quando o harness atender ao contrato acima.

Execução delegada

O proprietário de um harness pode definir delegatedExecutionPluginIds como os ids de plugins confiáveis que precisam executar uma sessão existente com modelo bloqueado, como um transporte de voz que continua uma conversa apoiada pelo Codex. Isso é um consentimento estático do proprietário, não uma lista de permissões do núcleo. Mantenha o escopo restrito.

Os delegados recebem apenas admissão de trabalho e execução incorporada. O OpenClaw exige a chave de sessão armazenada, o caminho do armazenamento e o id da sessão exatos; modelSelectionLocked: true; e valores correspondentes de agentHarnessId e agentHarnessRuntimeOverride. A execução é então delimitada pelo proprietário do harness. Criação, aplicação de patches, redefinição, exclusão e arquivamento de sessões, bem como mutações no Gateway, continuam restritos ao proprietário.

Política de seleção

O OpenClaw escolhe um harness após a resolução de provedor/modelo:

1. A política de runtime no escopo do modelo tem precedência.
2. A política de runtime no escopo do provedor vem em seguida.
3. auto consulta os harnesses registrados para saber se eles oferecem suporte à rota efetiva resolvida. Prefixos de provedor/modelo, por si só, nunca selecionam um harness.
4. Se nenhum harness registrado corresponder, o OpenClaw usará seu runtime incorporado.

Falhas de harnesses de plugins são apresentadas como falhas de execução. No modo auto, o fallback incorporado só se aplica quando nenhum harness de plugin registrado oferece suporte ao provedor/modelo resolvido. Depois que um harness de plugin reivindica uma execução, o OpenClaw não repete a mesma interação em outro runtime, pois isso pode alterar a semântica de autenticação/runtime ou duplicar efeitos colaterais.

A política de runtime configurada continua sendo a autoridade quanto ao runtime desejado. Um agentHarnessId de sessão persistido mantém a propriedade de sua transcrição nativa enquanto a preparação de rota/autenticação ainda está pendente. Nenhum dos dois torna compatível uma rota incompatível: assim que os fatos preparados existirem, o harness selecionado ou fixado deverá oferecer suporte a eles, ou a execução falhará de forma fechada. /status mostra o runtime efetivo selecionado com base na política, na propriedade persistida e no suporte à rota. O status preparado é explícito: a ausência de runtimePolicy permanece não declarada, em vez de ser inferida a partir de quaisquer campos de transporte que estejam presentes. Quando a autenticação de propriedade do harness deixa várias rotas físicas sem resolução, o fato de suporte preparado é a interseção dos ids de runtime compatíveis delas e informa substituições de solicitação se algum candidato as tiver. Portanto, um candidato não declarado torna vazia a compatibilidade nativa; preparedAuth.source: "harness" indica um proprietário da autenticação, não permissão para inferir suporte à rota.

Se o harness selecionado for inesperado, habilite o registro de depuração agents/harness e inspecione o registro estruturado agent harness selected do gateway: ele inclui o id do harness selecionado, o motivo da seleção, a política de runtime/fallback e, no modo auto, o resultado de suporte de cada candidato de plugin.

O plugin Codex incluído registra codex como seu id de harness. O núcleo trata esse valor como um id comum de harness de plugin; aliases específicos do Codex devem ficar no plugin ou na configuração do operador, não no seletor de runtime compartilhado.

Pareamento de provedor e harness

A maioria dos harnesses também deve registrar um provedor. O provedor torna as referências de modelo, o status de autenticação, os metadados do modelo e a seleção de /model visíveis para o restante do OpenClaw. O harness então reivindica esse provedor em supports(...).

O plugin Codex incluído segue este padrão:

• referências de modelo preferenciais para o usuário: openai/gpt-5.6-sol
• referências de compatibilidade: referências legadas codex/gpt-* continuam aceitas, mas novas configurações não devem usá-las como referências normais de provedor/modelo
• id do harness: codex
• autenticação: disponibilidade sintética do provedor, pois o harness Codex é responsável pelo login/sessão nativos do Codex
• solicitação ao servidor do aplicativo: o OpenClaw envia somente o id do modelo ao Codex e permite que o harness se comunique com o protocolo nativo do servidor do aplicativo

O plugin Codex é aditivo. Com a política de runtime não definida ou como auto, a OpenAI pode selecionar o Codex somente quando o contrato de rota pertencente ao provedor declarar compatibilidade com codex: uma rota oficial exata de HTTPS para Platform Responses ou ChatGPT Responses, sem substituição de solicitação criada pelo autor. O prefixo openai/*, por si só, nunca seleciona o Codex. Endpoints personalizados, adaptadores de Completions e comportamentos de solicitação criados pelo autor permanecem no OpenClaw. Endpoints HTTP oficiais sem criptografia são rejeitados. Referências codex/gpt-* mais antigas continuam sendo entradas de compatibilidade. Consulte runtime implícito de agente da OpenAI.

Para configuração pelo operador, exemplos de prefixos de modelo e configurações exclusivas do Codex, consulte Harness do Codex.

O plugin Codex exige a versão mínima do servidor do aplicativo documentada em Harness do Codex. Ele verifica o handshake de inicialização e bloqueia servidores mais antigos ou sem versão, de modo que o OpenClaw seja executado somente na superfície do protocolo que foi testada.

Middleware de resultados de ferramentas

Plugins incluídos e plugins instalados explicitamente habilitados com contratos de manifesto correspondentes podem anexar middleware de resultados de ferramentas independente de runtime por meio de api.registerAgentToolResultMiddleware(...) quando seu manifesto declarar os ids de runtime de destino em contracts.agentToolResultMiddleware. Esse ponto de integração confiável destina-se a transformações assíncronas de resultados de ferramentas que precisam ser executadas antes que o OpenClaw ou o Codex forneçam novamente a saída da ferramenta ao modelo.

Plugins incluídos legados ainda podem usar api.registerCodexAppServerExtensionFactory(...) para middleware exclusivo do servidor do aplicativo Codex, mas novas transformações de resultados devem usar a API independente de runtime. O hook api.registerEmbeddedExtensionFactory(...), exclusivo do executor incorporado, foi removido; transformações incorporadas de resultados de ferramentas devem usar middleware independente de runtime.

Classificação do resultado do terminal

Harnesses nativos que controlam sua própria projeção de protocolo podem usar classifyAgentHarnessTerminalOutcome(...) de openclaw/plugin-sdk/agent-harness-runtime quando um turno concluído não produzir texto visível do assistente. O helper retorna empty, reasoning-only ou planning-only para que a política de fallback do OpenClaw possa decidir se deve tentar novamente com um modelo diferente. planning-only exige o campo planText explícito do harness; o OpenClaw não o infere a partir da prosa do assistente. O helper deixa intencionalmente sem classificação erros de prompt, turnos em andamento e respostas intencionalmente silenciosas, como NO_REPLY.

Efeitos colaterais ao final do agente

Harnesses nativos devem chamar runAgentEndSideEffects(...) de openclaw/plugin-sdk/agent-harness-runtime depois de finalizarem uma tentativa. Ele despacha o hook portátil agent_end e a captura de pesquisa do OpenClaw sem atrasar respostas interativas. Use awaitAgentEndSideEffects(...) para execuções locais e não interativas nas quais a tentativa não deve ser resolvida até que esses efeitos colaterais terminem. Ambos os helpers aceitam o mesmo payload { event, ctx } que runAgentHarnessAgentEndHook(...); suas falhas não alteram o resultado da tentativa concluída.

Entrada do usuário e superfícies de ferramentas

Harnesses nativos que expõem uma solicitação de entrada do usuário no nível do runtime devem usar os helpers de entrada do usuário de openclaw/plugin-sdk/agent-harness-runtime para formatar o prompt, entregá-lo pelo caminho de resposta bloqueante do OpenClaw e normalizar respostas de escolha ou em formato livre de volta para o formato de resposta nativo do runtime. O helper mantém a apresentação no canal/TUI consistente, enquanto cada harness mantém sua própria análise de protocolo e seu ciclo de vida de solicitações pendentes.

Harnesses nativos que precisam de roteamento compacto de ferramentas semelhante ao PI devem usar createAgentHarnessToolSurfaceRuntime(...) de openclaw/plugin-sdk/agent-harness-tool-runtime. Ele controla a seleção de controle de pesquisa de ferramentas/modo de código, padrões enxutos para modelos locais, filtragem de esquemas compatível com o runtime, execução de catálogo oculto, hidratação de diretórios e limpeza de catálogo. Os harnesses continuam controlando sua conversão de ferramentas específica do SDK e o callback de execução nativo.

Modo de harness nativo do Codex

O harness codex incluído é o modo nativo do Codex para turnos de agente incorporados do OpenClaw. Primeiro, habilite o plugin codex incluído e adicione codex a plugins.allow se sua configuração usar uma lista de permissões restritiva. Configurações nativas do app-server devem usar openai/gpt-*; turnos de agente da OpenAI selecionam o harness do Codex somente quando a rota efetiva declara compatibilidade com o Codex. Referências legadas de modelos do Codex devem ser reparadas com openclaw doctor --fix, e referências legadas de modelos codex/* permanecem como aliases de compatibilidade para o harness nativo.

Quando esse modo é executado, o Codex controla o ID nativo da thread, o comportamento de retomada, a Compaction e a execução do app-server. O OpenClaw continua controlando o canal de chat, o espelho visível da transcrição, a política de ferramentas, as aprovações, a entrega de mídia e a seleção de sessão. Use agentRuntime.id: "codex" no provedor/modelo quando precisar comprovar que somente o caminho do app-server do Codex pode assumir a execução. Runtimes de plugins explícitos falham de forma fechada; falhas de seleção do app-server do Codex e falhas de runtime não são repetidas por meio de outro runtime.

Rigor do runtime

Por padrão, o OpenClaw usa a política de runtime auto para provedor/modelo: harnesses de plugins registrados podem assumir rotas efetivas compatíveis, e o runtime incorporado processa o turno quando nenhum corresponde. Um prefixo de provedor/modelo por si só nunca seleciona um harness. Use um runtime de plugin explícito de provedor/modelo, como agentRuntime.id: "codex", quando a ausência da seleção de harness deva causar falha em vez de rotear pelo runtime incorporado. A seleção explícita não torna compatível uma rota incompatível. Falhas de harnesses de plugins selecionados sempre causam uma falha definitiva. Isso não bloqueia um agentRuntime.id: "openclaw" explícito no provedor/modelo.

Para execuções incorporadas exclusivas do Codex:

{  "models": {    "providers": {      "openai": {        "agentRuntime": {          "id": "codex"        }      }    }  },  "agents": {    "defaults": {      "model": "openai/gpt-5.6-sol"    }  }}

Se quiser um backend de CLI para um único modelo canônico, coloque o runtime na entrada desse modelo:

{  "agents": {    "defaults": {      "model": "anthropic/claude-opus-4-8",      "models": {        "anthropic/claude-opus-4-8": {          "agentRuntime": {            "id": "claude-cli"          }        }      }    }  }}

Substituições por agente usam o mesmo formato com escopo de modelo:

{  "agents": {    "list": [      {        "id": "codex-only",        "model": "openai/gpt-5.6-sol",        "models": {          "openai/gpt-5.6-sol": {            "agentRuntime": { "id": "codex" }          }        }      }    ]  }}

Exemplos legados de runtime para o agente inteiro, como este, são ignorados:

{  "agents": {    "defaults": {      "agentRuntime": {        "id": "codex"      }    }  }}

Com um runtime de plugin explícito, uma sessão falha antecipadamente quando o harness solicitado não está registrado, não oferece suporte ao provedor/modelo resolvido ou falha antes de produzir efeitos colaterais do turno. Isso é intencional para implantações exclusivas do Codex e para testes ao vivo que precisam comprovar que o caminho do app-server do Codex está realmente em uso.

Essa configuração controla apenas o harness de agente incorporado. Ela não desabilita o roteamento de modelos específicos do provedor para imagem, vídeo, música, TTS, PDF ou outros tipos.

Sessões nativas e espelho da transcrição

Um harness pode manter um ID de sessão nativo, ID de thread ou token de retomada no lado do daemon. Mantenha essa vinculação explicitamente associada à sessão do OpenClaw e continue espelhando a saída do assistente e das ferramentas visível ao usuário na transcrição do OpenClaw.

A transcrição do OpenClaw continua sendo a camada de compatibilidade para:

• histórico da sessão visível no canal
• pesquisa e indexação da transcrição
• retorno ao harness integrado do OpenClaw em um turno posterior
• comportamento genérico de /new, /reset e exclusão de sessão

Se seu harness armazenar uma vinculação auxiliar, implemente reset(...) para que o OpenClaw possa apagá-la quando a sessão correspondente do OpenClaw for redefinida.

Resultados de ferramentas e mídia

O núcleo cria a lista de ferramentas do OpenClaw e a repassa à tentativa preparada. Quando um harness executar uma chamada dinâmica de ferramenta, retorne o resultado da ferramenta pelo formato de resultado do harness, em vez de enviar você mesmo a mídia ao canal.

Isso mantém as saídas de texto, imagem, vídeo, música, TTS, aprovação e ferramentas de mensagens no mesmo caminho de entrega das execuções processadas pelo OpenClaw.

Limitações atuais

• O caminho público de importação é genérico, mas alguns aliases de tipos de tentativa/resultado ainda mantêm nomes legados por compatibilidade.
• A instalação de harnesses de terceiros é experimental. Prefira plugins de provedores até precisar de um runtime de sessão nativo.
• A troca de harness é compatível entre turnos. Não troque de harness no meio de um turno depois que ferramentas nativas, aprovações, texto do assistente ou envios de mensagens tiverem começado.

Relacionados

• Visão geral do SDK
• Helpers de runtime
• Plugins de provedores
• Harness do Codex
• Provedores de modelos