​

Agentes ACP

​

Qual página eu quero?

​

Isso funciona imediatamente?

• Instalações novas agora vêm com o plugin de runtime acpx incluído e habilitado por padrão.
• O plugin acpx incluído prefere seu binário acpx fixado local ao plugin.
• Na inicialização, o OpenClaw faz probe desse binário e o autorepara, se necessário.
• Comece com /acp doctor se quiser uma verificação rápida de prontidão.

• Um adaptador do harness de destino pode ser buscado sob demanda com npx na primeira vez 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 adaptador na primeira execução podem falhar até que os caches sejam pré-aquecidos ou o adaptador seja instalado de outra forma.

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

​

Fluxo rápido do operador

1. Inicie uma sessão:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Trabalhe na conversa ou thread vinculada (ou mire essa chave de sessão explicitamente).
3. Verifique o estado do runtime:
   • /acp status
4. Ajuste as opções de runtime conforme necessário:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Direcione 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 vínculos)

​

Início rápido para pessoas

• “Vincule este canal do Discord ao Codex.”
• “Inicie uma sessão persistente do Codex em uma thread aqui e mantenha o foco.”
• “Execute isto 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, depois mantenha os acompanhamentos nessa mesma thread.”

1. Escolher runtime: "acp".
2. Resolver o alvo de harness solicitado (agentId, por exemplo codex).
3. Se for solicitada vinculação à conversa atual e o canal ativo a suportar, vincular a sessão ACP a essa conversa.
4. Caso contrário, se for solicitada vinculação à thread e o canal atual a suportar, vincular a sessão ACP à thread.
5. Rotear mensagens de acompanhamento vinculadas para essa mesma sessão ACP até perder o foco/fechar/expirar.

​

ACP versus subagentes

​

Como o ACP executa o Claude Code

1. Plano de controle de sessão ACP do OpenClaw
2. plugin de runtime acpx incluído
3. Adaptador ACP do Claude
4. Maquinário de runtime/sessão do lado do Claude

• Claude via ACP é uma sessão de harness com controles ACP, retomada de sessão, rastreamento de tarefa em segundo plano e vinculação opcional a conversa/thread.
• Backends de CLI são runtimes locais separados de fallback somente de texto. Veja CLI Backends.

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

​

Sessões vinculadas

​

Vínculos à conversa atual

