Configuração

Configure modelos, conecte canais de mensagens externos, configure o modo sob demanda e entenda os recursos de confiabilidade de serviço da sua instância NovitaClaw.

Modo sob demanda

O modo sob demanda pausa automaticamente seu sandbox após um período de inatividade configurável e o retoma ao ser acessado. Ideal para assistentes de IA com baixo tráfego, integrações de IM baseadas em webhook e tarefas agendadas. Sem cobrança enquanto estiver pausado.

Iniciando um sandbox sob 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

O modo sob demanda não pode ser combinado com --mode node.

Pausa e retomada manuais

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>

Configuração em tempo de execução

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

As alterações entram em vigor imediatamente. O agente dentro do sandbox obtém a nova configuração no próximo ciclo de verificação.

Como funciona

Detecção de inatividade — Um daemon de agente dentro do sandbox verifica periodicamente a atividade da sessão do OpenClaw e grava o status em /tmp/.novitaclaw-status.json.
Pausa automática — O monitor de inatividade no lado do servidor lê o status do agente. Após 2 verificações consecutivas de inatividade, o sandbox é pausado automaticamente.
Retomada automática — Solicitações de webhook recebidas ou acesso pela Web UI retomam automaticamente um sandbox pausado.
Pré-ativação por cron — O agendador verifica sandboxes pausados em busca de agendamentos cron próximos e os retoma cerca de 120 segundos antes da execução do próximo job, garantindo que os jobs cron sejam executados no horário.

Verificando o status

Bash

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

# List shows sandbox_type and state columns
novitaclaw list

Enquanto estiver pausado, o comando status ainda retorna as informações completas de URL (lidas do banco de dados sem se conectar ao sandbox), para que scripts possam armazenar endereços sem acionar uma retomada.

Configurando modelos

Sua instância vem pré-configurada com um modelo hospedado pela Novita por padrão. Para alterar os modelos que seu agente usa, navegue até Settings → Config, clique em Raw para alternar para a visualização Raw JSON5 e, em seguida, clique no botão de revelação ao lado de “secrets redacted” para mostrar a configuração completa. Atualize as duas seções a seguir:

Etapa 1: Registre o modelo no seu provedor

Adicione um novo objeto ao 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
          }
        ]
      }
    }
  }
}

Etapa 2: Defina-o como primário ou fallback

Atualize o campo model em agents.defaults para referenciar seu modelo usando o formato provider/model-id:

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

Clique em Update para salvar. Todos os LLMs disponíveis na plataforma Novita são compatíveis. Provedores de terceiros também podem ser configurados — ao trazer seu próprio LLM, você paga apenas pelo tempo de execução do sandbox, não pelo uso de modelos da Novita.

Conectando canais

O OpenClaw oferece suporte a canais de mensagens externos para que seu agente possa ser acessado fora da Web UI. Os canais são desativados por padrão e devem ser configurados.

Conecte seu agente ao Telegram como um canal de mensagens. Dois modos de conexão são suportados: Polling (padrão, long-poll — não requer URL pública) e Webhook (push HTTP — ideal para sandboxes sob demanda). Etapa 1: Crie um bot do Telegram

Abra o Telegram e encontre @BotFather.
Envie /newbot e siga as instruções para nomear seu bot.
Copie o token do bot fornecido pelo BotFather.

Modo 1: Polling

O modo Polling usa conexões long-poll. Não requer URL pública — é o mais simples de configurar.

O modo Polling não é recomendado para sandboxes sob demanda. Quando o sandbox entra em pausa automática, a conexão cai e as mensagens recebidas são perdidas. Use o modo Webhook para sandboxes sob demanda.

Bash

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

Modo 2: Webhook

O modo Webhook exige que o sandbox exponha uma porta HTTP para receber eventos push do Telegram. Mais adequado para sandboxes sob demanda — solicitações de webhook recebidas acionam automaticamente a retomada.

O --webhook-url é a URL pública atribuída ao seu sandbox. Execute o comando a seguir para obtê-la:

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 opcionais de Webhook

Parâmetro	Padrão	Descrição
`--webhook-host`	`0.0.0.0`	Endereço de bind do servidor de webhook
`--webhook-port`	`8787`	Porta de escuta do webhook
`--webhook-path`	`/webhook/telegram`	Caminho da URL do webhook
`--dm-policy`	`pairing`	Política de DM

