# akarshanop/openclaw architecture

> Architecture diagram of the GitHub repository akarshanop/openclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akarshanop/openclaw
- Repository: https://github.com/akarshanop/openclaw

## Overview

OpenClaw is a self-hosted AI assistant whose Gateway is the local control plane. The principal documented workflow is a user interacting through a Control UI or messaging channel, with the Gateway coordinating sessions, tools, events, and channel connections; companion apps and device nodes add local capabilities. The map also preserves model/provider configuration, extensibility, and memory. Several runtime relationships are documented only at a high level in the README, so those edges are dashed; sampled source confirms selected session, memory, and mobile-share behavior, not the full runtime.

Main entry points: [`src/gateway`](https://github.com/akarshanop/openclaw/tree/main/src/gateway) (Gateway), [`src/agents`](https://github.com/akarshanop/openclaw/tree/main/src/agents) (Agent Runtime), [`src/sessions/session-controller.lifecycle.ts`](https://github.com/akarshanop/openclaw/blob/main/src/sessions/session-controller.lifecycle.ts) (Session Lifecycle), [`src/channels`](https://github.com/akarshanop/openclaw/tree/main/src/channels) (Chat Channels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway Runtime"]
  node_gateway["Gateway"]
  node_sessions["Session Lifecycle"]
  node_config["Runtime Config<br/>[config.ts]"]
end

subgraph group_channels["Channels and Clients"]
  node_controlui["Control UI"]
  node_mobile["Android App"]
  node_share["iOS Share"]
  node_connectors["Chat Channels"]
end

subgraph group_agent["Agents and Capabilities"]
  node_agent["Agent Runtime"]
  node_context["Context Engine<br/>[registry.ts]"]
  node_models["Model Providers"]
  node_tools["Tools and Skills"]
  node_plugins["Plugins<br/>[registry-types.ts]"]
  node_nodes["Device Nodes"]
end

subgraph group_state["State and Memory"]
  node_sessionstore[("Session Storage")]
  node_delivery[("Delivery Queue")]
  node_memory["Memory Engine"]
  node_auth[("Credential Storage<br/>[auth-storage.ts]")]
end

node_user(("User"))

node_user -->|"uses"| node_controlui
node_user -.->|"messages"| node_connectors
node_controlui -->|"connects"| node_gateway
node_connectors -.->|"connects"| node_gateway
node_mobile -.->|"connects"| node_gateway
node_share -->|"sends event"| node_gateway
node_gateway -.->|"coordinates"| node_sessions
node_gateway -->|"manages connections"| node_connectors
node_gateway -->|"coordinates tools"| node_tools
node_gateway -.->|"runs assistant"| node_agent
node_agent -.->|"assembles context"| node_context
node_agent -->|"uses provider"| node_models
node_agent -->|"invokes"| node_tools
node_plugins -->|"extends"| node_models
node_plugins -->|"extends"| node_tools
node_nodes -->|"adds capabilities"| node_gateway
node_sessions -.->|"persists transcripts"| node_sessionstore
node_sessions -->|"queues delivery"| node_delivery
node_context -.->|"uses memory"| node_memory
node_agent -.->|"loads credentials"| node_auth
node_config -.->|"configures"| node_gateway

click node_gateway "https://github.com/akarshanop/openclaw/tree/main/src/gateway"
click node_sessions "https://github.com/akarshanop/openclaw/blob/main/src/sessions/session-controller.lifecycle.ts"
click node_config "https://github.com/akarshanop/openclaw/blob/main/src/config/config.ts"
click node_controlui "https://github.com/akarshanop/openclaw/tree/main/ui/src"
click node_mobile "https://github.com/akarshanop/openclaw/tree/main/apps/android/app/src/main/java/ai/openclaw/app"
click node_share "https://github.com/akarshanop/openclaw/blob/main/apps/ios/ShareExtension/ShareViewController.swift"
click node_connectors "https://github.com/akarshanop/openclaw/tree/main/src/channels"
click node_agent "https://github.com/akarshanop/openclaw/tree/main/src/agents"
click node_context "https://github.com/akarshanop/openclaw/blob/main/src/context-engine/registry.ts"
click node_models "https://github.com/akarshanop/openclaw/tree/main/src/agents"
click node_tools "https://github.com/akarshanop/openclaw/tree/main/src/agents"
click node_plugins "https://github.com/akarshanop/openclaw/blob/main/src/plugins/registry-types.ts"
click node_nodes "https://github.com/akarshanop/openclaw/tree/main/apps/android/app/src/main/java/ai/openclaw/app/node"
click node_sessionstore "https://github.com/akarshanop/openclaw/blob/main/src/config/sessions/session-cold-storage-worker.ts"
click node_delivery "https://github.com/akarshanop/openclaw/blob/main/src/infra/session-delivery-queue-storage.ts"
click node_memory "https://github.com/akarshanop/openclaw/blob/main/extensions/memory-core/src/memory/manager-embedding-ops.ts"
click node_auth "https://github.com/akarshanop/openclaw/blob/main/src/agents/sessions/auth-storage.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_sessions,node_config,node_user toneBlue
class node_controlui,node_mobile,node_share,node_connectors toneAmber
class node_agent,node_context,node_models,node_tools,node_plugins,node_nodes toneMint
class node_sessionstore,node_delivery,node_memory,node_auth toneRose
```

## Components

### Gateway Runtime

- [Gateway](https://github.com/akarshanop/openclaw/tree/main/src/gateway): `src/gateway`
- [Session Lifecycle](https://github.com/akarshanop/openclaw/blob/main/src/sessions/session-controller.lifecycle.ts): `src/sessions/session-controller.lifecycle.ts`
- [Runtime Config](https://github.com/akarshanop/openclaw/blob/main/src/config/config.ts): `src/config/config.ts`

### Channels and Clients

- [Control UI](https://github.com/akarshanop/openclaw/tree/main/ui/src): `ui/src`
- [Android App](https://github.com/akarshanop/openclaw/tree/main/apps/android/app/src/main/java/ai/openclaw/app): `apps/android/app/src/main/java/ai/openclaw/app`
- [iOS Share](https://github.com/akarshanop/openclaw/blob/main/apps/ios/ShareExtension/ShareViewController.swift): `apps/ios/ShareExtension/ShareViewController.swift`
- [Chat Channels](https://github.com/akarshanop/openclaw/tree/main/src/channels): `src/channels`

### Agents and Capabilities

- [Agent Runtime](https://github.com/akarshanop/openclaw/tree/main/src/agents): `src/agents`
- [Context Engine](https://github.com/akarshanop/openclaw/blob/main/src/context-engine/registry.ts): `src/context-engine/registry.ts`
- [Model Providers](https://github.com/akarshanop/openclaw/tree/main/src/agents): `src/agents`
- [Tools and Skills](https://github.com/akarshanop/openclaw/tree/main/src/agents): `src/agents`
- [Plugins](https://github.com/akarshanop/openclaw/blob/main/src/plugins/registry-types.ts): `src/plugins/registry-types.ts`
- [Device Nodes](https://github.com/akarshanop/openclaw/tree/main/apps/android/app/src/main/java/ai/openclaw/app/node): `apps/android/app/src/main/java/ai/openclaw/app/node`

### State and Memory

- [Session Storage](https://github.com/akarshanop/openclaw/blob/main/src/config/sessions/session-cold-storage-worker.ts): `src/config/sessions/session-cold-storage-worker.ts`
- [Delivery Queue](https://github.com/akarshanop/openclaw/blob/main/src/infra/session-delivery-queue-storage.ts): `src/infra/session-delivery-queue-storage.ts`
- [Memory Engine](https://github.com/akarshanop/openclaw/blob/main/extensions/memory-core/src/memory/manager-embedding-ops.ts): `extensions/memory-core/src/memory/manager-embedding-ops.ts`
- [Credential Storage](https://github.com/akarshanop/openclaw/blob/main/src/agents/sessions/auth-storage.ts): `src/agents/sessions/auth-storage.ts`

### Other components

- **User**

## Connections

- User → Control UI: uses
- User → Chat Channels: messages
- Control UI → Gateway: connects
- Chat Channels → Gateway: connects
- Android App → Gateway: connects
- iOS Share → Gateway: sends event (evidence: `apps/ios/ShareExtension/ShareViewController.swift`)
- Gateway → Session Lifecycle: coordinates (evidence: `src/gateway/server.chat-goal-workers.test-support.ts`)
- Gateway → Chat Channels: manages connections
- Gateway → Tools and Skills: coordinates tools (evidence: `src/gateway/server.chat-goal-workers.test-support.ts`)
- Gateway → Agent Runtime: runs assistant (evidence: `src/gateway/server.chat-goal-workers.test-support.ts`)
- Agent Runtime → Context Engine: assembles context (evidence: `src/agents/harness/context-engine-lifecycle.ts`)
- Agent Runtime → Model Providers: uses provider
- Agent Runtime → Tools and Skills: invokes
- Plugins → Model Providers: extends (evidence: `src/agents/harness/registry.ts`)
- Plugins → Tools and Skills: extends (evidence: `src/agents/harness/registry.ts`)
- Device Nodes → Gateway: adds capabilities
- Session Lifecycle → Session Storage: persists transcripts
- Session Lifecycle → Delivery Queue: queues delivery (evidence: `src/infra/session-delivery-queue-storage.ts`)
- Context Engine → Memory Engine: uses memory
- Agent Runtime → Credential Storage: loads credentials (evidence: `src/agents/sessions/auth-storage.ts`)
- Runtime Config → Gateway: configures (evidence: `src/gateway/server.chat-goal-workers.test-support.ts`)
