How to Get Started with the OpenClaw Python SDK

Many developers interact with AI agents through chat interfaces or CLI commands. The OpenClaw Python SDK offers direct control for building complex automation workflows. By integrating into your Python codebase, you can manage multi-agent systems, handle persistent storage, and execute tools dynamically.

The SDK connects your application logic to the Fast.io infrastructure. This gives access to 251 Model Context Protocol (MCP) tools without managing low-level API calls. Whether you are building a customer support bot, a data analysis pipeline, or an automated content generation system, the SDK simplifies connecting agents to real-world data and actions.

Developers choose the Python SDK because it allows for:

• Dynamic Configuration: Create agents and workspaces based on user input.
• Event-Driven Architecture: Trigger agent actions from webhooks or database changes.
• Easy Integration: Add agent capabilities directly into existing Django, Flask, or FastAPI applications.

Make sure you have Python 3.9 or higher installed on your system. You will also need a Fast.io account to generate your API keys and manage your agent's resources.

To install the OpenClaw SDK, use pip:

pip install openclaw

Once installed, you need to configure your authentication. Go to your Fast.io dashboard to generate a new API key with the necessary permissions for agent management and file storage access.

Set your API key as an environment variable to keep it secure:

export OPENCLAW_API_KEY="your_api_key_here"

You can verify your installation by running a simple check in your Python shell:

import openclaw
print(openclaw.__version__)

This confirms the library is installed and ready for use. Next, we will initialize the client and create our first agent.

The main entry point for the SDK is the OpenClawClient. This client manages the connection to the Fast.io platform and handles authentication when the environment variable is set.

Here is how to initialize the client and create a basic agent:

from openclaw import OpenClawClient

# Initialize the client
client = OpenClawClient()

# Create a new agent with specific capabilities
agent = client.agents.create(
    name="DataAnalyst_01",
    model="claude-3-5-sonnet",
    description="An agent designed to analyze financial reports.",
    tools=["calculator", "file_search", "python_interpreter"]
)

print(f"Agent created with ID: {agent.id}")

When you create an agent, you define its identity and the tools it can access. In this example, we've given the agent a calculator, file search capabilities, and a Python interpreter. These tools are powered by the underlying MCP protocol, giving the agent strong capabilities immediately.

The agent ID returned is important for subsequent operations, such as assigning tasks, managing its memory, or retrieving its execution logs.

A key feature of OpenClaw is its integration with Fast.io's persistent storage. Unlike ephemeral agents that lose their context after a session, OpenClaw agents can keep long-term memory and access files across different runs.

To connect storage to your agent, you need to create a workspace and mount it:

# Create a dedicated workspace for the agent
workspace = client.workspaces.create(
    name="Financial_Reports_2026",
    intelligence_mode=True
)

# Mount the workspace to the agent
agent.mount_workspace(workspace.id)

# Upload a file for the agent to analyze
client.files.upload(
    file_path="./data/q1_report.pdf",
    workspace_id=workspace.id
)

By enabling intelligence_mode, the workspace automatically indexes all uploaded files. This allows the agent to perform semantic searches and retrieval-augmented generation (RAG) tasks on documents without extra configuration.

This persistence layer is important for building agents that can learn and adapt over time, as they can reference past work and gather knowledge in their dedicated workspaces.

Start Building with OpenClaw Today

Get your API key and start automating your workflows with the power of Python and autonomous agents.

Get API Key

With the agent configured and storage connected, you can now assign tasks. The SDK provides a method to send instructions and receive structured responses.

# Define a task for the agent
task = "Analyze the Q1 report and summarize the key revenue drivers."

# Execute the task
execution = agent.run(task)

# Print the result
print(execution.output)

# Access the thought process (if enabled)
for step in execution.steps:
    print(f"Thought: {step.thought}")
    print(f"Action: {step.tool_call}")

The run method is synchronous by default, blocking until the agent completes the task. For long-running operations, you can use agent.run_async() to receive a job ID and poll for status updates or configure a webhook for notification upon completion.

The execution object contains the final answer and the "thought chain" showing how the agent arrived at its conclusion. This transparency is helpful for debugging and trusting the agent's output in production environments.

For production applications, simple task execution is often not enough. You need to handle concurrency and real-time events. The OpenClaw Python SDK includes built-in support for these patterns.

Webhooks allow your application to react when an agent finishes a task or requires human intervention.

client.webhooks.create(
    url="https://api.yourdomain.com/callbacks/agent-events",
    events=["task.completed", "task.failed", "human.required"]
)

Multi-Agent Locks are important when multiple agents share the same workspace. They prevent race conditions where two agents might try to edit the same file at the same time.

lock = client.locks.acquire(
    resource=f"workspaces/{workspace.id}/financial_summary.md",
    ttl=300  # Lock for 5 minutes
)

try:
    # Perform sensitive file operations
    agent.run("Update the financial summary with Q2 data.")
finally:
    lock.release()

Using these features ensures your agent system is stable and safe for production use, handling distributed system complexities automatically.