OpenClaw Internals Reference

Full analysis: docs/openclaw-analysis.md

Key Facts

Property	Value
Version pinned	v2026.2.13 (v2026.2.14 breaks — default-deny scope)
Codebase size	~675K lines TypeScript
Runtime	Node.js >=22.12.0, pnpm monorepo, tsdown bundler
Gateway WS port	:18789
HTTP port	:18790
Config path	~/.openclaw/openclaw.json (NOT ~/.config/openclaw/)
Session files	~/.openclaw/agents/{id}/sessions/{sid}.jsonl

Entry Points

Entry	Purpose
runEmbeddedPiAgent()	Run agent in-process, independent of Gateway WS server — the key Lambda integration point
extensionAPI.js	Library entry point (NOT in package.json exports map — must use file:// URL import)
openclaw gateway run	Start full Gateway WS server (subcommand required, plain openclaw gateway just waits)

// Correct import pattern for Lambda
const ocRoot = process.env.OPENCLAW_ROOT!;
const { extensionAPI } = await import(`file://${ocRoot}/dist/extensionAPI.js`);

SessionManager

• SessionManager.open(id) — synchronous fs read, JSONL format
• Returns [] if session file is missing (safe to call on first run)
• Sessions are append-only JSONL transcripts, compacted periodically
• SessionLock prevents concurrent access to same session (critical for Lambda concurrency)

Gateway Protocol (JSON-RPC 2.0 over WebSocket)

Handshake Sequence

1. GW → client:  { type: "event", event: "connect.challenge", data: { challenge } }
2. client → GW:  { type: "req", id: 1, method: "connect", params: { client: { id: "gateway-client", mode: "backend" }, response: <challenge-response> } }
3. GW → client:  { type: "res", id: 1, result: { status: "hello-ok", snapshot: { sessionDefaults: { mainSessionKey } } } }

Sending a Message

// sessionKey obtained from hello-ok snapshot
{ type: "req", id: 2, method: "chat.send", params: { sessionKey, message: "..." } }

Streaming Response

// Stream chunks
{ type: "event", event: "chat", data: { state: "delta", content: "..." } }
// Final
{ type: "event", event: "chat", data: { state: "final", content: "..." } }
// Error
{ type: "event", event: "chat", data: { state: "error", error: "..." } }

Valid client Field Values

• client.id: "cli", "gateway-client", "webchat-ui", etc. (TypeBox Literal)
• client.mode: "cli", "backend", "ui", "node" — NOT "operator" (invalid)
• device field: Optional — omit entirely (empty publicKey/signature strings fail validation)

Config Requirements

{
  "gateway": { "mode": "local" },
  "auth": { "method": "env" }
}

• auth.method key: removed in recent versions (invalid if present)
• gateway.mode: "local" required for embedded operation
• API keys via env vars only — never write to openclaw.json

Serverless Blockers (and How We Solved Them)

Blocker	Problem	Solution
Persistent WS server	Always-running :18789	Use runEmbeddedPiAgent() instead
Long-lived runs (10 min)	Lambda timeout	Lambda 15-min timeout + structured streaming
In-process tools (filesystem)	/tmp only in Lambda	HOME=/tmp, sessions in /tmp
SQLite vector store	Write access needed	/tmp mount
Plugin loading (~30-35s)	Cold start overhead	Bedrock discovery disabled, pre-loaded
Bedrock auto-discovery	56s scan on startup	bedrockDiscovery.enabled: false

Fargate vs Lambda Runtime

Aspect	Fargate (Phase 1)	Lambda (Phase 2)
Entry	openclaw gateway run	runEmbeddedPiAgent()
Session state	Persistent (~/.openclaw)	/tmp (ephemeral)
Cold start	40-57s	1.35s
Concurrent users	1 per task	Many (separate invocations)
Cost	~$0/month idle	Per-invocation