如何用 n8n 搭建 AI Agent：零基础完整教程 2026

TL;DR

如果你在搜"如何用 n8n 搭建 AI Agent"，直接答案是：将一个 AI Agent 节点连接到聊天模型（OpenAI、Claude 或本地 Ollama），挂载工具（HTTP 请求、Code 节点、数据库查询），Agent 就能自主调用这些工具完成任务，再用数据库节点添加可选记忆让 Agent 记住对话上下文。本教程带你走完全流程——从 Docker 自托管到部署一个能自动拉取 GitHub PR 并发送 Slack 摘要的 AI Agent——大约 45 分钟。

前置条件

• 一台安装了 Docker 的电脑（macOS、Windows、Linux 均可）
• 一个 OpenAI API Key（或 Anthropic Claude / Ollama 本地模型）
• 对 Web API 和 JSON 有基本了解（有帮助但不是必须）
• 不需要编程经验——n8n 的可视化编辑器处理所有逻辑

第一步：用 Docker 自托管 n8n（5 分钟）

自托管 n8n 让你免费获得无限次工作流执行、完全的数据隐私和社区节点访问权限。云版本免费套餐只允许 5 个活跃工作流。

创建 docker-compose.yml 文件：

version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_SECURE_COOKIE=false
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - DB_TYPE=sqlite
    volumes:
      - n8n_data:/home/node/.n8n
    restart: unless-stopped

volumes:
  n8n_data:

运行：

docker compose up -d

打开 http://localhost:5678，创建管理员账户，然后你就进入 n8n 了。

生产环境提示：真实部署时，将 DB_TYPE 切换为 postgresdb，并添加 N8N_ENCRYPTION_KEY（一个随机的 32 字符字符串）来加密存储的凭据。不设置的话，API Key 会以明文形式存储。

第二步：理解 AI Agent 节点架构

n8n 的 AI Agent 节点有四个核心组件，像一个真正的助手那样协同工作：

Agent 通过一个推理循环工作：接收输入 → 聊天模型决定调用哪个工具 → 工具执行 → 结果返回给模型 → 模型决定下一步或返回最终答案。这个循环持续进行，直到模型判断任务完成。

关键洞察：Agent 的质量更多取决于工具设计而非模型选择。一个设计良好、描述清晰、有适当错误处理的工具，效果会优于向顶级模型发送模糊的提示词。

第三步：构建你的第一个 AI Agent —— GitHub PR 摘要机器人

我们将构建一个 Agent：给定 GitHub 仓库名，拉取开放的 Pull Request 并发送摘要到 Slack。这教你三种基本模式：外部 API 调用、数据转换和结果输出。

3.1 创建工作流触发器

1. 在 n8n 中，点击添加工作流。
2. 添加Webhook 节点作为触发器。设置 HTTP 方法为 POST，响应模式为 Last Node。
3. Webhook 会给你一个测试 URL。我们将发送 JSON 数据如 {"repo": "n8n-io/n8n"}。

3.2 添加 AI Agent 和聊天模型

1. 拖入 AI Agent 节点（位于 Advanced AI 类别下）。
2. 设置 Agent 类型为 Tools Agent。
3. 拖入 OpenAI Chat Model 节点（或 Anthropic Claude / Ollama）。
4. 在 OpenAI 节点凭据中填入你的 API Key。
5. 将聊天模型连接到 AI Agent 的「Chat Model」输入。

3.3 创建 GitHub 工具

1. 添加 HTTP Request 节点。设置请求方法为 GET，URL 为：

1. 添加请求头：

Accept: application/vnd.github+json
User-Agent: n8n-ai-agent-tutorial

1. 将此 HTTP 请求节点连接到 AI Agent 的「Tools」输入。Agent 现在可以调用 GitHub API 了。

重要：给你的 HTTP 请求节点起一个描述性名称（如"拉取 GitHub Pull Requests"）。n8n 会把节点名当作工具描述发给 LLM。清晰的名称帮助模型决定何时使用该工具。

3.4 添加 Slack 输出

1. 添加 Slack 节点（发送消息）。用你的 Slack 工作区认证。
2. 设置频道为目标频道（如 #dev-updates）。
3. 在文本字段中写：

📊 *PR 摘要 — {{ $json.body.repo }}*

{{ $fromAI('用3个要点总结这些 Pull Request，包含标题、作者和状态。', $json.body) }}

_由 n8n AI Agent 生成，时间：{{ $now.format('YYYY-MM-DD HH:mm') }}_

1. 将 AI Agent 的输出连接到 Slack 节点。

3.5 测试工作流

