> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openagno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Problemas comunes del flujo vigente y cómo diagnosticarlos rápido.

## El gateway no arranca

```bash theme={null}
openagno validate
openagno start --foreground
```

Si usas supervisor:

```bash theme={null}
openagno status
openagno logs --follow
```

## `Workspace no encontrado`

La CLI espera `workspace/` dentro de `OPENAGNO_ROOT` o del directorio actual.

Solución:

* ejecuta los comandos desde la raíz del proyecto
* o define `OPENAGNO_ROOT`
* o crea el workspace con `openagno init --template ...`

## Knowledge deshabilitada

Revisa:

* `database.type`
* disponibilidad de PostgreSQL + `pgvector`
* `OPENAI_API_KEY` si usas el embedder por defecto

## Slack o Telegram no levantan

Revisa:

* `SLACK_TOKEN` y `SLACK_SIGNING_SECRET`
* `TELEGRAM_TOKEN`
* que el entorno haya sido instalado con las dependencias del proyecto

## `agui` o `a2a` no levantan

Instala extras:

```bash theme={null}
pip install -e '.[protocols]'
```

## WhatsApp responde `Invalid signature`

Revisa:

* `WHATSAPP_APP_SECRET`
* configuración del webhook de Meta
* si estás probando en local sin firma real

Para pruebas locales controladas:

```bash theme={null}
WHATSAPP_SKIP_SIGNATURE_VALIDATION=true
```

## Mensajes repetidos en WhatsApp

OpenAgno deduplica por `message_id`. Si ves replays:

* confirma que el proveedor reenvía el mismo `message_id`
* revisa logs de duplicados
* valida que el webhook esté respondiendo 200