Key Files Map

Critical Path (Must-Read to Understand the System)

Entry & Bootstrap

File	Responsibility
`openclaw.mjs`	CLI bootstrap shim — respawns Node with warning suppression flags
`src/entry.ts`	Main entry — warning filter, env normalization, profile parsing, respawn logic, then loads `run-main.ts`
`src/index.ts`	Library API entry — exports public utilities, sets up logging, builds Commander program
`src/cli/run-main.ts`	Calls `runCli()` — the bridge between entry and Commander
`src/cli/program.ts`	Builds the Commander.js program, registers all subcommands
`src/cli/deps.ts`	Dependency injection for CLI commands

The Agentic Loop

File	Responsibility
`src/agents/pi-embedded-runner/run/attempt.ts`	The orchestrator — `runEmbeddedAttempt()` sets up everything and calls `session.prompt()`
`src/agents/pi-embedded-runner/runs.ts`	Run lifecycle management, queue handling, active run tracking
`src/agents/pi-embedded-subscribe.ts`	Event subscription setup and state management for the running agent
`src/agents/pi-embedded-subscribe.handlers.ts`	Event dispatcher — routes SDK events to specialized handlers
`src/agents/pi-embedded-subscribe.handlers.messages.ts`	Handles streaming text events (message_start, update, end)
`src/agents/pi-embedded-subscribe.handlers.tools.ts`	Handles tool execution events (start, update, end)

Tools

File	Responsibility
`src/agents/pi-tools.ts`	`createOpenClawCodingTools()` — assembles all tools for an agent session
`src/agents/openclaw-tools.ts`	Tool definitions and implementations
`src/agents/tools/common.ts`	Shared tool utilities and types
`src/agents/channel-tools.ts`	Channel-specific tool resolution

System Prompt

File	Responsibility
`src/agents/system-prompt.ts`	`buildSystemPrompt()` — modular section-based prompt construction
`src/agents/system-prompt-params.ts`	Runtime parameters for prompt building (timezone, capabilities, model info)
`src/agents/system-prompt-report.ts`	Debug/logging of constructed prompt
`src/agents/pi-embedded-runner/system-prompt.ts`	Embedded-runner-specific prompt logic (overrides, SDK integration)

Gateway

File	Responsibility
`src/gateway/server.impl.ts`	Gateway server initialization, lifecycle management
`src/gateway/server.ts`	Server exports and types
`src/gateway/server-methods.ts`	RPC method dispatch router
`src/gateway/client.ts`	Client-side gateway connection
`src/gateway/auth.ts`	Authentication and authorization
`src/gateway/config-reload.ts`	Hot-reload logic for config and plugin changes
`src/gateway/boot.ts`	Gateway startup sequence
`src/gateway/server-methods/`	50+ method handler files (chat., config., agents.*, etc.)

Channels

File	Responsibility
`src/channels/dock.ts`	Lightweight channel metadata registry (capabilities, limits, threading)
`src/channels/registry.ts`	Channel registration and lookup
`src/channels/plugins/types.plugin.ts`	`ChannelPlugin` interface — the contract every channel must implement

Routing

File	Responsibility
`src/routing/resolve-route.ts`	`resolveRoute()` — maps (channel, peer, guild) to (agent, session key)
`src/routing/session-key.ts`	Session key construction and parsing

Plugin System

File	Responsibility
`src/plugins/registry.ts`	`createPluginRegistry()` — factory + registration collection
`src/plugins/loader.ts`	Plugin discovery and dynamic import
`src/plugins/hooks.ts`	Hook runner — priority-ordered, composable plugin hooks
`src/plugins/discovery.ts`	Filesystem scanning for plugins
`src/plugins/manifest-registry.ts`	Manifest parsing and validation
`src/plugin-sdk/index.ts`	Public plugin SDK (exported as `openclaw/plugin-sdk`)
`src/extensionAPI.ts`	Extension runtime API

Hooks

File	Responsibility
`src/hooks/internal-hooks.ts`	Internal hook registry — simple event-based (registerInternalHook / triggerInternalHook)
`src/plugins/hooks.ts`	Plugin hook runner — typed, priority-ordered, supports modifying hooks
`src/plugins/hook-runner-global.ts`	Global hook runner access

Configuration

File	Responsibility
`src/config/config.ts`	`loadConfig()` — YAML config loading and validation
`src/config/sessions.ts`	Session store — load/save/derive session keys and paths
`src/config/channel-capabilities.ts`	Channel capability resolution

Model & Provider

