Gestión de servicios

ZeroClaw incluye integración de servicios de primera clase para systemd (Linux), launchctl (macOS) y Task Scheduler (Windows). Los tres se gestionan mediante una única interfaz de CLI:

sh

zeroclaw service install     # registrar el servicio
zeroclaw service start       # iniciarlo
zeroclaw service stop        Detener
zeroclaw service restart     # detener + iniciar
zeroclaw service status      # ejecutando / detenido, último código de salida
zeroclaw service uninstall   # eliminarlo

Los backends específicos de cada plataforma están implementados en crates/zeroclaw-runtime/src/service/. No tienes que pensar en ellos, pero saber qué producen ayuda a la hora de depurar.

Linux: systemd

zeroclaw service install escribe una unidad a nivel de usuario en ~/.config/systemd/user/zeroclaw.service.

La unidad:

Type=simple con el proceso del agente en primer plano
ExecStart={cargo-bin}/zeroclaw daemon
Restart=always con RestartSec=3
Environment=HOME=%h y PassEnvironment=DISPLAY XDG_RUNTIME_DIR para que las herramientas de navegador sin interfaz gráfica puedan crear directorios de perfil/caché y acceder a la sesión del usuario
WantedBy=default.target

Control manual (systemd)

sh

systemctl --user start zeroclaw
systemctl --user stop zeroclaw
systemctl --user status zeroclaw
systemctl --user enable zeroclaw     # iniciar al iniciar sesión

Registros

sh

journalctl --user -u zeroclaw -f        # seguir
journalctl --user -u zeroclaw --since "hace 1 hora"

Anulaciones de entorno (systemd)

Usa una anulación de servicio de usuario cuando el daemon necesite variables de entorno que no están presentes en tu shell interactivo:

sh

systemctl --user edit zeroclaw.service

Por ejemplo, un perfil de Bedrock que usa credential_process necesita AWS_PROFILE en el entorno del servicio:

[Service]
Environment=AWS_PROFILE=zeroclaw-bedrock

Después de guardar la anulación, recarga y reinicia el servicio de usuario:

sh

systemctl --user daemon-reload
systemctl --user restart zeroclaw
journalctl --user -u zeroclaw -f

El servicio de usuario generado establece HOME=%h, por lo que el código del proveedor que lee archivos en el directorio de inicio del usuario del servicio puede resolver rutas como ~/.aws/config. Si una anulación hace referencia a un ejecutable, usa una ruta absoluta; los servicios de systemd suelen ejecutarse con un PATH más reducido que un shell interactivo.

Inicio antes del inicio de sesión del usuario

La CLI solo escribe siempre una unidad con alcance de usuario (systemctl --user), que de forma predeterminada se inicia al iniciar sesión y se detiene al cerrar sesión. Para mantener ZeroClaw en ejecución en una máquina sin interfaz gráfica (headless) sin una sesión activa, habilita el lingering para el usuario del servicio:

sh

sudo loginctl enable-linger $USER
systemctl --user enable --now zeroclaw

Si necesitas una unidad verdadera con alcance de sistema (propiedad de root, /etc/systemd/system/, cuenta de servicio dedicada o grupos de hardware mediante SupplementaryGroups), la CLI no genera una; adapta la plantilla a nivel de sistema en scripts/zeroclaw.service e instálala tú mismo. En hosts con OpenRC, sudo zeroclaw service install sí aprovisiona un usuario zeroclaw dedicado y rutas de sistema (ver más abajo).

Linux: OpenRC

Se detecta automáticamente cuando existe /run/openrc (Alpine, algunas configuraciones de Gentoo).

sh

zeroclaw service install   # escribe /etc/init.d/zeroclaw
rc-service zeroclaw start
rc-update add zeroclaw default    # iniciar al arrancar

OpenRC mantiene la salida del demonio en /var/log/zeroclaw/access.log y /var/log/zeroclaw/error.log. Cada archivo conserva la salida reciente dentro de un límite de 8 MiB. Reinstale y reinicie el servicio después de actualizarlo para que el script de inicio generado use procesos de registro con límites.

macOS: LaunchAgent

