Agentes ACP do OpenClaw

Você quer comandar o Claude Code ou o Gemini CLI a partir de uma mensagem no Telegram em vez de um terminal, e o OpenClaw consegue fazer isso pelo Agent Client Protocol. Uma sessão ACP inicia o harness externo real como um processo no host do Gateway, acompanha cada inicialização como uma tarefa em segundo plano e pode vincular uma conversa ou uma thread para que as mensagens seguintes continuem chegando ao mesmo harness. Antes, ela precisa de um plugin de runtime, e uma pequena lista de condições decide se o seu agente chega a ser informado de que esse caminho existe.

Instalando o plugin de runtime acpx

• As instalações empacotadas usam o plugin de runtime oficial acpx, publicado no npm sob o escopo openclaw, e são dois comandos: openclaw plugins install, com o nome desse pacote com escopo, e depois openclaw config set plugins.entries.acpx.enabled true. Checkouts do código-fonte podem usar, em vez disso, o plugin local do workspace extensions/acpx depois de pnpm install. Em seguida, rode /acp doctor para uma verificação de prontidão, ou /acp install para que o OpenClaw mostre as etapas determinísticas de instalação e ativação.
• Se plugins.allow estiver definido, ele é um inventário restritivo de plugins, e não uma sugestão, e precisa incluir acpx; caso contrário, o backend ACP instalado fica bloqueado de propósito. Essa é a falha de primeira execução mais confundida com uma instalação quebrada, e ela aparece como o erro dizendo que o backend de runtime ACP não está configurado; /acp doctor aponta a entrada que falta na lista de permissões em vez de deixar você adivinhando.
• O plugin acpx incorpora o runtime ACP diretamente, então não há um binário acpx separado nem uma versão para configurar. Ele registra o backend incorporado durante a inicialização do Gateway e espera uma verificação de saúde antes do sinal de pronto do gateway, e essa verificação também fornece o diagnóstico das falhas. Ela é limitada por plugins.entries.acpx.config.timeoutSeconds, cujo padrão é 120 segundos, para que harnesses mais lentos, como o Gemini CLI, consigam concluir o startup e a inicialização do ACP.
• O adaptador ACP do Codex vem com o plugin acpx e é iniciado localmente quando possível, rodando com um CODEX_HOME isolado para o qual o OpenClaw copia as entradas de confiança dos projetos confiáveis, além de uma configuração segura de roteamento de modelo e provedor, enquanto autenticação, notificações e hooks ficam apenas na configuração do host. Outros adaptadores de harness podem ser baixados sob demanda com npx no primeiro uso, então um host sem npm ou sem acesso à rede falha nesses downloads até que os caches sejam pré-aquecidos ou o adaptador seja instalado de outra forma.

Se qualquer condição falhar, as skills ACP e as orientações de ACP do sessions_spawn ficam ocultas, para que o agente não sugira um backend indisponível.

Por que as skills ACP podem ficar invisíveis

As condições estão listadas por completo: o ACP precisa estar ativado, o despacho não pode estar desativado, a sessão atual não pode estar bloqueada pela sandbox, e um backend de runtime precisa estar carregado e saudável. Um agente que nunca ofereceu iniciar uma sessão ACP geralmente está relatando a própria configuração com precisão, e não ignorando você. As duas metades falham de formas diferentes: acp.dispatch.enabled=false pausa o despacho automático de threads ACP sem ocultar nem bloquear uma chamada explícita a sessions_spawn com runtime acp, enquanto um solicitante em sandbox é recusado de cara, porque o runtime ACP roda no host. A partir de uma sessão em sandbox, a resposta documentada é o runtime subagent.

A lista de pré-requisitos

