roteador-acp

Roteador de Harness ACP

Quando a intenção do usuário for "executar isso no Claude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Grok Build/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode (harness ACP)", não use runtime de subagente ou PTY scraping. Roteie através de fluxos com reconhecimento ACP.

Codex é especial: a vinculação e controle de conversas/chat comuns devem usar o plugin nativo do servidor de aplicativos Codex (/codex bind, /codex threads, /codex resume) em vez do caminho ACP padrão. Use ACP para Codex apenas quando o usuário nomear explicitamente ACP//acp/acpx, ou ao gerar sessões filhas em segundo plano através de sessions_spawn quando um runtime Codex nativo ainda não estiver disponível.

Detecção de intenção

Acione esta skill quando o usuário pedir ao OpenClaw para:

• executar algo no Claude Code / Cursor / Copilot / OpenClaw / OpenCode / Gemini / Grok Build / Qwen / Kiro / Kimi / iFlow / Droid / Kilocode
• executar Codex explicitamente através de ACP, /acp ou acpx
• continuar trabalho de harness existente
• repassar instruções para um harness de codificação externo
• manter uma conversa de harness externa em uma conversa do tipo thread

Pré-verificação obrigatória para solicitações de thread de agente de código:

• Antes de criar qualquer thread para trabalho de harness ACP, leia esta skill primeiro na mesma rodada.
• Após a leitura, siga o Caminho do runtime ACP do OpenClaw abaixo; não use message(action="thread-create") para criação de thread de harness ACP.

Seleção de modo

Escolha um destes caminhos:

1. Caminho do runtime ACP do OpenClaw (padrão): use sessions_spawn / ferramentas de runtime ACP.
2. Caminho direto acpx (telefone sem fio): use a CLI acpx através de exec para conduzir a sessão de harness diretamente.

Use acpx direto quando uma destas condições for verdadeira:

• o usuário pede explicitamente pela condução direta via acpx
• o caminho do runtime/plugin ACP está indisponível ou com problemas
• a tarefa é "apenas repassar prompts para o harness" e nenhum recurso de ciclo de vida do ACP do OpenClaw é necessário

Não use:

• runtime subagents para controle de harness
• delegação de comando /acp como um requisito para o usuário
• PTY scraping de CLIs de harness ACP suportados quando acpx estiver disponível

Mapeamento de AgentId

Use estes padrões quando o usuário nomear um harness diretamente:

• "openclaw" -> agentId: "openclaw"
• "claude" ou "claude code" -> agentId: "claude"
• "codex" -> agentId: "codex" apenas para solicitações ACP/acpx explícitas ou criação de runtime ACP em segundo plano
• "copilot" ou "github copilot" -> agentId: "copilot"
• "cursor" ou "cursor cli" -> agentId: "cursor"
• "droid" ou "factory droid" -> agentId: "droid"
• "opencode" -> agentId: "opencode"
• "gemini" ou "gemini cli" -> agentId: "gemini"
• "grok build" ou "grok-build" -> agentId: "grok-build"
• "iflow" -> agentId: "iflow"
• "kilocode" -> agentId: "kilocode"
• "kimi" ou "kimi cli" -> agentId: "kimi"
• "kiro" ou "kiro cli" -> agentId: "kiro"
• "qwen" ou "qwen code" -> agentId: "qwen"

Estes padrões correspondem aos aliases integrados atuais do acpx.

grok-build é um alvo de agente ACPX, não o ID de modelo xAI xai/grok-build-0.1. Roteie grok-build através de agentId; use a ref xAI totalmente qualificada apenas em um campo model do OpenClaw.

Se a política rejeitar o ID escolhido, relate claramente o erro de política e pergunte pelo ID de agente ACP permitido.

Caminho do runtime ACP do OpenClaw

Comportamento obrigatório:

1. Para solicitações de criação de thread de harness ACP, leia esta skill primeiro na mesma rodada antes de chamar ferramentas.
2. Use sessions_spawn com:
   • runtime: "acp"
   • thread: true
   • mode: "session" (a menos que o usuário queira explicitamente uma execução única)
3. Para criação de thread de harness ACP, não use message com action=thread-create; sessions_spawn é o único caminho para criação de threads.
4. Coloque o trabalho solicitado em task para que a sessão ACP o receba imediatamente.
5. Defina agentId explicitamente, a menos que o agente padrão ACP seja conhecido.
6. Não peça ao usuário para executar comandos de barra ou CLI quando este caminho funcionar diretamente.

Exemplo:

Usuário: "cria uma sessão ACP de teste no codex em uma thread e diz pra ela falar oi"

Chamada:

