OpenClaw ↔ n8n Orchestrator

Build secure, auditable bridges between OpenClaw autonomous agents and n8n deterministic workflows. This skill generates production-ready OpenClaw skill directories (SKILL.md + scripts) that route all external API interactions through n8n's locked, credentialed pipelines.

Why Route Through n8n

OpenClaw's exec tool grants the LLM shell-level access. Every API key stored in .env or skill files becomes an attack vector — leakable through hallucination, prompt injection, or plaintext logging. The proxy orchestration pattern eliminates this:

- The agent never touches external API credentials
All external calls route through n8n webhooks with locked, encrypted credentials
Every agent-triggered action appears as an inspectable node graph (black-box → glass-box)
Deterministic loops run at zero token cost in n8n

Mode Detection

Mode 1: Egress (OpenClaw → n8n)

User says: "trigger n8n workflow," "create webhook skill," "call n8n from openclaw" → Generate an OpenClaw skill directory that triggers n8n webhooks

Mode 2: Ingress (n8n → OpenClaw)

User says: "push data to openclaw," "n8n response to agent," "gateway API" → Configure n8n HTTP Request nodes to POST to the Gateway /v1/responses endpoint

Mode 3: Bidirectional (Proxy Pattern)

User says: "round trip," "full integration," "proxy pattern," "credential isolation" → Complete egress + ingress loop with air-gap credential provisioning

Mode 4: n8n-claw Architecture

User says: "rebuild agent in n8n," "n8n-claw," "supabase memory" → Read references/n8n-claw-architecture.md

Mode 5: Publish to ClawHub

User says: "publish skill," "clawhub," "package for registry" → Read references/publishing.md

Generating OpenClaw Skill Directories (Egress)

When building an OpenClaw skill that triggers n8n, generate a complete skill directory — not a loose file. OpenClaw skills are directories containing a SKILL.md with YAML frontmatter.

Required Directory Structure

CODEBLOCK0

SKILL.md Template

Every generated SKILL.md must follow this exact structure:

CODEBLOCK1

Critical YAML rules:

- description is the only trigger mechanism. The LLM cannot see the Markdown body until after it selects the skill. Pack ALL trigger heuristics into this single string.
Use metadata.clawdbot namespace — NOT metadata.openclaw (the registry ignores the legacy namespace).
Use requires.env (singular) — NOT requires.envs (causes parse validation errors).
No multi-line strings or YAML block scalars. The parser expects single-line values or valid arrays only.
Declare files: ["scripts/*"] — omitting this causes ClawHub security scanners to flag the skill as suspicious.

Markdown Body Structure

Below the frontmatter, write instructions the LLM will follow. Include these mandatory transparency sections for ClawHub compliance:

CODEBLOCK2

Trigger Script Template

Every webhook trigger script MUST include:

1. set -euo pipefail (non-negotiable — prevents silent failures)
Security Manifest Header
Input sanitization via INLINECODE11
INLINECODE12 or pre-encoded payloads (never raw string interpolation)

CODEBLOCK3

Native MCP Tool Alternative

For simple webhook calls, prefer OpenClaw's built-in exec tool with a Node.js one-liner over shell scripts. Node.js avoids shell expansion vulnerabilities entirely:

CODEBLOCK4

Node.js is preferred because OpenClaw requires Node.js 22+ — it's always available. No dependencies, no shell injection surface.

Ingress: n8n → OpenClaw Gateway

The Gateway /v1/responses endpoint is disabled by default.

Enable the Endpoint

Edit openclaw.json:
CODEBLOCK5

n8n HTTP Request Node Configuration

Parameter	Value	Why
Method	POST	Standard transmission
URL

http://{gateway-host}:18789/v1/responses | OpenResponses ingress | | Authorization | Bearer {token} | Gateway auth | | Content-Type | application/json | JSON parsing | | timeout_seconds | 0 | MANDATORY — prevents infinite echo loop |

The echo loop problem: Without timeout_seconds: 0, the Gateway event bus reverberates the payload back into the session, causing the LLM to hallucinate an infinite dialogue with its own data. This destroys the 64k token context window and burns API costs exponentially.

