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 é bloqueado intencionalmente e /acp doctor relata a entrada ausente na allowlist.
• O adaptador ACP do Codex é preparado com o plugin acpx e iniciado localmente quando possível.
• Codex ACP executa com um CODEX_HOME isolado; o OpenClaw copia apenas entradas de projeto confiáveis da configuração do Codex do host e confia no workspace ativo, deixando autenticação, notificações e hooks 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, buscas de adaptador na primeira execução falham até que os caches sejam pré-aquecidos ou o adaptador seja instalado de outra forma.

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

Antes de culpar o OpenClaw, verifique:

• /acp doctor relata um backend habilitado e íntegro.
• O id de destino é permitido por acp.allowedAgents quando essa allowlist está definida.
• O comando do harness pode iniciar no host do 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, então execuções de codificação intensivas em escrita/execução geralmente precisam de um perfil de permissão ACPX que possa prosseguir sem intervenção.

• A geração cria 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; conclusão e entrega entre superfícies passam pelo notificador da tarefa pai em vez de agir como uma sessão normal de chat voltada ao usuário.
• A manutenção de tarefas fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai. Sessões ACP persistentes são preservadas enquanto um vínculo ativo de conversa permanece; sessões persistentes obsoletas sem um 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 do Gateway permanecem locais. /acp ..., /status e /unfocus nunca são enviados como texto normal de prompt 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 retomar.
• O plugin acpx limpa árvores de processos de wrapper e adaptador pertencentes ao OpenClaw após close, e recolhe órfãos ACPX obsoletos pertencentes ao OpenClaw durante a inicialização do Gateway.
• Workers de runtime ociosos são 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 do Codex <id>."
• "Mostre as threads do Codex, depois vincule esta."

A vinculação nativa de conversas do Codex é o caminho padrão de controle de chat. As ferramentas dinâmicas do OpenClaw ainda são executadas pelo 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 retransmitidos para before_agent_finalize do OpenClaw, onde Plugins podem solicitar mais uma passagem do modelo antes que o Codex finalize 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 do ACP. O limite de suporte do Codex incorporado está documentado no contrato de suporte do harness Codex v1.

• openai-codex/* - rota legada de modelo Codex OAuth/assinatura reparada pelo doctor.
• openai/* - runtime incorporado nativo do servidor de aplicativo Codex para turnos de agente OpenAI.
• /codex ... - controle nativo de conversa 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 avulsa do Claude Code e resuma o resultado."
• "Use Gemini CLI para esta tarefa em uma thread e depois mantenha os acompanhamentos nessa mesma thread."
• "Execute o Codex pelo 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 o 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 de sessions_spawn({ runtime: "acp" }). Ele aponta para ids de harness ACP como codex, claude, droid, gemini ou opencode. Não passe um id normal de agente da configuração do OpenClaw vindo 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 do OpenClaw está 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 só funciona em canais que anunciam vinculação de conversa atual; caso contrário, o OpenClaw retorna uma mensagem clara de não suporte. Vinculações persistem entre 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 criação.
• 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 estiver 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 roteiam para a sessão ACP vinculada.
• A saída do ACP é entregue de volta à mesma thread.
• Unfocus/fechamento/arquivamento/timeout 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 threads:

• acp.enabled=true
• acp.dispatch.enabled fica ligado por padrão (defina false para pausar o despacho automático de threads ACP; chamadas explícitas de sessions_spawn({ runtime: "acp" }) continuam funcionando).
• Criações de sessão de thread do adaptador de canal habilitadas (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 não suporte/indisponibilidade.

• 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 pela mesma interface de vinculação.

Sessões interativas foram pensadas para continuar conversando 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 de canal à sessão ACP.
• bindings[].type="acp" persistentes configurados 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.
• Comandos de gerenciamento /acp e comandos locais do Gateway são interceptados antes do despacho 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 a 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 internos de eventos permanecem estruturados no OpenClaw quando possível e não são tratados como conteúdo de chat escrito pelo usuário.

Sessões ACP de execução única criadas por outra execução de agente são filhos em segundo plano, semelhantes a subagentes:

• O pai solicita trabalho com sessions_spawn({ runtime: "acp", mode: "run" }).
• O filho executa na própria sessão de harness ACP.
• Vezes do filho executam na mesma faixa em segundo plano usada por criações de subagentes nativos, então um harness ACP lento não bloqueia trabalho não relacionado da sessão principal.
• A conclusão é reportada de volta pelo caminho de anúncio de conclusão da 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 criação. Para sessões pares normais, o OpenClaw usa um caminho de acompanhamento agente a 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 vezes de acompanhamento.
• Pede ao destino para produzir uma mensagem de anúncio.
• Entrega esse anúncio ao canal ou thread visível.

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

O OpenClaw ignora o acompanhamento A2A somente quando o solicitante é o pai de seu próprio filho ACP de execução única 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 reporta delivery.status="skipped" nesse caso de filho pertencente ao pai 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 todo o contexto 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:

• Transferir uma sessão Codex do seu laptop para o seu telefone - diga ao seu agente para retomar de onde você parou.
• Continuar uma sessão de codificação que você iniciou interativamente na CLI, agora sem interface por meio do seu agente.
• Retomar trabalho que foi interrompido por uma reinicialização do Gateway ou timeout por inatividade.

Observações:

• resumeSessionId só se aplica quando runtime: "acp"; o runtime padrão de subagente ignora este campo exclusivo de ACP.
• streamTo só se aplica quando runtime: "acp"; o runtime padrão de subagente ignora este campo exclusivo de ACP.
• resumeSessionId é um ID de retomada ACP/harness local do 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 é responsável pela 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 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 da sessão não for encontrado, a criação falha com um erro claro - sem fallback silencioso para uma nova sessão.

Após um deploy de Gateway, execute uma verificação ao vivo de ponta a ponta 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 de ponte ACPX temporária para um agente ativo.
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 de ponte temporária.

Mantenha o gate em mode: "run" e ignore streamTo: "parent" - mode: "session" vinculado à thread e caminhos de retransmissão de stream são passagens de integração mais completas separadas.