Configuración

Configura modelos, conecta canales de mensajería externos, establece el modo bajo demanda y comprende las funciones de fiabilidad del servicio de tu instancia de NovitaClaw.

Modo bajo demanda

El modo bajo demanda pausa automáticamente tu sandbox tras un período de inactividad configurable y lo reanuda al acceder. Es ideal para asistentes de IA con poco tráfico, integraciones de mensajería instantánea basadas en webhooks y tareas programadas. Sin facturación mientras está pausado.

Iniciar un sandbox bajo demanda

Bash

# Default idle timeout: 300 seconds
novitaclaw launch --type on-demand

# Custom idle timeout (60–86400 seconds)
novitaclaw launch --type on-demand --idle-timeout 600

El modo bajo demanda no se puede combinar con --mode node.

Pausa y reanudación manuales

Bash

# Pause a sandbox (zero billing while paused)
novitaclaw pause <SANDBOX_ID>

# Resume a sandbox (~1s to restore to pre-pause state)
novitaclaw resume <SANDBOX_ID>

Configuración en tiempo de ejecución

Bash

# Update idle timeout (60–86400 seconds)
novitaclaw config set <SANDBOX_ID> idle-timeout 600

# Update sandbox lifetime timeout (300–2592000 seconds)
novitaclaw config set <SANDBOX_ID> timeout 3600

Los cambios surten efecto inmediatamente. El agente dentro del sandbox recoge la nueva configuración en su siguiente ciclo de comprobación.

Cómo funciona

Detección de inactividad — Un daemon de agente dentro del sandbox comprueba periódicamente la actividad de las sesiones de OpenClaw y escribe el estado en /tmp/.novitaclaw-status.json.
Pausa automática — El monitor de inactividad del servidor lee el estado del agente. Después de 2 comprobaciones consecutivas de inactividad, el sandbox se pausa automáticamente.
Reanudación automática — Las solicitudes de webhook entrantes o el acceso a la interfaz web reanudan automáticamente un sandbox pausado.
Preactivación de cron — El programador analiza los sandboxes pausados en busca de próximas programaciones cron y los reanuda ~120 segundos antes de que se ejecute el siguiente trabajo, lo que garantiza que los trabajos cron se ejecuten a tiempo.

Comprobar el estado

Bash

# View sandbox status (does not trigger resume when paused)
novitaclaw status <SANDBOX_ID>

# List shows sandbox_type and state columns
novitaclaw list

Mientras está pausado, el comando status sigue devolviendo la información completa de las URL (leída desde la base de datos sin conectarse al sandbox), de modo que los scripts pueden almacenar direcciones sin activar una reanudación.

Configurar modelos

Tu instancia viene preconfigurada con un modelo alojado por Novita listo para usar. Para cambiar los modelos que utiliza tu agente, ve a Settings → Config, haz clic en Raw para cambiar a la vista Raw JSON5 y, a continuación, haz clic en el botón de revelado junto a “secrets redacted” para mostrar la configuración completa. Actualiza las dos secciones siguientes:

Paso 1: Registra el modelo bajo tu proveedor

Añade un nuevo objeto al array models dentro de models.providers.novita:

{
  "models": {
    "providers": {
      "novita": {
        "models": [
          {
            "id": "model-id",
            "name": "display name",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 50000
          }
        ]
      }
    }
  }
}

Paso 2: Establécelo como principal o de respaldo

Actualiza el campo model bajo agents.defaults para referenciar tu modelo usando el formato provider/model-id:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "novita/model-id",
        "fallbacks": ["novita/fallback-model-id"]
      }
    }
  }
}

Haz clic en Update para guardar. Se admite cualquier LLM disponible en la plataforma Novita. También se pueden configurar proveedores de terceros: cuando traes tu propio LLM, solo pagas por el tiempo de ejecución del sandbox, no por el uso de modelos de Novita.

Conectar canales

OpenClaw admite canales de mensajería externos para que tu agente esté disponible fuera de la interfaz web. Los canales están deshabilitados de forma predeterminada y deben configurarse.

Conecta tu agente a Telegram como canal de mensajería. Se admiten dos modos de conexión: Polling (predeterminado, long-poll; no se necesita URL pública) y Webhook (push HTTP; ideal para sandboxes bajo demanda). Paso 1: Crea un bot de Telegram

