Install & Compatibility
Where this runs
tested against v2026.3.20 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
92MB installed
● package 92MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ from openclaw import Agent
✗ from openclaw import Agent
This quickstart demonstrates how to initialize an OpenClaw agent, define a simple tool using the `@tool` decorator, and run the agent asynchronously. It uses an environment variable for the API key for security. The agent will connect to the CMDOP platform and make its defined tools available.
import asyncio
import os
from openclaw.agent import Agent
from openclaw.config import OpenClawConfig
from openclaw.tools import tool
# Define a tool for the agent to use
@tool
def greet(name: str) -> str:
"""Greets the given name."""
return f"Hello, {name}!"
async def main():
# Configure OpenClaw agent
# Obtain your API key from the CMDOP platform
config = OpenClawConfig(
api_key=os.environ.get("OPENCLAW_API_KEY", "sk-DUMMY_API_KEY"),
agent_id="my-first-openclaw-agent"
)
# Initialize the agent with the configuration
agent = Agent(config)
print(f"OpenClaw Agent '{config.agent_id}' running...")
# The agent.run() method is asynchronous and connects to the CMDOP platform
await agent.run()
print("Agent stopped.")
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Agent interrupted and stopping.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingOpenClaw has a strict, exact version dependency on `cmdop-sdk`. Mismatching versions (e.g., installing `cmdop-sdk` manually with a different version) will lead to runtime errors, unexpected behavior, or even `ImportError`.fixAlways install `openclaw` directly via `pip install openclaw`. This ensures the correct `cmdop-sdk` version is pulled. Avoid manually installing or upgrading `cmdop-sdk` independently of `openclaw` unless explicitly instructed.
affects: All versions where `cmdop-sdk` is an exact dependency.
gotchaKey agent methods, particularly `agent.run()`, are asynchronous coroutines. Failing to `await` these methods or run them within an `asyncio` event loop will result in `TypeError: 'coroutine' object is not awaited` or the agent simply not starting.fixWrap your agent execution logic in an `async def` function and call it using `asyncio.run()`. Ensure all calls to `agent.run()` and other async methods are preceded by `await`.
affects: All versions where agent methods are async.
gotchaIncorrect or missing `api_key` or `agent_id` in `OpenClawConfig` will prevent the agent from authenticating and connecting to the CMDOP platform, leading to connection failures or API errors.fixEnsure the `OPENCLAW_API_KEY` environment variable is correctly set with a valid key from your CMDOP account. Verify that the `agent_id` is unique and adheres to CMDOP's naming conventions. For local development, `base_url` might also need to be configured.
affects: All versions.
Audit
Dependencies
cmdop-sdkrequiredOpenClaw is built on and strictly tied to the CMDOP SDK, requiring a matching version for proper functionality.
requestsrequiredUsed for making HTTP requests to the CMDOP platform.
pydanticrequiredUsed for data validation and settings management within the library.