Codebase Navigation ๐ข
Before diving into source code, you need a map. This chapter gives you a complete overview of OpenClaw's directory structure so you can quickly find any piece of code.
Learning Objectives
After reading this chapter, you'll be able to:
- Understand the purpose of each top-level directory
- Navigate the
src/ subdirectory structure (~30 modules)
- Find plugin code in
extensions/ (~90 plugins)
- Understand what's in
skills/ (~60 Skills)
I. Top-Level Directory Structure
openclaw/
โโโ src/ โ Core runtime source code (~40K lines TypeScript)
โโโ extensions/ โ Official plugins (channel/provider/capability)
โโโ skills/ โ Built-in Skills (~60 directories)
โโโ packages/ โ Shared utility packages
โโโ ui/ โ Web UI (React)
โโโ scripts/ โ Build and maintenance scripts
โโโ docs/ โ Documentation
โโโ openclaw.mjs โ CLI entry point
II. src/ Subdirectory Breakdown
This is the heart of OpenClaw:
Core Control
| Directory | Role |
|---|
src/gateway/ | HTTP/WebSocket server, authentication, routing |
src/routing/ | Message-to-agent routing engine |
src/agents/ | Agent reasoning, Bootstrap, compaction |
src/plugins/ | Plugin discovery, loading, registry |
Infrastructure
| Directory | Role |
|---|
src/config/ | Configuration loading, parsing, validation |
src/sessions/ | Session storage (SQLite-based) |
src/infra/ | Utilities (backoff, heartbeat, outbound) |
src/logging/ | Structured logging system |
src/security/ | Prompt injection protection, secret handling |
Channels
| Directory | Role |
|---|
src/channels/ | Channel types, adapters, plugin interfaces |
src/auto-reply/ | Reply strategies (heartbeat, thinking, streaming) |
Integration
| Directory | Role |
|---|
src/acp/ | Agent Coordination Protocol (multi-agent) |
src/tasks/ | Task registry and executor |
src/cron/ | Cron job types and normalization |
src/secrets/ | Secret reference resolution |
SDK
| Directory | Role |
|---|
src/plugin-sdk/ | Public Plugin SDK (channel, provider, capability contracts) |
src/cli/ | CLI commands and argument parsing |
III. extensions/ Plugin Directory
90+ official plugins, organized by type:
Channel Plugins (Platform Adapters)
extensions/telegram/ โ Telegram Bot
extensions/discord/ โ Discord Bot
extensions/slack/ โ Slack Bot
extensions/bluebubbles/ โ iMessage (via BlueBubbles)
extensions/signal/ โ Signal Messenger
extensions/matrix/ โ Matrix Protocol
extensions/msteams/ โ Microsoft Teams
extensions/email/ โ Email (SMTP/IMAP)
extensions/sms-twilio/ โ SMS (via Twilio)
extensions/line/ โ LINE
extensions/wechat/ โ WeChat
...
LLM Provider Plugins
extensions/anthropic/ โ Anthropic Claude (default)
extensions/openai/ โ OpenAI GPT-4, o1
extensions/ollama/ โ Local Ollama models
extensions/google-gemini/ โ Google Gemini
extensions/mistral/ โ Mistral AI
extensions/groq/ โ Groq (fast inference)
extensions/amazon-bedrock/ โ AWS Bedrock
extensions/anthropic-vertex/ โ Claude on Google Vertex
...
Capability Plugins
extensions/memory-core/ โ Local vector memory
extensions/mcporter/ โ MCP Server launcher
extensions/acpx/ โ ACP extensions
...
IV. skills/ Directory
~60 built-in Skills grouped by category:
skills/
โโโ coding-agent/ โ Programming assistant
โโโ github/ โ Git/GitHub workflow
โโโ taskflow/ โ Task flow management
โโโ summarize/ โ Summary generation
โโโ notion/ โ Notion integration
โโโ obsidian/ โ Obsidian notes
โโโ discord/ โ Discord workflow
โโโ slack/ โ Slack workflow
โโโ spotify-player/ โ Music playback control
โโโ weather/ โ Weather queries
โโโ sag/ โ Skill-as-Agent (create new Skills)
โโโ skill-creator/ โ Skill creation assistant
...
V. Key Files Reference
| File | Size | Role |
|---|
openclaw.mjs | Entry | CLI wrapper, version check, launch core |
src/entry.ts | 11KB | Main entry point, runCli() |
VISION.md | - | Design philosophy document |
CLAUDE.md | - | Architecture boundary constraints |
src/plugin-sdk/core.ts | 21KB | Plugin SDK public API entry |
src/plugin-sdk/entrypoints.ts | - | All SDK entry points |
package.json | - | Exports map (SDK entry point definitions) |
Summary
src/ = Core runtime: gateway, routing, agents, plugins โ all key logic is here.extensions/ = Capability library: 90+ official plugins, organized by type.skills/ = Instruction library: 60 built-in Markdown Skills.- Plugin SDK entry is
src/plugin-sdk/core.ts: all public APIs re-exported from here.
โ What Is OpenClaw | โ Running Locally: Startup Flow