tenequm/acpx-faq

FAQ de acpx

Impulsa agentes de codificación sin interfaz gráfica a través de acpx (>= 0.19.3).

Autoridad de sintaxis

La sintaxis proviene del binario, no de este archivo. acpx --skill show acpx es la referencia del proveedor (~43k caracteres) y el desempate sobre la forma del comando; NO lo vuelques en la transcripción. Recupéralo en este orden:

1. acpx --help / acpx <cmd> --help - las banderas que estás a punto de componer.
2. Un tema: acpx --skill show acpx | rg -B2 -A12 '<término>', o una sección: acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'.
3. Si estás creando algo novedoso (un flujo, un runtime incrustado): vuelca UNA VEZ en un archivo temporal y haz grep en ese archivo.

Este archivo no repite nada de lo que cubre la referencia. Solo contiene lo que le falta a la referencia: códigos de salida, semántica de fallos, trampas y recetas por agente. Si una pregunta de sintaxis no se responde aquí, se responde allí; ve a buscarlo, nunca adivines una bandera. El docs/ del repositorio (códigos de salida, control de sesiones, vigilancia de sesiones, permisos, configuración) cubre parte de lo que la referencia enviada omite.

Cuándo usar este carril

acpx es el carril de ejecutor headless fuera de proceso: otro agente, vendedor o cuenta, manejado desde un script o desde otro agente, en una terminal simple, ssh o cron. La expansión dentro de una sesión permanece en la herramienta de subagente del arnés.

Invariantes

1. Las banderas globales preceden al subcomando del agente (--cwd, --model, --approve-all, --agent, --format, --timeout, --ttl, --mcp-config). El formulario de prompt acepta solo -s, --no-wait, -f (y exec también --config-option); otros subcomandos tienen los suyos propios (sessions watch --cursor, sessions export|import --cwd). Una bandera global después del agente sale con 1 y error: unknown option; una bandera incorrecta antes del agente sale con 2.

2. -s <nombre> nunca crea una sesión. La resuelve, caminando desde --cwd hacia arriba hasta el .git más cercano - un directorio o archivo, por lo que cada árbol de trabajo y submódulo es su propio límite; fuera de git solo se verifica el --cwd exacto. Sin coincidencia sale con 4. Crea primero con sessions ensure --name <n> en el mismo directorio.

3. status no es una señal de giro. Sonda el proceso propietario de la cola, nunca al agente, y sigue diciendo running después de que el turno ha terminado. Nunca condiciones la automatización en él.

4. Las banderas de permiso no son una caja de arena.

   • claude: el adaptador comienza en permissions.defaultMode de la configuración de Claude (acceptEdits / auto aprueba ediciones sin preguntar). Solo lo que ese modo escala llega a acpx como una solicitud de permiso - --deny-all rechaza esas (salida 5), pero una edición aprobada automáticamente nunca pregunta.
   • codex: las escrituras dentro de su caja de arena de espacio de trabajo (con raíz en --cwd, más directorios temporales) no generan solicitudes, por lo que --deny-all aún escribe; fuera falla con Operation not permitted - incluyendo el gitdir de un árbol de trabajo enlazado, por lo que un carril enjaulado en un git worktree no puede hacer commit (index.lock: Operation not permitted). La red está desactivada a menos que config.toml habilite network_access. --approve-all no cambia el modo del adaptador; INITIAL_AGENT_MODE=read-only|agent|agent-full-access al iniciar, o codex set-mode agent-full-access -s <n> en una sesión en vivo, sí lo hace.
   • --allowed-tools / --max-turns solo alcanzan a claude (y qoder); codex y agy los ignoran. --allowed-tools pre-aprueba y nunca restringe: --help's "" for no tools significa sin aprobaciones, no sin herramientas.

   El control real del sistema de archivos es qué --cwd le entregas.

5. [done] end_turn y salida 0 no son prueba de éxito. Una muerte por filtro de contenido, una falla de carga de MCP, un error de API (un 401 durante una renovación de token, un rechazo de modelo 400 ), o un turno truncado terminan de esa manera. Lee el flujo, o exige que el agente escriba un archivo de resultados que puedas verificar. Antes de una expansión, un exec barato ("Reply OK") por agente y modelo atrapa errores de autenticación y modelo - codex y agy rechazan un --model no anunciado antes del turno, claude advierte y lo reenvía.

