Palantir Clawd

Name: Palantir Clawd
Rating: 3.5 (1 reviews)
Author: Assidefok

By Assidefok 👁 59 views ▲ 0 votes

Cron monitoring plugin for OpenClaw with multi-gateway support

GitHub

Install

npm install -g

README

# 🦞 Palantir Clawd

**Cron monitoring plugin for OpenClaw.** Includes a setup wizard for deployment in minutes.

---

## Features

- **Setup Wizard** - deploy the service in 3 steps
- **Multi-gateway** - each gateway (machine) has its own data space, identified by `deviceId`
- **FastAPI** (port 3040) for queries and configuration
- **Timeout detection** - detects if a cron hangs
- **Auto-recover** with configurable retries
- **Notifications** via Telegram and other channels
- **Heartbeat system** - each cron reports its status

---

## Setup Wizard (3 Steps)

### 1. Deploy the Service

```bash
cd ~/.openclaw/workspace/palantir-clawd/py

# Generate a unique token (or provide your own)
export WATCHDOG_API_TOKEN="$(openssl rand -hex 32)"
echo "TOKEN=$WATCHDOG_API_TOKEN"

# You can choose which hosts can make requests (CORS, not security)
export WATCHDOG_ALLOWED_HOSTS="*"

# Start the service
python3 -m uvicorn main:app --host 0.0.0.0 --port 3040
```

### 2. Configure the Tools

Once the service is running, run the interactive assistant:

```bash
node -e "
const readline = require('readline');
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

async function wizard() {
  console.log('');
  console.log('🧙  Palantir Clawd Setup Wizard');
  console.log('=============================');
  console.log('');
  
  const token = process.env.WATCHDOG_API_TOKEN || '';
  console.log('📡 API URL: http://localhost:3040');
  if (token) {
    console.log('🔑 Token:  ' + token);
    console.log('   (Add WATCHDOG_API_TOKEN=' + token + ' to your environment for remote connection)');
  }
  console.log('');
  console.log('✅ Service should be running!');
  console.log('');
  console.log('Next steps:');
  console.log('  1. Add crons to watchlist:   curl -X POST http://localhost:3040/api/watchdog/add/my-cron-id');
  console.log('  2. Check status:              curl http://localhost:3040/api/watchdog/status');
  console.log('  3. Enable tools in OpenClaw:  tooling.commands.register() in your plugin');
  console.log('');
  rl.close();
}
wizard();
"
```

### 3. PM2 for Persistence (optional)

```bash
# Install PM2 if you don't have it
npm install -g pm2

# Save the token configuration
echo "WATCHDOG_API_TOKEN=$(openssl rand -hex 32)" >> ~/.bashrc
source ~/.bashrc

# Start with PM2 (auto-resurrect on reboot)
cd ~/.openclaw/workspace/palantir-clawd/py
pm2 start 'python3 -m uvicorn main:app --host 0.0.0.0 --port 3040' --name palantir-clawd
pm2 save
pm2 startup
```

---

## Multi-Gateway Architecture

Each machine running OpenClaw is a **gateway** identified by `deviceId` (from `~/.openclaw/identity/device.json`). This enables:

- **Separate tables** per gateway (crons, config, heartbeats)
- **One API for all machines** - each request carries its own `gateway_id`
- **Horizontal scalability** - add gateways without changing code

### How Each Request Is Identified

1. **Header `X-Gateway-ID`** (high priority)
2. **Fallback** → reads `deviceId` from `~/.openclaw/identity/device.json`

### Adding a New Gateway

