Referência de comandos

Referência completa para todos os comandos da CLI NovitaClaw.

`launch`

Crie uma nova instância de sandbox.

Bash

novitaclaw launch [OPTIONS]

Opção	Descrição
`--api-key`	Chave de API da Novita
`--gateway-token`	Token de gateway personalizado (opcional, gerado automaticamente por padrão)
`--timeout`	Tempo limite de criação em segundos (padrão: `60`)
`--type`	Tipo de sandbox: `persistent` (padrão) ou `on-demand`
`--idle-timeout`	Tempo limite de inatividade em segundos para o modo sob demanda (padrão: `300`, intervalo: 60–86400)

`list`

Liste instâncias de sandbox ativas.

Bash

novitaclaw list --api-key YOUR_API_KEY

Opção	Descrição
`--api-key`	Chave de API da Novita
`--quiet`, `-q`	Imprimir apenas IDs de sandbox, um por linha (útil para scripts)

`status`

Verifique o status de uma instância de sandbox. Exibe URLs de webhook para todos os canais configurados.

Bash

novitaclaw status <SANDBOX_ID> --api-key YOUR_API_KEY

Opção	Descrição
`--api-key`	Chave de API da Novita
`--json`	Saída em formato JSON (útil para extrair URLs de webhook)

`stop`

Encerre uma instância de sandbox.

Bash

novitaclaw stop <SANDBOX_ID> --api-key YOUR_API_KEY

Opção	Descrição
`--api-key`	Chave de API da Novita
`--yes`, `-y`	Ignorar prompt de confirmação

`pause`

Pause uma instância de sandbox. Sem cobrança enquanto estiver pausada.

Bash

novitaclaw pause <SANDBOX_ID> --api-key YOUR_API_KEY

`resume`

Retome uma instância de sandbox pausada (~1s para restaurar).

Bash

novitaclaw resume <SANDBOX_ID> --api-key YOUR_API_KEY

`config set`

Atualize a configuração de runtime do sandbox.

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

`tui`

Conecte-se a um sandbox via interface de terminal.

Bash

novitaclaw tui <SANDBOX_ID> --token <GATEWAY_TOKEN>

`doctor`

Execute diagnósticos e verificações de reparo em uma instância de sandbox.

Bash

novitaclaw doctor <SANDBOX_ID> --api-key YOUR_API_KEY

Opção	Descrição
`--api-key`	Chave de API da Novita
`--deep`	Verificar serviços do sistema em busca de instalações extras do gateway
`--fix`	Aplicar reparos recomendados (alias para `--repair`)
`--force`	Aplicar reparos agressivos (sobrescreve a configuração de serviço personalizada)
`--generate-gateway-token`	Gerar e configurar um token de gateway
`--no-workspace-suggestions`	Desativar sugestões do sistema de memória do workspace
`--repair`	Aplicar reparos recomendados sem solicitar confirmação
`--yes`	Aceitar padrões sem solicitar confirmação

`gateway update`

Atualize o OpenClaw para a versão mais recente dentro de um sandbox.

Bash

novitaclaw gateway update <SANDBOX_ID> --api-key YOUR_API_KEY

Opção	Descrição
`--api-key`	Chave de API da Novita
`--restart`	Reiniciar o gateway após a atualização

`gateway restart`

Reinicie o OpenClaw Gateway em um sandbox.

Bash

novitaclaw gateway restart <SANDBOX_ID> --api-key YOUR_API_KEY

`services setup`

Instale e inicie o Web Terminal e o File Manager em um sandbox existente. Use isto para adicionar serviços a sandboxes mais antigos que foram iniciados antes de estes serviços serem incluídos.

Bash

novitaclaw services setup <SANDBOX_ID> --api-key YOUR_API_KEY

`pair list`

Liste solicitações de pareamento pendentes para um canal.

Bash

novitaclaw pair list <SANDBOX_ID> --channel <CHANNEL_NAME> --api-key YOUR_API_KEY

`pair approve`

Aprove uma solicitação de pareamento para um canal.

Bash

novitaclaw pair approve <SANDBOX_ID> --channel <CHANNEL_NAME> --code <PAIRING_CODE> --api-key YOUR_API_KEY

`pair feishu`

Configure o Feishu (Lark) como um canal de mensagens.

Bash

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

Opção	Descrição
`--app-id`	ID do app Feishu
`--app-secret`	Segredo do app Feishu
`--mode`	`event` (padrão) ou `webhook`
`--verification-token`	Token de verificação do webhook (somente modo webhook)
`--encrypt-key`	Chave de criptografia do webhook (somente modo webhook)
`--webhook-host`	Endereço de vinculação do webhook (padrão: `0.0.0.0`)
`--webhook-port`	Porta de escuta do webhook (padrão: `3000`)
`--webhook-path`	Caminho da URL do webhook (padrão: `/feishu/events`)

`pair telegram`

Configure o Telegram como um canal de mensagens.

Bash

# Polling mode (default)
novitaclaw pair telegram <SANDBOX_ID> \
  --bot-token <BOT_TOKEN>

