tenequm/acpx-faq

FAQ do acpx

Execute agentes de codificação de forma headless através do acpx (>= 0.19.3).

Autoridade de sintaxe

A sintaxe vem do binário, não deste arquivo. acpx --skill show acpx é a referência do fornecedor (~43k caracteres) e o desempate na forma do comando – NÃO o despeje na transcrição. Recupere nesta ordem:

1. acpx --help / acpx <cmd> --help – as flags que você está prestes a compor.
2. Um tópico: acpx --skill show acpx | rg -B2 -A12 '<term>', ou uma seção: acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'.
3. Criando algo novo (um fluxo, um runtime embutido): despeje UMA VEZ em um arquivo temporário e pesquise nesse arquivo.

Este arquivo não repete nada que a referência cobre. Ele carrega apenas o que falta na referência: códigos de saída, semântica de falha, armadilhas e receitas por agente. Se uma dúvida de sintaxe não for respondida aqui, ela está respondida lá – vá buscá-la, nunca adivinhe uma flag. Os docs/ do repositório (códigos de saída, controle de sessão, observação de sessão, permissões, configuração) cobrem parte do que a referência fornecida omite.

Quando usar esta via

acpx é a via de execução headless fora do processo: outro agente, fornecedor ou conta, dirigido a partir de um script ou de outro agente, em um terminal simples, ssh ou cron. A ramificação dentro da sessão permanece na ferramenta de subagente do próprio harness.

Invariantes

1. Flags globais precedem o subcomando do agente (--cwd, --model, --approve-all, --agent, --format, --timeout, --ttl, --mcp-config). O formulário de prompt aceita apenas -s, --no-wait, -f (e exec também --config-option); outros subcomandos carregam os seus próprios (sessions watch --cursor, sessions export|import --cwd). Uma flag global após o agente sai com código 1 e error: unknown option; uma flag errada antes do agente sai com código 2.

2. -s <nome> nunca cria uma sessão. Ela resolve uma, caminhando de --cwd para cima até o .git mais próximo – um diretório ou arquivo, então cada worktree e submódulo é seu próprio limite; fora do git apenas o --cwd exato é verificado. Sem correspondência sai com código 4. Crie primeiro com sessions ensure --name <n> no mesmo diretório.

3. status não é um sinal de virada. Ele sonda o processo proprietário da fila, nunca o agente, e continua dizendo running depois que a virada terminou. Nunca baseie automação nele.

4. Flags de permissão não são uma sandbox.

   • claude: o adaptador inicia em permissions.defaultMode das configurações do Claude (acceptEdits / auto aprova edições sem perguntar). Apenas o que esse modo escalona atinge o acpx como uma solicitação de permissão – --deny-all recusa essas (código de saída 5), mas uma edição aprovada automaticamente nunca pergunta.
   • codex: escritas dentro da sua sandbox de workspace (raiz em --cwd, mais diretórios temporários) não geram solicitação, então --deny-all ainda escreve; fora dela falha com Operation not permitted – incluindo o gitdir de um worktree vinculado, então uma via em sandbox em um git worktree não pode commitar (index.lock: Operation not permitted). A rede está desligada a menos que config.toml habilite network_access. --approve-all não altera o modo do adaptador; INITIAL_AGENT_MODE=read-only|agent|agent-full-access na inicialização, ou codex set-mode agent-full-access -s <n> em uma sessão ativa, altera.
   • --allowed-tools / --max-turns atingem apenas o claude (e qoder); codex e agy os ignoram. --allowed-tools pré-aprova e nunca restringe: --help com "" for no tools significa sem aprovações, não sem ferramentas.

   O controle real do sistema de arquivos é qual --cwd você fornece.

5. [done] end_turn e código de saída 0 não são prova de sucesso. Uma interrupção por filtro de conteúdo, uma falha ao carregar MCP, um erro de API (um 401 durante uma renovação de token, uma rejeição de modelo 400) ou uma virada truncada terminam assim. Leia o fluxo, ou exija que o agente escreva um arquivo de resultado que você possa verificar. Antes de uma ramificação, um exec barato ("Reply OK") por agente e modelo captura erros de autenticação e modelo – codex e agy rejeitam um --model não anunciado antes da virada, claude avisa e encaminha.

