# openclaw-handbook **Repository Path**: agentq/openclaw-handbook ## Basic Information - **Project Name**: openclaw-handbook - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-14 - **Last Updated**: 2026-03-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🦞 OpenClaw Engineer's Handbook > A comprehensive technical reference for engineers building and operating AI agents with OpenClaw — covering architecture, configuration, orchestration, memory, security, and cost optimization. This handbook was built from hands-on experience running OpenClaw in production. It goes deeper on the things that actually trip people up: context compaction, multi-agent patterns, cost control, Tailscale security, and writing workspace files that actually work. --- ## What's in here | File | Contents | |---|---| | [📖 Handbook](./01-handbook.md) | Complete technical reference — 30 chapters | | [💰 Cost Optimization](./02-cost-optimization.md) | Model tiering, LLM cost reduction techniques | --- ## Handbook — Table of Contents ### Foundation - [1. What is OpenClaw](./01-handbook.md#1-what-is-openclaw) — Architecture positioning, how it differs from ChatGPT, core concepts - [2. Installation & First Run](./01-handbook.md#2-installation--first-run) — Prerequisites, npm install, onboarding wizard, `.env` setup - [3. Core Architecture](./01-handbook.md#3-core-architecture--how-it-works-internally) — Gateway vs. Agent Runtime, WebSocket protocol, the agentic loop, command queue ### Configuration & Files - [4. Configuration Reference](./01-handbook.md#4-configuration-reference) — Full annotated `openclaw.json`, every setting explained - [5. File Structure](./01-handbook.md#5-file-structure--every-file-explained) — Every file in `~/.openclaw/` and the workspace, what each one does - [6. Sessions & Agent Channels](./01-handbook.md#6-sessions--agent-channels) — Session lifecycle, DM scope, channel bindings and routing ### Scheduling - [7. Heartbeat vs. Cron](./01-handbook.md#7-heartbeat-vs-cron--complete-breakdown) — Full breakdown, config examples, when to use which, comparison table ### Agent Orchestration - [8. Agent Orchestration & Multi-Agent Patterns](./01-handbook.md#8-agent-orchestration--multi-agent-patterns) — Sub-agents, orchestrator pattern, spawn depth, agent-to-agent communication ### Memory - [9. Managing Agent Memory](./01-handbook.md#9-managing-agent-memory) — Three memory layers, daily logs, vector search, Mem0/Cognee integrations - [10. Context Window Management & Compaction](./01-handbook.md#10-context-window-management--compaction) — The compaction danger, pre-flush config, context pruning ### Security & Permissions - [11. Sandbox Modes & Tool Permissions](./01-handbook.md#11-sandbox-modes--tool-permissions) — `off/non-main/all` modes, `tools.allow/deny`, available tool groups - [22. Securing OpenClaw with Tailscale](./01-handbook.md#22-securing-openclaw-with-tailscale) — Serve vs. Funnel, setup walkthrough, security best practices ### Skills & Integrations - [12. Adding Skills & MCP Integration](./01-handbook.md#12-adding-skills--mcp-integration) — Skill format, ClawHub, custom skills, MCP servers, skills vs. MCP - [13. Channel Setup Guides](./01-handbook.md#13-channel-setup-guides) — WhatsApp, Telegram, Slack, Discord step-by-step - [18. Browser Automation](./01-handbook.md#18-browser-automation) — All browser tool calls, real examples, config ### Operations - [14. Access Control & Multi-User Setup](./01-handbook.md#14-access-control--multi-user-setup) — allowFrom, dmPolicy, pairing flow, session isolation - [15. Slash Commands — Full Reference](./01-handbook.md#15-slash-commands--full-reference) — Every `/command` with description - [19. Auth Profiles & Model Failover](./01-handbook.md#19-auth-profiles--model-failover) — `auth-profiles.json`, failover chain logic, monitoring - [23. WebChat UI](./01-handbook.md#23-webchat-ui) — Local browser interface, when to use it vs. messaging apps ### Advanced - [16. Writing Effective Workspace Files](./01-handbook.md#16-writing-effective-workspace-files) — AGENTS.md, SOUL.md, USER.md, HEARTBEAT.md, MEMORY.md best practices with real examples - [17. Lobster — The Workflow Engine](./01-handbook.md#17-lobster--the-workflow-engine) — YAML syntax, LLM task steps, approval gates, loops - [20. Hooks System](./01-handbook.md#20-hooks-system) — TypeScript lifecycle hooks with code examples - [21. Canvas (A2UI)](./01-handbook.md#21-canvas-a2ui) — Visual workspace, tool calls, use cases ### Reliability & Cost - [24. Privacy & Data Flow Map](./01-handbook.md#24-privacy--data-flow-map) — Exactly what leaves your machine, local-only config - [25. Backup, Recovery & Disaster Prep](./01-handbook.md#25-backup-recovery--disaster-prep) — Git backup strategy, golden config, recovery procedure - [26. Troubleshooting & openclaw doctor](./01-handbook.md#26-troubleshooting--openclaw-doctor) — Common failures with fix commands - [27. Performance Tuning](./01-handbook.md#27-performance-tuning) — Concurrency, debounce, context pruning, model selection ### Reference - [28. How OpenClaw Differs From Other Tools](./01-handbook.md#28-how-openclaw-differs-from-other-tools) — vs. LangChain, CrewAI, n8n, OpenAI Assistants - [29. Deployment Patterns](./01-handbook.md#29-deployment-patterns) — Mac Mini, VPS, Docker, multi-agent setup - [30. Security Audit Checklist](./01-handbook.md#30-security-audit-checklist) — 30-point pre-production checklist --- ## Cost Optimization — Table of Contents - [The Core Principle](./02-cost-optimization.md#the-core-principle) - [Model Tiers — What They Cost](./02-cost-optimization.md#model-tiers--what-they-cost-and-what-theyre-good-for) — Heavy hitters, workhorses, micro-models - [Technique 1 — Per-agent model assignment](./02-cost-optimization.md#technique-1--per-agent-model-assignment) - [Technique 2 — Per-cron-job model assignment](./02-cost-optimization.md#technique-2--per-cron-job-model-assignment) - [Technique 3 — Heartbeat with cheapest model](./02-cost-optimization.md#technique-3--heartbeat-with-the-cheapest-model) - [Technique 4 — Sub-agent model tiering](./02-cost-optimization.md#technique-4--sub-agent-model-tiering) - [Technique 5 — Context pruning](./02-cost-optimization.md#technique-5--context-pruning-stop-paying-for-old-tool-results) - [Technique 6 — Compaction threshold tuning](./02-cost-optimization.md#technique-6--compaction-threshold-tuning) - [Technique 7 — Daily session reset](./02-cost-optimization.md#technique-7--daily-session-reset) - [Technique 8 — Slim down workspace files](./02-cost-optimization.md#technique-8--slim-down-workspace-files) - [Technique 9 — Lazy skill loading](./02-cost-optimization.md#technique-9--lazy-skill-loading) - [Technique 10 — Local models via Ollama](./02-cost-optimization.md#technique-10--local-models-via-ollama-for-appropriate-tasks) - [Technique 11 — Queue debounce](./02-cost-optimization.md#technique-11--queue-debounce-to-batch-messages) - [Decision Framework — Which model to pick](./02-cost-optimization.md#decision-framework--which-model-to-pick) - [Quick Wins Checklist](./02-cost-optimization.md#quick-wins-checklist) --- ## Who this is for Engineers and developers who are: - Setting up OpenClaw for the first time and want to go beyond the basics - Running OpenClaw in production and hitting edge cases - Building multi-agent systems and want reference patterns - Trying to reduce LLM API costs without sacrificing capability - Deploying OpenClaw for a team and need to think about security and access control --- ## Prerequisites assumed - Comfortable with terminal and JSON config files - Basic understanding of how LLMs work (context windows, tokens, tool use) - Familiarity with concepts like cron expressions, WebSockets, and environment variables No prior OpenClaw experience required — the handbook starts from installation. --- ## Contributing Found something wrong, outdated, or missing? PRs are welcome. - **Corrections** — open a PR directly - **New sections** — open an issue first to discuss scope - **Config examples** — especially welcome, the more real-world the better Please keep examples generic (no real API keys, no personal details). --- ## Resources - [OpenClaw Official Docs](https://docs.openclaw.ai) - [OpenClaw GitHub](https://github.com/openclaw/openclaw) - [ClawHub Skills Registry](https://clawhub.io) - [OpenClaw Discord](https://discord.gg/openclaw) --- ## Author Built by [Tanzeel Saleem](https://www.linkedin.com/in/tanzeel-saleem/) — Founder of DevNexus, a software development agency specializing in web, mobile, and AI solutions. 📧 [info@devnexus.co](mailto:info@devnexus.co) 🌐 [devnexus.co](https://devnexus.co) --- ## License MIT — use freely, attribution appreciated but not required. --- *Built with production experience. Corrections and additions welcome.*