```bash
# On the new machine, the API auto-registers on startup
# Just needs WATCHDOG_API_TOKEN (if remote access is desired)
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `watchdog_status` | Query status (global or per cron) |
| `watchdog_add` | Add a cron to the watchlist |
| `watchdog_remove` | Remove a cron from the watchlist |
| `watchdog_run` | Execute a cron manually |
| `watchdog_retry` | Immediate retry of a cron |
| `watchdog_interval` | Change check interval |
| `watchdog_retries` | Configure retries per cron |
| `watchdog_channels` | Manage notification channels |
| `watchdog_notify` | Send test notification |
| `watchdog_config` | Query/modify global config |

---

## Security

| Layer | Level | Description |
|-------|-------|-------------|
| **Local connections** | ✅ Allowed | `127.0.0.1` / `localhost` - direct access without token |
| **Remote connections** | 🔐 Token required | Need `Authorization: Bearer <WATCHDOG_API_TOKEN>` |
| **CORS** | 🌐 Open by default | `*` in development, change to specific domains in production |
| **Auth token** | 🔑 Bearer token | Generated with `openssl rand -hex 32` or provided by user |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `WATCHDOG_API_TOKEN` | _(empty)_ | Token for remote connections. If absent, only local access allowed |
| `WATCHDOG_ALLOWED_HOSTS` | `*` | Allowed hosts for CORS (not security!) |
| `WATCHDOG_PORT` | `3040` | API port |
| `WATCHDOG_DB` | _(see above)_ | Path to SQLite database |

---

## API Endpoints

### Health
- `GET /` - Service info (public)
- `GET /api/health` - Health check (public)
- `GET /api/health/db` - Database health
- `GET /api/health/config` - Gateway configuration

### Cron Lifecycle
- `POST /api/cron/heartbeat/{cronId}` - Cron running
- `POST /api/cron/start/{cronId}` - Cron started
- `POST /api/cron/complete/{cronId}` - Cron completed
- `POST /api/cron/fail/{cronId}` - Cron failed
- `GET /api/cron/status/{cronId}` - Status of a cron
- `GET /api/cron/history/{cronId}` - Execution history

### Watchdog Query
- `GET /api/watchdog/status` - Status of all crons for this gateway
- `GET /api/watchdog/overdue` - Crons that should have run
- `GET /api/watchdog/gateways` - List of registered gateways
- `GET /api/watchdog/gateways/{gatewayId}` - Details of a gateway
- `GET /api/watchdog/discover` - Auto-discover crons from jobs.json

### Watchdog Actions
- `POST /api/watchdog/add/{cronId}` - Add a cron to the watchlist
- `POST /api/watchdog/remove/{cronId}` - Remove a cron from the watchlist
- `POST /api/watchdog/run/{cronId}` - Run cron now
- `POST /api/watchdog/retry/{cronId}` - Immediate retry

### Config
- `PATCH /api/health/config` - Modify configuration

---

## Database Schema

```sql
-- Each gateway registers here
CREATE TABLE gateways (
    gateway_id TEXT PRIMARY KEY,
    name TEXT,
    host TEXT,
    added_at INTEGER NOT NULL,
    last_seen INTEGER,
    metadata TEXT DEFAULT '{}'
);

-- Crons belong to a gateway
CREATE TABLE crons (
    gateway_id TEXT NOT NULL,
    cron_id TEXT NOT NULL,
    name TEXT,
    schedule TEXT,
    added_at INTEGER NOT NULL,
    last_heartbeat INTEGER,
    last_status TEXT DEFAULT 'unknown',
    consecutive_failures INTEGER DEFAULT 0,
    config TEXT DEFAULT '{}',
    PRIMARY KEY (gateway_id, cron_id)
);

-- Individual heartbeats
CREATE TABLE heartbeats (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    gateway_id TEXT NOT NULL,
    cron_id TEXT NOT NULL,
    timestamp INTEGER NOT NULL,
    status TEXT NOT NULL,
    message TEXT,
    duration_ms INTEGER
);

-- Execution history
CREATE TABLE executions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    gateway_id TEXT NOT NULL,
    cron_id TEXT NOT NULL,
    started_at INTEGER NOT NULL,
    completed_at INTEGER,
    status TEXT NOT NULL,
    error TEXT,
    duration_ms INTEGER
);

-- Config per gateway
CREATE TABLE config (
    gateway_id TEXT NOT NULL,
    key TEXT NOT NULL,
    value TEXT NOT NULL,
    PRIMARY KEY (gateway_id, key)
);
```

---

## Structure

```
palantir-clawd/
├── README.md                 # This file
├── assets/                    # Lobster logo
├── index.ts                   # Plugin entry point (TypeScript)
├── openclaw.plugin.json       # Plugin manifest
├── package.json               # Dependencies
├── tsconfig.json              # TypeScript config
└── py/                       # Python Backend (FastAPI)
    ├── main.py               # App + lifespan
    ├── db.py                 # DB utilities
    ├── validators.py         # Input validation (SQL/command injection protection)
    ├── security.py           # Auth dependencies
    ├── routers/
    │   ├── cron.py           # Cron lifecycle endpoints
    │   ├── watchdog.py       # Watchdog query/actions
    │   └── health.py         # Health + config
    └── services/
        └── notifier.py       # Telegram notifier
```

---

## Installation

```bash
openclaw plugins install clawhub:@navi-os/palantir-clawd
```

---

## Development

```bash
# Install dependencies
pnpm install

# Compile TypeScript
pnpm build

# Test the plugin (development mode)
pnpm start
```

---

## Security Notes

- **SQL injection**: All queries use parameterized queries (`?` placeholders)
- **Command injection**: `subprocess.run()` uses argument lists, never shell strings
- **Input validation**: All API endpoints validate inputs with `validators.py`

tools