Ingress Payload

CODEBLOCK6

The user string routes to a stable session. Use consistent patterns: n8n-workflow-{id} for per-workflow sessions, n8n-global for shared.

→ Full Gateway API spec, WebSocket protocol, telemetry codes: references/gateway-api.md

Proxy Orchestration Lifecycle

CODEBLOCK7

Air-Gap Credential Provisioning

After the agent generates the workflow structure:

1. Human logs into n8n UI
Provisions API keys into n8n's encrypted credential store
Binds credentials to nodes
Locks the workflow — agent cannot alter it
Agent only sends webhook payloads from this point

→ Security deep-dive, ClawHavoc analysis, safeguard nodes: references/security.md

System Hardening

Gateway Hardening (Critical)

Configure exec tool approval in openclaw.json:
CODEBLOCK8

With approval: true, every shell command requires human confirmation. This prevents a prompt-injected agent from executing arbitrary code.

soul.md Guardrails

Add to the agent's soul.md:
CODEBLOCK9

Multi-Model Routing for Cost Optimization

Configure OpenRouter in openclaw.json to route mundane webhook formatting to cheap models (GPT-4o Mini, Claude 3.5 Haiku) and reserve expensive models for complex reasoning:

CODEBLOCK10

This reduces API costs by ~70% for repetitive webhook orchestration tasks.

Scaling: The SkillPointer Pattern

When managing many n8n webhook skills (20+), loading all skill metadata at startup wastes tokens. Use the SkillPointer pattern:

1. Move individual webhook skills to a vault directory outside the agent's scan path:

INLINECODE29

2. Create a single lightweight pointer skill in the active directory:

CODEBLOCK11

3. The agent dynamically discovers skills via filesystem traversal at runtime

This reduces startup token consumption from ~8,000 tokens (40 webhook skills × 200 tokens each) to ~200 tokens (one pointer), while maintaining access to every skill.

Deployment

→ Docker Compose templates, network topologies, environment variables: references/deployment.md

Quick reference: OpenClaw Gateway defaults to port 18789, n8n to 5678. Never bind the Gateway to public interfaces. Use SSH tunnels or Tailscale for cross-network ingress.

Failure Mode Reference

Egress
Symptom Cause Fix
401 from webhook Secret mismatch Verify `N8N_WEBHOOK_SECRET` matches n8n Header Auth credential
404 from webhook
Inactive workflow or wrong path | Activate workflow; verify naming convention |

Symptom	Cause	Fix
401 from webhook	Secret mismatch	Verify `N8N_WEBHOOK_SECRET` matches n8n Header Auth credential
404 from webhook

Ingress
Symptom Cause Fix
403 from Gateway Token mismatch Verify INLINECODE33
Infinite echo loop
Missing `timeout_seconds: 0` | Add immediately |

Symptom	Cause	Fix
403 from Gateway	Token mismatch	Verify INLINECODE33
Infinite echo loop

| Session not found | Inconsistent user string | Use stable pattern: n8n-workflow-{id} | | DEVICE_AUTH_SIGNATURE_EXPIRED | Clock skew | Sync NTP across hosts | | Skill not loading | Invalid YAML frontmatter | Check for multi-line strings; validate with openclaw skills status |

Quick Start Checklist

Egress only:

- [ ] OpenClaw running (Node.js 22+) with workspace/skill/ directory
[ ] n8n running with webhook endpoint reachable
[ ] Webhook secret generated: INLINECODE39
[ ] Skill directory created with SKILL.md (YAML frontmatter) + scripts/trigger.sh
[ ] N8N_WEBHOOK_URL and N8N_WEBHOOK_SECRET set in INLINECODE42
[ ] requires.env and requires.bins declared in YAML frontmatter
[ ] files: ["scripts/*"] declared in frontmatter
[ ] Security Manifest Header in trigger.sh
[ ] set -euo pipefail in trigger.sh
[ ] Input sanitization via urllib.parse.quote or Node.js
[ ] n8n workflow created, validated, activated with Header Auth credential
[ ] Test with manual curl before agent triggers

