n8n-claw — Self-Hosted AI Agent

A fully self-hosted AI agent built on n8n + PostgreSQL + Claude. Talks to you via Telegram or HTTP API (Slack, Teams, custom apps), builds its own MCP tools, manages reminders and memory — all running on your own infrastructure.

Short Introduction

https://github.com/user-attachments/assets/10b7b93d-f482-47c1-a144-80a1b9d1be16

Contents

• What it does
• Architecture
• Installation
• Services & URLs
• Connect Claude Desktop, ChatGPT, Claude Code, Lovable & Cursor
• Webhook API & External Integrations
• MCP Skills Library
• Google Services (OAuth2)
• Expert Agents
• OpenClaw Integration
• Building custom MCP Skills
• Memory
• Knowledge Graph
• Project Memory
• Task Management
• Reminders & Scheduled Actions
• Media Support
• Heartbeat & Scheduled Actions
• Customization
• Alternative LLM Providers
• Switching from Telegram to WhatsApp
• HTTPS Setup
• Updating
• Postgres 17 Upgrade
• Troubleshooting
• WorkflowBuilder with Claude Code
• Stack

---

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)
• Browser automation — drives a real Chromium via Browser Use to perform agentic actions on websites: newsletter signups, contact forms, click flows, login-gated content. Sessions are pooled per domain so the agent stays logged in across calls (in-memory, lost on restart). Supports interactive 2FA: agent stops at the 2FA prompt, asks you for the code via Telegram, you reply with the TOTP code, agent enters it on the same live page and completes the login.
• 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:

Secure your Telegram bot

By default, your Telegram bot accepts messages from anyone who finds it. To restrict it to your chat only:

1. Open the n8n-claw Agent workflow in n8n
2. Click the Telegram Trigger node
3. Under Additional Fields, add Allowed Chat IDs
4. Enter your Telegram Chat ID (the one from setup)
5. Save the workflow

This ensures only you can talk to your agent. Without this, anyone on Telegram could message your bot and access the agent’s capabilities.

---

---

Triggering the agent

MCP clients can discover and execute the agent workflow automatically. When triggered, the agent runs its full pipeline — personality, memory, conversation history, AI reasoning with all tools — and returns the response.

Conversations are isolated per source and session, so MCP usage won’t interfere with Telegram chats.

Limitations

• 5-minute timeout — MCP-triggered executions have a hard 5-minute limit
• Text only — binary inputs (images, files) are not supported via MCP
• No client scoping — all connected MCP clients see the same exposed workflows

Requires n8n v2.2+. Workflow creation/editing requires v2.13+. See n8n MCP docs for details.

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

---

Stack

• n8n — workflow automation engine
• PostgreSQL — database
• PostgREST — auto-generated REST API
• Supabase Studio — database admin UI
• Kong — API gateway
• Claude (Anthropic) — LLM powering the agent
• Telegram — messaging interface
• SearXNG — self-hosted meta search engine (no API key needed)
• Crawl4AI — self-hosted web crawler, returns clean markdown (JS rendering)
• Email Bridge — lightweight IMAP/SMTP REST API for email integration
• File Bridge — temporary file storage for binary passthrough between agent tools
• Open-Meteo — free weather API (example MCP, no key needed)

---

License

MIT