Skip to content
The Complete OpenClaw Developer Guide
The Trove library · Marudi

The Complete OpenClaw Developer Guide

A comprehensive guide to building AI agents with OpenClaw — from installation and first steps to advanced multi-agent orchestration, production deployment.

Read a preview
  • 51 chapters
  • Updated Sep 7, 2026
  • 30 readers

What’s inside

  • Introduction to OpenClaw
  • Core Concepts and Architecture
  • Installation and Environment Setup
  • Your First OpenClaw Agent
  • Configuration Deep Dive
  • Built-in Tools Reference

Contents

  1. 01The Complete OpenClaw Developer Guidep.1
    1. How to use this bookp.1
    2. Table of Contentsp.1
  2. 02Introduction to OpenClawp.2
    1. What OpenClaw Isp.2
    2. The Problem OpenClaw Solvesp.2
    3. Architecture in One Paragraphp.2
    4. How OpenClaw Differs from Alternativesp.2
    5. Ideal Use Casesp.2
    6. What OpenClaw Is Notp.2
    7. A Quick First Look: Installationp.2
    8. What This Book Coversp.2
    9. How to Get the Most from This Bookp.2
    10. Summaryp.2
    11. Next Stepsp.2
  3. 03Decision Matrixp.3
  4. 04Core Concepts and Architecturep.4
    1. The Single Governing Thesisp.4
    2. The Five Subsystemsp.4
    3. 1. Channel Adaptersp.4
    4. 2. Session Managerp.4
    5. 3. Message Queuep.4
    6. 4. Agent Runtimep.4
    7. 5. Control Planep.4
    8. The Network Topologyp.4
    9. Key Abstractionsp.4
    10. Agentsp.4
    11. Toolsp.4
    12. Memoryp.4
    13. Contextp.4
    14. Sessionsp.4
    15. The Seven-Stage Execution Loopp.4
    16. The Mental Model: Thinking in OpenClawp.4
    17. Summaryp.4
    18. Next Stepsp.4
  5. 05Installation and Environment Setupp.5
    1. Prerequisites and System Requirementsp.5
    2. Installing OpenClawp.5
    3. Method 1: Official Install Script (macOS and Linux)p.5
    4. Method 2: PowerShell (Windows)p.5
    5. Method 3: npm Global Installp.5
    6. Method 4: Dockerp.5
    7. Method 5: Nixp.5
    8. Setting Up API Keysp.5
    9. Running the Onboarding Wizardp.5
    10. Directory Structurep.5
    11. Creating Your First Projectp.5
    12. Verifying the Installationp.5
    13. IDE and Editor Setupp.5
    14. VS Codep.5
    15. JetBrains (WebStorm, IntelliJ)p.5
    16. Neovim / Vimp.5
    17. Any Editor: Workspace Git Setupp.5
    18. Development Installation (Contributing or Building From Source)p.5
    19. Summaryp.5
    20. Next Stepsp.5
    21. Agent rulesp.5
  6. 06Your First OpenClaw Agentp.6
    1. Prerequisitesp.6
    2. Step 1: Install OpenClawp.6
    3. Step 2: Run the Onboarding Wizardp.6
    4. Step 3: Verify the Gateway Is Runningp.6
    5. Step 4: Inspect Your Default Agent Filesp.6
    6. Step 5: Send Your First Messagep.6
    7. Step 6: Watch the Logsp.6
    8. Step 7: Iterate on Your First Skillp.6
    9. Step 8: Customize Your AGENTS.mdp.6
    10. Debugging: When the Agent Does Not Respondp.6
    11. Understanding Console Outputp.6
    12. The Minimal Working Agent: What You Builtp.6
    13. Summaryp.6
    14. Next Stepsp.6
  7. 07Configuration Deep Divep.7
    1. The Configuration Hierarchyp.7
    2. The Main Config Filep.7
    3. Top-Level Structurep.7
    4. The `agents` Blockp.7
    5. `model.primary`p.7
    6. `model.fallbacks`p.7
    7. `heartbeat.every` and `heartbeat.model`p.7
    8. `cache_ttl`p.7
    9. `compaction`p.7
    10. The `channels` Blockp.7
    11. `dmPolicy`p.7
    12. `allowFrom`p.7
    13. `groupPolicy`p.7
    14. The `bindings` Arrayp.7
    15. The `logging` Blockp.7
    16. Log Levelsp.7
    17. `consoleStyle`p.7
    18. `redactSensitive`p.7
    19. Log File Detailsp.7
    20. Environment Overridep.7
    21. Timestamp and Timezone Configurationp.7
    22. `envelopeTimezone`p.7
    23. `timeFormat`p.7
    24. Environment Variablesp.7
    25. Auth Profiles and Secrets Managementp.7
    26. Profile Typesp.7
    27. Credential Portability Rulesp.7
    28. Auth Probe Reason Codesp.7
    29. Secrets Management Recommendationsp.7
    30. Multi-Environment Profilesp.7
    31. Directory-per-environment Patternp.7
    32. Recommended Dev Config Differencesp.7
    33. Configuration Validationp.7
    34. Config Precedence: Worked Examplep.7
    35. Summaryp.7
    36. Next Stepsp.7
  8. 08Built-in Tools Referencep.8
    1. File System Toolsp.8
    2. `read`p.8
    3. `write`p.8
    4. `list`p.8
    5. `delete`p.8
    6. `move` and `copy`p.8
    7. Web Toolsp.8
    8. `web_fetch`p.8
    9. `web_search`p.8
    10. Memory Toolsp.8
    11. `memory_search`p.8
    12. `memory_write`p.8
    13. Agent and Session Toolsp.8
    14. `sessions_spawn`p.8
    15. `ask_user_question`p.8
    16. Scheduling Toolp.8
    17. `schedule`p.8
    18. Shell and Package Toolsp.8
    19. Shell Command Executionp.8
    20. `install_packages`p.8
    21. `add_mcp_server`p.8
    22. Combining Tools Effectivelyp.8
    23. Security Considerations Across All Toolsp.8
    24. Summaryp.8
    25. Next Stepsp.8
