Command Reference

Complete reference for all NovitaClaw CLI commands.

`launch`

Create a new sandbox instance.

CLI

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.

CLI

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.

CLI

novitaclaw status --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.

CLI

novitaclaw stop --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.

CLI

novitaclaw pause --api-key YOUR_API_KEY

`resume`

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

CLI

novitaclaw resume --api-key YOUR_API_KEY

`config set`

Update sandbox runtime configuration.

CLI

# idle-timeout range: 60–86400 seconds
novitaclaw config set idle-timeout 600
# timeout in seconds
novitaclaw config set timeout 3600

`tui`

Connect to a sandbox via terminal UI.

CLI

novitaclaw tui --token YOUR_GATEWAY_TOKEN

`doctor`

Run diagnostics and repair checks on a sandbox instance.

CLI

novitaclaw doctor --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.

CLI

novitaclaw gateway update --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.

CLI

novitaclaw gateway restart --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.

CLI

novitaclaw services setup --api-key YOUR_API_KEY

`pair list`

List pending pairing requests for a channel.

CLI

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

`pair approve`

Approve a pairing request for a channel.

CLI

novitaclaw pair approve --channel CHANNEL --code CODE --api-key YOUR_API_KEY

`pair feishu`

Configure Feishu (Lark) as a messaging channel.

CLI

novitaclaw pair feishu \
  --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.

CLI

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

# Webhook mode
novitaclaw pair telegram \
  --bot-token YOUR_BOT_TOKEN \
  --mode webhook \
  --webhook-url https://example.com/webhook/telegram \
  --webhook-secret YOUR_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.

CLI

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

# HTTP mode
novitaclaw pair slack \
  --bot-token xoxb-... \
  --mode http \
  --signing-secret YOUR_SIGNING_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.

CLI

novitaclaw update

Programmatic Usage

Use JSON output for automation:

CLI

novitaclaw -j launch --api-key YOUR_API_KEY

Example response:

JSON

{
  "success": true,
  "data": {
    "sandbox_id": "...",
    "webui": "https://...",
    "gateway_ws": "wss://...",
    "gateway_token": "...",
    "terminal_url": "https://...",
    "filemanager_url": "https://...",
    "services_username": "admin",
    "services_password": "..."
  }
}

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:

CLI

# Linux
~/.local/bin/novitaclaw launch

# macOS (typical path)
~/Library/Python/3.x/bin/novitaclaw launch

Connection timeout

Increase launch timeout:

CLI

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`

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

`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

`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