Hosted Hermes and OpenClaw API

The short answer

OpenClaw Launch has a REST API at https://openclawlaunch.com/api/v1. One call creates a bot in its own container, and further calls start it, stop it, message it, read its files and connect its chat channels. Any signed-in account can create a key, and you switch on billing by saving a card. You then pay $0.007 an hour for a Small bot from a prepaid balance, with no deploy fee.

What this API is for

This is a provisioning API: it creates and manages many always-on bots, and each one keeps its memory, files and channels between calls. That suits a product where every customer needs their own assistant. If you only need to start one short job and collect the result, a task-runner service is simpler.

Get a key and switch on billing

Sign in, open the dashboard, go to Build & Resell, and create a key on the API Keys tab. Your first key comes with $1 of free credit, but the credit alone does not switch the account on. Save a card under Build & Resell, Billing, or hold an active paid plan. Until then, creating a bot answers 402. Every request sends the key as a bearer token:

export OCL_KEY="…"
export BASE=https://openclawlaunch.com/api/v1

Create a bot

Hermes Agent is shown here. Change the framework value to openclaw for an OpenClaw bot.

BOT=$(curl -s -X POST $BASE/instances \
  -H "Authorization: Bearer $OCL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"framework":"hermes","size":"lite",
       "assistant_name":"Nova","timezone":"Europe/London",
       "client_ref":"customer-42"}' | jq -r .id)

That saves the bot's id for the calls below. The full response looks like this (trimmed):

{ "id": "<uuid>", "status": "starting", "framework": "hermes", "trial": false }

Most creates claim a warm container and are ready in seconds. An empty pool means a cold start of roughly 30 to 90 seconds. Poll until the status reads running; the other values are creating, starting, stopped, sleeping, error and deleted.

curl $BASE/instances/$BOT -H "Authorization: Bearer $OCL_KEY"

Three fields are worth setting from the start:

• client_ref makes a retry safe. Creating a bot can outlast a client timeout, and sending the same value returns the bot from the first attempt instead of creating a second one.
• timezone takes an IANA name. Without it the bot runs on UTC, including its scheduled jobs.
• assistant_name cannot contain “OpenClaw” or “Hermes”.

Give it a model

Hosting and AI usage are separate, so decide who pays for tokens before the first message. On a Hermes bot, point it at any OpenAI-compatible endpoint once it is running. That endpoint is billed, not your balance, and the bot restarts for a few seconds:

curl -X PUT $BASE/instances/$BOT/hermes-profile \
  -H "Authorization: Bearer $OCL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":{"base_url":"https://openrouter.ai/api/v1",
                "api_key":"…","model":"<model id>"}}'

An OpenClaw bot sets this on create instead: pass model_key and model_key_provider, or add an Agnes key or an OpenRouter provisioning key under Build & Resell first.

Send it a message

/responses streams the agent's reply as server-sent events. The agent can use its tools and memory during the turn, so a reply can take much longer than a plain model call.

curl -N -X POST $BASE/responses \
  -H "Authorization: Bearer $OCL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"'$BOT'","input":"Hello","session_id":"customer-42"}'

Keep session_id stable, one per customer or thread. Without it, an OpenClaw bot starts a new session on every request and a Hermes bot chooses the session itself, so your code no longer controls which conversation continues.

Use it from an OpenAI-compatible app

An app that already speaks the OpenAI format does not need /responses. Turn on the bot's endpoint:

curl -X POST $BASE/instances/$BOT/endpoint \
  -H "Authorization: Bearer $OCL_KEY"

The reply holds a base_url, a model name and an api_key. A GET on this path never shows the key, so store it now. The endpoint is server-to-server by default. To call it from a browser, send allowed_origin with your one https origin. A DELETE on the same path turns the endpoint off at once.

Connect a chat channel

A bot can answer on Telegram, Discord and other platforms, also set up by API:

curl -X POST $BASE/instances/$BOT/channels \
  -H "Authorization: Bearer $OCL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"connect","platform":"telegram","bot_token":"…"}'

The call checks the token, then applies it in the background because the bot has to restart. It answers applying: true; confirm with a GET on the same path. When your customer first messages the bot on Telegram, it replies with a pairing code, and you submit that code with pairing_approve. Strangers who find the bot cannot use it. WhatsApp and WeChat use the qr action instead of a token.

Hermes and OpenClaw differences

The calls above work on both. These parts do not:

What it costs

Keep at least $1 on the balance to create a bot. An account switched on by a paid plan with no card instead needs enough balance to run all its bots for 24 hours. A test bot you delete after an hour costs about a cent, but the meter stops only when a bot is deleted, not when it is stopped. GET /balance shows what is left, so your code can warn you before it runs low.

Limits to plan around

• 25 live bots by default on a prepaid balance. Ask support if you need more.
• 30 creates and 300 responses a minute per key.
• 120 read requests a minute, shared across read endpoints. A 429 means slow down.
• Revoking the API key that created a bot closes that bot's endpoint, so rotate keys with care.

Common errors

When to use something else

• You already have a bot and only want to call it from code: use its chat API.
• You want one bot for yourself and no code: managed Hermes hosting is simpler.
• You want to sell bots but not build an app: a ready-made storefront gets you there without this API.
• You want a coding box that runs Codex or Claude Code: the Developer API covers coding workspaces.

FAQ

Related Guides

• Resell AI Agents — the wider reselling walkthrough
• White-Label Hermes Agent Hosting — sell Hermes bots under your brand
• White-Label OpenClaw Hosting — the same for OpenClaw, with client-owned keys
• Build & Resell, in full — billing, limits and your clients' experience