Openclaw N8n Orchestrator

openclaw-{service}-{action}/
├── SKILL.md              ← YAML frontmatter + instructions (REQUIRED)
├── README.md             ← Human documentation
└── scripts/
    └── trigger.sh        ← Webhook trigger with input sanitization

---
name: openclaw-{service}-{action}
description: "When the user requests {specific trigger condition}, POST a structured JSON payload to the n8n webhook at {path} to execute {what it does}. Use this skill for {explicit use cases}."
homepage: "https://github.com/{user}/{repo}"
metadata:
  clawdbot:
    emoji: "{relevant_emoji}"
requires:
  env:
    - N8N_WEBHOOK_URL
    - N8N_WEBHOOK_SECRET
  bins:
    - "curl"
files:
  - "scripts/*"
user-invocable: true
---

# {Skill Name}

## Execution

When triggered, run the webhook script:

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

The script sanitizes all input, constructs the authenticated webhook request,
and returns the n8n response for the agent to summarize.

## Failure Handling

- If curl returns non-zero exit code, read stderr and report the specific error
- If HTTP 401: webhook secret mismatch — instruct user to verify N8N_WEBHOOK_SECRET
- If HTTP 404: workflow inactive or path wrong — instruct user to check n8n
- If HTTP 5xx: n8n execution failure — report and suggest checking n8n execution logs
- Do NOT hallucinate success if the response is empty or unexpected

## External Endpoints

| URL | Method | Payload |
|-----|--------|---------|
| `${N8N_WEBHOOK_URL}/webhook/openclaw-{service}-{action}` | POST | JSON action + payload object |

## Security & Privacy

- Webhook secret loaded from environment variable, never hardcoded
- All user input sanitized via URL encoding before shell execution
- No data stored locally; payload transmitted to n8n instance only
- Agent has NO access to downstream API credentials (Slack, GitHub, etc.)

## Model Invocation Note

The OpenClaw agent may invoke this skill autonomously without direct human
prompting. To disable autonomous triggering, remove this skill directory
from the active skills path.

## Trust Statement

By using this skill, data is sent to your configured n8n instance.
Only install if you trust your n8n deployment and its configured integrations.

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

# SECURITY MANIFEST:
# Environment variables accessed: N8N_WEBHOOK_URL, N8N_WEBHOOK_SECRET (only)
# External endpoints called: ${N8N_WEBHOOK_URL}/webhook/openclaw-{service}-{action} (only)
# Local files read: none
# Local files written: none

ACTION="${1:?Usage: trigger.sh <action> <payload_json>}"
PAYLOAD="${2:?Usage: trigger.sh <action> <payload_json>}"

# Sanitize inputs — prevents shell injection via command substitution
SAFE_ACTION=$(printf '%s' "$ACTION" | python3 -c \
  'import sys, urllib.parse; print(urllib.parse.quote(sys.stdin.read().strip(), safe=""))')

# Construct and send webhook request
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
  "${N8N_WEBHOOK_URL}/webhook/openclaw-${SAFE_ACTION}" \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: ${N8N_WEBHOOK_SECRET}" \
  --data-urlencode "payload=${PAYLOAD}" \
  --max-time 30)

# Parse response
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [[ "$HTTP_CODE" -ge 200 && "$HTTP_CODE" -lt 300 ]]; then
  echo "SUCCESS (HTTP ${HTTP_CODE}): ${BODY}"
  exit 0
else
  echo "ERROR (HTTP ${HTTP_CODE}): ${BODY}" >&2
  exit 1
fi

// Inline via exec tool — no external dependencies
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.N8N_WEBHOOK_SECRET,
    'Content-Length': data.length
  }
};
const req = https.request(options, res => {
  let body = '';
  res.on('data', chunk => body += chunk);
  res.on('end', () => {
    process.stdout.write(body);
    process.exit(res.statusCode >= 200 && res.statusCode < 300 ? 0 : 1);
  });
});
req.on('error', e => { process.stderr.write(e.message); process.exit(1); });
req.write(data);
req.end();

{
  "gateway": {
    "http": {
      "endpoints": {
        "responses": { "enabled": true }
      }
    },
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

{
  "model": "claude-sonnet-4-20250514",
  "user": "n8n-workflow-{workflow_id}",
  "input": [
    { "role": "user", "content": "Workflow result: {data}" }
  ],
  "instructions": "Summarize this result for the user. Do NOT re-trigger the workflow.",
  "stream": false,
  "timeout_seconds": 0
}

1. USER → Agent: "Post Q3 report to #marketing Slack"
2. Agent REASONS: needs Slack API → has no credentials → knows webhook exists
3. Agent TRIGGERS: exec scripts/trigger.sh "slack-send-message" '{"channel":"#marketing"}'
4. n8n EXECUTES: Webhook → Validate → Slack API (locked credentials) → Log
5. n8n RETURNS: HTTP POST to Gateway /v1/responses with result
6. Agent REPORTS: "Posted to #marketing at 2:34 PM"

{
  "exec": {
    "enabled": true,
    "approval": true
  }
}

## Hard Constraints
- NEVER store, log, or output API keys or webhook secrets in conversation
- NEVER attempt to access n8n management API — only use webhook endpoints
- NEVER execute shell commands that modify system files outside workspace/
- If a webhook fails 3 consecutive times, STOP and alert the user
- NEVER enter infinite retry loops on failed API calls