letsbe
/
LetsBeBiz-Redesign
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
LetsBeBiz-Redesign/docs/OPENCLAW_DEEP_DIVE_PROMPT.md

6.9 KiB
Raw Blame History

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.