• Antes de culpar o OpenClaw, confirme que /acp doctor informa um backend ativado e saudável, que o ID de destino é permitido por acp.allowedAgents quando essa lista de permissões está definida e que o comando do harness consegue de fato iniciar no host do Gateway. Cada um desses pontos tem o próprio texto de erro, em vez de uma falha genérica, então a mensagem que você recebe já restringe a causa.
• A autenticação do provedor já precisa existir no host para o harness que você quer usar: claude, codex, gemini, opencode, droid e os demais têm, cada um, o próprio login. Um erro de autenticação do fornecedor significa que o OpenClaw está saudável e que a CLI ou o provedor de destino simplesmente não está logado, o que você corrige fazendo login ou fornecendo a chave do provedor no ambiente do host do Gateway, e não editando a configuração do OpenClaw.
• O modelo selecionado precisa existir para esse harness, porque os IDs de modelo não são portáveis entre harnesses, e o controle de modelo depende das capacidades do adaptador: um harness que não anuncia nem a capacidade models do ACP nem a própria flag de modelo na inicialização não pode ser forçado a usar um modelo de jeito nenhum. O cwd solicitado precisa existir e estar acessível; caso contrário, omita-o e deixe o backend usar o padrão dele.

Uma coisa decide a escolha antes de você escrever qualquer configuração: as ferramentas de plugin do OpenClaw e as ferramentas integradas do OpenClaw não são expostas aos harnesses ACP por padrão, e as duas pontes MCP que mudam isso são explícitas e vêm desativadas por padrão. Se o que você quer é uma execução delegada nativa do OpenClaw, com as próprias ferramentas do OpenClaw, isso é uma execução de subagentes do OpenClaw, com a própria chave de sessão e o próprio comando de barra; se você só quer uma CLI de IA local como modelo de fallback somente texto, os backends de CLI do OpenClaw não são ACP nem um runtime de harness, e não têm ferramentas do OpenClaw nem controles ACP.

Os dezessete IDs de destino de harness

Com o backend acpx, estes são os IDs que você passa para /acp spawn ou para sessions_spawn como agentId: claude, codex, copilot, cursor, droid, fast-agent, gemini, iflow, kilocode, kimi, kiro, mux, opencode, openclaw, qoder, qwen e trae. claude precisa da autenticação do Claude Code no host, copilot de um login na CLI ou no runtime do Copilot, cursor executa cursor-agent acp, droid precisa da autenticação do Factory ou do Droid ou de FACTORY_API_KEY no ambiente do harness, gemini precisa da autenticação do Gemini CLI ou de uma chave de API configurada, opencode precisa da autenticação da CLI do OpenCode ou do provedor, e openclaw é a ponte do Gateway que permite a um harness compatível com ACP responder a uma sessão do Gateway do OpenClaw. codex é o fallback ACP explícito, usado apenas quando o caminho nativo /codex está indisponível ou quando o ACP é pedido pelo nome. pi também está registrado no backend acpx, mas não é um harness de programação no mesmo sentido. Toda inicialização vai parar nas tarefas em segundo plano do OpenClaw, e é nos modos de permissão do OpenClaw que ficam as configurações no nível do harness, ao lado das aprovações de execução do OpenClaw: uma sessão ACP não tem TTY interativo, então programação com muita escrita e muita execução de comandos geralmente precisa de um perfil que consiga avançar sem interação.

Na Diali

A Diali hospeda o OpenClaw para você, e cada cliente roda o próprio assistente, e não uma fatia de um assistente compartilhado. A configuração do runtime é gerada a partir do painel e substituída a cada versão, então as chaves de política são escritas para você, em vez de editadas à mão em uma máquina da qual você precisa se lembrar. O estado fica em um volume persistente, que é o que preserva uma sessão e o histórico dela após uma atualização; snapshots diários e restauração com um clique estão disponíveis pelo complemento Backups (incluído no Max). O OpenClaw hospedado na Diali explica o que o runtime hospedado cobre, e a página de preços da Diali mostra os planos.

• Dois comandos instalam o acpx; depois, /acp doctor antes de qualquer outra coisa.
• Orientações de ACP ocultas indicam uma condição que falhou, e não um recurso ausente.
• Dezessete IDs de harness, cada um com o próprio login no host.