N8n Operator

何时激活

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

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

前置条件

环境变量

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

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

认证方式

所有 API 请求必须携带：

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

连通性检查

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：理解需求

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

阶段 2：规划设计

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

阶段 3：逐步构建

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

阶段 4：验证交付

1. 确认已激活
2. 提供 Webhook URL
3. 展示测试结果
4. 记录 workflow_id

API 速查

基础 URL

{N8N_BASE_URL}/api/v1

工作流管理

凭证管理

执行记录

常用 curl 示例

# 列出所有工作流
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。

节点数据结构

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

关键规则：

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

连接数据结构

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

三层嵌套：

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

常见模式：

线性（A→B→C）：

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

分支（IF→true/false）：

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

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

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

n8n 表达式语法速查

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

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

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

发送 JSON body 的正确配置：

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

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

Gateway Cron 自动触发 n8n Webhook

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

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

路径：$USER_HOME_PATH.openclaw\cron\jobs.json

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

关键经验：

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

微信公众号 API 限制速查

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

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

错误处理策略

工作流级错误处理

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

节点级错误处理

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

Error Trigger

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

工作流设计原则

核心原则：防静默失败

1. 幂等性

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

2. 可观测性

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

3. 重试 + backoff

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

4. No Silent Failure

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

设计检查清单

• 触发类型
• 输入 schema 和必填字段
• dedup key 是什么？
• 错误重试策略
• 哪些情况路由人工审核？
• credential 通过引用，不硬编码？

Agent 操作规范

必须遵守

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

禁止事项

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

完整示例：Webhook Echo

{
  "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" }
}

激活 + 测试：

# 创建（自动获取 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"

常见问题排查

实战教训汇总

❌ 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 次 → 必须停止：

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

性能与监控

健康检查

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 工具

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 种经典架构模式
• api.md — 完整 API 端点索引