如何在 VPS 上自建 n8n AI Agent：完整配置指南

n8n AI agent 的定义，以及它与链的区别

n8n AI agent 是一个单独的 AI Agent 节点，并在其上连接子节点：一个聊天模型、一个或多个工具，以及可选的记忆。您只需用自然语言说明目标，模型就会决定调用哪些工具以及调用顺序，直到能够生成答案为止。下面的所有内容，都是围绕这一概念配置这个节点。

链的工作方式正好相反。在 Basic LLM Chain 中，您决定执行步骤，模型只负责生成文本。在 agent 中，模型决定执行步骤，因此同一个问题今天可能只触发一次模型调用，明天却可能触发9次。这个差异决定了本指南中的所有设置。如果您刚开始接触这种循环机制，而不仅仅是接触 n8n 中的对应功能，建议先手动编写一次，再用节点组装它。因为节点隐藏了您将在本指南其余部分反复分析的确切过程。

本文假设 n8n 已在您控制的机器上通过 HTTPS 运行。如果尚未完成，请先阅读在 Docker 上自托管 n8n 并配置有效证书。这是因为您即将存储的 API key 需要该指南要求备份的加密密钥。对于非 agent 模式，包括 webhook 摘要器和定时分类器，请参阅Claude 和 n8n 工作流模式。

在信任本文中的任何字段名称之前，请先检查您的版本，因为 n8n 经常修改 AI 节点。

docker compose exec n8n n8n --version

Version 1.82.0 弃用了 agent-type 设置，改用 Tools Agent。旧版 v1 节点仍包含此设置；n8n 文档显示，该节点版本计划在 n8n 3.0 中移除。

第 1 步：选择触发器

对于对话代理，添加一个 Chat Trigger 节点。在构建期间关闭 Make Chat Publicly Available，这样只有编辑器的聊天面板可以访问它。代理完成并确定身份验证方式后，再将其打开。

Chat Trigger 会向代理传递一个名为 chatInput 的字段。第 3 步会用到这个名称。名称写错是首次运行最常见的失败原因。

对于无人值守的代理，请改用 Schedule Trigger 或 Webhook 节点。这两者都不会生成 chatInput，因此需要自行编写提示词。

第 2 步：模型凭据

在画布上放置一个 AI Agent 节点。n8n 会立即在其下方显示一个空的 Chat Model 连接器。在此处连接一个 Anthropic Chat Model 子节点。

在 platform.claude.com 的 Claude Console 中创建凭据，依次打开 Settings 和 API keys。密钥只显示一次。创建密钥时，Console 还会要求选择过期时间。无人值守的代理会在密钥过期当天停止工作，因此请将该日期记录在容易看到的位置。对于无人值守的代理，请使用限定到某个工作区的服务账户密钥，这样请求无需单独提供 workspace header。

API 使用量按 token 计费。截至 31 October 2026，具体付费方式取决于您的 Claude 方案。Max、Ultra 和 Team 方案包含每月 API 额度：Max 为 $100，Ultra 为 $200，Team 共享额度最高为 $500。您需要在 Max 或 Ultra 中打开 Settings > Billing，或在 Team 中打开 Organization settings > Billing，将 Console 组织关联到该方案，即可使用这些额度；无需在 Console 中添加付款方式。新订阅者在使用该方案 7 天后才能领取额度。未使用的额度会在每个计费周期结束时过期；年度方案则按月过期。包含的额度用完后，请求会继续消耗已购买的额度；自动充值可以购买更多额度，采用账单结算的组织则会收到超额使用费用。预付费组织没有剩余额度时，请求会停止；API 使用量不会计入您的 Claude 方案。Free、Pro 和 Enterprise 方案不包含每月 API 额度，因此这些方案的 API 费用独立于订阅费用结算。

应按代理选择模型，而不是按公司统一选择。只使用一个工具来查找信息并报告结果的代理，使用 Haiku 即可。当前版本 Haiku 5.5 截至 12 October 2026 的价格为：每百万输入 token $0.10，每百万输出 token $0.50。如果请求的 prompt 超过 100,000 tokens，价格会升至每百万输入 token $0.50、每百万输出 token $2.50；较长的记忆窗口和较大的工具结果都可能导致请求超过该限制。当代理使用多个工具并需要在这些工具之间进行规划时，应改用 Sonnet。需要避免的情况是：低价模型连续 4 次调用错误的工具，其成本可能高于高价模型正确调用一次。

