> ## 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.

# Referência de comandos

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

## `launch`

Crie uma nova instância de sandbox.

```bash Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
novitaclaw pause <SANDBOX_ID> --api-key YOUR_API_KEY
```

## `resume`

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

```bash Bash icon="terminal" theme={"system"}
novitaclaw resume <SANDBOX_ID> --api-key YOUR_API_KEY
```

## `config set`

Atualize a configuração de runtime do sandbox.

```bash Bash icon="terminal" theme={"system"}
# 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 Bash icon="terminal" theme={"system"}
novitaclaw tui <SANDBOX_ID> --token <GATEWAY_TOKEN>
```

## `doctor`

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

```bash Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
novitaclaw services setup <SANDBOX_ID> --api-key YOUR_API_KEY
```

## `pair list`

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

```bash Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
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 Bash icon="terminal" theme={"system"}
# 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 Bash icon="terminal" theme={"system"}
# 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 Bash icon="terminal" theme={"system"}
novitaclaw update
```

## Uso programático

Use saída JSON para automação:

```bash Bash icon="terminal" theme={"system"}
novitaclaw -j launch --api-key YOUR_API_KEY
```

Exemplo de resposta:

```json theme={"system"}
{
  "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 Bash icon="terminal" theme={"system"}
# 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 Bash icon="terminal" theme={"system"}
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`                                      |