# Novita OpenClaw CLI

One-click launch of [OpenClaw](https://docs.openclaw.ai/) sandbox environments powered by [Novita Agent Sandbox](https://novita.ai/docs/guides/sandbox-sdk-and-cli).

## Installation

```bash
pip install novita-openclaw-cli
```

## Configuration

### 1. Get a Novita API Key

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

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

```bash
novita-openclaw-cli --json launch    # {"status":"ok","sandbox_id":"...","webui":"...","gateway_ws":"...","gateway_token":"..."}
novita-openclaw-cli --json list      # {"status":"ok","sandboxes":[...]}
novita-openclaw-cli --json status <id>  # {"status":"ok","sandbox_id":"...","state":"...","webui":"...","gateway_ws":"...","gateway_token":"..."}
novita-openclaw-cli --json stop <id>    # {"status":"ok","sandbox_id":"...","message":"..."}
```

### Launch a Sandbox

```bash
novita-openclaw-cli launch
```

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

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

```bash
novita-openclaw-cli list
```

### Check Sandbox Status

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

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

### Stop a Sandbox

```bash
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](https://docs.openclaw.ai/install)
- [Novita Agent Sandbox Documentation](https://novita.ai/docs/guides/sandbox-sdk-and-cli)
- [Novita API Key Guide](https://novita.ai/docs/guides/quickstart#2-manage-api-key)
