NovitaClaw 1.2.1

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

NovitaClaw

Deploy your own AI assistant in the cloud with a single command. NovitaClaw creates an isolated cloud environment (sandbox) on Novita Agent Sandbox, automatically installs and configures OpenClaw — an open-source AI assistant framework that supports web chat, Telegram, Discord, WhatsApp, and more.

No server setup, no Docker knowledge needed — just an API key and one command.

Quick Start

Go from zero to a running AI assistant in 3 steps:

Step 1: Install NovitaClaw

pip install NovitaClaw

If pip is not found, see the Prerequisites section below to install Python first.

Step 2: Get and Configure Your API Key

1. Go to Novita API Key Management and sign up / log in
2. Create an API key on the page and copy the key starting with sk_
3. Set the environment variable in your terminal:

macOS / Linux:

export NOVITA_API_KEY=sk_your_api_key

Windows PowerShell:

$env:NOVITA_API_KEY = "sk_your_api_key"

Step 3: Launch and Open the Web UI

NovitaClaw launch

Wait about 1 minute. Once launched, the output will include a Web UI URL. Copy that URL and open it in your browser to start chatting with your AI assistant. The authentication token is already embedded in the URL — no extra login required.

When you're done, stop the sandbox to free up resources:

NovitaClaw stop <sandbox-id>

Replace <sandbox-id> with the Sandbox ID shown in the launch output.

---

Prerequisites

NovitaClaw requires Python 3.9 or later. If Python is not installed on your machine, follow the instructions below.

macOS

macOS often comes with Python pre-installed. Open the Terminal app and check:

python3 --version

If it shows a version number (e.g., Python 3.12.x), you're all set. If the command is not found:

Option A: Via Homebrew (recommended)

brew install python

Option B: Download from the official site

Go to https://www.python.org/downloads/ and download the installer.

Windows

1. Go to the Python website and download the latest installer
2. Important: Check the "Add Python to PATH" box at the bottom of the installer
3. After installation, open PowerShell and verify:

python --version
pip --version

Linux (Ubuntu / Debian)

sudo apt update && sudo apt install python3 python3-pip -y

Verify Installation

After installing Python, confirm that pip is available:

pip --version
# or
pip3 --version

If pip is not available but pip3 works, replace pip with pip3 in all subsequent commands.

---

Configuring the API Key

All NovitaClaw operations require a Novita API key. This key is used for:

• Creating and managing cloud sandbox instances
• Powering the AI assistant's LLM inference (driving conversations)

Getting an API Key

1. Open Novita API Key Management
2. Sign up or log in to your Novita account
3. Click "Create API Key"
4. Copy the generated key (starts with sk_) and keep it safe

Configuration Methods

Choose whichever method suits you best:

Method 1: Pass directly (one-time use)

NovitaClaw launch --api-key sk_your_api_key

Method 2: Environment variable (current terminal session)

# macOS / Linux
export NOVITA_API_KEY=sk_your_api_key

# Windows PowerShell
$env:NOVITA_API_KEY = "sk_your_api_key"

Method 3: Shell profile (persistent, recommended)

# macOS (zsh)
echo 'export NOVITA_API_KEY=sk_your_api_key' >> ~/.zshrc
source ~/.zshrc

# Linux (bash)
echo 'export NOVITA_API_KEY=sk_your_api_key' >> ~/.bashrc
source ~/.bashrc

On Windows, add NOVITA_API_KEY through System Properties → Advanced → Environment Variables.

Method 4: Inline with a single command

NOVITA_API_KEY=sk_your_api_key NovitaClaw launch

---

Key Concepts

Understanding these concepts will help you navigate NovitaClaw:

Concept	Description
Sandbox	An isolated cloud environment — think of it as a dedicated virtual machine. Your AI assistant runs inside it.
Gateway	A service running inside the sandbox that receives and routes messages. The Web UI and messaging channels communicate with the AI assistant through it.
Web UI	A browser-based chat interface. Open the URL and start talking to your AI assistant — no software installation needed.
Gateway Token	An authentication key that protects your sandbox from unauthorized access.
Sandbox ID	A unique identifier for your sandbox, used for management commands (check status, stop, etc.). Example format: iz64antbdg1l8ww7fp2zg-4551786a.

Typical workflow:

Install NovitaClaw → Configure API Key → Launch Sandbox → Open Web UI → Stop Sandbox When Done

---

Command Reference

Launch a Sandbox

NovitaClaw launch

On success, the output includes the Sandbox ID, Web UI URL, Gateway Token, and more. Copy the Web UI URL and open it in your browser.

Options:

Option	Description	Default
--api-key	Novita API Key	Reads from NOVITA_API_KEY env var
--gateway-token	Custom Gateway Token (recommended for easy recall)	Auto-generated random token
--timeout	Sandbox creation timeout in seconds	60

