> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # OpenClaw Code Walkthrough > Overview and code map for OpenClaw, a production AI agent platform, explaining subsystems, key files, and where to find agent, memory, tools, providers, channels, and sandbox code 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 | Path | Purpose | | - | - | | `openclaw/` | Repository root | | `openclaw/src/` | All core agent logic — start here | | `openclaw/apps/` | Platform clients: iOS, Android, macOS | | `openclaw/packages/` | Shared packages used across the monorepo | | `openclaw/extensions/` | Extensions system | | `openclaw/plugins/` | Plugin system | | `openclaw/skills/` | Skill definitions the agent can load | | `openclaw/ui/` | React UI components | | `openclaw/scripts/` | Build and utility scripts | | `openclaw/test/` | End-to-end test suite | | `openclaw/vendor/` | Bundled third-party dependencies | 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: ```text theme={null} src/agents/ 1 src/agents/ 2 pi-embedded-runner.ts ← runs the agent loop (Perceive/Reason/Act) 3 pi-embedded-subscribe.ts ← streams responses to the user 4 pi-embedded-helpers.ts ← error formatting and context overflow handling 5 openclaw-tools.ts ← registers all tools available to the agent 6 bash-tools.ts ← shell command execution (tool implementation) ``` 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: ```text theme={null} src/memory/ 1 src/memory/ 2 manager.ts ← central memory manager: reads, writes, and searches memories 3 search-manager.ts ← vector search — finds memories by semantic similarity 4 embeddings.ts ← converts text into vectors 5 sync-memory-files.ts ← persists memory snapshots to disk 6 sync-session-files.ts ← keeps conversation history synchronized 7 sqlite.ts ← SQLite storage backend ``` 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: ```text theme={null} src/agents/ (tools) 1 src/agents/ (tools) 2 openclaw-tools.ts ← registers ALL tools available to the agent (descriptions + schemas) 3 bash-tools.ts ← shell command execution with approval and sandboxing ``` 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: ```text theme={null} src/ (channel folders) 1 src/ 2 ├─ slack/ 3 ├─ telegram/ 4 ├─ discord/ 5 ├─ imessage/ 6 ├─ whatsapp/ 7 ├─ signal/ 8 ├─ line/ 9 ├─ web/ 10 └─ channels/ ← shared channel infrastructure and helpers ``` 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: ```text theme={null} src/providers/ 1 src/providers/ 2 github-copilot-auth.ts ← GitHub Copilot authentication helpers 3 github-copilot-token.ts ← fetches and caches Copilot tokens ``` Failover logic integrated with the agent: ```text theme={null} src/agents/ (failover) 1 src/agents/ (multi-provider failover) 2 auth-profiles.ts ← rotates keys/models when one fails or is rate-limited 3 failover-error.ts ← handles provider errors and orchestrates fallback ``` 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: ```text theme={null} src/agents/sandbox/ 1 src/agents/sandbox/ 2 config.ts ← per-agent sandbox settings and configuration 3 tool-policy.ts ← allow/deny rules controlling which tools can run 4 types.ts ← sandbox type definitions 5 docker.ts ← Docker-based sandbox container management 6 workspace.ts ← controls which filesystem paths the agent can access 7 manage.ts ← creates and tears down sandbox environments ``` 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: ```text theme={null} Perceive/Reason/Act orchestration → src/agents/pi-embedded-runner.ts Advanced tool usage → src/agents/openclaw-tools.ts Semantic memory → src/memory/manager.ts Shell/code execution + safety → src/agents/bash-tools.ts + src/agents/sandbox/ ``` * 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. ## Links and references * [OpenClaw architecture overview — internal docs](/docs/architecture) (internal reference) * [Semantic search and embeddings](https://en.wikipedia.org/wiki/Semantic_search) * [Best practices for sandboxing and container security](https://owasp.org/www-project-top-ten/) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.