Philosophy

HOVClaw is built on a simple principle: run your own AI agent infrastructure, controlled from the channels you already use.

• Self-hosted first - Everything runs on your machine, no cloud dependency
• Channel-native - Talk to your agent via Telegram or Discord, not a custom app
• Gateway-first control - WebSocket protocol v3 for programmatic access, with a built-in web UI for quick ops

Features

Multi-Channel Agent Gateway

• Telegram - Polling/webhook intake, callback queries, topic routing (chatId#threadId), media send, reactions
• Discord - Full bot adapter via discord.js
• Multi-account Telegram - Multiple bot accounts with per-account status and logout
• Text mode controls - Per-channel plain|markdown rendering mode (default plain)
• Policy layer - dmPolicy, groupPolicy, per-group/per-topic overrides, pairing flow
• Native Telegram commands - Auto-registered slash command menu (including skill aliases)
• Thinking controls - /think <level> <task> plus persisted default via commands.defaultThinkingLevel
• Exec chat approvals - /bash <cmd> requests approval and /approve <id> allow-once|allow-always|deny resolves

Gateway & Control Plane

• WebSocket protocol v3 - Request/response/event frames with 25 methods
• Built-in web UI - Connection, health, channels, sessions, and chat in one page
• Fail-closed auth defaults - Gateway auth is required unless explicitly opting into insecure mode
• Origin-aware WS policy - Browser Origin headers must be same-origin or allowlisted
• LaunchAgent integration - hovclaw gateway install/start/stop for macOS background service
• Programmatic access - hovclaw gateway call <method> for scripting
• Approval APIs - exec.approval.request|resolve and exec.approvals.get|set

Agent Runtime

• Pi agent core - @mariozechner/pi-agent-core for agent loop and tool orchestration
• Multi-provider models - Anthropic, Google, OpenAI, OpenRouter via @mariozechner/pi-ai
• Model routing - Per-target model slots (interactive, discord, cron) with fallback policy
• Workspace-first tools - Relative file tool paths resolve from agent workspace
• Exec approvals model - deny/allowlist/full + off|on-miss|always ask modes with persistent allowlists
• Least-privilege defaults - exec disabled by default (runtime.tools.exec.enabled=false)
• Read-only diagnostics - built-in diagnose_device tool (profile=core)
• Session persistence - SQLite-backed sessions, messages, agent state, and usage tracking

Scheduling & Automation

• Cron jobs - ~/.hovclaw/agents/*/cron.json with configurable schedules and timezone support
• Channel notifications - Scheduled job results delivered to Telegram or Discord
• Concurrent execution - Configurable max concurrent jobs

Installation

Prerequisites

• Node.js 22+
• Bun package manager

Build

# Clone the repository
git clone https://github.com/user/hovclaw.git
cd hovclaw

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun run test

First-Time Setup

# Interactive onboarding (configures channels, models, credentials)
bun run onboard

# Or if hovclaw is linked globally
hovclaw onboard

Configuration

Run the onboarding wizard to get started:

hovclaw onboard

The wizard handles channel tokens, model provider credentials (via OAuth or API key), and agent configuration. All settings are saved to ~/.hovclaw/config.json.

Security defaults in this release are intentionally strict:

• gateway start fails if gateway.enabled=true and neither gateway.auth.token nor gateway.auth.password is set (unless gateway.auth.allowUnauthenticated=true)
• Telegram webhook mode requires a non-empty webhook secret
• exec runtime tool is opt-in via runtime.tools.exec.enabled=true (legacy runtime.tools.bashEnabled=true still maps to exec enabled)

Agent and skill definitions are loaded from:

• ~/.hovclaw/agents/<name>/agent.json (CLAUDE.md, cron.json)
  • missing ~/.hovclaw/agents/main/agent.json is auto-bootstrapped with a minimal scaffold (name, skills)
• ~/.agents/skills/<name>/SKILL.md
  • legacy ~/.hovclaw/skills content is copied once when shared skills are empty

Runtime state is written under:

• ~/.hovclaw/store (SQLite hovclaw.db, pairing store)
• ~/.hovclaw/data

Workspace Defaults and Bootstrap

• Default workspace: ~/.hovclaw/workspace
• Blank agent workspace values resolve to the same default workspace
• On startup and onboarding, HOVClaw auto-creates missing workspace files:
  • AGENTS.md
  • SOUL.md
  • IDENTITY.md
  • USER.md
  • BOOTSTRAP.md (only when the workspace is effectively empty)
• Workspace files are appended to the system prompt in this order:
  • AGENTS.md -> SOUL.md -> IDENTITY.md -> USER.md -> BOOTSTRAP.md
  • capped at 4,000 chars per file and 12,000 chars total

Config Structure

| Key | Purpose | |-----|---------| | assistant | Assistant name and identity | | agents | Agent definitions and defaults | | bindings | Inbound message routing rules | | models | Model slots, fallback policy, aliases | | commands | Native command behavior, slash registration, authorization | | runtime | Execution mode, timeouts, allowed paths/commands | | channels | Telegram and Discord channel config | | gateway | Gateway host, port, auth, web UI settings | | scheduler | Cron poll interval, concurrency, timezone |

Environment overrides are supported for most fields. See docs/config-reference.md.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Channels                               │
│  ┌──────────┐  ┌─────────┐  ┌─────┐  ┌───────────┐          │
│  │ Telegram │  │ Discord │  │ CLI │  │ Scheduler │          │
│  └────┬─────┘  └────┬────┘  └──┬──┘  └─────┬─────┘          │
│       └──────────────┴─────────┴────────────┘                 │
│                          │                                     │
│                   ┌──────▼──────┐                             │
│                   │   Router    │  Binding-based agent        │
│                   │             │  resolution                 │
│                   └──────┬──────┘                             │
│                          │                                     │
│                ┌─────────▼─────────┐                          │
│                │  Agent Manager    │  Session lifecycle       │
│                │                   │  + persistence           │
│                └─────────┬─────────┘                          │
│                          │                                     │
│         ┌────────────────┼────────────────┐                   │
│         ▼                ▼                ▼                   │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│   │ Agent    │    │ Agent    │    │ Agent    │  pi-agent     │
│   │ Session  │    │ Session  │    │ Session  │  core loop    │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘              │
│        └────────────────┼────────────────┘                    │
│                         │                                     │
│              ┌──────────▼──────────┐                          │
│              │    Tool Runtime     │                          │
│              │  ┌───────────────┐  │                          │
│              │  │ Built-in      │  │                          │
│              │  │ Skills        │  │                          │
│              │  │ Local / Docker│  │                          │
│              │  └───────────────┘  │                          │
│              └─────────────────────┘                          │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                    Gateway (ws + http)                  │   │
│  │  WebSocket v3 protocol  •  Web UI  •  25 methods       │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                    SQLite (better-sqlite3)              │   │
│  │  sessions • messages • agent_state • usage_costs       │   │
│  │  scheduled_jobs • task_run_logs • audit_log            │   │
│  └────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Core Components

| Component | Purpose | |-----------|---------| | Agent Manager | Per-session agent lifecycle, state persistence, model resolution | | Router | Binding-based inbound routing with peer/guild/account/channel cascade | | Scheduler | Cron job loading, execution, and channel notifications | | Gateway | WebSocket v3 server with 25 methods, 7 event types, built-in web UI | | Skill Loader | SKILL.md frontmatter parsing and dependency checking | | Channels | Telegram (multi-account, policy, pairing) and Discord adapters |

CLI Overview

# Setup
hovclaw onboard
hovclaw login [provider]
hovclaw reset [--scope config|config+creds+sessions|full] [--yes] [--non-interactive] [--dry-run] [--json]
hovclaw doctor [--fix] [--deep] [--json]
hovclaw status [--json]

# Messaging
hovclaw message send --channel telegram --to <chat_id> --message "hello"

# Channel management
hovclaw channels list|status|add|remove|login|logout [--account <id>] [--json]

# Pairing management
hovclaw pairing approve telegram <code>
hovclaw pairing approve --channel telegram [--account <id>] <code> [--json]

# Model management
hovclaw models list|status|set [--model <ref>] [--target <slot>] [--json]

# Skill management
hovclaw skills list|info|check|init [--json]

# Gateway lifecycle
hovclaw gateway run
hovclaw gateway install|uninstall|start|stop|restart [--json]
hovclaw gateway status|health [--json]
hovclaw gateway call <method> [--params '{...}'] [--json]
hovclaw gateway open-ui

# Daemon
hovclaw daemon install|uninstall|start|stop|restart|status|logs

Gateway Methods (v3)

| Method | Purpose | |--------|---------| | health | Uptime, active sessions, channels | | status | Gateway config, channel status, session counts | | channels.status | Per-channel enabled/connected status | | channels.logout | Log out a channel (optionally scoped) | | config.get / config.set / config.patch | Read/write/merge config | | models.list / models.set / models.status | Model catalog and routing | | skills.status | Skill list with dependency checks | | sessions.list / sessions.preview | Session listing and message history | | send | Send text/media/reaction to a channel | | agent | Run agent loop, stream events | | chat.history / chat.send / chat.abort | Chat session interaction | | cron.list / cron.status | Scheduled job listing and status | | logs.tail | Recent audit events | | exec.approval.request / exec.approval.resolve | Create and resolve pending exec approvals | | exec.approvals.get / exec.approvals.set | Read/write persisted exec defaults and per-agent allowlists |

Events: tick, health, agent, chat, shutdown, exec.approval.requested, exec.approval.resolved

Development

bun run build          # tsc compile to dist/
bun run typecheck      # tsc --noEmit
bun run dev            # start daemon (tsx src/index.ts)
bun run test           # vitest run
bun run test:watch     # vitest watch

OpenClaw Heritage

HOVClaw is a lean TypeScript implementation inspired by OpenClaw. See FEATURE_PARITY.md for the complete tracking matrix.

Key differences:

• Lean scope - Telegram + Discord only, not all 20+ channels
• Gateway-first - WebSocket v3 control plane with built-in web UI
• SQLite persistence - Single-file database, no external services
• Pi agent runtime - @mariozechner/pi-agent-core for agent loop orchestration
• Multi-account Telegram - Per-account config, policy, and pairing

Docs

• docs/concept.md
• docs/architecture.md
• docs/config-reference.md
• docs/gateway-compat.md

License

MIT