Skip to content

Commit 0d38dd4

Browse files
melvincarvalhomelvincarvalho
committed
Expand Introduction (84→230) and Quick Start (129→270) guides
Introduction adds: complete feature overview with categories, community/ecosystem numbers, "What OpenClaw is NOT" section, expanded security warnings with CVE count, system requirements table, comparison to alternatives (Devin, Cursor, Copilot), cost reduction strategies. Quick Start adds: prerequisites with free-tier options, onboarding wizard walkthrough with expected output, execution approval explanation, SOUL.md personalization step, verify-your-setup checklist, common gotchas table (8 issues), structured "What's Next" with Immediate/First Week/Going Deeper tiers. Closes #71
1 parent a894d4b commit 0d38dd4

2 files changed

Lines changed: 400 additions & 58 deletions

File tree

‎docs/getting-started/introduction.md‎

Lines changed: 174 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ description: What is OpenClaw and why it matters — the open-source autonomous
66

77
# Introduction to OpenClaw
88

9-
**OpenClaw** is a free, open-source, autonomous AI agent that runs locally on your machine. It connects large language models — Claude, GPT, Grok, or fully local models — to your files, shell, browser, messaging apps, and dozens of other services.
9+
**OpenClaw** is a free, open-source, autonomous AI agent that runs locally on your machine. It connects large language models — Claude, GPT, Gemini, DeepSeek, Grok, or fully local models — to your files, shell, browser, messaging apps, and dozens of other services.
1010

1111
Think of it as a personal AI assistant that actually *does things*, not just answers questions.
1212

13+
---
14+
1315
## What Makes OpenClaw Different
1416

1517
Unlike chatbots that wait for you to type, OpenClaw is an **autonomous agent**:
@@ -19,18 +21,45 @@ Unlike chatbots that wait for you to type, OpenClaw is an **autonomous agent**:
1921
| Execution | Responds to prompts | Acts proactively via heartbeat |
2022
| Scope | Text in, text out | Full system access (files, shell, browser, APIs) |
2123
| Memory | Session-based | Persistent local Markdown memory |
22-
| Integrations | None | 50+ platforms (WhatsApp, Slack, Gmail, GitHub...) |
24+
| Integrations | None or few | 50+ platforms (WhatsApp, Slack, Gmail, GitHub...) |
2325
| Hosting | Cloud service | Runs on your machine |
2426
| Privacy | Data sent to provider | All data stays local |
27+
| Extensibility | Limited | 10,700+ community skills, 32,600+ MCP servers |
28+
| Autonomy | None | Heartbeat fires every 30 min, takes action without prompting |
29+
30+
---
2531

2632
## Key Capabilities
2733

34+
### Agent Fundamentals
35+
2836
- **Autonomous operation** — The [heartbeat system](/architecture/heartbeat) checks for pending tasks every 30 minutes and takes action without prompting
29-
- **Multi-platform messaging** — Operate through WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Teams, Feishu/Lark, and more
30-
- **10,700+ skills** — Extensible via [ClawHub](/guides/clawhub), the community skill marketplace with security scanning
31-
- **Model-agnostic** — Works with any LLM provider or [local models](/guides/local-models) via Ollama/vLLM
37+
- **Persistent memory** — Remembers facts, preferences, and context across sessions using local Markdown files
38+
- **Multi-step reasoning** — Breaks complex tasks into steps, executes them, and reports results
39+
- **Execution approval** — Asks permission before running shell commands (configurable: ask, auto, or deny)
40+
41+
### Integrations
42+
43+
- **50+ messaging channels** — WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Teams, Matrix, Feishu/Lark, and more
44+
- **MCP ecosystem** — 32,600+ Model Context Protocol servers with 229,800+ tools for databases, APIs, cloud services
45+
- **Browser automation** — Fill forms, scrape pages, interact with web apps
46+
- **Email** — Gmail integration with label management, auto-reply, digest generation
47+
48+
### Extensibility
49+
50+
- **10,700+ skills** — Reusable task templates on [ClawHub](/guides/clawhub), the community marketplace with security scanning
51+
- **Model-agnostic** — Works with any LLM provider (Anthropic, OpenAI, Google, DeepSeek, xAI) or [local models](/guides/local-models) via Ollama, LM Studio, vLLM
52+
- **Multi-agent** — Spawn sub-agents for parallel work: research pipelines, DevOps fleets, specialized workers
53+
- **Plugin system** — Extend the gateway with custom functionality
54+
55+
### Advanced Features
56+
57+
- **Workboard** — Visual task management for tracking multi-step agent work
58+
- **Voice and multimodal** — Voice input/output, image understanding, screen reading
59+
- **Dreaming mode** — Self-directed exploration during idle heartbeat cycles
3260
- **Self-improving** — Can write code for its own new capabilities
33-
- **Private by default** — All data stored locally as Markdown files
61+
62+
---
3463