Fluxo de pareamento

Na primeira conversa, o bot responde com um código de pareamento:

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>

Comparação de modos

	Polling	Webhook
Conexão	Saída (long-poll)	Entrada (push HTTP)
Porta pública	Não necessária	Necessária
Complexidade de configuração	Baixa	Média (segredos adicionais)
Retomada automática sob demanda	Não suportada (a conexão cai ao pausar)	Suportada (webhook aciona a retomada)
Recomendado para	Sandboxes sempre ativos, desenvolvimento	Sandboxes sob demanda, IM em produção

Slack

Conecte seu agente ao Slack como um canal de mensagens. Dois modos de conexão são suportados: Socket (padrão, WebSocket — não requer URL pública) e HTTP (webhook da Events API — ideal para sandboxes sob demanda).

Modo 1: Socket

O modo Socket usa uma conexão WebSocket. Não requer URL pública — é o mais simples de configurar.

O modo Socket não é recomendado para sandboxes sob demanda. Quando o sandbox entra em pausa automática, a conexão WebSocket cai e as mensagens recebidas são perdidas. Use o modo HTTP para sandboxes sob demanda.

Bash

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

Modo 2: HTTP

O modo HTTP usa webhooks da Slack Events API. Mais adequado para sandboxes sob demanda — solicitações de webhook recebidas acionam automaticamente a retomada.

Bash

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

Parâmetros HTTP opcionais

Parâmetro	Padrão	Descrição
`--webhook-host`	`0.0.0.0`	Endereço de bind do servidor de webhook
`--webhook-port`	`8788`	Porta de escuta do webhook
`--webhook-path`	`/webhook/slack`	Caminho da URL do webhook

Fluxo de pareamento

Na primeira conversa, o bot responde com um código de pareamento:

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>

Comparação de modos

	Socket	HTTP
Conexão	WebSocket (saída)	Push HTTP (entrada)
Porta pública	Não necessária	Necessária
Complexidade de configuração	Baixa	Média (segredos adicionais)
Retomada automática sob demanda	Não suportada (a conexão cai ao pausar)	Suportada (webhook aciona a retomada)
Recomendado para	Sandboxes sempre ativos, desenvolvimento	Sandboxes sob demanda, IM em produção

Status dos canais

novitaclaw status exibe URLs de webhook para todos os canais 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

Conecte seu agente ao Feishu (Lark) como um canal de mensagens. Dois modos de conexão são suportados: Webhook (push HTTP) e Event (long-poll WebSocket).

Pré-requisitos: Crie um app do Feishu

Abra a Feishu Open Platform, faça login e clique em Create Custom App.
Na página Credentials & Basic Info, copie:
- App ID (formato: cli_xxx)
- App Secret

Vá para Permission Management, clique em Batch Import e cole as seguintes permissões:

{
  "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"]
  }
}

Vá para App Capabilities > Bot e habilite a capacidade de bot.
Crie uma versão e publique o app.

Modo 1: Webhook

O modo Webhook exige que o sandbox exponha uma porta HTTP para receber eventos push do Feishu. Mais adequado para sandboxes sob demanda — solicitações de webhook recebidas acionam automaticamente a retomada. Credenciais adicionais: Na Feishu Open Platform, vá para Development Configuration > Events & Callbacks > Encryption Strategy e copie:

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

Na página Event Subscription da Feishu Open Platform:

Selecione Request URL Configuration

Insira a URL do webhook — obtenha-a via:

Bash

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

Adicione o evento: im.message.receive_v1

Modo 2: Event

O modo Event usa uma conexão long-poll WebSocket do Feishu. Não requer URL pública — é o mais simples de configurar.

O modo Event não é recomendado para sandboxes sob demanda. Quando o sandbox entra em pausa automática, a conexão WebSocket cai e as mensagens recebidas são perdidas. Use o modo Webhook para sandboxes sob demanda.

Bash

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

Após a configuração, na página Event Subscription da Feishu Open Platform:

Selecione Use Long Connection to Receive Events
Adicione o evento: im.message.receive_v1

Certifique-se de que o gateway esteja em execução (novitaclaw status <SANDBOX_ID>) antes de salvar; caso contrário, o Feishu pode falhar ao salvar a configuração de conexão longa.

Parâmetros opcionais de Webhook

