If you’re running OpenClaw and looking to integrate more than just the default models, you’ve hit on one of its most powerful, yet sometimes undersold, features: the plugin architecture. OpenClaw isn’t just a monolithic application; it’s designed with extensibility in mind, particularly when it comes to Large Language Models (LLMs). This means you can hook into various providers, from local Ollama instances to commercial APIs like Anthropic, OpenAI, or even custom endpoints, without modifying the core OpenClaw codebase. The real power here is in creating a unified interface for diverse LLM capabilities.
Understanding the Plugin Directory
The first place to look when you want to extend OpenClaw’s model support is the plugins/ directory within your OpenClaw installation. By default, you’ll find a few examples, typically for OpenAI or Anthropic, and sometimes a placeholder for a local model. Each subdirectory within plugins/ represents a distinct plugin. For instance, you might see plugins/anthropic/ and plugins/openai/. Inside each of these, you’ll find the Python code that defines how OpenClaw communicates with that specific LLM provider. This separation is crucial for maintaining a clean and modular system.
Let’s say you want to add support for a new model from an existing provider, like a newer Anthropic model. You don’t necessarily need to create a whole new directory if the existing anthropic plugin already handles the API specifics. Instead, you’ll primarily be interacting with your OpenClaw configuration file to tell it which model to use. If you’re adding an entirely new provider, however, you’d create a new directory, say plugins/mistral/, and write the necessary Python code to handle the Mistral API calls.
Configuring Models via config.json
The true magic happens in your .openclaw/config.json file. This is where you declare which models OpenClaw should be aware of and how to access them. Each model entry maps a user-friendly name to a specific plugin and its configuration. Here’s a typical structure:
{
"models": {
"default": "claude-haiku",
"claude-haiku": {
"plugin": "anthropic",
"model_name": "claude-3-haiku-20240307",
"api_key_env": "ANTHROPIC_API_KEY",
"max_tokens": 4096,
"temperature": 0.7
},
"gpt-4o": {
"plugin": "openai",
"model_name": "gpt-4o",
"api_key_env": "OPENAI_API_KEY",
"max_tokens": 4096,
"temperature": 0.6
},
"local-llama3": {
"plugin": "ollama",
"model_name": "llama3",
"api_base": "http://localhost:11434/api",
"max_tokens": 2048,
"temperature": 0.8
}
},
"plugins": {
"anthropic": {
"module": "plugins.anthropic.anthropic_plugin"
},
"openai": {
"module": "plugins.openai.openai_plugin"
},
"ollama": {
"module": "plugins.ollama.ollama_plugin"
}
}
}
In this snippet:
- The
"models"section defines custom model aliases and their parameters."default": "claude-haiku": This sets the default model OpenClaw will use if you don’t specify one. This is a huge quality-of-life improvement; you don’t always need GPT-4o for simple tasks."claude-haiku": This is a user-defined alias. It maps to theanthropicplugin, specifies the exact Anthropic model name (claude-3-haiku-20240307), and tells OpenClaw to look for the API key in theANTHROPIC_API_KEYenvironment variable."local-llama3": This demonstrates integrating a local Ollama instance. Notice the"plugin": "ollama"and"api_base"pointing to the local Ollama server.
- The
"plugins"section tells OpenClaw which Python module to load for each plugin type."module": "plugins.anthropic.anthropic_plugin"means it will look for a file namedanthropic_plugin.pyinside theplugins/anthropic/directory.
The non-obvious insight here is that while the official Anthropic documentation might push for their more powerful (and expensive) models like Opus, claude-3-haiku-20240307, configured as claude-haiku in your config, is often 10x cheaper and perfectly sufficient for 90% of OpenClaw’s typical use cases, like summarization, basic code generation, or content rephrasing. Don’t always go for the biggest gun if a smaller, faster, cheaper one does the job.
Creating a New Plugin
Let’s say you want to integrate a model from a provider not natively supported, or a custom local inference server. You’d start by creating a new directory in plugins/, e.g., plugins/my_custom_provider/. Inside, you’d create a Python file, say my_custom_plugin.py. This file needs to define a class that implements the necessary interface expected by OpenClaw. While the exact interface can vary slightly with OpenClaw versions, the core requirement is usually a method for generating responses and handling model configuration.
A simplified structure for plugins/my_custom_provider/my_custom_plugin.py might look like this:
import os
import requests
import json
class MyCustomPlugin:
def __init__(self, config):
self.model_name = config.get("model_name")
self.api_base = config.get("api_base", "http://localhost:8080/v1")
self.api_key = os.getenv(config.get("api_key_env"))
self.max_tokens = config.get("max_tokens", 512)
self.temperature = config.get("temperature", 0.7)
# Any other provider-specific initialization
def generate_response(self, messages, stream=False):
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {self.api_key}" # If your API uses this
}
payload = {
"model": self.model_name,
"messages": messages,
"max_tokens": self.max_tokens,
"temperature": self.temperature,
"stream": stream
}
try:
response = requests.post(f"{self.api_base}/chat/completions",
headers=headers,
json=payload,
stream=stream)
response.raise_for_status()
if stream:
for line in response.iter_lines():
if line:
yield json.loads(line.decode('utf-8').lstrip('data: ')) # Adjust based on stream format
else:
return response.json()['choices'][0]['message']['content'] # Adjust based on response format
except requests.exceptions.RequestException as e:
print(f"Error calling custom provider: {e}")
return None # Or raise a specific exception
Then, you’d update your .openclaw/config.json:
{
"models": {
"my-model": {
"plugin": "my_custom_provider",
"model_name": "custom-llama-7b",
"api_base": "http://my-inference-server:8080/v1",
"api_key_env": "MY_CUSTOM_API_KEY",
"max_tokens": 1024
}
},
"plugins": {
"my_custom_provider": {
"module":
Frequently Asked Questions
What is the OpenClaws Plugin Architecture?
It's a modular system designed to enhance OpenClaws' functionality. It allows developers to integrate new features, tools, or AI models seamlessly, extending the application's core capabilities without altering its main codebase.
How does the plugin architecture support 'different models'?
Plugins enable OpenClaws to integrate various computational or AI models, such as machine learning algorithms, data processing units, or specialized analytical tools. This allows users to leverage diverse model types for specific tasks within the OpenClaws ecosystem.
What are the key benefits of OpenClaws' plugin architecture?
Key benefits include enhanced flexibility, allowing users to customize OpenClaws for specific needs. It promotes innovation by enabling third-party development, ensures scalability, and keeps the core application lean while offering a vast array of extended functionalities.