Command Reference - Documentation

Complete reference for all NovitaClaw CLI commands.

`launch`

Create a new sandbox instance.

Bash

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

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

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

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

novitaclaw pause <SANDBOX_ID> --api-key YOUR_API_KEY

`resume`

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

Bash

novitaclaw resume <SANDBOX_ID> --api-key YOUR_API_KEY

`config set`

Update sandbox runtime configuration.

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`

Connect to a sandbox via terminal UI.

Bash

novitaclaw tui <SANDBOX_ID> --token <GATEWAY_TOKEN>

`doctor`

Run diagnostics and repair checks on a sandbox instance.

Bash

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

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

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

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

`pair list`

List pending pairing requests for a channel.

Bash

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

`pair approve`

Approve a pairing request for a channel.

Bash

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

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

# 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

# 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

novitaclaw update

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

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

# 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

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`

​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

​Programmatic Usage

​Environment Variables

​Troubleshooting

​Command not found

​Connection timeout

​Frequently Asked Questions

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

Programmatic Usage

Environment Variables

Troubleshooting

Command not found

Connection timeout

Frequently Asked Questions