Add bidirectional:

- [ ] Gateway /v1/responses enabled in INLINECODE50
[ ] exec.approval: true configured in gateway
[ ] soul.md guardrails written
[ ] timeout_seconds: 0 in all ingress payloads
[ ] SSH tunnel or Tailscale for cross-network Gateway access

Reference Files

- references/deployment.md — Docker Compose, topologies, env vars
references/gateway-api.md — Gateway endpoints, WebSocket protocol, payload schemas, telemetry codes
references/security.md — Proxy pattern, ClawHavoc analysis, credential isolation, safeguard nodes, shell injection mitigation
references/n8n-claw-architecture.md — n8n-claw paradigm: Supabase schema, RAG pipeline, MCP Builder, Telegram interface
references/publishing.md — ClawHub publishing pipeline, clawhub CLI, security scan requirements, version management

OpenClaw ↔ n8n Orchestrator

在OpenClaw自主代理与n8n确定性工作流之间构建安全、可审计的桥梁。此技能生成可直接投入生产的OpenClaw技能目录（SKILL.md + 脚本），将所有外部API交互路由至n8n锁定且具有凭证的管道。

为何通过n8n路由

OpenClaw的exec工具赋予LLM shell级访问权限。存储在.env或技能文件中的每个API密钥都成为攻击向量——可通过幻觉、提示注入或明文日志泄露。代理编排模式消除了这一问题：

- 代理绝不接触外部API凭证
所有外部调用通过具有锁定加密凭证的n8n webhook路由
每个代理触发的动作都显示为可检查的节点图（黑盒→玻璃盒）
确定性循环在n8n中以零token成本运行

模式检测

模式1：出站（OpenClaw → n8n）

用户说：触发n8n工作流、创建webhook技能、从openclaw调用n8n → 生成触发n8n webhook的OpenClaw技能目录

模式2：入站（n8n → OpenClaw）

用户说：推送数据到openclaw、n8n响应代理、网关API → 配置n8n HTTP请求节点以POST方式发送至网关/v1/responses端点

模式3：双向（代理模式）

用户说：往返、完整集成、代理模式、凭证隔离 → 完整的出站+入站循环，带气隙凭证配置

模式4：n8n-claw架构

用户说：在n8n中重建代理、n8n-claw、supabase内存 → 阅读references/n8n-claw-architecture.md

模式5：发布到ClawHub

用户说：发布技能、clawhub、打包到注册表 → 阅读references/publishing.md

生成OpenClaw技能目录（出站）

当构建触发n8n的OpenClaw技能时，生成一个完整的技能目录——而非零散文件。OpenClaw技能是包含带有YAML前置元数据的SKILL.md的目录。

必需的目录结构

openclaw-{service}-{action}/
├── SKILL.md ← YAML前置元数据 + 指令（必需）
├── README.md ← 人类可读文档
└── scripts/
└── trigger.sh ← 带输入清理的Webhook触发器

SKILL.md模板

每个生成的SKILL.md必须遵循以下精确结构：

yaml