6. Una sesión persistente mantiene una pila de procesos residente solo mientras está ocupada o caliente. Cada prompt -s elige un propietario de cola que tiene npm exec -> node <adaptador> -> <agente> (más los servidores MCP del agente), aproximadamente 550-650 MB antes de MCP. Después del TTL de inactividad (por defecto 300s) el propietario sale y la sesión permanece reanudable; el siguiente prompt la revive. sessions close finaliza la tarea - encadénalo en la línea de lanzamiento (ver Por agente) para que la desinstalación nunca dependa de que alguien se acuerde; --ttl 0 elimina la auto-recolección. Ver Desinstalación.

Por agente

Despacho único: sessions ensure && prompt && sessions close, una llamada encadenada. Una sesión nombrada por tarea, un prompt, cerrada cuando se lee el archivo de resultados. La cadena && hace que la desinstalación sea mecánica - nada recolecta registros abiertos, y los huérfanos provienen de cierres no encadenados - mientras que un turno que falla con estado no cero (tiempo de espera 3, permiso 5) omite el cierre por sí mismo, dejando la sesión abierta para recuperación (ver Hablando con una sesión en vivo). Un turno cancelado externamente aún sale con 0, por lo que el archivo de resultados, no el código de salida, es la verificación de éxito (invariante 5). No estaciones una sesión para seguimientos esperados: el estado de un bloqueador vive fuera de la conversación (las credenciales son a nivel de máquina, los parciales pertenecen al archivo de resultados) - responde con una sesión fresca alimentada con el resumen más ese archivo. El retrabajo - una corrección, revisión o pulido de la salida de una sesión - también obtiene una sesión fresca: un agente releyendo su propio contexto pierde lo que ojos nuevos captan. Nunca uses --no-wait en una sesión cuya línea de lanzamiento lleva el cierre: el apagado del propietario descarta prompts pendientes silenciosamente y cancela el turno activo (verificado en 0.19.4); un prompt bloqueante antes del cierre es seguro. Usa exec para una respuesta sin estado sin registro que valga la pena conservar (un "Reply OK" de verificación). Las sesiones se identifican por comando de agente + cwd + nombre; dale a cada ejecutor paralelo su propio nombre y, cuando escriba archivos, su propio directorio (idealmente un árbol de trabajo).

Los adaptadores se ejecutan a través de npm exec a menos que el binario del adaptador (claude-agent-acp, codex-acp) esté en PATH - esa copia gana sobre la alternativa del paquete, y actualizar acpx nunca la actualiza. Un HOME nuevo por trabajo los descarga de nuevo (cientos de MB cada uno); comparte un npm_config_cache. En macOS un HOME nuevo también oculta el Llavero de inicio de sesión: el adaptador de claude falla con RUNTIME: Unable to validate model: Could not resolve authentication method - conserva HOME. El caché de npx también reutiliza compilaciones obsoletas - fija versiones exactas de adaptadores en ~/.acpx/config.json (agents.<nombre>.argv). Una fijación congela qué IDs de modelo funcionan, y cambiarla re-clava las sesiones (ver Sesiones).

Los ejecutores heredan los archivos de instrucciones globales del usuario (el ~/.claude/CLAUDE.md de claude, el AGENTS.md global de codex). Una regla como "pregunta antes de editar" termina un turno headless con una pregunta sin trabajo realizado - abre cada resumen con "actúa ahora; no te detengas a preguntar ni termines con una pregunta". Un ejecutor que lee "usa un ejecutor fuera de proceso" allí puede lanzar un carril acpx anidado en el mismo checkout - agrega "tú eres el ejecutor; no delegues". Elimina o renombra el archivo de resultados antiguo antes de un relanzamiento (un sondeador lee el obsoleto), y dale a los carriles paralelos sus propias rutas temporales y puertos - los árboles de trabajo separados no aíslan /tmp.

También heredan el entorno del lanzador, y el zsh de codex relee $ZDOTDIR/.zshenv (por defecto ~/.zshenv) para cada comando - desactivar un secreto en el lanzador no lo mantiene fuera, y lo que el shell imprima termina en los archivos de despliegue bajo ~/.codex/sessions.

agy / Antigravity

