Metadata-Version: 2.4
Name: NovitaClaw
Version: 1.1.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: novita-sandbox>=1.2.3b1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0

# 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

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

---

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

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

```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 |
| `--gateway-token` | Custom Gateway Token (recommended for easy recall) | Auto-generated random token |
| `--timeout` | Sandbox creation timeout in seconds | 60 |

**Example:**

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

### List Sandboxes

List all running sandboxes:

```bash
NovitaClaw list
```

### Check Sandbox Status

View a sandbox's runtime status and access URLs:

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

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

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

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

> Connecting messaging channels requires additional configuration (e.g., Bot Token). See the [OpenClaw Channels Documentation](https://docs.openclaw.ai/channels) for details.

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

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:

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

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

---

## 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 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](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