6. Uma sessão persistente mantém uma pilha de processos residente apenas enquanto está ocupada ou quente. Cada prompt -s elege um proprietário de fila segurando npm exec -> node <adaptador> -> <agente> (mais os servidores MCP do agente), aproximadamente 550-650 MB antes do MCP. Após o TTL ocioso (padrão 300s) o proprietário sai e a sessão permanece retomável; o próximo prompt a reinicia. sessions close encerra a tarefa – encadeie-a na linha de lançamento (veja Por agente) para que a desmontagem nunca dependa de alguém lembrar; --ttl 0 remove a autodestruição. Veja Desmontagem.

Por agente

Envio único: sessions ensure && prompt && sessions close, uma chamada encadeada. Uma sessão nomeada por tarefa, um prompt, fechada quando o arquivo de resultado é lido. O encadeamento && torna a desmontagem mecânica – nada coleta registros abertos, e órfãos vêm de fechamentos não encadeados – enquanto uma virada que falha com código diferente de zero (timeout 3, permissão 5) pula o fechamento por conta própria, deixando a sessão aberta para recuperação (veja Conversando com uma sessão ativa). Uma virada cancelada externamente ainda sai com 0, então o arquivo de resultado, não o código de saída, é a verificação de sucesso (invariante 5). Não estacione uma sessão para acompanhamentos esperados: o estado de um bloqueador vive fora da conversa (credenciais são no nível da máquina, parciais pertencem ao arquivo de resultado) – responda com uma sessão nova alimentada com o resumo mais esse arquivo. Retrabalho – uma correção, revisão ou polimento da saída de uma sessão – também recebe uma sessão nova: um agente relendo seu próprio contexto perde o que olhos novos pegam. Nunca --no-wait em uma sessão cuja linha de lançamento carrega o fechamento: o desligamento do proprietário descarta prompts pendentes silenciosamente e cancela a virada ativa (verificado 0.19.4); um prompt bloqueante antes do fechamento é seguro. Use exec para uma resposta sem estado sem registro que valha a pena manter (um pré-voo "Reply OK"). As sessões são chaveadas por comando do agente + cwd + nome; dê a cada executor paralelo seu próprio nome e, quando ele escrever arquivos, seu próprio diretório (idealmente um worktree).

Os adaptadores são executados através de npm exec a menos que o binário do adaptador (claude-agent-acp, codex-acp) esteja no PATH – essa cópia prevalece sobre o fallback do pacote, e atualizar o acpx nunca a atualiza. Um HOME novo por trabalho os baixa novamente (centenas de MB cada); compartilhe um npm_config_cache. No macOS, um HOME novo também oculta o Keychain de login: o adaptador do claude falha com RUNTIME: Unable to validate model: Could not resolve authentication method – mantenha HOME. O cache do npx também reutiliza construções obsoletas – fixe versões exatas dos adaptadores em ~/.acpx/config.json (agents.<nome>.argv). Uma fixação congela quais IDs de modelo funcionam, e alterá-la troca as chaves das sessões (veja Sessões).

Os executores herdam os arquivos de instrução global do usuário (~/.claude/CLAUDE.md do claude, AGENTS.md global do codex). Uma regra como "pergunte antes de editar" termina uma virada headless em uma pergunta sem trabalho feito – abra cada resumo com "aja agora; não pare para perguntar ou termine em uma pergunta". Um executor que lê "use um executor fora do processo" lá pode lançar uma via acpx aninhada no mesmo checkout – adicione "você é o executor; não delegue". Exclua ou renomeie o arquivo de resultado antigo antes de um relançamento (um polidor lê o obsoleto), e dê às vias paralelas seus próprios caminhos e portas temporários – worktrees separados não isolam /tmp.

Eles também herdam o ambiente do lançador, e o zsh do codex relê $ZDOTDIR/.zshenv (padrão ~/.zshenv) para cada comando – desdefinir um segredo no lançador não o mantém fora, e o que o shell imprime vai para os arquivos de rollout em ~/.codex/sessions.

agy / Antigravity