El acpx antigravity integrado (0.17.1+) ejecuta agy_acp_server.par desde PATH, y la copia que Antigravity instala bajo ~/.local/lib/antigravity-acp/ no está en PATH - un simple acpx antigravity sale con 1 y Failed to spawn agent command: agy_acp_server.par. Antepón ese directorio a PATH, establece agents.antigravity.argv, o usa --agent <ruta>. El agente gemini integrado es el CLI público de Gemini - un producto diferente. El .par proviene de la instalación de Antigravity o del archivo oficial del registro ACP; mantenlo junto a su ayudante localharness_external de la misma versión (un ayudante faltante solo registra Localharness not found. y continúa), o apunta ANTIGRAVITY_HARNESS_PATH hacia él. Ni acpx ni agy update actualizan el .par: compara su --version Build label: con el registro ACP e intercambia ambos archivos juntos (el ayudante instalado es de solo lectura - rm -f antes de copiar el nuevo).

D=/abs/real/dir                              # debe existir: las raíces se resuelven a través de realpath
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
     --cwd "$D" --model gemini-3.8-flash --approve-all --timeout 1800 \
     exec "Lleva a cabo $D/brief.md. Escribe tu informe en $D/report.md."

• --approve-all es obligatorio. Sin él, cada escritura es rechazada: salida 5 (o un estancamiento a salida 3), con [done] end_turn aún impreso y sin informe.

• Las preguntas de opción fija hacen fallar el prompt con salida 5 incluso bajo --approve-all (línea final Antigravity requested a user answer...) - también para lanzamientos con --agent. acpx falla cualquier pregunta de opción fija de un agente de esta manera (PERMISSION_PROMPT_UNAVAILABLE); agy es donde muerde. Escribe resúmenes que nunca necesiten una elección del usuario.

• Usa solo ids que la sesión ACP anuncie - un --model deliberadamente malo imprime Available models: sin iniciar un turno (servidor 1.4.5: gemini-4-argon, gemini-3.8-flash; los ids con esfuerzo gemini-3.7-flash-{low,medium,high} han desaparecido). agy models es una lista diferente. Flash es adecuado para trabajo masivo basado en rúbricas y es mucho más rápido, pero pierde hallazgos reales en trabajo de revisión / caza de errores; usa un modelo más fuerte allí.

• agy lee archivos hermanos sin que se le pida - los agentes que comparten un directorio reproducen la salida del otro. Un directorio por agente, y verifica cualquier re-ejecución antes de creer un número de acuerdo.

• Autenticación: necesita auth.type en <GEMINI_HOME>/antigravity-acp/settings.json (una vez):

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

  Sin ello: inmediato [error] RUNTIME: Authentication required (salida 1). Con ello pero nunca iniciado sesión: session/new se bloquea en un inicio de sesión del navegador hasta que --timeout (salida 3) - inicia sesión una vez de forma interactiva. La credencial del servidor es separada del CLI agy: el Llavero de macOS (servicio gemini, cuenta antigravity-acp), o <GEMINI_HOME>/antigravity-acp/acp_token.json fuera de macOS o con AGY_ACP_FORCE_FILE_STORAGE=1. GEMINI_HOME solo no aísla la credencial de macOS. Un problema de derechos es del lado del servidor - no lo "arregles" cambiando a gemini-api-key o un proyecto GCP (facturación separada, no arreglos).

• Nunca pases un agente posicional con --agent - salida 2.

• Prompts de verificación: exige una respuesta simple y lee todo el registro. agy enruta respuestas a archivos de artefactos cerebrales, por lo que un tail no puede distinguir "sin herramientas" de "respondido en otro lado". Agrega "No crees ningún archivo".

• agy oculta fallos de MCP dentro de un turno de apariencia exitosa - salida 0, [done] end_turn, y toda la respuesta es The MCP server '<nombre>' failed to initialize: .... Busca failed to initialize.

• Prefiere exec. Se ha reportado que una muerte del servidor a mitad de un punto de control rompe una conversación guardada para siempre (could not find doneCh for checkpoint); la única recuperación reportada es eliminar ~/.gemini/antigravity-acp/conversations/<id>.db.

Linux / NixOS

