n8n-node-configuration-official

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Node Configuration

n8n 节点配置

Each n8n node has its own parameter shape, often with conditional fields (parameter X only matters when parameter Y has value Z). Shapes evolve between versions. Guessing produces cryptic validation errors.

Don't guess, use the

get_node_types

tool.

每个n8n节点都有自己的参数结构，通常包含条件字段（即参数X仅在参数Y的值为Z时生效）。参数结构会随版本更新而变化。凭猜测配置会导致难以理解的验证错误。

不要凭猜测，使用

get_node_types

工具。

Non-negotiable

必须遵循的规则

Call
get_node_types
with discriminators (resource, operation, mode) before configuring a node. Without discriminators you get the generic shape, missing operation-specific parameters and required fields. Build against the exact shape. Don't guess from memory.

The live
get_node_types
output is the canonical parameter shape. The references in this skill cover patterns, gotchas, security rules, and decision-making (when to use which operation, why credentials over text fields, engine retry caps, etc.) not parameter names or field structures. If a reference example conflicts with what

get_node_types

returns, trust the tool. Markdown drifts; the type def is generated from the live source.

Never guess resource-locator or load-options values. When

get_node_types

shows a param with

@searchListMethod

@loadOptionsMethod

(Slack channels, Sheets tabs/docs, DB tables/columns, model lists, labels), resolve the real value with

explore_node_resources

(pass a

credentialId

from

list_credentials

) and use a returned

value

. If you already know the exact ID, use it; if several match and intent is ambiguous, ask the user. An invented ID validates but points at nothing. Exception:

toolWorkflow.workflowId

has no search method, resolve it via

search_workflows

and use

mode: 'id'

在配置节点前，务必传入鉴别器（resource、operation、mode）调用
get_node_types
工具。如果不传鉴别器，你将得到通用结构，会缺失操作专属参数和必填字段。要基于精确的参数结构进行配置，不要凭记忆猜测。

get_node_types
的实时输出是参数结构的权威来源。本技能中的参考内容仅涵盖模式、常见陷阱、安全规则和决策逻辑（比如何时使用何种操作、为何优先使用凭证而非文本字段、引擎重试上限等），不包含参数名称或字段结构。如果参考示例与

get_node_types

返回的内容冲突，请以工具结果为准。Markdown文档可能会过时，而类型定义是从实时源码生成的。

切勿猜测资源定位器或加载选项的值。 当

get_node_types

显示某个参数带有

@searchListMethod

或

@loadOptionsMethod

（如Slack频道、表格标签/文档、数据库表/列、模型列表、标签等）时，需通过

explore_node_resources

工具（传入

list_credentials

返回的

credentialId

）获取真实值，并使用返回的

value

。如果你已经知道确切的ID，可以直接使用；如果有多个匹配项且意图不明确，请询问用户。自行编造的ID可能通过验证，但实际指向空资源。例外情况：

toolWorkflow.workflowId

没有搜索方法，需通过

search_workflows

工具解析，并使用

mode: 'id'

。

Strong defaults

The flow for any new node

新建节点的流程

1. search_nodes(['<capability keyword>'])
   → returns matching node IDs + discriminators
2. Pick the right (resource, operation) for the task.
3. get_node_types([{ name: '...', resource: '...', operation: '...' }])
   → returns exact parameter shape including conditional fields
4. For any RLC / load-options param in that shape, ground the real value:
   explore_node_resources({ nodeType, version, methodName, methodType, credentialType, credentialId, currentNodeParameters? })
   → use a returned `value`. Don't invent IDs.
5. Build the node config from that shape.
6. validate_workflow → fix errors.
7. get_workflow_details → inspect the saved config; confirm parameters landed.
8. test_workflow with pinned data → confirm runtime behavior.

Skipping any step compounds the next. The most common skip is step 3, leading to "Cannot read property X" errors that are really "you didn't pass the discriminators."

1. search_nodes(['<能力关键词>'])
   → 返回匹配的节点ID + 鉴别器
2. 为任务选择合适的（resource, operation）组合。
3. get_node_types([{ name: '...', resource: '...', operation: '...' }])
   → 返回包含条件字段的精确参数结构
4. 对于该结构中任何资源定位器/加载选项类型的参数，获取真实值：
   explore_node_resources({ nodeType, version, methodName, methodType, credentialType, credentialId, currentNodeParameters? })
   → 使用返回的`value`，切勿编造ID。
5. 基于该结构构建节点配置。
6. validate_workflow → 修复错误。
7. get_workflow_details → 检查保存后的配置；确认参数已正确设置。
8. 使用固定数据运行test_workflow → 确认运行时行为符合预期。

跳过任何步骤都会加剧后续步骤的问题。最常被跳过的是步骤3，这会导致“无法读取属性X”的错误，而实际原因是“你未传入鉴别器”。

validate_node_config

