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

# Command Reference

Complete reference for all NovitaClaw CLI commands.

## `launch`

Create a new sandbox instance.

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

| Option            | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `--api-key`       | Novita API key                                                               |
| `--gateway-token` | Custom gateway token (optional, auto-generated by default)                   |
| `--timeout`       | Creation timeout in seconds (default: `60`)                                  |
| `--type`          | Sandbox type: `persistent` (default) or `on-demand`                          |
| `--idle-timeout`  | Idle timeout in seconds for on-demand mode (default: `300`, range: 60–86400) |

## `list`

List active sandbox instances.

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

| Option          | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| `--api-key`     | Novita API key                                              |
| `--quiet`, `-q` | Only print sandbox IDs, one per line (useful for scripting) |

## `status`

Check a sandbox instance status. Displays webhook URLs for all configured channels.

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

| Option      | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `--api-key` | Novita API key                                             |
| `--json`    | Output in JSON format (useful for extracting webhook URLs) |

## `stop`

Terminate a sandbox instance.

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

| Option        | Description              |
| ------------- | ------------------------ |
| `--api-key`   | Novita API key           |
| `--yes`, `-y` | Skip confirmation prompt |

## `pause`

Pause a sandbox instance. Zero billing while paused.

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

## `resume`

Resume a paused sandbox instance (\~1s to restore).

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

## `config set`

Update sandbox runtime configuration.

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

Connect to a sandbox via terminal UI.

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

## `doctor`

Run diagnostics and repair checks on a sandbox instance.

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

| Option                       | Description                                                 |
| ---------------------------- | ----------------------------------------------------------- |
| `--api-key`                  | Novita API key                                              |
| `--deep`                     | Scan system services for extra gateway installs             |
| `--fix`                      | Apply recommended repairs (alias for `--repair`)            |
| `--force`                    | Apply aggressive repairs (overwrites custom service config) |
| `--generate-gateway-token`   | Generate and configure a gateway token                      |
| `--no-workspace-suggestions` | Disable workspace memory system suggestions                 |
| `--repair`                   | Apply recommended repairs without prompting                 |
| `--yes`                      | Accept defaults without prompting                           |

## `gateway update`

Update OpenClaw to the latest version inside a sandbox.

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

| Option      | Description                  |
| ----------- | ---------------------------- |
| `--api-key` | Novita API key               |
| `--restart` | Restart gateway after update |

## `gateway restart`

Restart the OpenClaw Gateway in a sandbox.

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

## `services setup`

Install and start Web Terminal and File Manager on an existing sandbox. Use this to add services to older sandboxes that were launched before these services were included.

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

## `pair list`

List pending pairing requests for a channel.

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

## `pair approve`

Approve a pairing request for a channel.

```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 Feishu (Lark) as a messaging channel.

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

| Option                 | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `--app-id`             | Feishu app ID                                  |
| `--app-secret`         | Feishu app secret                              |
| `--mode`               | `event` (default) or `webhook`                 |
| `--verification-token` | Webhook verification token (webhook mode only) |
| `--encrypt-key`        | Webhook encrypt key (webhook mode only)        |
| `--webhook-host`       | Webhook bind address (default: `0.0.0.0`)      |
| `--webhook-port`       | Webhook listen port (default: `3000`)          |
| `--webhook-path`       | Webhook URL path (default: `/feishu/events`)   |

## `pair telegram`

Configure Telegram as a messaging channel.

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

| Option             | Description                                     |
| ------------------ | ----------------------------------------------- |
| `--bot-token`      | Telegram bot token from BotFather               |
| `--mode`           | `polling` (default) or `webhook`                |
| `--webhook-url`    | Public webhook URL (webhook mode only)          |
| `--webhook-secret` | Webhook secret (webhook mode only)              |
| `--webhook-host`   | Webhook bind address (default: `0.0.0.0`)       |
| `--webhook-port`   | Webhook listen port (default: `8787`)           |
| `--webhook-path`   | Webhook URL path (default: `/webhook/telegram`) |
| `--dm-policy`      | DM policy (default: `pairing`)                  |

## `pair slack`

Configure Slack as a messaging channel.

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

| Option             | Description                                    |
| ------------------ | ---------------------------------------------- |
| `--bot-token`      | Slack bot token (`xoxb-...`)                   |
| `--app-token`      | Slack app token (`xapp-...`, socket mode only) |
| `--mode`           | `socket` (default) or `http`                   |
| `--signing-secret` | Slack signing secret (HTTP mode only)          |
| `--webhook-host`   | Webhook bind address (default: `0.0.0.0`)      |
| `--webhook-port`   | Webhook listen port (default: `8788`)          |
| `--webhook-path`   | Webhook URL path (default: `/webhook/slack`)   |

## `update`

Check for CLI updates and upgrade to the latest version.

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

## Programmatic Usage

Use JSON output for automation:

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

Example response:

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

## Environment Variables

| Variable                 | Description                                       |
| ------------------------ | ------------------------------------------------- |
| `NOVITA_API_KEY`         | API key, eliminates the need for `--api-key` flag |
| `OPENCLAW_GATEWAY_TOKEN` | Preset gateway token                              |

## Troubleshooting

### Command not found

Try one of these:

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

### Connection timeout

Increase launch timeout:

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

## Frequently Asked Questions

| Problem                                | Why it happens                                       | What to do                                                                  |
| -------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
| "Command not found" / "Not recognized" | Python PATH not configured during install            | Reinstall Python and check "Add to PATH", or add the bin directory manually |
| "Permission Denied"                    | Insufficient permissions                             | Windows: Run Terminal as Administrator. Mac/Linux: prefix with `sudo`       |
| "Invalid API Key"                      | Key copied incorrectly                               | Check for extra spaces around the `sk_` string, or generate a new key       |
| Sandbox won't stop                     | Requires confirmation to prevent accidental deletion | Type `y` when prompted, or use `--yes` to skip confirmation                 |
| Mac: `pip` command not found           | macOS uses `pip3` by default                         | Use `pip3 install novitaclaw` instead of `pip`                              |