Skip to main content
OpenClaw is a production-grade AI agent platform powering real conversations across Slack, Telegram, Discord, iMessage, and WhatsApp. Real users depend on it to respond reliably: it must handle bad API keys, preserve long-term context, and ensure potentially dangerous actions (like running shell commands) are gated by safety checks. This walkthrough gives you a practical map of the codebase so you can quickly find the subsystem that answers your question. The repository is large — hundreds of files across many folders — so start at the right place and follow the mapping below.

​
Top-level repository layout

Start in src/ — that’s where OpenClaw thinks, decides, and acts. Inside src/ there are six primary systems you should know. Each maps to specific folders and key files you’ll open frequently.

​
1) Agent loop — orchestration and runtime

  • Location: src/agents
  • Purpose: The central Perceive → Reason → Act orchestration. Every incoming message (Slack, WhatsApp, CLI, etc.) is normalized, handed to the runner, transformed into LLM queries, and processed until a final response is produced. The production runner adds auth rotation, streaming, multi-provider failover, retries, and robust error recovery.
Key files:
The loop implemented in pi-embedded-runner.ts is the production-grade Perceive → Reason → Act cycle with streaming and provider failover built in.

​
2) Memory — persistent, searchable conversation and agent memories

  • Location: src/memory
  • Purpose: Memory stores everything OpenClaw needs to persist between conversations. It supports writes, reads, and semantic search using vector embeddings, with durable storage in SQLite.
Key files:
This is a meaning-based memory system: store and retrieve by semantic similarity, not by literal string matching.

​
3) Tools — registered actions the agent can call

  • Location: src/agents (tool registry) and the tool implementation files
  • Purpose: Tools are actions the agent can request. Each tool is registered with a description and a JSON schema so the LLM knows when to call it and what parameters to send. The platform exposes 50+ tools (integrations, API wrappers, local helpers). Tools that execute shell or code are subject to approval and sandboxing.
Key files:
Each tool description includes when to use it and the expected output. Interactive code execution flows through these implementations but always with safety controls.

​
4) Channels — incoming/outgoing platform adapters

  • Location: src/* (per-channel folders)
  • Purpose: Each platform (Slack, Telegram, Discord, iMessage, WhatsApp, etc.) implements an adapter. Adapters normalize payloads into a common internal message format, handle platform-specific auth and webhooks, hand messages to the agent loop, and deliver replies. From the agent’s perspective, a message is a message — the loop is platform-agnostic.
Channel folders:
Each adapter handles platform-specific authentication, payload normalization, and webhook lifecycles.

​
5) Providers — AI model backends and failover

  • Location: src/providers and related failover logic in agent code
  • Purpose: Providers implement backends for AI models (Claude, Gemini, GitHub Copilot, local models, etc.). OpenClaw routes requests across providers and orchestrates multi-provider failover so users rarely see errors.
Key files:
Failover logic integrated with the agent:
The central provider orchestrator (e.g., Hybrid.ts in src/providers) attempts multiple backends in sequence — for example: Claude → Gemini → local model — removing single points of failure.

​
6) Security and sandboxing — tool runtime safety

  • Location: src/agents/sandbox
  • Purpose: All tool calls that could affect the host environment are checked before execution. The sandbox enforces which binaries can run, which filesystem paths are accessible, and which operations are blocked. Rules are enforced in code — the agent cannot bypass them by prompting.
Key files:
Sandbox controls:
  • Which binaries can execute
  • Which filesystem paths are accessible
  • Which operations are blocked
This enforces the same checks a human operator previously would have performed manually.

​
How the pieces map to behavior

At a glance, here are the key behavior-to-code mappings you’ll refer to most often:
  • If you’re debugging runtime behavior or message streaming, open src/agents/pi-embedded-runner.ts.
  • If you need to add or change a tool, edit src/agents/openclaw-tools.ts and the corresponding tool implementation.
  • If semantic search or memory storage is failing, investigate src/memory/search-manager.ts and src/memory/sqlite.ts.
  • If a shell command executed by the agent is unsafe or misbehaving, inspect src/agents/bash-tools.ts and src/agents/sandbox/.
This map gives you a reliable starting point: begin in src/, then pick the subsystem (agents, memory, tools, providers, channels, sandbox) relevant to your issue. Use the key files listed above to quickly navigate the code that implements each capability.

Watch Video