Agentes ACP

• Se plugins.allow estiver definido, ele será um inventário restritivo de plugins e deverá incluir acpx; caso contrário, o backend ACP instalado será bloqueado intencionalmente (/acp doctor informará a ausência da entrada na lista de permissões).
• O adaptador ACP do Codex é fornecido com o plugin acpx e é iniciado localmente quando possível.
• O Codex ACP é executado com um CODEX_HOME isolado. O OpenClaw copia as entradas confiáveis de confiança do projeto e a configuração segura de roteamento de modelo/provedor (model, model_provider, model_reasoning_effort, sandbox_mode e os campos seguros de model_providers.<name>) da configuração do Codex no host; autenticação, notificações e hooks permanecem apenas na configuração do host.
• Outros adaptadores de ambientes de destino podem ser obtidos sob demanda com npx no primeiro uso.
• A autenticação do fornecedor já deve existir no host para esse ambiente.
• Se o host não tiver npm ou acesso à rede, a obtenção dos adaptadores na primeira execução falhará até que os caches sejam pré-aquecidos ou que o adaptador seja instalado de outra forma.

O ACP inicia um processo real de ambiente externo. O OpenClaw controla o roteamento, o estado das tarefas em segundo plano, a entrega, os vínculos e as políticas; o ambiente controla o login no provedor, o catálogo de modelos, o comportamento do sistema de arquivos e as ferramentas nativas.

Antes de atribuir o problema ao OpenClaw, verifique:

• /acp doctor informa um backend habilitado e íntegro.
• O id de destino é permitido por acp.allowedAgents quando essa lista de permissões está definida.
• O comando do ambiente pode ser iniciado no host do Gateway.
• A autenticação do provedor está presente para esse ambiente (claude, codex, gemini, opencode, droid etc.).
• O modelo selecionado existe para esse ambiente — os ids de modelo não são intercambiáveis entre ambientes.
• O cwd solicitado existe e está acessível; caso contrário, omita cwd e permita que o backend use seu padrão.
• O modo de permissão corresponde ao trabalho. Sessões não interativas não podem clicar em solicitações nativas de permissão; portanto, execuções de programação com uso intenso de gravação/execução geralmente precisam de um perfil de permissões ACPX capaz de prosseguir sem interface interativa.

• A inicializaçã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 à tarefa principal.
• As sessões ACP pertencentes à tarefa principal 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 principal, em vez de se comportarem como uma sessão normal de chat voltada ao usuário.
• A manutenção de tarefas encerra sessões ACP de execução única, terminais ou órfãs, pertencentes à tarefa principal. Sessões ACP persistentes são preservadas enquanto houver um vínculo ativo com uma conversa; sessões persistentes obsoletas sem vínculo ativo são encerradas para impedir que sejam retomadas silenciosamente após a conclusão da tarefa proprietária ou a remoção do registro dessa tarefa.
• Mensagens subsequentes vinculadas são enviadas diretamente à sessão ACP até que o vínculo seja encerrado, perca o foco, seja redefinido ou expire.
• Os comandos do Gateway permanecem locais. /acp ..., /status e /unfocus nunca são enviados como texto normal de prompt a um ambiente ACP vinculado.
• cancel interrompe o turno ativo quando o backend é compatível com 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 ambiente ainda pode manter seu próprio histórico no serviço de origem se for compatível com retomada.
• O plugin acpx limpa as árvores de processos de wrappers e adaptadores pertencentes ao OpenClaw após close e remove processos ACPX órfãos e obsoletos pertencentes ao OpenClaw durante a inicialização do Gateway.
• Workers de runtime ociosos podem ser limpos após acp.runtime.ttlMinutes; os metadados de sessão armazenados continuam disponíveis para /acp sessions.

Gatilhos em linguagem natural que devem ser encaminhados ao plugin nativo do Codex quando ele estiver habilitado:

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

