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

# Referencia de comandos

Referencia completa de todos los comandos de NovitaClaw CLI.

## `launch`

Crea una nueva instancia de sandbox.

```bash Bash icon="terminal" theme={"system"}
novitaclaw launch [OPTIONS]
```

| Opción            | Descripción                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `--api-key`       | Clave de API de Novita                                                                                          |
| `--gateway-token` | Token de gateway personalizado (opcional, generado automáticamente de forma predeterminada)                     |
| `--timeout`       | Tiempo de espera de creación en segundos (predeterminado: `60`)                                                 |
| `--type`          | Tipo de sandbox: `persistent` (predeterminado) o `on-demand`                                                    |
| `--idle-timeout`  | Tiempo de espera por inactividad en segundos para el modo bajo demanda (predeterminado: `300`, rango: 60–86400) |

## `list`

Lista las instancias de sandbox activas.

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

| Opción          | Descripción                                                         |
| --------------- | ------------------------------------------------------------------- |
| `--api-key`     | Clave de API de Novita                                              |
| `--quiet`, `-q` | Imprime solo los ID de sandbox, uno por línea (útil para scripting) |

## `status`

Comprueba el estado de una instancia de sandbox. Muestra las URL de webhook para todos los canales configurados.

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

| Opción      | Descripción                                               |
| ----------- | --------------------------------------------------------- |
| `--api-key` | Clave de API de Novita                                    |
| `--json`    | Salida en formato JSON (útil para extraer URL de webhook) |

## `stop`

Termina una instancia de sandbox.

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

| Opción        | Descripción                        |
| ------------- | ---------------------------------- |
| `--api-key`   | Clave de API de Novita             |
| `--yes`, `-y` | Omite la solicitud de confirmación |

## `pause`

Pausa una instancia de sandbox. Sin facturación mientras está pausada.

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

## `resume`

Reanuda una instancia de sandbox pausada (\~1 s para restaurar).

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

## `config set`

Actualiza la configuración de runtime del 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`

Conéctate a un sandbox mediante la interfaz de terminal.

```bash Bash icon="terminal" theme={"system"}
novitaclaw tui <SANDBOX_ID> --token <GATEWAY_TOKEN>
```

## `doctor`

Ejecuta diagnósticos y comprobaciones de reparación en una instancia de sandbox.

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

| Opción                       | Descripción                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `--api-key`                  | Clave de API de Novita                                                                 |
| `--deep`                     | Escanea los servicios del sistema en busca de instalaciones adicionales del gateway    |
| `--fix`                      | Aplica las reparaciones recomendadas (alias de `--repair`)                             |
| `--force`                    | Aplica reparaciones agresivas (sobrescribe la configuración de servicio personalizada) |
| `--generate-gateway-token`   | Genera y configura un token de gateway                                                 |
| `--no-workspace-suggestions` | Deshabilita las sugerencias del sistema de memoria del workspace                       |
| `--repair`                   | Aplica las reparaciones recomendadas sin preguntar                                     |
| `--yes`                      | Acepta los valores predeterminados sin preguntar                                       |

## `gateway update`

Actualiza OpenClaw a la versión más reciente dentro de un sandbox.

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

| Opción      | Descripción                                     |
| ----------- | ----------------------------------------------- |
| `--api-key` | Clave de API de Novita                          |
| `--restart` | Reinicia el gateway después de la actualización |

## `gateway restart`

Reinicia OpenClaw Gateway en un sandbox.

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

## `services setup`

Instala e inicia Web Terminal y File Manager en un sandbox existente. Usa esto para añadir servicios a sandboxes antiguos que se lanzaron antes de que estos servicios estuvieran incluidos.

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

## `pair list`

Lista las solicitudes de emparejamiento pendientes para un canal.

```bash Bash icon="terminal" theme={"system"}
novitaclaw pair list <SANDBOX_ID> --channel <CHANNEL_NAME> --api-key YOUR_API_KEY
```

## `pair approve`

Aprueba una solicitud de emparejamiento para un 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`

Configura Feishu (Lark) como canal de mensajería.

```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
```

