Docs / Developers / Architecture

Architecture overview

CloudyBot is a hosted assistant platform: clients talk to a CloudyBot API (Node.js/Express) that owns auth, billing, threads, files, and policy. An optional OpenClaw gateway runs the agent loop (tools, skills, channels). Hub: developers.

Two runtime components

• CloudyBot API (port 3000) — sessions, POST /chat, Stripe, moderation, AI credit metering, SQLite persistence, Browserbase browser APIs, integration token storage.
• OpenClaw gateway (port 18789, optional) — orchestrates multi-turn tool use; calls back to the API for model completions when the model route is cloudybot/*. If the gateway is down, the API can fall back to a built-in lean agent path.

Dashboard chat always starts at the API. WhatsApp/Telegram may enter via webhooks or native OpenClaw channels depending on deployment — both paths still enforce the same user limits server-side.

Dashboard chat flow (simplified)

1. Client sends POST /chat with Bearer token, threadId, and message (optional attachments).
2. API validates session, thread ownership, rate limits, moderation, and remaining AI credits.
3. API loads thread memory (summary + recent turns + pinned facts), file context from ~/files/, and enabled skills.
4. API streams the run to OpenClaw (SSE) or fallback agent; tool calls may invoke browser, Notion, email, etc.
5. Assistant reply is persisted to the conversation store; usage counters update.

Async UI updates may also arrive on GET /api/events (SSE) with a pending-message fallback for reconnect gaps — see API reference.

Identity and sessions

• userId — from authenticated session only; never trust body userId on POST /chat.
• threadId — scopes rolling memory and pinned facts; create via POST /api/threads.
• OpenClaw session key — dashboard uses a compound id {userId}--{threadId} so agent state does not bleed across threads.

Assistant runs

Each execution assembles system instructions, Specialist persona (if any), saved credentials (injected at runtime, not echoed to users), tool schemas for enabled skills, and recent conversation. Browser work attaches a managed cloud browser (Browserbase) — not a browser on the user’s laptop. Browser minutes are metered separately from AI credits.

Schedules and workflows

Cron jobs fire stored duty prompts for Specialists or threads. Credentials load from encrypted storage at execution time. Multi-step pipelines chain duties via next_job_id or in-run trigger_duty — see chaining tasks. Recipe deploy hires Specialists and wires schedules in one transaction.

Integrations

First-party connectors (Notion, Google Sheets, GitHub, email, calendar, WhatsApp) call provider APIs with OAuth or API keys saved under Settings → Connect. Skills are gated per Specialist; missing credentials fail the tool with a clear error rather than silent noop.

Data stores (conceptual)

• SQLite (cloudybot.db) — users, threads, conversations, usage, billing, credentials metadata.
• File workspace — per-user files on disk + user_files index; agents read/write via file_* tools.
• OpenClaw session files — .jsonl transcripts per session key; rotated on idle/size caps.

Related: Memory model · API reference · Security · repo docs/ARCHITECTURE.md (full engineering diagram).