King Claw

A server-based AI agent with multi-platform messaging support, configurable sandbox, and extensible plugin system.

Features

• Web UI: Real-time chat interface accessible from any browser
• Multi-Provider AI: Support for Claude, OpenAI, and local models (Ollama)
• Messaging Integrations: Telegram, Discord, and WhatsApp bots
• Configurable Sandbox: Control file system access (workspace, home, full, custom)
• Task Management: Create and execute AI-powered tasks
• Plugin System: Extend functionality with custom plugins
• Authentication: JWT-based auth with API key support
• Deployment Ready: Docker, PM2, systemd support

Quick Start

Local Development

1. Clone the repository

   git clone https://github.com/yourusername/king-claw.git
   cd king-claw

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env with your API keys

4. Start the server

   npm run dev

5. Open in browser

   • Navigate to http://localhost:3000
   • Complete the initial setup wizard
   • Start chatting!

Docker Deployment

1. Configure environment

   cp .env.example .env
   # Edit .env with your configuration

2. Build and run

   docker-compose up -d

3. View logs

   docker-compose logs -f

VPS Deployment

1. Run the install script

   curl -fsSL https://raw.githubusercontent.com/yourusername/king-claw/main/install.sh | bash

   Or with systemd:

   curl -fsSL https://raw.githubusercontent.com/yourusername/king-claw/main/install.sh | bash -s -- --systemd

2. Configure

   cd /opt/king-claw
   nano .env

3. Start with PM2

   npm run start:pm2

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	3000
HOST	Server host	0.0.0.0
NODE_ENV	Environment	production
DATA_PATH	Data storage path	./data
JWT_SECRET	JWT signing secret	(required)
SANDBOX_MODE	File access level	workspace

Sandbox Modes

Mode	Description
workspace	Most secure - only workspace folder (default)
home	Access to user's home directory
custom	Access to specified custom path
full	Full system access (use with caution)

AI Providers

Set your API keys in .env:

# Claude (Anthropic)
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
OPENAI_API_KEY=sk-...

Messaging Integrations

Telegram Bot

1. Create a bot with @BotFather
2. Add token to .env:

   TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
   TELEGRAM_ALLOWED_USERS=12345678,87654321  # Optional

Commands:

• /start - Welcome message
• /help - Show commands
• /files [path] - List files
• /read <file> - Read file
• /tasks - List tasks
• /newtask <title> - Create task
• /clear - Clear conversation
• /status - System status

Discord Bot

1. Create app at Discord Developer Portal
2. Enable Message Content Intent
3. Add token to .env:

   DISCORD_BOT_TOKEN=...
   DISCORD_PREFIX=!kc
   DISCORD_ALLOWED_CHANNELS=  # Optional
   DISCORD_ALLOWED_ROLES=     # Optional

Commands: Use !kc help for command list

WhatsApp Bot

1. Enable in .env:

   WHATSAPP_ENABLED=true
   WHATSAPP_ALLOWED_NUMBERS=14155551234  # Optional

2. Scan QR code shown in terminal on first run
3. Message the bot to chat

Plugin System

Plugins are located in the /plugins directory. Each plugin has:

• manifest.json - Plugin metadata and skills
• index.js - Plugin code

Example plugin structure:

plugins/
  my-plugin/
    manifest.json
    index.js

See existing plugins for examples.

API Reference

Authentication

# Login
POST /api/auth/login
Body: { "username": "...", "password": "..." }

# Use API key
Header: X-API-Key: kc_...

Chat

# Send message
POST /api/ai/chat
Body: { "messages": [{ "role": "user", "content": "..." }] }

Files

# List files
GET /api/files?path=...

# Read file
GET /api/files/read?path=...

# Write file
POST /api/files/write
Body: { "path": "...", "content": "..." }

Tasks

# List tasks
GET /api/tasks

# Create task
POST /api/tasks
Body: { "title": "...", "description": "..." }

Security

• Always change JWT_SECRET and COOKIE_SECRET in production
• Use workspace sandbox mode unless you need broader access
• Enable HTTPS via reverse proxy (nginx, Caddy, etc.)
• Restrict messaging bot access with allowed users/channels/roles

Troubleshooting

Common Issues

Port already in use:

# Find process using port
lsof -i :3000
# Kill it
kill -9 <PID>

WhatsApp QR not showing:

• Ensure Chromium is installed
• Check logs for puppeteer errors
• Try deleting data/whatsapp-session and restarting

API key errors:

• Verify API keys are correct in .env
• Check API key permissions/limits

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.