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
  • Added OpenClaw tool invocation
  • Added two context strategies: conversation-level and user-level
  • Added Dify uploaded file support through base64 /
  • Added URL-based image and document inputs
  • Added OpenClaw Gateway configuration documentation and Docker networking guidance

Quick Start

1. Edit and add or merge the following configuration. Replace with your own token:

2. Start OpenClaw Gateway:

3. Install the plugin package in Dify.

4. Configure provider credentials in Dify:

   • : OpenClaw Gateway base URL
   • : OpenClaw Gateway token
   • : OpenClaw agent target such as or
   • : optional request timeout, default

5. Choose a tool:

   • : conversation-level context
   • : user-level context

Key Features

• OpenClaw Gateway Integration: Uses to interact with OpenClaw agents.
• Credential Validation: Verifies OpenClaw connectivity and model availability through .
• Two Context Strategies: Supports both per-conversation and per-user OpenClaw sessions.
• Direct Dify File Uploads: Accepts Dify 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 , , or 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 ()

Conversation-level OpenClaw context retention.

• Required:
• Optional: , ,
• 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 ()

User-level OpenClaw context retention across Dify conversations.

• Required:
• Optional: , ,
• 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
• Uploaded images: sent as base64
• Uploaded documents: sent as base64
• Image URLs: sent as URL
• Document URLs: sent as URL

OpenClaw Gateway Configuration

Before using this plugin, enable OpenClaw Gateway HTTP endpoints.

Required endpoint:

Recommended endpoint for Dify credential validation:

Optional compatibility endpoint:

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

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

Bind Mode Notes

Do not set to raw values such as , , or a LAN IP. OpenClaw accepts only these values:

Use plus when Docker or another private-network runtime needs to reach the host gateway.

JSON5 still requires commas between properties. This is invalid:

Use this instead:

Dify Provider Configuration

Base URL examples by deployment:

If Dify reports or , the Dify plugin runtime cannot reach the configured . The most common cause is using inside Docker while OpenClaw is running on the host loopback address.

Tool Parameters

Both tools expose the same parameters.

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 and .

Supported File Types

Supported image extensions:

Supported uploaded image MIME types:

Supported document types:

Safety Limits

URL validation before forwarding to OpenClaw:

• Accepts only and URLs.
• Rejects URLs longer than characters.
• Rejects more than URLs per URL parameter.
• Rejects URL user info such as .
• Rejects invalid ports.
• Rejects obvious local/private host literals including , , , , , , , and private IPv6 literals.
• Checks file type by parsed URL path extension.

Uploaded file validation before forwarding to OpenClaw:

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

Usage Examples

Text:

Image URL:

Document URL:

Direct Dify upload:

Requirements

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

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 for reliable tool execution.
• Uploaded files are sent as base64, increasing request size by about one third.

Developer Information

• Author:
• Email: [email protected]
• License: Apache License 2.0
• Source Code:
• 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?