agentes ACP

• Se plugins.allow estiver definido, ele é um inventário restritivo de plugins e deve incluir acpx; caso contrário, o backend ACP instalado será bloqueado intencionalmente e /acp doctor reportará a entrada ausente na lista de permissões.
• O adaptador ACP do Codex é preparado com o plugin acpx e iniciado localmente quando possível.
• Codex ACP é executado com um CODEX_HOME isolado; o OpenClaw copia entradas de projeto confiáveis e configuração segura de roteamento de modelo/provedor da configuração do Codex no host, enquanto autenticação, notificações e hooks permanecem na configuração do host.
• Outros adaptadores de harness de destino ainda podem ser buscados sob demanda com npx na primeira vez que você os usa.
• A autenticação do fornecedor ainda precisa existir no host para esse harness.
• Se o host não tiver npm ou acesso à rede, as buscas de adaptador na primeira execução falham até que os caches sejam pré-aquecidos ou o adaptador seja instalado de outra forma.

O ACP inicia um processo real de harness externo. O OpenClaw é responsável por roteamento, estado de tarefa em segundo plano, entrega, vínculos e política; o harness é responsável por seu login de provedor, catálogo de modelos, comportamento do sistema de arquivos e ferramentas nativas.

Antes de culpar o OpenClaw, verifique:

• /acp doctor reporta um backend habilitado e saudável.
• O id de destino é permitido por acp.allowedAgents quando essa lista de permissões está definida.
• O comando do harness consegue iniciar no host Gateway.
• A autenticação do provedor está presente para esse harness (claude, codex, gemini, opencode, droid, etc.).
• O modelo selecionado existe para esse harness - ids de modelo não são portáveis entre harnesses.
• O cwd solicitado existe e está acessível, ou omita cwd e deixe o backend usar seu padrão.
• O modo de permissão corresponde ao trabalho. Sessões não interativas não conseguem clicar em prompts nativos de permissão, portanto execuções de codificação com muita escrita/execução geralmente precisam de um perfil de permissão ACPX que possa prosseguir sem interação.

• Criar inicia ou retoma uma sessão de runtime ACP, registra metadados ACP no armazenamento de sessões do OpenClaw e pode criar uma tarefa em segundo plano quando a execução pertence ao pai.
• Sessões ACP pertencentes ao pai são tratadas como trabalho em segundo plano mesmo quando a sessão de runtime é persistente; a conclusão e a entrega entre superfícies passam pelo notificador da tarefa pai, em vez de agir como uma sessão de chat normal voltada ao usuário.
• A manutenção de tarefas fecha sessões ACP one-shot pertencentes ao pai que estejam terminais ou órfãs. Sessões ACP persistentes são preservadas enquanto permanecer um vínculo de conversa ativo; sessões persistentes obsoletas sem vínculo ativo são fechadas para que não possam ser retomadas silenciosamente depois que a tarefa proprietária termina ou seu registro de tarefa desaparece.
• Mensagens de acompanhamento vinculadas vão diretamente para a sessão ACP até que o vínculo seja fechado, desfocado, redefinido ou expire.
• Comandos Gateway permanecem locais. /acp ..., /status e /unfocus nunca são enviados como texto de prompt normal para um harness ACP vinculado.
• cancel aborta o turno ativo quando o backend oferece suporte a cancelamento; ele não exclui o vínculo nem os metadados da sessão.
• close encerra a sessão ACP do ponto de vista do OpenClaw e remove o vínculo. Um harness ainda pode manter seu próprio histórico upstream se oferecer suporte a retomada.
• O plugin acpx limpa árvores de processos de wrapper e adaptador pertencentes ao OpenClaw após close e coleta órfãos ACPX obsoletos pertencentes ao OpenClaw durante a inicialização do Gateway.
• Workers de runtime ociosos ficam elegíveis para limpeza após acp.runtime.ttlMinutes; metadados de sessão armazenados permanecem disponíveis para /acp sessions.

Gatilhos em linguagem natural que devem ser roteados para o plugin nativo do Codex quando ele está habilitado:

• "Vincule este canal do Discord ao Codex."
• "Anexe este chat à thread Codex <id>."
• "Mostre as threads do Codex e então vincule esta."

A vinculação de conversa nativa do Codex é o caminho padrão de controle por chat. As ferramentas dinâmicas do OpenClaw ainda são executadas por meio do OpenClaw, enquanto ferramentas nativas do Codex, como shell/apply-patch, são executadas dentro do Codex. Para eventos de ferramentas nativas do Codex, o OpenClaw injeta um relay de hook nativo por turno para que hooks de Plugin possam bloquear before_tool_call, observar after_tool_call e rotear eventos PermissionRequest do Codex pelas aprovações do OpenClaw. Hooks Stop do Codex são repassados para before_agent_finalize do OpenClaw, onde Plugins podem solicitar mais uma passagem do modelo antes de o Codex finalizar sua resposta. O relay permanece deliberadamente conservador: ele não altera argumentos de ferramentas nativas do Codex nem reescreve registros de thread do Codex. Use ACP explícito somente quando quiser o modelo de runtime/sessão ACP. O limite de suporte do Codex incorporado está documentado no contrato de suporte do harness Codex v1.

