n8n-nodes-openclaw 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Jason Williscroft
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,164 @@
+# n8n-nodes-openclaw
+
+[n8n](https://n8n.io/) community nodes for the [OpenClaw](https://github.com/openclaw/openclaw) Gateway API.
+
+Control your OpenClaw instance from n8n workflows — manage sessions, send messages, run cron jobs, search the web, execute commands, and more.
+
+![OpenClaw Node in n8n](https://img.shields.io/badge/n8n-community_node-ff6d5a?logo=n8n)
+[![npm version](https://img.shields.io/npm/v/n8n-nodes-openclaw)](https://www.npmjs.com/package/n8n-nodes-openclaw)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)
+
+## Installation
+
+### Community Nodes (recommended)
+
+1. Open **Settings → Community Nodes** in your n8n instance
+2. Click **Install a community node**
+3. Enter `n8n-nodes-openclaw`
+4. Click **Install**
+
+### Manual Installation
+
+```bash
+# In your n8n custom nodes directory
+cd ~/.n8n/custom
+npm install n8n-nodes-openclaw
+```
+
+Or link from source:
+
+```bash
+git clone https://github.com/karmaniverous/n8n-nodes-openclaw.git
+cd n8n-nodes-openclaw
+npm install
+npm run build
+
+# Link into n8n
+mkdir -p ~/.n8n/custom/node_modules
+ln -s "$(pwd)" ~/.n8n/custom/node_modules/n8n-nodes-openclaw
+```
+
+Then restart n8n.
+
+## Setup
+
+1. In n8n, go to **Settings → Credentials → Add Credential**
+2. Search for **OpenClaw API**
+3. Enter your:
+   - **Gateway URL** — e.g. `http://127.0.0.1:18789`
+   - **Gateway Token** — found in your OpenClaw config file under `gateway.auth.token`
+
+## Available Tools
+
+The OpenClaw node exposes **20 tools** via a Resource dropdown, each with contextual parameters:
+
+| Resource | Description |
+|----------|-------------|
+| **Agents List** | List available agent IDs for spawning sub-agents |
+| **Browser** | Control a browser — open pages, screenshots, snapshots, click, fill forms |
+| **Canvas** | Control canvas overlays on paired nodes |
+| **Cron** | Manage scheduled jobs — list, add, update, remove, run, wake |
+| **Execute Command** | Run shell commands on the host system |
+| **Gateway** | Manage the gateway — restart, read/write config, trigger updates |
+| **Image** | Analyze images with a vision model |
+| **Memory Get** | Read snippets from agent memory files |
+| **Memory Search** | Semantically search agent memory |
+| **Message** | Send, read, edit, delete messages across channels (Slack, Discord, Telegram, etc.) |
+| **Nodes** | Discover and control paired nodes — notifications, camera, location, commands |
+| **Process Manager** | Manage running exec sessions — poll, log, write stdin, kill |
+| **Session Status** | Get session status, usage stats, and set model overrides |
+| **Sessions History** | Retrieve conversation history for a session |
+| **Sessions List** | List active sessions with filters |
+| **Sessions Send** | Send messages into other sessions (cross-session communication) |
+| **Sessions Spawn** | Spawn background sub-agents in isolated sessions |
+| **Text to Speech** | Convert text to speech audio |
+| **Web Fetch** | Fetch and extract readable content from URLs (HTML → markdown) |
+| **Web Search** | Search the web via Brave Search |
+
+### Raw Mode
+
+Every resource supports **Raw Mode** — toggle it on to send arbitrary JSON arguments instead of using the form fields. Useful for edge cases or new parameters not yet in the schema.
+
+## CLI Commands Not in the API
+
+The OpenClaw CLI (`openclaw`) has commands that are **not available** via the Gateway HTTP API — notably `openclaw gateway status`, `openclaw gateway start`, and `openclaw gateway stop`. These manage the local daemon and require OS-level access.
+
+If you need these in a workflow, use n8n's built-in **Execute Command** node to run them directly:
+
+```
+openclaw gateway status
+```
+
+The CLI does not currently support JSON output, so you'll need to parse the human-readable text.
+
+## Examples
+
+See the [`examples/`](examples/) directory for ready-to-import n8n workflow files:
+
+- **List Sessions** — basic workflow showing session listing
+- **Send Slack Message** — send a message to a Slack channel
+- **Cron Job Management** — list and run cron jobs
+- **Web Search → Message** — search the web and post results to a channel
+
+Import any example via **Workflows → Import from File** in n8n.
+
+## How It Works
+
+This node calls the OpenClaw Gateway's [`POST /tools/invoke`](https://docs.openclaw.ai) endpoint. Each resource/action combination maps to a tool invocation:
+
+```json
+{
+  "tool": "sessions_list",
+  "args": { "limit": 5, "kinds": ["main", "group"] }
+}
+```
+
+The gateway enforces tool policies, authentication, and session context. See the [OpenClaw docs](https://docs.openclaw.ai) for full API details.
+
+## Development
+
+```bash
+git clone https://github.com/karmaniverous/n8n-nodes-openclaw.git
+cd n8n-nodes-openclaw
+npm install
+npm run build
+npm test
+```
+
+### Project Structure
+
+```
+src/
+  credentials/          # OpenClaw API credential type
+  nodes/OpenClaw/       # Main node implementation
+    OpenClaw.node.ts    # Node class with execute function
+    toolSchemas.ts      # Static tool schema loader
+    openclaw.svg        # Node icon
+tool-schemas/           # JSON schema files for each tool (20 files)
+examples/               # Example n8n workflows
+```
+
+### Running Tests
+
+```bash
+npm test                                    # Unit tests
+OPENCLAW_TOKEN=<token> npm test             # + integration tests against live gateway
+```
+
+### Linting & Type Checking
+
+```bash
+npm run lint
+npm run typecheck
+npm run knip          # Unused exports/dependencies check
+```
+
+## License
+
+[BSD-3-Clause](LICENSE)
+
+## Links
+
+- [OpenClaw](https://github.com/openclaw/openclaw) — the AI agent framework
+- [OpenClaw Docs](https://docs.openclaw.ai) — full documentation
+- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/) — how community nodes work

package/dist/credentials/OpenClawApi.credentials.js

@@ -0,0 +1,29 @@
+'use strict';
+
+class OpenClawApi {
+    name = 'openClawApi';
+    displayName = 'OpenClaw API';
+    documentationUrl = 'https://docs.openclaw.ai/gateway/tools-invoke-http-api';
+    properties = [
+        {
+            displayName: 'Gateway URL',
+            name: 'gatewayUrl',
+            type: 'string',
+            default: 'http://127.0.0.1:18789',
+            placeholder: 'http://127.0.0.1:18789',
+            description: 'The URL of your OpenClaw Gateway. Default port is 18789.',
+            required: true,
+        },
+        {
+            displayName: 'Gateway Token',
+            name: 'gatewayToken',
+            type: 'string',
+            typeOptions: { password: true },
+            default: '',
+            description: 'The authentication token for your OpenClaw Gateway. Found in your gateway config under gateway.auth.token.',
+            required: true,
+        },
+    ];
+}
+
+exports.OpenClawApi = OpenClawApi;

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { ICredentialType, INodeProperties, INodeType, INodeTypeDescription, IExecuteFunctions, INodeExecutionData } from 'n8n-workflow';
+
+declare class OpenClawApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}
+
+declare class OpenClaw implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}
+
+/**
+ * Tool schema type definition.
+ */
+interface ToolParameterDef {
+    type: string;
+    required?: boolean;
+    enum?: string[];
+    description?: string;
+    default?: unknown;
+    placeholder?: string;
+    /** If true, the n8n field is a comma-separated string that should be split into an array before sending to the API. */
+    splitAsArray?: boolean;
+    displayOptions?: {
+        show?: {
+            action?: string[];
+        };
+    };
+}
+interface ToolSchema {
+    name: string;
+    label: string;
+    description: string;
+    actions?: string[];
+    parameters: Record<string, ToolParameterDef>;
+}
+/**
+ * All tool schemas, sorted by label for UI display.
+ */
+declare const toolSchemas: ToolSchema[];
+
+export { OpenClaw, OpenClawApi, toolSchemas };
+export type { ToolParameterDef, ToolSchema };

package/dist/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+var credentials_OpenClawApi_credentials = require('./credentials/OpenClawApi.credentials.js');
+var nodes_OpenClaw_OpenClaw_node = require('./nodes/OpenClaw/OpenClaw.node.js');
+var nodes_OpenClaw_toolSchemas = require('./nodes/OpenClaw/toolSchemas.js');
+require('n8n-workflow');
+
+
+
+exports.OpenClawApi = credentials_OpenClawApi_credentials.OpenClawApi;
+exports.OpenClaw = nodes_OpenClaw_OpenClaw_node.OpenClaw;
+exports.toolSchemas = nodes_OpenClaw_toolSchemas.toolSchemas;

package/dist/nodes/OpenClaw/OpenClaw.node.js

@@ -0,0 +1,284 @@
+'use strict';
+
+var n8nWorkflow = require('n8n-workflow');
+var nodes_OpenClaw_toolSchemas = require('./toolSchemas.js');
+
+/**
+ * Build n8n node properties from tool schemas.
+ */
+function buildResourceOptions() {
+    return nodes_OpenClaw_toolSchemas.toolSchemas.map((schema) => ({
+        name: schema.label,
+        value: schema.name,
+        description: schema.description,
+    }));
+}
+/**
+ * Build action (operation) options for a specific tool.
+ */
+function buildActionProperties() {
+    const properties = [];
+    for (const schema of nodes_OpenClaw_toolSchemas.toolSchemas) {
+        if (!schema.actions)
+            continue;
+        properties.push({
+            displayName: 'Action',
+            name: 'action',
+            type: 'options',
+            displayOptions: {
+                show: { resource: [schema.name] },
+            },
+            options: schema.actions.map((action) => ({
+                name: action.charAt(0).toUpperCase() + action.slice(1),
+                value: action,
+            })),
+            default: schema.actions[0],
+            noDataExpression: true,
+            required: true,
+            description: `The ${schema.label} operation to perform`,
+        });
+    }
+    return properties;
+}
+/**
+ * Build parameter fields for each tool, respecting displayOptions.
+ */
+function buildParameterProperties() {
+    const properties = [];
+    for (const schema of nodes_OpenClaw_toolSchemas.toolSchemas) {
+        const params = schema.parameters;
+        for (const [paramName, paramDef] of Object.entries(params)) {
+            // Skip 'action' — already handled above
+            if (paramName === 'action')
+                continue;
+            // Skip gateway override params — handled by credentials
+            if (paramName === 'gatewayUrl' || paramName === 'gatewayToken')
+                continue;
+            const displayOptions = {
+                show: { resource: [schema.name] },
+            };
+            // If the param has its own displayOptions.show.action, merge it
+            if (paramDef.displayOptions?.show?.action) {
+                displayOptions.show.action =
+                    paramDef.displayOptions.show.action;
+            }
+            const n8nType = mapType(paramDef.type);
+            const prop = {
+                displayName: formatDisplayName(paramName),
+                name: paramName,
+                type: n8nType,
+                displayOptions,
+                default: paramDef.default ?? (n8nType === 'boolean' ? false : ''),
+                required: paramDef.required ?? false,
+                description: paramDef.description ?? '',
+            };
+            if (paramDef.enum && n8nType === 'options') {
+                prop.options = paramDef.enum.map((v) => ({
+                    name: v.charAt(0).toUpperCase() + v.slice(1),
+                    value: v,
+                }));
+            }
+            if (paramDef.placeholder) {
+                prop.placeholder = paramDef.placeholder;
+            }
+            // For object/json types, use the json type
+            if (paramDef.type === 'object') {
+                prop.type = 'json';
+                prop.default = '{}';
+            }
+            properties.push(prop);
+        }
+    }
+    return properties;
+}
+function mapType(schemaType) {
+    switch (schemaType) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'object':
+            return 'json';
+        default:
+            return 'string';
+    }
+}
+function formatDisplayName(name) {
+    return name
+        .replace(/([A-Z])/g, ' $1')
+        .replace(/[_-]/g, ' ')
+        .replace(/\b\w/g, (c) => c.toUpperCase())
+        .trim();
+}
+class OpenClaw {
+    description = {
+        displayName: 'OpenClaw',
+        name: 'openClaw',
+        icon: 'file:openclaw.svg',
+        group: ['transform'],
+        version: 1,
+        subtitle: '={{$parameter["resource"] + ": " + ($parameter["action"] || "execute")}}',
+        description: 'Interact with the OpenClaw Gateway API',
+        defaults: {
+            name: 'OpenClaw',
+        },
+        inputs: ['main'],
+        outputs: ['main'],
+        credentials: [
+            {
+                name: 'openClawApi',
+                required: true,
+            },
+        ],
+        properties: [
+            // Resource selector (tool)
+            {
+                displayName: 'Resource',
+                name: 'resource',
+                type: 'options',
+                noDataExpression: true,
+                options: buildResourceOptions(),
+                default: 'sessions_list',
+                required: true,
+                description: 'The OpenClaw tool to invoke',
+            },
+            // Raw mode option
+            {
+                displayName: 'Raw Mode',
+                name: 'rawMode',
+                type: 'boolean',
+                default: false,
+                description: 'Whether to send raw JSON arguments instead of using the form fields. Useful for tools not yet supported with typed fields.',
+            },
+            {
+                displayName: 'Raw Arguments (JSON)',
+                name: 'rawArgs',
+                type: 'json',
+                default: '{}',
+                displayOptions: {
+                    show: { rawMode: [true] },
+                },
+                description: 'Raw JSON arguments to pass to the tool',
+            },
+            // Action selectors per resource
+            ...buildActionProperties(),
+            // Parameter fields per resource
+            ...buildParameterProperties(),
+        ],
+    };
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const credentials = await this.getCredentials('openClawApi');
+        const gatewayUrl = credentials.gatewayUrl;
+        const gatewayToken = credentials.gatewayToken;
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const resource = this.getNodeParameter('resource', i);
+                const rawMode = this.getNodeParameter('rawMode', i, false);
+                let args;
+                if (rawMode) {
+                    const rawArgs = this.getNodeParameter('rawArgs', i, '{}');
+                    args = JSON.parse(rawArgs);
+                }
+                else {
+                    args = buildArgsFromParameters.call(this, resource, i);
+                }
+                const body = {
+                    tool: resource,
+                    args,
+                };
+                // If there's an action, also set it at the top level
+                if (args.action) {
+                    body.action = args.action;
+                }
+                const options = {
+                    method: 'POST',
+                    url: `${gatewayUrl.replace(/\/$/, '')}/tools/invoke`,
+                    body,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${gatewayToken}`,
+                    },
+                    json: true,
+                };
+                const response = (await this.helpers.httpRequest(options));
+                if (response.ok === false) {
+                    throw new n8nWorkflow.NodeApiError(this.getNode(), response, {
+                        message: response.error?.message ?? 'Unknown error',
+                    });
+                }
+                returnData.push({
+                    json: (response.result ?? response),
+                });
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: { error: error.message },
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+/**
+ * Build args object from n8n parameter values for a given resource.
+ */
+function buildArgsFromParameters(resource, itemIndex) {
+    const schema = nodes_OpenClaw_toolSchemas.toolSchemas.find((s) => s.name === resource);
+    if (!schema)
+        return {};
+    const args = {};
+    // Get action if this tool has actions
+    if (schema.actions && schema.actions.length > 0) {
+        try {
+            args.action = this.getNodeParameter('action', itemIndex);
+        }
+        catch {
+            // action not available for this resource
+        }
+    }
+    // Get each parameter
+    for (const [paramName, paramDef] of Object.entries(schema.parameters)) {
+        if (paramName === 'action')
+            continue;
+        if (paramName === 'gatewayUrl' || paramName === 'gatewayToken')
+            continue;
+        try {
+            const value = this.getNodeParameter(paramName, itemIndex, undefined);
+            if (value !== undefined && !(typeof value === 'string' && value === '')) {
+                if (paramDef.type === 'object' && typeof value === 'string') {
+                    // Parse JSON strings for object types
+                    try {
+                        args[paramName] = JSON.parse(value);
+                    }
+                    catch {
+                        args[paramName] = value;
+                    }
+                }
+                else if (paramDef.splitAsArray && typeof value === 'string') {
+                    // Split comma-separated strings into arrays
+                    args[paramName] = value
+                        .split(',')
+                        .map((s) => s.trim())
+                        .filter((s) => s.length > 0);
+                }
+                else {
+                    args[paramName] = value;
+                }
+            }
+        }
+        catch {
+            // Parameter not available (hidden by displayOptions)
+        }
+    }
+    return args;
+}
+
+exports.OpenClaw = OpenClaw;

package/dist/nodes/OpenClaw/openclaw.svg

@@ -0,0 +1,22 @@
+<svg viewBox="0 0 120 120" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="lobster-gradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#ff4d4d"/>
+      <stop offset="100%" stop-color="#991b1b"/>
+    </linearGradient>
+  </defs>
+  <!-- Body -->
+  <path d="M60 10 C30 10 15 35 15 55 C15 75 30 95 45 100 L45 110 L55 110 L55 100 C55 100 60 102 65 100 L65 110 L75 110 L75 100 C90 95 105 75 105 55 C105 35 90 10 60 10Z" fill="url(#lobster-gradient)"/>
+  <!-- Left Claw -->
+  <path d="M20 45 C5 40 0 50 5 60 C10 70 20 65 25 55 C28 48 25 45 20 45Z" fill="url(#lobster-gradient)"/>
+  <!-- Right Claw -->
+  <path d="M100 45 C115 40 120 50 115 60 C110 70 100 65 95 55 C92 48 95 45 100 45Z" fill="url(#lobster-gradient)"/>
+  <!-- Antenna -->
+  <path d="M45 15 Q35 5 30 8" stroke="#ff4d4d" stroke-width="3" stroke-linecap="round"/>
+  <path d="M75 15 Q85 5 90 8" stroke="#ff4d4d" stroke-width="3" stroke-linecap="round"/>
+  <!-- Eyes -->
+  <circle cx="45" cy="35" r="6" fill="#050810"/>
+  <circle cx="75" cy="35" r="6" fill="#050810"/>
+  <circle cx="46" cy="34" r="2.5" fill="#00e5cc"/>
+  <circle cx="76" cy="34" r="2.5" fill="#00e5cc"/>
+</svg>