3564
## A Brief History
3665

@@ -41,44 +70,166 @@ OpenClaw has had one of the most dramatic trajectories in open-source history:
4170
3. **January 28, 2026** — **Moltbook** launches — a social network where AI agents autonomously post, comment, and vote. Andrej Karpathy calls it *"the most incredible sci-fi takeoff-adjacent thing"*
4271
4. **January 30, 2026** — Renamed again to **OpenClaw** ("Moltbot never quite rolled off the tongue") — completing the fastest triple rebrand in open-source history
4372
5. **January 30, 2026** — **CVE-2026-25253** disclosed: a critical one-click RCE vulnerability. Patched in v2026.1.29
44-
6. **Late January 2026** — Goes massively viral, gaining **100,000+ GitHub stars in ~2 days** — the fastest repo to 100K stars in GitHub history
73+
6. **Late January 2026** — Goes massively viral, gaining **100,000+ GitHub stars in ~2 days** — the fastest repo to reach 100K stars in GitHub history
4574
7. **February 2026** — 341 malicious ClawHub skills discovered; VirusTotal partnership announced; 40,000+ exposed instances found; adopted by Alibaba and Tencent; banned by Korean tech firms
46-
47-
As of June 2026, OpenClaw has **377,000+ GitHub stars**, 78,900+ forks, and 365+ contributors. It drew 2 million visitors to its website in a single week.
75+
8. **March 2026** — Structured heartbeat tasks, plugin system v2, and major security hardening
76+
9. **June 2026** — **377,000+ GitHub stars**, 78,900+ forks, 365+ contributors
4877

4978
:::info
5079
Steinberger has said he *"ships code he doesn't read"* — having made 6,600 commits in January alone using AI coding tools. This philosophy of rapid AI-assisted development is both OpenClaw's strength and a source of its security challenges.
5180
:::
5281

82+
---
83+
84+
## Community and Ecosystem
85+
86+
| Metric | Count |
87+
|--------|-------|
88+
| GitHub stars | 377,000+ |
89+
| GitHub forks | 78,900+ |
90+
| Contributors | 365+ |
91+
| Discord members | ~176,000 |
92+
| Reddit subscribers | 143,000+ (r/OpenClaw + r/Clawdbot) |
93+
| ClawHub skills | 10,700+ |
94+
| MCP servers | 32,600+ |
95+
| MCP tools | 229,800+ |
96+
97+
Notable community projects include **Nanobot** (15.9K stars, lightweight alternative), **memU** (8.8K stars, memory system), **Moltworker** (8.4K stars, Docker deployment), and **NanoClaw** (6.9K stars, minimal fork). See [Ecosystem](/reference/ecosystem) for the full landscape.
98+
99+
---
100+
53101
## Who Is This For?
54102

55103
OpenClaw is aimed at:
56104