Parâmetro	Padrão	Descrição
`--webhook-host`	`0.0.0.0`	Endereço de bind do servidor de webhook
`--webhook-port`	`3000`	Porta de escuta do webhook
`--webhook-path`	`/feishu/events`	Caminho da URL do webhook

Fluxo de pareamento

O Feishu usa uma estratégia pairing por padrão. Na primeira conversa, o bot responde com um código de pareamento que deve ser aprovado via 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>

Comparação de modos

	Event	Webhook
Conexão	Long-poll WebSocket (saída)	Push HTTP (entrada)
Porta pública	Não necessária	Necessária (padrão 3000)
Complexidade de configuração	Baixa (apenas App ID + Secret)	Média (Token + Key adicionais)
Retomada automática sob demanda	Não suportada	Suportada (webhook aciona a retomada)
Recomendado para	Sandboxes sempre ativos, desenvolvimento	Sandboxes sob demanda, IM em produção

Confiabilidade do serviço

Todos os serviços principais no sandbox são gerenciados pelo systemd para confiabilidade de nível de produção:

Serviço	Descrição	Reinício automático
OpenClaw Gateway	Runtime do agente e servidor WebSocket	✅
Web Terminal (ttyd)	Acesso ao terminal baseado no navegador	✅
File Manager (gohttpserver)	Gerenciamento de arquivos baseado na web	✅

Recuperação automática de falhas: Se o Gateway falhar repetidamente, o sistema executa diagnósticos automaticamente, tenta reparar e restaura a última configuração válida conhecida a partir do backup — sem necessidade de intervenção manual. Backup automático de configuração: Cada gravação de configuração cria um backup automático. Se uma configuração inválida causar uma falha, o processo de recuperação restaura a partir do backup válido mais recente.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Modo sob demanda

Iniciando um sandbox sob demanda

Pausa e retomada manuais

Configuração em tempo de execução

Como funciona

Verificando o status

Configurando modelos

Etapa 1: Registre o modelo no seu provedor

Etapa 2: Defina-o como primário ou fallback

Conectando canais

Telegram

Modo 1: Polling

Modo 2: Webhook

Parâmetros opcionais de Webhook

Fluxo de pareamento

Comparação de modos

Slack

Modo 1: Socket

Modo 2: HTTP

Parâmetros HTTP opcionais

Fluxo de pareamento

Comparação de modos

Status dos canais

Feishu

Pré-requisitos: Crie um app do Feishu

Modo 1: Webhook

Modo 2: Event

Parâmetros opcionais de Webhook

Fluxo de pareamento

Comparação de modos

Confiabilidade do serviço

​Modo sob demanda

​Iniciando um sandbox sob demanda

​Pausa e retomada manuais

​Configuração em tempo de execução

​Como funciona

​Verificando o status

​Configurando modelos

​Etapa 1: Registre o modelo no seu provedor

​Etapa 2: Defina-o como primário ou fallback

​Conectando canais

​Telegram

​Modo 1: Polling

​Modo 2: Webhook

​Parâmetros opcionais de Webhook

​Fluxo de pareamento

​Comparação de modos

​Slack

​Modo 1: Socket

​Modo 2: HTTP

​Parâmetros HTTP opcionais

​Fluxo de pareamento

​Comparação de modos

​Status dos canais

​Feishu

​Pré-requisitos: Crie um app do Feishu

​Modo 1: Webhook

​Modo 2: Event

​Parâmetros opcionais de Webhook

​Fluxo de pareamento

​Comparação de modos

​Confiabilidade do serviço

Modo sob demanda

Iniciando um sandbox sob demanda

Pausa e retomada manuais

Configuração em tempo de execução

Como funciona

Verificando o status

Configurando modelos

Etapa 1: Registre o modelo no seu provedor

Etapa 2: Defina-o como primário ou fallback

Conectando canais

Telegram

Modo 1: Polling

Modo 2: Webhook

Parâmetros opcionais de Webhook

Fluxo de pareamento

Comparação de modos

Slack

Modo 1: Socket

Modo 2: HTTP

Parâmetros HTTP opcionais

Fluxo de pareamento

Comparação de modos

Status dos canais

Feishu

Pré-requisitos: Crie um app do Feishu

Modo 1: Webhook

Modo 2: Event

Parâmetros opcionais de Webhook

Fluxo de pareamento

Comparação de modos

Confiabilidade do serviço