> ## Documentation Index > Fetch the complete documentation index at: https://novita.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 Bash icon="terminal" theme={"system"} # 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 Bash icon="terminal" theme={"system"} # Pause a sandbox (zero billing while paused) novitaclaw pause # Resume a sandbox (~1s to restore to pre-pause state) novitaclaw resume ``` ### Configuração em tempo de execução ```bash Bash icon="terminal" theme={"system"} # Update idle timeout (60–86400 seconds) novitaclaw config set idle-timeout 600 # Update sandbox lifetime timeout (300–2592000 seconds) novitaclaw config set 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 1. **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`. 2. **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. 3. **Retomada automática** — Solicitações de webhook recebidas ou acesso pela Web UI retomam automaticamente um sandbox pausado. 4. **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 Bash icon="terminal" theme={"system"} # View sandbox status (does not trigger resume when paused) novitaclaw status # 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`: ```json theme={"system"} { "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`: ```json theme={"system"} { "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](https://novita.ai/model-api/product/llm-api) 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. Configuração de modelo do NovitaClaw ## 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. ### Telegram 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** 1. Abra o Telegram e encontre [@BotFather](https://t.me/BotFather). 2. Envie `/newbot` e siga as instruções para nomear seu bot. 3. 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 Bash icon="terminal" theme={"system"} novitaclaw pair telegram \ --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 Bash icon="terminal" theme={"system"} novitaclaw status --json | jq -r '.telegram_webhook_url' ``` ```bash Bash icon="terminal" theme={"system"} novitaclaw pair telegram \ --bot-token \ --mode webhook \ --webhook-url \ --webhook-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 Bash icon="terminal" theme={"system"} # List pending pairing requests novitaclaw pair list --channel telegram # Approve a pairing request novitaclaw pair approve --channel telegram --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 Bash icon="terminal" theme={"system"} novitaclaw pair slack \ --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 Bash icon="terminal" theme={"system"} novitaclaw pair slack \ --bot-token xoxb-... \ --mode http \ --signing-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 Bash icon="terminal" theme={"system"} # List pending pairing requests novitaclaw pair list --channel slack # Approve a pairing request novitaclaw pair approve --channel slack --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 Bash icon="terminal" theme={"system"} novitaclaw status # Shows: Feishu Webhook, Telegram Webhook, Slack Webhook (when configured) # JSON mode novitaclaw status --json | jq -r '.feishu_webhook_url' novitaclaw status --json | jq -r '.telegram_webhook_url' novitaclaw status --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 1. Abra a [Feishu Open Platform](https://open.feishu.cn/app), faça login e clique em **Create Custom App**. 2. Na página **Credentials & Basic Info**, copie: * **App ID** (formato: `cli_xxx`) * **App Secret** 3. Vá para **Permission Management**, clique em **Batch Import** e cole as seguintes permissões: ```json theme={"system"} { "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"] } } ``` 4. Vá para **App Capabilities > Bot** e habilite a capacidade de bot. 5. 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 Bash icon="terminal" theme={"system"} novitaclaw pair feishu \ --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: 1. Selecione **Request URL Configuration** 2. Insira a URL do webhook — obtenha-a via: ```bash Bash icon="terminal" theme={"system"} novitaclaw status --json | jq -r '.feishu_webhook_url' ``` 3. 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 Bash icon="terminal" theme={"system"} novitaclaw pair feishu \ --app-id cli_xxx \ --app-secret secret_xxx ``` Após a configuração, na página **Event Subscription** da Feishu Open Platform: 1. Selecione **Use Long Connection to Receive Events** 2. Adicione o evento: `im.message.receive_v1` Certifique-se de que o gateway esteja em execução (`novitaclaw status `) 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 Bash icon="terminal" theme={"system"} # List pending pairing requests novitaclaw pair list --channel feishu # Approve a pairing request novitaclaw pair approve --channel feishu --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.