• refs legadas de modelo Codex - rota legada de modelo OAuth/assinatura do Codex reparada pelo doctor.
• openai/* - runtime incorporado nativo de app-server do Codex para turnos de agente OpenAI.
• /codex ... - controle de conversa nativo do Codex.
• /acp ... ou runtime: "acp" - controle ACP/acpx explícito.

Gatilhos que devem rotear para o runtime ACP:

• "Execute isto como uma sessão ACP Claude Code avulsa e resuma o resultado."
• "Use Gemini CLI para esta tarefa em uma thread, depois mantenha os acompanhamentos nessa mesma thread."
• "Execute Codex por meio de ACP em uma thread em segundo plano."

O OpenClaw escolhe runtime: "acp", resolve o agentId do harness, vincula à conversa ou thread atual quando houver suporte e roteia acompanhamentos para essa sessão até o fechamento/expiração. O Codex só segue esse caminho quando ACP/acpx é explícito ou o Plugin nativo do Codex está indisponível para a operação solicitada.

Para sessions_spawn, runtime: "acp" é anunciado somente quando ACP está habilitado, o solicitante não está em sandbox e um backend de runtime ACP está carregado. acp.dispatch.enabled=false pausa o despacho automático de threads ACP, mas não oculta nem bloqueia chamadas explícitas sessions_spawn({ runtime: "acp" }). Ele direciona ids de harness ACP como codex, claude, droid, gemini ou opencode. Não passe um id normal de agente de configuração do OpenClaw de agents_list, a menos que essa entrada esteja explicitamente configurada com agents.list[].runtime.type="acp"; caso contrário, use o runtime padrão de subagente. Quando um agente OpenClaw é configurado com runtime.type="acp", o OpenClaw usa runtime.acp.agent como o id de harness subjacente.

• --bind here e --thread ... são mutuamente exclusivos.
• --bind here funciona apenas em canais que anunciam vinculação da conversa atual; caso contrário, o OpenClaw retorna uma mensagem clara de sem suporte. Vinculações persistem após reinicializações do Gateway.
• No Discord, spawnSessions controla a criação de threads filhas para --thread auto|here - não --bind here.
• Se você criar uma sessão para um agente ACP diferente sem --cwd, o OpenClaw herda por padrão o workspace do agente de destino. Caminhos herdados ausentes (ENOENT/ENOTDIR) fazem fallback para o padrão do backend; outros erros de acesso (por exemplo, EACCES) aparecem como erros de spawn.
• Comandos de gerenciamento do Gateway permanecem locais em conversas vinculadas - comandos /acp ... são tratados pelo OpenClaw mesmo quando texto normal de acompanhamento é roteado para a sessão ACP vinculada; /status e /unfocus também permanecem locais sempre que o tratamento de comandos está habilitado para essa superfície.

Quando vinculações de thread estão habilitadas para um adaptador de canal:

• O OpenClaw vincula uma thread a uma sessão ACP de destino.
• Mensagens de acompanhamento nessa thread são roteadas para a sessão ACP vinculada.
• A saída do ACP é entregue de volta à mesma thread.
• Desfocar/fechar/arquivar/tempo limite de inatividade ou expiração por idade máxima remove a vinculação.
• /acp close, /acp cancel, /acp status, /status e /unfocus são comandos do Gateway, não prompts para o harness ACP.

Flags de recurso necessárias para ACP vinculado a thread:

• acp.enabled=true
• acp.dispatch.enabled fica ativado por padrão (defina false para pausar o despacho automático de threads ACP; chamadas explícitas sessions_spawn({ runtime: "acp" }) ainda funcionam).
• Spawns de sessão de thread do adaptador de canal habilitados (padrão: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

O suporte a vinculação de thread é específico do adaptador. Se o adaptador de canal ativo não oferecer suporte a vinculações de thread, o OpenClaw retorna uma mensagem clara de sem suporte/indisponível.

• Qualquer adaptador de canal que exponha capacidade de vinculação de sessão/thread.
• Suporte integrado atual: threads/canais do Discord, tópicos do Telegram (tópicos de fórum em grupos/supergrupos e tópicos de DM).
• Canais de Plugin podem adicionar suporte por meio da mesma interface de vinculação.

Sessões interativas são destinadas a manter a conversa em uma superfície de chat visível:

• /acp spawn ... --bind here vincula a conversa atual à sessão ACP.
• /acp spawn ... --thread ... vincula uma thread/tópico do canal à sessão ACP.
• bindings[].type="acp" configuradas persistentes roteiam conversas correspondentes para a mesma sessão ACP.

Mensagens de acompanhamento na conversa vinculada são roteadas diretamente para a sessão ACP, e a saída ACP é entregue de volta ao mesmo canal/thread/tópico.

O que o OpenClaw envia ao harness:

• Acompanhamentos vinculados normais são enviados como texto de prompt, mais anexos somente quando o harness/backend oferece suporte a eles.
• Comandos de gerenciamento /acp e comandos locais do Gateway são interceptados antes do envio ACP.
• Eventos de conclusão gerados pelo runtime são materializados por destino. Agentes OpenClaw recebem o envelope interno de contexto de runtime do OpenClaw; harnesses ACP externos recebem um prompt simples com o resultado filho e a instrução. O envelope bruto <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> nunca deve ser enviado para harnesses externos nem persistido como texto de transcrição de usuário ACP.
• Entradas de transcrição ACP usam o texto de acionamento visível ao usuário ou o prompt simples de conclusão. Metadados de evento internos permanecem estruturados no OpenClaw quando possível e não são tratados como conteúdo de chat de autoria do usuário.

Sessões ACP one-shot geradas por outra execução de agente são filhas em segundo plano, semelhantes a subagentes:

• O pai solicita trabalho com sessions_spawn({ runtime: "acp", mode: "run" }).
• O filho executa em sua própria sessão de harness ACP.
• Turnos do filho executam na mesma faixa em segundo plano usada por gerações de subagentes nativos, então um harness ACP lento não bloqueia trabalho não relacionado da sessão principal.
• Relatórios de conclusão retornam pelo caminho de anúncio de conclusão de tarefa. O OpenClaw converte metadados internos de conclusão em um prompt ACP simples antes de enviá-lo a um harness externo, para que harnesses não vejam marcadores de contexto de runtime exclusivos do OpenClaw.
• O pai reescreve o resultado do filho em voz normal de assistente quando uma resposta voltada ao usuário é útil.

Não trate este caminho como um chat ponto a ponto entre pai e filho. O filho já tem um canal de conclusão de volta para o pai.

sessions_send pode direcionar outra sessão após a geração. Para sessões pares normais, o OpenClaw usa um caminho de acompanhamento agente-para-agente (A2A) depois de injetar a mensagem:

• Aguarda a resposta da sessão de destino.
• Opcionalmente permite que solicitante e destino troquem um número limitado de turnos de acompanhamento.
• Solicita que o destino produza uma mensagem de anúncio.
• Entrega esse anúncio ao canal ou thread visível.

Esse caminho A2A é um fallback para envios entre pares quando o remetente precisa de um acompanhamento visível. Ele permanece habilitado quando uma sessão não relacionada pode ver e enviar mensagem a um destino ACP, por exemplo, sob configurações amplas de tools.sessions.visibility.

OpenClaw pula o acompanhamento A2A somente quando o solicitante é o pai de seu próprio filho ACP de uso único pertencente ao pai. Nesse caso, executar A2A sobre a conclusão da tarefa pode acordar o pai com o resultado do filho, encaminhar a resposta do pai de volta ao filho e criar um loop de eco pai/filho. O resultado de sessions_send informa delivery.status="skipped" para esse caso de filho pertencente porque o caminho de conclusão já é responsável pelo resultado.

Use resumeSessionId para continuar uma sessão ACP anterior em vez de começar do zero. O agente reproduz seu histórico de conversa via session/load, então retoma com o contexto completo do que veio antes.

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Casos de uso comuns:

• Passe uma sessão Codex do seu laptop para o seu telefone - diga ao seu agente para retomar de onde você parou.
• Continue uma sessão de codificação que você iniciou interativamente na CLI, agora de forma headless por meio do seu agente.
• Retome um trabalho que foi interrompido por uma reinicialização do gateway ou tempo limite de inatividade.

Observações:

• resumeSessionId só se aplica quando runtime: "acp"; o runtime padrão de subagente ignora esse campo exclusivo de ACP.
• streamTo só se aplica quando runtime: "acp"; o runtime padrão de subagente ignora esse campo exclusivo de ACP.
• resumeSessionId é um id de retomada ACP/harness local ao host, não uma chave de sessão de canal do OpenClaw; o OpenClaw ainda verifica a política de criação ACP e a política do agente de destino antes do despacho, enquanto o backend ou harness ACP controla a autorização para carregar esse id upstream.
• resumeSessionId restaura o histórico de conversa ACP upstream; thread e mode ainda se aplicam normalmente à nova sessão do OpenClaw que você está criando, então mode: "session" ainda exige thread: true.
• O agente de destino deve oferecer suporte a session/load (Codex e Claude Code oferecem).
• Se o id de sessão não for encontrado, a criação falha com um erro claro - sem fallback silencioso para uma nova sessão.

Depois de um deploy do Gateway, execute uma verificação ponta a ponta ao vivo em vez de confiar em testes unitários:

1. Verifique a versão e o commit do Gateway implantado no host de destino.
2. Abra uma sessão temporária de ponte ACPX para um agente ao vivo.
3. Peça a esse agente para chamar sessions_spawn com runtime: "acp", agentId: "codex", mode: "run" e a tarefa Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verifique accepted=yes, um childSessionKey real e nenhum erro de validador.
5. Limpe a sessão temporária de ponte.

Mantenha a porta em mode: "run" e pule streamTo: "parent" - mode: "session" vinculado a thread e caminhos de retransmissão de stream são passes de integração mais ricos separados.