This page is the authoritative reference for the OpenClaw Python and Node.js SDKs. Each entry lists every parameter, its type, default value and a short description. Bookmark it β€” you'll come back often.

Base configuration

All clients share the same environment variables:

OPENCLAW_API_KEY      # required β€” your secret key
OPENCLAW_BASE_URL     # optional β€” defaults to https://api.openclaw.ai
OPENCLAW_TIMEOUT      # optional β€” request timeout in seconds (default 60)
OPENCLAW_MAX_RETRIES  # optional β€” retries on 5xx (default 3)

The Agent class

Constructor

Agent(
    name: str,
    model: str = "openclaw-1",
    instructions: str | None = None,
    tools: list[Tool] | None = None,
    temperature: float = 0.7,
    max_tokens: int | None = None,
    memory: Memory | None = None,
    metadata: dict | None = None,
)

Parameters

  • name (str, required) β€” Human-readable identifier, used in logs and tracing.
  • model (str, default openclaw-1) β€” The underlying model. Available: openclaw-1, openclaw-1-mini, openclaw-embed.
  • instructions (str | None) β€” The system prompt that primes the agent's behaviour.
  • tools (list[Tool]) β€” Tool definitions the agent can invoke.
  • temperature (float, default 0.7) β€” Sampling temperature. 0 = deterministic, 1 = maximum creativity.
  • max_tokens (int | None) β€” Cap on tokens generated per call.
  • memory (Memory | None) β€” A memory backend (in-memory, Redis, SQLite…).
  • metadata (dict | None) β€” Custom key/value pairs attached to every trace.

Methods

agent.run(prompt, **opts) β†’ Result

Synchronous single-shot call.

result = agent.run("Summarise the article.", timeout=30)
print(result.text)        # final assistant message
print(result.usage)       # {"prompt_tokens": 42, "completion_tokens": 88}

agent.stream(prompt, **opts) β†’ AsyncIterator[Chunk]

Stream tokens as they are produced. Ideal for chat UIs.

async for chunk in agent.stream("Write a haiku about servers"):
    print(chunk.delta, end="", flush=True)

agent.chat(messages, **opts) β†’ Result

Multi-turn conversation. messages is a list of {role, content} dicts.

result = agent.chat([
    {"role": "user",      "content": "Hi, who are you?"},
    {"role": "assistant", "content": "I'm a research assistant."},
    {"role": "user",      "content": "Tell me about black holes."},
])

Tools

Tools let agents call your own code. Define one with the @tool decorator:

from openclaw import tool

@tool(description="Look up the current weather for a city")
def get_weather(city: str, unit: str = "celsius") -> dict:
    # your implementation here
    return {"city": city, "temp": 21, "unit": unit}

agent = Agent(name="weather-bot", tools=[get_weather])

Errors

All SDK errors inherit from openclaw.OpenClawError:

  • AuthenticationError β€” invalid or missing API key (HTTP 401).
  • RateLimitError β€” too many requests; respect the Retry-After header.
  • InvalidRequestError β€” malformed payload (HTTP 400).
  • ServerError β€” upstream failure (HTTP 5xx). SDK retries automatically.
  • TimeoutError β€” request exceeded OPENCLAW_TIMEOUT.
AdvertisementAd slot (in-article / responsive)

Rate limits

Default limits (per API key, per minute):

  • openclaw-1: 60 requests / 200 000 tokens
  • openclaw-1-mini: 600 requests / 2 000 000 tokens

Need higher? Contact sales.

Authentication

All requests must include your API key in the Authorization header. The SDK handles this automatically once OPENCLAW_API_KEY is set. If you prefer to manage headers yourself (for example, when proxying through your own backend), pass the key explicitly when constructing the client:

from openclaw import OpenClaw

client = OpenClaw(api_key="sk-...", base_url="https://api.openclaw.ai")

Never expose your key in client-side code, public repositories or browser bundles. Treat it like a password and rotate it immediately if you suspect it has leaked.

Request signing (advanced)

For high-security deployments, enable HMAC request signing by setting OPENCLAW_SIGNING_SECRET. Each request will include an X-OpenClaw-Signature header that your webhook handlers can verify using the same secret.

Response format

Every successful API call returns a JSON object with at minimum a result field. Helper methods on the SDK (like result.text) extract the most useful pieces for you, but the raw payload is always available on result.raw for custom parsing.

{
  "id": "resp_8f3a1c...",
  "model": "openclaw-1",
  "result": {
    "role": "assistant",
    "content": "Black holes are regions of spacetime..."
  },
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 88,
    "total_tokens": 130
  }
}

Versioning and stability

The SDK follows semantic versioning. Minor releases add backwards-compatible features; major releases may introduce breaking changes with at least six months of deprecation notices published in the changelog. Pin your dependency to a major version to avoid surprises:

pip install "openclaw>=2,<3"     # Python
npm install "openclaw@^2.0.0"   # Node.js

Where to next

Now that you've seen every parameter and error code, head over to the prompt engineering tutorial to learn how to get the most out of your agents, or browse the full tutorials list for hands-on examples covering RAG pipelines, function calling and production observability.

Quick checklist

  • Set OPENCLAW_API_KEY in your environment before importing the SDK.
  • Pick the smallest model that solves your task to control cost.
  • Catch RateLimitError and back off using the Retry-After hint.
  • Log every result.id so support can correlate traces quickly.