El agente integrado añade el --uid= requerido por sí mismo. NixOS además necesita un paquete CA, por lo que apunta --agent (o agents.antigravity.argv) a un envoltorio (~/.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= "$@"

Sin SSL_CERT_FILE el OpenSSL incrustado del .par no tiene rutas CA válidas; su proxy local reporta 502 Bad Gateway: Failed to connect to backend API y el turno aún termina [done] end_turn con salida 0 (invariante 5). El verdadero CERTIFICATE_VERIFY_FAILED aparece solo bajo --alsologtostderr.

codex

D=/abs/dir
acpx --cwd "$D" codex sessions ensure --name work            # idempotente; -s no puede crear
acpx --cwd "$D" codex set model gpt-6-astra -s work
acpx --cwd "$D" codex set reasoning_effort high -s work
{ acpx --cwd "$D" --approve-all --timeout 5400 --suppress-reads \
     codex -s work 'Lleva a cabo ./brief.md. Escribe tu informe en ./report.md.' && \
  acpx --cwd "$D" codex sessions close work; } > run.log 2>&1 &
# un turno fallido omite el cierre - vuelve a solicitar -s work para recuperar, luego cierra tú mismo

Despacho único: --model <id> exec --config-option reasoning_effort=low establece modelo y esfuerzo en línea.

• El adaptador de codex (@agentclientprotocol/codex-acp) flota en ^1.1.5 - el comportamiento puede cambiar sin una actualización de acpx, pero el 2.x que rompe está fuera de rango. Un adaptador obsoleto rechaza ids de modelo más nuevos: [error] RUNTIME: Invalid params en session/set_config_option (salida 1), o un 400 model is not supported que aún termina [done] end_turn, salida 0. Fija uno actual: {"agents":{"codex":{"argv":["npx","-y","@agentclientprotocol/[email protected]"]}}}. Una fijación exacta aún hace flotar el binario de codex dentro (2.5.0 depende de @openai/codex ^0.165.0). Los mismos síntomas afectan a un adaptador actual cuando la cuenta carece del modelo: la lista anunciada difiere por cuenta; verifica antes del vuelo bajo el propio inicio de sesión del carril.

• El filtro de contenido de OpenAI mata turnos benignos que terminan limpios ([done] end_turn, salida 0). Vocabulario como race / sweep / exploit / attack en un nombre de archivo, comentario o prompt lo activa. Lee la cola de la transcripción antes de creer en la finalización; recupera solicitando nuevamente el mismo -s <nombre> (el contexto sobrevive a menos que la reconexión falle - acpx entonces cae silenciosamente a session/new) con el argumento de que se trató de un falso positivo.

  acpx codex -s work "El informe en ./report.md estaba vacío / truncado. Un filtro de contenido puede haberlo matado. Vuelve a ejecutar la misma tarea desde cero."
  

• --suppress-reads es recomendable para carriles de procesamiento. Sin él, la salida de git diff --name-only o fd . --type f se imprime en vivo, lo que es bueno para sondear pero ruidoso para pipelines automatizados. Desactivarlo no acelera el adaptador.

claude

D=/abs/dir
acpx --cwd "$D" --model claude-sonnet-8-20250422 --approve-all --timeout 3600 \
     claude -s fix "Implementa los cambios en $D/brief.md. No crees archivos; edita directamente." && \
  acpx --cwd "$D" claude sessions close fix

• --approve-all es seguro aquí porque el adaptador de claude por defecto usa acceptEdits, que de todos modos aprueba automáticamente las ediciones. --approve-all solo pre-aprueba las solicitudes de permiso que escapan de acceptEdits - llamadas de herramientas como Bash o Read. Sin --approve-all, el agente se detendrá en cualquier comando de shell o lectura de archivo fuera del alcance de acceptEdits, rompiendo el flujo headless. Siempre úsalo para carriles headless.
• El modo read-only de claude se activa con el flag --approve-all si el agente soporta --mode. A partir de claude 4.5+, --mode read-only se puede pasar explícitamente, pero --approve-all con --model apropiado es suficiente para carriles de solo lectura. No hay modo de solo escritura.
• El adaptador puede fallar con RUNTIME: Unable to validate model: Could not resolve authentication method si el directorio HOME del usuario carece de acceso al Llavero de macOS (ver sección de inicio de Por agente arriba).

MCP con acpx

acpx no gestiona servidores MCP por separado; pasa --mcp-config <archivo.json> a cualquier agente que lo soporte. El archivo sigue el formato de configuración MCP del agente:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/absoluta"]
    }
  }
}

• --mcp-config es una bandera global - debe ir antes del subcomando del agente (invariante 1).
• El adaptador de claude requiere que los servidores MCP estén en su propio archivo claude.json para algunas configuraciones; --mcp-config anula eso para la sesión. Para codex y agy, funciona directamente.
• Los fallos de MCP pueden terminar un turno con [done] end_turn y salida 0 (invariante 5) - busca failed to initialize en la salida del agente.

Sesiones

Control de sesiones

# Listar todas las sesiones
acpx sessions list

# Ver detalles de una sesión específica
acpx sessions show -s <nombre>

# Ver la salida en vivo de una sesión
acpx sessions watch -s <nombre>

# Exportar el historial de una sesión
acpx sessions export -s <nombre> > sesion.json