在子节点的选项中设置 Maximum Number of Tokens。该选项限制模型生成的每次响应长度。如果保留较大的默认值，一次混乱的运行可能生成很长的答案并产生相应费用。

n8n 文档中有一个容易被忽略的注意事项：子节点中的表达式始终针对第一个输入项目解析，不会按项目分别解析。请将按项目变化的表达式放在根节点的 prompt 字段中。

步骤 3：代理接收的提示词

打开 AI Agent 节点。Source for Prompt (User Message) 参数有两个选项。

• Connected Chat Trigger Node 接收名为 chatInput 的传入字段。在 Chat Trigger 后使用时，应选择此选项。
• Define below 会显示 Prompt (User Message) 字段，您可以在其中填写静态文本或表达式。在 Schedule Trigger 或 Webhook 节点后使用时，应选择此选项。

如果前面连接的是 Webhook 节点，POST 请求体会存放在 $json.body 下，因此提示词字段如下所示。

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

步骤 4：为代理提供一个工具

n8n 文档要求至少将一个工具子节点连接到 AI Agent 节点，但当前节点代码（版本 3.1）实际上只会在缺少聊天模型时拒绝运行。无论如何，都应先配置一个工具，因为一个可正常工作的工具比四个配置不完整的工具更有价值；没有工具的代理只是成本更高的链。

将一个 HTTP Request 节点连接到代理的 Tool 连接器。按照配置普通 HTTP Request 节点的方式完成配置，然后先从 shell 测试该端点。

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

如果该 curl 命令返回错误或 HTML 登录页面，代理也会失败。此时错误信息可能看起来像模型问题，但实际原因是 URL 或身份验证问题。应在 shell 中修复，而不是在节点中修复。

工具的 Description 字段不是写给同事看的文档。模型会将它与工具名称和参数架构一起读取，以判断该工具是否相关。应直接说明工具返回的内容：“以 JSON 格式返回一个受监控服务当前为 up 还是 down，以及持续中断时长。”

要让模型填充请求的一部分，请使用 $fromAI() 表达式。该表达式仅适用于连接到 AI Agent 节点的工具，在 Code 工具中不可用。

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

参数依次为 key，然后是可选的 description、type 和 defaultValue。键的长度必须为 1 到 64 个字符，只能使用字母、数字、下划线和连字符。类型必须是 string、number、boolean 或 json 之一，默认值为 string。更完整的调用如下所示。

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

键只是提示，不是对现有数据的引用。$fromAI('service') 不会从任何位置读取名为 service 的字段。它告诉模型“生成一个值，并将其命名为 service”，模型会从对话、输入数据和其他工具结果中查找该值。在聊天工作流中，它也可能直接询问用户。

Web 搜索通常是第二个工具。由于它本质上也是一个 HTTP 端点，因此可以让同一个节点访问 您自己的 SearXNG 实例，而不是付费搜索 API；但必须将它返回的每个页面都视为不受信任的文本，因为这些内容现在已经进入提示词。

步骤 5：记忆，以及代理为何会遗忘

如果没有记忆子节点，每条消息都会从空白上下文开始。添加一个 Simple Memory 子节点，用于保存最近的对话。

它有两个参数。Session Key 用于标识对话，因此使用不同键的两个用户会获得彼此独立的历史记录。Context Window Length 指定会重新放入提示词中的历史交互数量。

Context Window Length 不仅影响质量，也直接影响成本，因为每次后续调用都会将记住的每轮交互作为输入令牌重新发送。对于消息频繁的代理，将窗口设为 20 意味着最早的消息会被重复计费 20 次。

n8n 以队列模式运行时，Simple Memory 无法在活跃的生产工作流中正常工作，因为它将历史记录存储在按工作流 ID 和会话 ID 索引的进程本地单例 Map 中，而各个 worker 不共享这块内存。在队列模式实例中，应改用 Postgres Chat Memory 子节点，并将其指向主进程和各个 worker 都能访问的数据库。

