Agent Skills › serithemage/serverless-openclaw › openclaw

openclaw

GitHub

OpenClaw 内部架构参考，涵盖 Gateway 协议、Agent 运行时、会话管理及 Serverless 集成。用于 OpenClaw API 开发与 Agent 行为调试。

.claude/skills/openclaw/SKILL.md serithemage/serverless-openclaw

Trigger Scenarios

使用 OpenClaw APIs 调试 Agent 行为集成 Lambda 环境配置 Gateway 连接

Install

npx skills add serithemage/serverless-openclaw --skill openclaw -g -y

More Options

Non-standard path

npx skills add https://github.com/serithemage/serverless-openclaw/tree/main/.claude/skills/openclaw -g -y

Use without installing

npx skills use serithemage/serverless-openclaw@openclaw

指定 Agent (Claude Code)

npx skills add serithemage/serverless-openclaw --skill openclaw -a claude-code -g -y

安装 repo 全部 skill

npx skills add serithemage/serverless-openclaw --all -g -y

预览 repo 内 skill

npx skills add serithemage/serverless-openclaw --list

SKILL.md

Frontmatter

{
    "name": "openclaw",
    "description": "References OpenClaw internals and integration points. Covers Gateway protocol, agent runtime, session management, tool system, and serverless integration. Use when working with OpenClaw APIs or debugging agent behavior.",
    "allowed-tools": "Read, Glob, Grep"
}

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