Fleet Integration Plugin

OpenClaw plugin for connecting to Fleet Core coordination center.

Features

• Automatic instance registration on gateway startup
• Periodic heartbeat to Fleet Core (default 30s)
• Load reporting (tracks active sessions)
• Task reporting for agent sessions
• Commands: /fleet_status, /fleet_reconnect, /fleet_info

Installation

Option 1: Manual Installation

Copy plugin folder to OpenClaw marketplace directory:

mkdir -p ~/.claude/plugins/marketplaces/openclaw-fleet
cp -r /Users/heang/Desktop/openclaw-fleet/fleet-plugin ~/.claude/plugins/marketplaces/openclaw-fleet/

Option 2: Install via git clone

cd ~/.claude/plugins/marketplaces
git clone https://github.com/openclaw-fleet/fleet-plugin openclaw-fleet

Configuration

Add to your OpenClaw gateway config (~/.claude/openclaw.json or equivalent):

{
  "plugins": {
    "fleet-integration": {
      "fleetUrl": "http://160.202.254.29:34444",
      "instanceId": "prod-claw-01",
      "instanceToken": "your-token-here",
      "name": "Production Claw 01",
      "heartbeatInterval": 30,
      "capabilities": ["code_review", "architecture", "debugging", "testing"],
      "tags": ["production", "backend"],
      "capacity": 1,
      "reportTasks": true
    }
  }
}

Required Fields

| Field | Description | |-------|-------------| | fleetUrl | Fleet Core API URL (e.g., http://160.202.254.29:34444) | | instanceId | Unique instance identifier (max 64 chars, must match pre-allocated token) | | instanceToken | Pre-allocated authentication token from Fleet Core |

Optional Fields

| Field | Default | Description | |-------|---------|-------------| | name | instanceId | Display name for this instance | | heartbeatInterval | 30 | Heartbeat interval in seconds (10-120) | | capabilities | ["code_review", "architecture", ...] | Capabilities this instance provides | | tags | [] | Tags for task routing | | capacity | 1 | Max concurrent tasks (1-10) | | reportTasks | true | Report agent sessions as tasks to Fleet Core |

Instance Tokens

Tokens must be pre-allocated in Fleet Core database before use.

Generate tokens via API

# First, insert into instance_tokens table directly
curl -X POST http://160.202.254.29:34444/api/admin/tokens/create \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "prod-claw-01", "description": "Production instance 01"}'

Or via PostgreSQL:

INSERT INTO instance_tokens (instance_id, token_hash, description)
VALUES ('prod-claw-01', '<sha256-hash-of-token>', 'Production instance 01');

Token generation script

import hashlib

instance_id = "prod-claw-01"
token = "your-secret-token-here"
token_hash = hashlib.sha256(token.encode()).hexdigest()

print(f"INSERT INTO instance_tokens (instance_id, token_hash, description)")
print(f"VALUES ('{instance_id}', '{token_hash}', 'Production instance 01');")

Commands

/fleet_status

Check connection status and Fleet Core health.

/fleet_reconnect

Force reconnection to Fleet Core (useful after network issues).

/fleet_info

Show instance info retrieved from Fleet Core.

API Endpoints Used

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/instance/register | POST | Register instance on startup | | /api/instance/heartbeat | POST | Send periodic heartbeat | | /api/instance/unregister | POST | Mark offline on shutdown | | /api/instance/{id} | GET | Get instance info | | /api/task/submit_direct | POST | Create task from agent session | | /api/task/{id}/complete | POST | Mark task completed | | /api/task/{id}/fail | POST | Mark task failed | | /health | GET | Health check |

Architecture

┌─────────────────┐     HTTP/REST     ┌─────────────────┐
│   OpenClaw      │ ←──────────────→ │   Fleet Core    │
│   Instance      │                   │   API Server    │
│                 │                   │                 │
│  fleet-plugin   │                   │  (FastAPI)      │
└─────────────────┘                   └─────────────────┘
        │                                     │
        │                                     │
        ▼                                     ▼
┌─────────────────┐                   ┌─────────────────┐
│  Plugin Hooks   │                   │   PostgreSQL    │
│  - gateway_start│                   │   (Persistence) │
│  - session_start│                   └─────────────────┘
│  - agent_start  │                           │
│  - agent_end    │                           ▼
│  - session_end  │                   ┌─────────────────┐
└─────────────────┘                   │     Redis       │
                                      │   (Cache)       │
                                      └─────────────────┘

Events Hooked

• gateway_start: Register instance, start heartbeat loop
• session_start: Track session start, update load
• before_agent_start: Report task to Fleet Core
• agent_end: Report task completion with result
• session_end: Cleanup session, update load

Development

Build the plugin (TypeScript to ESM):

cd fleet-plugin
npm install
npm run build

The compiled output goes to dist/index.js. OpenClaw can load TypeScript directly if tsconfig.json is present.

Troubleshooting

Connection fails

1. Check fleetUrl is correct and accessible
2. Verify instanceToken matches a pre-allocated token in Fleet Core
3. Check Fleet Core logs for auth errors

Heartbeat not working

1. Use /fleet_status to check connection state
2. Use /fleet_reconnect to force reconnection
3. Check network connectivity

Tasks not reported

1. Ensure reportTasks: true in config
2. Check that before_agent_start event fires
3. Verify task endpoints exist in Fleet Core