# mahdertesf/openclaw architecture

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

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

## Overview

OpenClaw is a self-hosted personal AI assistant whose Gateway coordinates messaging, agent sessions, tools, and events. A typical workflow starts with onboarding and configuration, receives a message through a channel, routes it to an agent, and returns a reply; companion apps also connect as nodes for voice and device capabilities. The README documents the major product branches, while the sampled source confirms selected agent, tool-policy, browser-storage, voice, and Android service relationships. Several subsystems are represented at directory level because their implementation was not sampled.

Main entry points: [`src/gateway/server.impl.ts`](https://github.com/mahdertesf/openclaw/blob/main/src/gateway/server.impl.ts) (Gateway control plane), [`src/commands/agent.ts`](https://github.com/mahdertesf/openclaw/blob/main/src/commands/agent.ts) (Agent execution), [`src/telegram/bot-handlers.ts`](https://github.com/mahdertesf/openclaw/blob/main/src/telegram/bot-handlers.ts) (Channel adapters), [`src/commands`](https://github.com/mahdertesf/openclaw/tree/main/src/commands) (Onboarding wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and control"]
  node_onboarding["Onboarding wizard"]
  node_config["Configuration"]
  node_gateway["Gateway control plane<br/>[server.impl.ts]"]
end

subgraph group_assistant["Assistant runtime"]
  node_agent["Agent execution<br/>[agent.ts]"]
  node_routing["Session routing<br/>[session-key.ts]"]
  node_toolpolicy["Tool policy"]
  node_memory[("Memory search")]
  node_model["Model providers"]
end

subgraph group_channels["Messaging channels"]
  node_channels["Channel adapters<br/>[bot-handlers.ts]"]
  node_discordvoice["Discord voice<br/>[manager.ts]"]
  node_extensions["Channel extensions"]
end

subgraph group_capabilities["Tools and capabilities"]
  node_browser["Browser tools"]
  node_canvas["Live Canvas<br/>[server.ts]"]
  node_cron["Cron and sessions"]
end

subgraph group_clients["Companion clients"]
  node_android["Android node<br/>[NodeRuntime.kt]"]
  node_ios["iOS node<br/>[NodeAppModel.swift]"]
  node_macos["macOS companion<br/>[AppState.swift]"]
  node_sharedkit["Shared node protocol"]
end

node_operator(("Operator"))
node_user(("Assistant user"))
node_externalmodels{{"AI model services"}}

node_operator -->|"configures"| node_onboarding
node_onboarding -->|"sets up"| node_config
node_operator -->|"starts"| node_gateway
node_gateway -.->|"uses"| node_config
node_user -->|"sends message"| node_channels
node_channels -.->|"delivers events"| node_gateway
node_gateway -->|"routes sessions"| node_routing
node_routing -->|"selects agent"| node_agent
node_agent -.->|"requests inference"| node_model
node_model -.->|"calls"| node_externalmodels
node_agent -->|"filters tools"| node_toolpolicy
node_agent -.->|"uses memory"| node_memory
node_agent -.->|"invokes browser"| node_browser
node_agent -->|"controls canvas"| node_canvas
node_gateway -->|"coordinates"| node_cron
node_gateway -->|"connects nodes"| node_android
node_gateway -->|"connects nodes"| node_ios
node_gateway -->|"connects companion"| node_macos
node_android -.->|"uses protocol"| node_sharedkit
node_ios -->|"uses protocol"| node_sharedkit
node_channels -->|"extends channels"| node_extensions
node_discordvoice -->|"runs agent"| node_agent
node_gateway -.->|"returns replies"| node_user

click node_onboarding "https://github.com/mahdertesf/openclaw/tree/main/src/commands"
click node_config "https://github.com/mahdertesf/openclaw/tree/main/src/config"
click node_gateway "https://github.com/mahdertesf/openclaw/blob/main/src/gateway/server.impl.ts"
click node_agent "https://github.com/mahdertesf/openclaw/blob/main/src/commands/agent.ts"
click node_routing "https://github.com/mahdertesf/openclaw/blob/main/src/routing/session-key.ts"
click node_toolpolicy "https://github.com/mahdertesf/openclaw/blob/main/src/agents/tool-policy-pipeline.ts"
click node_memory "https://github.com/mahdertesf/openclaw/tree/main/src/memory"
click node_model "https://github.com/mahdertesf/openclaw/tree/main/src/agents"
click node_channels "https://github.com/mahdertesf/openclaw/blob/main/src/telegram/bot-handlers.ts"
click node_discordvoice "https://github.com/mahdertesf/openclaw/blob/main/src/discord/voice/manager.ts"
click node_extensions "https://github.com/mahdertesf/openclaw/tree/main/extensions"
click node_browser "https://github.com/mahdertesf/openclaw/tree/main/src/browser"
click node_canvas "https://github.com/mahdertesf/openclaw/blob/main/src/canvas-host/server.ts"
click node_cron "https://github.com/mahdertesf/openclaw/tree/main/src"
click node_android "https://github.com/mahdertesf/openclaw/blob/main/apps/android/app/src/main/java/ai/openclaw/android/NodeRuntime.kt"
click node_ios "https://github.com/mahdertesf/openclaw/blob/main/apps/ios/Sources/Model/NodeAppModel.swift"
click node_macos "https://github.com/mahdertesf/openclaw/blob/main/apps/macos/Sources/OpenClaw/AppState.swift"
click node_sharedkit "https://github.com/mahdertesf/openclaw/blob/main/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayNodeSession.swift"

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_onboarding,node_config,node_gateway,node_user toneBlue
class node_agent,node_routing,node_toolpolicy,node_memory,node_model toneAmber
class node_channels,node_discordvoice,node_extensions toneMint
class node_browser,node_canvas,node_cron toneRose
class node_android,node_ios,node_macos,node_sharedkit,node_operator,node_externalmodels toneIndigo
```

## Components

### Setup and control

- [Onboarding wizard](https://github.com/mahdertesf/openclaw/tree/main/src/commands): `src/commands`
- [Configuration](https://github.com/mahdertesf/openclaw/tree/main/src/config): `src/config`
- [Gateway control plane](https://github.com/mahdertesf/openclaw/blob/main/src/gateway/server.impl.ts): `src/gateway/server.impl.ts`

### Assistant runtime

- [Agent execution](https://github.com/mahdertesf/openclaw/blob/main/src/commands/agent.ts): `src/commands/agent.ts`
- [Session routing](https://github.com/mahdertesf/openclaw/blob/main/src/routing/session-key.ts): `src/routing/session-key.ts`
- [Tool policy](https://github.com/mahdertesf/openclaw/blob/main/src/agents/tool-policy-pipeline.ts): `src/agents/tool-policy-pipeline.ts`
- [Memory search](https://github.com/mahdertesf/openclaw/tree/main/src/memory): `src/memory`
- [Model providers](https://github.com/mahdertesf/openclaw/tree/main/src/agents): `src/agents`

### Messaging channels

- [Channel adapters](https://github.com/mahdertesf/openclaw/blob/main/src/telegram/bot-handlers.ts): `src/telegram/bot-handlers.ts`
- [Discord voice](https://github.com/mahdertesf/openclaw/blob/main/src/discord/voice/manager.ts): `src/discord/voice/manager.ts`
- [Channel extensions](https://github.com/mahdertesf/openclaw/tree/main/extensions): `extensions`

### Tools and capabilities

- [Browser tools](https://github.com/mahdertesf/openclaw/tree/main/src/browser): `src/browser`
- [Live Canvas](https://github.com/mahdertesf/openclaw/blob/main/src/canvas-host/server.ts): `src/canvas-host/server.ts`
- [Cron and sessions](https://github.com/mahdertesf/openclaw/tree/main/src): `src`

### Companion clients

- [Android node](https://github.com/mahdertesf/openclaw/blob/main/apps/android/app/src/main/java/ai/openclaw/android/NodeRuntime.kt): `apps/android/app/src/main/java/ai/openclaw/android/NodeRuntime.kt`
- [iOS node](https://github.com/mahdertesf/openclaw/blob/main/apps/ios/Sources/Model/NodeAppModel.swift): `apps/ios/Sources/Model/NodeAppModel.swift`
- [macOS companion](https://github.com/mahdertesf/openclaw/blob/main/apps/macos/Sources/OpenClaw/AppState.swift): `apps/macos/Sources/OpenClaw/AppState.swift`
- [Shared node protocol](https://github.com/mahdertesf/openclaw/blob/main/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayNodeSession.swift): `apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayNodeSession.swift`

### Other components

- **Operator**
- **Assistant user**
- **AI model services**

## Connections

- Operator → Onboarding wizard: configures (evidence: `README.md`)
- Onboarding wizard → Configuration: sets up (evidence: `README.md`)
- Operator → Gateway control plane: starts (evidence: `README.md`)
- Gateway control plane → Configuration: uses
- Assistant user → Channel adapters: sends message (evidence: `README.md`)
- Channel adapters → Gateway control plane: delivers events
- Gateway control plane → Session routing: routes sessions (evidence: `README.md`)
- Session routing → Agent execution: selects agent (evidence: `README.md`)
- Agent execution → Model providers: requests inference
- Model providers → AI model services: calls
- Agent execution → Tool policy: filters tools (evidence: `src/agents/tool-policy-pipeline.ts`)
- Agent execution → Memory search: uses memory
- Agent execution → Browser tools: invokes browser
- Agent execution → Live Canvas: controls canvas (evidence: `README.md`)
- Gateway control plane → Cron and sessions: coordinates (evidence: `README.md`)
- Gateway control plane → Android node: connects nodes (evidence: `README.md`)
- Gateway control plane → iOS node: connects nodes (evidence: `README.md`)
- Gateway control plane → macOS companion: connects companion (evidence: `README.md`)
- Android node → Shared node protocol: uses protocol
- iOS node → Shared node protocol: uses protocol
- Channel adapters → Channel extensions: extends channels (evidence: `README.md`)
- Discord voice → Agent execution: runs agent (evidence: `src/discord/voice/manager.ts`)
- Gateway control plane → Assistant user: returns replies
