Laraclaw — OpenClaw AI Assistant for Laravel

Installation • Quick Start • Skills • Gateways • Dashboard • Configuration

_{Last updated: 2026-04-08}

Laraclaw is a Laravel-based implementation of OpenClaw, the open-source personal AI assistant platform. It brings powerful, local-first, and highly extensible AI assistant capabilities to the Laravel ecosystem.

• 🧠 Open Brain Memory — Supabase-ready memory store with pgvector semantic search and fallback lexical search
• 🔄 Streaming-Aware Memory Context — Streaming chat now uses token-budgeted history, relevant memory retrieval, and intent routing
• 📝 Automatic Memory Extraction — Reminder, preference, watch-intent, and explicit fact-style messages can be auto-saved into memory fragments after replies
• ⚡ Model Benchmarks — Persist model test latency, rank providers/models, and review recent failures from the dashboard
• 🔧 14 Built-in Skills — Time, Calculator, Web Search, HTTP Request, Web Fetch, App Builder, Memory, Shopping List, File System, Execute, Email, Calendar, Scheduler, Notifications
• 💬 Multi-Platform Gateways — CLI, Telegram, Discord, WhatsApp, and Slack support
• 🌐 Web Dashboard — Tabbed dashboard with real-time polling, skill marketplace with toggle switches, and dedicated tool pages
• 🎨 Modern UI Stack — Laravel Volt single-file components with Tailwind CSS 4 conventions for dashboard and chat UI
• 🤝 Multi-Agent Mode — Per-message planner/executor/reviewer orchestration for complex tasks
• 🧩 Skill Marketplace — Enable/disable registered skills from the dashboard with toggle switches, inline skill editor with custom descriptions, schema parameter display, and reset-to-default
• 📄 Document Ingestion — Dedicated Documents page for uploading and indexing documents into vector storage
• 🏗️ App Builder — Dedicated App Builder page for creating and managing Laravel MVC modules
• 🔐 Security First — User allowlists, autonomy levels, filesystem scoping, webhook verification
• 🤖 Multi-Provider AI — OpenAI, Anthropic, Gemini, Ollama, Groq, Mistral, DeepSeek, xAI, OpenRouter, ZAI
• 📋 AIEOS Support — AI Entity Object Specification v1.1 for portable AI identities
• 🚇 Tunnel Support — ngrok, Cloudflare Tunnel, and Tailscale for local development
• 🧭 Intent Routing — Specialist prompt routing for builder, memory, scheduling, shopping, and entertainment intents
• 🧱 Module App Builder (MVP) — Generate blog apps inside the same Laravel install using Laravel MVC modules under app/Modules

• ✅ Dashboard UX Overhaul — Tabbed dashboard (Overview/Analytics/Infrastructure/Management), real-time polling via wire:poll, skill marketplace with toggle switches, extracted Documents & App Builder into dedicated pages
• ✅ Skill Editor — Click-to-edit skill marketplace panel with custom descriptions, parameter schema display, enable/disable toggle, and reset-to-default (42 new tests)
• ✅ Conversations Management — Bulk selection/deletion, prune empty conversations, hide-empty toggle, smart auto-titling (strips attachment prefixes, 60-char word-boundary truncation)
• ✅ Improved Empty States — Contextual guidance text, icons, and CTA links on Conversations, Memories, Documents, and App Builder pages
• ✅ Phase 17: Web Chat Parity — Voice I/O, file attachments, rich markdown rendering, chat settings panel, conversation export, agent activity visibility (real-time tool calls, intent badges, token usage), PWA removal
• ✅ Laravel 13 Upgrade — Framework upgraded to Laravel 13
• ✅ Model Benchmarks — Stored model-card response times with a new benchmarks leaderboard page
• ✅ Telegram Reliability — CSRF-safe webhook handling, secret-token sync, and persistent Cloudflare quick-tunnel lifecycle
• ✅ Memory Recall Fixes — Anonymous gateway chats now scope memories by conversation, explicit fact requests are extracted, and Telegram memories are visible in the Memories page
• ✅ Dashboard UX Overhaul — Tabbed dashboard (Overview/analytics/infrastructure/management) with wire:poll auto-refresh, real-time stats skill marketplace with toggle switches, and dedicated Documents/app-builder pages
• ✅ Improved Empty states — Better empty states with guidance text and CTAs on Conversations, memories, and chat pages
• ✅ Auto-Title improvement — Smart title generation from user messages content, strips attachment prefix, word-boundary truncation, re-titles "New Chat" conversations
• ✅ Laravel 13 Upgrade — Framework upgraded to Laravel 13