Abre Telegram y busca @BotFather.
Envía /newbot y sigue las indicaciones para poner nombre a tu bot.
Copia el token del bot que proporciona BotFather.

Modo 1: Polling

El modo Polling usa conexiones long-poll. No requiere URL pública; es el más sencillo de configurar.

El modo Polling no se recomienda para sandboxes bajo demanda. Cuando el sandbox se pausa automáticamente, la conexión se interrumpe y los mensajes entrantes se pierden. Usa el modo Webhook para sandboxes bajo demanda.

Bash

novitaclaw pair telegram <SANDBOX_ID> \
  --bot-token <BOT_TOKEN>

Modo 2: Webhook

El modo Webhook requiere que el sandbox exponga un puerto HTTP para recibir eventos push de Telegram. Es el más adecuado para sandboxes bajo demanda: las solicitudes de webhook entrantes activan automáticamente la reanudación.

--webhook-url es la URL pública asignada a tu sandbox. Ejecuta el siguiente comando para obtenerla:

Bash

novitaclaw status <SANDBOX_ID> --json | jq -r '.telegram_webhook_url'

Bash

novitaclaw pair telegram <SANDBOX_ID> \
  --bot-token <BOT_TOKEN> \
  --mode webhook \
  --webhook-url <WEBHOOK_URL> \
  --webhook-secret <SECRET>

Parámetros opcionales de Webhook

Parámetro	Predeterminado	Descripción
`--webhook-host`	`0.0.0.0`	Dirección de enlace del servidor Webhook
`--webhook-port`	`8787`	Puerto de escucha de Webhook
`--webhook-path`	`/webhook/telegram`	Ruta de URL de Webhook
`--dm-policy`	`pairing`	Política de DM

Flujo de emparejamiento

En la primera conversación, el bot responde con un código de emparejamiento:

Bash

# List pending pairing requests
novitaclaw pair list <SANDBOX_ID> --channel telegram

# Approve a pairing request
novitaclaw pair approve <SANDBOX_ID> --channel telegram --code <CODE>

Comparación de modos

	Polling	Webhook
Conexión	Saliente (long-poll)	Entrante (push HTTP)
Puerto público	No requerido	Requerido
Complejidad de configuración	Baja	Media (secretos adicionales)
Reanudación automática bajo demanda	No compatible (la conexión se interrumpe al pausar)	Compatible (el webhook activa la reanudación)
Recomendado para	Sandboxes siempre activos, desarrollo	Sandboxes bajo demanda, mensajería instantánea en producción

Slack

Conecta tu agente a Slack como canal de mensajería. Se admiten dos modos de conexión: Socket (predeterminado, WebSocket; no se necesita URL pública) y HTTP (webhook de Events API; ideal para sandboxes bajo demanda).

Modo 1: Socket

El modo Socket usa una conexión WebSocket. No requiere URL pública; es el más sencillo de configurar.

El modo Socket no se recomienda para sandboxes bajo demanda. Cuando el sandbox se pausa automáticamente, la conexión WebSocket se interrumpe y los mensajes entrantes se pierden. Usa el modo HTTP para sandboxes bajo demanda.

Bash

novitaclaw pair slack <SANDBOX_ID> \
  --bot-token xoxb-... \
  --app-token xapp-...

Modo 2: HTTP

El modo HTTP usa webhooks de Slack Events API. Es el más adecuado para sandboxes bajo demanda: las solicitudes de webhook entrantes activan automáticamente la reanudación.

Bash

novitaclaw pair slack <SANDBOX_ID> \
  --bot-token xoxb-... \
  --mode http \
  --signing-secret <SECRET>

Parámetros HTTP opcionales

Parámetro	Predeterminado	Descripción
`--webhook-host`	`0.0.0.0`	Dirección de enlace del servidor Webhook
`--webhook-port`	`8788`	Puerto de escucha de Webhook
`--webhook-path`	`/webhook/slack`	Ruta de URL de Webhook

Flujo de emparejamiento

En la primera conversación, el bot responde con un código de emparejamiento:

Bash

# List pending pairing requests
novitaclaw pair list <SANDBOX_ID> --channel slack

# Approve a pairing request
novitaclaw pair approve <SANDBOX_ID> --channel slack --code <CODE>

