Metadata-Version: 2.4
Name: novita-openclaw-cli
Version: 0.6.1
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.1.1b3
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0

# 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                                      # launch sandbox
novita-openclaw-cli --json list                                        # list sandboxes
novita-openclaw-cli --json status <id>                                 # sandbox status & URLs
novita-openclaw-cli --json stop <id>                                   # stop sandbox
novita-openclaw-cli --json pair list <id> --channel telegram           # pending pairing requests
novita-openclaw-cli --json pair approve <id> --channel telegram --code X  # approve pairing
novita-openclaw-cli --json doctor <id>                                 # run diagnostics
```

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

### Manage Channel Pairing

When a messaging channel (Telegram, Discord, etc.) uses `dmPolicy: "pairing"` (the default), new users who DM the bot receive a one-time pairing code. Use these commands to list and approve pairing requests:

```bash
# List pending pairing requests for a channel
novita-openclaw-cli pair list <sandbox-id> --channel telegram

# Approve a pairing request with the code
novita-openclaw-cli pair approve <sandbox-id> --channel telegram --code <CODE>
```

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

Pairing codes expire after 1 hour. To see pending requests, run `pair list` first.

### Run OpenClaw Doctor

```bash
novita-openclaw-cli doctor <sandbox-id>
```

Diagnoses configuration issues, file permissions, gateway health, and plugin status inside the sandbox.

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