n8n-automation

n8n Automation 是一个用于通过 REST API 控制 n8n 工作流自动化平台的技能，可在 OpenClaw 中调用。

用途

该技能用于管理 n8n 工作流，包括列出、查看、创建、删除、激活/停用工作流，查看执行记录，以及通过 webhook 触发工作流。适用于用户询问 n8n 工作流、自动化、执行记录，或希望触发、列出工作流等场景。

主要能力

列出工作流：获取所有工作流的基本信息（id、名称、是否激活）。
获取工作流详情：查看指定工作流的完整配置。
激活/停用工作流：通过 PATCH 请求切换工作流状态。
触发工作流：通过生产或测试 webhook 发送 POST 请求触发。
列出执行记录：查看最近执行、失败执行或指定工作流的执行记录。
获取执行详情：查看单次执行的详细信息。
创建工作流：从 JSON 文件创建新工作流。
删除工作流：删除指定工作流。

使用方式

环境配置

需设置以下环境变量（或存储在 .n8n-api-config 中）：

export N8N_API_URL="https://your-instance.app.n8n.cloud/api/v1"  # 或 http://localhost:5678/api/v1
export N8N_API_KEY="your-api-key-here"

API 密钥生成方式：n8n 设置 → n8n API → 创建 API 密钥。

认证

所有 API 调用使用请求头 X-N8N-API-KEY 进行认证。

常用操作示例

列出工作流：

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows" | jq '.data[] | {id, name, active}'

获取工作流详情：

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows/{id}"

激活/停用工作流：

# 激活
curl -s -X PATCH -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}' "$N8N_API_URL/workflows/{id}"

# 停用
curl -s -X PATCH -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}' "$N8N_API_URL/workflows/{id}"

通过 webhook 触发工作流：

# 生产 webhook
curl -s -X POST "$N8N_API_URL/../webhook/{webhook-path}" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# 测试 webhook
curl -s -X POST "$N8N_API_URL/../webhook-test/{webhook-path}" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

列出执行记录：

# 所有最近执行
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?limit=10" | jq '.data[] | {id, workflowId, status, startedAt}'

# 仅失败执行
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?status=error&limit=5"

# 指定工作流的执行
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?workflowId={id}&limit=10"

获取执行详情：

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions/{id}"

从 JSON 创建工作流：

curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow.json "$N8N_API_URL/workflows"

删除工作流：

curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows/{id}"

常见模式

健康检查（定期运行）

列出激活的工作流，检查最近执行是否有错误，并报告状态：

# 统计激活的工作流数量
ACTIVE=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/workflows?active=true" | jq '.data | length')

# 统计失败执行数量（最近24小时）
FAILED=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_URL/executions?status=error&limit=100" | jq '[.data[] | select(.startedAt > (now - 86400 | todate))] | length')

echo "Active workflows: $ACTIVE | Failed (24h): $FAILED"

调试失败执行

列出失败执行 → 获取执行 ID
获取执行详情 → 找到失败的节点
检查节点参数和输入数据
根据错误信息建议修复方案

工作流摘要

解析工作流 JSON，总结触发类型、节点数量、连接的应用程序、调度计划。

API 端点参考

完整端点文档见 references/api-endpoints.md。

提示

非企业版计划中，API 密钥拥有完全访问权限。
速率限制因计划而异（云版），自托管版无限制。
Webhook URL 与 API URL 不同（无需认证头）。
使用 ?active=true 或 ?active=false 过滤工作流列表。
执行数据可能根据 n8n 保留设置被清理。

适用场景

适用于需要自动化管理 n8n 工作流的场景，例如批量查看工作流状态、监控执行失败、通过 webhook 触发自动化流程、定期健康检查等。

限制

需要有效的 n8n API 密钥和正确的 API URL。
部分功能（如执行数据保留）受 n8n 实例配置影响。
速率限制取决于 n8n 计划类型。