如何用n8n构建AI代理？2026零基础完整教程

TL;DR

如果你想构建一个能够搜索网页、读取邮件、查询数据库并自主决策的 AI 代理（Agent），又不想写几百行代码，n8n 提供了一个可视化的拖拽编辑器，将大语言模型（OpenAI、Claude、Gemini）与现实世界的工具连接起来。本教程将带你从零到一，在 60 分钟内构建一个可运行的 AI 代理，包括一个 RAG 文档问答机器人和一个多工具研究助手。

你将学到

• 如何在 5 分钟内用 Docker 在本地安装 n8n
• 如何将 OpenAI、Claude 或 Ollama 模型连接到 AI Agent 节点
• 如何为代理添加工具：网页搜索、计算器、HTTP 请求、代码执行
• 如何添加记忆功能，让代理记住对话上下文
• 如何构建 RAG（检索增强生成）代理，根据你的文档回答问题
• 如何通过 Webhook、定时任务或聊天界面触发代理
• 常见陷阱及解决方案

前置条件

• 一台安装了 Docker 的电脑（或 Node.js 18+ 用于 npm 安装）
• 至少一个 LLM 提供商的 API 密钥（OpenAI、Anthropic 或 Google AI Studio — 均提供免费额度）
• 对 API 概念有基本了解（不需要写代码）
• 每个部分需要 10-15 分钟的专注时间

第1步：用 Docker 安装 n8n

最快的本地部署方式是 Docker。打开终端运行：

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

这条命令：

• 下载 n8n 官方镜像
• 映射 5678 端口，通过 http://localhost:5678 访问编辑器
• 将工作流和凭证持久化到 ~/.n8n，容器重启后数据不丢失

看到 n8n ready on ::, port 5678 后，在浏览器打开 http://localhost:5678。创建一个账户（邮箱+密码）——这是你的本地实例，数据完全留在你的机器上。

替代方案：n8n Cloud。 如果你不想自托管，在 n8n.cloud 注册免费试用。编辑器完全一样，只是跳过 Docker 步骤。

替代方案：npm。 如果你有 Node.js 18+：

npx n8n

第2步：了解 n8n 编辑器

在构建代理之前，先熟悉界面：

1. 画布（中央）：可视化工作流构建器。将节点拖到上面并连接它们。
2. 节点面板（左侧）：所有可用节点，按类别分组 — AI、触发器、操作等。
3. 节点设置（右侧，点击节点后出现）：配置参数、凭证和选项。
4. 执行记录（左侧边栏）：查看过去的工作流运行记录，检查输入/输出和调试错误。

核心概念：每个工作流都以触发器节点开始。这是启动代理的入口——Webhook 调用、定时任务、聊天消息或手动点击。从触发器开始，数据通过箭头连接的操作节点流动。

你的第一个迷你工作流： 将「Manual Trigger」拖到画布上。添加一个「Code」节点，粘贴 return [{ json: { message: "Hello from n8n!" } }];，连接它们，点击「Execute Workflow」。你将在执行记录中看到输出。这就是基本模式：触发→处理→输出。

第3步：连接你的第一个大语言模型

你的 AI 代理需要大脑。n8n 通过基于凭证的连接支持多个 LLM 提供商。

添加 OpenAI 凭证：

1. 点击左下角头像 → Credentials → Add Credential
2. 搜索「OpenAI API」并选择
3. 粘贴你的 API 密钥（从 platform.openai.com/api-keys 获取）
4. 点击 Save

添加 Anthropic（Claude）凭证：

1. 同样路径：Credentials → Add Credential → 搜索「Anthropic API」
2. 粘贴 Anthropic API 密钥（从 console.anthropic.com 获取）
3. 保存

添加 Google AI（Gemini）凭证：

1. Credentials → Add Credential → 搜索「Google Gemini(PaLM) API」
2. 粘贴 API 密钥（从 aistudio.google.com 获取）
3. 保存

测试连接： 将「AI Agent」节点拖到新工作流画布上。点击它，在 Model 下拉菜单中选择「OpenAI Chat Model」。在 Credential 下，选择你刚创建的 OpenAI 凭证。将 Model 设为 gpt-4o。这确认了你的 LLM 连接正常——我们将在下一步构建完整的代理。

第4步：构建你的第一个 AI 代理——邮件摘要器

现在构建一个有用的工具：读取邮件（模拟）并生成摘要的代理。

工作流设置：

