OpenClaw /v1/chat API Reference

1. Introduction

OpenClaw is UBOS’s open‑source conversational AI engine that powers intelligent chat experiences. This reference article walks you through every technical detail of the /v1/chat endpoint – from authentication to error handling – so you can integrate it with confidence.

Whether you’re a marketing manager drafting API docs or a technical writer building developer portals, the sections below are MECE‑structured for quick lookup and easy quoting by AI assistants.

2. Endpoint Overview (/v1/chat)

3. Authentication

OpenClaw uses Bearer Token authentication. Obtain your API key from the About UBOS dashboard and include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Tokens are scoped to the Enterprise AI platform by UBOS and can be regenerated at any time.

4. Request Schema

The request body must be a valid JSON object. Below is the full schema with field descriptions.

{
  "model": "string",               // Identifier of the language model (e.g., "gpt-4o")
  "messages": [                   // Ordered list of conversation turns
    {
      "role": "system|user|assistant",
      "content": "string"
    }
  ],
  "temperature": 0.0,             // Optional: creativity control (0‑2)
  "max_tokens": 1024,             // Optional: max tokens in response
  "stream": false,                // Optional: true for Server‑Sent Events
  "metadata": {                   // Optional: custom key‑value pairs
    "session_id": "string"
  }
}

• model – Required. Choose a model supported by OpenClaw. See the OpenAI ChatGPT integration page for compatible versions.
• messages – Required. The conversation history. The first system message can set behavior.
• temperature – Optional. Lower values make output deterministic; higher values increase creativity.
• max_tokens – Optional. Limits the length of the generated reply.
• stream – Optional. When true, the API streams partial tokens.
• metadata – Optional. Useful for tracing sessions in the Workflow automation studio.

5. Response Schema

5.1 Success Response (200 OK)

{
  "id": "string",                     // Unique request identifier
  "object": "chat.completion",
  "created": 1697041234,             // Unix timestamp
  "model": "string",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "string"
      },
      "finish_reason": "stop|length|content_filter"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

5.2 Error Responses

Errors follow the standard JSON‑API error object. Common HTTP status codes:

{"error":{"code":400,"message":"Invalid request payload"}}

{"error":{"code":401,"message":"Invalid API key"}}

{"error":{"code":429,"message":"Rate limit exceeded. Try again later."}}

{"error":{"code":500,"message":"Unexpected server error"}}

6. Usage Limits

OpenClaw enforces a tiered quota system based on your subscription plan. The default free tier provides:

• Up to 60 requests per minute (burstable to 120).
• Maximum 2 000 tokens per minute across all requests.
• Daily limit of 100 000 tokens.

For higher throughput, upgrade via the UBOS pricing plans. Enterprise customers can request dedicated capacity through the UBOS partner program.

7. Example Code Snippets

7.1 Python (requests)

import os
import requests
import json

API_KEY = os.getenv("OPENCLAW_API_KEY")
ENDPOINT = "https://api.openclaw.ubos.tech/v1/chat"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain the benefits of AI marketing agents."}
    ],
    "temperature": 0.7,
    "max_tokens": 500
}

response = requests.post(ENDPOINT, headers=headers, json=payload)

if response.status_code == 200:
    data = response.json()
    reply = data["choices"][0]["message"]["content"]
    print("Assistant:", reply)
else:
    print("Error:", response.status_code, response.text)

7.2 JavaScript (fetch)

const apiKey = process.env.OPENCLAW_API_KEY;
const endpoint = "https://api.openclaw.ubos.tech/v1/chat";

async function chat() {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-4o",
      messages: [
        {role: "system", content: "You are a concise AI copywriter."},
        {role: "user", content: "Write a short tagline for a SaaS startup."}
      ],
      temperature: 0.5,
      max_tokens: 50
    })
  });

  if (!response.ok) {
    const err = await response.json();
    console.error("API error:", err);
    return;
  }

  const data = await response.json();
  const reply = data.choices[0].message.content;
  console.log("Assistant:", reply);
}

chat();

8. Error Handling

Robust client code should anticipate the four main error families defined in the response schema. A practical pattern:

# Python example
if response.status_code == 429:
    # Rate‑limit – back‑off exponentially
    wait = int(response.headers.get("Retry-After", "1"))
    time.sleep(wait)
elif response.status_code >= 500:
    # Server error – retry a few times
    for i in range(3):
        time.sleep(2 ** i)
        retry = requests.post(...)
else:
    # 4xx client errors – log and abort
    logger.error(f"Request failed: {response.text}")

In JavaScript, use try / catch with response.ok checks and exponential back‑off via setTimeout.

9. Internal Links

Deploy OpenClaw on UBOS with a single click using the OpenClaw hosting on UBOS page. For a broader view of the platform, explore the UBOS platform overview. If you’re a startup, the UBOS for startups guide shows how to scale quickly. SMB teams benefit from UBOS solutions for SMBs, while enterprises can leverage the Enterprise AI platform by UBOS.

Build custom UI with the Web app editor on UBOS and automate workflows using the Workflow automation studio. Marketing teams love the AI marketing agents for personalized campaigns.

10. Illustrative Diagram Placeholder

*Replace the placeholder URL with the actual diagram asset when publishing.

11. Publishing Instructions

This article belongs to the OpenClaw API Reference series on the UBOS blog. Follow these steps:

1. Copy the HTML content into the CMS editor.
2. Set the SEO meta title to “OpenClaw /v1/chat API Reference – Full Guide”.
3. Add the canonical URL https://ubos.tech/blog/openclaw-v1-chat-api-reference.
4. Upload the final diagram image and replace the placeholder URL.
5. Publish and verify that the page appears in the UBOS templates for quick start navigation.