Tools

Dify Openclaw

Name: Dify Openclaw
Rating: 3.5 (1 reviews)
Author: one-leaf

By one-leaf 👁 10 views ▲ 0 votes

Dify plugin implementing a custom LLM provider (`openclaw`) using the `dify_plugin` SDK with custom header support for agent/session routing.

GitHub

Configuration Example

model: "openclaw"           # Use default agent
model: "openclaw/default"   # Use default agent
model: "openclaw/<agentId>" # Use specific agent
model: "agent:<agentId>"    # Compatibility syntax

README

# OpenClaw Provider for Dify

A Dify models plugin that provides OpenAI-compatible API access with custom header support for the OpenClaw backend.

## Features

- **OpenAI-Compatible Protocol**: Works with Dify's standard OpenAI provider interface
- **Custom Header Support**: Adds OpenClaw Gateway routing headers:
  - `x-openclaw-model`: Override backend model for selected agent
  - `x-openclaw-agent-id`: Compatibility override for agent selection  
  - `x-openclaw-session-key`: Controls session routing
  - `x-openclaw-message-channel`: Sets synthetic ingress channel context

## Installation

Copy the `models/openclaw` directory to your Dify installation:

```bash
cp -r models/openclaw /path/to/dify/api/core/model_runtime/model_providers/
```

## API Reference

OpenClaw Gateway API Documentation: https://docs.openclaw.ai/gateway/openai-http-api

### Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/chat/completions` | POST | Chat completion (streaming supported) |
| `/v1/models` | GET | List available models |
| `/v1/models/{id}` | GET | Get model details |
| `/v1/embeddings` | POST | Embeddings |
| `/v1/responses` | POST | Responses API |

### Endpoint URL

```
POST http://<gateway-host>:<port>/v1/chat/completions
```

### Authentication

OpenClaw Gateway supports multiple auth modes:

| Auth Mode | Config | Header |
|-----------|--------|--------|
| Token | `gateway.auth.mode="token"` | `Authorization: Bearer <token>` |
| Password | `gateway.auth.mode="password"` | `Authorization: Bearer <password>` |
| Trusted Proxy | `gateway.auth.mode="trusted-proxy"` | - |
| None | `gateway.auth.mode="none"` | - |

### OpenClaw Headers

| Header | Required | Description |
|--------|----------|-------------|
| `x-openclaw-model` | Yes | `<provider/model-or-bare-id>` - overrides backend model |
| `x-openclaw-agent-id` | No | `<agentId>` - compatibility override |
| `x-openclaw-session-key` | No | `<sessionKey>` - controls session routing |
| `x-openclaw-message-channel` | No | `<channel>` - sets ingress channel context |

### Model Syntax

The following model specification formats are supported:

```yaml
model: "openclaw"           # Use default agent
model: "openclaw/default"   # Use default agent
model: "openclaw/<agentId>" # Use specific agent
model: "agent:<agentId>"    # Compatibility syntax
```

## Configuration

### Provider Credentials

| Field | Required | Description |
|-------|----------|-------------|
| `base_url` | Yes | OpenClaw Gateway URL (e.g., `http://localhost:8080`) |
| `api_key` | Yes | API key or password for authentication |
| `openclaw_model` | No | Model override. Supports `{{sys.app_id}}` |
| `openclaw_agent_id` | No | Agent ID. Supports `{{sys.app_id}}` |
| `openclaw_session_key` | No | Session key. Supports `{{sys.conversation_id}}` |
| `openclaw_channel` | No | Message channel |

### Dify Built-in Variables

| Variable | Resolves To | Usage |
|----------|-------------|-------|
| `{{sys.conversation_id}}` | Conversation UUID | Per-conversation session routing |
| `{{sys.user_id}}` | Current user ID | Auto-passed as `user` parameter |

### Recommended Configuration

```yaml
openclaw_agent_id: "main"                   # Or leave empty for "main"
openclaw_session_key: "{{sys.conversation_id}}"
```

This ensures each conversation has isolated session routing.

### Model Configuration

After installing the provider, configure it in Dify's model management:

1. Navigate to Settings → Model Providers
2. Find "OpenClaw" in the provider list
3. Add credentials and configure routing options

## Usage

Once configured, select the OpenClaw provider when setting up LLM models in Dify applications.

## Development

### Project Structure

```
models/openclaw/
├── __init__.py          # Plugin entry point
├── openclaw.py          # Provider implementation
├── openclaw.yaml        # Provider metadata
├── openclaw_credentials.yaml  # Credential schema
├── _position.yaml       # Provider position
├── icon.svg             # Provider icon
├── api/
│   └── http.py          # HTTP client with header injection
└── utils/
    └── headers.py       # Header builder
```

### Testing

Test credentials validation through Dify's model management UI, or run:

```bash
cd /path/to/dify/api
python -c "from core.model_runtime.model_providers.openclaw import OpenClawProvider; p = OpenClawProvider(); p.validate_credentials('your-model', {'base_url': '...', 'api_key': '...'})"
```

## License

Same as Dify's main license.

tools