clawhive

# clawhive

[![CI](https://github.com/longzhi/clawhive/actions/workflows/ci.yml/badge.svg)](https://github.com/longzhi/clawhive/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.92%2B-orange.svg)](https://www.rust-lang.org/)
[![GitHub release](https://img.shields.io/github/v/release/longzhi/clawhive?include_prereleases)](https://github.com/longzhi/clawhive/releases)

English | [中文](README_CN.md)

An open-source, Rust-native alternative to [OpenClaw](https://github.com/openclaw/openclaw) — deploy your own AI agents across Telegram, Discord, Feishu/Lark, WhatsApp, WeChat, and more with a single binary.

**One binary, ~14 MB, zero runtime dependencies.** No Node.js, no npm, no Docker — just download, configure, and run.

## Installation

```bash
curl -fsSL https://raw.githubusercontent.com/longzhi/clawhive/main/install.sh | bash
```

Auto-detects OS/architecture, downloads latest release, installs binary and skills to `~/.clawhive/`.

After installation, run to activate in your current shell:

```bash
source ~/.clawhive/env
```

Or download manually from [GitHub Releases](https://github.com/longzhi/clawhive/releases).

## Setup

Configure providers, agents, and channels using either method:

**Option A: Web Setup Wizard** — Start the server and open the browser-based wizard:

```bash
clawhive start
# Open http://localhost:8848/setup in your browser
```

**Option B: CLI Setup Wizard** — Run the interactive terminal wizard:

```bash
clawhive setup
```

## Usage

```bash
# Setup / config
clawhive setup
clawhive validate

# Chat mode (local REPL)
clawhive chat

# Service lifecycle
clawhive start               # start in foreground
clawhive up                  # start if not already running (always daemon)
clawhive restart
clawhive stop
clawhive reload              # hot-reload config without restart

# Dashboard mode (observability TUI)
clawhive dashboard

# Code mode (developer TUI)
clawhive code

# Agents / sessions
clawhive agent list
clawhive agent show clawhive-main
clawhive session reset <session_key>

# Schedules / tasks
clawhive schedule list
clawhive schedule run <schedule_id>
clawhive task trigger clawhive-main "summarize today's work"

# Logs
clawhive logs

# Auth
clawhive auth status
clawhive auth login openai
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `setup` | Interactive configuration wizard |
| `up` | Start as background daemon (alias for `start -d`) |
| `start [--tui] [--daemon]` | Start all configured channel bots and HTTP API server |
| `stop` | Stop a running clawhive process |
| `restart` | Restart clawhive (stop + start as daemon) |
| `reload [--agents\|--routing]` | Hot-reload configuration without restart |
| `chat [--agent <id>]` | Local REPL for testing |
| `validate` | Validate YAML configuration |
| `consolidate` | Run memory consolidation manually |
| `logs` | Tail the latest log file |
| `agent list\|show\|enable\|disable` | Agent management |
| `skill list\|show\|analyze\|install` | Skill management |
| `session reset <key>` | Reset a session |
| `schedule list\|run\|enable\|disable\|history` | Scheduled task management |
| `wait list` | List background wait tasks |
| `task trigger <agent> <task>` | Send a one-off task to an agent |
| `auth login\|status` | OAuth authentication management |

## Why clawhive?

- **Tiny footprint** — One binary, ~14 MB. Runs on a Raspberry Pi, a VPS, or a Mac Mini with minimal resource usage.
- **Security by design** — Two-layer security model: non-bypassable hard baseline + origin-based trust. External skills must declare permissions explicitly.
- **Bounded execution** — Enforced token budgets, timeout limits, and sub-agent recursion depth. No runaway loops, no surprise bills.
- **Web + CLI setup** — Browser-based setup wizard or interactive CLI. Get your first agent running in under 2 minutes.

## Features

- Multi-agent orchestration with per-agent personas, model routing, and memory policy controls
- Three-layer memory system: Session JSONL → Daily files → MEMORY.md (long-term)
- Hybrid search: sqlite-vec vector similarity + FTS5 BM25 over memory chunks
- Hippocampus consolidation: periodic LLM-driven synthesis into long-term memory
- Channel adapters: Telegram, Discord, Slack, WhatsApp, iMessage, Feishu, DingTalk, WeCom (multi-bot, multi-connector)
- ReAct reasoning loop with repeat guard and sub-agent spawning
- Skill system (SKILL.md with frontmatter + permission declarations)
- Token-bucket rate limiting per user
- LLM provider abstraction with retry + exponential backoff (Anthropic, OpenAI, Gemini, DeepSeek, Groq, Ollama, OpenRouter, Together, Fireworks, and any OpenAI-compatible endpoint)
- Real-time TUI dashboard and YAML-driven configuration

## Architecture

![clawhive architecture](assets/architecture.png)

<details>
<summary><strong>Project Structure</strong></summary>

```
crates/
├── clawhive-cli/        # CLI binary (clap) — start, setup, chat, validate, agent/skill/session/schedule
├── clawhive-core/       # Orchestrator, session mgmt, config, persona, skill system, sub-agent, LLM router
├── clawhive-memory/     # Memory system — file store (MEMORY.md + daily), session JSONL, SQLite index, chunker, embedding
├── clawhive-gateway/    # Gateway with agent routing and per-user rate limiting
├── clawhive-bus/        # Topic-based in-process event bus (pub/sub)
├── clawhive-provider/   # LLM provider trait + multi-provider adapters (streaming, retry)
├── clawhive-channels/   # Channel adapters (Telegram, Discord, Slack, WhatsApp, iMessage)
├── clawhive-auth/       # OAuth and API key authentication
├── clawhive-scheduler/  # Cron-based task scheduling
├── clawhive-server/     # HTTP API server
├── clawhive-schema/     # Shared DTOs (InboundMessage, OutboundMessage, BusMessage, SessionKey)
├── clawhive-runtime/    # Task executor abstraction
└── clawhive-tui/        # Real-time terminal dashboard (ratatui)

~/.clawhive/             # Created by install + setup
├── bin/                 # Binary
├── skills/              # Skill definitions (SKILL.md with frontmatter)
├── config/              # Generated by `clawhive setup`
│   ├── main.yaml        # App settings, channel configuration
│   ├── agents.d/*.yaml  # Per-agent config (model policy, tools, memory, identity)
│   ├── providers.d/*.yaml # LLM provider settings
│   └── routing.yaml     # Channel → agent routing bindings
├── workspaces/          # Per-agent workspace (memory, sessions, prompts)
├── data/                # SQLite databases
└── logs/                # Log files
```

</details>

<details>
<summary><strong>Security Model</strong></summary>

clawhive implements a **two-layer security architecture** for defense-in-depth:

**Hard Baseline (Always Enforced)**

| Protection | What It Blocks |
|------------|----------------|
| **SSRF Prevention** | Private networks (10.x, 172.16-31.x, 192.168.x), loopback, cloud metadata endpoints |
| **Sensitive Path Protection** | Writes to `~/.ssh/`, `~/.gnupg/`, `~/.aws/`, `/etc/`, system directories |
| **Private Key Shield** | Reads of `~/.ssh/id_*`, `~/.gnupg/private-keys`, cloud credentials |
| **Dangerous Command Block** | `rm -rf /`, fork bombs, disk wipes, curl-pipe-to-shell patterns |
| **Resource Limits** | 30s timeout, 1MB output cap, 5 concurrent executions |

**Origin-Based Trust Model**

| Origin | Trust Level | Permission Checks |
|--------|-------------|-------------------|
| **Builtin** | Trusted | Hard baseline only |
| **External** | Sandboxed | Must declare all permissions in SKILL.md frontmatter |

External skills declare permissions in SKILL.md:

```yaml
---
name: weather-skill
permissions:
  network:
    allow: ["api.openweathermap.org:443"]
  fs:
    read: ["${WORKSPACE}/**"]
  exec: [curl, jq]
  env: [WEATHER_API_KEY]
---
```

Any access outside declared permissions is denied at runtime.

</details>

<d

[truncated…]