Inside Clawdbot: Core Architecture & the Gateway Control Plane

┌──────────────────────────────────────────────────────────────┐
│                      Gateway Daemon (:18789)                  │
│                                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ Telegram │  │ WhatsApp │  │ Discord  │  │  Slack   │ ...  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │              │              │              │            │
│       ▼              ▼              ▼              ▼            │
│  ┌─────────────────────────────────────────────────────┐      │
│  │               Channel Manager                        │      │
│  │          (plugin lifecycle, hot-reload)               │      │
│  └──────────────────────┬──────────────────────────────┘      │
│                          │                                      │
│  ┌───────────────────────┼───────────────────────────────┐    │
│  │                Agent Runtime                           │    │
│  │    Sessions · Models · Tools · Memory · Skills         │    │
│  └───────────────────────┬───────────────────────────────┘    │
│                          │                                      │
│  ┌───────────────────────┼───────────────────────────────┐    │
│  │            WebSocket Control Plane                     │    │
│  │   80+ RPC methods · Event broadcast · Auth · Presence  │    │
│  └───────────────────────┬───────────────────────────────┘    │
│                          │                                      │
│         ┌────────────────┼────────────────┐                    │
│         ▼                ▼                ▼                    │
│    ┌─────────┐    ┌───────────┐    ┌───────────┐              │
│    │   CLI   │    │ Control UI│    │   Nodes   │              │
│    │ (local) │    │  (WebApp) │    │(iOS/macOS)│              │
│    └─────────┘    └───────────┘    └───────────┘              │
└──────────────────────────────────────────────────────────────┘

// src/entry.ts
process.title = "clawdbot";
installProcessWarningFilter();

// Color mode
if (process.argv.includes("--no-color")) {
  process.env.NO_COLOR = "1";
  process.env.FORCE_COLOR = "0";
}

function ensureExperimentalWarningSuppressed(): boolean {
  if (isTruthyEnvValue(process.env.CLAWDBOT_NO_RESPAWN)) return false;
  if (isTruthyEnvValue(process.env.CLAWDBOT_NODE_OPTIONS_READY)) return false;

  process.env.NODE_OPTIONS = `${nodeOptions} ${EXPERIMENTAL_WARNING_FLAG}`.trim();
  const child = spawn(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
    stdio: "inherit",
    env: process.env,
  });
  attachChildProcessBridge(child);
  return true; // Parent must not continue — child takes over
}

import("./cli/run-main.js")
  .then(({ runCli }) => runCli(process.argv))

loadDotEnv({ quiet: true });
normalizeEnv();
ensureClawdbotCliOnPath();
enableConsoleCapture();     // Structured logging wrapping console.*
assertSupportedRuntime();   // Node 22+ check

import { buildProgram } from "./cli/program.js";
const program = buildProgram();  // Commander.js program

startGatewayServer(port=18789)
  ├─ Read & validate config snapshot
  │   ├─ Auto-migrate legacy config entries
  │   ├─ Validate against Zod schema
  │   └─ Auto-enable plugins from env vars
  ├─ Initialize subsystems
  │   ├─ Subagent registry
  │   ├─ Plugin registry + gateway method extensions
  │   ├─ Channel manager
  │   ├─ Node registry (iOS/Android/macOS nodes)
  │   ├─ Cron service
  │   ├─ Heartbeat runner
  │   ├─ Exec approval manager
  │   └─ Skills remote registry
  ├─ Create runtime state
  │   ├─ HTTP server(s) + optional TLS
  │   ├─ WebSocket server
  │   ├─ Client set + broadcast function
  │   └─ Canvas host handler
  ├─ Attach WS handlers (auth, routing, methods)
  ├─ Start sidecars
  │   ├─ Browser control server
  │   ├─ Plugin services
  │   └─ Channel connections
  ├─ Start service discovery (Bonjour/mDNS)
  ├─ Start Tailscale exposure (Serve/Funnel)
  ├─ Start config file watcher (hot reload)
  ├─ Start maintenance timers (tick, health, dedupe)
  └─ Return { close() } handle

const log = createSubsystemLogger("gateway");
const logCanvas = log.child("canvas");
const logDiscovery = log.child("discovery");
const logTailscale = log.child("tailscale");
const logChannels = log.child("channels");
const logBrowser = log.child("browser");
const logHealth = log.child("health");
const logCron = log.child("cron");

// Request frame (client → gateway)
{ type: "req", id: "<uuid>", method: "connect", params: { ... } }

// Response frame (gateway → client)
{ type: "res", id: "<uuid>", ok: true, payload: { ... } }
{ type: "res", id: "<uuid>", ok: false, error: { code: "...", message: "..." } }

