​

Agentes ACP

​

Qual página eu quero?

​

Isso funciona pronto para uso?

• Instalações novas agora já vêm com o plugin de runtime integrado acpx habilitado por padrão.
• O plugin integrado acpx prefere seu binário acpx fixado localmente no plugin.
• Na inicialização, o OpenClaw sonda esse binário e faz autorreparo se necessário.
• Comece com /acp doctor se quiser uma verificação rápida de prontidão.

• Um adapter do harness de destino pode ser buscado sob demanda com npx na primeira vez em que você usar esse harness.
• A autenticação do fornecedor ainda precisa existir no host para esse harness.
• Se o host não tiver acesso a npm/rede, buscas de adapter na primeira execução podem falhar até que os caches sejam pré-aquecidos ou o adapter seja instalado de outra forma.

• /acp spawn codex: o OpenClaw deve estar pronto para inicializar acpx, mas o adapter ACP do Codex ainda pode precisar de uma busca na primeira execução.
• /acp spawn claude: a mesma situação para o adapter ACP do Claude, além da autenticação do lado do Claude nesse host.

​

Fluxo rápido para operadores

1. Gere uma sessão:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Trabalhe na conversa ou thread vinculada (ou direcione explicitamente para essa session key).
3. Verifique o estado do runtime:
   • /acp status
4. Ajuste opções do runtime conforme necessário:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Dê uma orientação a uma sessão ativa sem substituir o contexto:
   • /acp steer tighten logging and continue
6. Pare o trabalho:
   • /acp cancel (interrompe o turno atual), ou
   • /acp close (fecha a sessão + remove bindings)

​

Início rápido para pessoas

• “Vincule este canal do Discord ao Codex.”
• “Inicie uma sessão Codex persistente em uma thread aqui e mantenha o foco.”
• “Execute isso como uma sessão ACP one-shot do Claude Code e resuma o resultado.”
• “Vincule este chat do iMessage ao Codex e mantenha os acompanhamentos no mesmo workspace.”
• “Use Gemini CLI para esta tarefa em uma thread e depois mantenha os acompanhamentos nessa mesma thread.”

1. Escolher runtime: "acp".
2. Resolver o destino de harness solicitado (agentId, por exemplo codex).
3. Se for solicitado binding na conversa atual e o canal ativo oferecer suporte, vincular a sessão ACP a essa conversa.
4. Caso contrário, se for solicitado binding em thread e o canal atual oferecer suporte, vincular a sessão ACP à thread.
5. Encaminhar mensagens vinculadas de acompanhamento para essa mesma sessão ACP até perder foco/ser fechada/expirar.

​

ACP versus subagentes

​

Como o ACP executa Claude Code

1. Plano de controle da sessão ACP do OpenClaw
2. plugin de runtime integrado acpx
3. adapter ACP do Claude
4. maquinário de runtime/sessão do lado do Claude

• Claude em ACP não é a mesma coisa que o runtime de fallback direto claude-cli/....
• Claude em ACP é uma sessão de harness com controles ACP, retomada de sessão, rastreamento de tarefa em segundo plano e binding opcional de conversa/thread.
• claude-cli/... é um backend de CLI local somente de texto. Consulte CLI Backends.

• quer /acp spawn, sessões vinculáveis, controles de runtime ou trabalho persistente em harness: use ACP
• quer um fallback simples de texto local pela CLI bruta: use backends CLI

​

Sessões vinculadas

​

Bindings da conversa atual

• O OpenClaw continua sendo dono do transporte do canal, autenticação, segurança e entrega.
• A conversa atual é fixada na session key ACP gerada.
• Mensagens de acompanhamento nessa conversa são encaminhadas para a mesma sessão ACP.
• /new e /reset redefinem a mesma sessão ACP vinculada no mesmo lugar.
• /acp close fecha a sessão e remove o binding da conversa atual.