{
  "task": "Diga oi.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

Política de recuperação de criação de thread

Quando o usuário pedir para iniciar um harness de codificação em uma thread, trate isso como uma solicitação de runtime ACP e tente satisfazê-la de ponta a ponta.

Comportamento obrigatório quando o backend ACP estiver indisponível:

1. Não peça imediatamente ao usuário para escolher um caminho alternativo.
2. Primeiro, tente o reparo local automático:
   • verifique se o acpx fixado local do plugin está instalado no pacote do plugin ACPX
   • verifique ${ACPX_CMD} --version
3. Após reinstalação/reparo, reinicie o gateway e ofereça explicitamente executar essa reinicialização para o usuário.
4. Repita a tentativa de criação de thread ACP uma vez após o reparo.
5. Somente se o reparo + nova tentativa falharem, reporte o erro concreto e então ofereça opções de fallback.

Ao oferecer fallback, mantenha ACP em primeiro lugar:

• Opção 1: repetir a criação ACP após mostrar a etapa exata que falhou
• Opção 2: fluxo direto acpx telefone-sem-fio

Não use o runtime de subagente como padrão para estas solicitações.

Política de instalação e versão do ACPX (caminho acpx direto)

Para este repositório, chamadas diretas acpx devem seguir a mesma política de versão fixada que o pacote de extensão @openclaw/acpx.

1. Prefira o binário local do plugin, não o PATH global:
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx
2. Resolva a versão fixada a partir da dependência da extensão:
   • node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"
3. Se o binário estiver ausente ou a versão não corresponder, instale a versão fixada local do plugin:
   • cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<pinnedVersion>
4. Verifique antes de usar:
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version
5. Se a instalação/reparo alterou artefatos do ACPX, reinicie o gateway e ofereça executar a reinicialização.
6. Não execute npm install -g acpx a menos que o usuário peça explicitamente por uma instalação global.

Defina e reutilize:

ACPX_PLUGIN_ROOT="<bundled-acpx-plugin-root>"
ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"

Caminho direto acpx ("telefone sem fio")

Use este caminho para conduzir sessões de harness sem /acp ou runtime de subagente.

Regras

1. Use comandos exec que chamam ${ACPX_CMD}.
2. Reutilize um nome de sessão estável por conversa para que prompts de acompanhamento permaneçam no mesmo contexto de harness.
3. Prefira --format quiet para texto de assistente limpo a ser repassado ao usuário.
4. Use exec (único) apenas quando o usuário quiser comportamento de execução única.
5. Mantenha o diretório de trabalho explícito (--cwd) quando o escopo da tarefa depender do contexto do repositório.

Nomeação de sessão

Use um nome estável, por exemplo:

• oc-<harness>-<conversationId>

Onde conversationId é o ID da thread quando disponível, caso contrário o ID do canal/conversa.

Modelos de comando

Sessão persistente (criar se não existir, então enviar prompt):

${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>

${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"

Execução única:

${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"

Cancelar rodada em andamento:

${ACPX_CMD} codex cancel -s oc-codex-<conversationId>

Fechar sessão:

${ACPX_CMD} codex sessions close oc-codex-<conversationId>

Aliases de harness no acpx

• claude
• codex
• copilot
• cursor
• droid
• gemini
• grok-build
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

Comandos de adaptador integrados no acpx

Os padrões são:

• openclaw -> openclaw acp
• claude -> bundled @agentclientprotocol/[email protected]
• codex -> bundled @agentclientprotocol/[email protected] através do wrapper CODEX_HOME isolado do OpenClaw
• copilot -> copilot --acp --stdio
• cursor -> cursor-agent acp
• droid -> droid exec --output-format acp
• gemini -> gemini --acp
• grok-build -> grok agent stdio
• iflow -> iflow --experimental-acp
• kilocode -> npx -y @kilocode/cli acp
• kimi -> kimi acp
• kiro -> kiro-cli acp
• opencode -> npx -y opencode-ai acp
• qwen -> qwen --acp

Se ~/.acpx/config.json sobrescrever agents, essas substituições substituem os padrões. Se sua instalação local do Cursor ainda expõe ACP como agent acp, defina essa substituição explicitamente como o agente cursor.

Tratamento de falhas

• acpx: comando não encontrado:
  • para solicitações ACP de criação de thread, instale imediatamente o acpx fixado local do plugin no pacote do plugin ACPX
  • reinicie o gateway após a instalação e ofereça executar a reinicialização automaticamente
  • então tente novamente uma vez
  • não peça permissão de instalação primeiro, a menos que a política exija explicitamente
  • não instale acpx global a menos que solicitado explicitamente
• comando de adaptador ausente (por exemplo, claude-agent-acp não encontrado):
  • para solicitações ACP de criação de thread, primeiro restaure os padrões integrados removendo as substituições de agente ~/.acpx/config.json defeituosas
  • então tente novamente uma vez antes de oferecer fallback
  • se o usuário quiser substituições baseadas em binário, instale exatamente o binário do adaptador configurado
• NO_SESSION: execute ${ACPX_CMD} <agent> sessions new --name <sessionName> e repita o prompt.
• fila ocupada: espere pela conclusão (padrão) ou use --no-wait quando o comportamento assíncrono for explicitamente desejado.

Repasse de saída

Ao repassar para o usuário, retorne a saída final do texto do assistente do resultado do comando acpx. Evite repassar ruído bruto de ferramentas locais, a menos que o usuário tenha pedido logs detalhados.