What it does

Talk to your agent in natural language — it manages tasks, remembers context across conversations, builds API integrations, and proactively keeps you on track.

• Telegram chat — talk to your AI agent directly via Telegram
• Webhook API — call the agent from any external system via HTTP (Slack, Teams, Paperclip, custom apps)
• Enriched long-term memory — hybrid search (semantic + full-text + entity match, fused via RRF) with time decay, tags, entity tracking, source attribution, and category-based auto-expiry. Finds people by name, survives embedding API outages, naturally prefers recent context.
• Knowledge graph — automatically tracks people, companies, products, and events; multi-hop graph traversal reveals how everything connects
• Task management — create, track, and complete tasks with priorities and due dates
• Proactive heartbeat — automatically reminds you of overdue/urgent tasks
• Recurring actions — repeating tasks on any schedule ("check my emails every 15 minutes", "daily briefing at 8am")
• Smart background checks — monitoring tasks only notify you when something new is found
• Failure awareness — workflow errors are logged to memory and pushed to Telegram. Just ask "did anything fail today?" or "what was the error in the last background check?" and the agent explains in plain language — no more digging through n8n execution logs
• Expert agents — delegate complex tasks to specialized sub-agents (3 included, 100+ available from agent catalog across 12 categories)
• MCP Skills — install pre-built skills or build new API integrations on demand
• Smart reminders — timed Telegram reminders ("remind me in 2 hours to...")
• Scheduled actions — the agent executes instructions at a set time ("search HN for AI news at 9am")
• Web search — searches the web via built-in SearXNG instance (no API key needed)
• Web reader — reads webpages as clean markdown via Crawl4AI (JS rendering, no boilerplate)
• File passthrough — stores documents and photos from Telegram so Skills can use the originals (upload to Lexware, save to Nextcloud, etc.). Can also download files from the internet or cloud services and send them back to the chat.
• Project memory — persistent markdown documents for tracking ongoing work across conversations
• OpenClaw integration — delegate coding tasks to an autonomous AI agent that can build websites, apps, and run shell commands
• Extensible — add new skills and capabilities through natural language or from the skill catalog

Architecture

Telegram  ───────────────────────────────────┐
Webhook API (POST /webhook/agent)  ───────┐
  │                                     │
  └─────────────────▼─────────────────────┘
n8n-claw Agent (Claude Sonnet)
  ├── Task Manager        — create, track, complete tasks
  ├── Project Manager     — persistent project notes (markdown)
  ├── Memory              — save, search, update, delete long-term memories
  ├── Knowledge Graph     — track entities and relationships automatically
  ├── MCP Client          → calls tools on MCP skill servers
  ├── Library Manager     → install/remove skills from catalog
  ├── MCP Builder          → builds custom skills from scratch
  ├── Reminder            — timed reminders + scheduled actions
  ├── Expert Agent        → delegates to specialized sub-agents
  ├── Agent Library       → install/remove expert agents from catalog
  ├── Telegram Status     — sends progress updates during long tasks
  ├── HTTP Tool           — simple web requests
  ├── Web Search          — search the web (SearXNG)
  ├── Web Reader          — read webpages as markdown (Crawl4AI)
  └── Self Modify         — inspect/list n8n workflows
  │
  ├── Webhook caller? → JSON response to HTTP caller
  └── Telegram?      → Telegram Reply

Webhook Adapter (optional, connects external systems):
  💬 Slack Trigger     ──┐
  💬 Teams Trigger     ──┤
  🌐 Generic Webhook   ──┼── Map Input → POST /webhook/agent → Route Response
  🛠️ Custom Webhook    ──┘   (Set node — easy to customize, no code)

Background Workflows (automated):
  💓 Heartbeat              — every 5 min: recurring actions + proactive reminders + file cleanup
  🔍 Background Checker     — silent checks: only notifies when something new is found
  🧠 Memory Consolidation   — daily at 3am: summarizes conversations → long-term memory
  ⏰ Reminder Runner         — every 1 min: sends due reminders + triggers one-time actions
  🚨 Error Notification     — catches workflow failures: Telegram alert + logs to memory_long

Internal Services:
  📁 File Bridge            — temporary binary storage (documents, photos) for tool passthrough
  📧 Email Bridge           — IMAP/SMTP REST API for email integration

Installation

Want to run locally instead of on a VPS? See the Local Setup Guide for Docker + ngrok instructions (contributed by @salvodmt, tested on Debian 13).

What you need

• A Linux VPS (Ubuntu 22.04/24.04 recommended, also tested with Debian 13, 4GB RAM and 15GB Disk minimum)
• A Telegram Bot Token — open @BotFather in Telegram, send /newbot, follow the prompts, and copy the token it gives you
• Your Telegram Chat ID — send any message to @userinfobot and it replies with your numeric ID
• An LLM API Key — setup lets you choose your provider:
  • Anthropic (default) · OpenAI · OpenRouter · DeepSeek · Google Gemini · Mistral · Ollama (local, no key needed) · any OpenAI-compatible endpoint
• A domain name (required for Telegram HTTPS webhooks). No domain? You can use sslip.io — it turns your IP into a domain automatically (e.g. your server has IP 123.45.67.89, type 123-45-67-89.sslip.io), no DNS setup needed

Step 1 — Clone & run

git clone https://github.com/freddy-schuetz/n8n-claw.git && cd n8n-claw && ./setup.sh

The script installs everything automatically. It will ask you for:

• n8n API Key — generated in the n8n UI that opens during setup (Settings → API)
• Telegram Bot Token + Chat ID
• LLM API Key — choose your provider (Anthropic, OpenAI, OpenRouter, DeepSeek, Gemini, Mistral, Ollama, or OpenAI-compatible)
• Domain name (enables HTTPS via Let's Encrypt. Use sslip.io if you don't have one)
• Agent personality — name, language, communication style, custom persona

After that, setup handles everything else: Docker, database, credentials, workflows, activation.

Setup also asks about two optional features (you can skip both):

• Embeddings — enables semantic memory search (find memories by meaning, not just keywords). Supports OpenAI, Voyage AI, or Ollama. Without it, memory still works via keyword search.
• Voice messages — requires an OpenAI API key for Whisper transcription. If you already chose OpenAI for embeddings, the same key is reused. Without it, voice messages won't work — but photos, documents, and locations work fine.

Step 2 — Start chatting

All credentials are created and connected automatically by setup. Send a message to your Telegram bot — it's ready!

Webhook API — you can also interact with the agent via HTTP (for Slack, Teams, or custom apps):

curl -X POST https://YOUR-DOMAIN/webhook/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_WEBHOOK_SECRET" \
  -d '{"message": "Hello!", "user_id": "test-user"}'

The WEBHOOK_SECRET is shown at the end of setup output (also in .env).

Optional: extra workflows

The core agent and all background workflows are activated automatically. These optional workflows can be activated in the n8n UI if you need them:

| Workflow | Purpose | |---|---| | MCP Builder | Builds custom MCP skills on demand | | MCP: Weather | Example skill — weather via Open-Meteo (no API key needed) | | WorkflowBuilder