• --bind here mantém a mesma superfície de chat. No Discord, o canal atual continua sendo o canal atual.
• --bind here ainda pode criar uma nova sessão ACP se você estiver gerando trabalho novo. O binding anexa essa sessão à conversa atual.
• --bind here não cria por si só uma thread filha do Discord nem um tópico do Telegram.
• O runtime ACP ainda pode ter seu próprio diretório de trabalho (cwd) ou workspace em disco gerenciado pelo backend. Esse workspace do runtime é separado da superfície de chat e não implica uma nova thread de mensagens.
• Se você gerar para um agente ACP diferente e não passar --cwd, o OpenClaw herda por padrão o workspace do agente de destino, não o do solicitante.
• Se esse caminho de workspace herdado estiver ausente (ENOENT/ENOTDIR), o OpenClaw usa como fallback o cwd padrão do backend em vez de reutilizar silenciosamente a árvore errada.
• Se o workspace herdado existir, mas não puder ser acessado (por exemplo EACCES), o spawn retorna o erro real de acesso em vez de descartar cwd.

• superfície de chat: onde as pessoas continuam conversando (canal do Discord, tópico do Telegram, chat do iMessage)
• sessão ACP: o estado durável de runtime de Codex/Claude/Gemini para o qual o OpenClaw encaminha
• thread/tópico filho: uma superfície extra opcional de mensagens criada apenas por --thread ...
• workspace de runtime: o local no sistema de arquivos onde o harness roda (cwd, checkout do repositório, workspace do backend)

• /acp spawn codex --bind here: mantenha este chat, gere ou anexe uma sessão ACP do Codex e encaminhe mensagens futuras daqui para ela
• /acp spawn codex --thread auto: o OpenClaw pode criar uma thread/tópico filho e vincular a sessão ACP lá
• /acp spawn codex --bind here --cwd /workspace/repo: mesmo binding de chat acima, mas o Codex roda em /workspace/repo

• Canais de chat/mensagem que anunciam suporte a binding da conversa atual podem usar --bind here pelo caminho compartilhado de binding de conversa.
• Canais com semântica customizada de thread/tópico ainda podem fornecer canonicalização específica do canal por trás da mesma interface compartilhada.
• --bind here sempre significa “vincular a conversa atual no mesmo lugar”.
• Bindings genéricos da conversa atual usam o armazenamento compartilhado de bindings do OpenClaw e sobrevivem a reinicializações normais do gateway.

• --bind here e --thread ... são mutuamente exclusivos em /acp spawn.
• No Discord, --bind here vincula o canal ou thread atual no mesmo lugar. spawnAcpSessions só é necessário quando o OpenClaw precisa criar uma thread filha para --thread auto|here.
• Se o canal ativo não expuser bindings ACP da conversa atual, o OpenClaw retorna uma mensagem clara de não compatibilidade.
• resume e perguntas de “nova sessão” são questões da sessão ACP, não do canal. Você pode reutilizar ou substituir o estado do runtime sem mudar a superfície de chat atual.

​

Sessões vinculadas à thread

• O OpenClaw vincula uma thread a uma sessão ACP de destino.
• Mensagens de acompanhamento nessa thread são encaminhadas para a sessão ACP vinculada.
• A saída ACP é entregue de volta à mesma thread.
• Perda de foco/fechamento/arquivamento/timeout por inatividade ou expiração por idade máxima removem o binding.

• acp.enabled=true
• acp.dispatch.enabled vem ativado por padrão (defina false para pausar o despacho ACP)
• Flag de spawn ACP em thread do adapter de canal habilitada (específica do adapter)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Canais compatíveis com thread

• Qualquer adapter de canal que exponha capacidade de binding 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 binding.

​

Configurações específicas de canal

​

Modelo de binding

• bindings[].type="acp" marca um binding persistente de conversa ACP.
• bindings[].match identifica a conversa de destino:
  • Canal ou thread do Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Tópico de fórum do Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • Chat DM/em grupo do BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Prefira chat_id:* ou chat_identifier:* para bindings estáveis de grupos.
  • Chat DM/em grupo do iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Prefira chat_id:* para bindings estáveis de grupos.
• bindings[].agentId é o id do agente OpenClaw proprietário.
• Overrides opcionais de ACP ficam em bindings[].acp:
  • mode (persistent ou oneshot)
  • label
  • cwd
  • backend

​

