📦 Kkclaw Server — 无头客户端

---

name: KKClaw Server description: Headless OpenClaw client for Ubuntu/Raspbian with heartbeat, auto-reconnect, auto-recovery, queue management, and hot model switching. icon: 🦞 version: 2026.2.17 platforms: - ubuntu - raspbian tags: - openclaw - headless - server - automation - iot

---

Overview

KKClaw Server is a headless, server-optimized version of OpenClaw designed for Ubuntu and Raspbian systems. It provides all the core OpenClaw functionality without a GUI, making it perfect for Raspberry Pi deployments, cloud servers, and headless environments.

Features

• Heartbeat Monitoring: Configurable heartbeat that reports status, model, queue length, memory usage, and uptime to a gateway
• Auto Reconnect: Automatic reconnection with exponential backoff when connection is lost
• Auto Recovery: Automatic recovery features to resume operation after unexpected failures
• Queue Management: Advanced FIFO queue with size and retry limits, resumes after disconnect
• Hot Model Switching: Switch models on-the-fly with fallback support and auto-rollback protection
• CLI Interface: Detailed command-line interface for all operations
• Systemd Integration: Easy deployment via systemd service

Requirements

• Ubuntu 18.04+ or Raspbian
• Node.js 18+
• Network access to configured gateway

Installation

• Clone or download this skill
• Install dependencies:

npm install

• Create the configuration file:

mkdir -p ~/.kkclaw
cp config.json.example ~/.kkclaw/config.json

• Edit the configuration with your gateway details:

nano ~/.kkclaw/config.json

• Install the systemd service (optional):

sudo cp kkclaw.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable kkclaw
sudo systemctl start kkclaw

Configuration

Edit ~/.kkclaw/config.json to configure your gateway connection:

{
  "gateway": {
    "url": "https://your-gateway.example.com",
    "apiKey": "your-api-key-here"
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30000
  },
  "queue": {
    "maxSize": 100,
    "maxRetries": 3
  },
  "model": {
    "fallback": "default-model",
    "autoRollback": true
  }
}

Usage

Start the server

node main.js

Check status

node main.js status

Switch model

node main.js switch-model 

View queue

node main.js queue

Clear queue

node main.js clear-queue

Systemd Service

The included kkclaw.service file provides systemd integration. After installation:

• Start: sudo systemctl start kkclaw
• Stop: sudo systemctl stop kkclaw
• Restart: sudo systemctl restart kkclaw
• View logs: journalctl -u kkclaw -f

Security Considerations

• Always review the configuration before running
• Use API keys only with gateways you trust
• Run as a non-privileged user (not as root)
• Consider running in a container for additional isolation

Troubleshooting

Server not connecting

• Check your gateway URL is correct
• Verify network connectivity
• Check API key is valid

Queue filling up

• Check gateway is reachable
• Review queue size limits in config
• Use clear-queue command if needed

Model switching failing

• Verify model name is valid
• Check fallback model is configured
• Review logs for specific errors

License

MIT