O acpx antigravity embutido (0.17.1+) executa agy_acp_server.par do PATH, e a cópia que o Antigravity instala em ~/.local/lib/antigravity-acp/ não está no PATH – o acpx antigravity simples sai com 1 e Failed to spawn agent command: agy_acp_server.par. Adicione esse diretório ao PATH, defina agents.antigravity.argv, ou use --agent <caminho>. O agente gemini embutido é a CLI pública do Gemini – um produto diferente. O .par vem da instalação do Antigravity ou do arquivo oficial do registro ACP; mantenha-o junto com seu auxiliar localharness_external da mesma versão (um auxiliar ausente apenas registra Localharness not found. e continua), ou aponte ANTIGRAVITY_HARNESS_PATH para ele. Nem acpx nem agy update atualizam o .par: compare seu --version Build label: com o registro ACP e troque ambos os arquivos juntos (o auxiliar instalado é somente leitura – rm -f antes de copiar o novo).

D=/caminho/absoluto/real                              # deve existir: raízes resolvem via realpath
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
     --cwd "$D" --model gemini-3.8-flash --approve-all --timeout 1800 \
     exec "Execute $D/brief.md. Escreva seu relatório em $D/report.md."

• --approve-all é obrigatório. Sem ele, cada escrita é recusada: código de saída 5 (ou uma paralisação para o código 3), com [done] end_turn ainda impresso e nenhum relatório.

• Perguntas de escolha fixa fazem o prompt falhar com código de saída 5 mesmo sob --approve-all (linha final Antigravity requested a user answer...) – para lançamentos --agent também. acpx falha a pergunta de escolha fixa de qualquer agente dessa forma (PERMISSION_PROMPT_UNAVAILABLE); agy é onde isso morde. Escreva resumos que nunca precisem de uma escolha do usuário.

• Use apenas IDs que a sessão ACP anuncia – um --model deliberadamente ruim imprime Available models: sem iniciar uma virada (servidor 1.4.5: gemini-4-argon, gemini-3.8-flash; os IDs com esforço gemini-3.7-flash-{low,medium,high} sumiram). agy models é uma lista diferente. Flash é adequado para trabalho em massa orientado por rubricas e é muito mais rápido, mas perde achados reais em trabalho de revisão/caça a bugs; use um modelo mais forte lá.

• agy lê arquivos irmãos sem solicitação – agentes compartilhando um diretório reproduzem a saída uns dos outros. Um diretório por agente, e verifique a soma de verificação de qualquer reexecução antes de acreditar em um número de acordo.

• Autenticação: precisa de auth.type em <GEMINI_HOME>/antigravity-acp/settings.json (uma vez):

  mkdir -p ~/.gemini/antigravity-acp
  echo '{"auth":{"type":"oauth-personal"}}' > ~/.gemini/antigravity-acp/settings.json
  

  Sem ele: imediatamente [error] RUNTIME: Authentication required (código de saída 1). Com ele, mas nunca logado: session/new bloqueia em um login via navegador até --timeout (código de saída 3) – faça login uma vez interativamente. A credencial do servidor é separada da CLI do agy: o Keychain do macOS (serviço gemini, conta antigravity-acp), ou <GEMINI_HOME>/antigravity-acp/acp_token.json fora do macOS ou com AGY_ACP_FORCE_FILE_STORAGE=1. GEMINI_HOME sozinho não isola a credencial do macOS. Um problema de autorização é do lado do servidor – não "corrija" mudando para gemini-api-key ou um projeto GCP (faturamento separado, não correções).

• Nunca passe um agente posicional com --agent – código de saída 2.

• Prompts de verificação: exija uma resposta simples e leia o log inteiro. agy roteia respostas para arquivos de artefato cerebral, então um tail não pode distinguir "sem ferramentas" de "respondido em outro lugar". Adicione "Não crie nenhum arquivo".

• agy esconde falhas de MCP dentro de uma virada de aparência bem-sucedida – código de saída 0, [done] end_turn, e toda a resposta é O servidor MCP '<nome>' falhou ao inicializar: .... Pesquise por failed to initialize.

