agent-ecosystem/landing/product-docs/es/guide/troubleshooting.md

title	description	lang
Solución de problemas – Documentación de Agent Teams	Resuelve problemas de lanzamiento de equipos, respuestas de agentes faltantes, límites de uso, problemas de autenticación de la CLI y bloqueos en el bootstrap de los lanes con diagnósticos locales.	es-ES

Solución de problemas

La mayoría de los problemas de equipo entran en una de cuatro categorías: configuración del runtime, confirmación del lanzamiento, análisis de tareas y límites del proveedor.

Configuración rápida de evidencias

Para cualquier problema del ciclo de vida del equipo, define primero estas variables y reutiliza el mismo shell:

TEAM="<team-name>"
TEAM_DIR="$HOME/.claude/teams/$TEAM"
TASKS_DIR="$HOME/.claude/tasks/$TEAM"

Luego confirma que los archivos esperados existen antes de interpretar el estado de la interfaz:

test -d "$TEAM_DIR" && find "$TEAM_DIR" -maxdepth 2 -type f | sort | sed -n '1,80p'
test -d "$TASKS_DIR" && find "$TASKS_DIR" -maxdepth 1 -name '*.json' | sort | sed -n '1,40p'

::: warning Las evidencias primero No corrijas los prompts, la configuración del proveedor ni la limpieza de procesos basándote únicamente en una insignia atascada. Primero correlaciona la interfaz con los archivos persistidos, los artefactos de lanzamiento y la evidencia del runtime. :::

El equipo no se lanza

Comprueba cada elemento en orden:

1. Runtime disponible — la CLI seleccionada (claude, codex, opencode) está instalada
2. PATH accesible — el binario está disponible en el PATH del entorno
3. Acceso al modelo — el proveedor tiene acceso a la cadena de modelo solicitada (especialmente en OpenCode, donde los nombres exactos de proveedor/modelo importan)
4. Ruta del proyecto — el directorio del proyecto existe y se puede leer
5. Red / VPN — algunos proveedores descartan el tráfico cuando hay una VPN activa

::: tip Ejecuta el binario del runtime en una terminal para verificar el PATH y la autenticación. Por ejemplo: claude --version u opencode --version. :::

OpenCode: registrado pero bootstrap sin confirmar

Si OpenCode muestra registered pero el bootstrap no está confirmado, inspecciona los artefactos primero antes de cambiar los prompts del equipo.

Los detalles para colaboradores/depuración están en Arquitectura para colaboradores, que enlaza con el runbook canónico de depuración de equipos de agentes.

Observa el artefacto de fallo de lanzamiento más reciente:

LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
MANIFEST_PATH="$(jq -r '.manifestPath' "$LATEST_FAILURE")"
jq '.classification, .bootstrapTransportBreadcrumb, .memberSpawnStatuses' "$MANIFEST_PATH"

latest.json apunta al directorio de artefactos empaquetados más reciente y a su manifest.json. El manifiesto incluye:

• classification — por qué se consideró que el lanzamiento fue un fallo
• bootstrapTransportBreadcrumb — ruta de entrega utilizada
• Los estados de spawn de los miembros
• Registros y trazas redactados

Comprueba también el manifiesto del lane:

jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime/lanes" -maxdepth 2 -name manifest.json -print -exec jq '.activeRunId, .entries' {} \; 2>/dev/null

::: tip No adivines a partir de la interfaz Correlaciona siempre los diagnósticos de la interfaz con los archivos persistidos (launch-state.json, bootstrap-journal.jsonl) y la evidencia específica del runtime. :::

Diagnósticos generales

Empieza por los archivos persistidos en disco en lugar de basarte solo en la interfaz.

Raíz del equipo

printf '%s\n' "$TEAM_DIR"

Archivos clave y lo que te indican:

