N8n Operator

n8n 工作流助手 - 通过 REST API 设计、创建、修改和管理 n8n 工作流。适合：自动化工程师、DevOps、流程编排。

Install

openclaw skills install @lujun2508/n8n-operator

n8n 工作流助手

通过 n8n REST API 设计、创建、修改和管理工作流。无需 MCP，纯 REST API 调用即可完全操控 n8n。

元信息

Name: n8n-operator
Version: 2.0.0
Author: AI-generated for OpenClaw
License: MIT
Dependencies: n8n 2.x 实例 + API Key
Tested on: n8n 2.14.0 (Docker, 2026-04-14)

n8n 2.x 关键差异（实测验证，必须遵守）

以下规则经过真实 n8n 2.x 实例验证，违反任一条都会导致 API 报错。

active 是只读字段 — 创建/更新时不传 active
tags / staticData 是只读字段 — 创建时不传
shared / activeVersion / pinData 是只读字段 — PUT 更新时不传
激活用专用端点 — POST /api/v1/workflows/{id}/activate（body: {}）
PUT 是全量替换 — 只传 name/nodes/connections/settings，否则 must NOT have additional properties
PATCH 不支持 — n8n 2.x 返回 PATCH method not allowed
Webhook lastNode 模式 — responseMode: "lastNode" 时，最后一个节点返回值自动作为 HTTP 响应，不要加 respondToWebhook 节点
激活后等待 1-2 秒 — 再触发 Webhook，确保路由注册完成

何时激活

当用户请求以下操作时，自动激活此 Skill：

创建/修改/删除 n8n 工作流
激活/停用/执行 n8n 工作流
查看 n8n 工作流列表或执行记录
添加节点、连接节点
设计自动化流程
任何涉及 n8n 的请求

前置条件

环境变量

text

N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=<your-api-key>

获取 API Key：n8n 界面 → Settings → API → Create an API Key

认证方式

所有 API 请求必须携带：

text

X-N8N-API-KEY: <N8N_API_KEY>
Content-Type: application/json

连通性检查

bash

curl -s -o /dev/null -w "%{http_code}" -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/workflows"

200 → 正常 | 401 → Key 无效 | 000 → 网络不通

核心工作流

Agent 必须严格遵循以下 4 阶段：

阶段 1：理解需求

确认工作流目的和功能
识别触发方式（Webhook / Schedule / Manual）
列出节点和数据流向
确认后进入下一阶段

阶段 2：规划设计

从 workflow-patterns.md 选择架构模式
绘制节点连接图
从 node-templates.md 选择节点配置
规划错误处理策略
展示设计方案，等待确认

阶段 3：逐步构建

text

Step 1: 创建空骨架 → 获取 workflow_id
Step 2: 逐个添加节点（每次 1-3 个）
Step 3: 建立节点连接
Step 4: GET 验证完整工作流
Step 5: 激活（用户确认后）

阶段 4：验证交付

确认已激活
提供 Webhook URL
展示测试结果
记录 workflow_id

API 速查

基础 URL

text

{N8N_BASE_URL}/api/v1

工作流管理

操作	方法	端点
列表	`GET`	`/workflows?active=true&limit=50`
详情	`GET`	`/workflows/{id}`
创建	`POST`	`/workflows`
更新	`PUT`	`/workflows/{id}`（全量替换）
删除	`DELETE`	`/workflows/{id}`
激活	`POST`	`/workflows/{id}/activate`
停用	`POST`	`/workflows/{id}/deactivate`
执行	`POST`	`/workflows/{id}/execute`

凭证管理

操作	方法	端点
列表	`GET`	`/credentials`
创建	`POST`	`/credentials`

执行记录

操作	方法	端点
列表	`GET`	`/executions?workflowId={id}&status=error&limit=20`
详情	`GET`	`/executions/{id}`
重试	`POST`	`/executions/{id}/retry`

常用 curl 示例

bash

# 列出所有工作流
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/workflows?limit=50"

# 获取单个工作流
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/workflows/123"

# 激活
curl.exe -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" -d "{}" "$N8N_BASE_URL/api/v1/workflows/123/activate"

# 停用
curl.exe -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/workflows/123/deactivate"

# 删除
curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/workflows/123"

# 手动执行
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" -d '{"data": {"key": "value"}}' "$N8N_BASE_URL/api/v1/workflows/123/execute"

Windows 注意： PowerShell 的 curl 是 Invoke-WebRequest 别名，用 curl.exe 调用真正的 curl。

节点数据结构

json

{
  "parameters": {},
  "id": "unique-uuid",
  "name": "Node Display Name",
  "type": "n8n-nodes-base.xxx",
  "typeVersion": 1,
  "position": [250, 300],
  "credentials": {},
  "disabled": false
}

关键规则：

type 始终用完整格式 n8n-nodes-base.xxx
id 用 UUID v4
name 既是显示名称，也是 connections 中引用的 key
建议位置间距：x=220, y=200

连接数据结构

json