• Prefira exec. Foi relatado que uma morte de servidor no meio de um checkpoint quebra uma conversa salva permanentemente (could not find doneCh for checkpoint); a única recuperação relatada é excluir ~/.gemini/antigravity-acp/conversations/<id>.db.

Linux / NixOS

O agente embutido adiciona o --uid= necessário por conta própria. NixOS adicionalmente precisa de um pacote de CAs, então aponte --agent (ou agents.antigravity.argv) para um wrapper (~/.local/bin/agy-acp-server):

#!/usr/bin/env bash
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
exec ~/.local/lib/antigravity-acp/agy_acp_server.par --uid= "$@"

Sem SSL_CERT_FILE o OpenSSL embutido no .par não tem caminhos de CA válidos; seu proxy local reporta 502 Bad Gateway: Failed to connect to backend API e a virada ainda termina [done] end_turn com código de saída 0 (invariante 5). O verdadeiro CERTIFICATE_VERIFY_FAILED aparece apenas sob --alsologtostderr.

codex

D=/caminho/abs
acpx --cwd "$D" codex sessions ensure --name trabalho            # idempotente; -s não pode criar
acpx --cwd "$D" codex set model gpt-6-astra -s trabalho
acpx --cwd "$D" codex set reasoning_effort high -s trabalho
{ acpx --cwd "$D" --approve-all --timeout 5400 --suppress-reads \
     codex -s trabalho 'Execute ./brief.md. Escreva seu relatório em ./report.md.' && \
  acpx --cwd "$D" codex sessions close trabalho; } > run.log 2>&1 &
# uma virada com falha pula o fechamento - re-prompt -s trabalho para recuperar, então feche você mesmo

Envio único: --model <id> exec --config-option reasoning_effort=low define modelo e esforço inline.

• O adaptador codex (@agentclientprotocol/codex-acp) flutua em ^1.1.5 – o comportamento pode mudar sem uma atualização do acpx, mas o 2.x de quebra está fora do alcance. Um adaptador obsoleto rejeita IDs de modelo mais novos: [error] RUNTIME: Invalid params em session/set_config_option (código de saída 1), ou um 400 model is not supported que ainda termina [done] end_turn, código de saída 0. Fixe um atual: {"agents":{"codex":{"argv":["npx","-y","@agentclientprotocol/[email protected]"]}}}. Uma fixação exata ainda flutua o binário codex dentro dele (2.5.0 depende de @openai/codex ^0.165.0). Os mesmos sintomas atingem um adaptador atual quando a conta não tem o modelo: a lista anunciada difere por conta – faça um pré-voo sob o próprio login da via.
• O filtro de conteúdo da OpenAI interrompe viradas benignas que terminam limpas ([done] end_turn, código de saída 0). Vocabulário como race / sweep / exploit / attack em um nome de arquivo, comentário ou prompt o aciona. Leia o final da transcrição antes de acreditar na conclusão; recupere re-promptando o mesmo -s <nome> (o contexto sobrevive a menos que a reconexão falhe – acpx então cai silenciosamente para session/new) com a solicitação ou contexto reformulado.
• codex encerra viradas longas com código de saída 3 (acpx timeout) na maioria dos limites (limite de caracteres da saída, não tempo real). O timeout interno do codex é mais curto que o limite do acpx; --timeout define o relógio do acpx, não o do codex, e se o codex terminar primeiro o acpx vê o final prematuro. O limite de saída do codex é mais baixo entre os agentes principais (~80k vs. ~200k do claude).
• codex respeita apenas --cwd para resolução de caminho; ele não executa cd. Prompts no estilo cd dir && cmd falham. Em vez disso, produza cmd com caminhos absolutos ou relativos a --cwd.

claude

D=/caminho/abs
acpx --cwd "$D" --agent claude --model claude-4.6-sonnet \
     -s trabalho 'Execute ./brief.md. Escreva seu relatório em ./report.md.'

• Sem --agent claude:
  • acpx padrão para acpx claude.
  • Fora de um repositório git o -s resolve o nome do sistema de arquivos relativo a --cwd.
  • -s trabalho sem --cwd explicitamente definido resolve para o CWD real (pwd) que é mais amplo; o comportamento difere de exec de modelo único onde --cwd é explícito. Defina --cwd explicitamente em todos os lugares.
