n8n claw——自托管人工智能代理
基于n8n+PostgreSQL+Claude构建的完全自托管的AI代理。通过Telegram或HTTP API(Slack、Teams、自定义应用程序)与您交谈,构建自己的MCP工具,管理提醒和内存-所有这些都运行在您自己的基础设施上。
简短介绍
https://github.com/user-attachments/assets/10b7b93d-f482-47c1-a144-80a1b9d1be16
目录
- 它做什么
- 建筑
- 安装
- 服务和URL
- 连接克劳德桌面、聊天GPT、克劳德代码、可爱和光标
- Webhook API和外部集成
- MCP技能库
- 谷歌服务(OAuth2)
- 专业代理
- OpenClaw集成
- 构建自定义MCP技能
- 记忆
- 知识图谱
- 项目记忆
- 任务管理
- 提醒和计划行动
- 媒体支持
- 心跳和预定行动
- 定制
- 替代LLM提供商
- 从Telegram切换到WhatsApp
- HTTPS设置
- 更新
- Postgres 17升级
- 故障排除
- 使用Claude代码的工作流生成器
- 堆栈
______________________________________________________________________
它做什么
用自然语言与您的代理交谈-它管理任务,记忆对话中的上下文,构建API集成,并主动让您保持在正轨上。
- 电报聊天 --直接通过Telegram与您的AI代理交谈
- Webhook API --通过HTTP从任何外部系统调用代理(Slack、Teams、Paperclip、自定义应用程序)
- 丰富的长期记忆 --混合搜索(语义+全文+实体匹配,通过RRF融合),具有时间衰减、标签、实体跟踪、源归因和基于类别的自动过期功能。按姓名查找人员,在嵌入API中断后幸存,自然更喜欢最近的上下文。
- 知识图谱 --自动跟踪人员、公司、产品和事件;多跳图遍历揭示了一切是如何连接的
- 任务管理 --创建、跟踪和完成具有优先级和截止日期的任务
- 主动心跳 --自动提醒您逾期/紧急任务
- 经常性行动 --按照任何时间表重复任务(“每15分钟检查一次我的电子邮件”,“每天早上8点的简报”)
- 智能背景调查 --监控任务仅在发现新内容时通知您
- 故障意识 --工作流错误被记录到内存中并推送到Telegram。尽管问 *“今天有什么失败的吗?”* 或 *“上次背景调查中的错误是什么?”* 代理以通俗易懂的语言进行解释——不再需要挖掘n8n执行日志
- 专业代理商 --将复杂任务委托给专门的子代理(包括3个,100多个可从 代理商目录 横跨12个类别)
- MCP技能 -根据需要安装预先构建的技能或构建新的API集成
- 智能提醒 --定时电报提醒(“2小时后提醒我…”)
- 预定行动 --代理在设定的时间执行指令(“上午9点在HN搜索AI新闻”)
- 网络搜索 -通过内置的SearXNG实例搜索web(不需要API密钥)
- 网络阅读器 --通过Crawl4AI将网页读取为干净的标记(JS渲染,无样板)
- 浏览器自动化 --通过浏览器驱动真正的Chromium,用于在网站上执行代理操作:时事通讯注册、联系表单、点击流、登录门控内容。会话按域进行池化,因此代理在调用过程中保持登录状态(在内存中,重新启动时丢失)。支持 交互式2FA:agent在2FA提示处停止,通过Telegram询问您的代码,您用TOTP代码回复,agent在同一实时页面上输入代码并完成登录。
- 文件传递 --存储来自Telegram的文档和照片,以便Skills可以使用原件(上传到Lexware、保存到Nextcloud等)。还可以从互联网或云服务下载文件并将其发送回聊天室。
- 项目记忆 --用于跟踪对话中正在进行的工作的持久标记文档
- OpenClaw集成 --将编码任务委托给可以构建网站、应用程序和运行shell命令的自主AI代理
- 可扩展 --通过自然语言或技能目录添加新技能和能力
建筑
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______________________________________________________________________
安装
你需要的
- Linux VPS(建议使用Ubuntu 22.04/24.04,也使用Debian 13、4GB RAM和最低15GB磁盘进行测试)
- A. Telegram Bot令牌 --打开 @植物学家 在Telegram中,发送
/newbot,按照提示操作,并复制它给您的令牌 - 你的 Telegram聊天ID --向发送任何消息 @用户信息机器人 它会回复你的数字ID
- 一 LLM API密钥 --安装程序允许您选择提供商:
- Anthropic (默认)· 开放人工智能 · 开放路由 · 深度求索 · 谷歌双子座 · 米斯特拉尔 ·Ollama(本地,无需密钥)·任何与OpenAI兼容的端点
- A. 域名 (Telegram HTTPS网络挂钩需要)。没有域名?你可以使用 sslip.io --它会自动将您的IP转换为域(例如,您的服务器具有IP
123.45.67.89,类型123-45-67-89.sslip.io),不需要DNS设置
步骤1--克隆并运行
git clone https://github.com/freddy-schuetz/n8n-claw.git && cd n8n-claw && ./setup.sh该脚本会自动安装所有内容。它会问你:
- n8n API密钥 --在安装过程中打开的n8n UI中生成 *(设置→ API)*
- Telegram Bot令牌 + 聊天ID
- LLM API密钥 --选择您的提供商(Anthropic、OpenAI、OpenRouter、DeepSeek、Gemini、Mistral、Ollama或OpenAI兼容)
- 域名 *(通过Let's Encrypt启用HTTPS。使用 sslip.io 如果你没有)*
- 代理人个性 --姓名、语言、沟通风格、自定义角色
之后,安装程序会处理其他所有事情:Docker、数据库、凭据、工作流、激活。
安装程序还会询问两个可选功能(您可以跳过这两个功能):
- 嵌入 --启用语义记忆搜索(按意义而不仅仅是关键字查找记忆)。支持OpenAI、Voyage AI或Ollama。没有它,内存仍然通过关键字搜索工作。
- 语音信息 -Whisper转录需要一个OpenAI API密钥。如果你已经选择OpenAI进行嵌入,那么相同的密钥将被重用。没有它,语音信息将无法工作,但照片、文档和位置可以正常工作。
第二步——开始聊天
所有凭据都是由安装程序自动创建和连接的。向您的Telegram机器人发送消息——它已经准备好了!
______________________________________________________________________
Webhook API --您还可以通过HTTP与代理进行交互(适用于Slack、Teams或自定义应用程序):
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"}'这 WEBHOOK_SECRET 显示在设置输出的末尾(也在 .env).
可选:额外工作流
核心代理和所有后台工作流都会自动激活。如果需要,可以在n8n UI中激活这些可选工作流:
| 工作流程 | 目的 |
|---|---|
| MCP Builder | 按需构建自定义MCP技能 |
| MCP:天气 | 示例技能-通过Open-Meteo的天气(不需要API密钥) |
| WorkflowBuilder | 构建通用n8n自动化 *(要求 额外设置)* |
保护您的Telegram机器人
默认情况下,您的Telegram机器人接受来自以下来源的消息 任何人 谁找到了它。要将其仅限于您的聊天:
- 打开 n8n爪剂 n8n中的工作流
- 点击 电报触发器 节点
- 在...之下 附加字段,添加 允许的聊天ID
- 输入您的Telegram聊天ID(设置中的ID)
- 保存工作流
这确保了只有你可以与你的代理人交谈。如果没有这个,Telegram上的任何人都可以向你的机器人发送消息并访问代理的功能。
______________________________________________________________________
服务和URL
安装后,这些服务将运行:
| 服务 | URL | 目的 |
|---|---|---|
| n8n | http://YOUR-IP:5678 | 工作流编辑器 |
| Supabase工作室 | http://localhost:3001 (通过SSH隧道) | 数据库管理UI |
| Webhook API | https://YOUR-DOMAIN/webhook/agent | 代理HTTP端点(POST,需要X-API-Key头) |
| Webhook适配器 | https://YOUR-DOMAIN/webhook/adapter | 多系统适配器端点(POST) |
| 自定义Webhook | https://YOUR-DOMAIN/webhook/custom | 易于定制的适配器(设置节点,无需代码) |
| SearXNG | http://localhost:8888 (Docker内部) | 自托管网络搜索引擎 |
| Crawl4AI | 仅限Docker内部 | Web阅读器——JS渲染以清除标记 |
| 电子邮件桥 | http://localhost:3100 (Docker-internal) | IMAP/SMTP电子邮件REST API(用于电子邮件技能) |
| 文件桥 | http://localhost:3200 (Docker内部) | 用于工具之间二进制传递的临时文件存储 |
| 发布REST API | http://kong:8000 (仅适用于Docker-internal) | 适用于PostgreSQL的REST API |
访问Supabase工作室
Supabase工作室必须 localhost 仅(未公开披露)。要从浏览器访问它,请打开SSH隧道:
ssh -L 3001:localhost:3001 user@YOUR-VPS-IP然后打开 http://localhost:3001 在您的浏览器中。只要SSH会话运行,隧道就会保持打开状态。
______________________________________________________________________
连接克劳德桌面、聊天GPT、克劳德代码、可爱和光标
n8n claw可以直接从Claude Desktop、ChatGPT、Claude Code、Lovable、Cursor和其他MCP兼容工具中使用,使用n8n内置的实例级MCP服务器。无需额外的工作流程或代码。
连接后,您的MCP客户端可以与代理聊天(可以完全访问内存、网络搜索、技能、提醒和电报),触发其他工作流,甚至创建新的工作流。
设置
1.在n8n中启用实例级MCP
导航到 设置 (齿轮图标) >实例级MCP 并切换 启用MCP访问.
2.公开代理工作流程
点击 启用工作流,选择 n8n爪剂 工作流,然后单击 启用。添加一个好的描述,以帮助MCP客户端理解工作流的作用。
3.连接您的MCP客户端
Claude Desktop (easiest — OAuth, no token needed)
- 在实例级MCP页面上,单击 连接详细信息 并复制 OAuth URL
- 在Claude Desktop中,转到 文件>设置>连接器 > 添加自定义连接器
- 输入名称(例如您的代理名称)并粘贴OAuth URL,然后单击 添加
- 在连接器概述中,单击 连接 并在打开的浏览器窗口中进行授权
就是这样——Claude Desktop现在可以发现并使用您的代理。
ChatGPT (OAuth)
- 在ChatGPT中,转到 设置>应用程序>高级设置 并启用 开发者模式
- 返回并单击 创建新应用
- 输入一个名称(例如您的代理名称),粘贴您的n8n MCP URL
https:///mcp-server/http,选择 OAuth,接受风险警告,然后单击 创建
Claude Code (Access Token)
在实例级MCP页面上,单击 连接详细信息 > 访问令牌 标签。立即复制您的令牌——它将在以后的访问中被屏蔽。
claude mcp add --transport http n8n-claw https:///mcp-server/http \
--header "Authorization: Bearer "或添加到您的 .mcp.json:
{
"mcpServers": {
"n8n-claw": {
"type": "http",
"url": "https:///mcp-server/http",
"headers": {
"Authorization": "Bearer "
}
}
}
}Lovable (OAuth)
- 在《爱》中,前往 设置>连接器>个人连接器 然后单击 新建MCP服务器
- 输入一个名称(例如您的代理名称),粘贴您的n8n MCP URL
https:///mcp-server/http,然后选择 OAuth 作为身份验证 - 点击 添加并授权 并在浏览器中确认
Cursor / Other MCP clients
使用 OAuth URL 如果您的客户端支持OAuth,请查看连接详细信息,或 访问令牌 使用HTTP端点 https:///mcp-server/http。有关确切的配置格式,请参阅客户的MCP文档。
触发代理
MCP客户端可以自动发现和执行代理工作流。当被触发时,代理会运行其完整的管道——个性、记忆、对话历史、使用所有工具的人工智能推理——并返回响应。
每个源和会话的对话都是隔离的,因此MCP的使用不会干扰Telegram聊天。
局限性
- 5分钟超时 --MCP触发的执行有5分钟的硬性限制
- 仅文本 --MCP不支持二进制输入(图像、文件)
- 无客户范围 --所有连接的MCP客户端都看到相同的公开工作流
需要n8n v2.2+。 创建/编辑工作流需要v2.13+。看 n8n MCP文档 了解详情。
______________________________________________________________________
Webhook API和外部集成
n8n-claw公开了一个HTTP API,因此外部系统可以与代理进行对话-不需要Telegram。
直接Webhook API
任何可以发出HTTP请求的系统都可以直接调用代理:
POST {{N8N_URL}}/webhook/agent
Header: X-API-Key: {{WEBHOOK_SECRET}}
Content-Type: application/json
{
"message": "What is the weather in Berlin?",
"user_id": "my-app-user-123",
"session_id": "my-app:conv-456",
"source": "my-app",
"metadata": { "any": "data you want back" }
}答复(200):
{
"success": true,
"response": "The weather in Berlin is...",
"session_id": "my-app:conv-456",
"source": "my-app",
"metadata": { "any": "data you want back" }
}| 字段 | 必填 | 默认 | 描述 |
|---|---|---|---|
message | 是 | -- | 用户的消息 |
user_id | yes | -- | 唯一用户标识符 |
session_id | 没有 | api:{user_id} | 对话会话ID(用于历史记录) |
source | 没有 | api | 源标识符(出现在日志中) |
metadata | 没有 | {} | 任意数据——回复中的往返 |
代理人使用 session_id 和 user_id (带源前缀)用于对话历史和用户配置文件——与Telegram相同,只是前缀不同。
Webhook适配器(松弛、团队、Discord、回形针)
对于需要输入/输出映射(不同的消息格式、响应路由)的系统,请使用 Webhook适配器 工作流程。它在外部格式和代理的webhook API之间进行转换。
适配器附带了以下输入路径:
| 触发器 | 端点 | 默认状态 | 用例 |
|---|---|---|---|
| 通用Webhook | /webhook/adapter | 活动 | 回形针、Discord桥、API超级用户(带回退链的代码节点) |
| 自定义Webhook | /webhook/custom | 活动 | 您自己的应用程序——简单的Set节点,无需代码即可轻松定制 |
| 松弛触发器 | -- | 已禁用 | Slack工作区集成 |
| 团队触发 | -- | 已禁用 | Microsoft Teams集成 |
| Discord 的中文翻译是“不和谐”或“纷争”。 | /webhook/adapter (通过bot sidecar) | 选择加入 | Discord服务器——通过启用 setup.sh 提示,使用 discord-bridge 集装箱 |
每个触发器都有一个映射器节点,用于规范消息→ calls /webhook/agent → 通过以下方式将响应路由回正确的系统 metadata._responseChannel回形针有效载荷被自动检测,并得到一个专用的响应分支,该分支将代理的答案作为评论发布,并将问题标记为已完成。
启用Slack
- 创建Slack应用程序 在 api.slack.com/apps
- 添加Bot令牌作用域 在OAuth和权限下:
chat:write,channels:history,channels:read - 安装到工作区 并复制Bot令牌(
xoxb-...) - 在n8n中:创建Slack API凭据(Bot令牌+签名密钥)
- 启用Slack触发器+Slack回复 Webhook适配器工作流中的节点
- 激活Webhook适配器 工作流程
- 在Slack应用程序设置中:在事件订阅下添加Slack触发器的webhook URL
- 订阅机器人事件:
message.channels(公共频道),message.im(直接消息) - 邀请机器人 转到您的Slack频道(
/invite @YourBotName)
重新创建适配器工作流时,Slack触发器webhook URL会发生变化(例如。 setup.sh --force).每次重新安装后,更新Slack应用程序中的事件订阅URL。赋能团队
- 注册机器人 在 Azure 门户 (机器人框架)
- 创建应用ID+客户端密码
- 设置消息传递终结点 指向Teams触发器的webhook URL
- 在n8n中:创建Microsoft Teams OAuth2凭据
- 启用团队触发器+团队回复 Webhook适配器工作流中的节点
- 激活Webhook适配器 工作流程
启用Discord
与Slack和Teams不同,n8n不提供本地Discord触发器。n8n claw通过一个小型sidecar容器解决了这个问题(discord-bridge)它作为机器人连接到Discord的网关,并将消息转发到适配器。容器是可选的——只有在安装过程中启用Discord时,它才会被构建和启动。
- 创建Discord应用程序 在 confirm.com/developers/applications
- 添加机器人,启用 消息内容意图 在Bot设置下
- 复制Bot令牌
- 邀请机器人 到您的服务器
bot+applications.commands范围 - 跑
./setup.sh(或./setup.sh --force在现有安装上)--当被询问时 *“是否启用Discord作为附加聊天界面?”* 回答y并粘贴令牌 - 激活Webhook适配器 n8n中的工作流
就是这样。n8n本身没有Discord凭据——bot令牌只存在于sidecar容器中,通过以下方式设置 DISCORD_BOT_TOKEN 在 .env。sidecar将传入消息发布到 /webhook/adapter 并通过内部 POST /reply 端点,因此n8n从不直接与Discord的API对话。
未启用Discord的用户永远看不到额外的容器: discord-bridge 使用docker compose profiles: ["discord"] 标记,因此除非满足以下条件,否则不会建造或启动 COMPOSE_PROFILES=discord 已设置 .env (setup.sh为您完成的操作)。
启用回形针
回形针 是一个开源代理编排平台。n8n claw可作为开箱即用的回形针代理,无需在n8n中进行额外配置。
适配器自动检测回形针的有效载荷格式(runId + context),通过Paperclip API获取问题标题和说明,代理响应后:
- 将响应作为 评论 关于回形针问题
- 将问题状态设置为 完成
Paperclip中的设置:
- 展开回形针 与n8n claw位于同一服务器或网络上
- 创建公司 和一个 代理 随着
http适配器类型 - 配置代理的HTTP适配器:
{
"url": "https://YOUR-DOMAIN/webhook/adapter",
"method": "POST",
"headers": {
"X-API-Key": "YOUR_WEBHOOK_SECRET"
},
"payloadTemplate": {
"source": "paperclip"
}
}- 生成代理API密钥 在Paperclip中(n8n claw使用它来发布评论)
- 将占位符添加到
.env(或在工作流中硬编码):
- PAPERCLIP_INTERNAL_URL --回形针的内部URL(例如。 http://paperclip:3100 如果在同一个Docker网络上) - PAPERCLIP_AGENT_KEY -来自步骤4的代理API密钥
- 创建问题 在Paperclip中并将其分配给代理——心跳将自动触发工作流
Docker网络: 如果Paperclip在同一台服务器上运行,请将其连接到n8n claw的Docker网络(n8n-claw_n8n-claw-net)并使用容器DNS名称(paperclip:3100)而不是localhost.
添加自定义集成
最简单的方法——使用自定义Webhook(无代码):
- 打开 地图自定义输入 在Webhook适配器工作流中设置节点
- 调整字段映射以匹配应用程序的JSON结构:
- message → 包含用户文本的字段(例如。 $json.body.text) - user_id → 发送者标识符(例如。 $json.body.username) - session_id → 唯一对话ID - source → 应用程序的名称
- 向发送POST
/webhook/custom随着X-API-Key头球
高级--添加新触发器(适用于具有自定义响应路由的系统):
- 添加新 触发节点 在Webhook适配器工作流中
- 添加新 映射节点 (代码节点),输出:
{ message, user_id, session_id, source, metadata: { _responseChannel: "your-system" } } - 在中添加匹配的输出 路线响应 交换节点
- 添加一个 应答节点 对于您的系统
这 _responseChannel 元数据中的值告诉适配器将代理的响应路由到何处。
______________________________________________________________________
MCP技能库
43项预置技能 可从 技能目录 --只需一个聊天命令即可安装,无需编码。
“有哪些可用的技能?” “安装露天气象站” “删除露天气象站”
库管理器从GitHub获取技能模板,将工作流导入n8n,并自动注册新的MCP服务器。
技能有两种:
- 本土的 -n8n将REST API包装为MCP服务器(默认模式,大多数技能)。
- 桥 --注册a 现有外部MCP服务器 (例如DeepWiki、Zapier、自托管的Claude Code MCP)通过URL+可选的承载/报头身份验证直接进入代理。没有导入工作流,没有包装器代码。从v1.3.0开始支持。看 桥梁模板指南.
| 类别 | 示例 |
|---|---|
| 分析 | 谷歌分析 |
| 通讯 | Gmail、电子邮件(IMAP/SMTP)、OpenClaw |
| 创意 | 谷歌新一代媒体(Nano Banana Pro,Veo 3.1) |
| 娱乐 | TMDB电影、食谱、琐事 |
| 金融 | KontoFlux(开放银行),汇率,加密货币价格 |
| 知识 | 维基百科、OpenFoodFacts、OpenWebUI知识 |
| 语言 | DeepL翻译,词典 |
| 营销 | 谷歌广告 |
| 会议 | Vexa会议 |
| 网络 | 网站检查,IP地理定位 |
| 新闻 | 黑客新闻,NewsAPI |
| 生产力 | Todoist、Notion、GitHub、谷歌日历、谷歌云端硬盘、Nextcloud Files、Seafile、CalDAV、Vikunja、NocoDB CRM |
| 参考 | 国家信息、公共假日、时区/世界时钟 |
| 交通 | 德国铁路, 路线规划, 维也纳线路 |
| 实用程序 | PDF工具,二维码 |
查看完整目录 n8n爪形模板.
使用API键的技能: 某些技能需要API密钥(例如NewsAPI)。当你安装一个时,代理会通过Telegram向你发送一个安全的一次性链接。点击它,输入你的密钥——完成。密钥存储在数据库中,技能在运行时读取它。链接在10分钟后过期,只能使用一次。
“安装新闻API” → 代理发送链接以输入您的NewsAPI密钥 → 在表单中输入密钥→ 技能立即生效
您还可以稍后重新生成凭据链接:
“为新闻API添加凭据”
想创造自己的技能吗?看 模板贡献指南.
安全通知——技能证书以纯文本形式存储 通过凭证表单输入的API密钥当前已存储 未加密 在template_credentialsPostgreSQL中的表。这意味着: - 任何有权访问数据库的人都可以读取所有存储的API密钥 - Supabase工作室(localhost:3001,可通过SSH隧道访问)以纯文本显示凭据 - 泄露的VPS会暴露所有存储的API密钥 攻击者需要什么: 数据库和API都无法通过互联网访问。PostgREST仅在Docker内部网络上运行,PostgreSQL(端口5432)绑定到127.0.0.1。要读取凭据,攻击者需要SSH访问您的VPS——没有远程网络路径。 缓解措施: 安全的SSH访问(基于密钥的身份验证,无根密码,fail2ban),并尽可能使用权限最小的API密钥。 技能证书的静态加密已计划并正在进行中。
______________________________________________________________________
谷歌服务(OAuth2)
谷歌技能(Gmail、谷歌日历、谷歌分析、谷歌广告)使用OAuth2进行身份验证——代理通过Telegram处理整个流程,不需要n8n UI。
所有Google技能共享一组OAuth凭据(client_id / client_secret).你只需设置一次,每增加一项谷歌技能,就会自动重用它们。如果一项新技能需要额外的权限,代理会生成一个具有扩展范围的新同意链接。
设置
- 谷歌云控制台 — console.cloud.google.com
- 创建项目(或使用现有项目) - 启用您需要的API:Gmail API、Google Calendar API、Google Analytics Data API、Google Ads API - 首选 API和服务→ OAuth 授权界面: - 用户类型: 外部 (或谷歌工作区内部) - 将您的电子邮件添加为 测试用户 - 首选 API和服务→ 凭证→ 创建凭据→ OAuth客户端ID: - 类型: Web应用程序 - 授权重定向URI: https://YOUR-N8N-DOMAIN/webhook/oauth-callback - 复制 客户端ID 和 客户端密钥
- 安装谷歌技能 --问你的经纪人:
> “安装Gmail技能”
- 输入凭据 --代理发送两个安全表单链接(客户端ID+客户端密钥)。单击每个,粘贴值,提交。
- 授权 --代理生成谷歌同意链接。点击它,用你的谷歌帐户登录,授予权限。浏览器显示“授权成功”,代理通过Telegram确认。
- 完成 --这项技能已经准备好使用了。
可用的谷歌技能
| 技能 | 工具 | 范围 |
|---|---|---|
| Gmail | 搜索、阅读、发送、创建草稿、列出标签 | Gmail.readonly、Gmail.modify、Gmail.send |
| 谷歌日历 | 列表/创建/更新/删除事件,列表日历 | 日历,日历.只读 |
| 谷歌分析 | 运行报告、列出属性、实时数据 | Analytics.readonly |
| 谷歌广告(测试版) | 列出广告系列、广告组、统计数据、性能 | adwords |
Google Ads需要额外 开发者令牌 和 客户ID (通过单独的凭证表格输入)。
范围扩展
当你安装第二个谷歌技能(例如Gmail之后的日历)时,代理会检查现有的令牌是否已经覆盖了所需的范围。如果没有,它会生成一个新的同意链接,一次请求所有范围(现有+新)。您之前存储的刷新令牌将被替换为覆盖所有权限的令牌。
重要说明
- 测试模式:处于“测试”状态的Google OAuth应用程序具有在以下时间过期的刷新令牌 7天。如需永久使用,请将应用程序发布为“内部”(谷歌工作区),无需验证。
- 令牌刷新:访问令牌会自动刷新(到期前5分钟缓冲)。
- 共享凭据:所有谷歌技能都是一样的
client_id,client_secret,以及下面的令牌google-oauth命名空间。您只能验证一次。
______________________________________________________________________
专业代理
将复杂任务委托给专门的子代理。每个专家都有自己的人工智能代理,有一个专注的角色、工具(网络搜索、HTTP请求、网络阅读器、MCP),并且独立工作——然后主代理以自己的语气重新表述结果。
默认情况下包括三名专家:
| 代理 | 专业 |
|---|---|
| 研究专家 | 网络研究、事实核查、来源评估、结构化摘要 |
| 内容创建者 | 文案、社交媒体帖子、博客文章、营销文案 |
| 数据分析师 | 数据分析、模式识别、KPI解释、结构化报告 |
使用专家代理:
“用资源研究蒂罗尔州最好的徒步旅行路线” “写一篇关于我们新产品发布的Instagram帖子” “分析这些数字并给我一个总结”
代理会根据您的请求自动选择合适的专家,或者您可以明确地问:
“让研究专家来调查一下” “将此委托给内容创建者”
管理代理人:
“我有什么专业代理人?” “安装数据分析师” “删除内容创建者”
从安装更多专家 代理商目录 或者要求社区贡献新的。
100多名专家可用 从 代理商目录 涵盖12个类别:分析、传播、创意、开发、教育、人力资源、休闲、营销、运营、产品、研究和销售。
许多代理与MCP Skills配对以增强功能,例如,数据分析师与Google Analytics合作,或者代码审查员与GitHub集成。
状态更新: 在长时间运行的专家任务中,代理会向您发送Telegram进度更新,以便您知道发生了什么(例如“正在启动研究专家…”)。
______________________________________________________________________
OpenClaw集成
将n8n爪连接到 龙虾 实例并解锁一类全新的功能。OpenClaw是一个自主的人工智能代理,可以完全访问Linux系统——它可以编写代码、构建网站、部署应用程序、管理文件、运行shell命令,以及处理复杂的多步骤软件项目。
安装了OpenClaw技能后,n8n claw可以将任务委托给OpenClaw并获得结果:
“请OpenClaw为我们的新产品构建一个登录页面” “让OpenClaw创建一个Python脚本来监控我们的服务器正常运行时间” “将此发送给OpenClaw:重构auth模块并编写测试”
它是如何工作的:
- n8n-claw向OpenClaw的网关API发送消息(与OpenAI兼容)
- 对话是持久的——OpenClaw通过会话键记住消息中的上下文
- n8n claw使用可配置的调用者ID来标识自己,以便OpenClaw知道谁在说话
设置:
- 安装OpenClaw技能: *“安装openclaw”*
- 通过安全表单输入您的凭据:
- 网关URL — http://:18789。要查找端口,请在OpenClaw服务器上运行:
grep -A2 'gateway:' ~/openclaw/config.yaml | grep port- API代币 --在OpenClaw服务器上运行:
grep -A2 'gateway:' ~/openclaw/config.yaml | grep api_key- 主叫号码 --标识您的n8n爪实例的名称(例如“Greg(n8n claw)”)
- 确保您的n8n claw服务器可以访问OpenClaw的网关。检查
bind设置:
grep -A2 'gateway:' ~/openclaw/config.yaml | grep bind如果它说 "loopback",将其更改为 "lan" 并重新启动OpenClaw:
nano ~/openclaw/config.yaml # change bind: "loopback" → bind: "lan"- 开始委派任务
这将n8n claw从一个基于工作流的代理转变为一个通往完全自主编码代理的桥梁——结合n8n craw的优势(内存、提醒、任务管理、电报界面、MCP技能)和OpenClaw执行任意代码和构建软件的能力。
______________________________________________________________________
构建自定义MCP技能
对于技能目录中未涵盖的API,请让您的代理从头开始构建一个:
“为OpenLibrary API构建一个MCP服务器-按ISBN查找书籍”
MCP建设者将:
- 自动搜索API文档(通过SearXNG+Crawl4AI)
- 生成工作工具代码
- 部署两个新的n8n工作流(MCP触发器+子工作流)
- 在数据库中注册服务器
- 更新代理,使其了解新工具
______________________________________________________________________
记忆
代理有一个多层记忆系统——它记住你告诉它的事情,并随着时间的推移从你的对话中学习。
自动记忆: 代理人自己决定从你的对话中值得记住的内容(偏好、关于你的事实、决定)。无需采取任何行动。
手动记忆: 你也可以明确地要求它记住一些东西:
“记住,我更喜欢上午10点之前的早间会议” “记住我喝黑咖啡”
内存搜索: 相关时,代理会搜索其内存,为您提供上下文答案。它使用 混合搜索 --通过交互秩融合(RRF)融合的三种独立搜索策略:
- 语义搜索 -使用向量嵌入通过意义查找记忆(需要嵌入API密钥,在设置过程中配置)
- 全文搜索 --将精确单词与重音/变音标准化相匹配(
München火柴muenchen) - 实体匹配 --增强与你询问的人、公司或项目相关的记忆
如果嵌入API暂时不可用,代理会正常地返回到全文+实体搜索-无静默失败。
时间衰减 赋予最近的记忆一种自然的优势。旧的记忆不会被删除,但新的记忆在竞争同一个查询时排名更高。类别豁免确保了联系、偏好和决策永远不会衰减。
“你对我的咖啡偏好了解多少?” “关于服务器迁移,我们讨论了什么?”
内存更新和删除: 该代理可以纠正或删除存储的记忆,不再堆积相互矛盾的条目:
“实际上,我现在更喜欢茶”——更新现有的咖啡偏好,而不是创建一个重复的偏好 “忘记我喜欢早开会”--完全删除该条目
标签和实体跟踪: 每个内存都会自动标记英文小写关键字,并链接到命名实体(人、公司、项目等)。这使得过滤和交叉引用记忆更加有效。
自动到期: 记忆会根据其类型和重要性自动过期。联系信息、偏好和决定永远不会过期。一般记忆在90-180天后过期。这使内存保持干净,无需手动维护。
记忆巩固 每晚凌晨3点自动运行。它通过向量嵌入将当天的对话总结为简洁的长期记忆,提取标签和实体名称,并清理过期的条目。需要嵌入API密钥(OpenAI、Voyage AI或Ollama-在设置过程中配置)。
洞察——模式提取(v1.5.0): 同样的夜间跑步会进行第二次,将行为模式、沟通风格和反复出现的压力源提取到 category='insight' 回忆。新模式被标记 new, reinforced,或 contradicted 与过去7天相比。过时的见解被标记 metadata.outdated=true 而不是被删除——时间有效性,而不是破坏性覆盖。前3个主动见解在每次转弯时都会默默地加载到系统提示中,因此代理的行为会围绕你的实际工作方式而变化。
开放循环(v1.5.0): 半完成的想法(“我还需要检查X”,“不要忘记Y”)被捕捉为 category='open_loop' 回忆。心跳每24小时检查一次超过3天的未解决循环,并主动询问: *“几天前你想Y——发生了吗?”* 闭环将原始内容保留为审计跟踪(仅 metadata.closed=true 已添加)。
______________________________________________________________________
知识图谱
代理自动构建人员、公司、项目、事件及其关系的知识图,不需要明确的命令。
自动实体跟踪: 当你提到一个人、公司、项目或任何命名实体时,代理会在知识图中默默地创建它,并将其链接到相关实体。
“Stefan Huber是destination.one的首席执行官”——为Stefan Hube(个人)和destination.one(公司)创建实体,以及“管理”关系
关系映射: 代理跟踪实体之间的关系——谁在哪里工作,谁创建了什么,哪些产品属于哪家公司。
图遍历: 询问某人的连接,代理遍历图表以显示整个网络:
“Stefan Huber有什么关系?”
该代理显示了跨多个跃点的所有链接实体——公司、联合创始人、产品、活动。
链接到内存: 知识图中的实体会自动链接到相关的记忆,在回答问题时为代理提供更丰富的上下文。
______________________________________________________________________
项目记忆
使用持久项目文档跟踪多个对话中正在进行的工作。每个项目都是一个标记文件,代理会根据需要创建、读取和更新,就像你正在处理的每个主题的活笔记本一样。
创建项目:
“我正在做一个关于旅游业人工智能的演讲” “新项目:服务器迁移到Hetzner”
代理创建了一个包含目标、注释和打开项的结构化markdown文档。
检查项目:
“我有什么项目?” “演示文稿的状态如何?”
活动项目名称会自动显示给代理——它总是知道你在做什么。
更新项目:
“添加到演示文稿中:幻灯片3应显示统计数据” “更新服务器迁移:DNS现已配置”
代理读取当前文档,添加注释,并保存更新的版本。
归档:
“演示已完成”
将项目状态设置为 completed --它从活动列表中消失,但保留在数据库中。
______________________________________________________________________
任务管理
代理可以为您管理任务——只需用自然语言告诉它您需要什么。
创建任务:
“提醒我明天打电话给牙医” 创建任务:准备周五的演示文稿,优先级高 “我需要在星期六之前买杂货”
检查任务:
“我的任务是什么?” “显示过期任务” “任务摘要”
更新任务:
“将牙医任务标记为已完成” “取消杂货任务” “将演示优先级更改为紧急”
任务支持优先级(low, medium, high, urgent)、截止日期和子任务。
______________________________________________________________________
提醒和计划行动
代理支持三种类型的定时操作:
提醒事项 --在指定时间发送Telegram消息:
“30分钟后提醒我检查烤箱” “明天早上9点提醒我医生的预约” “周五下午3点设置提醒:提交报告”
计划行动 --代理在指定时间主动执行指令并发送结果:
“上午9点在Hacker News上搜索人工智能文章并列出” “查看明天早上7点柏林的天气预报,并给我发一份摘要”
重复操作 --按时间间隔、每天或每周重复预定的操作:
“每15分钟检查一次我的电子邮件” “每天早上8点给我做一次简报” “每周一和周五上午9点,总结最新的人工智能新闻”
重复操作通过自然语言进行管理——列表、暂停、恢复或删除:
“显示我的计划操作” “暂停邮件检查” “删除操作2”
还可以列出、编辑和删除一次性提醒:
“显示我的提醒” “将研讨会提醒移至周一上午10点” “删除租车提醒”
提醒和一次性预定行动由 提醒跑步者 (每分钟进行一次民意调查)。重复操作由执行 心跳 (每5分钟运行一次)。错过的提醒将在下次运行时自动发送。
______________________________________________________________________
媒体支持
该代理不仅能理解文本,还能直接在Telegram中发送语音消息、照片、文档或位置。
| 媒体类型 | 发生了什么 | 需要 |
|---|---|---|
| 语音信息 | 通过OpenAI Whisper转录,然后作为文本处理 | OpenAI API密钥 |
| 照片 | 通过OpenAI Vision(GPT-4o-mini)进行分析,将描述传递给代理。原始文件存储在File Bridge中以供以后使用。 | OpenAI API密钥 |
| 文件(PDF) | 通过n8n内置的PDF解析器提取的文本,传递给代理。原始文件存储在File Bridge中以供以后使用。 | --(内置) |
| 位置 | 转换为坐标文本后,代理使用上下文 | --(内置)进行响应 |
语音和照片分析 需要一个OpenAI API密钥(在安装过程中配置)。没有它,语音消息和照片就无法工作,但如果没有任何额外的API键,文档和位置就可以工作。
文件存储(二进制直通)
当您发送文档或照片时,代理会提取对话的文本/描述 和 将原始二进制文件存储在文件桥服务中。这意味着代理稍后可以将文件传递给MCP Skills,例如,将收据上传到Lexware或将照片保存到Nextcloud。
- 文件被临时存储(24小时)并自动清理
- 代理通过以下方式引用存储的文件
file_refID——LLM永远看不到二进制数据 - 支持文件上传的技能接受两者
file_ref(存储的文件)和file_url(外部URL) - 代理可以将文件从公共URL、云服务(Google Drive、Nextcloud)或任何生成文件的技能发送回Telegram聊天
- 云服务技能
download_file自动处理身份验证——代理下载文件,将其存储在文件桥中,并将其传递给Telegram
*\[发送语音信息\]* --自动转录并回答 *\[发送照片\]* --“你看到了什么?”——由GPT-4o-mini Vision分析,原始存储用于工具使用 *\[发送PDF文件\]* --提取和分析文本,原始存储以供工具使用 *\[共享位置\]* --代理以位置上下文进行响应
______________________________________________________________________
心跳和预定行动
心跳是每5分钟运行一次的后台工作流。它执行重复的计划操作并提供主动提醒。
重复操作
当您创建重复操作时,代理将决定如何通知您:
always--始终发送结果(例如上午简报、报告)。主代理以完整的个性、对话历史和所有工具执行任务。on_change--仅在发现新内容时通知(例如电子邮件监控、价格跟踪)。轻量级 背景检查器 以静默方式执行任务,仅在有实际要报告的内容时发送Telegram消息。
代理会根据您的请求自动选择正确的模式:
“每天早上8点给我做简报”→always(你总是想要简报) “每15分钟检查一次我的电子邮件”→on_change(仅通知新电子邮件)
运作原理
Heartbeat (every 5 min)
→ Load due actions from DB
→ For each action, check notify_mode:
'always' (e.g. briefing):
→ Main Agent executes task → always sends Telegram
'on_change' (e.g. mail check):
→ Background Checker executes task
→ Something new? → sends Telegram
→ Nothing new? → stays silent背景检查器是一个轻量级的子工作流程,使用Claude+工具(MCP技能、网络搜索、HTTP请求、网络阅读器),但没有个性或对话历史记录——快速且经济高效。
主动提醒
心跳还会检查逾期或紧急的任务,并向您发送简短的电报提醒,而无需您询问。
“启用心跳”/“禁用主动消息”
速率限制为每2小时一条消息(可配置)——无垃圾邮件。
______________________________________________________________________
定制
编辑 soul 和 agents 直接在Supabase Studio中的表格(http://localhost:3001 通过 SSH隧道)更改代理的个性、工具和行为——无需更改代码。
| 表 | 目录 |
|---|---|
soul | 代理个性(姓名、角色、氛围、边界)——加载到系统提示中 |
agents | 工具说明、MCP配置、内存行为——加载到系统提示符中 |
user_profiles | 用户名、时区、偏好(语言、早间简报) |
tasks | 任务管理(标题、状态、优先级、截止日期、子任务) |
projects | 项目文件(名称、状态、标记内容) |
reminders | 定时提醒+一次性任务(消息、时间、类型、交付状态) |
scheduled_actions | 重复操作(计划、指令、notify_mode、next_run) |
heartbeat_config | 心跳+早间简报设置(启用、last_run、间隔) |
tools_config | LLM提供程序配置,嵌入提供程序--由心跳+内存整合使用 |
mcp_registry | 可用的MCP服务器(名称、URL、工具) |
template_credentials | MCP模板的API密钥(通过凭证表格输入) |
credential_tokens | 用于安全凭证输入的一次性令牌(10分钟TTL) |
conversations | 完整聊天记录(基于会话) |
memory_long | 向量嵌入的长期记忆(语义搜索) |
memory_daily | 每日交互日志(用于内存整合) |
______________________________________________________________________
支持的LLM提供商
n8n claw完全与模型无关。在设置过程中,您可以选择LLM提供商,然后 所有工作流都是自动配置的 --不需要手动交换节点。
可用提供商
| 提供者 | 默认型号 | 凭据名称 | 备注 |
|---|---|---|---|
| 人为(默认) | claude-sonnet-4-6 | Anthropic API | |
| OpenAI | gpt-5.4 | OpenAI API | |
| OpenRouter | anthropic/claude-sonnet-4-6 | OpenRouter API | 通过统一的API访问任何模型 |
| DeepSeek | deepseek-chat | DeepSeek API | |
| 谷歌双子座 | gemini-3-flash-preview | Google Gemini API | |
| 米斯特拉尔 | mistral-large-latest | Mistral API | |
| 奥拉马 | glm-4.7-flash | Ollama | 本地,不需要API密钥 |
| OpenAI兼容 | *(您的选择)* | LLM API | 具有与OpenAI兼容的API的任何终结点 |
运作原理
setup.sh 在将LLM节点导入n8n之前,会自动修补每个工作流中的所有LLM节点,以匹配您选择的提供者。这包括:
- n8n爪剂 --主LLM节点
- MCP生成器 --代码生成LLM节点
- 子代理跑步者 --专家代理LLM节点
- 背景检查器 --监视LLM节点
心跳 和 记忆巩固 从以下位置读取LLM提供程序配置 tools_config 运行时的数据库表——这些也适用于任何提供者。
切换提供商
重新运行 ./setup.sh --force 并在提示时选择其他提供商。所有工作流都将使用新的LLM节点和凭据重新导入。
已知注意事项
- MCP生成器 使用您选择的模型进行代码生成。更强的模型(Claude Opus,GPT-5.4)比更小的模型产生更好的结果。
- 一些本地模型可能会在工具调用JSON前添加额外的文本。这是固定在 #13 --确保你使用的是最新版本。
经过社区测试的供应商
| 提供者 | 状态 | 备注 |
|---|---|---|
| llama.cpp(qwen coder next) | 正在工作 | 社区报道(讨论#6)--文本+MCP天气确认 |
| Ollama | 预计将发挥作用 | OpenAI兼容端点 localhost:11434/v1 |
测试了不同的提供商?让我们知道 讨论!
______________________________________________________________________
从Telegram切换到WhatsApp
n8n claw默认使用Telegram,但您可以通过替换n8n UI中的Telegram节点切换到WhatsApp。这需要更改8个节点上的3个工作流,不需要n8n之外的代码。
需求
- A. 元商业账户 使用WhatsApp Business API访问- Meta商务套件
- A. 经过验证的业务 在Meta上(审核可能需要1-5个工作日)
- A. 电话号码 在WhatsApp Business API注册(不是您的个人WhatsApp号码)
- 在n8n中配置的WhatsApp Business Cloud凭据--请参阅 n8n WhatsApp凭据文档
字段映射:Telegram→ WhatsApp
这两个平台使用不同的JSON结构。以下是字段的映射方式:
| 数据 | 电报路径 | WhatsApp路径 |
|---|---|---|
| 消息文本 | $json.message.text | $json.messages[0].text.body |
| 发送方标识 | $json.message.from.id | $json.contacts[0].wa_id |
| 聊天/会话ID | $json.message.chat.id | $json.contacts[0].wa_id (电话号码) |
| 语音消息 | $json.message.voice.file_id | WhatsApp音频媒体ID |
| 照片 | $json.message.photo.pop().file_id | WhatsApp图像媒体ID |
| 文件 | $json.message.document.file_id | WhatsApp文档媒体ID |
| 字幕 | $json.message.caption | $json.messages[0].image.caption (或 .document.caption) |
| 位置 | $json.message.location.latitude/longitude | $json.messages[0].location.latitude/longitude |
| 发送至 | chatId (数字) | 收件人电话号码(例如。 49151...) |
| DB会话前缀 | telegram:{chatId} | whatsapp:{phoneNumber} |
| DB用户前缀 | telegram:{userId} | whatsapp:{phoneNumber} |
要替换的节点
n8n爪代理(6个节点)
| 当前节点 | 用途 | 替换为 |
|---|---|---|
| 电报触发器 | 接收传入消息 | WhatsApp触发器 --更新“路由媒体类型”切换条件,以匹配WhatsApp的消息结构 |
| 电报回复 | 发送代理响应 | WhatsApp→ 发送消息 --将收件人设置为发件人的电话号码,而不是 chatId |
| 电报状态 | 长任务期间的进度更新(AI工具) | WhatsApp→ 发送消息 (配置为 工具节点) |
| 获取语音文件 | 下载语音信息进行转录 | HTTP请求 使用媒体ID调用WhatsApp媒体下载端点的节点 |
| 获取照片文件 | 下载照片进行视觉分析 | HTTP请求 调用WhatsApp媒体下载端点的节点 |
| 获取文档文件 | 下载文档进行文本提取 | HTTP请求 调用WhatsApp媒体下载端点的节点 |
心跳(1个节点)
| 当前节点 | 用途 | 替换为 |
|---|---|---|
| 发送电报 | 发送主动提醒+早间简报 | WhatsApp→ 发送消息 --更新 chatId 使用电话号码的参数 |
提醒运行程序(1个节点)
| 当前节点 | 用途 | 替换为 |
|---|---|---|
| 发送提醒 | 发送定时提醒 | WhatsApp→ 发送消息 --the chat_id 列在 reminders 表必须包含电话号码,而不是Telegram聊天ID |
要更新的代码节点
这 “规范消息” 主代理中的代码节点从电报触发器输出中提取消息数据。更新这些参考文献:
// BEFORE (Telegram)
const msg = $('Telegram Trigger').first().json.message;
const chatId = String(msg.chat.id);
const userId = String(msg.from.id);
const source = 'telegram';
// AFTER (WhatsApp)
const wa = $('WhatsApp Trigger').first().json;
const chatId = String(wa.contacts[0].wa_id);
const userId = String(wa.contacts[0].wa_id);
const source = 'whatsapp';同时更新 “格式化位置” 代码节点和引用的任何其他节点 $('Telegram Trigger').
数据库更改
更新这些值以使用电话号码而不是Telegram聊天ID:
| 表 | 字段 | 更改 |
|---|---|---|
user_profiles | user_id | whatsapp:{phone} 而不是 telegram:{chatId} |
conversations | session_id | whatsapp:{phone} 而不是 telegram:{chatId} |
reminders | chat_id | 电话号码而不是Telegram聊天ID |
heartbeat_config | -- | 更新 {{TELEGRAM_CHAT_ID}} 在心跳工作流中转换为电话号码 |
消息长度限制
Telegram允许每条消息包含4096个字符。代理将长消息拆分为4000个字符。WhatsApp也允许最多4096个字符的文本消息,因此现有的拆分逻辑无需更改即可工作。
媒体处理差异
WhatsApp媒体下载的工作方式与Telegram不同。您需要:
- 获取媒体URL:
GET https://graph.facebook.com/v21.0/{media-id}(带auth标头) - 从返回的URL下载文件
一旦你有了文件,现有的语音转录(Whisper)和照片分析(GPT-4o Vision)节点的工作原理是一样的——只是下载步骤发生了变化。
这是一种高级定制。如果你遇到问题,请进 讨论.
______________________________________________________________________
HTTPS设置
如果您在设置过程中提供了域,HTTPS将通过Let's Encrypt+nginx自动配置。这是默认设置,适用于大多数人。如果没有,您可以稍后添加:
DOMAIN=n8n.yourdomain.com ./setup.sh在运行此操作之前,请将域的DNS A记录指向VPS IP。如果你没有域名,你可以使用 sslip.io --只需使用 n8n..sslip.io 作为域(例如。 n8n.123.45.67.89.sslip.io).不需要DNS配置。
已经有反向代理了吗?
如果您正在运行自己的反向代理(Caddy、Traefik、另一台主机上的nginx等),安装程序将询问是否跳过内置的nginx+Let's Encrypt安装。回答 是 跳过-n8n仍将配置正确的HTTPS webhook URL,但TLS终止将留给您现有的代理。
您也可以在 .env 在运行安装程序之前:
SKIP_REVERSE_PROXY=true您的反向代理应将流量转发到 localhost:5678 (n8n)已启用WebSocket支持。
已知问题: 当你输入一个域并跳过nginx时,安装程序会设置N8N_URL=https://your-domain在.env.然后它尝试通过该HTTPS URL访问n8n API,但如果反向代理尚未将流量转发到n8n,则“等待n8n API…”步骤将失败,脚本将退出。 解决方法: 1. 打开.env并删除N8N_URL线 1. 重新运行./setup.sh--它将使用http://localhost:5678而是成功完成 1. 设置完成后,添加N8N_URL=https://your-domain回到.env1. 重新启动n8n:docker compose up -d确保您的反向代理将HTTPS流量转发到localhost:5678在使用该试剂之前。
安全说明: 在没有域的情况下,n8n在没有TLS和速率限制的普通HTTP上运行。这很好 本地安装 (家庭服务器、局域网、测试)。对于a 公共VPS,始终使用具有HTTPS的域,否则凭据将以未加密的方式传输,实例将暴露在互联网上。
______________________________________________________________________
更新
正常更新 --拉取代码+Docker镜像,重启服务。您的个性、证书和数据将被保留:
cd n8n-claw && ./setup.sh完全重新配置 --重新运行设置向导(个性、语言、时区、主动/被动、嵌入密钥)。您现有的数据和凭据将被保留,但您可以更改所有设置:
./setup.sh --force使用 --force 当您想更改代理的名称、语言、沟通方式或在主动/被动模式之间切换时。
______________________________________________________________________
Postgres 17升级(现有安装)
n8n爪船 PostgreSQL 17 默认情况下,对于新安装。如果您已经在PG15上安装了n8n爪,那么本节适合您——它将介绍一次性升级。(Supabase对PG15的平台支持将于2026年5月左右结束;PostgreSQL社区对PG15支持的EOL将于2027年11月结束。相应地计划,但不要惊慌。)
为什么这需要一个特殊的命令: Postgres主要版本更改了磁盘存储格式。简单的图像标签交换将拒绝从 FATAL: database files are incompatible with server。数据必须迁移到新格式。
方法: pg_dump PG15→ 新的PG17集群(通过独立启动 docker run 因此,suabase/postgres映像的内置init脚本可以创建标准角色)→ 恢复转储→ 切换到与PG17图像合成。我们使用它而不是就地使用 pg_upgrade 因为Supabase的官方升级工具与n8n claw不提供的完整自主机堆栈(保险库加密、数据库配置卷)紧密耦合。
要求:
- 至少 3×当前数据库大小+2 GB 可用磁盘空间(转储+备份+新集群+缓冲区)
- 运行前建议使用VM级快照(Hetzner/Vultr/等)
- 约3-5分钟的停机时间
运行升级:
sudo ./setup.sh --upgrade-pg17脚本:
- 飞行前检查:PG版本、磁盘空间、不兼容的扩展、复制插槽
- 将Docker命名的卷迁移到主机绑定挂载(如果尚未完成,则一次性)
- 在接触任何数据之前,请您确认
- 将PG15数据库转储到
./volumes/db/dump_pg15.sql - 将PG15数据目录重命名为
./volumes/db/data.bak.pg15(保留用于回滚) - 写
docker-compose.override.yml带有PG17图像标签 - 启动一个新的PG17集群(自动初始化被抑制;恢复处理架构)
- 恢复转储
- 应用升级后迁移
007_pg17_compat.sql - 与验证
SELECT version()行数
原始PG15数据目录保留为 ./volumes/db/data.bak.pg15 用于回滚。经过2-3天的验证后删除:
sudo rm -rf ./volumes/db/data.bak.pg15升级后,正常更新(./setup.sh, ./setup.sh --force, git pull)像往常一样工作——覆盖文件使PG17保持活动状态。中的默认图像标签 docker-compose.yml 将在稍后的版本中切换到PG17;覆盖文件将变得多余但无害。
回滚 (仅在删除备份之前需要):
docker compose down
sudo rm -rf ./volumes/db/data
sudo mv ./volumes/db/data.bak.pg15 ./volumes/db/data
sudo rm -f docker-compose.override.yml
docker compose up -d______________________________________________________________________
故障排除
代理没有响应Telegram消息? → 检查所有工作流是否 激活的 在n8n用户界面中
“凭证不存在”错误? → 安装程序会自动创建所有凭据,但如果显示⚠️ 警告任何凭据,请在n8n UI中手动添加→ 凭证→ New:
| 凭证 | 类型 | 关键字段 |
|---|---|---|
Supabase Postgres | Postgres | 主机: db,端口: 5432,DB: postgres,用户: postgres,密码: *(来自设置输出)*,SSL: disable |
Telegram Bot | 电报 | 机器人令牌: *(来自设置)* |
| LLM提供者 | *取决于选择* | API密钥: *(来自设置)* --凭据名称必须完全匹配(请参见 支持的LLM提供商) |
Webhook Auth | 标头身份验证 | 名称: X-API-Key,价值: *(来自.env的WEBHOOK_SECRET)* |
MCP生成器失败? → 确保MCP Builder中的LLM节点已选择您的LLM提供者凭据
代理显示错误的时间? → 重新运行 ./setup.sh --force 并设置正确的时区,或直接在中更新 user_profiles Supabase工作室的桌子
心跳不发信息? → 检查一下 heartbeat_config 有 enabled = true 为了 heartbeat (主动)或 morning_briefing。您可以通过聊天启用它: *“启用心跳”*
内存搜索不返回任何内容/矢量化:false? → 在中检查嵌入API密钥 tools_config 表(工具名称: embedding).如果没有有效的密钥,内存仍然可以工作,但会退回到关键字搜索。
DB空/Load Soul什么也不返回? → 重新运行种子: ./setup.sh (跳过已设置的配置)
MCP技能失败 ECONNREFUSED 127.0.1.1:443? → 许多云提供商(Hostinger等)将服务器主机名映射到 127.0.1.1 在 /etc/hosts。当n8n尝试调用自己的webhook URL时,它会解析到该地址,而不是真实的IP。修复:
# Find your real IP
curl -4 ifconfig.me
# Fix /etc/hosts — replace 127.0.1.1 with your real IP
sed -i 's/^127\.0\.1\.1\(.*\)/YOUR_REAL_IP\1/' /etc/hosts
# If your server uses cloud-init, also fix the template for persistence across reboots:
sed -i 's/^127\.0\.1\.1\(.*\)/YOUR_REAL_IP\1/' /etc/cloud/templates/hosts.debian.tmpl
# Restart n8n
docker restart n8n-claw日志:
docker logs n8n-claw # n8n
docker logs n8n-claw-db # PostgreSQL
docker logs n8n-claw-rest # PostgREST______________________________________________________________________
可选:带Claude代码的WorkflowBuilder
WorkflowBuilder工具允许您的代理使用Claude Code CLI构建复杂的n8n工作流。由于n8n在Docker内部运行,Claude Code节点连接到 宿主机 通过安装CLI的SSH。
1.安装社区节点
在n8n用户界面中→ 设置→ 社区节点→ 安装:
n8n-nodes-claude-code-cli2.在您的VPS主机上安装Claude Code
重要提示: 将其安装在VPS本身(主机)上, 不 Docker容器内部。
curl -fsSL https://claude.ai/install.sh | bash在主机的外壳环境中设置Anthropic API键(例如。 /root/.bashrc):
echo 'export ANTHROPIC_API_KEY=your_key_here' >> ~/.bashrc
source ~/.bashrc3.生成SSH密钥对
Claude Code节点在Docker内部运行,并通过SSH连接到主机。大多数VPS提供商默认禁用密码身份验证,因此建议使用基于密钥的身份验证。
# Generate a dedicated key pair (no passphrase)
ssh-keygen -t ed25519 -f ~/.ssh/n8n-claude-code -C "n8n-claude-code" -N ""
# Authorize it
cat ~/.ssh/n8n-claude-code.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys4.在n8n中创建SSH凭据
- 在n8n用户界面中→ 凭证 → 添加凭据
- 搜索 克劳德密码SSH (随社区节点一起提供)
- 配置:
- 主持人: 172.17.0.1 (这是Docker容器到达主机的方式) - 端口: 22 - 用户名: root (或安装了Claude Code的用户) - 身份验证: SSH私钥 - 私钥: 粘贴以下内容 ~/.ssh/n8n-claude-code
- 用名称保存
Claude Code Runner SSH(必须完全匹配)
5.激活工作流程
- 打开 工作流生成器 n8n中的工作流
- 点击 激活 (在右上角切换)
如果没有此设置,WorkflowBuilder工具将无法运行,但没有它,所有其他代理功能都可以正常工作。
______________________________________________________________________
堆栈
- n8n --工作流自动化引擎
- PostgreSQL --数据库
- PostgREST -自动生成的REST API
- Supabase工作室 --数据库管理UI
- 孔 -API网关
- 克劳德 (人类学)——LLM为代理人提供动力
- 电报 --消息传递接口
- SearXNG -自托管元搜索引擎(不需要API密钥)
- Crawl4AI --自托管网络爬虫,返回干净的markdown(JS渲染)
- 电子邮件桥 -用于电子邮件集成的轻量级IMAP/SMTP REST API
- 文件桥 --代理工具间二进制传递的临时文件存储
- 开放天气 -免费天气API(例如MCP,不需要密钥)
______________________________________________________________________
许可证
麻省理工学院
