<<< Back to Index


OpenClaw Full Technical Specification (Source-Derived)


Date: 2026-03-02

Repo analyzed: /home/slime/openclaw

Spec scope: Gateway + CLI + agent runtime integration + channels + plugins + memory + automation + node/browser/canvas + policy/safety + startup/ops.




0) Method, confidence, and constraints



Primary code anchors used:




1) System architecture


1.1 What OpenClaw is (runtime architecture)


OpenClaw is a local-first control plane + assistant runtime built around:

1. A multi-surface CLI (openclaw ...) and daemon-capable gateway server.

2. A gateway WS/HTTP control plane exposing methods for chat/session/channel/tool/cron/node operations.

3. A tool-enabled agent run path (embedded Pi runtime + optional CLI providers).

4. A plugin architecture for channels, tools, hooks, memory, and extension CLIs.


1.2 Layered architecture


1) Process/bootstrap layer


2) CLI routing/execution layer


3) Gateway control plane


4) Agent runtime/tool execution layer


5) Integration layer


1.3 Runtime model



Edge cases/constraints:




2) Startup sequence (from executable to ready gateway)


2.1 CLI/bootstrap sequence


1. openclaw.mjs


2. src/entry.ts


3. src/cli/run-main.ts


2.2 Gateway startup sequence (`startGatewayServer`)


From src/gateway/server.impl.ts:


Known constraints:




3) Configuration and schema system


What it does


Provides a typed, validated, migratable configuration model with schema export and runtime snapshot support.


Key modules



Data flow


config file -> read snapshot -> legacy detect/migrate -> zod validation -> runtime snapshot -> downstream subsystem resolution.


Edge cases / constraints





4) Session model and lifecycle


What it does


Tracks conversations/runs via session keys, session files/transcripts, and store entries; supports main aliases, per-agent mapping, override fields, and lifecycle operations via CLI and gateway methods.


Key modules



Data flow


Inbound command/message -> resolve agent + session key -> load/merge session entry -> run agent/tooling -> append transcript / update store -> emit transcript update events.


Edge cases / constraints





5) Agent runtime and model execution


What it does


Runs turns against either embedded provider runtime or CLI provider bridges, with model fallback, think-level controls, and session-bound metadata.


Key modules



Data flow


agent command opts -> resolve provider/model/timeout/session -> run provider attempt(s) w/ fallback -> collect output/meta -> persist session + deliver optional outbound.


Edge cases / constraints





6) Tool system


6.1 Core tool composition


src/agents/openclaw-tools.ts constructs core tools including:


It threads runtime context into tools: session key, channel/account/thread/group context, sender identity, policy constraints.


6.2 Plugin tools


src/plugins/tools.ts:


6.3 HTTP tool invocation


src/gateway/tools-invoke-http.ts exposes POST /tools/invoke:


Edge cases/constraints:




7) Channel plugin system and messaging semantics


What it does


Abstracts each messaging surface behind typed adapters while keeping core flows channel-agnostic.


Key modules



Channel adapter capabilities (contract)



Outbound data flow


reply payload(s) -> normalize payloads -> enqueue delivery queue (write-ahead) -> resolve channel outbound adapter -> chunk text (channel aware) -> send text/media/payload -> ack/fail queue entry -> optional transcript mirroring/hooks.


Edge cases / constraints





8) Memory subsystem


What it does


Provides file-backed + vector-augmented memory indexing/search/get tooling with pluggable embeddings and batching backends.


Key modules



Data flow (typical)


source files/transcripts -> chunk + embedding generation -> store vectors/metadata -> query parse/expansion -> retrieval/rerank/hybrid -> return snippets/docs.


Edge cases / constraints





9) Cron and heartbeat behavior


9.1 Cron


src/gateway/server-cron.ts builds gateway cron service.


Capabilities:


Edge cases/constraints:


9.2 Heartbeat


src/infra/heartbeat-runner.ts:


Edge cases/constraints:




10) Browser, node, and canvas integrations


10.1 Browser



Constraint:


10.2 Node integration



Constraint:


10.3 Canvas



Edge cases:




11) Gateway auth, safety, and policy behavior


11.1 Auth model


src/gateway/auth.ts supports:


11.2 Role + scope authorization



11.3 Tool-risk restrictions



Known constraints:




12) Skills loading and refresh behavior


What it does


Loads and surfaces workspace/global/plugin-provided skills and keeps snapshots current as skill files change.


Key modules



Data flow


resolve skill dirs -> load SKILL.md entries -> build command specs/prompts -> include in agent run context -> watch changes -> bump skill snapshot version -> refresh future runs.


Edge cases / constraints





13) Gateway plugin system (beyond tools/channels)


What it does


Discovers/loads plugin manifests and code, wires hook phases, optional HTTP and runtime services, and plugin CLI commands.


Key modules



Constraints





14) Gateway method and command surface (major features)


Gateway methods (representative)


Method inventory is centrally listed via src/gateway/server-methods-list.ts and scope classification in method-scopes.ts.


Major groups:


CLI major command families (source footprint)


From src/cli/* and registrars:


TODO/uncertain: exact complete command argument matrix was not fully enumerated from every registrar in this pass.




15) Session messaging semantics


What it does


Normalizes assistant outputs into channel-deliverable payloads with chunking, media handling, best-effort behavior, delivery queue durability, and transcript mirroring hooks.


Key modules



Semantics highlights



Edge constraints:




16) BOOT flow / automated startup run


src/gateway/boot.ts:


Edge case:




17) Known constraints and sharp edges (cross-cutting)


1. Policy complexity is high (global/provider/agent/group/subagent + scope/role).

2. Plugin and channel ecosystems create broad behavior variance by install/profile.

3. Some feature surfaces are intentionally disabled in tests and require env overrides.

4. Config migration strictness can hard-stop startup.

5. Large method/CLI surface means parity verification should use generated inventories + tests, not prose alone.




18) Full feature inventory checklist (for parity auditing)


Legend: [x] observed in source, [?] partial/uncertain detail.


Core runtime


Gateway core


Auth + security + policy


Sessions


Agent execution


Tooling


Channels + messaging


Memory


Automation


Node/browser/canvas


Skills + plugins


Ops and management


Top-level checklist feature count: 95




19) Parity Audit Input Summary


Normalized feature IDs for Clawmacs parity comparison.





20) Explicit TODO / uncertain items


1. Exact complete CLI option matrices for every subcommand were not exhaustively expanded from all registrar files.

2. Exact default memory slot behavior across all profiles/install modes needs targeted trace through config defaults + plugin auto-enable path.

3. Exact full gateway WS method payload schemas per method should be generated from method handler signatures/protocol schema output for machine-check parity.



<<< Back to Index