OpenClaw

Common errors

• TypeError: object NoneType can't be used in 'await' expression

  cause You are calling an asynchronous OpenClaw method (like `agent.run()`) without `await` or outside an `async` context.
  fix Ensure `agent.run()` is awaited inside an `async def` function, and that function is executed with `asyncio.run()`.

• cmdop_sdk.exceptions.APIError: Authentication Failed: Invalid API Key

  cause The `api_key` provided in your `OpenClawConfig` is incorrect, expired, or missing, preventing authentication with the CMDOP platform.
  fix Double-check the value of your `OPENCLAW_API_KEY` environment variable or the `api_key` parameter in `OpenClawConfig`. Obtain a valid API key from your CMDOP account settings.

• ModuleNotFoundError: No module named 'openclaw'

  cause The `openclaw` package is not installed in your current Python environment or the environment is not activated.
  fix Activate your virtual environment (if using one) and run `pip install openclaw`. If you have multiple Python installations, ensure you're using the correct `pip` associated with your project's Python interpreter.

Warnings

• breaking OpenClaw 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`.
  Fix: Always 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.
• gotcha Key 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.
  Fix: Wrap 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`.
• gotcha Incorrect 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.
  Fix: Ensure 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.

Install

• pip install openclaw Install OpenClaw

Imports

• Agent

  from openclaw.agent import Agent

• OpenClawConfig

  from openclaw.config import OpenClawConfig

• tool
  wrong:

  from openclaw.tools import register_tool

  correct:

  from openclaw.tools import tool

  While `register_tool` exists, the `@tool` decorator is the idiomatic way to define tools in OpenClaw.

Quickstart

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}")