// Event frame (gateway → client, broadcast)
{ type: "event", event: "tick", payload: { ts: 1234 }, seq: 42 }

const ajv = new Ajv({ allErrors: true, strict: false, removeAdditional: false });
export const validateConnectParams = ajv.compile<ConnectParams>(ConnectParamsSchema);
export const validateRequestFrame = ajv.compile<RequestFrame>(RequestFrameSchema);

Client connects via WebSocket
  │
  ▼
Gateway sends:  { type: "event", event: "connect.challenge",
                  payload: { nonce, ts } }
  │
  ▼
Client sends:   { type: "req", method: "connect",
                  params: ConnectParams }
  │
  ▼
Gateway validates:
  1. Protocol version negotiation (minProtocol/maxProtocol range)
  2. Role validation (operator | node)
  3. Scope resolution
  4. Device identity (Ed25519 signature + nonce verification)
  5. Auth check (token | password | tailscale | device-token)
  6. Device pairing check (is this device known?)
  7. Node command filtering (if role=node)
  │
  ▼
Gateway responds: { type: "res", id: "...", ok: true, payload: HelloOk }
  │
  ▼
Normal RPC cycle begins
  │
  ▼
Gateway sends periodic ticks every 30s for liveness

const helloOk = {
  type: "hello-ok",
  protocol: PROTOCOL_VERSION,
  server: {
    version: "2026.1.25",
    commit: "abc123",
    host: "my-server",
    connId: "<uuid>",
  },
  features: {
    methods: ["health", "agent", "chat.send", ...],   // ~80+ methods
    events: ["tick", "agent", "chat", "presence", ...], // ~14 event types
  },
  snapshot: {
    presence: [...],           // Currently connected clients
    stateVersion: { presence: 42, health: 7 },
    health: { ... },           // Cached health snapshot
  },
  canvasHostUrl: "http://...",
  auth: {
    deviceToken: "...",        // Per-device rotating token
    role: "operator",
    scopes: ["operator.admin"],
  },
  policy: {
    maxPayload: 524288,        // 512KB frame limit
    maxBufferedBytes: 1572864, // 1.5MB buffer limit
    tickIntervalMs: 30000,
  },
};

// Scope hierarchy:
// operator.admin  → full access (default for operators)
// operator.read   → read-only methods (health, status, lists)
// operator.write  → send messages, invoke agents, etc.
// operator.approvals → exec approval workflow
// operator.pairing   → device/node pairing management

export const coreGatewayHandlers: GatewayRequestHandlers = {
  ...connectHandlers,
  ...sessionsHandlers,
  ...channelsHandlers,
  ...chatHandlers,
  ...cronHandlers,
  ...configHandlers,
  ...healthHandlers,
  // ... ~20 more handler modules
};

export const GATEWAY_EVENTS = [
  "connect.challenge",      // Handshake nonce
  "agent",                  // Agent run progress/completion
  "chat",                   // WebChat streaming deltas
  "presence",               // Client connect/disconnect
  "tick",                   // Liveness heartbeat (30s)
  "shutdown",               // Gateway shutting down
  "health",                 // Health snapshot update
  "cron",                   // Cron job events
  "node.pair.requested",    // Node pairing request
  "exec.approval.requested",// Exec approval request
  // ...
];

const broadcast = (event: string, payload: unknown, opts?) => {
  const eventSeq = ++seq;  // Monotonic sequence number
  const frame = JSON.stringify({ type: "event", event, payload, seq: eventSeq });

  for (const c of params.clients) {
    if (!hasEventScope(c, event)) continue;          // Scope filtering
    const slow = c.socket.bufferedAmount > MAX_BUFFERED_BYTES;
    if (slow && opts?.dropIfSlow) continue;           // Drop non-critical
    if (slow) { c.socket.close(1008, "slow consumer"); continue; }
    try { c.socket.send(frame); } catch { /* ignore */ }
  }
};

CLAWDBOT_CONFIG_PATH       → explicit override
CLAWDBOT_STATE_DIR/clawdbot.json → state dir override
~/.clawdbot/clawdbot.json  → default

// Zod schema — runtime parsing and validation
export const ClawdbotSchema = z.object({
  meta: z.object({
    lastTouchedVersion: z.string().optional(),
    lastTouchedAt: z.string().optional(),
  }).strict().optional(),
  gateway: z.object({ /* auth, port, tls, reload, ... */ }).optional(),
  agents: AgentsSchema.optional(),
  channels: ChannelsSchema.optional(),
  models: ModelsConfigSchema.optional(),
  tools: ToolsSchema.optional(),
  // ... 30+ top-level sections
}).strict();