# Importar una sesión desde un archivo
cat sesion.json | acpx sessions import -s <nombre>

Ver sesiones

# Ver con cursor para actualización continua
acpx sessions watch --cursor -s <nombre>

# Ver desde un punto específico (número de línea)
acpx sessions watch --cursor --from 100 -s <nombre>

Ciclo de vida de la sesión

1. Crear: acpx sessions ensure --name <nombre> - idempotente, no falla si existe.
2. Prompt: acpx -s <nombre> "tu prompt aquí" - envía un mensaje a la sesión.
3. Cerrar: acpx sessions close <nombre> - finaliza la sesión y limpia recursos.

Importante: -s <nombre> nunca crea una sesión (invariante 2). Siempre usa sessions ensure primero en el mismo directorio donde se ejecutará el prompt.

Códigos de salida

Código	Significado
0	Éxito (pero verifica invariante 5)
1	Error general (bandera desconocida, fallo de autenticación)
2	Error de sintaxis (bandera incorrecta antes del agente)
3	Tiempo de espera agotado
4	Sesión no encontrada
5	Permiso denegado

Configuración

Archivo de configuración global: ~/.acpx/config.json

{
  "agents": {
    "antigravity": {
      "argv": ["~/.local/lib/antigravity-acp/agy_acp_server.par"]
    },
    "codex": {
      "argv": ["npx", "-y", "@agentclientprotocol/[email protected]"]
    }
  },
  "defaults": {
    "timeout": 300,
    "ttl": 300
  }
}

Variables de entorno

• SSL_CERT_FILE: Ruta al paquete CA (necesario en NixOS para agy)
• GEMINI_HOME: Directorio base para archivos de configuración de Gemini/agy
• AGY_ACP_FORCE_FILE_STORAGE=1: Forzar almacenamiento de token en archivo en lugar de Llavero de macOS
• ANTIGRAVITY_HARNESS_PATH: Ruta al ayudante localharness_external para agy
• npm_config_cache: Caché de npm compartido para evitar descargas duplicadas de adaptadores

Desinstalación

La desinstalación automática de sesiones es crítica para evitar sesiones huérfanas. Dos mecanismos:

1. TTL de inactividad (por defecto 300s): El proceso propietario de la cola sale después de este tiempo de inactividad, pero la sesión permanece reanudable.
2. --ttl 0: Elimina la auto-recolección - la sesión nunca expira por inactividad.
3. Cadena &&: La mejor práctica para tareas headless - encadena sessions ensure && prompt && sessions close para que el cierre ocurra automáticamente después del prompt exitoso.

Regla de oro: Cada sesión abierta debe tener una ruta de cierre clara. Si un turno falla (salida no cero), la sesión queda abierta intencionalmente para depuración - ciérrala manualmente después de la inspección.

Preguntas frecuentes

¿Por qué mi agente está atascado en "running" pero no produce salida?

Probablemente esté esperando entrada del usuario debido a una solicitud de permiso, o el agente está en un bucle infinito. Usa sessions watch -s <nombre> para ver la salida en vivo. Si ves [PERMISSION] o una pregunta, el prompt necesita revisión.

¿Cómo ejecuto múltiples agentes en paralelo?

Cada agente necesita su propio nombre de sesión y, al escribir archivos, su propio directorio de trabajo:

# Agente 1
acpx --cwd /tmp/trabajo1 sessions ensure --name agente1
acpx --cwd /tmp/trabajo1 -s agente1 "tarea 1" &

# Agente 2
acpx --cwd /tmp/trabajo2 sessions ensure --name agente2
acpx --cwd /tmp/trabajo2 -s agente2 "tarea 2" &

# Esperar a que ambos terminen
wait

¿Cómo manejo secretos?

• No pongas secretos en los prompts - los agentes pueden registrar salida que incluya el prompt.
• Usa variables de entorno para secretos, pero ten en cuenta que codex relee ~/.zshenv que puede contener secretos.
• Considera usar un sistema de gestión de secretos externo y pasar tokens a través del prompt.

¿Cómo verifico que un agente realmente completó su tarea?

No confíes en el código de salida o [done] end_turn. Haz que el agente escriba un archivo de resultados conteniendo un resumen de lo que hizo, y verifica ese archivo después de que el turno termine:

echo "Escribe un informe de lo que hiciste en $D/report.md. Confirma que está completo." | \
  acpx -s trabajo - && test -f $D/report.md && echo "Éxito" || echo "Fallo"