{
  "SourceNodeName": {
    "main": [
      [
        { "node": "TargetNodeName", "type": "main", "index": 0 }
      ]
    ]
  }
}

三层嵌套：

text

{源节点} → {输出类型} → [[{目标列表}]]

常见模式：

线性（A→B→C）：

json

{"A":{"main":[[{"node":"B","type":"main","index":0}]]}},
{"B":{"main":[[{"node":"C","type":"main","index":0}]]}}

分支（IF→true/false）：

json

{"IF":{"main":[[{"node":"True","type":"main","index":0}],[{"node":"False","type":"main","index":0}]]}}

并行（A→B+C→D）：

json

{"A":{"main":[[{"node":"B","type":"main","index":0},{"node":"C","type":"main","index":0}]]}}

n8n 表达式语法速查

在 parameters 中使用 ={{ }} 嵌入动态值。

变量	用途	示例
`$json`	当前节点输入	`{{ $json.email }}`
`$json.body`	Webhook 请求体	`{{ $json.body.data }}`
`$json.query`	URL 查询参数	`{{ $json.query.page }}`
`$node["Name"].json`	引用指定节点输出	`{{ $node["HTTP"].json.data }}`
`$now`	当前时间	`{{ $now.toISO() }}`
`$env`	环境变量	`{{ $env.MY_VAR }}`
`$input.first()`	第一个输入项	`{{ $input.first().json.name }}`

Webhook 陷阱： POST 请求体在 $json.body 下，不是直接在 $json 下。

HTTP Request 节点正确配置（实测关键）

发送 JSON body 的正确配置：

json

{
  "parameters": {
    "sendBody": true,
    "specifyBody": "json",
    "jsonParameters": false,
    "jsonBody": "={{ JSON.stringify({key: 'value'}) }}"
  }
}

关键：jsonParameters: false 是必须的！设为 true 直接崩溃。

参数	值	说明
`sendBody`	`true`	启用请求体
`specifyBody`	`"json"`	JSON 格式
`jsonParameters`	`false`	必须为 false
`jsonBody`	`"={{ ... }}"`	用表达式传递

Gateway Cron 自动触发 n8n Webhook

当需要 OpenClaw 定时自动触发 n8n 工作流时：

方法：直接编辑 jobs.json 文件

text

路径：C:\Users\lujun\.openclaw\cron\jobs.json

在 jobs.json 中添加 cron 任务，通过 curl.exe POST 触发 n8n webhook URL。

关键经验：

isolated session 才能正常执行完整流程（主 session 会跳过 system-event）
直接编辑文件比 CLI/API 更可靠
已配置过的 webhook 路径不要反复问用户，直接查历史记录

微信公众号 API 限制速查

通过 n8n 调用微信公众号草稿 API 时的限制：

限制项	字节数	中文数	说明
title	≤ 20字节	≤ 10个	超过报 45003
digest	≤ 54字节	≤ 25个	超过报 45004
thumb_media_id	不能为空	—	先上传封面获取

access_token 有效期 7200 秒，每次发草稿前重新获取，不缓存复用。

错误处理策略

工作流级错误处理

json

{
  "settings": {
    "executionOrder": "v1",
    "errorWorkflow": "error-handler-workflow-id"
  }
}

节点级错误处理

json

{
  "name": "HTTP Request",
  "continueOnFail": true
}

Error Trigger

json

{
  "type": "n8n-nodes-base.errorTrigger",
  "typeVersion": 1
}

工作流设计原则

核心原则：防静默失败

1. 幂等性

用什么字段判断重复？（唯一 ID / 时间戳+业务ID）
重试不产生重复记录

2. 可观测性

生成 run_id 贯穿全程
记录每个关键节点状态

3. 重试 + backoff

1s → 2s → 4s 递增间隔
最大 3 次，超过 → 人工审核队列

4. No Silent Failure

关键计数/阈值不达标 → 立即停止并告警

设计检查清单

Agent 操作规范

必须遵守

先确认再操作 — 设计方案展示给用户
逐步构建 — 每步 1-3 个节点
每次修改后验证 — GET 确认
使用描述性节点名称
记录 workflow_id
先查后建 — 避免重复

禁止事项

不跳过设计阶段直接创建
不在 connections 中使用节点 ID（必须用 name）
不硬编码凭证密码
不跳过连通性检查
不修改正在运行的工作流（先停用）
不使用 n8n-nodes-base.function（v1，已弃用），用 n8n-nodes-base.code（v2）

完整示例：Webhook Echo

json

{
  "name": "Webhook Echo",
  "nodes": [
    {
      "id": "a1",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [0, 0],
      "parameters": {
        "httpMethod": "POST",
        "path": "echo",
        "responseMode": "lastNode",
        "responseData": "lastNode",
        "options": {}
      }
    },
    {
      "id": "a2",
      "name": "Process & Respond",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [250, 0],
      "parameters": {
        "jsCode": "return [{ json: { received: $json.body, processed: true, time: new Date().toISOString() } }];"
      }
    }
  ],
  "connections": {
    "Webhook": { "main": [[{ "node": "Process & Respond", "type": "main", "index": 0 }]] }
  },
  "settings": { "saveManualExecutions": true, "executionOrder": "v1" }
}

