# OpenClaw Architecture Deep Dive — Claude Code Prompt

Copy everything below the line into Claude Code as your prompt. Point it at the `openclaw/` directory.

---

## Task

Do a comprehensive architectural deep dive of this OpenClaw codebase and produce a single document called `OpenClaw_Architecture_Analysis.md` saved in the `docs/technical/` directory (create the dir if it doesn't exist). This analysis is for the LetsBe Biz team — we're building a privacy-first AI workforce platform for SMBs that uses OpenClaw as its core AI agent runtime. Each customer gets an isolated VPS with OpenClaw + 30 containerized business tools + our custom "Safety Wrapper" proxy layer.

We need to understand OpenClaw deeply enough to: (1) provision it reliably and quickly per customer, (2) build our Safety Wrapper integration layer on top of it, (3) leverage its existing integrations (especially Google, IMAP/Himalaya, email), and (4) write accurate technical documentation.

## Document Structure

Produce the analysis with these exact sections:

### 1. Architecture Overview
- High-level architecture diagram (ASCII/Mermaid)
- Core runtime: what language, what framework, entry point, how it boots
- Package/module structure — what does each top-level directory do?
- Dependency graph of internal packages
- What is `OpenClawKit` (in apps/shared/) and how does it relate to the core?

### 2. Startup & Bootstrap Sequence
- Exact sequence from `openclaw.mjs` (or wherever the entry point is) to "ready to accept requests"
- What config files are read and in what order?
- What environment variables are required vs optional? List ALL of them with descriptions
- What services/connections are established at startup (DB, Redis, message queues, etc.)?
- What is the minimum viable config to get OpenClaw running?

### 3. Plugin/Extension System
- How do extensions (in `extensions/`) work? What's the extension API?
- How are extensions loaded, registered, and activated?
- What hooks/events can extensions listen to?
- What's the `plugin-sdk` export and how would we build a custom extension?
- List ALL extensions with a one-line description of what each does
- Which extensions are relevant for business/productivity use cases vs. chat platform integrations?

### 4. AI Agent Runtime
- How does OpenClaw manage AI agent conversations?
- What LLM providers are supported and how are they configured?
- How does tool/function calling work? What's the tool registration API?
- How are agent "skills" defined (the `skills/` directory)?
- What's the agent execution loop — how does it process a user message end-to-end?
- How does it handle multi-turn conversations, context windows, and memory?
- What is the token counting/tracking mechanism (if any)?

### 5. Tool & Integration Catalog
- List EVERY built-in tool/integration with:
  - Name
  - What it does
  - How it's configured
  - What API/protocol it uses
- Pay special attention to and provide DETAILED analysis of:
  - **Google integration** (Calendar, Drive, Gmail, etc.) — exact OAuth flow, scopes, config
  - **IMAP/Himalaya** — how email reading/sending works, config required
  - **Email capabilities** — any SMTP/sending integrations
  - **File system access** — how agents interact with files
  - **Web browsing/search** — Brave Search and any other web tools
  - **Calendar integrations** — Cal.com, Google Calendar, etc.
- What's the tool execution sandbox? How are tool calls isolated?

### 6. Data & Storage
- What databases does OpenClaw use? (SQLite? Postgres? Custom?)
- What's the data model for conversations, messages, users, agents?
- Where are credentials/secrets stored?
- How does memory/knowledge persistence work?
- What is `memory-core` and `memory-lancedb` in extensions?
- Is there a vector store? How is RAG implemented?

### 7. Deployment & Configuration
- Docker setup: analyze `Dockerfile`, `Dockerfile.sandbox`, `Dockerfile.sandbox-browser`, `docker-compose.yml`
- What does each container do?
- What's the sandbox architecture? How are agent actions sandboxed?
- `docker-setup.sh` — what does it do step by step?
- What ports need to be exposed?
- What volumes need to be mounted?
- What's the minimum system requirements (RAM, CPU, disk)?
- How would you deploy this to a fresh VPS with a single command?

### 8. API Surface
- What HTTP/WebSocket APIs does OpenClaw expose?
- What's the API for sending a message to an agent and getting a response?
- What's the API for managing conversations?
- What authentication mechanism does it use?
- Is there an admin API?
- What's the gateway (referenced in docs/gateway)?

### 9. Security Model
- How does OpenClaw handle authentication and authorization?
- What's in `SECURITY.md`?
- How are secrets managed?
- What sandboxing exists for agent tool execution?
- What are the attack surfaces we need to be aware of?
- How would we insert a proxy layer (our Safety Wrapper) between the agent and tool execution?

### 10. Integration Points for LetsBe Safety Wrapper
This is critical. Based on everything above, identify:
- **Where exactly** in the execution flow should our Safety Wrapper intercept tool calls?
- What interfaces/hooks exist for intercepting agent actions before they execute?
- Can we use the extension system to build the Safety Wrapper as an extension?
- What would a minimal Safety Wrapper extension look like (pseudocode)?
- What agent actions CAN'T be intercepted with the current architecture?
- Recommendations for the integration approach (extension vs. proxy vs. fork)

### 11. Provisioning Blueprint
Based on everything above, design:
- A step-by-step provisioning sequence to spin up OpenClaw on a fresh VPS for a new customer
- Estimated time for each step
- What can be pre-baked into a base image vs. configured at runtime
- Config template with all variables that need to be set per-customer
- Health check sequence to verify the instance is ready
- What the minimum viable OpenClaw setup looks like (fewest containers, simplest config)

### 12. Risks, Limitations & Open Questions
- What parts of OpenClaw are immature, poorly documented, or likely to break?
- What are the scaling limitations?
- What features are missing that we'd need to build ourselves?
- Any licensing concerns for commercial use?
- Version pinning strategy — how stable are releases?
- List any open questions that came up during analysis

## Rules

- Be exhaustive. Read actual source code, don't just skim READMEs.
- Include file paths for every claim (e.g., "defined in `src/core/agent.ts:142`")
- Include actual code snippets for critical interfaces and APIs (keep them short but precise)
- If something is unclear or undocumented, say so explicitly — don't guess
- Prioritize the sections most relevant to our use case: provisioning (§11), Safety Wrapper integration (§10), tool catalog (§5), and deployment (§7)
- The document should be self-contained — someone reading it should understand OpenClaw's architecture without needing to read the source code themselves
- Target length: 3,000-5,000 lines. Be thorough.