as a side-channel

将

validate_node_config

作为辅助手段

validate_node_config([{ type, typeVersion, parameters, isToolNode? }])

runs the same Zod schema as

validate_workflow

on isolated node configs. Schema-level only; doesn't replace

validate_workflow

(still the publish gate). Cleaner signal for:

Iterating on a single node mid-build. Faster than re-running
```
validate_workflow
```
per tweak.
Small edits to an existing workflow. Wiring unchanged? Check the one node you touched; full validate before publish.
Debugging a misconfigured node. Per-parameter errors with no graph noise.

For tool subnodes (wired via

ai_tool

), set

isToolNode: true

so the correct

displayOptions

branch evaluates.

validate_node_config([{ type, typeVersion, parameters, isToolNode? }])

会在独立节点配置上运行与

validate_workflow

相同的Zod校验规则。仅针对Schema层面，不能替代

validate_workflow

（它仍是发布前的校验关卡）。适用于以下场景，能提供更清晰的反馈：

构建过程中迭代单个节点。 比每次调整后重新运行
```
validate_workflow
```
更快。
对现有工作流进行小幅修改。 连线未改动？只需检查你修改的那个节点；发布前再进行完整校验。
调试配置错误的节点。 提供逐参数的错误信息，无多余的图结构干扰。

对于通过

ai_tool

连接的工具子节点，需设置

isToolNode: true

，以便正确评估对应的

displayOptions

分支。

Operation-aware configuration

感知操作的配置方式

Most nodes have a top-level shape like:

{
  resource: '<thing being operated on>',   // 'message', 'spreadsheet', 'user', etc.
  operation: '<verb>',                      // 'send', 'append', 'lookup', etc.
  // ...operation-specific parameters
}

The

(resource, operation)