| Opción                 | Descripción                                                 |
| ---------------------- | ----------------------------------------------------------- |
| `--app-id`             | ID de app de Feishu                                         |
| `--app-secret`         | Secreto de app de Feishu                                    |
| `--mode`               | `event` (predeterminado) o `webhook`                        |
| `--verification-token` | Token de verificación de webhook (solo modo webhook)        |
| `--encrypt-key`        | Clave de cifrado de webhook (solo modo webhook)             |
| `--webhook-host`       | Dirección de enlace del webhook (predeterminado: `0.0.0.0`) |
| `--webhook-port`       | Puerto de escucha del webhook (predeterminado: `3000`)      |
| `--webhook-path`       | Ruta de URL del webhook (predeterminado: `/feishu/events`)  |

## `pair telegram`

Configura Telegram como canal de mensajería.

```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>
```

| Opción             | Descripción                                                   |
| ------------------ | ------------------------------------------------------------- |
| `--bot-token`      | Token de bot de Telegram de BotFather                         |
| `--mode`           | `polling` (predeterminado) o `webhook`                        |
| `--webhook-url`    | URL pública de webhook (solo modo webhook)                    |
| `--webhook-secret` | Secreto del webhook (solo modo webhook)                       |
| `--webhook-host`   | Dirección de enlace del webhook (predeterminado: `0.0.0.0`)   |
| `--webhook-port`   | Puerto de escucha del webhook (predeterminado: `8787`)        |
| `--webhook-path`   | Ruta de URL del webhook (predeterminado: `/webhook/telegram`) |
| `--dm-policy`      | Política de DM (predeterminado: `pairing`)                    |

## `pair slack`

Configura Slack como canal de mensajería.

```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>
```

| Opción             | Descripción                                                 |
| ------------------ | ----------------------------------------------------------- |
| `--bot-token`      | Token de bot de Slack (`xoxb-...`)                          |
| `--app-token`      | Token de app de Slack (`xapp-...`, solo modo socket)        |
| `--mode`           | `socket` (predeterminado) o `http`                          |
| `--signing-secret` | Secreto de firma de Slack (solo modo HTTP)                  |
| `--webhook-host`   | Dirección de enlace del webhook (predeterminado: `0.0.0.0`) |
| `--webhook-port`   | Puerto de escucha del webhook (predeterminado: `8788`)      |
| `--webhook-path`   | Ruta de URL del webhook (predeterminado: `/webhook/slack`)  |

## `update`

Comprueba si hay actualizaciones de CLI y actualiza a la versión más reciente.

```bash Bash icon="terminal" theme={"system"}
novitaclaw update
```

## Uso programático

Usa la salida JSON para automatización:

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

Respuesta de ejemplo:

```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"
  }
}
```

## Variables de entorno

| Variable                 | Descripción                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| `NOVITA_API_KEY`         | Clave de API; elimina la necesidad de usar la bandera `--api-key` |
| `OPENCLAW_GATEWAY_TOKEN` | Token de gateway predefinido                                      |

## Solución de problemas

### Comando no encontrado

Prueba una de estas opciones:

```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
```

### Tiempo de espera de conexión

Aumenta el tiempo de espera de lanzamiento:

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

## Preguntas frecuentes

| Problema                               | Por qué ocurre                                              | Qué hacer                                                                                    |
| -------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| "Command not found" / "Not recognized" | Python PATH no se configuró durante la instalación          | Reinstala Python y marca "Add to PATH", o añade el directorio bin manualmente                |
| "Permission Denied"                    | Permisos insuficientes                                      | Windows: ejecuta Terminal como administrador. Mac/Linux: anteponlo con `sudo`                |
| "Invalid API Key"                      | La clave se copió incorrectamente                           | Comprueba si hay espacios adicionales alrededor de la cadena `sk_`, o genera una clave nueva |
| El sandbox no se detiene               | Requiere confirmación para evitar la eliminación accidental | Escribe `y` cuando se te solicite, o usa `--yes` para omitir la confirmación                 |
| Mac: comando `pip` no encontrado       | macOS usa `pip3` de forma predeterminada                    | Usa `pip3 install novitaclaw` en lugar de `pip`                                              |