Comparación de modos

	Socket	HTTP
Conexión	WebSocket (saliente)	Push HTTP (entrante)
Puerto público	No requerido	Requerido
Complejidad de configuración	Baja	Media (secretos adicionales)
Reanudación automática bajo demanda	No compatible (la conexión se interrumpe al pausar)	Compatible (el webhook activa la reanudación)
Recomendado para	Sandboxes siempre activos, desarrollo	Sandboxes bajo demanda, mensajería instantánea en producción

Estado del canal

novitaclaw status muestra las URL de webhook para todos los canales configurados:

Bash

novitaclaw status <SANDBOX_ID>
# Shows: Feishu Webhook, Telegram Webhook, Slack Webhook (when configured)

# JSON mode
novitaclaw status <SANDBOX_ID> --json | jq -r '.feishu_webhook_url'
novitaclaw status <SANDBOX_ID> --json | jq -r '.telegram_webhook_url'
novitaclaw status <SANDBOX_ID> --json | jq -r '.slack_webhook_url'

Feishu

Conecta tu agente a Feishu (Lark) como canal de mensajería. Se admiten dos modos de conexión: Webhook (push HTTP) y Event (long-poll WebSocket).

Requisitos previos: Crea una aplicación de Feishu

Abre la Feishu Open Platform, inicia sesión y haz clic en Create Custom App.
En la página Credentials & Basic Info, copia:
- App ID (formato: cli_xxx)
- App Secret

Ve a Permission Management, haz clic en Batch Import y pega los siguientes permisos:

{
  "scopes": {
    "tenant": [
      "im:message", "im:message:send_as_bot", "im:message:readonly",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:resource", "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access"
    ],
    "user": ["im:chat.access_event.bot_p2p_chat:read"]
  }
}

Ve a App Capabilities > Bot y habilita la capacidad de bot.
Crea una versión y publica la aplicación.

Modo 1: Webhook

El modo Webhook requiere que el sandbox exponga un puerto HTTP para recibir eventos push de Feishu. Es el más adecuado para sandboxes bajo demanda: las solicitudes de webhook entrantes activan automáticamente la reanudación. Credenciales adicionales: En la Feishu Open Platform, ve a Development Configuration > Events & Callbacks > Encryption Strategy y copia:

Verification Token
Encrypt Key

Bash

novitaclaw pair feishu <SANDBOX_ID> \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode webhook \
  --verification-token tok_xxx \
  --encrypt-key key_xxx

En la página Event Subscription de Feishu Open Platform:

Selecciona Request URL Configuration

Introduce la URL de Webhook; obténla mediante:

Bash

novitaclaw status <SANDBOX_ID> --json | jq -r '.feishu_webhook_url'

Añade el evento: im.message.receive_v1

Modo 2: Event

El modo Event usa una conexión long-poll WebSocket de Feishu. No requiere URL pública; es el más sencillo de configurar.

El modo Event no se recomienda para sandboxes bajo demanda. Cuando el sandbox se pausa automáticamente, la conexión WebSocket se interrumpe y los mensajes entrantes se pierden. Usa el modo Webhook para sandboxes bajo demanda.

Bash

novitaclaw pair feishu <SANDBOX_ID> \
  --app-id cli_xxx \
  --app-secret secret_xxx

Después de la configuración, en la página Event Subscription de Feishu Open Platform:

Selecciona Use Long Connection to Receive Events
Añade el evento: im.message.receive_v1

Asegúrate de que el gateway esté en ejecución (novitaclaw status <SANDBOX_ID>) antes de guardar; de lo contrario, Feishu podría no guardar la configuración de conexión larga.

Parámetros opcionales de Webhook

Parámetro	Predeterminado	Descripción
`--webhook-host`	`0.0.0.0`	Dirección de enlace del servidor Webhook
`--webhook-port`	`3000`	Puerto de escucha de Webhook
`--webhook-path`	`/feishu/events`	Ruta de URL de Webhook

Flujo de emparejamiento

Feishu utiliza una estrategia pairing de forma predeterminada. En la primera conversación, el bot responde con un código de emparejamiento que debe aprobarse mediante CLI:

Bash

# List pending pairing requests
novitaclaw pair list <SANDBOX_ID> --channel feishu