File	Responsibility
`src/agents/model-auth.ts`	Auth profile resolution for LLM providers
`src/agents/model-selection.ts`	Default model selection per agent
`src/agents/model-fallback.ts`	Automatic model failover on errors
`src/agents/ollama-stream.ts`	Ollama (local model) streaming adapter
`src/agents/anthropic-payload-log.ts`	Anthropic API request/response logging

Session Management

File	Responsibility
`src/agents/session-write-lock.ts`	File-based session locking
`src/agents/session-file-repair.ts`	Corrupt session file detection and repair
`src/agents/session-transcript-repair.ts`	Fix orphaned tool_use/tool_result pairs
`src/agents/pi-embedded-runner/session-manager-init.ts`	Session manager initialization
`src/agents/pi-embedded-runner/session-manager-cache.ts`	Session file caching and prewarming

Skills

File	Responsibility
`src/agents/skills.ts`	Skill loading, env overrides, prompt generation
`src/agents/workspace.ts`	Bootstrap file (OPENCLAW.md) detection

Memory

File	Responsibility
`src/memory/`	Conversation memory, vector search, QMD integration

Infrastructure

File	Responsibility
`src/infra/env.ts`	Environment variable normalization
`src/infra/dotenv.ts`	.env file loading
`src/infra/binaries.ts`	External binary management
`src/infra/ports.ts`	Port availability checking
`src/infra/runtime-guard.ts`	Node.js version validation
`src/infra/warning-filter.ts`	Suppress experimental warnings

Extension Highlights

Located in src/extensions/ — 39 extensions total. Key ones:

Extension	Purpose
`memory-core`	Core memory implementation (MEMORY.md, memory_search, memory_get)
`memory-lancedb`	LanceDB vector database for semantic memory search
`discord`	Discord channel plugin
`slack`	Slack channel plugin
`telegram`	Telegram channel plugin
`whatsapp`	WhatsApp channel plugin
`signal`	Signal channel plugin
`imessage`	iMessage channel plugin
`talk-voice`	Voice call integration
`device-pair`	Mobile device pairing
`diagnostics-otel`	OpenTelemetry observability

Important Prompts

System Prompt Sections (in `src/agents/system-prompt.ts`)

The system prompt is assembled from these sections (in order):

Identity line — Agent name and personality
Skills — Available skills with instructions on how/when to use them
Memory Recall — Instructions for using memory_search and memory_get tools
User Identity — Owner/user identification
Current Date & Time — Timezone context for time-aware responses
Reply Tags — Instructions for [[reply_to_current]] / [[reply_to:<id>]]
Messaging — Channel routing, subagent delegation, message tool documentation
Voice (TTS) — Voice output hints
LLMs.txt — External documentation references
Workspace — Repository structure hints, bootstrap file contents
Runtime — Host, OS, architecture, model, channel info

Prompt Modes

Mode	Sections Included	Use Case
`full`	All sections	Main agent
`minimal`	Tooling, Workspace, Runtime only	Subagents
`none`	Identity line only	Bare-bones

Tool Descriptions

Each tool in src/agents/tools/ has a description field that serves as a prompt to the LLM. These descriptions tell the AI:

What the tool does
When to use it (and when not to)
Parameter constraints and valid values
Expected output format

These are among the most important "prompts" in the system — they directly control how effectively the agent uses its tools.

Bootstrap Files

Projects can include OPENCLAW.md (or configured filename) in their root. This file is automatically included in the system prompt, letting projects customize agent behavior:

Coding conventions
Project-specific instructions
Repository context
Workflow preferences

The agent also loads context files discovered via the resolveBootstrapContextForRun() function, which supports plugin hooks for additional bootstrap content.

Configuration Files

File	Purpose
`package.json`	Main workspace manifest (57 deps, 12 dev deps)
`pnpm-workspace.yaml`	Monorepo workspace (4 packages)
`tsconfig.json`	TypeScript config (ES2023, NodeNext, strict)
`tsdown.config.ts`	Build entry points and bundler config
`vitest.config.ts`	Test config (70% coverage thresholds)
`fly.toml`	Fly.io deployment config
`Dockerfile`	Production container (Node 22 + Bun)
`.oxlintrc.json`	Linter rules

Test Infrastructure

Config File	Scope
`vitest.config.ts`	All tests (unit + integration)
`vitest.unit.config.ts`	Fast unit tests only
`vitest.e2e.config.ts`	End-to-end tests
`vitest.live.config.ts`	Live model tests (requires API keys)
`vitest.extensions.config.ts`	Extension-specific tests
`vitest.gateway.config.ts`	Gateway tests

Coverage thresholds: 70% lines, 70% functions, 55% branches, 70% statements.