• É improvável que funcione sem um ~/.claude/config.json ou variáveis de ambiente definidas pelo claude (como ANTHROPIC_BASE_URL). Execute claude interativamente uma vez, ou veja claude env.
• As viradas não são atômicas. Um erro de rede ou encerramento do processo deixa o trabalho do claude em um estado parcial; canalize para arquivos de resultado e não parafraseie as respostas – a saída do claude em sessões de diretório único é um append não determinístico de arquivos e não deve ser interpretada.
• Apenas claude-4.6-* e mais recentes suportam edição estendida (acima de 8k tokens) sem truncamento; modelos anteriores ou alternativos podem truncar os arquivos editados. Para --agent agy (antigravity) o modelo não importa; para claude, use a série mais recente.

outromodelo

acpx --agent '/caminho/para/algum_acp_server.par' --cwd /tmp --model modelo-outro exec "olá"

Conversando com uma sessão ativa

Para recuperar uma sessão deixada aberta (falha de permissão, timeout curto) sem um novo contexto, envie um novo prompt para ela. O prompt substitui a virada mais recente da sessão: o contexto anterior sobrevive, exceto quaisquer ferramentas/file_edits naquela virada. Uma sessão fechada (sessions close bem-sucedido) não pode ser reaberta; uma sessão abandonada (proprietário morto) pode ser retomada – sessions ensure falha em uma sessão quebrada? Verifique com sessions list.

acpx --cwd "$D" codex -s nome 'Continue a tarefa de ./brief.md. A saída anterior estava em ./report.md; adicione a esta tarefa.'

Desmontagem

O proprietário de uma sessão carrega um custo de memória (veja invariante 6) enquanto qualquer virada está ativa ou dentro do TTL ocioso. Após o TTL, o processo do proprietário é eliminado; a sessão persiste, mas nenhum processo permanece.

• Para tarefas de etapa única, anexe sessions close com && na linha de lançamento (acima).
• Para tarefas longas ou monitoramento contínuo de saída, cancele com sessions cancel. Isso encerra a virada do agente, encerra o proprietário imediatamente e marca a sessão como encerrada – evitando deadlocks ou processos órfãos.
• sessions close encerra a sessão (marca como fechada, nenhum outro prompt pode reabri-la).
• Em plataformas Windows, o gerenciamento de processos é diferente; sessions cancel atualmente não elimina processos no Windows (o encerramento interrompe saídas de I/O).
• O cancelamento não exclui artefatos (arquivos de sessão, diretórios de trabalho) – eles permanecem até a coleta de lixo ou exclusão manual.

Códigos de saída

Código	Significado	Notas
0	Sucesso (virada limpa)	[done] end_turn impresso; pode mascarar falhas de filtro, MCP ou modelo (invariante 5)
1	Erro de sintaxe/autenticação	Flag errada, credencial ausente, falha ao carregar MCP, 401/400
2	Erro de argumento (posicional)	Agente posicional com --agent, sessão inexistente
3	Timeout	--timeout expirado; agente não respondeu
4	Sessão não encontrada	-s <nome> sem sessão existente
5	Permissão negada	--deny-all ou pergunta de escolha fixa do agente
6	Erro interno (não utilizado atualmente)	Reservado
7	Sinal externo (SIGINT, SIGTERM)	Encerramento ou cancelamento

Configuração

O acpx usa um arquivo de configuração (~/.acpx/config.json) para controle de versão do agente, modelos padrão, flags de permissão, etc. Edite ou defina com acpx commands.

cat ~/.acpx/config.json
{
  "agents": {
    "codex": {
      "argv": ["npx", "-y", "@agentclientprotocol/[email protected]"]
    }
  }
}

Veja a documentação do acpx para mais detalhes.

Notas finais

• O acpx é uma ferramenta de linha de comando para executar agentes de IA de forma headless. Ele não substitui o subagente do harness; ele fornece uma via de execução fora do processo para automação e scripts.
• A sintaxe e o comportamento estão sujeitos a alterações com as versões do acpx e do adaptador. Consulte acpx --help e a documentação do fornecedor para obter informações atualizadas.
• Relate problemas ou contribua no repositório: acpx.