1. 点击 Webhook 节点的监听测试事件。
2. 发送测试请求：

curl -X POST http://localhost:5678/webhook-test/你的webhook路径 \
  -H "Content-Type: application/json" \
  -d '{"repo": "n8n-io/n8n"}'

1. 检查你的 Slack 频道——应该能看到格式化的开放 PR 摘要。

第四步：添加记忆和多轮对话

上面的 Agent 是无状态的——每次调用都是全新开始。要打造真正的助手，需要添加记忆：

4.1 Window Buffer Memory（简单方案）

1. 拖入 Window Buffer Memory 节点。
2. 设置 Session Key 为 {{ $json.sessionId }}（或自定义标识符）。
3. 设置上下文窗口长度为 10（保留最近 10 条消息）。
4. 将其连接到 AI Agent 的「Memory」输入。

这会保留最近 10 条消息在上下文中。适合短会话，但工作流重启时会重置。

4.2 Postgres Chat Memory（持久化方案）

跨会话持久记忆：

1. 拖入 Postgres Chat Memory 节点。
2. 连接到 Postgres 数据库（或使用 n8n 内置 SQLite）。
3. 设置表名为 chat_history。
4. 当 Agent 回复时，整个对话会被保存。

有了记忆后，你可以追问"只显示上周的 PR"，Agent 会记住上一轮的仓库名。

第五步：部署到生产环境——安全与可靠性

5.1 配置 HTTPS

生产环境中，将 n8n 放在反向代理后面并启用 HTTPS。使用 Caddy：

n8n.yourdomain.com {
    reverse_proxy localhost:5678
}

将 N8N_HOST 更新为你的域名，N8N_PROTOCOL 更新为 https。

5.2 保护 API 密钥

始终使用 n8n 凭据——绝不在节点中硬编码 API Key。前往设置 → 凭据为 OpenAI、Slack、GitHub 等服务创建凭据条目，在节点中按名称引用它们。

5.3 错误处理

添加错误触发器节点来捕获故障：

1. 创建一个错误工作流，当任何工作流失败时给你发 Slack 私信。
2. 在主工作流设置中，将「错误工作流」指向此告警工作流。

5.4 速率限制

GitHub API 每小时允许 60 次未认证请求。生产环境：

1. 创建 GitHub Personal Access Token。
2. 在 n8n 中将其添加为 Header 凭据。
3. 在 GitHub HTTP 请求节点的认证设置中使用。

5.5 激活工作流

切换右上角的激活开关。n8n 启动 Webhook 监听器并保持运行。你的 AI Agent 现已上线。

实际扩展场景

基础 Agent 跑通后，可以用以下模式扩展：

故障排查

AI Agent 没有调用任何工具

原因：模型无法将用户请求匹配到任何可用工具。修复：（1）将工具节点重命名为更描述性的名称——"拉取 GitHub Pull Requests"优于"HTTP Request"。（2）在工具节点的「Description」字段添加描述。（3）检查模型是否支持 function calling（GPT-4o 和 Claude Sonnet 支持；旧模型可能不支持）。

记忆在两次调用之间没有保留

原因：会话密钥在请求之间发生变化。修复：在 Webhook 数据中使用一致的 sessionId，或为单用户 Agent 使用固定密钥。对于 Postgres Chat Memory，通过运行测试查询验证数据库连接正常。

工作流在处理大响应时超时

原因：模型生成了非常长的回复或 API 响应缓慢。修复：（1）在聊天模型节点中设置较低的 max_tokens（1024–2048 通常足够）。（2）在 HTTP 请求节点中添加超时设置。（3）对于有 50+ PR 的大型 GitHub 仓库，将 per_page 减少到 5。

Docker 容器不断重启

原因：端口冲突或权限问题。修复：（1）检查端口 5678 是否被占用：lsof -i :5678。（2）确保 n8n_data 卷有写入权限。（3）运行 docker compose logs n8n 查看错误信息。

OpenAI API 返回 401 未授权

原因：API Key 无效或已过期。修复：（1）在 platform.openai.com/api-keys 重新生成密钥。（2）检查使用额度和账单状态。（3）验证 n8n 凭据中的密钥没有多余空格。

Slack 消息显示原始 JSON 而非格式化文本

原因：$fromAI() 函数输出未被正确解析。修复：用 Code 节点包装提取 $json.output，或使用 {{ $fromAI('...').output }}（如果你的 n8n 版本支持表达式属性访问）。

相关教程

• 为 Claude Code 构建自定义 MCP 服务器
• Codex CLI 多 Agent v2：如何委托任务
• Cursor SDK 3.7：构建自定义 Agent 工具