• PHP 8.4+
• Laravel 13.x
• SQLite (default) / MySQL / PostgreSQL
• Composer

• Component model: Laravel Volt (classless Livewire components in Blade single-file components)
• Styling standard: Tailwind CSS 4 utility conventions
• Scope: All new or refactored dashboard/chat UI should follow this standard

• Tailwind is compiled locally via Vite + @tailwindcss/vite plugin — no CDN runtime dependency.
• Tailwind is configured in resources/css/app.css using @import, @source, @theme, and @plugin directives.
• Add new template scan paths via @source entries in app.css (instead of a JS config file).
• Keep shared design tokens (e.g. fonts) in the @theme block in app.css.

composer require laraclaw/laraclaw

php artisan laraclaw:install

This interactive command will:

• Check system requirements
• Configure your AI provider (OpenAI, Anthropic, Ollama, etc.)
• Set up Telegram/Discord bots (optional)
• Run database migrations
• Create identity files (IDENTITY.md, SOUL.md)

Add your AI provider credentials to .env:

# AI Provider (openai, anthropic, gemini, ollama, groq, mistral, deepseek, xai, openrouter, zai, zai-anthropic)
AI_PROVIDER=openai
AI_MODEL=gpt-4o-mini

# API Keys
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=sk-or-...
# ZAI_API_KEY=...

# Telegram (optional)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_SECRET_TOKEN=your-webhook-secret

# Discord (optional)
DISCORD_BOT_TOKEN=Bot ...
DISCORD_PUBLIC_KEY=...
DISCORD_APPLICATION_ID=...

# WhatsApp (optional)
WHATSAPP_ENABLED=true
WHATSAPP_TOKEN=...
WHATSAPP_PHONE_NUMBER_ID=...
WHATSAPP_VERIFY_TOKEN=...
WHATSAPP_APP_SECRET=...

# Multi-Agent & Marketplace
LARACLAW_MULTI_AGENT_ENABLED=false
LARACLAW_MARKETPLACE_ENABLED=true

# Memory extraction (auto-save reminders/preferences)
LARACLAW_MEMORY_AUTO_EXTRACT=true

# Local queue mode (recommended for solo/local use)
QUEUE_CONNECTION=sync

# Web tools network policy (set true for private VPS/Tailscale-only deployments)
LARACLAW_ALLOW_PRIVATE_NETWORK_URLS=false
LARACLAW_ALLOW_LOOPBACK_URLS=false

# Local development: bypass auth (auto-login as first user)
AUTH_DISABLED=false

# Timezone (defaults to America/New_York)
APP_TIMEZONE=America/New_York

# Optional: route memory storage to Supabase
# LARACLAW_MEMORY_CONNECTION=supabase

# Slack (optional)
# SLACK_BOT_USER_OAUTH_TOKEN=xoxb-...
# SLACK_SIGNING_SECRET=...

# Supabase (optional)
# DB_SUPABASE_HOST=...
# DB_SUPABASE_PORT=5432
# DB_SUPABASE_DATABASE=postgres
# DB_SUPABASE_USERNAME=postgres
# DB_SUPABASE_PASSWORD=...
# DB_SUPABASE_URL=
# DB_SUPABASE_DIRECT_URL=

For local development and solo usage, Laraclaw now defaults to QUEUE_CONNECTION=sync in .env.example so memory extraction and similar lightweight jobs run immediately in the same request.

If you want to exercise the queued architecture instead, switch back to QUEUE_CONNECTION=database and run a worker:

php artisan queue:work

With sync, explicit memory requests such as Remember that my cat's name is Wilma are stored immediately after the reply is generated.

You can keep global defaults with AI_PROVIDER / AI_MODEL and override specific agent keys when needed.

Use config/laraclaw.php under ai.agents to define per-agent keys. The config is pre-wired for general, builder, memory, entertainment, shopping, scheduling, planner, executor, and reviewer (and you can add any additional key).

Example environment overrides:

AGENT_BUILDER_PROVIDER=anthropic
AGENT_BUILDER_MODEL=claude-opus-4-20250514

AGENT_PLANNER_PROVIDER=gemini
AGENT_PLANNER_MODEL=gemini-2.5-flash

If an agent-specific provider/model is not set, Laraclaw falls back to AI_PROVIDER and AI_MODEL.

Model IDs must be valid for the selected provider. For example, when using OpenRouter, use OpenRouter model identifiers (often vendor-prefixed), such as openai/gpt-4o-mini or provider-specific IDs published by OpenRouter.

Start chatting immediately from the command line:

php artisan laraclaw:chat

Visit /laraclaw in your browser for:

• 📊 Dashboard — System overview and health status
• 💬 Conversations — Browse all conversations
• 🧠 Memories — View stored memory fragments
• 📈 Metrics — Performance statistics
• 💭 Chat — Interactive web chat interface

use App\Laraclaw\Facades\Laraclaw;

// Start a conversation
$conversation = Laraclaw::startConversation(userId: 1);

// Send a message and get a response
$response = Laraclaw::chat($conversation, "What time is it?");

// Optional per-message override for multi-agent mode
$response = Laraclaw::chat($conversation, "Research and summarize this topic", true);

// Quick one-off question
$response = Laraclaw::ask("Calculate 15% of 850");

• Unified webhook ingest: POST /api/webhooks/{platform} (slack, telegram, discord, whatsapp)
• Dedicated Slack parity webhook: POST /laraclaw/webhooks/slack
• MCP memory tools:
  • POST /api/mcp/search
  • GET /api/mcp/recent
  • GET /api/mcp/stats

These endpoints queue memory ingestion, persist memory records via MemoryStore, and expose retrieval-friendly outputs for MCP clients.

Laraclaw comes with 14 built-in skills that the AI can use automatically:

Laraclaw can now generate blog modules in standard Laravel MVC style using AppBuilderSkill.

Each generated module includes:

• Module manifest in app/Modules/{ModuleName}/module.json
• Eloquent model in app/Modules/{ModuleName}/Models/*Post.php
• Controller in app/Modules/{ModuleName}/Http/Controllers/*PostController.php
• Route file in routes/modules/{slug}.php loaded dynamically by ModuleServiceProvider
• Blade views in resources/views/modules/{slug}/
• Migration in database/migrations/ for {slug}_posts table

Runtime loading behavior:

• ModuleServiceProvider discovers module manifests from app/Modules
• Route groups are mounted from each module manifest (prefix or optional domain)

After generating an app, run:

php artisan migrate

You can manage modules from:

• AppBuilderSkill tool actions
• Livewire dashboard “Module App Builder (Laravel MVC)” panel

Current module actions (via tool calls):

• create_app
• list_apps
• create_post_draft
• publish_post
• list_posts
• set_domain

<?php

namespace App\Laraclaw\Skills;

use App\Laraclaw\Skills\Contracts\SkillInterface;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;

class MyCustomSkill implements SkillInterface, Tool
{
    public function name(): string
    {
        return 'my_custom_skill';
    }

    public function description(): string
    {
        return 'Description of what this skill does';
    }

    public function execute(array $parameters): string
    {
        // Your skill logic here
        return "Result: ...";
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'param' => $schema->string()->description('Parameter description'),
        ];
    }

    public function toTool(): Tool
    {
        return $this;
    }

    public function handle(Request $request): string
    {
        return $this->execute($request->all());
    }
}

Register in LaraclawServiceProvider:

$this->app->singleton(MyCustomSkill::class);
$this->app->tag([MyCustomSkill::class], 'laraclaw.skills');

The built-in CLI gateway for terminal interaction:

php artisan laraclaw:chat

Options:

• --session=ID — Resume a specific conversation
• --new — Start a new conversation

1. Create a bot via @BotFather
2. Start a public tunnel for your local app:

php artisan laraclaw:tunnel start --provider=cloudflare

3. Sync the Telegram webhook to the current public URL:

php artisan laraclaw:telegram:webhook-sync

If you already have a public URL, pass it explicitly:

php artisan laraclaw:telegram:webhook-sync --url=https://example.trycloudflare.com

The webhook endpoint is: POST /laraclaw/webhooks/telegram

Telegram memories are stored immediately when QUEUE_CONNECTION=sync. Anonymous Telegram conversations are surfaced in the dashboard Memories page with a telegram badge.

1. Create a Discord application at Discord Developer Portal
2. Register slash commands:

php artisan laraclaw:discord:register-commands

The webhook endpoint is: POST /laraclaw/webhooks/discord

Meta Cloud API webhook endpoints:

• Verification: GET /laraclaw/webhooks/whatsapp
• Incoming messages: POST /laraclaw/webhooks/whatsapp

Voice notes are transcribed via STT and processed as normal chat messages.

Access the live Volt dashboard at /laraclaw/live:

• Tabbed Layout — Overview, Analytics, Infrastructure, and Management tabs
• Real-Time Polling — Dashboard stats auto-refresh every 30 seconds via wire:poll
• Skill Marketplace — Toggle switches for enabling/disabling skills with descriptions
• Bulk Actions — Select multiple conversations for batch deletion
• Empty Conversation Cleanup — Prune conversations with zero messages older than 1 hour
• Auto-Titled Conversations — Smart title generation from first user message (strips attachment prefixes, 60-char limit with word-boundary truncation)
• Improved Empty States — Guidance text and CTAs on empty Conversations, Memories, and Chat pages

Expose your local server for Telegram/Discord webhooks:

# Cloudflare Tunnel (recommended)
php artisan laraclaw:tunnel start --provider=cloudflare

# ngrok
php artisan laraclaw:tunnel start --provider=ngrok

# Tailscale
php artisan laraclaw:tunnel start --provider=tailscale

Check tunnel status:

php artisan laraclaw:tunnel status

Configure in .env:

LARACLAW_AUTONOMY=supervised

Restrict who can interact with Laraclaw:

LARACLAW_ALLOWLIST_ENABLED=true
LARACLAW_ALLOWED_USERS=telegram:123456,discord:789012

Limit file operations to a specific directory:

LARACLAW_FILESYSTEM_SCOPE=/var/www/storage/laraclaw

Full configuration in config/laraclaw.php:

return [
    // AI Provider
    'ai' => [
        'provider' => env('AI_PROVIDER', 'openai'),
        'model' => env('AI_MODEL', 'gpt-4o-mini'),
        'max_tokens' => env('AI_MAX_TOKENS', 4096),
        'temperature' => env('AI_TEMPERATURE', 0.7),
    ],

    // Security
    'security' => [
        'autonomy' => env('LARACLAW_AUTONOMY', 'supervised'),
        'allowlist_enabled' => env('LARACLAW_ALLOWLIST_ENABLED', false),
        'filesystem_scope' => env('LARACLAW_FILESYSTEM_SCOPE', storage_path('laraclaw')),
    ],

    // Identity
    'identity' => [
        'path' => env('LARACLAW_IDENTITY_PATH', storage_path('laraclaw')),
        'identity_file' => env('LARACLAW_IDENTITY_FILE', 'IDENTITY.md'),
        'soul_file' => env('LARACLAW_SOUL_FILE', 'SOUL.md'),
        'aieos_file' => env('LARACLAW_AIEOS_FILE', 'aieos.json'),
        'aieos_enabled' => env('LARACLAW_AIEOS_ENABLED', true),
    ],

    // Memory
    'memory' => [
        'conversation_limit' => env('LARACLAW_MEMORY_LIMIT', 50),
        'search_limit' => env('LARACLAW_SEARCH_LIMIT', 10),
        'fts_enabled' => env('LARACLAW_FTS_ENABLED', true),
    ],
];

Laraclaw supports the AIEOS v1.1 specification for portable AI identities.

Create storage/laraclaw/aieos.json:

{
  "standard": {
    "protocol": "AIEOS",
    "version": "1.1.0"
  },
  "identity": {
    "names": {
      "first_name": "Laraclaw",
      "nickname": "Claw"
    }
  },
  "psychology": {
    "neural_matrix": {
      "creativity": 0.7,
      "empathy": 0.8,
      "logic": 0.9
    },
    "moral_compass": {
      "core_values": ["helpfulness", "honesty", "privacy"]
    }
  },
  "linguistics": {
    "text_style": {
      "formality_level": 0.4,
      "verbosity_level": 0.5
    }
  }
}

# Run all tests
php artisan test --compact

# Run with filter
php artisan test --compact --filter=testName

# Run specific file
php artisan test --compact tests/Feature/VoltImprovementsTest.php

• 29 tests for Volt dashboard improvements (tabs, bulk actions, pruning, empty states, auto-title, route accessibility)
• 155+ tests total across all features with Pest 4

• Unit Tests — Models, relationships, memory manager, skill execution
• Feature Tests — Volt component rendering, dashboard tabs, conversation bulk actions, auto-title logic, route accessibility, skill marketplace toggles, scheduler controls
• Gateway Tests — Webhook signature verification, message parsing, voice replies

app/Laraclaw/
├── Agents/
│   ├── CoreAgent.php          # LLM orchestration
│   ├── IntentRouter.php
│   └── MultiAgentOrchestrator.php
├── Channels/
│   └── ChannelBindingManager.php
├── Events/
│   ├── MessageProcessed.php
│   └── MessageProcessingFailed.php
├── Gateways/
│   ├── CliGateway.php
│   ├── TelegramGateway.php
│   ├── DiscordGateway.php
│   └── WhatsAppGateway.php
├── Identity/
│   ├── IdentityManager.php
│   └── Aieos/
│       ├── AieosEntity.php
│       ├── AieosParser.php
│       └── AieosPromptCompiler.php
├── Jobs/
│   ├── ProcessMessageJob.php
│   └── SendMessageJob.php
├── Memory/
│   └── MemoryManager.php
├── Modules/
│   └── ModuleManager.php
├── Monitoring/
│   └── MetricsCollector.php
├── Security/
│   └── SecurityManager.php
├── Skills/
│   ├── AppBuilderSkill.php
│   ├── CalculatorSkill.php
│   ├── CalendarSkill.php
│   ├── EmailSkill.php
│   ├── ExecuteSkill.php
│   ├── FileSystemSkill.php
│   ├── HttpRequestSkill.php
│   ├── MemorySkill.php
│   ├── NotificationSkill.php
│   ├── SchedulerSkill.php
│   ├── ShoppingListSkill.php
│   ├── TimeSkill.php
│   ├── WebFetchSkill.php
│   └── WebSearchSkill.php
└── Tunnels/
    ├── TunnelManager.php
    ├── NgrokService.php
    ├── CloudflareTunnelService.php
    └── TailscaleService.php

resources/views/livewire/laraclaw/
├── dashboard.blade.php        # Tabbed Volt dashboard
├── chat.blade.php             # Streaming chat Volt component
├── conversations.blade.php    # Bulk actions Volt component
├── memories.blade.php         # Memory fragments Volt component
├── documents.blade.php        # Document upload Volt component
└── app-builder.blade.php      # Module builder Volt component

app/Modules/
└── {ModuleName}/
  ├── module.json
  ├── Models/
  └── Http/Controllers/

routes/modules/
resources/views/modules/

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Laraclaw is open-sourced software licensed under the MIT license.

• Inspired by OpenClaw and NullClaw
• Built with Laravel and Laravel AI SDK
• AIEOS specification by EntitAI