Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Operaciones: Descripción general

Cómo ejecutar ZeroClaw en producción. La superficie es intencionalmente pequeña: un binario, un archivo de configuración y una raíz de instalación con unos pocos almacenes en tiempo de ejecución. La mayor parte de las “operaciones” es “systemd y journald”.

Esta sección cubre:

La forma de un despliegue

Una instalación típica de ZeroClaw siempre activa es:

zeroclaw service                          — systemd / launchctl / Windows Service
└── zeroclaw daemon                       — the single long-running process
    ├── gateway listener  :42617          — REST / WebSocket / webhook intake
    ├── channel pollers                   — Telegram, IMAP, Nostr relays (outbound poll)
    ├── channel listeners                 — Discord / Slack / Matrix / WebSocket (inbound stream)
    ├── cron scheduler                    — scheduled SOPs and jobs
    └── agent loop  (one per session)     — provider call + tool execution
                                            ▲ driven by any listener, poller,
                                              gateway request, or cron fire

on disk (everything but the binary can move)
├── ~/.zeroclaw/config.toml               — configuration
├── ~/.zeroclaw/.secret_key               — master key for the encrypted secrets store
└── ~/.zeroclaw/data/                     — runtime state
    ├── memory/                           — agent memory backend
    ├── sessions/                         — per-session conversation stores
    └── state/                            — scheduler, cost, health, misc runtime state

logs                                      — journald / launchctl / Windows Event Log (platform-native)

Todo excepto el binario puede moverse. El directorio de datos tiene por defecto ~/.zeroclaw/data/ (el nombre heredado ~/.zeroclaw/workspace/ sigue siendo aceptado); las rutas de configuración se resuelven según el entorno (Homebrew frente a bootstrap frente a XDG), y los destinos de registro son nativos de la plataforma de forma predeterminada. Para el mapa completo del almacén, consulte Estado de ejecución y persistencia.

Qué monitorear

Cuatro señales son importantes:

1. Estado de servicio

¿Está el proceso en ejecución?

Linux

systemctl --user is-active zeroclaw

macOS

launchctl list | grep -c com.zeroclaw.daemon

Windows

schtasks /Query /TN Daemon de ZeroClaw /FO LIST | findstr Status

Si se está reiniciando repetidamente, consulta Solución de problemas → El demonio se reinicia constantemente.

2. Estado del canal y los componentes

El gateway expone una instantánea del estado de los componentes en /health (pública, sin secretos) y en /api/health (autenticada). Los canales, proveedores y otros componentes de larga ejecución se registran en el mapa components a medida que se inician, informan que están OK o reportan errores.

sh

curl -s http://localhost:42617/health | jq

{
  "estado": "ok",
  "emparejado": true,
  "require_pairing": true,
  "tiempo de ejecución": {
    pid: 4821,
    "updated_at": "2026-06-08T09:00:00+00:00",
    "uptime_seconds": 3600,
    componentes: {
      "channel:telegram": {"estado": "ok", "updated_at": "…", "last_ok": "…", "last_error": null, "restart_count": 0},
      "channel:matrix":   {"estado": "error", "updated_at": "…", "last_ok": "…", "last_error": "401 No autorizado", "restart_count": 3}
    }
  }
}

Cada componente incluye status (starting / ok / error), last_ok, last_error y restart_count. Esté atento a status: "error" y a un restart_count en aumento.

Un canal muestra starting con un last_ok nulo hasta que confirma que realmente puede conectarse a su servicio, no simplemente hasta que se inicia su proceso de escucha. Algunos canales informan de lo que observaron al comunicarse con el servicio, por lo que un proceso de escucha que está en ejecución pero nunca ha completado un intercambio permanece en starting en lugar de ok, y uno cuyas llamadas fallan muestra error. Un canal que se reinicia con un alias que anteriormente había informado de ok vuelve a starting hasta que produce su propio intercambio correcto. Los canales que no ofrecen ninguna señal de este tipo se marcan como ok mientras su proceso de escucha esté en ejecución.

