# Command Reference - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/novitaclaw-commands

# Command Reference

Complete reference for all NovitaClaw CLI commands.

##

[​](#launch)

`launch`

Create a new sandbox instance.

Bash

```
novitaclaw launch [OPTIONS]
```

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

List active sandbox instances.

Bash

```
novitaclaw list --api-key YOUR_API_KEY
```

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

##

[​](#status)

`status`

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

Bash

```
novitaclaw status --api-key YOUR_API_KEY
```

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

##

[​](#stop)

`stop`

Terminate a sandbox instance.

Bash

```
novitaclaw stop --api-key YOUR_API_KEY
```

OptionDescription`--api-key`Novita API key`--yes`, `-y`Skip confirmation prompt

##

[​](#pause)

`pause`

Pause a sandbox instance. Zero billing while paused.

Bash

```
novitaclaw pause --api-key YOUR_API_KEY
```

##

[​](#resume)

`resume`

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

Bash

```
novitaclaw resume --api-key YOUR_API_KEY
```

##

[​](#config-set)

`config set`

Update sandbox runtime configuration.

Bash

```
# Update idle timeout (60–86400 seconds)
novitaclaw config set idle-timeout 600

# Update sandbox lifetime timeout (300–2592000 seconds)
novitaclaw config set timeout 3600
```

##

[​](#tui)

`tui`

Connect to a sandbox via terminal UI.

Bash

```
novitaclaw tui --token
```

##

[​](#doctor)

`doctor`

Run diagnostics and repair checks on a sandbox instance.

Bash

```
novitaclaw doctor --api-key YOUR_API_KEY
```

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

`gateway update`

Update OpenClaw to the latest version inside a sandbox.

Bash

```
novitaclaw gateway update --api-key YOUR_API_KEY
```

OptionDescription`--api-key`Novita API key`--restart`Restart gateway after update

##

[​](#gateway-restart)

`gateway restart`

Restart the OpenClaw Gateway in a sandbox.

Bash

```
novitaclaw gateway restart --api-key YOUR_API_KEY
```

##

[​](#services-setup)

`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

```
novitaclaw services setup --api-key YOUR_API_KEY
```

##

[​](#pair-list)

`pair list`

List pending pairing requests for a channel.

Bash

```
novitaclaw pair list --channel --api-key YOUR_API_KEY
```

##

[​](#pair-approve)

`pair approve`

Approve a pairing request for a channel.

Bash

```
novitaclaw pair approve --channel --code --api-key YOUR_API_KEY
```

##

[​](#pair-feishu)

`pair feishu`

Configure Feishu (Lark) as a messaging channel.

Bash

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

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

`pair telegram`

Configure Telegram as a messaging channel.

Bash

```
# Polling mode (default)
novitaclaw pair telegram \
--bot-token

# Webhook mode
novitaclaw pair telegram \
--bot-token \
--mode webhook \
--webhook-url https://example.com/webhook/telegram \
--webhook-secret
```

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

`pair slack`

Configure Slack as a messaging channel.

Bash

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

# HTTP mode
novitaclaw pair slack \
--bot-token xoxb-... \
--mode http \
--signing-secret
```

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

`update`

Check for CLI updates and upgrade to the latest version.

Bash

```
novitaclaw update
```

##

[​](#programmatic-usage)

Programmatic Usage

Use JSON output for automation:

Bash

```
novitaclaw -j launch --api-key YOUR_API_KEY
```

Example response:

```
{
"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)

Environment Variables

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

##

[​](#troubleshooting)

Troubleshooting

###

[​](#command-not-found)

Command not found

Try one of these:

Bash

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

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

###

[​](#connection-timeout)

Connection timeout

Increase launch timeout:

Bash

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

##

[​](#frequently-asked-questions)

Frequently Asked Questions

ProblemWhy it happensWhat to do”Command not found” / “Not recognized”Python PATH not configured during installReinstall Python and check “Add to PATH”, or add the bin directory manually”Permission Denied”Insufficient permissionsWindows: Run Terminal as Administrator. Mac/Linux: prefix with `sudo`”Invalid API Key”Key copied incorrectlyCheck for extra spaces around the `sk_` string, or generate a new keySandbox won’t stopRequires confirmation to prevent accidental deletionType `y` when prompted, or use `--yes` to skip confirmationMac: `pip` command not foundmacOS uses `pip3` by defaultUse `pip3 install novitaclaw` instead of `pip`

Last modified on April 8, 2026