132 lines
6.9 KiB
Markdown
132 lines
6.9 KiB
Markdown
|
# 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.
|