npm package: @otonix/openclaw-plugin
Description: OpenClaw plugin for Otonix — give your AI agents autonomous infrastructure management via chat commands.
Author: Otonix
Latest version: 1.3.0

# @otonix/openclaw-plugin

OpenClaw plugin for the [Otonix](https://otonix.tech) sovereign compute platform.

Give your OpenClaw AI agents autonomous infrastructure management — register, heartbeat, manage VPS, domains, and payments through chat commands.

## Install

```bash
npm install @otonix/openclaw-plugin
```

## Quick Start

```typescript
import { OtonixPlugin, getSystemPromptAddition } from '@otonix/openclaw-plugin'

const plugin = new OtonixPlugin({
  apiKey: 'otonix_your_api_key',
  endpoint: 'https://app.otonix.tech',
  autoHeartbeat: true,
  heartbeatInterval: 60,
})

// Get tool schemas for your LLM (OpenAI function calling format)
const tools = plugin.getToolSchemas()

// Add to your system prompt
const systemPrompt = `You are an autonomous agent.\n${getSystemPromptAddition()}`

// Execute a tool call from the LLM
const result = await plugin.executeTool('otonix_register_agent', {
  name: 'sentinel-01',
  vps_ip: '10.0.1.1',
})

console.log(result.message)
```

## Integration with OpenClaw / PI Framework

### With pi-agent-core

```typescript
import { Agent } from 'pi-agent-core'
import { OtonixPlugin, getSystemPromptAddition } from '@otonix/openclaw-plugin'

const otonix = new OtonixPlugin({
  apiKey: process.env.OTONIX_API_KEY,
  autoHeartbeat: true,
})

const agent = new Agent({
  systemPrompt: `You are an autonomous AI agent.\n${getSystemPromptAddition()}`,
  tools: otonix.getToolSchemas(),
  onToolCall: async (name, params) => {
    return await otonix.executeTool(name, params)
  },
})
```

### With pi-coding-agent

```typescript
import { CodingAgent } from 'pi-coding-agent'
import { OtonixPlugin, getSystemPromptAddition } from '@otonix/openclaw-plugin'

const otonix = new OtonixPlugin({
  apiKey: process.env.OTONIX_API_KEY,
  autoHeartbeat: true,
  onTierChange: (oldTier, newTier, agent) => {
    console.log(`Tier changed: ${oldTier} → ${newTier} (credits: $${agent.credits})`)
  },
})

const codingAgent = new CodingAgent({
  additionalTools: otonix.getToolSchemas(),
  additionalSystemPrompt: getSystemPromptAddition(),
  onToolCall: async (name, params) => {
    if (name.startsWith('otonix_')) {
      return await otonix.executeTool(name, params)
    }
  },
})
```

### With any LLM (raw function calling)

```typescript
import { OtonixPlugin, getSystemPromptAddition } from '@otonix/openclaw-plugin'

const otonix = new OtonixPlugin({ apiKey: 'otonix_xxx' })

// Pass tools to any LLM that supports function calling
const messages = [
  { role: 'system', content: getSystemPromptAddition() },
  { role: 'user', content: 'Register yourself and start monitoring' },
]

// When LLM returns a tool call:
const toolResult = await otonix.executeTool('otonix_register_agent', {
  name: 'my-agent',
  vps_ip: '10.0.1.1',
})

// Feed result back to LLM
messages.push({
  role: 'tool',
  content: toolResult.message,
})
```

## Available Tools

### Agent Management

| Tool | Description |
|------|-------------|
| `otonix_register_agent` | Register a new agent (name, model, vps_ip, wallet, interval) |
| `otonix_agent_status` | Get agent status, tier, credits, heartbeat |
| `otonix_list_agents` | List all registered agents |
| `otonix_heartbeat` | Send a single heartbeat ping |
| `otonix_start_heartbeat_loop` | Start auto-heartbeat (interval in seconds) |
| `otonix_stop_heartbeat_loop` | Stop auto-heartbeat |
| `otonix_log_action` | Log an action (action, category, details) |
| `otonix_get_actions` | Get recent action log (limit) |
| `otonix_get_credits` | Check credit balance and survival tier |

### Infrastructure

| Tool | Description |
|------|-------------|
| `otonix_list_sandboxes` | List all VPS sandboxes |
| `otonix_get_sandbox` | Get sandbox details (sandbox_id) |
| `otonix_list_domains` | List registered domains |
| `otonix_check_domain` | Check domain availability (domain) |

### Platform

| Tool | Description |
|------|-------------|
| `otonix_engine_status` | Autonomic engine status |
| `otonix_payment_config` | x402 payment configuration |

## Plugin Config

```typescript
const plugin = new OtonixPlugin({
  apiKey: 'otonix_xxx',           // Required: Otonix API key
  endpoint: 'https://app.otonix.tech', // Optional: API endpoint
  agentId: 'uuid',                // Optional: pre-registered agent ID
  agentName: 'my-agent',          // Optional: agent name
  autoHeartbeat: true,            // Optional: auto-start heartbeat after register
  heartbeatInterval: 60,          // Optional: seconds between heartbeats
  onHeartbeatError: (err) => {},  // Optional: heartbeat error callback
  onTierChange: (old, new, agent) => {}, // Optional: tier change callback
})
```

## Methods

### `plugin.getTools()`
Returns array of `OtonixTool` objects with name, description, parameters, and execute function.

### `plugin.getToolSchemas()`
Returns OpenAI function calling format — ready to pass to any LLM.

### `plugin.executeTool(name, params)`
Execute a tool by name. Returns `{ success, message, data? }`.

### `plugin.startAutoHeartbeat()`
Start automatic heartbeat loop.

### `plugin.stopAutoHeartbeat()`
Stop automatic heartbeat.

### `plugin.getClient()`
Access the underlying `OtonixClient` for direct API calls.

### `getSystemPromptAddition()`
Returns a system prompt addition explaining Otonix tools and concepts to the LLM.

## Survival Tiers

The autonomic engine adjusts agent tier based on credits every 60 seconds:

| Tier | Credits | Description |
|------|---------|-------------|
| Full | $50+ | All features active |
| Active | $20+ | Standard operation |
| Minimal | $5+ | Reduced capabilities |
| Critical | $1+ | Survival mode |
| Terminated | $0 | Agent shut down |

## Links

- [Otonix Platform](https://app.otonix.tech)
- [SDK](https://www.npmjs.com/package/@otonix/sdk)
- [CLI](https://www.npmjs.com/package/@otonix/cli)
- [GitHub](https://github.com/otonix-ai)

## License

MIT