name: openclaw-{service}-{action}
description: 当用户请求{特定触发条件}时，将结构化JSON负载POST到位于{路径}的n8n webhook以执行{其功能}。在{明确用例}下使用此技能。
homepage: https://github.com/{user}/{repo}
metadata:
clawdbot:
emoji: {相关表情符号}
requires:
env:
- N8NWEBHOOKURL
- N8NWEBHOOKSECRET
bins:
- curl
files:
- scripts/*
user-invocable: true

关键的YAML规则：

- description是唯一的触发机制。LLM在选择技能之前无法看到Markdown正文。将所有触发启发式信息打包到这一个字符串中。
使用metadata.clawdbot命名空间——而非metadata.openclaw（注册表忽略旧命名空间）。
使用requires.env（单数）——而非requires.envs（会导致解析验证错误）。
无多行字符串或YAML块标量。解析器仅期望单行值或有效数组。
声明files: [scripts/*]——省略此声明会导致ClawHub安全扫描器将该技能标记为可疑。

Markdown正文结构

在前置元数据下方，编写LLM将遵循的指令。为符合ClawHub要求，包含以下强制性透明度部分：

markdown

{技能名称}

执行

触发时，运行webhook脚本：

\\\bash
exec scripts/trigger.sh {action} {payload_json}
\\\

该脚本清理所有输入，构建经过身份验证的webhook请求，
并返回n8n响应供代理总结。

失败处理

- 如果curl返回非零退出码，读取stderr并报告具体错误
如果HTTP 401：webhook密钥不匹配——指示用户验证N8NWEBHOOKSECRET
如果HTTP 404：工作流未激活或路径错误——指示用户检查n8n
如果HTTP 5xx：n8n执行失败——报告并建议检查n8n执行日志
如果响应为空或意外，不要幻觉成功

外部端点

URL	方法	负载
${N8NWEBHOOKURL}/webhook/openclaw-{service}-{action}	POST	JSON动作+负载对象

安全与隐私

- Webhook密钥从环境变量加载，绝不硬编码
所有用户输入在shell执行前通过URL编码进行清理
无本地数据存储；负载仅传输到n8n实例
代理无权访问下游API凭证（Slack、GitHub等）

模型调用说明

OpenClaw代理可能在无直接人类提示的情况下自主调用此技能。
要禁用自主触发，请从活动技能路径中移除此技能目录。

信任声明

使用此技能即表示数据将发送到您配置的n8n实例。
仅当您信任您的n8n部署及其配置的集成时才安装。

触发脚本模板

每个webhook触发脚本必须包含：

1. set -euo pipefail（不可协商——防止静默失败）
安全清单头
通过urllib.parse.quote进行输入清理
--data-urlencode或预编码负载（绝不使用原始字符串插值）

bash
#!/usr/bin/env bash
set -euo pipefail

安全清单：

访问的环境变量：N8NWEBHOOKURL, N8NWEBHOOKSECRET（仅限）

调用的外部端点：${N8NWEBHOOKURL}/webhook/openclaw-{service}-{action}（仅限）

读取的本地文件：无

写入的本地文件：无

ACTION=${1:?用法：trigger.sh }
PAYLOAD=${2:?用法：trigger.sh }

清理输入——通过命令替换防止shell注入

SAFE_ACTION=$(printf %s $ACTION | python3 -c \ import sys, urllib.parse; print(urllib.parse.quote(sys.stdin.read().strip(), safe=)))

构建并发送webhook请求

RESPONSE=$(curl -s -w \n%{http_code} -X POST \ ${N8NWEBHOOKURL}/webhook/openclaw-${SAFE_ACTION} \ -H Content-Type: application/json \ -H x-webhook-secret: ${N8NWEBHOOKSECRET} \ --data-urlencode payload=${PAYLOAD} \ --max-time 30)

解析响应

HTTP_CODE=$(echo $RESPONSE | tail -1) BODY=$(echo $RESPONSE | sed $d)

if [[ $HTTPCODE -ge 200 && $HTTPCODE -lt 300 ]]; then
echo 成功（HTTP ${HTTP_CODE}）：${BODY}
exit 0
else
echo 错误（HTTP ${HTTP_CODE}）：${BODY} >&2
exit 1
fi

原生MCP工具替代方案

对于简单的webhook调用，优先使用OpenClaw内置的exec工具配合Node.js单行命令而非shell脚本。Node.js完全避免了shell扩展漏洞：

javascript
// 通过exec工具内联——无外部依赖
const https = require(https);
const data = JSON.stringify({action: ACTION, payload: PAYLOAD});
const options = {
hostname: N8N_HOST, port: 5678, path: /webhook/openclaw-{service}-{action},
method: POST,
headers: {
Content-Type: application/json,
x-webhook-secret: process.env.N8NWEBHOOKSECRET,
Content-Length: data.length
}
};
const req = https.request(options, res => {
let body = ;
res.on(data, chunk => body += chunk);
res.on(end, ()

openclaw-n8n-orchestratorOpenClaw-n8n编排器