A vinculação nativa de conversas do Codex é o caminho padrão de controle do chat. As ferramentas dinâmicas do OpenClaw ainda são executadas pelo OpenClaw, enquanto as ferramentas nativas do Codex, como shell/apply-patch, são executadas dentro do Codex. Para eventos de ferramentas nativas do Codex, o OpenClaw injeta, a cada turno, um retransmissor de hooks nativos para que os hooks de plugins possam bloquear before_tool_call, observar after_tool_call e encaminhar eventos PermissionRequest do Codex pelas aprovações do OpenClaw. Os hooks Stop do Codex são retransmitidos para before_agent_finalize do OpenClaw, onde os plugins podem solicitar mais uma passagem do modelo antes que o Codex finalize sua resposta. O retransmissor permanece deliberadamente conservador: ele não modifica os argumentos das ferramentas nativas do Codex nem reescreve os registros de threads 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 v1 do harness do Codex.

• referências legadas de modelos do Codex - rota legada de modelo por OAuth/assinatura do Codex reparada pelo doctor.
• openai/* - runtime incorporado do app-server nativo do Codex para turnos de agentes da OpenAI.
• /codex ... - controle nativo de conversas do Codex.
• /acp ... ou runtime: "acp" - controle explícito do ACP/acpx.

Gatilhos que devem ser roteados ao runtime do ACP:

• "Execute isto como uma sessão ACP pontual do Claude Code e resuma o resultado."
• "Use o Gemini CLI para esta tarefa em uma thread e mantenha os acompanhamentos nessa mesma thread."
• "Execute o Codex pelo ACP em uma thread em segundo plano."

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

Para sessions_spawn, runtime: "acp" só é anunciado quando o ACP está habilitado, o solicitante não está em sandbox e um backend de runtime do ACP está carregado. acp.dispatch.enabled=false pausa o despacho automático de threads do ACP, mas não oculta nem bloqueia chamadas explícitas de sessions_spawn({ runtime: "acp" }). Ele tem como alvo ids de harness do ACP, como codex, claude, droid, gemini ou opencode. Não passe um id normal de agente da configuração do OpenClaw proveniente de agents_list, a menos que essa entrada esteja configurada explicitamente 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 suporte à vinculação da conversa atual; caso contrário, o OpenClaw retorna uma mensagem clara informando que não há suporte. As 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 para --bind here.
• Se você criar uma sessão para um agente ACP diferente sem --cwd, o OpenClaw herdará, por padrão, o workspace do agente de destino. Caminhos herdados ausentes (ENOENT/ENOTDIR) usam como alternativa o padrão do backend; outros erros de acesso (por exemplo, EACCES) são apresentados como erros de criação.
• Os comandos de gerenciamento do Gateway permanecem locais em conversas vinculadas — os comandos /acp ... são processados pelo OpenClaw mesmo quando o texto normal de acompanhamento é encaminhado à sessão ACP vinculada; /status e /unfocus também permanecem locais sempre que o processamento de comandos estiver habilitado para essa superfície.

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

• O OpenClaw vincula uma thread a uma sessão ACP de destino.
• As mensagens de acompanhamento nessa thread são encaminhadas à sessão ACP vinculada.
• A saída do ACP é entregue de volta à mesma thread.
• Remover o foco, fechar, arquivar ou expirar por inatividade ou 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 do ACP.

Flags de recurso obrigatórias para ACP vinculado a threads:

• acp.enabled=true
• acp.dispatch.enabled fica ativado por padrão (defina como false para pausar o despacho automático de threads do ACP; chamadas explícitas de sessions_spawn({ runtime: "acp" }) continuam funcionando).
• Criação de sessões de thread pelo adaptador de canal habilitada (padrão: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

O suporte à vinculação de threads é específico de cada adaptador. Se o adaptador de canal ativo não oferecer suporte a vinculações de threads, o OpenClaw retornará uma mensagem clara informando que o recurso não é compatível ou não está disponível.

• Qualquer adaptador de canal que exponha a capacidade de vinculação de sessões/threads.
• Suporte incorporado atual: threads/canais do Discord, tópicos do Telegram (tópicos de fórum em grupos/supergrupos e tópicos de mensagens diretas).
• Canais de plugins podem adicionar suporte pela mesma interface de vinculação.

As sessões interativas destinam-se 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 um tópico encadeado ou tópico do canal à sessão ACP.
• Vínculos persistentes configurados com bindings[].type="acp" encaminham as conversas correspondentes para a mesma sessão ACP.

Mensagens subsequentes na conversa vinculada são encaminhadas diretamente para a sessão ACP, e a saída ACP é entregue de volta ao mesmo canal, tópico encadeado ou tópico.

O que o OpenClaw envia à estrutura de execução:

• Mensagens subsequentes vinculadas normais são enviadas como texto do prompt, além de anexos somente quando a estrutura de execução ou a infraestrutura oferece suporte a eles.
• Os comandos de gerenciamento /acp e os comandos locais do Gateway são interceptados antes do envio ao ACP.
• Eventos de conclusão gerados durante a execução são materializados para cada destino. Agentes do OpenClaw recebem o envelope interno de contexto de execução do OpenClaw; estruturas de execução ACP externas recebem um prompt simples com o resultado da sessão secundária e a instrução. O envelope bruto <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> nunca deve ser enviado a estruturas externas nem persistido como texto de transcrição do usuário no ACP.
• As entradas da transcrição ACP usam o texto de acionamento visível ao usuário ou o prompt simples de conclusão. Os metadados internos do evento permanecem estruturados no OpenClaw sempre que possível e não são tratados como conteúdo de chat escrito pelo usuário.

Sessões ACP de execução única iniciadas por outra execução de agente são sessões secundárias em segundo plano, semelhantes a subagentes:

• A sessão principal solicita o trabalho com sessions_spawn({ runtime: "acp", mode: "run" }).
• A sessão secundária é executada em sua própria sessão da estrutura de execução ACP.
• Os turnos da sessão secundária são executados na mesma faixa de segundo plano usada pelas inicializações nativas de subagentes; portanto, uma estrutura de execução ACP lenta não bloqueia trabalhos não relacionados da sessão principal.
• A conclusão é informada pelo caminho de anúncio de conclusão da tarefa. O OpenClaw converte os metadados internos de conclusão em um prompt ACP simples antes de enviá-los a uma estrutura externa; assim, essas estruturas não veem marcadores de contexto de execução exclusivos do OpenClaw.
• A sessão principal reformula o resultado da sessão secundária na voz normal do assistente quando uma resposta voltada ao usuário é útil.

Não trate esse caminho como um chat ponto a ponto entre a sessão principal e a sessão secundária. A sessão secundária já possui um canal de conclusão de volta para a sessão principal.

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

• Aguarda a resposta da sessão de destino.
• Opcionalmente, permite que o solicitante e o destino troquem uma quantidade limitada de turnos subsequentes.
• Solicita que o destino produza uma mensagem de anúncio.
• Entrega esse anúncio ao canal ou tópico encadeado 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, sob 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 além da conclusão da tarefa pode despertar o pai com o resultado do filho, encaminhar a resposta do pai de volta ao filho e criar um ciclo de eco pai/filho. O resultado de sessions_send informa delivery.status="skipped" nesse caso de filho pertencente ao pai, pois 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 o histórico da conversa por meio de session/load, retomando com o contexto completo do que ocorreu antes.

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

Casos de uso comuns:

• Transfira uma sessão do Codex do seu laptop para o telefone — peça ao agente que retome de onde você parou.
• Continue uma sessão de programação iniciada interativamente na CLI, agora sem interface por meio do seu agente.
• Retome um trabalho interrompido por uma reinicialização do Gateway ou pelo tempo limite de inatividade.

Observações:

• resumeSessionId só se aplica quando runtime: "acp"; o runtime padrão de subagente ignora esse campo exclusivo do ACP.
• streamTo só se aplica quando runtime: "acp"; o runtime padrão de subagente ignora esse campo exclusivo do ACP.
• resumeSessionId é um id de retomada do 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 do 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 de origem.
• resumeSessionId restaura o histórico da conversa ACP de origem; thread e mode ainda se aplicam normalmente à nova sessão do OpenClaw que você está criando, portanto 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 falhará com um erro claro — sem fallback silencioso para uma nova sessão.

Após uma implantação do Gateway, execute uma verificação completa e ativa 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 temporária de ponte ACPX para um agente ativo.
3. Peça a esse agente que chame sessions_spawn com runtime: "acp", agentId: "codex", mode: "run" e a tarefa Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verifique accepted=yes, uma childSessionKey real e a ausência de erros do validador.
5. Encerre a sessão temporária de ponte.

Mantenha a validação em mode: "run" e ignore streamTo: "parent" — o mode: "session" vinculado a uma thread e os caminhos de retransmissão de fluxo são verificações de integração distintas e mais abrangentes.