pair determines what other parameters exist (e.g., Slack

(message, send)

differs from

(user, info)

Pattern:

Set
```
resource
```
and
```
operation
```
first.
Re-fetch
```
get_node_types
```
with those discriminators if you didn't initially.
Configure the rest from the operation-specific shape.

大多数节点的顶层结构如下：

{
  resource: '<操作对象>',   // 'message'、'spreadsheet'、'user'等
  operation: '<操作动作>',                      // 'send'、'append'、'lookup'等
  // ...操作专属参数
}

(resource, operation)

组合决定了其他参数的存在（例如Slack的

(message, send)

与

(user, info)

参数结构不同）。

配置模式：

先设置
```
resource
```
和
```
operation
```
。
如果初始调用时没有传入这些鉴别器，需重新调用
```
get_node_types
```
并传入它们。
基于操作专属的参数结构配置其余内容。

Property dependencies: the subtle trap

属性依赖：隐蔽的陷阱

Some parameters depend on others in non-obvious ways:

A field is required only when another field has a specific value.
A field accepts different types depending on a mode.
A field's options come from another field's value.

Examples:

HTTP Request

authentication: 'genericCredentialType'

requires

genericAuthType

and

credentials

, but

'predefinedCredentialType'

requires a different shape.

Postgres

operation: 'executeQuery'

requires

query

, while

operation: 'select'

requires

table

and

columns

Slack
```
messageType: 'block'
```
enables block-builder fields absent from
```
messageType: 'text'
```
.

Always inspect via

get_node_types

for the specific operation. Don't reuse a config from a different operation and expect it to validate.

Options-from-another-field is a

@loadOptionsMethod

: resolve the live options with

explore_node_resources

(

methodType: 'loadOptions'

), passing prior selections via

currentNodeParameters

when the method depends on them (e.g. listing a spreadsheet's tabs needs

documentId

有些参数之间存在不明显的依赖关系：

某个字段仅在另一个字段为特定值时才是必填项。
某个字段接受的类型取决于模式设置。
某个字段的选项来自另一个字段的值。

示例：

HTTP请求节点中，

authentication: 'genericCredentialType'

需要

genericAuthType

和

credentials

参数，但

'predefinedCredentialType'

需要不同的参数结构。

Postgres节点中，

operation: 'executeQuery'

需要

query

参数，而

operation: 'select'

需要

table

和

columns

参数。

Slack节点中，
```
messageType: 'block'
```
会启用
```
messageType: 'text'
```
模式下没有的块构建字段。

务必通过

get_node_types

查看特定操作的参数结构。不要复用其他操作的配置并期望它能通过验证。

“选项来自其他字段”属于

@loadOptionsMethod

类型：需通过

explore_node_resources

工具（

methodType: 'loadOptions'

）获取实时选项，当方法依赖于之前的选择时，需通过

currentNodeParameters

传入已选值（例如列出表格标签需要

documentId

）。

Reference files

参考文档

Per-category gotchas. Read the file for the node type you're configuring:

File	When to read
`references/HTTP_NODES.md`	Configuring HTTP Request: auth, pagination, query/body parameters, retries
`references/WEBHOOK_NODES.md`	Configuring Webhook trigger or Respond to Webhook: body parsing, response shape, async patterns
`references/COMMS_NODES.md`	Slack, Gmail, Discord, email: credential types, message shapes, attachments
`references/DATABASE_NODES.md`	Postgres, MySQL, Mongo, Supabase: query vs operation, parameter binding, error handling
`references/AI_NODES.md`	AI Agent node config knobs: streaming, vision, `maxIterations` , retries on the model sub-node. Defers design (prompts, tools, memory, structured output) to `n8n-agents-official`
`references/TRIGGER_NODES.md`	Webhook, Schedule, Manual, Execute Workflow Trigger: input schemas, polling vs realtime
`references/SWITCH_FALLBACK.md`	Configuring a Switch node: unnamed outputs / missing fallback silently drop unmatched items
`references/MERGE_NODE.md`	Configuring a Merge node, or you see `useDataOfInput` , `numberOfInputs` , or branches converging

按分类整理的常见问题。配置对应类型的节点时，请阅读相关文档：

文档	阅读场景
`references/HTTP_NODES.md`	配置HTTP请求节点：认证、分页、查询/请求体参数、重试
`references/WEBHOOK_NODES.md`	配置Webhook触发器或响应Webhook节点：请求体解析、响应结构、异步模式
`references/COMMS_NODES.md`	Slack、Gmail、Discord、邮件类节点：凭证类型、消息结构、附件
`references/DATABASE_NODES.md`	Postgres、MySQL、Mongo、Supabase类节点：查询vs操作、参数绑定、错误处理
`references/AI_NODES.md`	AI Agent节点配置项：流式传输、视觉功能、 `maxIterations` 、模型子节点的重试。设计相关（提示词、工具、内存、结构化输出）请参考 `n8n-agents-official`
`references/TRIGGER_NODES.md`	Webhook、定时、手动、执行工作流触发器：输入Schema、轮询vs实时
`references/SWITCH_FALLBACK.md`	配置Switch节点：未命名输出/缺失回退会静默丢弃不匹配的项
`references/MERGE_NODE.md`	配置Merge节点，或遇到 `useDataOfInput` 、 `numberOfInputs` 、分支收敛场景时

Anti-patterns

反模式

Anti-pattern	What goes wrong	Fix
Building node config from memory of how the node looked last year	Parameter shape has drifted, validation fails with cryptic errors	Always `get_node_types` per session per node
Skipping discriminators in `get_node_types`	Get generic shape, miss operation-specific required fields	Always pass `resource` + `operation` (and `mode` where present)
Copying a node config from one operation to another and tweaking	Stale parameters trip validation, and conditional fields don't apply	Re-derive from the new operation's shape
Hardcoding tokens / credentials in node text fields	Leaks on export. See `n8n-credentials-and-security-official`	Always credentials
Not testing the node with `test_workflow` after configuring	Runtime errors only surface on real data	Always test with pinned data before publish

反模式	问题	修复方案
凭去年对节点的记忆构建配置	参数结构已更新，验证失败并抛出难以理解的错误	每次会话配置每个节点时都要调用 `get_node_types`
在 `get_node_types` 中跳过鉴别器	获取到通用结构，缺失操作专属的必填字段	务必传入 `resource` + `operation` （如有 `mode` 也需传入）
复制一个操作的节点配置并微调后用于另一个操作	过时参数触发验证错误，条件字段不生效	基于新操作的参数结构重新配置
在节点文本字段中硬编码令牌/凭证	导出时会泄露敏感信息。请参考 `n8n-credentials-and-security-official`	始终使用凭证管理
配置完成后不使用 `test_workflow` 测试节点	运行时错误仅在真实数据场景下才会暴露	发布前务必使用固定数据测试

n8n-node-configuration-official

Original

Translation

n8n Node Configuration

n8n 节点配置

Non-negotiable

必须遵循的规则

Strong defaults

推荐默认做法

The flow for any new node

新建节点的流程

`validate_node_config`
as a side-channel

将
`validate_node_config`
作为辅助手段

Operation-aware configuration

感知操作的配置方式

Property dependencies: the subtle trap

属性依赖：隐蔽的陷阱

Reference files

参考文档

Anti-patterns

反模式

n8n-node-configuration-official

Original

Translation

n8n Node Configuration

n8n 节点配置

Non-negotiable

必须遵循的规则

Strong defaults

推荐默认做法

The flow for any new node

新建节点的流程

validate_node_config as a side-channel

将validate_node_config作为辅助手段

Operation-aware configuration

感知操作的配置方式

Property dependencies: the subtle trap

属性依赖：隐蔽的陷阱

Reference files

参考文档

Anti-patterns

反模式

`validate_node_config`
as a side-channel

将
`validate_node_config`
作为辅助手段