• launch-state.json — estado de lanzamiento/actividad de los miembros (.teamLaunchState, .summary, .members)
• bootstrap-journal.jsonl — eventos de bootstrap ordenados desde la CLI/runtime (tail -80)
• bootstrap-state.json — resumen de la fase de bootstrap
• config.json — configuración del proveedor, el modelo y el proyecto
• inboxes/*.json y sentMessages.json — estado de entrega de los mensajes

jq '.teamLaunchState, .summary, .members' "$TEAM_DIR/launch-state.json"
tail -80 "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null

Evidencia del runtime de OpenCode

Para los compañeros de equipo de OpenCode, la prueba de la sesión está en el almacén del runtime del lane:

• .opencode-runtime/lanes.json — índice de lanes con su estado
• .opencode-runtime/lanes/<lane>/manifest.json — activeRunId y entradas de evidencia
• .opencode-runtime/lanes/<lane>/opencode-sessions.json — registros de sesión confirmados

Estado saludable esperado: estado del lane active, el manifiesto tiene activeRunId con al menos una entrada de evidencia, el miembro tiene bootstrapConfirmed: true.

jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime" -maxdepth 3 -type f | sort

Artefactos de fallo de lanzamiento

Cuando un lanzamiento se marca como fallo, inspecciona latest.json:

LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
jq '.' "$LATEST_FAILURE"
jq '.' "$(jq -r '.manifestPath' "$LATEST_FAILURE")"

El manifiesto incluye:

• classification — por qué se consideró que el lanzamiento fue un fallo
• bootstrapTransportBreadcrumb — ruta de entrega utilizada
• Los estados de spawn de los miembros y los registros/trazas redactados

Faltan respuestas de los agentes

Abre los registros de tareas y los mensajes de los compañeros de equipo. Las respuestas faltantes suelen deberse a:

• Reintento de entrega del runtime — puede que el agente haya respondido, pero el mensaje no se entregó a la aplicación. Comprueba el ledger de entrega.
• Análisis o filtrado — la salida del agente no incluía los marcadores esperados ni las referencias de tarea.
• Atribución de tarea — el trabajo ocurrió durante la sesión pero no se vinculó a la tarea porque faltaba el id de tarea correcto en la salida.

::: warning No supongas que el silencio significa que se ignoró No supongas que el modelo ignoró el mensaje hasta que los registros lo confirmen. :::

Usa el estado persistido de los mensajes para separar lo "no enviado" de lo "enviado pero no renderizado":

jq '.' "$TEAM_DIR/inboxes/user.json" 2>/dev/null
jq '.' "$TEAM_DIR/sentMessages.json" 2>/dev/null

Comprueba from, to, messageId, relayOfMessageId y taskRefs. Para los compañeros de equipo de OpenCode, inspecciona también la evidencia de entrega del runtime antes de suponer que el modelo ignoró el prompt.

Las tareas no están vinculadas a los cambios

Usa los registros específicos de cada tarea y los enlaces de revisión de código. Si un diff parece desvinculado:

• Comprueba si el id de tarea o la referencia de tarea se incluyó en la salida del agente.
• Verifica que el agente llamó a task_add_comment antes de hacer ediciones.
• Asegúrate de que el agente llamó a task_start para que el tablero supiera que el trabajo había comenzado.

Para los compañeros de equipo de OpenCode, la prueba fehaciente de que una sesión pertenece a una tarea está en opencode-sessions.json y la entrada del manifiesto del lane, no solo en el flujo de mensajes de la interfaz.

Triaje del registro de tareas

Cuando un registro de tarea parezca incompleto, busca por id de tarea en el JSON de tareas, las bandejas de entrada y los eventos de bootstrap:

TASK="<short-or-full-task-id>"
rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null

Interpreta el resultado con cuidado:

Evidencia	Qué demuestra	Qué no demuestra
Mensaje entregado	La aplicación escribió o retransmitió un prompt	Que el agente progresó
Comentario de tarea	El agente publicó texto visible en el tablero	Que el comentario sea progreso significativo
Filas de herramientas nativas	El runtime hizo trabajo en una sesión	Que el trabajo pertenezca a esta tarea, a menos que la atribución coincida
Entrada del ledger de cambios	La aplicación registró cambios de archivo	Que la implementación sea correcta

En OpenCode, un registro de tarea saludable suele incluir filas nativas del runtime como read, bash, edit o write, además de filas de MCP de Agent Teams. Si solo ves filas agent-teams_*, confirma la atribución de la tarea y los límites de la sesión antes de ampliar la coincidencia de registros.

Límites de uso

Si un proveedor informa de una hora de restablecimiento conocida, Agent Teams puede indicar al lead que continúe tras el enfriamiento. Si se desconoce la hora de restablecimiento, espera o cambia de proveedor/ruta de runtime.

Comportamiento del proveedor	Acción sugerida
Se muestra una hora de restablecimiento conocida	Espera el enfriamiento y continúa
No se muestra ninguna hora de restablecimiento	Cambia de proveedor o de ruta de runtime
429 repetidos	Reduce la concurrencia o usa un lane de modelo distinto

Problemas de autenticación de la CLI

claude login no persiste

Si la CLI está autenticada en una terminal pero la aplicación dice que no lo está, verifica que la autenticación se guarda en la ruta de configuración esperada y que el proceso de la aplicación ve el mismo $HOME.

Clave del proveedor de OpenCode rechazada

• Verifica que el nombre del proveedor en config.json coincide con el prefijo del proveedor en la cadena de modelo
• Asegúrate de que la clave no haya caducado ni haya sido revocada en el panel del proveedor

Registro de diagnóstico de autenticación

Cada llamada a CliInstallerService.getStatus() añade una línea a claude-cli-auth-diag.ndjson en la carpeta de registros de Electron (normalmente ~/Library/Logs/<product-name>/ en macOS). Si el archivo supera los 512 KiB, se trunca a vacío antes de la siguiente escritura.

Comprueba este archivo si ves "Not logged in" o errores de autenticación en la aplicación empaquetada.

Bootstrap del lane atascado

Para los lanes secundarios de OpenCode:

• La ausencia de inboxes/<member>.json no es automáticamente un error. Los lanes de OpenCode no tienen que crearse mediante la bandeja de entrada primaria antes de arrancar.
• Si la interfaz muestra que el equipo aún se está lanzando mientras los miembros primarios ya son utilizables, "se han unido todos los compañeros de equipo" está esperando a los lanes secundarios.
• Si Prepared communication channels for X/Y members se queda colgado, verifica si Y incluye incorrectamente a miembros secundarios de OpenCode.

Entradas vacías en el manifiesto del lane

Si el puente dice que el bootstrap tuvo éxito pero manifest.json muestra entries: [], el problema es la confirmación de la evidencia, no el comportamiento del modelo. El miembro no debe considerarse entregable hasta que existan opencode-sessions.json y su entrada en el manifiesto.

Estados comunes de los miembros

Estado	Significado
confirmed_alive + bootstrapConfirmed	Saludable y listo
registered / runtime_pending_bootstrap	El proceso o el lane existe, pero la prueba de bootstrap aún no se ha confirmado
failed_to_start + runtime_process	El proceso existe, pero la puerta de lanzamiento falló. Comprueba los diagnósticos
failed_to_start + stale_metadata	El pid/sesión guardado está obsoleto o muerto

::: warning member_briefing por sí solo NO es evidencia del runtime. Para OpenCode, la prueba fehaciente es la evidencia del runtime confirmada, como opencode-sessions.json y la entrada del manifiesto. :::

Modo de depuración del runtime

Para la depuración local, puedes forzar que los compañeros de equipo se ejecuten en paneles de tmux:

# Launch from a terminal
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev

# Or add to custom CLI args
--teammate-mode tmux

Úsalo para inspeccionar el comportamiento interactivo de la CLI. No lo consideres totalmente equivalente al backend de procesos.

Comprobaciones rápidas

Usa la aplicación de escritorio Electron para la validación normal. El modo de desarrollo en navegador/web no incluye el runtime de escritorio completo, el IPC, la autenticación del proveedor, la terminal ni el comportamiento del ciclo de vida del equipo.

Cambios solo en la documentación

Desde la raíz del repositorio:

pnpm --dir landing docs:build
git diff --check -- landing/product-docs

Cambios en el ciclo de vida del equipo

Empieza de forma acotada y luego amplía:

pnpm test -- test/main/services/team/TeamProvisioningService.test.ts
pnpm test -- test/main/services/team/TeamAgentLaunchMatrix.safe-e2e.test.ts
pnpm typecheck
git diff --check

Prueba rápida de un equipo en vivo

Usa un equipo pequeño y un proyecto desechable bajo control de Git:

1. Inicia la aplicación de escritorio con pnpm dev.
2. Crea un lead más un builder.
3. Pide un cambio mínimo con un comando de verificación explícito.
4. Confirma que la tarea pasa de pending -> in_progress -> completed.
5. Abre los registros de tareas y verifica que las filas de herramientas, los comentarios de tarea y los cambios de archivo cuadran.
6. Detén únicamente el equipo/procesos propios de la prueba rápida al limpiar.

::: warning Limpieza acotada únicamente No mates todos los hosts de OpenCode, paneles de tmux no relacionados ni equipos de usuario mientras limpias una prueba rápida. :::

Limpieza segura

Al limpiar procesos obsoletos:

1. Identifica el pid y confirma que pertenece al equipo / lane actual.
2. Detén únicamente los procesos que pertenezcan explícitamente a una prueba rápida o al lanzamiento que estás depurando.
3. No mates todos los procesos de OpenCode ni de hosts compartidos como atajo.

Cuándo recopilar evidencias

Antes de pedir ayuda, recopila:

• El id de tarea (corto o completo)
• El nombre del equipo
• La ruta del runtime (claude, codex u opencode)
• Un extracto del registro de lanzamiento (de latest.json o bootstrap-journal.jsonl)
• La cadena de proveedor / modelo
• La ventana de tiempo exacta en la que ocurrió el problema

Estos datos suelen ser suficientes para depurar problemas del ciclo de vida del lanzamiento y de las tareas.

::: tip Si el problema persiste, abre los archivos persistidos del equipo en ~/.claude/teams/<teamName>/ y correlaciona los diagnósticos de la interfaz con el estado de los procesos en vivo antes de cambiar código. :::