See all 51 parts
  1. 09Building Custom Toolsp.9
    1. The Two Paths to Custom Toolsp.9
    2. The Tool Development APIp.9
    3. Defining Tool Schemas and Type Signaturesp.9
    4. Use the Narrowest Type That Worksp.9
    5. Mark Exactly the Required Fieldsp.9
    6. TypeScript Type Inference from Schemap.9
    7. Implementing Tool Handlersp.9
    8. Return Structured Data, Not Prosep.9
    9. Write Error Messages That Tell the Agent What to Do Nextp.9
    10. Error Handling in Toolsp.9
    11. Designing for Idempotencyp.9
    12. Testing Tools in Isolationp.9
    13. Unit Testing with Mocked Contextp.9
    14. Live Integration Testingp.9
    15. MCP Server Integrationp.9
    16. Adding an MCP Server to an Agentp.9
    17. MCP Server Structure (TypeScript)p.9
    18. Packaging and Sharing Tools via Skillsp.9
    19. Skill Directory Structurep.9
    20. SKILL.md for a Tool Skillp.9
    21. Publishing to ClawHubp.9
    22. Tool Registryp.9
    23. Registering a Code-Based Toolp.9
    24. Tool Allowlists and Policiesp.9
    25. Summaryp.9
    26. Next Stepsp.9
    27. Agent rulesp.9
  2. 10Agent Patterns and Workflowsp.10
    1. Sequential Agent Chainsp.10
    2. Basic Sequential Chain with OpenProsep.10
    3. Sequential Chain via an Orchestrator Agentp.10
    4. Passing Context Between Stepsp.10
    5. Pattern 1: Inline String Injectionp.10
    6. Pattern 2: Structured Intermediate Filesp.10
    7. Pattern 3: Structured JSON Handoffp.10
    8. Branching Logic and Conditional Executionp.10
    9. Conditional Branching in OpenProsep.10
    10. Branching via Orchestrator Reasoningp.10
    11. Retry and Fallback Patternsp.10
    12. Model Fallback Configurationp.10
    13. Retry Logic in OpenProsep.10
    14. Output Validation with Retryp.10
    15. Agent Compositionp.10
    16. Generator-Verifier Compositionp.10
    17. The CEO/COO/Worker Topologyp.10
    18. Workflow Orchestration Patternsp.10
    19. Parallel Fan-Out with Synthesisp.10
    20. The Human-in-the-Loop Gatep.10
    21. Error Escalation Patternp.10
    22. Putting It Together: A Complete Orchestration Examplep.10
    23. Summaryp.10
    24. Next Stepsp.10
  3. 11Memory and State Managementp.11
    1. Understanding the Memory Hierarchyp.11
    2. Tier 1: MEMORY.md — The Pointer Indexp.11
    3. Tier 2: memory/*.md — Working Knowledgep.11
    4. Tier 3: vault/ — Deep Storagep.11
    5. In-Context Memory: Conversation Historyp.11
    6. How Sessions Are Storedp.11
    7. Context Window Pressurep.11
    8. Size Budgets by Filep.11
    9. Compaction: Managing History Growthp.11
    10. Cache-TTL Modep.11
    11. Manual Session Resetp.11
    12. Persistent Memory with Vector Storesp.11
    13. State Between Agent Runsp.11
    14. Caching Strategiesp.11
    15. The April 2026 TTL Changep.11
    16. What Gets Cachedp.11
    17. Heartbeat Cachingp.11
    18. Memory Maintenance: The Dream Processp.11
    19. Debugging Memory and State Issuesp.11
    20. Checking Effective Context Sizep.11
    21. Inspecting Session Historyp.11
    22. Verifying Memory Search is Workingp.11
    23. Model Call Metricsp.11
    24. Summaryp.11
    25. Next Stepsp.11
  4. 12Error Handling and Debuggingp.12
    1. Error Taxonomy in OpenClawp.12
    2. Category 1 — Configuration Errorsp.12
    3. Category 2 — Auth Errorsp.12
    4. Category 3 — Channel Errorsp.12
    5. Category 4 — Model Errorsp.12
    6. Category 5 — Tool Errorsp.12
    7. Category 6 — Session Errorsp.12
    8. Graceful Degradation Strategiesp.12
    9. Fallback Model Chainsp.12
    10. Tool Unavailability Handlingp.12
    11. Channel Degradationp.12
    12. Retry with Backoffp.12
    13. Timeout Handlingp.12
    14. Comprehensive Logging Setupp.12
    15. Recommended Production Configurationp.12
    16. Development / Debugging Configurationp.12
    17. Environment Variable Overridep.12
    18. Log Rotationp.12
    19. Accessing Logsp.12
    20. Debugging with Tracesp.12
    21. Enable Trace-Level Logging for One Sessionp.12
    22. Gateway Debug UIp.12
    23. Session File Inspectionp.12
    24. Tracing a Tool Permission Failurep.12
    25. Common Errors and Their Fixesp.12
    26. "Gateway not starting"p.12
    27. "Agent not responding"p.12
    28. "API cost spiking unexpectedly"p.12
    29. "OpenProse workflow failing silently"p.12
    30. "Auth error: unresolved_ref"p.12
    31. "Model error: context length exceeded"p.12
    32. Summaryp.12
    33. Next Stepsp.12
  5. 13Multi-Agent Systemsp.13
    1. When to Use Multiple Agentsp.13
    2. Anthropic's Five Coordination Patternsp.13
    3. The CEO/COO/Worker Modelp.13
    4. Agent-to-Agent Communicationp.13
    5. Parallel Executionp.13
    6. Handoffs and Routingp.13
    7. Shared Memory Between Agentsp.13
    8. Credential Portability in Multi-Agent Systemsp.13
    9. Avoiding Coordination Pitfallsp.13
    10. Production Multi-Agent Configuration Examplep.13
    11. Summaryp.13
    12. Next Stepsp.13
    13. Agent rulesp.13
  6. 14Production Deploymentp.14
    1. Deployment Architecturep.14
    2. Choosing a Hostp.14
    3. VPS Deployment Patternp.14
    4. Systemd: Keeping the Gateway Runningp.14
    5. Docker and Containerizationp.14
    6. Environment Variable Managementp.14
    7. Scaling Strategiesp.14
    8. Vertical Scaling (Recommended First)p.14
    9. Horizontal Scalingp.14
    10. Multi-Agent Load Distributionp.14
    11. Monitoring and Observabilityp.14
    12. Log Accessp.14
    13. Querying Logsp.14
    14. Health Checksp.14
    15. Control UI for Live Debuggingp.14
    16. Cost Management and Token Budgetingp.14
    17. The Four Cost Leversp.14
    18. Token Budget Estimatesp.14
    19. Cost Monitoring Scriptp.14
    20. CI/CD Integrationp.14
    21. Workspace Versioningp.14
    22. Deploying Configuration Changesp.14
    23. Security Audit in CIp.14
    24. Security Hardening for Productionp.14
    25. Summaryp.14
    26. Agent rulesp.14
    27. Next Stepsp.14
  7. 15Advanced Patternsp.15
    1. Self-Reflection and Self-Critique Loopsp.15
    2. Simple Self-Critique via AGENTS.mdp.15
    3. Multi-Pass Critique with Toolsp.15
    4. Chain-of-Thought Enforcementp.15
    5. RAG Integration for Knowledge Retrievalp.15
    6. Pattern 1: MCP-Based Vector Retrievalp.15
    7. Pattern 2: Web-Based RAG with web_fetchp.15
    8. Injecting Retrieved Context Efficientlyp.15
    9. Planning Agentsp.15
    10. The Plan-Then-Execute Patternp.15
    11. Hierarchical Planning for Complex Tasksp.15
    12. Dynamic Tool Selectionp.15
    13. Tool Routing via TOOLS.mdp.15
    14. Capability Discovery Patternp.15
    15. Agentic Loops with Termination Conditionsp.15
    16. Defining Termination Conditions in AGENTS.mdp.15
    17. Implementing a Monitoring Loopp.15
    18. Loop State Managementp.15
    19. Combining the Patterns: A Research Agentp.15
    20. Summaryp.15
    21. Next Stepsp.15
  8. 16Real-World Use Cases and Complete Examplesp.16
    1. Example 1: Research Assistant Agentp.16
    2. Design Goalsp.16
    3. Configurationp.16
    4. Bootstrap Filesp.16
    5. Skill: Research Deep Divep.16
    6. Example Interactionp.16
    7. Customization Guidep.16
    8. Example 2: Code Review and PR Agentp.16
    9. Design Goalsp.16
    10. Configurationp.16
    11. Bootstrap Filesp.16
    12. The Approval Gate Patternp.16
    13. Skill: GitHub PR Monitorp.16
    14. Customization Guidep.16
    15. Example 3: Data Analysis Pipeline Agentp.16
    16. Design Goalsp.16
    17. Configurationp.16
    18. Bootstrap Filesp.16
    19. Analysis Skillp.16
    20. Row and column countp.16
    21. Quick null checkp.16
    22. Numeric summary (requires awk)p.16
    23. Data Analysis Reportp.16
    24. Data Qualityp.16
    25. Executive Summaryp.16
    26. Descriptive Statisticsp.16
    27. Anomaliesp.16
    28. Correlationsp.16
    29. Recommended Next Stepsp.16
  9. 17Support Bot — Operating Instructionsp.17
    1. Response Protocolp.17
    2. Escalation Protocolp.17
    3. Escalation Handoff Formatp.17
    4. Hard Policyp.17
    5. Tone Rulesp.17
  10. 18Product Knowledge Skillp.18
    1. Documentation Sourcesp.18
    2. Confidence Assessmentp.18
    3. Common Question Categoriesp.18
    4. Response Formatp.18
  11. 19Escalation Log — 2026-06-08p.19
    1. 09:14 — @user_alicep.19
    2. 11:32 — @user_bobp.19
  12. 20Start the Gateway daemonp.20
  13. 21Stop a running Gatewayp.21
  14. 22Restart (applies config changes without clearing sessions)p.22
  15. 23Check whether the Gateway is running and on which portp.23
  16. 24Launch in development mode (verbose, hot-reload)p.24
  17. 25Open the browser-based Debug UIp.25
  18. 26Run the interactive onboarding wizard (recommended for first install)p.26
  19. 27Re-run setup for workspace bootstrap files onlyp.27
  20. 28Open the Control UI dashboard in the default browserp.28
  21. 29List all configured agentsp.29
  22. 30Create a new agentp.30
  23. 31Show current configuration for an agentp.31
  24. 32Dump the full runtime state of an agent (model, skills, memory)p.32
  25. 33Check whether an agent is active and responsivep.33
  26. 34Set a configuration value for an agentp.34
  27. 35Examplesp.35
  28. 36List connected channels and their statusp.36
  29. 37Reconnect a channel that has dropped (e.g., after WhatsApp QR expiry)p.37
  30. 38Example: reconnect WhatsAppp.38
  31. 39Install a skill from ClawHubp.39
  32. 40List installed skillsp.40
  33. 41Enable a pluginp.41
  34. 42Disable a pluginp.42
  35. 43Example: enable the OpenProse multi-agent pluginp.43
  36. 44Follow live log output (human-readable)p.44
  37. 45Follow with structured JSON outputp.45
  38. 46Show timestamps in local timep.46
  39. 47Show logs with both flagsp.47
  40. 48Diagnose common configuration problemsp.48
  41. 49Diagnose and auto-fix common problemsp.49
  42. 50Run a full pre-deployment security auditp.50
  43. 51Send a test message to an agent directly (useful in dev mode)p.51

From the first page

> Load this book when: > - You are installing, configuring, or operating an OpenClaw Gateway and need the exact config keys, CLI commands, or directory layout. > - You are authoring agents (bootstrap files, skills, MCP servers) or multi-agent workflows (OpenProse / Task Flow). > - You are hardening or debugging a production OpenClaw deployment (cost runaways, CVEs, ClawHub skill risk, auth/cache issues). > - You are deciding whether OpenClaw fits a use case versus Claude Code / LangChain / AutoGen / CrewAI.

Audience & governance: Public marketplace reference. Maintainer: Marudi. Attribution required; built from openclaw.ai docs, github.com/openclaw/openclaw, and cited community/security sources.

Last updated: 2026-06-14 · Scope of validity: OpenClaw v2026.6.x. Version-pinned facts (CLI flags, config keys, CVE list, model IDs) expire fastest — see Chapter 17 (Currency & Scope) before trusting any version-specific claim.

Read a preview

1. Read this page and the Decision Matrix (Chapter 2). 2. Jump to the chapters the matrix lists for your task. Do not read linearly. 3. Each chapter opens with its own > Load this page when: trigger and is self-contained. 4. Cross-references use chapter numbers within this book and CandleKeep IDs across books.

1. Introduction to OpenClaw 2. Decision Matrix ← start here for navigation 3. Core Concepts and Architecture 4. Installation and Environment Setup 5. Your First OpenClaw Agent 6. Configuration Deep Dive 7. Built-in Tools Reference 8. Building Custom Tools 9. Agent Patterns and Workflows 10. Memory and State Management 11. Error Handling and Debugging 12. Multi-Agent Systems 13. Production Deployment 14. Advanced Patterns 15. Real-World Use Cases and Complete Examples 16. Reference Guide and Appendices 17. Currency & Scope of Validity 18. Corrections & Stale-Fact Supersedes

Add this book to your library to keep reading.

About this book

A comprehensive guide to building AI agents with OpenClaw — from installation and first steps to advanced multi-agent orchestration, production deployment, and real-world examples. Covers all features, configuration, tools, patterns, and best practices. Tags: ai, agents, openclaw, development, guide.

Read more

Marudi · markdown · Listed Jun 8, 2026

Distributed Task Reliability for AI Agents: Idempotency, Retries & Queues

Distributed Task Reliability for AI Agents: Idempotency, Retries & Queues

Nested Sub-Agents in OrchestKit: Adopting CC 2.1.172–2.1.173

Nested Sub-Agents in OrchestKit: Adopting CC 2.1.172–2.1.173

The Complete Guide to the Vercel AI SDK

The Complete Guide to the Vercel AI SDK

Building Agents in Production

Building Agents in Production