OpenClaw Chat

A Dify tool plugin that connects Dify to a self-hosted OpenClaw Gateway through OpenClaw's OpenResponses-compatible HTTP API. It supports text chat, conversation-level and user-level context retention, Dify direct file uploads, image/document URL inputs, and interaction with OpenClaw agents and skills.

Simplified Chinese documentation is provided through Dify Marketplace multilingual README support.

Version Information

• Current Version: v0.0.1
• Release Date: 2026-05-09
• Compatibility: Dify Plugin Framework
• Python Version: 3.12
• License: Apache License 2.0

Version History

• v0.0.1 (2026-05-09):
  • Added OpenClaw Gateway provider credential validation through GET /v1/models
  • Added OpenClaw /v1/responses tool invocation
  • Added two context strategies: conversation-level and user-level
  • Added Dify uploaded file support through base64 input_image / input_file
  • Added URL-based image and document inputs
  • Added OpenClaw Gateway configuration documentation and Docker networking guidance

Quick Start

1. Edit ~/.openclaw/openclaw.json and add or merge the following gateway configuration. Replace YOUR_OPENCLAW_GATEWAY_TOKEN with your own token:

   {
     "gateway": {
       "port": 18789,
       "mode": "local",
       "bind": "custom",
       "customBindHost": "0.0.0.0",
       "auth": {
         "mode": "token",
         "token": "YOUR_OPENCLAW_GATEWAY_TOKEN"
       },
       "http": {
         "endpoints": {
           "chatCompletions": { "enabled": true },
           "responses": {
             "enabled": true,
             "maxBodyBytes": 20000000,
             "maxUrlParts": 8,
             "files": {
               "allowUrl": true,
               "allowedMimes": [
                 "text/plain",
                 "text/markdown",
                 "text/html",
                 "text/csv",
                 "application/json",
                 "application/pdf"
               ],
               "maxBytes": 5242880
             },
             "images": {
               "allowUrl": true,
               "allowedMimes": [
                 "image/jpeg",
                 "image/png",
                 "image/gif",
                 "image/webp",
                 "image/heic",
                 "image/heif"
               ],
               "maxBytes": 10485760
             }
           }
         }
       }
     }
   }
   

2. Start OpenClaw Gateway:

   openclaw gateway run
   

3. Install the plugin package in Dify.

4. Configure provider credentials in Dify:

   • Base URL: OpenClaw Gateway base URL
   • API Key: OpenClaw Gateway token
   • Model: OpenClaw agent target such as openclaw/default or openclaw/main
   • Timeout: optional request timeout, default 600

5. Choose a tool:

   • openclaw_chat: conversation-level context
   • openclaw_user_chat: user-level context

Key Features

• OpenClaw Gateway Integration: Uses POST /v1/responses to interact with OpenClaw agents.
• Credential Validation: Verifies OpenClaw connectivity and model availability through GET /v1/models.
• Two Context Strategies: Supports both per-conversation and per-user OpenClaw sessions.
• Direct Dify File Uploads: Accepts Dify files objects and forwards them as base64 inputs.
• Image and Document URL Inputs: Supports URL-based image and file references.
• Safe Session Routing: Does not expose session_key, conversation_id, or user_id as LLM-controllable tool parameters.
• Request Safety Guards: Validates URL schemes, local/private URL literals, file types, upload size, and filename safety.

Core Features

1) OpenClaw Chat (openclaw_chat)

Conversation-level OpenClaw context retention.

• Required: message
• Optional: upload_files, image_urls, file_urls
• Context scope: Dify conversation/session metadata plus Dify user id
• Best for: normal multi-turn chat where each Dify conversation should stay isolated

2) OpenClaw User Chat (openclaw_user_chat)

User-level OpenClaw context retention across Dify conversations.

• Required: message
• Optional: upload_files, image_urls, file_urls
• Context scope: Dify user id only
• Best for: scenarios where the same Dify user should share one OpenClaw context across multiple Dify conversations

Shared Input Support

• Text: sent as OpenResponses input_text
• Uploaded images: sent as base64 input_image
• Uploaded documents: sent as base64 input_file
• Image URLs: sent as URL input_image
• Document URLs: sent as URL input_file

OpenClaw Gateway Configuration

Before using this plugin, enable OpenClaw Gateway HTTP endpoints.

Required endpoint:

• POST /v1/responses

Recommended endpoint for Dify credential validation:

• GET /v1/models

Optional compatibility endpoint:

• POST /v1/chat/completions

Recommended config for Docker Desktop or controlled private-network access:

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "custom",
    "customBindHost": "0.0.0.0",
    "auth": {
      "mode": "token",
      "token": "YOUR_OPENCLAW_GATEWAY_TOKEN"
    },
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true },
        "responses": {
          "enabled": true,
          "maxBodyBytes": 20000000,
          "maxUrlParts": 8,
          "files": {
            "allowUrl": true,
            "allowedMimes": [
              "text/plain",
              "text/markdown",
              "text/html",
              "text/csv",
              "application/json",
              "application/pdf"
            ],
            "maxBytes": 5242880
          },
          "images": {
            "allowUrl": true,
            "allowedMimes": [
              "image/jpeg",
              "image/png",
              "image/gif",
              "image/webp",
              "image/heic",
              "image/heif"
            ],
            "maxBytes": 10485760
          }
        }
      }
    }
  }
}

If Dify and OpenClaw run in the same host process environment, loopback is enough:

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "YOUR_OPENCLAW_GATEWAY_TOKEN"
    }
  }
}