zeroclaw service install escribe ~/Library/LaunchAgents/com.zeroclaw.daemon.plist y lo carga.

sh

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

Los registros se escriben en <config-dir>/logs/ como daemon.stdout.log y daemon.stderr.log (en una instalación predeterminada, ~/.zeroclaw/logs/). Las instalaciones de Homebrew escriben en $HOMEBREW_PREFIX/var/zeroclaw/logs/ en su lugar. Cada archivo de captura de launchd conserva la salida reciente dentro de un límite de 8 MiB. Reinstala y reinicia el servicio después de actualizarlo para que el LaunchAgent generado use una captura limitada.

Gestionado por Homebrew

Si se instaló mediante Homebrew, brew services es la interfaz preferida:

sh

brew services start zeroclaw
brew services restart zeroclaw
brew services info zeroclaw

No mezcles los comandos CLI de zeroclaw service con brew services, elige uno. Ambos terminan escribiendo un plist; tener ambos a la vez confunde a launchctl.

Windows: Programador de tareas

zeroclaw service install crea una tarea programada por usuario llamada ZeroClaw Daemon:

Desencadenador: al iniciar sesión (/SC ONLOGON)
Nivel de ejecución: LIMITED (se ejecuta como el usuario actual, sin elevación)
Acción: ejecuta el envoltorio de instalación zeroclaw-daemon.cmd, que inicia zeroclaw daemon

Verifique en la interfaz gráfica del Programador de tareas (taskschd.msc) en Biblioteca del Programador de tareas → ZeroClaw Daemon.

Los registros se guardan en <config-dir>\logs\ como daemon.stdout.log y daemon.stderr.log (para una instalación predeterminada, %USERPROFILE%\.zeroclaw\logs\):

cmd

type %USERPROFILE%\.zeroclaw\logs\daemon.stdout.log

Control manual (Programador de tareas)

La tarea se controla mediante zeroclaw service start|stop|status, que envuelven schtasks /Run, /End y /Query contra la tarea ZeroClaw Daemon. También puedes administrarla directamente:

cmd

schtasks /Run /TN Daemon de ZeroClaw
schtasks /End /TN Daemon de ZeroClaw
schtasks /Query /TN Daemon de ZeroClaw /FO LIST

La CLI instala únicamente una tarea ONLOGON por usuario; no registra un servicio de Windows LocalSystem. Para un verdadero servicio del sistema, envuelva el binario usted mismo con un supervisor de terceros (p. ej., NSSM).

Resolución de la ruta de configuración

El servicio lee la configuración del directorio que se haya resuelto en el momento de la instalación. Precedencia (gana la primera coincidencia):

$ZEROCLAW_CONFIG_DIR (la configuración se encuentra directamente bajo $ZEROCLAW_CONFIG_DIR)
$ZEROCLAW_DATA_DIR
$ZEROCLAW_WORKSPACE (obsoleto, se prefiere ZEROCLAW_DATA_DIR; resuelve $ZEROCLAW_WORKSPACE o el directorio hermano heredado .zeroclaw/)
Solo en macOS, el directorio de configuración de Homebrew ($HOMEBREW_PREFIX/var/zeroclaw/) cuando se instala mediante Homebrew
Predeterminado ~/.zeroclaw/ (Linux/macOS) o %USERPROFILE%\.zeroclaw\ (Windows)

ZEROCLAW_CONFIG_DIR tiene prioridad sobre todo lo demás; configurarla junto con ZEROCLAW_DATA_DIR o ZEROCLAW_WORKSPACE registra una advertencia e ignora las demás.

Si su servicio parece ignorar los cambios de configuración, verifique contra qué ruta resolvió el daemon, zeroclaw status informa el archivo de configuración activo, y el runtime registra una línea de origen de resolución al iniciarse:

sh

zeroclaw status

La salida incluye la ruta del archivo de configuración con respecto a la cual se resolvió.

Actualización automática

El servicio no se actualiza automáticamente. Esto es deliberado; usted decide cuándo adoptar el código nuevo. Suscríbase al feed de versiones de GitHub o al canal #releases de Discord (consulte Contributing → Communication).

ZeroClaw Docs