ACP

​

O que isto não é

• o editor/cliente quer se comunicar via ACP com o OpenClaw: use openclaw acp
• o OpenClaw deve iniciar Codex/Claude/Gemini como um ambiente ACP: use /acp spawn e Agentes ACP

​

Matriz de compatibilidade

​

Limitações conhecidas

• loadSession reproduz o histórico completo do registro de eventos ACP apenas para sessões criadas pela ponte. Sessões antigas ou sem registro usam o histórico da conversa como alternativa e não reconstroem chamadas históricas de ferramentas nem avisos do sistema.
• Se vários clientes ACP compartilharem a mesma chave de sessão do Gateway, o roteamento de eventos e cancelamentos funciona com melhor esforço, em vez de ser estritamente isolado por cliente. Prefira as sessões isoladas padrão acp-bridge:<uuid> quando precisar de turnos locais do editor claramente separados.
• Os estados de parada do Gateway são convertidos em motivos de parada do ACP, mas esse mapeamento é menos expressivo do que o de um ambiente de execução totalmente nativo de ACP.
• Os controles de sessão apresentam um subconjunto específico das opções do Gateway: nível de pensamento, detalhamento das ferramentas, raciocínio, detalhes de uso e ações elevadas. A seleção de modelo e os controles do host de execução não são expostos como opções de configuração do ACP.
• session_info_update e usage_update são derivados de instantâneos das sessões do Gateway, não da contabilização em tempo real de um ambiente de execução nativo de ACP. O uso é aproximado, não inclui dados de custo e só é emitido quando o Gateway marca os dados totais de tokens como atuais.
• Os dados de acompanhamento das ferramentas funcionam com melhor esforço: a ponte apresenta caminhos de arquivos que aparecem em argumentos/resultados conhecidos das ferramentas, mas não emite terminais ACP nem diffs estruturados de arquivos.
• O retransmissão de aprovações de execução é limitada ao turno ativo do prompt ACP; aprovações de outras sessões do Gateway são ignoradas.

​

Uso

openclaw acp

# Gateway remoto
openclaw acp --url wss://gateway-host:18789 --token <token>

# Gateway remoto (token de arquivo)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Anexar a uma chave de sessão existente
openclaw acp --session agent:main:main

# Anexar por rótulo (deve existir previamente)
openclaw acp --session-label "support inbox"

# Redefinir a chave de sessão antes do primeiro prompt
openclaw acp --session agent:main:main --reset-session

​

Cliente ACP (depuração)

openclaw acp client

# Direcionar a ponte iniciada para um Gateway remoto
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Substituir o comando do servidor (padrão: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

• A aprovação automática é baseada em uma lista de permissões e se aplica somente a IDs confiáveis de ferramentas principais.
• A aprovação automática de read é limitada ao diretório de trabalho atual (--cwd, quando definido).
• O ACP aprova automaticamente apenas classes restritas somente leitura: chamadas read limitadas ao cwd ativo, além de ferramentas de pesquisa somente leitura (search, web_search, memory_search). Ferramentas desconhecidas ou não pertencentes ao núcleo, leituras fora do escopo, ferramentas capazes de executar comandos, ferramentas do plano de controle, ferramentas que realizam alterações e fluxos interativos sempre exigem aprovação explícita no prompt.
• O toolCall.kind fornecido pelo servidor é tratado como metadado não confiável, não como fonte de autorização.
• Esta política da ponte ACP é separada das permissões do ambiente ACPX. Se você executar o OpenClaw por meio do backend acpx, plugins.entries.acpx.config.permissionMode=approve-all será o interruptor emergencial “yolo” para essa sessão do ambiente.

​

Teste de fumaça do protocolo

{
  "initialize": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "resume": {},
        "close": {}
      }
    }
  },
  "listSessions": {
    "sessions": [
      {
        "sessionId": "agent:main:acp-smoke",
        "cwd": "/path/to/workspace",
        "_meta": {
          "sessionKey": "agent:main:acp-smoke",
          "kind": "direct"
        }
      }
    ],
    "nextCursor": null
  },
  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}

​

Como usar

1. Certifique-se de que o Gateway esteja em execução (local ou remoto).
2. Configure o destino do Gateway (configuração ou flags).
3. Configure sua IDE para executar openclaw acp via stdio.

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

openclaw acp --url wss://gateway-host:18789 --token <token>
# preferencial para a segurança do processo local
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

​

Seleção de agentes

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

​

Uso pelo acpx (Codex, Claude e outros clientes ACP)

1. Execute o Gateway e verifique se a ponte ACP consegue acessá-lo.
2. Direcione acpx openclaw para openclaw acp.
3. Defina como destino a chave de sessão do OpenClaw que você quer que o agente de programação use.

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

​

Configuração do editor Zed

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

​

Mapeamento de sessões

• --session <key>: usa uma chave de sessão específica do Gateway.
• --session-label <label>: resolve uma sessão existente pelo rótulo.
• --reset-session: gera um novo ID de sessão para essa chave (mesma chave, nova transcrição).

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

​

Opções

• --url <url>: URL WebSocket do Gateway (o padrão é gateway.remote.url quando configurado).
• --token <token>: token de autenticação do Gateway.
• --token-file <path>: lê o token de autenticação do Gateway de um arquivo.
• --password <password>: senha de autenticação do Gateway.
• --password-file <path>: lê a senha de autenticação do Gateway de um arquivo.
• --session <key>: chave de sessão padrão.
• --session-label <label>: rótulo de sessão padrão a ser resolvido.
• --require-existing: falha se a chave ou o rótulo da sessão não existir.
• --reset-session: redefine a chave da sessão antes do primeiro uso.
• --no-prefix-cwd: não adiciona o diretório de trabalho como prefixo aos prompts.
• --provenance <off|meta|meta+receipt>: inclui metadados ou recibos de proveniência do ACP.
• --verbose, -v: registro detalhado em stderr.

• --token e --password podem ficar visíveis nas listas de processos locais em alguns sistemas. Prefira --token-file/--password-file ou variáveis de ambiente (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• A resolução da autenticação do Gateway segue o contrato compartilhado usado por outros clientes do Gateway:
  • modo local: variáveis de ambiente (OPENCLAW_GATEWAY_*) e depois gateway.auth.*, recorrendo a gateway.remote.* somente quando gateway.auth.* não estiver definido (uma SecretRef local configurada, mas não resolvida, falha de forma segura em vez de recorrer silenciosamente a outra opção)
  • modo remoto: gateway.remote.*, com fallback para variáveis de ambiente/configuração de acordo com as regras de precedência remota
  • --url é seguro para substituição e não reutiliza credenciais implícitas da configuração ou das variáveis de ambiente; passe --token/--password explicitamente (ou as variantes de arquivo)

​

Opções de acp client

• --cwd <dir>: diretório de trabalho da sessão ACP.
• --server <command>: comando do servidor ACP (padrão: openclaw).
• --server-args <args...>: argumentos adicionais passados ao servidor ACP.
• --server-verbose: habilita o registro detalhado no servidor ACP.
• --verbose, -v: registro detalhado do cliente.
• openclaw acp client define OPENCLAW_SHELL=acp-client no processo da ponte iniciado, o que pode ser usado para regras de shell/perfil específicas do contexto.

​

Relacionados

• Referência da CLI
• Agentes ACP