第 6 步：系统消息

打开 agent 的 Options，添加一条 System Message。作业描述应写在这里，这是整个工作流中影响最大的文本。

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

“Always call the status tool before answering” 在这里确实会发挥作用。如果没有这条指令，认为自己已经知道答案的模型可能会跳过工具调用，直接根据记忆回复；基础设施一旦发生变化，这种回复就会立即变得自信但错误。

代理为什么会循环，以及什么会阻止循环

Options 中还有 Max Iterations，默认值为 10。一次迭代就是一次模型调用，该调用要么请求工具，要么返回最终答案；工具结果会反馈到下一次调用。因此，一次代理运行不是一次 API 调用，而是最多 10 次调用，并且每次调用都会携带不断增长的完整对话作为输入。

请降低此值。大多数只使用一个工具的代理会在两次迭代内完成，将限制设为 3 或 4 次，就能把无限循环变成执行列表中可见的明确失败。

调试时，启用 Return Intermediate Steps。最终输出会包含代理执行过程中发出的工具调用。这样可以区分“模型从未调用工具”和“工具没有返回有用结果”。上线前请将其关闭，因为这些步骤对最终用户而言只是噪声。

从 shell 观察一次运行。

docker compose logs -f n8n

控制无人值守 Agent 的隐性消耗

Chat Trigger 后面的 Agent 有人在监控。当输出看起来不正确时，该人员可以停止它。Schedule Trigger 后面的 Agent 没有人监控。这里需要关注的是模型用量，而不是许可证费用，因为 Agent、工具和记忆节点都可在免费的 self-hosted 版本中运行，而 需要付费密钥的功能主要是团队协作和治理功能。完整说明请参阅 持续运行 VPS 上的 AI Agent 成本控制。以下 4 项设置可以解决大部分问题。

• 在模型子节点上限制 Maximum Number of Tokens，避免单次响应运行过久。
• 将 Max Iterations 设置为仍能完成任务的最小值。
• 控制工具响应的大小。某个工具如果返回包含 4,000 行的 JSON blob，全部内容都会进入下一次模型调用，并在同一次运行中继续进入之后的每次调用。
• 确认 Agent 是否确实需要 Schedule。每 5 分钟运行一次的任务每天会触发 288 次。单次运行的成本是多少，每天就要将该数值乘以 288。

迭代期间请取消发布工作流，或者至少记住当前生效的版本。配置了 Schedule Trigger 的已发布工作流会继续运行你上次发布的版本，而不是屏幕上显示的草稿，因为 n8n 会将编辑内容保留为草稿，直到你再次发布。

FAQ

为什么 AI Agent 节点拒绝执行？

先检查连接器。AI Agent 节点需要一个聊天模型子节点。如果未连接模型，它会在发起任何 API 调用前停止，并显示 “Please connect a model to the Chat Model input”。n8n 文档还要求至少连接一个工具子节点。因此，如果模型已连接但节点仍然拒绝执行，请连接一个工具，即使是简单工具也可以，然后再次运行。

Agent 会回答，但始终不调用我的工具。原因是什么？

几乎总是工具的 Description 字段有问题。模型通过读取描述来选择工具，因此像 “HTTP Request” 这样的描述无法说明工具何时适用。请重写描述，说明工具返回哪些数据以及适用于什么情况，然后在 System Message 中添加一行指示 Agent 在回答前调用该工具。

为什么同一个问题每次运行的费用不同？

因为模型会决定执行多少步。每次迭代都会重新发送截至当前的完整对话，包括之前的工具输出。因此，执行 4 次迭代的运行会按 4 次调用中的输入和输出令牌总量计费。Max Iterations 设置迭代次数上限，Return Intermediate Steps 则显示某次运行实际使用了多少步。

我的内存在编辑器中正常，但在生产环境中不工作。发生了什么变化？

检查实例是否以队列模式运行。Simple Memory 会将历史记录存储在进程本地的单例 Map 中，并以工作流 ID 和会话 ID 作为键；不同的 worker 进程不会共享该 Map。请改用 Postgres Chat Memory 子节点。它会将历史记录保存在所有 worker 共享的数据库中。