n8n-claw

n8n-claw 是一个全自托管 AI Agent 系统，以 n8n 为工作流引擎、PostgreSQL 为数据底座、Claude 为默认 LLM，通过 Docker Compose 一键部署于自有 Linux VPS。系统通过 Telegram 聊天或 HTTP Webhook API 与用户交互。

核心能力#

记忆与知识

• 混合搜索增强长期记忆：语义 + 全文 + 实体匹配，RRF 融合，支持时间衰减、标签、实体追踪、来源归属与分类自动过期；嵌入 API 故障时降级为关键词搜索
• 知识图谱：自动追踪人物、公司、产品和事件，多跳图遍历揭示关联
• 项目记忆：持久化 Markdown 文档，跨对话跟踪进行中工作
• 记忆整合：每天凌晨 3 点自动将对话摘要写入长期记忆

任务与自动化

• 任务管理：创建、跟踪、完成任务，支持优先级和截止日期
• 主动心跳：每 5 分钟自动检查并提醒过期/紧急任务
• 周期性动作：任意计划重复任务（如"每 15 分钟检查邮件"）
• 智能后台检查：静默运行，仅在发现新内容时通知
• 智能提醒与定时动作：定时 Telegram 提醒 + 到期时间执行指令（每 1 分钟检查）
• 故障感知：工作流错误自动记录到记忆并推送 Telegram 告警，可用自然语言查询

技能与代理

• 专家代理：复杂任务委托给专业化子代理（内置 3 个，目录提供 100+ 跨 12 类别）
• MCP 技能：安装预建技能或通过 MCP Builder 按需构建新 API 集成
• OpenClaw 集成：委托编码任务给自主 AI Agent（构建网站、应用、执行 shell 命令）

信息获取与处理

• Web 搜索：内置 SearXNG 实例（无需 API Key）
• Web 阅读器：Crawl4AI 将网页转为干净 Markdown（支持 JS 渲染）
• 文件传递：存储 Telegram 文档和照片供技能使用，可从互联网/云服务下载文件并返回聊天
• 语音消息：OpenAI Whisper 转录（可选）

架构概览#

核心调用链路：Telegram / Webhook API → n8n-claw Agent (Claude Sonnet) → Task Manager / Project Manager / Memory / Knowledge Graph / MCP Client / Expert Agent / HTTP Tool 等模块。

后台工作流：

• Heartbeat（每 5 分钟）：周期性动作 + 主动提醒 + 文件清理
• Background Checker：静默检查，仅在有新发现时通知
• Memory Consolidation（每天凌晨 3 点）：对话摘要 → 长期记忆
• Reminder Runner（每 1 分钟）：发送到期提醒 + 触发一次性动作
• Error Notification：捕获工作流失败 → Telegram 告警 + 记录到 memory_long

内部服务：File Bridge（临时二进制文件存储）、Email Bridge（IMAP/SMTP REST API）。数据层以 PostgreSQL 为唯一数据库，通过 PostgREST 自动生成 REST API，Kong 作为 API 网关，Supabase Studio 提供管理 UI。记忆搜索实现为 PLpgSQL 函数，采用 RRF 融合三路检索结果。Docker Compose 编排全部服务。

集成与扩展#

• Google 服务 OAuth2 支持
• WhatsApp 替代 Telegram 支持
• Webhook 适配器：Slack Trigger / Teams Trigger / Generic Webhook / Custom Webhook 映射
• 外部客户端：Claude Desktop、ChatGPT、Claude Code、Lovable、Cursor
• 可选工作流（需在 n8n UI 手动激活）：MCP Builder、MCP: Weather、WorkflowBuilder

部署与配置#

前置条件：Linux VPS（推荐 Ubuntu 22.04/24.04）、Telegram Bot Token + Chat ID、LLM API Key（支持 Anthropic/OpenAI/OpenRouter/DeepSeek/Gemini/Mistral/Ollama）、域名（或 sslip.io 自动生成）。最低配置 4 GB RAM / 15 GB 磁盘。

一键安装：

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

安装脚本交互式引导配置 n8n API Key、Telegram 凭证、LLM API Key、域名、Agent 人格（名称/语言/风格/自定义 persona），以及可选嵌入模型和语音转录。安装完成后直接通过 Telegram 发消息即可使用。

Webhook API 端点：POST /webhook/agent，认证方式 X-API-Key Header，请求体包含 message 和 user_id 字段。

MIT 许可，489+ commits，46 releases，最新版本 v1.5.0。