v3.2 — Updated April 2026

OpenClaw Beginner Tutorial

Everything you need to go from zero to your first project. A step-by-step guide covering installation, core commands, and best practices.

Start Learning Quick Install
$ openclaw init my-first-app
✔ Scaffolding project in ./my-first-app
✔ Installing dependencies (3.2s)
✔ Setting up default config
$ cd my-first-app && openclaw dev
→ Dev server running at http://localhost:4000
→ Hot reload enabled
→ Ready in 240ms
Learning Path

Your Journey with OpenClaw

Follow this guided path from fundamentals to your first deployment. Each stage builds on the previous one.

01

Understand the Basics

Learn what OpenClaw is, its architecture, and why teams choose it for modern application pipelines.

~15 min read
02

Install & Configure

Set up OpenClaw on your machine, configure your environment, and verify everything works.

~10 min setup
03

Build Your First App

Follow a hands-on tutorial to scaffold, develop, and run a working project locally.

~25 min tutorial
04

Deploy & Iterate

Ship your project to production, set up CI/CD hooks, and learn the deployment lifecycle.

~20 min guide
Installation

Get Started in Seconds

OpenClaw works on macOS, Linux, and Windows. Choose your preferred method below.

npm / yarn / pnpm

Recommended for most users

# Using npm
npm install -g openclaw
# Or using pnpm
pnpm add -g openclaw
# Verify installation
openclaw --version # → 3.2.0

Shell Script (macOS / Linux)

One-line install without Node.js

curl -fsSL https://get.openclaw.dev | sh
# This installs the standalone binary
# Works on macOS (ARM/Intel) & Linux
# After install, restart your terminal
openclaw doctor # check env health

Docker

Containerised development environment

docker pull openclaw/cli:3.2
# Run with current directory mounted
docker run --rm -v $(pwd):/app \
openclaw/cli:3.2 init my-app
# Great for CI pipelines
First Project

Build a Task Tracker in 5 Steps

Create a working task tracker from scratch to learn OpenClaw's core workflow.

1

Scaffold the Project

Generate a new project with the task-tracker template. OpenClaw creates the folder structure, config files, and installs dependencies automatically.

openclaw init task-tracker --template starter
✔ Created 12 files in ./task-tracker
2

Define Your Data Model

Open schema/tasks.claw and define the Task entity. OpenClaw schemas are declarative — just describe the shape of your data.

entity Task {
title : String @required
done : Boolean @default(false)
priority : Enum("low", "mid", "high")
created : DateTime @auto
}
3

Generate Routes & Handlers

Use the generate command to create CRUD endpoints from your schema. OpenClaw reads the entity and creates type-safe handlers.

openclaw generate routes --from schema/tasks.claw
✔ Generated: routes/tasks.ts (create, read, update, delete)
✔ Generated: handlers/tasks.ts (4 handlers)
4

Start the Dev Server

Launch the development server with hot reload. OpenClaw watches for file changes and restarts automatically.

openclaw dev
→ Watching 14 files for changes
→ API: http://localhost:4000/api
→ Dashboard: http://localhost:4000/_dash
5

Test & Verify

Run the built-in test suite to make sure everything works. OpenClaw auto-generates smoke tests for your routes.

openclaw test --watch
✔ 4/4 tests passed (tasks: create, read, update, delete)
→ Watching for changes…
Common Commands

Commands You'll Use Every Day

A quick-reference cheat sheet for the most essential OpenClaw CLI commands.

Scaffold openclaw init <name>

Create a new project with default configuration. Add --template to use a specific starter.

Develop openclaw dev

Start local dev server with hot reload, file watching, and the built-in dashboard.

Generate openclaw generate <type>

Auto-generate routes, handlers, tests, or migrations from your schema definitions.

Test openclaw test

Run all tests. Use --watch for live re-runs or --coverage for a coverage report.

Deploy openclaw deploy

Build and deploy to your configured target (cloud, container, or edge). Runs checks automatically.

Diagnose openclaw doctor

Check your environment: Node version, dependencies, config validity, and port availability.

Migrate openclaw migrate

Apply pending data migrations. Use --dry-run to preview changes without executing.

Plugins openclaw plugin add <name>

Install community or official plugins. Use plugin list to browse available extensions.

Troubleshooting

Common Issues & Fixes

Stuck? These are the problems beginners run into most often, with proven solutions.

"openclaw: command not found" after install
Your shell doesn't see the global bin path. Run openclaw doctor --path to print the correct PATH entry, then add it to your ~/.bashrc or ~/.zshrc and restart your terminal.
Port 4000 already in use
Another process is using the default port. Either stop it, or run openclaw dev --port 4001 to use a different port. You can also set port: 4001 in openclaw.config.yaml.
Schema validation error on generate
Check your .claw file for typos in type names. Common mistakes: using string instead of String, or missing the closing brace. Run openclaw lint schema/ for detailed error locations.
Hot reload not detecting changes
On Linux, you may hit the inotify watch limit. Increase it with echo 65536 | sudo tee /proc/sys/fs/inotify/max_user_watches. On macOS, this usually means the fsevents module is missing — reinstall dependencies.
Deploy fails with "missing build artifact"
Run openclaw build before deploying. If the build itself fails, check that all environment variables referenced in your config are defined. Use openclaw env check to list missing variables.
Tests pass locally but fail in CI
This is usually a Node.js version mismatch. OpenClaw 3.2 requires Node 20+. Add node: '20' to your CI matrix and make sure openclaw doctor runs as the first CI step.
Next Steps

Where to Go from Here

You've got the basics down. Here's the recommended path to level up your skills.

Master the Plugin System

Extend OpenClaw with community plugins for auth, database connectors, caching, and more. Learn to write your own plugins.

Intermediate

Schema Relationships & Migrations

Define one-to-many and many-to-many relationships between entities. Manage data evolution with versioned migrations.

Intermediate

Testing Strategies

Go beyond auto-generated smoke tests. Write integration tests, mock external services, and measure coverage thresholds.

Intermediate

Production Deployment Patterns

Learn blue-green deployments, environment-specific configs, secrets management, and rollback procedures.

Advanced

Contribute to OpenClaw

Join the open-source community. Report issues, submit pull requests, write plugins, and help improve documentation.

Community