NovitaClaw 1.5.0

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

macOS / Linux (recommended):

curl -fsSL https://novitaclaw.novita.ai/install.sh | bash

Windows PowerShell:

irm https://novitaclaw.novita.ai/install.ps1 | iex

Or via pip:

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.

---

Architecture

NovitaClaw uses a two-layer architecture:

CLI (novitaclaw)  ──HTTP──▶  API Server (FastAPI)  ──SDK──▶  Novita Agent Sandbox

• CLI (openclaw_sandbox_cli/) — Click-based command-line tool. Sends HTTP requests to the API Server.
• API Server (openclaw_sandbox_server/) — FastAPI REST API + MCP (Model Context Protocol) endpoint. Manages sandbox lifecycle via the novita-sandbox SDK.

The API Server is hosted at https://novitaclaw.novita.ai/api by default. For local development, you can run your own server and point the CLI at it (see docs/server-dev.md).

---

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

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.
Node	A lightweight sandbox that connects to an existing gateway. Use node mode to scale processing across multiple sandboxes.
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.).

Typical workflow:

Install NovitaClaw → Configure API Key → Launch Sandbox → Open Web UI → Pause/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
--timeout	Sandbox creation timeout in seconds	180
--mode	Launch mode: gateway (full OpenClaw) or node (bare node)	gateway
--display-name	Node display name shown in gateway UI (node mode only)	—

Example:

# Launch a full gateway sandbox
novitaclaw launch

# Launch a node sandbox
novitaclaw launch --mode node --display-name "worker-1"

List Sandboxes

List all active sandboxes:

novitaclaw list

Check Sandbox Status

View a sandbox's runtime status and access URLs:

novitaclaw status <sandbox-id>

Pause / Resume a Sandbox

Pause a running sandbox to save costs while preserving all state (filesystem, memory, running processes). No runtime charges while paused.

novitaclaw pause <sandbox-id>
novitaclaw resume <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>

Node Management

Node mode allows you to launch lightweight sandboxes that connect to an existing gateway, enabling distributed processing.

# Launch a node sandbox
novitaclaw launch --mode node --display-name "worker-1"

# Connect the node to a gateway
novitaclaw node connect <node-sandbox-id> --gateway wss://... --gateway-token <token>

# Disconnect a node from its gateway
novitaclaw node disconnect <node-sandbox-id>

Device Management

List and approve node devices on a gateway:

novitaclaw devices list <gateway-sandbox-id>
novitaclaw devices approve <gateway-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

Web Terminal & File Manager

Set up Web Terminal and File Manager services on an existing sandbox:

novitaclaw services setup <sandbox-id>

Channel Pairing

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:

# 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.

Channel Configuration (Telegram, Slack, Feishu)

For channels that support webhook mode, NovitaClaw provides dedicated config commands:

# Configure Telegram (polling mode — default)
novitaclaw pair telegram <sandbox-id> --bot-token <BOT_TOKEN>

# Configure Telegram (webhook mode)
novitaclaw pair telegram <sandbox-id> --bot-token <BOT_TOKEN> \
  --mode webhook --webhook-url <HTTPS_URL> --webhook-secret <SECRET>

# Configure Slack (socket mode — default)
novitaclaw pair slack <sandbox-id> --bot-token <BOT_TOKEN> --app-token <APP_TOKEN>

# Configure Slack (http/Events API mode)
novitaclaw pair slack <sandbox-id> --bot-token <BOT_TOKEN> \
  --mode http --signing-secret <SIGNING_SECRET>

# Configure Feishu (event mode — default)
novitaclaw pair feishu <sandbox-id> --app-id <APP_ID> --app-secret <APP_SECRET>

Retrieve webhook URLs via novitaclaw status <sandbox-id> --json.

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

Self-Update

Check for updates and upgrade to the latest version:

novitaclaw update

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

CLI JSON Mode

All commands support the --json / -j global flag for structured JSON output:

novitaclaw --json launch
novitaclaw --json list
novitaclaw --json status <id>
novitaclaw --json pause <id>
novitaclaw --json resume <id>
novitaclaw --json stop <id>
novitaclaw --json node connect <id> --gateway wss://...
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.

MCP (Model Context Protocol)

The API Server exposes an MCP endpoint at /mcp using Streamable HTTP transport. AI agents and LLM tool-use frameworks can connect to it directly for sandbox management without going through the CLI.

All MCP requests require an Authorization: Bearer <api_key> header.

See docs/server-dev.md for details on the API Server and MCP integration.

---

Uninstall

macOS / Linux (if installed via install script):

curl -fsSL https://novitaclaw.novita.ai/install.sh | bash -s -- --uninstall

Windows PowerShell (if installed via install script):

powershell -ExecutionPolicy ByPass -File install.ps1 -Uninstall

If installed via pip:

pip uninstall NovitaClaw

---

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 300
• 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