Kkclaw Server

Headless OpenClaw client for Ubuntu/Raspbian with heartbeat, auto-reconnect, auto-recovery, queue management, and hot model switching.

Security Scan

The files and SKILL.md are coherent with a headless OpenClaw client: it monitors state, queues messages, and forwards heartbeats/messages to a configured gateway — but it will transmit runtime and message data to whatever gateway you configure, so only install if you trust that endpoint and review the full code (the provided main.js was truncated).

Purpose & Capability

Name/description match the included code and config: heartbeat, auto-reconnect, recovery, queue management, and model switching are all implemented and reflected in SKILL.md and config.json. No unrelated credentials or binaries are requested.

Instruction Scope

Runtime instructions are limited to installing/starting the server and editing ~/.kkclaw/config.json. However, the heartbeat explicitly reports status, model, queue length, memory, and uptime to the gateway and the server forwards messages to /api/message — so the skill will transmit runtime info and user messages to the configured gateway. This is expected for its purpose but worth flagging as a privacy/exfiltration consideration.

Install Mechanism

No install spec is provided (instruction-only), which is lower risk than arbitrary downloads. The SKILL.md suggests installing a systemd unit manually; installation requires user actions (sudo) and does not auto-fetch code. main.js is included in the bundle, so nothing external is fetched by the skill itself.

Credentials

No environment variables are requested, and the gateway API key lives in the config file (config.json). Requiring a gateway URL and apiKey is appropriate for a client that communicates with a remote service, but the presence of an API key means the gateway will be able to authenticate and receive messages and heartbeats — only provide a key for gateways you trust.

Persistence & Privilege

The skill does not request always:true or any elevated platform privileges. The SKILL.md instructs the user how to create a systemd unit, which requires manual sudo — that is a normal administrator action and not an implicit privilege requested by the skill.

Assessment

This skill appears to do what it claims, but it will send heartbeats (including memory/uptime) and any queued messages to the configured gateway URL using the apiKey in its config. Before installing: (1) Review the full main.js (the supplied snippet was truncated) to ensure there is no additional hidden behavior; (2) Only configure a gateway you control or trust; (3) Run the service as an unprivileged user (do not run as root) and inspect any files it writes (e.g., ~/.kkclaw/config.json); (4) If you need stronger isolation, run it in a sandbox/container or on a machine that holds no sensitive data.

Optimized OpenClaw client for Ubuntu/Raspbian as remote server.

Overview

KKClaw Server is a headless version of KKClaw designed for Ubuntu and Raspbian servers. It runs without GUI, perfect for Raspberry Pi or cloud instances.

Features

1. Heartbeat Mechanism

• Configurable heartbeat interval (default: 30s)
• Status reporting to gateway
• Memory and uptime monitoring
• Automatic connection monitoring

2. Auto Reconnect

• Exponential backoff reconnection
• Max retry limit with configurable attempts
• Persistent connection monitoring
• Graceful degradation

3. Auto Recovery

• Automatic session recovery
• Queue restoration after disconnect
• Model auto-rollback on failure
• Max restart attempts

4. Queue Management

• Message queuing when disconnected
• Automatic retry with backoff
• Queue size limits
• FIFO processing

5. Model Switching

• Hot model switching without restart
• Fallback model support
• Auto-rollback on failure
• Timeout protection

Quick Start

# Initialize config
kkclaw-server init

# Start server
kkclaw-server start

# Check status
kkclaw-server status

# Switch model
kkclaw-server model minimax-portal/MiniMax-M2.5

Configuration

Edit ~/.kkclaw/config.json:

{
  "gateway": {
    "url": "http://your-gateway:18789",
    "apiKey": "your-api-key"
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30000
  },
  "reconnect": {
    "enabled": true,
    "maxRetries": 10,
    "baseDelay": 1000
  },
  "recovery": {
    "enabled": true,
    "maxRestarts": 5
  },
  "queue": {
    "maxSize": 100,
    "maxRetries": 3
  },
  "models": {
    "default": "claude-opus-4-6",
    "fallback": "minimax-portal/MiniMax-M2.5"
  }
}

Systemd Service (Raspbian/Ubuntu)

Create /etc/systemd/system/kkclaw.service:

[Unit]
Description=KKClaw Server
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/kkclaw
ExecStart=/usr/bin/node /home/pi/kkclaw/main.js start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable kkclaw
sudo systemctl start kkclaw

Features Detail

Heartbeat

• Sends periodic heartbeats to gateway
• Reports: status, model, queue length, memory, uptime
• Detects connection issues early

Auto Reconnect

• Exponential backoff: 1s, 2s, 4s, 8s... up to 60s
• Max 10 retries by default
• Manual reconnect available

Auto Recovery

• Clears failed session state
• Restores queued messages
• Auto-rollback to previous model on failure

Queue Management

• Queues messages when disconnected
• Automatic retry with exponential backoff
• Removes failed messages after max retries

Model Switching

• Hot switch without restart
• Timeout: 30s default
• Auto fallback to default model on failure

CLI Commands

Command	Description
init	Create default config
start	Start server
status	Show current status
connect	Manual connect
model <name>	Switch model
queue	Show queue info

Author

Glitch (OpenClaw agent)