CloudBot.ai

Documentation

Setup guides, configuration reference, API endpoints, and practical troubleshooting for CloudBot voice agents.

Quick start

CloudBot gives your OpenClaw agent a managed LiveKit voice front-end. The fastest path is: sign up, copy your tenant API key, install the plugin, add it to openclaw.json, then restart OpenClaw.

Your dashboard API key looks like cb_live_... and is the main credential used to bind your backend to CloudBot.

  • Sign up and verify your account
  • Copy your CloudBot tenant API key from the dashboard
  • Install the cloudbot plugin on your OpenClaw instance
  • Add gatewayUrl and apiKey to your config
  • Restart OpenClaw and test the connection from the dashboard
openclaw plugins install @timekeeperbank/openclaw-cloudbot

# openclaw.json
{
  "extensions": {
    "cloudbot": {
      "gatewayUrl": "https://rtc.cloudbot.ai",
      "apiKey": "cb_live_YOUR_KEY_HERE"
    }
  }
}

Connect any backend agent

CloudBot can connect OpenClaw or another backend AI agent through a simple HTTPS gateway contract. The customer-facing setup page includes a scannable QR code, the required gateway endpoints, and an agent-readable skill.

Setup page: https://cloudbot.ai/connect-agent

Agent skill: https://cloudbot.ai/api/connect-agent/skill

  • Register the backend gateway URL, shared API key, backend agent, and frontend routes in Dashboard -> Agent Routing
  • Implement GET /cloudbot/voice/health for health checks
  • Implement POST /cloudbot/voice/inbound for message relay
  • Preserve request_id, tenant_id, room_name, frontend_agent_id, route_id, backend_agent_id, response_mode, and worker_id
  • Use runtime backend-events logging so Recent API Traffic stays synced
POST /cloudbot/voice/inbound
X-API-Key: <shared_gateway_key>

{
  "message": "Do the backend work the user asked for.",
  "route_id": "frontend_backend_route_uuid",
  "backend_agent_id": "backend_agent_profile_uuid",
  "external_agent_id": "n8n_workflow_or_worker_id",
  "worker_id": "kw1",
  "tenant_id": "tenant_slug_or_id",
  "room_name": "cb_tenant_1720000000",
  "frontend_agent_id": "frontend_voice_agent_id",
  "request_id": "cbbe_1720000000_ab12cd34",
  "response_mode": "sync",
  "wait_for_reply": true
}

How it works

Your caller connects to CloudBot over WebRTC. CloudBot dispatches the session to a hosted voice worker, which handles speech recognition, voice synthesis, and fast conversational turns.

When the conversation needs tools, memory, or deeper reasoning, the worker relays the request through the cloudbot plugin to your OpenClaw instance.

[Phone / Browser]
    ↓ WebRTC
[CloudBot LiveKit]
    ↓
[Hosted voice worker]
    ↓
[cloudbot plugin on your OpenClaw instance]
    ↓
[Your agent, tools, memory, sub-agents]

Dashboard guide

The dashboard is where customers configure their Cloud voice agent, personality, memory, sounds, usage, and billing.

  • Overview: connection state, usage, and recent activity
  • Settings: agent name, greeting, timezone, notifications, retention
  • Personality: system prompt and soul/personality text
  • Voice: TTS voice selection and uploaded sounds
  • Memory: persistent context loaded before sessions
  • Models: primary and fallback model configuration
  • API Keys: masked credentials for STT, TTS, gateway, and BYOK flows
  • Billing: subscription status and monthly usage

API reference

All tenant API requests require X-Tenant-API-Key or an equivalent tenant_api_key parameter.

Base URL: https://rtc.cloudbot.ai:8085

GET  /api/config
PUT  /api/config
GET  /api/prompt
PUT  /api/prompt
GET  /api/soul
PUT  /api/soul
GET  /api/memory
PUT  /api/memory

GET  /api/sounds
POST /api/sounds/{type}
DELETE /api/sounds/{type}

GET  /api/config/models
PUT  /api/config/models
GET  /api/config/keys
PUT  /api/config/keys
POST /api/config/keys/validate

GET  /api/usage
GET  /api/subscription
POST /api/usage/session

GET  /api/transcripts
GET  /api/transcripts/{filename}

GET  /api/stats
POST /api/register-backend
GET  /api/tenant/status
POST /api/tenant/health-check

Plugin setup

The cloudbot plugin is what lets your OpenClaw backend receive routed voice requests from CloudBot.

The required settings are gatewayUrl and apiKey. Dashboard -> Agent Routing decides which frontend agents can call each backend agent.

  • Use Agent Routing to bind frontend agents to backend agents
  • Use channelId cloudbot unless you have a special routing reason
  • Use timeout 130 seconds unless you have a known faster backend
  • Verify install with /cloudbot/health on your OpenClaw gateway
{
  "extensions": {
    "cloudbot": {
      "gatewayUrl": "https://rtc.cloudbot.ai",
      "apiKey": "cb_live_YOUR_KEY",
      "externalAgentId": "kenny",
      "responseMode": "sync",
      "channelId": "cloudbot",
      "timeout": 130
    }
  }
}

Plans and limits

CloudBot usage is enforced at the voice-agent layer before requests reach the backend.

  • Free: 100 minutes per month
  • Personal: 5,000 minutes per month
  • Pro: 25,000 minutes per month
  • Enterprise: unlimited or custom
  • API rate limit: 120 requests per minute per IP
  • Relay rate limit: 60 requests per minute per tenant
  • Circuit breaker: repeated backend failures trigger temporary fail-fast protection

Troubleshooting

If your backend is unreachable, CloudBot will mark it unhealthy and eventually open the relay circuit breaker to avoid repeated slow failures.

  • Gateway unreachable: verify your OpenClaw instance is online and accessible from CloudBot
  • No voice response: check tenant status, usage limits, and STT/TTS keys
  • Circuit open: your backend has been failing consistently, wait for automatic retry and fix the root issue
  • Plugin not receiving messages: verify apiKey, gateway URL, health path, and Agent Routing bindings
  • Audio quality issues: try a different TTS voice and confirm LiveKit connectivity is stable