• O OpenClaw continua sendo o dono do transporte do canal, autenticação, segurança e entrega.
• A conversa atual é fixada na chave da sessão ACP iniciada.
• Mensagens de acompanhamento nessa conversa são roteadas para a mesma sessão ACP.
• /new e /reset redefinem a mesma sessão ACP vinculada in place.
• /acp close fecha a sessão e remove o vínculo com a 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 iniciando trabalho novo. O vínculo anexa essa sessão à conversa atual.
• --bind here não cria sozinho uma thread filha no Discord nem um tópico no 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 do chat e não implica uma nova thread de mensagens.
• Se você iniciar 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 o caminho herdado do workspace estiver ausente (ENOENT/ENOTDIR), o OpenClaw recorre ao 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 falando (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 roteia
• thread/tópico filho: uma superfície extra opcional de mensagens criada somente por --thread ...
• workspace do runtime: o local no sistema de arquivos onde o harness é executado (cwd, checkout do repositório, workspace do backend)

• /acp spawn codex --bind here: mantenha este chat, inicie ou anexe uma sessão ACP do Codex e roteie 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 vínculo de chat acima, mas o Codex roda em /workspace/repo

• Canais de chat/mensagem que anunciam suporte a vinculação da conversa atual podem usar --bind here por meio do caminho compartilhado de vinculação de conversa.
• Canais com semântica personalizada de thread/tópico ainda podem fornecer canonização específica do canal por trás da mesma interface compartilhada.
• --bind here sempre significa “vincular a conversa atual in place”.
• Vínculos genéricos à conversa atual usam a store de vínculos compartilhada 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 in place. spawnAcpSessions só é necessário quando o OpenClaw precisa criar uma thread filha para --thread auto|here.
• Se o canal ativo não expuser vínculos ACP à conversa atual, o OpenClaw retorna uma mensagem clara de não compatibilidade.
• resume e perguntas de “nova sessão” são perguntas sobre sessão ACP, não sobre canal. Você pode reutilizar ou substituir o estado do runtime sem mudar a superfície atual do chat.

​

Sessões vinculadas à thread

• 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 ACP é entregue de volta na mesma thread.
• Perda de foco/fechamento/arquivamento/timeout por ociosidade ou expiração de idade máxima removem o vínculo.

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

​

Canais com suporte a thread

• Qualquer adaptador de canal que exponha capacidade de vínculo de sessão/thread.
• Suporte embutido atual:
  • threads/canais do Discord
  • tópicos do Telegram (tópicos de fórum em grupos/supergrupos e tópicos de DM)
• Plugins de canal podem adicionar suporte pela mesma interface de vínculo.

​

Configurações específicas do canal

​

Modelo de vínculo

• bindings[].type="acp" marca um vínculo 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 de DM/grupo BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Prefira chat_id:* ou chat_identifier:* para vínculos estáveis de grupo.
  • Chat de DM/grupo do iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Prefira chat_id:* para vínculos estáveis de grupo.
• bindings[].agentId é o id do agente OpenClaw proprietário.
• Substituições ACP opcionais 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 roteadas para a sessão ACP configurada.
• Em conversas vinculadas, /new e /reset redefinem a mesma chave de sessão ACP in place.
• Vínculos temporários de runtime (por exemplo criados por fluxos de foco em thread) ainda se aplicam 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 recorrem ao 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 tem como padrão subagent, 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 vinculada persistente.

• 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. Recorre a acp.defaultAgent se definido.
• thread (opcional, padrão false): solicita o fluxo de vínculo com thread quando compatível.
• mode (opcional): run (one-shot) ou session (persistente).
  • o padrão é run
  • se thread: true e o modo for omitido, o OpenClaw pode assumir comportamento persistente conforme o caminho de runtime
  • mode: "session" exige thread: true
• cwd (opcional): diretório de trabalho do runtime solicitado (validado pela política do backend/runtime). Se omitido, o spawn ACP herda o workspace do agente de destino quando configurado; caminhos herdados ausentes recorrem aos padrões do backend, enquanto erros reais de acesso são retornados.
• label (opcional): rótulo visível ao operador usado no texto de sessão/banner.
• resumeSessionId (opcional): retoma uma sessão ACP existente em vez de criar uma nova. O agente reproduz o histórico da 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, 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 do relay.

​

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 do 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 em modo headless por meio do seu agente
• Retomar um trabalho interrompido por reinicialização do gateway ou timeout por ociosidade

• resumeSessionId exige runtime: "acp" — retorna erro se usado com o runtime de subagente.
• 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 suportar session/load (Codex e Claude Code suportam).
• Se o id da sessão não for encontrado, o spawn falha com um erro claro — sem fallback silencioso para uma nova sessão.

​

Smoke test do operador

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"
   • tarefa: Reply with exactly LIVE-ACP-SPAWN-OK
5. Verifique se o agente informa:
   • accepted=yes
   • uma childSessionKey real
   • nenhum erro de validador
6. Faça a limpeza da 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 este smoke test em mode: "run" a menos que você esteja testando intencionalmente sessões ACP persistentes vinculadas à thread.
• Não exija streamTo: "parent" para o gate básico. Esse caminho depende de capacidades da sessão/solicitante e é uma verificação separada de integração.
• Trate o teste de mode: "session" vinculado à thread como uma segunda etapa de integração mais rica 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 suporta 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 a chave
   • depois o id de sessão em formato UUID
   • depois o rótulo
2. Vínculo da thread atual (se esta conversa/thread estiver vinculada a uma sessão ACP)
3. Fallback da sessão solicitante atual

​

Modos de vínculo no spawn

• --bind here é o caminho mais simples para o operador em “faça este canal ou chat ser respaldado por Codex”.
• --bind here não cria uma thread filha.
• --bind here só está disponível em canais que expõem suporte a vínculo com a conversa atual.
• --bind e --thread não podem ser combinados na mesma chamada /acp spawn.

​

Modos de thread no spawn

• Em superfícies sem vínculo de thread, o comportamento padrão efetivamente é off.
• Spawn vinculado à 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

​

Livro de receitas de comandos ACP

​

Mapeamento de opções de runtime

• /acp model <id> é mapeado para a chave de configuração de runtime model.
• /acp permissions <profile> é mapeado para a chave de configuração de runtime approval_policy.
• /acp timeout <seconds> é mapeado para a chave de configuração de runtime timeout.
• /acp cwd <path> atualiza diretamente a substituição de cwd do runtime.
• /acp set <key> <value> é o caminho genérico.
  • Caso especial: key=cwd usa o caminho de substituição de cwd.
• /acp reset-options limpa todas as substituições de runtime para a sessão de destino.

​

Suporte a harness acpx (atual)

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

​

Configuração obrigatória

{
  acp: {
    enabled: true,
    // Opcional. O padrão é true; defina false para pausar o despacho ACP mantendo os controles /acp.
    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 do 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 tem como padrão o node_modules/.bin/acpx local ao plugin dentro do pacote do plugin ACPX.
2. A versão esperada tem como padrão o pin da extensão.
3. Na inicialização, o backend ACP é registrado imediatamente como não pronto.
4. Um job de garantia em segundo plano verifica 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 verifica novamente.

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

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

​

Instalação automática de dependências

​

Ponte MCP de ferramentas de plugin

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

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

• Isso amplia a superfície de ferramentas do harness ACP.
• Agentes ACP só obtêm acesso a ferramentas de plugins já ativos no gateway.
• Trate isso como o mesmo limite de confiança que permitir que esses plugins sejam executados no próprio OpenClaw.
• Revise os plugins instalados antes de habilitar.

​

Configuração de timeout do runtime

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

​

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: No momento, o OpenClaw usa por padrão permissionMode=approve-reads e nonInteractivePermissions=fail. Em sessões ACP sem interação, qualquer gravação 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 tenham degradação graciosa em vez de travar.

​

Solução de problemas