# Webhook mode
novitaclaw pair telegram <SANDBOX_ID> \
  --bot-token <BOT_TOKEN> \
  --mode webhook \
  --webhook-url https://example.com/webhook/telegram \
  --webhook-secret <SECRET>

Opção	Descrição
`--bot-token`	Token do bot do Telegram obtido no BotFather
`--mode`	`polling` (padrão) ou `webhook`
`--webhook-url`	URL pública do webhook (somente modo webhook)
`--webhook-secret`	Segredo do webhook (somente modo webhook)
`--webhook-host`	Endereço de vinculação do webhook (padrão: `0.0.0.0`)
`--webhook-port`	Porta de escuta do webhook (padrão: `8787`)
`--webhook-path`	Caminho da URL do webhook (padrão: `/webhook/telegram`)
`--dm-policy`	Política de DM (padrão: `pairing`)

`pair slack`

Configure o Slack como um canal de mensagens.

Bash

# Socket mode (default)
novitaclaw pair slack <SANDBOX_ID> \
  --bot-token xoxb-... \
  --app-token xapp-...

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

Opção	Descrição
`--bot-token`	Token do bot do Slack (`xoxb-...`)
`--app-token`	Token do app Slack (`xapp-...`, somente modo socket)
`--mode`	`socket` (padrão) ou `http`
`--signing-secret`	Segredo de assinatura do Slack (somente modo HTTP)
`--webhook-host`	Endereço de vinculação do webhook (padrão: `0.0.0.0`)
`--webhook-port`	Porta de escuta do webhook (padrão: `8788`)
`--webhook-path`	Caminho da URL do webhook (padrão: `/webhook/slack`)

`update`

Verifique atualizações da CLI e atualize para a versão mais recente.

Bash

novitaclaw update

Uso programático

Use saída JSON para automação:

Bash

novitaclaw -j launch --api-key YOUR_API_KEY

Exemplo de resposta:

{
  "success": true,
  "data": {
    "sandbox_id": "xxx",
    "webui": "https://xxx.sandbox.novita.ai?token=xxx",
    "gateway_ws": "wss://xxx.sandbox.novita.ai",
    "gateway_token": "xxx",
    "terminal_url": "https://7681-xxx.sandbox.novita.ai",
    "filemanager_url": "https://7682-xxx.sandbox.novita.ai",
    "services_username": "admin",
    "services_password": "xxx"
  }
}

Variáveis de ambiente

Variável	Descrição
`NOVITA_API_KEY`	Chave de API, elimina a necessidade da flag `--api-key`
`OPENCLAW_GATEWAY_TOKEN`	Token de gateway predefinido

Solução de problemas

Comando não encontrado

Tente uma destas opções:

Bash

# Use full path (Linux)
~/.local/bin/novitaclaw launch

# Typical macOS user path
~/Library/Python/3.x/bin/novitaclaw launch

Tempo limite de conexão

Aumente o tempo limite de inicialização:

Bash

novitaclaw launch --timeout 180 --api-key YOUR_API_KEY

Perguntas frequentes

Problema	Por que acontece	O que fazer
”Command not found” / “Not recognized”	O PATH do Python não foi configurado durante a instalação	Reinstale o Python e marque “Add to PATH”, ou adicione o diretório bin manualmente
”Permission Denied”	Permissões insuficientes	Windows: execute o Terminal como Administrador. Mac/Linux: prefixe com `sudo`
”Invalid API Key”	Chave copiada incorretamente	Verifique se há espaços extras ao redor da string `sk_`, ou gere uma nova chave
O sandbox não para	Requer confirmação para evitar exclusão acidental	Digite `y` quando solicitado, ou use `--yes` para ignorar a confirmação
Mac: comando `pip` não encontrado	O macOS usa `pip3` por padrão	Use `pip3 install novitaclaw` em vez de `pip`

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

`launch`

`list`

`status`

`stop`

`pause`

`resume`

`config set`

`tui`

`doctor`

`gateway update`

`gateway restart`

`services setup`

`pair list`

`pair approve`

`pair feishu`

`pair telegram`

`pair slack`

`update`

Uso programático

Variáveis de ambiente

Solução de problemas

Comando não encontrado

Tempo limite de conexão

Perguntas frequentes

​launch

​list

​status

​stop

​pause

​resume

​config set

​tui

​doctor

​gateway update

​gateway restart

​services setup

​pair list

​pair approve

​pair feishu

​pair telegram

​pair slack

​update

​Uso programático

​Variáveis de ambiente

​Solução de problemas

​Comando não encontrado

​Tempo limite de conexão

​Perguntas frequentes

`launch`

`list`

`status`

`stop`

`pause`

`resume`

`config set`

`tui`

`doctor`

`gateway update`

`gateway restart`

`services setup`

`pair list`

`pair approve`

`pair feishu`

`pair telegram`

`pair slack`

`update`

Uso programático

Variáveis de ambiente

Solução de problemas

Comando não encontrado

Tempo limite de conexão

Perguntas frequentes