3. Fiabilidad del proveedor

Los proveedores aparecen como componentes en el mismo snapshot de /health. Para señales a nivel de solicitud (latencia, tasa de éxito, recuento de tokens), recopile /metrics (ver más abajo) y lea zeroclaw_llm_requests_total y zeroclaw_request_latency_seconds.

4. Volumen de llamadas a herramientas y métricas

/metrics devuelve texto en formato de exposición de Prometheus. Requiere [observability] backend = "prometheus" en la configuración; sin ello, el endpoint devuelve una indicación de una sola línea de “backend not enabled”.

sh

curl -s http://localhost:42617/metrics

zeroclaw_tool_calls_total{success="true",tool="shell"} 342
zeroclaw_tool_calls_total{success="false",tool="shell"} 6
zeroclaw_tool_calls_total{success="true",tool="file_write"} 89

El contador zeroclaw_tool_calls_total está etiquetado por tool y success ("true"/"false"). Un recuento creciente de success="false" para una herramienta merece atención: puede tratarse de un bloqueo de política, un agente con mal comportamiento o una herramienta inestable. Otras series útiles incluyen zeroclaw_llm_requests_total, zeroclaw_errors_total, zeroclaw_active_sessions y zeroclaw_tokens_input_total / zeroclaw_tokens_output_total.

Capacidad

Una única instancia de ZeroClaw puede manejar:

  • Múltiples conversaciones simultáneas en todos los canales
  • Llamadas a herramientas a la velocidad que el proveedor y el sandbox permitan
  • Bucles de agente de larga duración (cadenas de herramientas de 20+ llamadas)

Escale lateralmente ejecutando una instancia por workspace. No intente ejecutar dos daemons en el mismo workspace: el modelo de escritor único de SQLite producirá contención de bloqueos y, en última instancia, corrupción.

Para hosting multi-tenant, consulte la propuesta en #2765 (cerrada, histórica, la arquitectura para enrutamiento multi-workspace en proceso).

Copias de seguridad

Qué respaldar:

  • ~/.zeroclaw/data/memory/*.db: memoria de conversación SQLite (brain.db, además de audit.db)
  • ~/.zeroclaw/data/sessions/: estado de sesión persistido
  • ~/.zeroclaw/.secret_key: clave maestra del almacén de secretos cifrados (si se utiliza). Sin ella, los secretos cifrados de la configuración son irrecuperables.

Un simple tar czf zeroclaw-$(date +%F).tar.gz ~/.zeroclaw cubre todo. Restic, borg o Duplicacy funcionan bien para copias de seguridad incrementales.

~/.zeroclaw/data/memory/response_cache.db es una caché regenerable de respuestas de LLM; es seguro incluirla en una copia de seguridad de directorio completo o excluirla para ahorrar espacio. Los recibos de herramientas son tokens HMAC en banda dentro del historial de la conversación (consulte Recibos de herramientas), no un registro en disco, por lo que no hay nada adicional que respaldar para ellos.

Actualizaciones

El servicio no se actualiza automáticamente. Suscríbete al feed de lanzamientos (los releases de GitHub o el canal #releases de Discord: consulta Contributing → Communication). Cadencia típica de actualización:

  1. Leer las notas de la versión
  2. Haz una copia de seguridad de ~/.zeroclaw/
  3. Actualiza el binario (brew upgrade, vuelve a ejecutar el bootstrap o cargo install --force)
  4. zeroclaw service restart
  5. Verifica que el endpoint /health reporte status: "ok" sin ningún componente en error

Si la nueva versión requiere migraciones de configuración, el registro de inicio emite una advertencia y el binario suele migrar automáticamente. Comprueba zeroclaw config list para verificar algunos valores después de la actualización, y zeroclaw config migrate para aplicar manualmente cualquier migración de esquema pendiente.

Ver también