n8n Node for OpenClaw Gateway HTTP API

This n8n community node provides integration with OpenClaw Gateway HTTP API, enabling you to interact with OpenClaw agents directly from your n8n workflows. It supports chat completions, embeddings, model listing, OpenResponses, and direct tool invocation.

Features

• Chat Completions: Standard OpenAI-compatible chat completions with streaming support
• Embeddings: Generate embeddings for text inputs
• Model Listing: List available OpenClaw models/agents
• OpenResponses: Native OpenClaw responses with file uploads, tools, and session management
• Tool Invocation: Direct tool calls (memory search, session listing, etc.)
• Flexible Authentication: Support for multiple OpenClaw Gateway instances
• Error Handling: Comprehensive error handling with informative messages

Installation

Method 1: Community Nodes (Recommended)

1. Go to Settings → Community Nodes in your n8n instance
2. Click "Install"
3. Enter n8n-nodes-openclaw-chat and click "Install"

Method 2: Manual Installation

cd ~/.n8n/nodes
npm install n8n-nodes-openclaw-chat

Method 3: Docker Deployment

Add to your docker-compose.yml:

volumes:
  - ~/.n8n/nodes:/home/node/.n8n/nodes

environment:
  - N8N_CUSTOM_EXTENSIONS=n8n-nodes-openclaw-chat

Configuration

1. Create OpenClaw API Credentials

1. In your n8n workflow, add an OpenClaw Chat node
2. Click the "Create New Credential" button
3. Select "OpenClaw API" credential type
4. Fill in the following fields:

Field	Description	Example
Base URL	Your OpenClaw Gateway URL	http://localhost:18789 or https://agent1.apipie.ai
API Token	Bearer token from OpenClaw Gateway	82af605cb191558a24874cdc5983cd07bdd40819723920cb2502f4bd456bc026
Default Agent ID	Default agent for chat completions	default, main, webchat
Allow Insecure HTTPS	Allow self-signed certificates (dev only)	false

Security Note: Keep your API token secure. Never commit it to version control.

2. Get Your OpenClaw Gateway Token

• Local OpenClaw: Check ~/.openclaw/openclaw.json for gateway.auth.token
• OpenClaw Cloud: Available in your instance dashboard
• Generate new token: Run openclaw gateway token generate

Node Operations

📨 Chat Completion

Endpoint: POST /v1/chat/completions

Create chat completions with OpenAI-compatible API.

Parameters:

Parameter	Type	Required	Default	Description
Model	String	Yes	openclaw/default	Model identifier (openclaw/<agentId>)
Messages	Array	Yes	-	Conversation history with role/content
Stream	Boolean	No	false	Enable streaming response (SSE)
Max Tokens	Number	No	4096	Maximum tokens to generate
Temperature	Number	No	1	Sampling temperature (0-2)
Top P	Number	No	1	Nucleus sampling (0-1)
Frequency Penalty	Number	No	0	Frequency penalty (-2 to 2)
Presence Penalty	Number	No	0	Presence penalty (-2 to 2)
Stop Sequences	String	No	-	Sequences to stop generation
User	String	No	-	End-user identifier

Example Workflow:

Manual Trigger → OpenClaw Chat (Chat Completion)

Node Configuration:

• Resource: Chat Completion
• Operation: Create
• Model: openclaw/default
• Messages:
  • Role: system, Content: You are a helpful assistant
  • Role: user, Content: What skills are installed?
• Temperature: 0.7

🔤 Embeddings

Endpoint: POST /v1/embeddings

Generate embeddings for input text.

Parameters:

Parameter	Type	Required	Default	Description
Model	String	Yes	openclaw/default	Embedding model
Input	String	Yes	-	Text or array of texts to embed
Encoding Format	Options	No	float	float or base64
User	String	No	-	End-user identifier

Example Workflow:

Webhook → OpenClaw Chat (Embeddings) → Vector Database

📋 Model Listing

Endpoint: GET /v1/models

List available OpenClaw models and agents.

Example Workflow:

Schedule Trigger → OpenClaw Chat (Model List) → Google Sheets

🚀 OpenResponses

Endpoint: POST /v1/responses

Native OpenClaw responses with advanced features (files, tools, session persistence).

Parameters:

Parameter	Type	Required	Default	Description
Model	String	Yes	openclaw	Model identifier
Input	String/Array	Yes	-	Text, message array, or structured input
Stream	Boolean	No	false	Enable streaming response
Tools	JSON	No	-	Tool definitions array
User	String	No	-	Stable session identifier
Previous Response ID	String	No	-	Continue previous conversation

Example Workflow:

Email Attachment → File Parse → OpenClaw Chat (Response) → Send Answer

🛠️ Tool Invocation

Endpoint: POST /tools/invoke

Direct tool invocation without full agent turn.

Parameters:

Parameter	Type	Required	Default	Description
Tool Name	String	Yes	-	Tool name (e.g., memory_search, sessions_list)
Action	String	No	-	Tool action (e.g., json)
Arguments	JSON	No	{}	Tool arguments