Padrões de runtime por agente

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (id do harness, por exemplo codex ou claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. padrões globais de ACP (por exemplo acp.backend)

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

• O OpenClaw garante que a sessão ACP configurada exista antes do uso.
• Mensagens nesse canal ou tópico são encaminhadas para a sessão ACP configurada.
• Em conversas vinculadas, /new e /reset redefinem a mesma session key ACP no mesmo lugar.
• Bindings temporários de runtime (por exemplo criados por fluxos de foco em thread) continuam valendo quando presentes.
• Para spawns ACP entre agentes sem cwd explícito, o OpenClaw herda o workspace do agente de destino a partir da configuração do agente.
• Caminhos herdados de workspace ausentes usam como fallback o cwd padrão do backend; falhas reais de acesso em caminhos existentes aparecem como erros de spawn.

​

Iniciar sessões ACP (interfaces)

​

A partir de sessions_spawn

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime assume subagent por padrão, então defina runtime: "acp" explicitamente para sessões ACP.
• Se agentId for omitido, o OpenClaw usa acp.defaultAgent quando configurado.
• mode: "session" exige thread: true para manter uma conversa persistente vinculada.

• task (obrigatório): prompt inicial enviado à sessão ACP.
• runtime (obrigatório para ACP): deve ser "acp".
• agentId (opcional): id do harness ACP de destino. Usa acp.defaultAgent como fallback se estiver definido.
• thread (opcional, padrão false): solicita fluxo de binding de thread quando compatível.
• mode (opcional): run (one-shot) ou session (persistente).
  • o padrão é run
  • se thread: true e mode for omitido, o OpenClaw pode assumir comportamento persistente por caminho de runtime
  • mode: "session" exige thread: true
• cwd (opcional): diretório de trabalho solicitado para o runtime (validado pela política do backend/runtime). Se omitido, o spawn ACP herda o workspace do agente de destino quando configurado; caminhos herdados ausentes usam como fallback os padrões do backend, enquanto erros reais de acesso são retornados.
• label (opcional): rótulo voltado ao operador usado em texto de sessão/banner.
• resumeSessionId (opcional): retoma uma sessão ACP existente em vez de criar uma nova. O agente reproduz seu histórico de conversa via session/load. Exige runtime: "acp".
• streamTo (opcional): "parent" transmite resumos de progresso da execução ACP inicial de volta para a sessão solicitante como eventos de sistema.
  • Quando disponível, as respostas aceitas incluem streamLogPath apontando para um log JSONL com escopo de sessão (<sessionId>.acp-stream.jsonl) que você pode acompanhar para ver o histórico completo de retransmissão.

​

Retomar uma sessão existente

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

• Transferir uma sessão Codex do laptop para o telefone — pedir ao agente para continuar de onde parou
• Continuar uma sessão de coding iniciada interativamente na CLI, agora de forma headless por meio do agente
• Retomar um trabalho interrompido por reinicialização do gateway ou timeout por inatividade

• resumeSessionId exige runtime: "acp" — retorna erro se usado com o runtime de subagente.
• resumeSessionId restaura o histórico da conversa ACP no upstream; thread e mode continuam valendo normalmente para a nova sessão OpenClaw que você está criando, então mode: "session" ainda exige thread: true.
• O agente de destino precisa oferecer suporte a session/load (Codex e Claude Code oferecem).
• Se o id da sessão não for encontrado, o spawn falha com um erro claro — não há fallback silencioso para uma nova sessão.

​

Smoke test para operadores

1. Verifique a versão/commit do gateway implantado no host de destino.
2. Confirme que o código-fonte implantado inclui a aceitação de linhagem ACP em src/gateway/sessions-patch.ts (subagent:* or acp:* sessions).
3. Abra uma sessão bridge ACPX temporária para um agente ativo (por exemplo razor(main) em jpclawhq).
4. Peça a esse agente para chamar sessions_spawn com:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifique se o agente relata:
   • accepted=yes
   • um childSessionKey real
   • nenhum erro de validador
6. Limpe a sessão bridge ACPX temporária.

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

• Mantenha esse smoke test em mode: "run" a menos que você esteja testando intencionalmente sessões ACP persistentes vinculadas a thread.
• Não exija streamTo: "parent" para o gate básico. Esse caminho depende de capacidades da sessão/solicitante e é uma verificação de integração separada.
• Trate o teste de mode: "session" vinculado a thread como uma segunda etapa mais rica de integração a partir de uma thread real do Discord ou tópico do Telegram.

​

Compatibilidade com sandbox

• Se a sessão solicitante estiver em sandbox, spawns ACP serão bloqueados tanto para sessions_spawn({ runtime: "acp" }) quanto para /acp spawn.
  • Erro: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn com runtime: "acp" não oferece suporte a sandbox: "require".
  • Erro: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

A partir do comando /acp

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

• --mode persistent|oneshot
• --bind here|off
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Resolução de alvo de sessão

1. Argumento explícito de alvo (ou --session para /acp steer)
   • tenta key
   • depois session id em formato UUID
   • depois label
2. Binding da thread atual (se esta conversa/thread estiver vinculada a uma sessão ACP)
3. Fallback para a sessão atual do solicitante

​

Modos de bind no spawn

• --bind here é o caminho mais simples para operadores para “fazer este canal ou chat ser apoiado por Codex”.
• --bind here não cria uma thread filha.
• --bind here está disponível apenas em canais que expõem suporte a binding da conversa atual.
• --bind e --thread não podem ser combinados na mesma chamada de /acp spawn.

​

Modos de thread no spawn

• Em superfícies sem suporte a binding de thread, o comportamento padrão é efetivamente off.
• Spawn vinculado a thread exige suporte da política do canal:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Use --bind here quando quiser fixar a conversa atual sem criar uma thread filha.

​

Controles ACP

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

​

Cookbook de comandos ACP

​

Mapeamento de opções de runtime

• /acp model <id> mapeia para a chave de configuração de runtime model.
• /acp permissions <profile> mapeia para a chave de configuração de runtime approval_policy.
• /acp timeout <seconds> mapeia para a chave de configuração de runtime timeout.
• /acp cwd <path> atualiza diretamente o override de cwd do runtime.
• /acp set <key> <value> é o caminho genérico.
  • Caso especial: key=cwd usa o caminho de override de cwd.
• /acp reset-options limpa todos os overrides de runtime da sessão de destino.

​

Suporte a harnesses acpx (atual)

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

Configuração necessária

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

​

Configuração de plugin para backend acpx

/acp doctor

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

openclaw plugins install ./path/to/local/acpx-plugin

/acp doctor

​

Configuração de comando e versão do acpx

1. O comando usa por padrão node_modules/.bin/acpx local ao plugin dentro do pacote do plugin ACPX.
2. A versão esperada usa por padrão o pin da extensão.
3. A inicialização registra imediatamente o backend ACP como não pronto.
4. Um job de verificação em segundo plano valida acpx --version.
5. Se o binário local ao plugin estiver ausente ou incompatível, ele executa: npm install --omit=dev --no-save acpx@<pinned> e valida novamente.

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• command aceita caminho absoluto, caminho relativo ou nome de comando (acpx).
• Caminhos relativos são resolvidos a partir do diretório de workspace do OpenClaw.
• expectedVersion: "any" desabilita a correspondência estrita de versão.
• Quando command aponta para um binário/caminho personalizado, a instalação automática local ao plugin é desabilitada.
• A inicialização do OpenClaw continua sem bloqueio enquanto a verificação de integridade do backend é executada.

​

Instalação automática de dependências

​

Bridge MCP de tools de plugin

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

• Injeta um servidor MCP integrado chamado openclaw-plugin-tools no bootstrap da sessão ACPX.
• Expõe tools de plugin já registradas por plugins OpenClaw instalados e habilitados.
• Mantém o recurso explícito e desativado por padrão.

• Isso expande a superfície de tools do harness ACP.
• Agentes ACP obtêm acesso apenas a tools de plugin já ativas no gateway.
• Trate isso como o mesmo limite de confiança que permitir que esses plugins executem no próprio OpenClaw.
• Revise os plugins instalados antes de habilitar.

​

Configuração de permissões

​

permissionMode

​

nonInteractivePermissions

​

Configuração

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Importante: Atualmente, o OpenClaw usa por padrão permissionMode=approve-reads e nonInteractivePermissions=fail. Em sessões ACP sem interação, qualquer escrita ou exec que dispare um prompt de permissão pode falhar com AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Se você precisar restringir permissões, defina nonInteractivePermissions como deny para que as sessões degradem de forma elegante em vez de falhar.

​

Solução de problemas