Metadata-Version: 2.4
Name: NovitaClaw
Version: 1.6.0
Summary: One-click launch of OpenClaw sandbox environment powered by Novita Agent Sandbox
Author-email: Novita AI <support@novita.ai>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.25
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn[standard]>=0.34; extra == "server"
Requires-Dist: novita-sandbox>=1.2.3b1; extra == "server"
Requires-Dist: pyyaml>=6.0; extra == "server"
Requires-Dist: python-json-logger>=3.0; extra == "server"
Requires-Dist: mcp>=1.3; python_version >= "3.10" and extra == "server"
Requires-Dist: sqlalchemy>=2.0; extra == "server"
Requires-Dist: pymysql>=1.1; extra == "server"
Requires-Dist: cryptography>=42.0; extra == "server"
Requires-Dist: croniter>=2.0; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: httpx>=0.25; extra == "dev"

# NovitaClaw

Deploy your own AI assistant in the cloud with a single command. NovitaClaw creates an isolated cloud environment (sandbox) on [Novita Agent Sandbox](https://novita.ai/docs/guides/sandbox-sdk-and-cli), automatically installs and configures [OpenClaw](https://docs.openclaw.ai/) — 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):**

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

**Windows PowerShell:**

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

**Or via pip:**

```bash
pip install NovitaClaw
```

If `pip` is not found, see the [Prerequisites](#prerequisites) section below to install Python first.

### Step 2: Get and Configure Your API Key

1. Go to [Novita API Key Management](https://novita.ai/docs/guides/quickstart#2-manage-api-key) 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:**

```bash
export NOVITA_API_KEY=sk_your_api_key
```

**Windows PowerShell:**

```powershell
$env:NOVITA_API_KEY = "sk_your_api_key"
```

### Step 3: Launch and Open the Web UI

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

```bash
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](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:

```bash
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)**

```bash
brew install python
```

**Option B: Download from the official site**

Go to [https://www.python.org/downloads/](https://www.python.org/downloads/) and download the installer.

### Windows

1. Go to the [Python website](https://www.python.org/downloads/) 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:

```powershell
python --version
pip --version
```

### Linux (Ubuntu / Debian)

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

### Verify Installation

After installing Python, confirm that `pip` is available:

```bash
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](https://novita.ai/docs/guides/quickstart#2-manage-api-key)
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)**

```bash
novitaclaw launch --api-key sk_your_api_key
```

**Method 2: Environment variable (current terminal session)**

```bash
# 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)**

```bash
# 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**

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

```bash
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:**

```bash
# 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:

```bash
novitaclaw list
```

### Check Sandbox Status

View a sandbox's runtime status and access URLs:

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

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

```bash
novitaclaw stop <sandbox-id>
```

### Node Management

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

```bash
# 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:

```bash
novitaclaw devices list <gateway-sandbox-id>
novitaclaw devices approve <gateway-sandbox-id>
```

### Manage the Gateway

Update the OpenClaw configuration and hot-reload the gateway:

```bash
novitaclaw gateway update <sandbox-id>
```

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

```bash
novitaclaw gateway restart <sandbox-id>
```

### Diagnostics & Repair

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

```bash
novitaclaw doctor <sandbox-id>
```

Auto-fix discovered issues:

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

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

```bash
# 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:

```bash
# 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](https://docs.openclaw.ai/channels) for details.

### Self-Update

Check for updates and upgrade to the latest version:

```bash
novitaclaw update
```

### TUI Connection (Optional)

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

```bash
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](https://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:

```bash
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:**

```jsonc
// 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](docs/server-dev.md) for details on the API Server and MCP integration.

---

## Uninstall

**macOS / Linux (if installed via install script):**

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

**Windows PowerShell (if installed via install script):**

```powershell
powershell -ExecutionPolicy ByPass -File install.ps1 -Uninstall
```

**If installed via pip:**

```bash
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](#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:

```bash
# 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](https://novita.ai/docs/guides/quickstart#2-manage-api-key) 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](https://docs.openclaw.ai/) — Full documentation for the AI assistant framework
- [OpenClaw Channel Configuration](https://docs.openclaw.ai/channels) — Connect Telegram, Discord, and other platforms
- [Novita Agent Sandbox](https://novita.ai/docs/guides/sandbox-sdk-and-cli) — Cloud sandbox service documentation
- [Novita API Key Guide](https://novita.ai/docs/guides/quickstart#2-manage-api-key) — API key management page
