Servicio y Daemon

Esta página es la contraparte del lado de operaciones de Configuración → Gestión del servicio; esa página cubre la instalación y desinstalación del servicio. Esta página cubre su ejecución: ajuste, límites de recursos, reinicios elegantes y configuraciones de múltiples espacios de trabajo.

Elegir entre el alcance de usuario y el de sistema

Ámbito	Bueno para	Desventaja
Usuario	Portátil, estación de desarrollo para un solo usuario, despliegues simples	Solo se ejecuta cuando el usuario ha iniciado sesión (Linux con un escritorio, macOS) a menos que habilites el modo persistente.
Sistema	Servidores sin interfaz gráfica, SBCs, VPSes, hosts multiusuario	Requiere root para instalar; obtiene su propia cuenta de usuario

En Linux de escritorio, habilita el persistencia del servicio de usuario para que el servicio del usuario persista entre cierres de sesión:

sh

loginctl enable-linger $USER

Sin demorarse, un servicio systemd de ámbito de usuario se detiene cuando se cierra la última sesión.

Comportamiento de reinicio

La unidad de usuario de systemd instalada (~/.config/systemd/user/zeroclaw.service) utiliza:

Restart=always
RestartSec=3

systemd reinicia el daemon ante cualquier salida con un tiempo de espera de 3 segundos. No hay una lista de códigos de salida permitidos, por lo que un daemon que falle rápidamente con una configuración incorrecta entrará en un ciclo de reinicios; corrija la configuración y ejecute systemctl --user restart zeroclaw en lugar de confiar en que el servicio se detenga por sí solo.

En macOS, el LaunchAgent (~/Library/LaunchAgents/com.zeroclaw.daemon.plist) establece RunAtLoad y KeepAlive en true, por lo que launchd mantiene el daemon en ejecución y lo vuelve a iniciar cada vez que finaliza.

En Windows, zeroclaw service install registra una tarea del Programador de tareas activada con ONLOGON en el nivel de ejecución LIMITED. Inicia el daemon al iniciar sesión; no agrega una política de reinicio automático en caso de fallo.

Apagado ordenado

En Unix, el daemon captura SIGINT y SIGTERM; en Windows captura Ctrl+C (ctrl_c). Cualquiera de estas señales activa un cierre limpio: el daemon detiene su servidor de canales y el listener del gateway, y finaliza.

SIGHUP se ignora (el daemon sigue ejecutándose). Una recarga solicitada a través del endpoint /admin/reload reinicia el bucle del daemon en el lugar en vez de salir.

La memoria de conversación y el estado de sesión se escriben en SQLite de forma incremental durante la operación, no se almacenan en búfer hasta el apagado, por lo que una detención limpia no depende de un paso de vaciado. Los recibos de herramientas son tokens HMAC dentro de banda en la conversación, no un registro separado en disco. Un SIGKILL forzado omite el desmontaje limpio del canal, pero no corrompe la memoria ya confirmada; solo se pierde un turno del agente que estaba en medio de una escritura.

Inicio manual para depuración

Omita el servicio y ejecute el demonio directamente:

sh

zeroclaw service stop     # liberar el puerto de la puerta de enlace si el servicio está en ejecución
zeroclaw daemon

zeroclaw daemon se ejecuta en primer plano, registra en stderr y es el mismo proceso que ejecuta el servicio, solo que sin el arnés del servicio. Es útil cuando:

Diagnóstico de fallos de inicio que el servicio absorbe
Ejecutando bajo gdb / lldb
Probando un cambio de configuración antes de comprometerse con él

Terminar con Ctrl-C, misma semántica de apagado ordenado que SIGTERM.

Límites de recursos

Linux: systemd

Agregar a un drop-in:

sh

systemctl --user edit zeroclaw.service

[Service]
MemoryMax=2G
CPUQuota=200%            # two cores
LimitNOFILE=16384        # if opening many channel sockets

Recargar y reiniciar:

sh

systemctl --user daemon-reload
systemctl --user restart zeroclaw

macOS: launchd

Edita ~/Library/LaunchAgents/com.zeroclaw.daemon.plist:

<key>SoftResourceLimits</key>
<dict>
  <key>NumberOfFiles</key>
  <integer>16384</integer>
</dict>

Descargar + cargar el plist para aplicar:

sh

launchctl unload ~/Library/LaunchAgents/com.zeroclaw.daemon.plist
launchctl load ~/Library/LaunchAgents/com.zeroclaw.daemon.plist

Docker

Componer:

servicios:
  zeroclaw:
    imagen: ghcr.io/zeroclaw-labs/zeroclaw:latest
    límite_de_memoria: 2g
    cpus: 2.0
    límites de recursos:
      archivo no encontrado: 16384

Ejecutar múltiples espacios de trabajo

Cada daemon de ZeroClaw posee un directorio de configuración (que contiene su directorio data/). Para ejecutar dos en paralelo, asigne a cada uno su propio directorio de configuración mediante --config-dir (o la variable de entorno ZEROCLAW_CONFIG_DIR):

sh

zeroclaw --config-dir ~/.zeroclaw-home daemon
zeroclaw --config-dir ~/.zeroclaw-work daemon

Cada instancia lee su propia configuración, su propio data/ (memoria, sesiones), su propio puerto de gateway (establecido por configuración) y sus propios enlaces de canal. La memoria se mantiene separada; un bot de Telegram en un directorio de configuración no sabe nada del otro.

zeroclaw service install siempre instala una única unidad que apunta al directorio de configuración predeterminado; no tiene ningún flag para nombrar o parametrizar instancias. Para ejecutar más de una como servicio persistente, cree manualmente un segundo archivo de unidad (copie ~/.config/systemd/user/zeroclaw.service con un nombre nuevo) cuyo ExecStart pase --config-dir <dir>, y luego habilítelo por separado.

No apuntes dos daemons al mismo directorio de configuración. SQLite es de escritor único; el segundo fallará al iniciarse.

Observando reinicios y fallos

sh

# Linux
journalctl --user -u zeroclaw --since "hace 1 día" | grep -E 'Iniciado|Detenido|fallido'

# macOS
log show --predicate `process == "zeroclaw"` --last 1d | grep -E 'iniciar|detener|error'

Si observas reinicios repetidos, habilita el registro de depuración (RUST_LOG=debug mediante el Environment= del archivo de unidad) y permite que ocurra un fallo más para capturar el seguimiento completo.

ZeroClaw Docs