Example:

# Use a custom Gateway Token for easy reference
NovitaClaw launch --gateway-token my-secret-token-123

List Sandboxes

List all running sandboxes:

NovitaClaw list

Check Sandbox Status

View a sandbox's runtime status and access URLs:

NovitaClaw status <sandbox-id>

Stop a Sandbox

Terminate and release a sandbox. Always stop sandboxes when no longer in use to avoid unnecessary resource consumption:

NovitaClaw stop <sandbox-id>

Manage the Gateway

Update the OpenClaw configuration and hot-reload the gateway:

NovitaClaw gateway update <sandbox-id>

Restart the gateway process (needed when hot reload is insufficient):

NovitaClaw gateway restart <sandbox-id>

Diagnostics & Repair

Run diagnostics inside the sandbox to check configuration integrity, permissions, gateway health, and more:

NovitaClaw doctor <sandbox-id>

Auto-fix discovered issues:

NovitaClaw doctor <sandbox-id> --fix             # Apply recommended fixes
NovitaClaw doctor <sandbox-id> --fix --force      # Aggressive fixes (overwrites custom config)
NovitaClaw doctor <sandbox-id> --deep             # Deep scan of system services

Channel Pairing (Advanced)

NovitaClaw supports connecting your AI assistant to Telegram, Discord, WhatsApp, and other messaging platforms. When a channel uses device pairing mode, new users who DM the bot receive a one-time pairing code. Use these commands to manage pairing:

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

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

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

Pairing codes expire after 1 hour.

Connecting messaging channels requires additional configuration (e.g., Bot Token). See the OpenClaw Channels Documentation for details.

TUI Connection (Optional)

If you prefer working in the terminal, connect to a sandbox via TUI (Terminal User Interface):

NovitaClaw tui <sandbox-id> --token <gateway-token>

Requirements: Node.js and the OpenClaw CLI must be installed locally.

1. Install Node.js: download the LTS version from nodejs.org
2. Install OpenClaw CLI: npm install -g openclaw
3. On first connection, device pairing is triggered automatically — the sandbox auto-approval service completes pairing within ~3 seconds.

---

AI Agent Integration

If you are an AI agent or need to call NovitaClaw from scripts, all commands support the --json / -j global flag for structured JSON output:

NovitaClaw --json launch
NovitaClaw --json list
NovitaClaw --json status <id>
NovitaClaw --json stop <id>
NovitaClaw --json gateway update <id>
NovitaClaw --json gateway restart <id>
NovitaClaw --json pair list <id> --channel telegram
NovitaClaw --json pair approve <id> --channel telegram --code X
NovitaClaw --json doctor <id>

JSON output format:

// Success (exit code 0)
{"status": "ok", "sandbox_id": "...", ...}

// Failure (exit code > 0)
{"status": "error", "error_code": "SANDBOX_CREATE_FAILED", "message": "..."}

If you are an AI agent, always use the --json flag for stable, machine-parseable output.

---

Security Notes

The Gateway Token protects your AI assistant from unauthorized access:

• Keep your token safe — you can view it anytime with NovitaClaw status <id>
• Stop unused sandboxes promptly — to avoid unnecessary resource consumption and security risks
• Do not share the Web UI URL — the URL contains the token; anyone with the link can access your AI assistant

---

Troubleshooting

pip or pip3 command not found

Python is not installed or not added to your system PATH. See the Prerequisites section above. Windows users: make sure "Add Python to PATH" was checked during installation.

NovitaClaw command not found after installation

The executable installed by pip may not be on your system PATH. Try these solutions:

# Option A: Use pipx (handles PATH automatically)
pip install pipx
pipx install NovitaClaw
NovitaClaw --help

# Option B: Manually add the pip install directory to PATH
# macOS / Linux: usually ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

API key invalid or authentication failed

• Confirm the key starts with sk_
• Confirm the key was copied correctly with no extra spaces
• Visit Novita API Key Management to check the key status

Launch timeout (Gateway failed to start)

The sandbox was created but the gateway didn't start within the expected time. Possible causes:

• Network fluctuation — try again shortly
• Increase the timeout: NovitaClaw launch --timeout 120
• Diagnose the issue: NovitaClaw doctor <sandbox-id>

Network connection issues

NovitaClaw requires internet access to connect to Novita services. If you experience connection problems:

• Check that your network is working
• If behind a corporate network or proxy, ensure proxy settings are correct
• Retry the command — intermittent network issues often resolve on retry

---

Resources

• OpenClaw Documentation — Full documentation for the AI assistant framework
• OpenClaw Channel Configuration — Connect Telegram, Discord, and other platforms
• Novita Agent Sandbox — Cloud sandbox service documentation
• Novita API Key Guide — API key management page