1. 触发器：将「Webhook」节点拖到画布上。这会生成一个唯一 URL；我们将用它向代理发送邮件。
2. AI Agent 节点：将「AI Agent」节点拖到 webhook 之后并连接。
3. 配置 AI Agent：
   • Model：OpenAI Chat Model → gpt-4o
   • System Prompt：你是一个邮件助手。简洁地总结邮件。返回：(1) 发件人，(2) 主要请求，(3) 紧急程度（低/中/高），(4) 建议回复草稿。摘要控制在 150 字以内。
   • Tools 和 Memory 暂时留空。
4. 输出：在末尾添加「Respond to Webhook」节点。这会将代理的摘要发送回调用 webhook 的人。

测试： 在 webhook 节点上点击「Listen for Test Event」，然后在另一个终端执行：

curl -X POST http://localhost:5678/webhook-test/YOUR-WEBHOOK-ID \
  -H "Content-Type: application/json" \
  -d '{"from":"boss@company.com","subject":"Q3报告周五截止","body":"你好，提醒一下Q3报告本周五下午5点前截止。请在周四下班前把草稿发给我审阅。谢谢。"}'

代理收到邮件 JSON，用 GPT-4o 按照你的指令处理，并返回带有紧急程度和建议回复的结构化摘要。在执行记录中，你可以看到 LLM 收到的（输入）和返回的（输出）完整内容。

第5步：为代理添加工具

普通 LLM 只能思考。要行动，它需要工具。n8n 的 AI Agent 节点允许你将子工作流作为工具附加，代理可以自主调用它们。

添加网页搜索工具：

1. 在 Credentials 中添加「SerpAPI」（或「Google Custom Search」）凭证
2. 在 AI Agent 节点设置中，点击 + Add Tool
3. 选择「SerpAPI」→ 设置为返回前 3 条结果
4. 代理现在可以搜索网页了

添加计算器工具：

1. 在 AI Agent 节点中，+ Add Tool → 选择「Calculator」
2. 代理现在可以做数学运算——在研究工作流中非常有用

添加 HTTP 请求工具：

1. + Add Tool → 选择「HTTP Request Tool」
2. 配置允许的域名（如 api.github.com、weather.com）
3. 代理现在可以调用任何 REST API 获取实时数据

构建研究助手代理： 有了网页搜索 + HTTP + 计算器，你的代理变成了研究助手。更新系统提示词：

你是一个研究助手。当被提问时：
1. 搜索网页获取相关信息
2. 如果需要数值计算，使用计算器
3. 如果需要实时数据，使用 HTTP 请求工具
4. 综合发现，给出清晰的答案并附上来源

现在测试：「当前比特币价格是多少？如果我在 2024 年初投资了 1000 美元，今天值多少？」代理会搜索网页获取价格，使用计算器，返回完整答案。

重要提示： n8n 限制代理工具调用次数，防止无限循环。在研究任务中将 AI Agent 节点的 Max Iterations 设为 10-15（越高越深入，但更慢更贵）。

第6步：为代理添加记忆

没有记忆的话，每条消息都被当作全新的对话。记忆让代理记住之前讨论过的内容。

简单记忆（窗口缓冲）： 在 AI Agent 节点设置的 Memory 区域，添加「Window Buffer Memory」节点。将 Context Window Length 设为 10（记住最近 10 条消息）。这非常适合聊天式代理。

高级记忆（Postgres 聊天记忆）： 如需跨会话的持久记忆：

1. 安装 Postgres 节点（n8n 已内置）
2. 在代理的 Memory 区域添加「Postgres Chat Memory」节点
3. 配置你的 Postgres 连接字符串
4. 代理现在将对话历史存储在数据库中——关闭浏览器，明天回来，它仍然记得

基于会话的记忆： 在 webhook 输入中添加「Session ID」字段，并配置记忆使用它。不同用户获得独立的对话历史。

测试记忆： 问代理「我叫 Alex。」然后在后续消息中问「我叫什么名字？」配置了记忆后，它回答「Alex。」没有记忆时，它说「我不知道。」

第7步：构建 RAG 代理——根据你的文档回答问题

RAG（检索增强生成）让代理能够搜索你自己的文档，并根据内容回答问题。这是客服机器人、知识库问答和法律文档分析的基础。

搭建 RAG 管线：

1. 添加向量存储：

   • 在 Credentials 中添加「Qdrant」（qdrant.io 免费云层）或「Pinecone」凭证
   • 或使用内置的「In-Memory Vector Store」进行测试（数据在重启时重置）

