OpenClaw Python SDK

Programmatically create and manage OpenClaw AI assistant instances in Docker containers.

Why This Might Be Very Helpful

This SDK lets you spin up AI assistants programmatically - no manual setup, no clicking through UIs. Think:

• Multi-tenant AI platforms - Create isolated assistant instances for each user
• AI agent swarms - Spin up dozens of specialized agents that work together
• Development/testing - Quickly create and tear down AI environments
• SaaS products - Give your users their own private AI assistant with one API call
• Research - Run experiments with different models/prompts in parallel
• CI/CD pipelines - Automated AI assistant deployment

Each instance runs in its own Docker container with persistent storage, browser automation, and multi-channel support (webchat, Telegram, Discord, Slack, etc.).

Installation

pip install git+https://github.com/AnasMaar/openclaw-python-sdk.git

Requirements

• Python 3.9+
• Docker installed and running

Quick Start

from openclaw_sdk import OpenClaw

# Initialize the SDK
claw = OpenClaw()

# Create an AI assistant instance
instance = claw.create(
    name="my-assistant",
    model="openai/gpt-5.2",
    port=18789,
    env={"OPENAI_API_KEY": "sk-..."},
    agent_prompt="You are a helpful coding assistant."
)

print(f"Access your assistant at: {instance.url}")
print(f"Auth token: {instance.token}")

Usage

Create an Instance

from openclaw_sdk import OpenClaw

claw = OpenClaw()

# Basic creation
instance = claw.create(
    name="my-bot",
    model="openai/gpt-5.2",
    port=18789,
    env={"OPENAI_API_KEY": "sk-..."}
)

# With custom agent prompt
instance = claw.create(
    name="code-helper",
    model="anthropic/claude-opus-4.6",
    port=18790,
    env={"ANTHROPIC_API_KEY": "sk-ant-..."},
    agent_prompt="""You are an expert Python developer.
Help users write clean, efficient code."""
)

# With channel configuration
instance = claw.create(
    name="multi-channel-bot",
    model="openai/gpt-5.2",
    port=18791,
    env={
        "OPENAI_API_KEY": "sk-...",
        "TELEGRAM_BOT_TOKEN": "..."
    },
    channels={
        "webchat": True,
        "telegram": True,
        "discord": False
    }
)

Manage Instances

# List all instances
for inst in claw.list():
    print(f"{inst['name']}: {inst['status']}")

# Get an existing instance
instance = claw.get("my-bot")

# Stop an instance
claw.stop("my-bot")

# Start a stopped instance
claw.start("my-bot")

# Restart (picks up .env changes)
claw.restart("my-bot")

# View logs
logs = claw.logs("my-bot", tail=50)
print(logs)

# Remove an instance
claw.remove("my-bot")

# Remove instance and delete all data
claw.remove("my-bot", remove_data=True)

Custom Data Directory

# Store instance data in a custom location
claw = OpenClaw(data_dir="/path/to/my/instances")

Full Configuration

# Pass a complete OpenClaw config
instance = claw.create(
    name="advanced-bot",
    env={"OPENAI_API_KEY": "sk-..."},
    config={
        "agent": {"model": "openai/gpt-5.2"},
        "gateway": {
            "bind": "lan",
            "port": 18789,
            "auth": {"mode": "token"}
        },
        "channels": {
            "webchat": {"enabled": True},
            "telegram": {"enabled": False}
        },
        "browser": {"enabled": True},
        "agents": {
            "defaults": {
                "sandbox": {"mode": "off"}
            }
        }
    }
)

Supported Models

• openai/gpt-5.2
• openai/gpt-4o
• anthropic/claude-opus-4.6
• anthropic/claude-sonnet-4-20250514
• And more...

Instance Data Structure

Each instance stores data in {data_dir}/{instance_name}/:

my-assistant/
├── .env                 # Environment variables
├── config/
│   ├── openclaw.json    # Instance configuration
│   ├── identity/        # Device authentication
│   ├── agents/          # Agent sessions
│   └── ...
├── workspace/
│   └── AGENTS.md        # Agent prompt
└── credentials/         # API credentials

Environment Variables

Pass API keys and configuration through the env parameter:

instance = claw.create(
    name="my-bot",
    model="openai/gpt-5.2",
    env={
        # Required (one of these)
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",

        # Optional channel tokens
        "TELEGRAM_BOT_TOKEN": "...",
        "DISCORD_BOT_TOKEN": "...",
        "SLACK_BOT_TOKEN": "...",
    }
)

OpenClawInstance Object

The create() and get() methods return an OpenClawInstance object:

instance = claw.create(...)

instance.id        # Docker container ID
instance.name      # Container name
instance.url       # Gateway URL (e.g., http://localhost:18789)
instance.token     # Authentication token
instance.data_dir  # Path to instance data
instance.port      # Gateway port

# Convert to dict
instance.to_dict()

Building the Docker Image

The SDK automatically builds the Docker image on first use. To force a rebuild:

claw.rebuild_image()

Contributing

This is still a new repository, and contributors are welcome to help enhance both the OpenClaw framework and this OpenClaw SDK.

• Report bugs - Found something broken? Open an issue
• Suggest features - Have an idea? Let's discuss it
• Submit PRs - Bug fixes, new features, documentation improvements

Acknowledgments

This project is built on top of the OpenClaw project. All credit for the core AI assistant framework goes to the OpenClaw team and its contributors.

License

MIT