57-
- **Developers** who want an AI that can read/write code, run tests, manage repos
58-
- **Power users** who want to automate email triage, messaging, scheduling
105+
- **Developers** who want an AI that can read/write code, run tests, manage repos, and automate DevOps
106+
- **Power users** who want to automate email triage, messaging, scheduling, and research
59107
- **Self-hosters** who value privacy and local-first architecture
60108
- **Tinkerers** who want to build custom AI skills and workflows
109+
- **Teams** who want a shared AI agent for monitoring, alerting, and coordination
110+
111+
---
112+
113+
## What OpenClaw is NOT
114+
115+
Setting the right expectations:
116+
117+
- **Not a web UI** — OpenClaw is a CLI and gateway. For a web interface, see [WebClaw](/guides/webclaw) (separate project, 637 stars)
118+
- **Not a coding IDE** — It can write and edit code, but it's not a replacement for VS Code or Cursor. It's a general-purpose agent, not a code editor
119+
- **Not free to run** — OpenClaw itself is MIT-licensed and free, but LLM API calls cost money. Local models are free but require capable hardware
120+
- **Not secure by default** — It runs with your user permissions, has had 10 CVEs in 6 months, and has been called a *"security dumpster fire."* Read the [Security Guide](/security/overview) before deploying
121+
- **Not a hosted service** — You run it on your own machine or server. There's no cloud version (by design — privacy is a core value)
122+
123+
---
124+
125+
## Security: Read This First
126+
127+
OpenClaw grants your AI agent significant system access. Before deploying, understand the risks:
128+
129+
| Risk | Detail |
130+
|------|--------|
131+
| **Full system access** | Runs as your user — can read/write any file, execute any command |
132+
| **10 CVEs in 6 months** | Including a critical one-click RCE (CVE-2026-25253) |
133+
| **Exposed instances** | 40,000+ gateways found open on the internet in February 2026 |
134+
| **Malicious skills** | 341 trojanized skills (12% of ClawHub at the time) discovered in the ClawHavoc campaign |
135+
| **No auth by default** | Gateway port 18789 is open without authentication unless configured |
136+
137+
### How to Stay Safe
138+
139+
1. **Always update** — Critical patches ship frequently
140+
2. **Bind to localhost** — Don't expose port 18789 to the internet
141+
3. **Enable gateway authentication** — Set a token or use reverse proxy auth
142+
4. **Start with `ask` permission mode** — Approve each shell command before it runs
143+
5. **Run `openclaw security audit --deep`** — Built-in security scanner
144+
6. **Use sandboxing** — Docker container, `--container` flag, or VM for high-risk tasks
145+
146+
See [Security Overview](/security/overview) and [Hardening Guide](/security/hardening) for complete guidance.
61147

62148
:::warning
63-
OpenClaw grants your AI agent significant system access. It has been described as a *"security dumpster fire"* by npm's founding CTO and a *"security nightmare"* by Cisco. Before deploying, read the [Security Guide](/security/overview) carefully. Start with read-only permissions and expand gradually.
149+
Start with read-only permissions and expand gradually. Do not run OpenClaw as root. Do not expose the gateway to the internet without authentication.
64150
:::
65151

152+
---
153+
66154
## The Cost Question
67155

68156
OpenClaw itself is free (MIT license), but LLM API costs can add up quickly:
69157