Read file from disk (JSON5)
  │
  ▼
Resolve $include directives (recursive file merging)
  │
  ▼
Apply config.env to process.env (config-defined env vars)
  │
  ▼
Substitute ${VAR} references in string values
  │
  ▼
Warn on miskeys (e.g., "gateway.token" → "gateway.auth.token")
  │
  ▼
Validate against Zod schema (with plugin schemas merged)
  │
  ▼
Apply defaults chain:
  applyMessageDefaults → applySessionDefaults →
  applyLoggingDefaults → applyAgentDefaults →
  applyContextPruningDefaults → applyCompactionDefaults →
  applyModelDefaults
  │
  ▼
Normalize file paths (resolve ~, relative paths)
  │
  ▼
Apply runtime overrides (env var overrides)
  │
  ▼
Cache result for 200ms

async function writeConfigFile(cfg: ClawdbotConfig) {
  // 1. Validate before writing
  const validated = validateConfigObjectWithPlugins(cfg);
  if (!validated.ok) throw new Error(...)

  // 2. Stamp version metadata
  const stamped = stampConfigVersion(cfg);

  // 3. Write to temp file first
  const tmp = path.join(dir, `clawdbot.json.${pid}.${uuid}.tmp`);
  await fs.writeFile(tmp, json, { mode: 0o600 });

  // 4. Rotate backups (up to 5: .bak, .bak.1, .bak.2, ...)
  await rotateConfigBackups(configPath);
  await fs.copyFile(configPath, `${configPath}.bak`);

  // 5. Atomic rename (with Windows fallback)
  await fs.rename(tmp, configPath);
}

const watcher = chokidar.watch(opts.watchPath, {
  ignoreInitial: true,
  awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
});

const BASE_RELOAD_RULES: ReloadRule[] = [
  { prefix: "gateway.remote",     kind: "none" },    // No action needed
  { prefix: "hooks",              kind: "hot", actions: ["reload-hooks"] },
  { prefix: "cron",               kind: "hot", actions: ["restart-cron"] },
  { prefix: "browser",            kind: "hot", actions: ["restart-browser-control"] },
  { prefix: "channels.telegram",  kind: "hot", actions: ["restart-channel:telegram"] },
  { prefix: "gateway",            kind: "restart" }, // Full restart needed
  { prefix: "models",             kind: "none" },    // Dynamic, no restart
  { prefix: "agents",             kind: "none" },    // Dynamic
];

export function buildConfigSchema(params?) {
  const base = buildBaseConfigSchema();     // Zod → JSON Schema
  const merged = applyPluginSchemas(base, plugins);   // Plugin schemas
  const withChannels = applyChannelSchemas(merged, channels);
  const hints = applyPluginHints(base.uiHints, plugins);
  return { schema: merged, uiHints: hints, version, generatedAt };
}

export type GatewayWsClient = {
  socket: WebSocket;
  connect: ConnectParams;    // Handshake parameters (role, scopes, client info)
  connId: string;            // Connection UUID
  presenceKey?: string;      // Presence tracking key
};

export async function handleGatewayRequest(opts) {
  // 1. Authorization check (role + scopes)
  const authError = authorizeGatewayMethod(req.method, client);
  if (authError) { respond(false, undefined, authError); return; }

  // 2. Handler lookup (core handlers + plugin handlers)
  const handler = opts.extraHandlers?.[req.method] ?? coreGatewayHandlers[req.method];
  if (!handler) {
    respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "unknown method"));
    return;
  }

  // 3. Dispatch
  await handler({ req, params: req.params, client, respond, context });
}

if (role === "node") {
  const allowlist = resolveNodeCommandAllowlist(cfg, {
    platform: connectParams.client.platform,
    deviceFamily: connectParams.client.deviceFamily,
  });
  connectParams.commands = declared.filter(cmd => allowlist.has(cmd));
}

private scheduleReconnect() {
  const delay = this.backoffMs;
  this.backoffMs = Math.min(this.backoffMs * 2, 30_000);
  setTimeout(() => this.start(), delay).unref();
}

async request<T>(method: string, params?: unknown): Promise<T> {
  const id = randomUUID();
  const p = new Promise<T>((resolve, reject) => {
    this.pending.set(id, { resolve, reject });
  });
  this.ws.send(JSON.stringify({ type: "req", id, method, params }));
  return p;
}

export type GatewayRequestContext = {
  deps: CliDeps;
  cron: CronService;
  broadcast: BroadcastFn;
  nodeRegistry: NodeRegistry;
  getHealthCache: () => HealthSnapshot | null;
  // ... 30+ context entries
};