2. 创建文档摄入工作流：

   • 触发器：「Manual Trigger」
   • 节点：「Read Binary Files」→ 指向一个包含 PDF、markdown 或文本文件的文件夹
   • 节点：「Default Data Loader」→ 将文档分割成块
   • 节点：「Embeddings OpenAI」→ 将文本块转换为向量
   • 节点：「Vector Store」（Qdrant/Pinecone/In-Memory）→ 存储向量

   运行此工作流一次以索引你的文档。

3. 创建问答工作流：

   • 触发器：「Chat Trigger」（在 http://localhost:5678/chat 提供聊天界面）
   • 节点：「AI Agent」
     • Model：gpt-4o 或 claude-sonnet-4-20250514
     • + Add Tool → 「Vector Store Tool」→ 选择你的 Qdrant/Pinecone 存储
     • System Prompt：你是一个知识渊博的助手。当被提问时，先在向量存储中搜索相关文档块，然后根据找到的内容回答。如果文档中没有答案，诚实说明。始终注明信息来源于哪个文档。
   • 节点：AI Agent 输出连接回 Chat Trigger

4. 测试： 上传你的公司手册、产品文档或研究论文。提出领域特定的问题。代理检索相关片段并生成准确、有引用的答案。

性能提示： 生产环境使用 Qdrant 或 Pinecone（持久化、快速）。In-Memory 适合测试，但重启后数据丢失。

第8步：部署和触发你的代理

如果没人能访问，你的代理就毫无用处。以下是三种最常见的触发方式：

1. Webhook 触发（API 端点）： 你的代理获得一个唯一 URL。从任何应用 POST JSON 到它——你的网站、Slack 机器人、移动应用或另一个 n8n 工作流。非常适合将 AI 集成到现有产品中。

curl -X POST https://your-n8n-instance.com/webhook/abc123 \
  -H "Content-Type: application/json" \
  -d '{"question": "总结最新的 n8n 发布说明"}'

2. 定时触发（cron）： 按定时器运行你的代理。示例：每周一上午 9 点，搜索行业新闻 API，总结发现，并通过邮件发送摘要。使用「Schedule Trigger」节点配合 cron 语法：0 9 * * 1（每周一上午 9 点）。

3. 聊天触发（内置界面）： 「Chat Trigger」节点提供一个即用型聊天界面。与团队成员分享 URL、嵌入 iframe 或用于内部工具。界面支持流式响应（实时逐字输出）、文件上传和对话历史。

生产环境提示：

• 在 Docker 环境中设置 N8N_SECURE_COOKIE=true 以启用 HTTPS
• 使用 nginx 反向代理配合 SSL 进行公网访问
• 如果暴露到互联网，启用身份验证（基本认证或 OAuth）
• 监控 token 使用：n8n 在执行记录中显示每次运行的 token 数量
• 在 LLM 提供商设置消费限额，防止意外账单

故障排除

「AI Agent 节点显示 No model selected」 → 进入 AI Agent 节点设置，在「Model」下拉菜单中选择模型。你可能需要先添加凭证（第3步）。

「Tool call failed: 401 Unauthorized」 → 你的 API 密钥无效或已过期。进入 Credentials，找到相关凭证并更新密钥。点击凭证设置中的「Test」进行测试。

「Agent 循环不停」 → 如果任务确实需要更多步骤，增加 Max Iterations。但如果代理卡住了，你的系统提示词可能太模糊。添加明确指令：「找到答案后直接输出，不要再次搜索。」

「重启后记忆消失」 → 你使用的是 Window Buffer Memory（仅内存）。切换到 Postgres Chat Memory 以获得持久性。确保 Postgres 卷在 Docker 中已挂载。

「重启后向量存储为空」 → 你使用的是 In-Memory Vector Store。切换到 Qdrant（免费云层）或 Pinecone。切换后重新索引文档。

「OpenAI 限流错误」 → 免费层有严格的速率限制（GPT-4o-mini 每分钟 3 次请求）。升级到付费层（最低 $5）或添加重试逻辑。在 OpenAI 节点中，启用「Retry on Fail」设置 3 次尝试和 5 秒延迟。

「Docker 容器立即退出」 → 检查日志：docker logs n8n。常见原因：5678 端口已被占用。将端口映射改为 -p 5679:5678 或停止冲突进程。

相关教程

• Claude Code 教程：2026 零基础完全指南
• OpenAI Codex CLI 教程：多代理工作流
• 如何选择 AI 编程助手：Cursor vs Copilot vs Windsurf
• 用 Ollama + n8n 构建本地 AI 代理（无需 API 密钥）