Bind Mode Notes

Do not set gateway.bind to raw values such as "127.0.0.1", "0.0.0.0", or a LAN IP. OpenClaw accepts only these values:

• "auto"
• "lan"
• "loopback"
• "custom"
• "tailnet"

Use "bind": "custom" plus "customBindHost": "0.0.0.0" when Docker or another private-network runtime needs to reach the host gateway.

JSON5 still requires commas between properties. This is invalid:

{
  "gateway": {
    "bind": "custom",
    "customBindHost": "0.0.0.0"
    "auth": { "mode": "token", "token": "..." }
  }
}

Use this instead:

{
  "gateway": {
    "bind": "custom",
    "customBindHost": "0.0.0.0",
    "auth": { "mode": "token", "token": "..." }
  }
}

Dify Provider Configuration

Field	Required	Example	Description
Base URL	Yes	http://127.0.0.1:18789	OpenClaw Gateway base URL. It may include /v1; the plugin normalizes it internally.
API Key	Yes	YOUR_OPENCLAW_GATEWAY_TOKEN	OpenClaw Gateway bearer token.
Model	Yes	openclaw/default	OpenClaw agent target, such as openclaw/default or openclaw/main.
Timeout	No	600	Request timeout in seconds. Valid range is 1-600; invalid values fall back to 600.

Base URL examples by deployment:

Deployment	Dify Base URL	Required OpenClaw bind
Same host, no Docker	http://127.0.0.1:18789	"bind": "loopback"
Dify in Docker Desktop, OpenClaw on host	http://host.docker.internal:18789	"bind": "custom", "customBindHost": "0.0.0.0" or "bind": "lan"
Dify on another LAN machine	http://<OpenClaw-host-LAN-IP>:18789	"bind": "lan" or reachable "custom" bind
SSH tunnel	http://127.0.0.1:18789 from the tunnel endpoint	"bind": "loopback"

If Dify reports Failed to establish a new connection or Connection refused, the Dify plugin runtime cannot reach the configured Base URL. The most common cause is using http://127.0.0.1:18789 inside Docker while OpenClaw is running on the host loopback address.

Tool Parameters

Both tools expose the same parameters.

Parameter	Required	Form	Example	Description
message	Yes	llm	Summarize this PDF.	Current user message sent to OpenClaw.
upload_files	No	llm	Dify uploaded file objects	Uploaded images or documents. The plugin sends them as base64 OpenResponses parts.
image_urls	No	llm	https://example.com/a.png	Optional image URLs, comma-separated or newline-separated.
file_urls	No	llm	https://example.com/report.pdf	Optional document URLs, comma-separated or newline-separated.

The plugin does not expose session routing parameters as tool inputs. OpenClaw session keys are derived from Dify runtime metadata and sent as both OpenResponses user and x-openclaw-session-key.

Supported File Types

Supported image extensions:

• .jpg
• .jpeg
• .png
• .gif
• .webp
• .heic
• .heif

Supported uploaded image MIME types:

• image/jpeg
• image/png
• image/gif
• image/webp
• image/heic
• image/heif

Supported document types:

Extension	MIME type
.txt	text/plain
.md, .markdown	text/markdown
.html	text/html
.csv	text/csv
.json	application/json
.pdf	application/pdf

Safety Limits

URL validation before forwarding to OpenClaw:

• Accepts only http:// and https:// URLs.
• Rejects URLs longer than 2048 characters.
• Rejects more than 8 URLs per URL parameter.
• Rejects URL user info such as https://user:pass@example.com/file.pdf.
• Rejects invalid ports.
• Rejects obvious local/private host literals including localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, and private IPv6 literals.
• Checks file type by parsed URL path extension.

Uploaded file validation before forwarding to OpenClaw:

• Accepts at most 8 uploaded files per tool call.
• Requires Dify file size metadata before reading file bytes.
• Rejects images larger than 10MB.
• Rejects documents larger than 5MB.
• Rejects the whole upload set when raw uploaded bytes exceed 12MB.
• Rejects MIME/extension mismatches.
• Sanitizes uploaded filenames before forwarding.

Usage Examples

Text:

message: Summarize what you can do in this OpenClaw workspace.

Image URL:

message: Analyze this screenshot.
image_urls: https://example.com/screenshot.png

Document URL:

message: Summarize this PDF and list action items.
file_urls: https://example.com/report.pdf

Direct Dify upload:

message: Summarize the uploaded files and extract action items.
upload_files: <Dify uploaded image/document files>

Requirements

• Python 3.12
• Dify Platform access
• Running OpenClaw Gateway
• Required Python packages installed through requirements.txt

Installation & Packaging

Package from the project root:

Notes

• OpenClaw HTTP API is an operator-level Gateway surface. Keep it on loopback, VPN, tailnet, or private ingress.
• HTTP sends the bearer token in plaintext. Use it only on trusted private networks.
• The plugin currently exposes Dify tools, not a native Dify model provider.
• Native Dify streaming is not exposed yet; OpenClaw is called with stream=false for reliable tool execution.
• Uploaded files are sent as base64, increasing request size by about one third.

Developer Information

• Author: https://github.com/sawyer-shi
• Email: sawyer36@foxmail.com
• License: Apache License 2.0
• Source Code: https://github.com/sawyer-shi/dify-plugins-openclaw_chat
• Support: Through Dify platform and GitHub Issues

License Notice

This project is licensed under Apache License 2.0. See LICENSE file for full license text.

---

Ready to connect Dify with OpenClaw?