Example Workflow:

Manual Trigger → OpenClaw Chat (Tool) → Filter → Display Results

Supported Tools (subject to gateway policy):

• memory_search - Search memory files
• sessions_list - List active sessions
• cron_list - List cron jobs
• gateway_status - Gateway health check
• ...and other non-destructive tools

Advanced Usage

Streaming Responses

Enable streaming for real-time token delivery:

1. Select "Create Streaming" operation for Chat Completion or Response resources
2. Connect to "Split In Batches" node to process chunks
3. Use "Code" node to assemble final response

Session Management

Use the user field to maintain conversation context across nodes:

{
  "user": "customer-12345",
  "input": "Follow up on my previous question"
}

File Uploads (OpenResponses)

Use OpenResponses endpoint with base64-encoded files:

{
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": "Summarize this PDF"
    },
    {
      "type": "input_file",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "BASE64_DATA",
        "filename": "document.pdf"
      }
    }
  ]
}

Tool Definitions (OpenResponses)

Define client tools for agent use:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

Example Workflows

1. Customer Support Bot

Webhook (Customer Question)
    ↓
OpenClaw Chat (Chat Completion)
    ↓
IF (Needs Human)
    ├→ Slack Notification
    └→ Ticket Creation
    ↓
OpenClaw Chat (Response with Tools)
    ↓
Send Email Response

2. Document Processing Pipeline

Google Drive (New File)
    ↓
Convert to Text
    ↓
OpenClaw Chat (Embeddings)
    ↓
Qdrant Vector Store
    ↓
OpenClaw Chat (Response with RAG)
    ↓
Save to Database

3. Automated Monitoring

Schedule Trigger (Every hour)
    ↓
OpenClaw Chat (Tool: sessions_list)
    ↓
Filter (Inactive > 24h)
    ↓
IF (Found)
    └→ Slack Alert

Error Handling

The node includes comprehensive error handling:

Error Type	Description	Resolution
Authentication Failed	Invalid API token or base URL	Verify credentials, check gateway status
Endpoint Not Found	API endpoint disabled	Enable endpoint in gateway config
Rate Limited	Too many requests	Add wait node, implement backoff
Invalid Input	Malformed request body	Check parameter formatting
Tool Denied	Tool blocked by gateway policy	Use allowed tools only

Enable "Continue on Fail" in node settings to handle errors gracefully in your workflow.

Development

Project Structure

n8n-nodes-openclaw-chat/
├── src/
│   ├── credentials/
│   │   └── OpenClawApi.credentials.ts
│   ├── nodes/
│   │   └── OpenClaw/
│   │       ├── OpenClawChat.node.ts
│   │       └── GenericFunctions.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Build from Source

# Clone repository
git clone https://github.com/EncryptShawn/n8n-nodes-openclaw-chat.git
cd n8n-nodes-openclaw-chat

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint

Testing with Local n8n

1. Build the node: npm run build
2. Copy to n8n custom nodes directory:

   cp -r dist ~/.n8n/custom/n8n-nodes-openclaw-chat

3. Restart n8n
4. The node will appear as "OpenClaw Chat" in the node panel

API Reference

For complete OpenClaw Gateway HTTP API documentation, see:

• OpenClaw Docs: Gateway HTTP API
• OpenResponses Format
• Tool Invocation Security

Troubleshooting

Node Not Appearing

1. Check n8n logs for loading errors
2. Verify node is in ~/.n8n/custom/ directory
3. Restart n8n instance
4. Check n8n version compatibility (requires n8n 1.0+)

Authentication Errors

{
  "error": "OpenClaw API request failed: HTTP 401"
}

1. Verify base URL includes protocol (http:// or https://)
2. Check API token matches gateway token
3. Test connection with curl:

   curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:18789/health

Endpoint Errors

{
  "error": "OpenClaw API request failed: HTTP 404"
}

1. Ensure endpoint is enabled in gateway config:

   {
     "gateway": {
       "http": {
         "endpoints": {
           "chatCompletions": { "enabled": true },
           "responses": { "enabled": true }
         }
       }
     }
   }

2. Restart gateway after config changes

Streaming Issues

1. Ensure you're using "Create Streaming" operation
2. Check n8n version supports streaming responses
3. Verify network connectivity to gateway

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

Please follow the n8n Node Development Guidelines.

Example Workflows

Check the examples/ directory for ready-to-import n8n workflows:

• Basic Chat Completion (examples/basic-chat-completion.json) – Simple manual trigger asking OpenClaw to list installed skills

To import a workflow in n8n:

1. Go to Workflows → Import from file
2. Select the JSON file
3. Configure your OpenClaw API credentials (see Configuration)
4. Execute the workflow

License

MIT © EncryptShawn

Support

• Issues: GitHub Issues
• Documentation: OpenClaw Docs
• Community: OpenClaw Discord

---

Happy Automating! 🚀