70-
| Usage Level | Approximate Daily Cost |
71-
|-------------|----------------------|
72-
| Light (CLI chat only) | $1–5 |
73-
| Moderate (heartbeat + channels) | $5–20 |
74-
| Heavy (many channels, complex skills) | $20–50+ |
75-
| Local models (Ollama/vLLM) | $0 |
158+
| Usage Level | Approximate Daily Cost | Monthly |
159+
|-------------|----------------------|---------|
160+
| Light (CLI chat only) | $1-5 | $30-150 |
161+
| Moderate (heartbeat + channels) | $5-20 | $150-600 |
162+
| Heavy (many channels, complex skills) | $20-50+ | $600-1,500+ |
163+
| Local models (Ollama/vLLM) | $0 | $0 |
164+
165+
### Reducing Costs
166+
167+
The biggest cost driver is the **heartbeat** — it fires every 30 minutes, 24/7, each cycle consuming tokens. Five changes can cut costs by up to 97%:
168+
169+
| Change | Effect |
170+
|--------|--------|
171+
| Use Haiku/cheap model for heartbeat | Save 80-90% of heartbeat cost |
172+
| Increase heartbeat interval to 60 min | Save 50% |
173+
| Enable quiet hours (no heartbeat while sleeping) | Save 33% |
174+
| Use a local model for heartbeat | Save 100% of heartbeat API cost |
175+
| Enable `isolatedSession` for heartbeat | Reduce context from 100K to 2-5K tokens per cycle |
176+
177+
One documented case: **$1,200/month reduced to $36/month** with model routing alone.
178+
179+
See [Cost Management](/guides/cost-management) and [Performance Tuning](/guides/performance-tuning) for detailed strategies. For the zero-cost path, see [Local Models](/guides/local-models).
180+
181+
---
182+
183+
## How Does It Compare?
184+
185+
OpenClaw occupies a unique position — the only open-source agent with full system access, 50+ channel integrations, persistent memory, and autonomous heartbeat:
186+
187+
| Agent | Type | Autonomy | Integrations | Cost | Open Source |
188+
|-------|------|----------|-------------|------|-------------|
189+
| **OpenClaw** | General-purpose agent | Full (heartbeat) | 50+ channels | $0 + API | Yes (MIT) |
190+
| **Devin** | Coding agent | Task-based | IDE only | $500/mo | No |
191+
| **Cursor Agent** | Coding agent | IDE-embedded | IDE only | $20-40/mo | No |
192+
| **GitHub Copilot Agent** | Coding agent | GitHub-integrated | GitHub | $10-39/mo | No |
193+
| **Open Interpreter** | CLI agent | Reactive only | Shell only | $0 + API | Yes |
194+
| **CrewAI** | Multi-agent framework | Framework-level | Programmatic | $0 + API | Yes |
195+
196+
OpenClaw is the most autonomous and most integrated option — and also the highest risk. The commercial alternatives (Devin, Cursor, Copilot) are more constrained but safer.
197+
198+
See [Comparison](/reference/comparison) for the full feature matrix.
199+
200+
---
201+
202+
## System Requirements
203+
204+
| Component | Minimum | Recommended |
205+
|-----------|---------|-------------|
206+
| **OS** | macOS, Linux, Windows (WSL2 required) | macOS or Linux |
207+
| **Node.js** | 22.19+ LTS | 24 |
208+
| **RAM** | 2 GB (gateway only) | 4 GB+ |
209+
| **Disk** | 500 MB | 2 GB+ (for memory, skills, logs) |
210+
| **Network** | Outbound HTTPS (for cloud LLMs) | Stable connection |
211+
212+
For **local models**, add GPU requirements:
213+
214+
| VRAM | Recommended Model | Quality |
215+
|------|-------------------|---------|
216+
| 8 GB | Qwen3 8B | Basic tasks |
217+
| 16 GB | Qwen3 14B | Good for most tasks |
218+
| 24 GB (RTX 4090) | Qwen3 32B | Excellent daily driver |
219+
| 40-80 GB (A100) | Llama 3.3 70B | Near-cloud quality |
76220

77-
Some users have reported bills of $600+/month with heavy use. See [Local Models](/guides/local-models) for the zero-cost alternative and [Performance Tuning](/guides/performance-tuning) for techniques that have cut costs by 97%.
221+
:::caution
222+
**Windows** requires WSL2 — native Windows support is experimental. **Raspberry Pi** and ARM single-board computers are not supported.
223+
:::
224+
225+
---
78226

79227
## Next Steps
80228

81-
- [Install OpenClaw](/getting-started/installation) on your machine
82-
- Follow the [Quick Start](/getting-started/quick-start) to get running in 5 minutes
83-
- Understand the [Core Concepts](/getting-started/core-concepts) behind the architecture
84-
- Walk through the [First 7 Days](/guides/first-7-days) for a structured learning path
229+
| Step | Time | Link |
230+
|------|------|------|
231+
| Install OpenClaw | 2 min | [Installation](/getting-started/installation) |
232+
| Get your first chat working | 5 min | [Quick Start](/getting-started/quick-start) |
233+
| Understand the architecture | 10 min | [Core Concepts](/getting-started/core-concepts) |
234+
| Structured learning path | 7 days | [First 7 Days](/guides/first-7-days) |
235+
| Lock down security | 15 min | [Security Hardening](/security/hardening) |

0 commit comments

Comments
 (0)