# Approve a pairing request
novitaclaw pair approve <SANDBOX_ID> --channel feishu --code <CODE>

Comparación de modos

	Event	Webhook
Conexión	Long-poll WebSocket (saliente)	Push HTTP (entrante)
Puerto público	No requerido	Requerido (predeterminado 3000)
Complejidad de configuración	Baja (solo App ID + Secret)	Media (Token + Key adicionales)
Reanudación automática bajo demanda	No compatible	Compatible (el webhook activa la reanudación)
Recomendado para	Sandboxes siempre activos, desarrollo	Sandboxes bajo demanda, mensajería instantánea en producción

Fiabilidad del servicio

Todos los servicios principales del sandbox son gestionados por systemd para ofrecer fiabilidad de nivel de producción:

Servicio	Descripción	Reinicio automático
OpenClaw Gateway	Runtime del agente y servidor WebSocket	✅
Web Terminal (ttyd)	Acceso a terminal basado en navegador	✅
File Manager (gohttpserver)	Gestión de archivos basada en web	✅

Recuperación automática ante fallos: Si el Gateway falla repetidamente, el sistema ejecuta diagnósticos automáticamente, intenta repararlo y restaura desde la copia de seguridad la última configuración conocida como válida, sin requerir intervención manual. Copia de seguridad automática de configuración: Cada escritura de configuración crea una copia de seguridad automática. Si una configuración incorrecta provoca un fallo, el proceso de recuperación restaura la copia de seguridad válida más reciente.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Modo bajo demanda

Iniciar un sandbox bajo demanda

Pausa y reanudación manuales

Configuración en tiempo de ejecución

Cómo funciona

Comprobar el estado

Configurar modelos

Paso 1: Registra el modelo bajo tu proveedor

Paso 2: Establécelo como principal o de respaldo

Conectar canales

Telegram

Modo 1: Polling

Modo 2: Webhook

Parámetros opcionales de Webhook

Flujo de emparejamiento

Comparación de modos

Slack

Modo 1: Socket

Modo 2: HTTP

Parámetros HTTP opcionales

Flujo de emparejamiento

Comparación de modos

Estado del canal

Feishu

Requisitos previos: Crea una aplicación de Feishu

Modo 1: Webhook

Modo 2: Event

Parámetros opcionales de Webhook

Flujo de emparejamiento

Comparación de modos

Fiabilidad del servicio

​Modo bajo demanda

​Iniciar un sandbox bajo demanda

​Pausa y reanudación manuales

​Configuración en tiempo de ejecución

​Cómo funciona

​Comprobar el estado

​Configurar modelos

​Paso 1: Registra el modelo bajo tu proveedor

​Paso 2: Establécelo como principal o de respaldo

​Conectar canales

​Telegram

​Modo 1: Polling

​Modo 2: Webhook

​Parámetros opcionales de Webhook

​Flujo de emparejamiento

​Comparación de modos

​Slack

​Modo 1: Socket

​Modo 2: HTTP

​Parámetros HTTP opcionales

​Flujo de emparejamiento

​Comparación de modos

​Estado del canal

​Feishu

​Requisitos previos: Crea una aplicación de Feishu

​Modo 1: Webhook

​Modo 2: Event

​Parámetros opcionales de Webhook

​Flujo de emparejamiento

​Comparación de modos

​Fiabilidad del servicio

Modo bajo demanda

Iniciar un sandbox bajo demanda

Pausa y reanudación manuales

Configuración en tiempo de ejecución

Cómo funciona

Comprobar el estado

Configurar modelos

Paso 1: Registra el modelo bajo tu proveedor

Paso 2: Establécelo como principal o de respaldo

Conectar canales

Telegram

Modo 1: Polling

Modo 2: Webhook

Parámetros opcionales de Webhook

Flujo de emparejamiento

Comparación de modos

Slack

Modo 1: Socket

Modo 2: HTTP

Parámetros HTTP opcionales

Flujo de emparejamiento

Comparación de modos

Estado del canal

Feishu

Requisitos previos: Crea una aplicación de Feishu

Modo 1: Webhook

Modo 2: Event

Parámetros opcionales de Webhook

Flujo de emparejamiento

Comparación de modos

Fiabilidad del servicio