激活 + 测试：

bash

# 创建（自动获取 id）
# 激活（等 1-2 秒）
curl.exe -s -X POST -H "X-N8N-API-KEY: %N8N_API_KEY%" -H "Content-Type: application/json" -d "{}" "%N8N_BASE_URL%/api/v1/workflows/{id}/activate"

# 触发
curl.exe -s -X POST -H "Content-Type: application/json" -d "{\"hello\":\"world\"}" "%N8N_BASE_URL%/webhook/echo"

常见问题排查

问题	原因	解决
401	API Key 无效	重新生成
400 `active is read-only`	传了 `active`	不传，用 POST /activate
400 `tags is read-only`	传了 `tags`	不传
400 `must NOT have additional properties`	PUT 传了额外字段	只传 name/nodes/connections/settings
405 `PATCH method not allowed`	n8n 2.x 不支持	用 PUT 全量替换
500 `Unused Respond to Webhook node`	lastNode 模式下用了 respondToWebhook	删掉，用 Code 节点返回
Webhook 404	激活后立即触发	等 1-2 秒
Wait 节点导致激活失败	Wait for Callback 配置问题	用 Code + setTimeout 替代
HTTP Request 崩溃	`jsonParameters: true`	改为 `false`
微信 45003	title 超字节	title[:10]
微信 45004	digest 超字节	digest[:25]
微信草稿无封面	thumb_media_id 为空	先上传获取 media_id
Webhook 路径 404	用了 path 参数而非 webhookId	用 webhookId 触发

实战教训汇总

❌ `fs` 模块被屏蔽导致文件写入失败

解决： 用 ReadWriteFile 节点 + Binary 数据，详见 desktop-write.md

❌ Wait 节点导致激活失败

解决： 用 Code 节点 + await new Promise(r => setTimeout(r, 5000)) 替代

❌ HTTP Request jsonParameters

解决： 必须设为 false，true 直接崩溃

❌ 微信 API 字节限制

解决： title[:10] / digest[:25]，每次发草稿前重新获取 token

❌ PUT 后节点消失

解决： PUT 全量替换，必须包含全部节点

❌ Webhook URL 格式

解决： n8n 2.x 用 {webhookId} 触发，不是 path 参数

❌ 同一问题试错超过 3 次

解决： 停下来搜索文档/社区，分析根因，针对性解决

试错规则

同一问题试错超过 3 次 → 必须停止：

搜索文档/社区找类似问题
剖析错误根本原因
制定针对性方案
验证后记录

性能与监控

健康检查

bash

ACTIVE=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/workflows?active=true" | jq ".data | length")
FAILED=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_BASE_URL/api/v1/executions?status=error&limit=100" | jq "[.data[] | select(.startedAt > (now - 86400 | todate))] | length")
echo "Active: $ACTIVE | Failed(24h): $FAILED"

Python 工具

bash

python3 scripts/n8n_api.py list-workflows --active true --pretty
python3 scripts/n8n_api.py list-executions --limit 10 --pretty
python3 scripts/n8n_optimizer.py analyze --id <id> --pretty
python3 scripts/n8n_tester.py validate --id <id> --pretty

参考文件

node-templates.md — 30+ 常用节点 JSON 模板
workflow-patterns.md — 6 种经典架构模式
desktop-write.md — n8n 写入 Windows 桌面文件（2026-04-21 实测）

N8n Operator

Install

n8n 工作流助手

元信息

n8n 2.x 关键差异（实测验证，必须遵守）

何时激活

前置条件

环境变量

认证方式

连通性检查

核心工作流

阶段 1：理解需求

阶段 2：规划设计

阶段 3：逐步构建

阶段 4：验证交付

API 速查

基础 URL

工作流管理

凭证管理

执行记录

常用 curl 示例

节点数据结构

连接数据结构

n8n 表达式语法速查

HTTP Request 节点正确配置（实测关键）

Gateway Cron 自动触发 n8n Webhook

微信公众号 API 限制速查

错误处理策略

工作流级错误处理

节点级错误处理

Error Trigger

工作流设计原则

核心原则：防静默失败

1. 幂等性

2. 可观测性

3. 重试 + backoff

4. No Silent Failure

设计检查清单

Agent 操作规范

必须遵守

禁止事项

完整示例：Webhook Echo

常见问题排查

实战教训汇总

❌ fs 模块被屏蔽导致文件写入失败

❌ Wait 节点导致激活失败

❌ HTTP Request jsonParameters

❌ 微信 API 字节限制

❌ PUT 后节点消失

❌ Webhook URL 格式

❌ 同一问题试错超过 3 次

试错规则

性能与监控

健康检查

Python 工具

参考文件

Related skills

❌ `fs` 模块被屏蔽导致文件写入失败