Novita OpenClaw CLI

One-click launch of OpenClaw sandbox environments powered by Novita Agent Sandbox.

Installation

pip install novita-openclaw-cli

Configuration

1. Get a Novita API Key

Go to Novita API Key Management to obtain your API key. This key is used for:

• Creating and managing Novita sandbox instances
• Serving as the LLM inference API key for OpenClaw

2. Configure the API Key

Use any of the following methods:

# Option 1: Pass directly
novita-openclaw-cli launch --api-key sk_your_api_key

# Option 2: Set for a single command
NOVITA_API_KEY=sk_your_api_key novita-openclaw-cli launch

# Option 3: Export for the current session
export NOVITA_API_KEY=sk_your_api_key

# Option 4: Add to shell profile (persistent)
echo 'export NOVITA_API_KEY=sk_your_api_key' >> ~/.zshrc

Usage

All commands support the --json / -j global flag to output structured JSON (useful for AI agents or scripting). If you are an AI Agent, always use the --json flag to get stable, machine-parseable output:

novita-openclaw-cli --json launch                                      # launch sandbox
novita-openclaw-cli --json list                                        # list sandboxes
novita-openclaw-cli --json status <id>                                 # sandbox status & URLs
novita-openclaw-cli --json stop <id>                                   # stop sandbox
novita-openclaw-cli --json pair list <id> --channel telegram           # pending pairing requests
novita-openclaw-cli --json pair approve <id> --channel telegram --code X  # approve pairing
novita-openclaw-cli --json doctor <id>                                 # run diagnostics

Launch a Sandbox

novita-openclaw-cli launch

A random Gateway Token is generated automatically. You can also specify a custom token:

novita-openclaw-cli launch --gateway-token <your-token>

After launch you will see:

• Sandbox ID — used for subsequent management commands
• Web UI URL — open in browser to use OpenClaw (token is appended to the URL for auto-authentication)
• Gateway WebSocket URL — for TUI or API connections
• Gateway Token — authentication token for connections

Full options:

Option	Description	Default
--api-key	Novita API Key	Reads from NOVITA_API_KEY env var
--gateway-token	Gateway auth token for access control. Recommend setting a secure custom token	Auto-generated random token
--timeout	Sandbox creation timeout (seconds)	60

List Sandboxes

novita-openclaw-cli list

Check Sandbox Status

novita-openclaw-cli status <sandbox-id>

Shows Sandbox ID, status, Web UI URL, Gateway WS URL, and Gateway Token. Also provides a ready-to-use TUI connection command.

Connect via TUI

novita-openclaw-cli tui <sandbox-id> --token <gateway-token>

Requires the OpenClaw CLI to be installed locally: npm install -g openclaw

The first connection triggers device pairing. The sandbox auto-approval daemon will complete pairing within ~3 seconds — please wait briefly.

Manage Channel Pairing

When a messaging channel (Telegram, Discord, etc.) uses dmPolicy: "pairing" (the default), new users who DM the bot receive a one-time pairing code. Use these commands to list and approve pairing requests:

# List pending pairing requests for a channel
novita-openclaw-cli pair list <sandbox-id> --channel telegram

# Approve a pairing request with the code
novita-openclaw-cli pair approve <sandbox-id> --channel telegram --code <CODE>

Supported channels: telegram, discord, whatsapp, signal, slack, feishu.

Pairing codes expire after 1 hour. To see pending requests, run pair list first.

Run OpenClaw Doctor

novita-openclaw-cli doctor <sandbox-id>

Diagnoses configuration issues, file permissions, gateway health, and plugin status inside the sandbox.

Stop a Sandbox

novita-openclaw-cli stop <sandbox-id>

Security Notes

The Gateway Token protects your OpenClaw instance from unauthorized access. When a sandbox is exposed on a public address:

• Keep your token safe — the token is shown only once at launch, save it immediately
• Stop unused sandboxes promptly — to avoid unnecessary resource usage and security exposure

Resources

• OpenClaw Documentation
• Novita Agent Sandbox Documentation
• Novita API Key Guide