I've learned a lot from teaching this material. The same patterns repeat: people hit the same walls, ask the same questions, and get stuck at the same points. This guide is the fix — every common stumbling block is patched in. Three tiers, everything you need, nothing you don't.

Getting Started (Beginner)

Goal: Understand the system you just set up. Learn what each piece does, how they connect, and how to debug when things go wrong.

If you followed Part 1, you already have a running agent on Telegram with a dashboard. This tier gives you the mental model to understand what's happening under the hood.

The four building blocks

OpenClaw has four distinct mechanisms, and understanding which is "soft" (guidance) vs "hard" (enforced by the runtime) matters:

Markdown rules are the files you'll edit most. SOUL.md defines personality. AGENTS.md sets behavior guidelines. TOOLS.md provides usage guidance (but doesn't control tool availability — that's the runtime's job). HEARTBEAT.md is a checklist your agent follows during heartbeat runs. None of these are enforced by the system — they're instructions the AI reads and follows, like a detailed brief.

Heartbeats bridge hard and soft: the schedule is hard (runs every 30 minutes whether you ask it to or not), but the behavior follows whatever soft guidance is in HEARTBEAT.md. If the file is effectively empty, the heartbeat run is skipped to save API calls.

Cron jobs are fully hard-scheduled. They persist across server restarts, run at defined times, and can operate in isolated sessions separate from your main conversation.

Plugins are code extensions for when markdown isn't enough. They can register tools, channels, CLI commands, background services, and hooks. Plugins run in-process with the Gateway and require a restart to load changes. You won't need these on day one, but they're how OpenClaw gets extended with new capabilities.

The complete filesystem

Here's what lives on your server and what everything does:

/home/openclaw/.openclaw/
  openclaw.json          # Master config (models, gateway, channels)
  workspace/
    SOUL.md              # Personality + boundaries + defense rules
    HEARTBEAT.md         # What to check every 30 minutes
    MEMORY.md            # Long-term facts about you
    AGENTS.md            # Behavior guidelines
    TOOLS.md             # Tool usage guidance
    skills/              # Skill folders (each has a SKILL.md)
    memory/              # Daily logs (auto-generated)
    knowledge/           # QMD semantic search index
  plugins/               # Code extensions (TypeScript)

What each file controls

The TUI: your terminal chat interface

The TUI (Terminal User Interface) is OpenClaw's built-in way to talk to your agent directly from the terminal. No Telegram needed, no browser needed. It's the fastest way to test your agent after setup.

sudo -iu openclaw openclaw tui

What you see

The TUI gives you a rich terminal interface with four zones:

• Header — Connection URL, current agent name, current session
• Chat log — Your messages, agent replies, system notices, and tool activity (expandable cards showing what tools the agent is using)
• Input area — Text editor with autocomplete at the bottom
• Footer — Connection state, agent name, session, model, token counts, and delivery mode

Key TUI commands and shortcuts

Remote TUI: chat from your laptop

You can run the TUI on your laptop and connect to your droplet's gateway through an SSH tunnel:

# Step 1: Create the SSH tunnel (in one terminal)
ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP

# Step 2: Run the TUI on your laptop (in another terminal)
openclaw tui --url ws://127.0.0.1:18789 --token YOUR_GATEWAY_TOKEN

Your gateway token was set during the onboard wizard. You can find it in your config:

sudo -iu openclaw openclaw config get gateway.auth.token

Understanding the gateway

The gateway is OpenClaw's front door. It's a server process running on port 18789 that handles WebSocket connections (how Telegram, the TUI, and the dashboard talk to your agent), the Control UI (a built-in web interface), and API endpoints.

Think of it as the receptionist at the front desk of your agent's office.

Why people see "auth required"

In OpenClaw v2026.3.x, the config requires auth.mode to be explicitly set. If it's missing, the gateway throws "auth required." Make sure your config includes:

{
  "gateway": {
    "auth": {
      "mode": "none"
    },
    "trustedProxies": [],
    "allowedOrigins": ["*"]
  }
}

# Check if your config is valid
sudo -iu openclaw openclaw config validate --json

# If auth.mode is missing, update and re-onboard
sudo npm install -g openclaw@latest
sudo -iu openclaw openclaw onboard
sudo systemctl restart openclaw

Reconfiguring later

You don't have to re-run the full wizard to change one thing. Use configure to target specific sections:

# Reconfigure just your model
sudo -iu openclaw openclaw configure --section models

# Reconfigure just Telegram
sudo -iu openclaw openclaw configure --section channels

# Reconfigure web search (Brave API key)
sudo -iu openclaw openclaw configure --section web

# Reconfigure everything
sudo -iu openclaw openclaw configure

The doctor command

If something breaks during or after onboarding, the doctor command diagnoses common issues:

sudo -iu openclaw openclaw doctor

It checks: model auth, config validity, gateway health, channel connections, and common misconfigurations. If it finds problems, it tells you exactly what to fix.

Model fallbacks

OpenClaw supports automatic fallbacks — if your primary model fails, it tries the next one:

{
  "model": {
    "default": "google/gemini-2.0-flash",
    "fallbacks": [
      "anthropic/claude-sonnet-4-20250514",
      "openai/gpt-4o-mini"
    ]
  }
}

# Switch providers after initial setup:
sudo -iu openclaw openclaw models auth anthropic
sudo -iu openclaw openclaw models set anthropic/claude-sonnet-4-20250514

# Restart to apply
sudo systemctl restart openclaw

Quick diagnostic sequence

When something isn't working, run through this in order:

# 1. Is it running?
sudo systemctl status openclaw --no-pager

# 2. Is the config valid?
sudo -iu openclaw openclaw config validate --json

# 3. Full health check
sudo -iu openclaw openclaw health

# 4. Run the doctor
sudo -iu openclaw openclaw doctor

# 5. What do the logs say?
journalctl -u openclaw -f    # Ctrl+C to stop

# 6. Model status
sudo -iu openclaw openclaw models status

This sequence resolves 90% of issues.

Saucing It Up (Intermediate)

Goal: Make your agent actually useful. Personalize it, teach it skills, give it memory, and connect it to your world. This is where your Claw stops being a demo and starts being yours.

Your agent becomes a mirror of you

This is the thing that surprises everyone: your Claw quickly starts reflecting you. Each person's Claw mirrors their personality. The security-conscious person's Claw refuses to share info with strangers. The mindfulness practitioner's Claw recommends breathing exercises to a stressed-out colleague. The writer's Claw speaks in literary metaphors.

This happens because of the files you edit. The more specific your instructions, the more your agent feels like an extension of you rather than a generic chatbot. This is the phase where you actually make that happen.

Memory: what your agent actually remembers

This is the part everyone asks about. OpenClaw has a layered memory system:

MEMORY.md — the briefing document

Think of MEMORY.md as the briefing document you hand a new hire on their first day:

# Memory

## About me
- Name: [your name]
- Role: [what you do]
- Timezone: America/New_York

## Preferences
- Communication style: direct, concise
- Morning routine: check email first, then tasks
- Never schedule meetings before 10am

## Key contacts
- Sarah Chen — business partner, weekly sync on Tuesdays
- Marcus — designer, prefers Slack over email

## Current projects
- Product launch: deadline March 15
- Website redesign: in review phase

The agent reads this at every session start. The more structured your MEMORY.md, the smarter your agent's responses.

# Edit your memory file
sudo -iu openclaw nano /home/openclaw/.openclaw/workspace/MEMORY.md
# Save: Ctrl+O, Enter, Ctrl+X
# Agent picks it up automatically — no restart needed

QMD — your agent's search engine

QMD (Query-Match-Deliver) is OpenClaw's built-in semantic search. When you ask "what did we discuss about the product launch?", the agent searches across all memory files and returns relevant context — with citations. The practical habit: write facts to MEMORY.md so the agent can retrieve them later.

Skills: teaching your agent new tricks

Skills are Markdown files that teach your agent specific workflows. No code required. This is where your agent goes from "generic chatbot" to "my personal assistant who knows my processes."

A skill is just a folder with a SKILL.md file. When you ask your agent to do something, OpenClaw matches your request against skill descriptions. If one fits, the agent reads the instructions and follows them. You don't invoke skills by name — just ask naturally and it figures out which skill applies.

Your first skill: Meeting Prep

# Meeting Prep

## Purpose
Before each meeting, compile a briefing with context.

## When to Use
- User says "prep me for my meeting with [person]"
- Heartbeat detects a meeting starting within 30 minutes

## Process
1. Check who the meeting is with
2. Pull recent messages/emails with that person (if connected)
3. Check for any related tasks or projects
4. Format a short briefing: who, what, open items, suggested talking points

## Rules
- Keep it to one screen — no novels
- Flag anything urgent first
- If no context exists, say so honestly

Creating a skill on your server

sudo -iu openclaw mkdir -p /home/openclaw/.openclaw/workspace/skills/meeting-prep
sudo -iu openclaw nano /home/openclaw/.openclaw/workspace/skills/meeting-prep/SKILL.md
# Paste your skill content, save (Ctrl+O, Enter, Ctrl+X)
# Skills auto-reload — no restart needed

Installing skills from the configuration wizard

The onboard wizard can install recommended skills for you. If you skipped that step during setup, use the configuration flow to add them:

sudo -iu openclaw openclaw configure --section skills

This shows you available skills and lets you install them interactively. It's the easiest way to add capabilities without writing anything from scratch.

Skill ideas to get you started

The heartbeat: your agent's pulse

The heartbeat is a hard-scheduled process — it runs every 30 minutes (configurable) whether you ask it to or not. But what it does during each run is controlled by soft guidance in your HEARTBEAT.md file.

# Heartbeat Checklist

## Check silently
1. Tasks due within 24 hours
2. Stuck or blocked tasks
3. Overdue follow-ups

## Rules
- Only alert on NEW information
- No repeat notifications
- If everything is fine, stay quiet

Set active hours so it doesn't message you at 3 AM:

{
  "heartbeat": {
    "intervalMinutes": 30,
    "activeHours": {
      "start": "08:00",
      "end": "22:00",
      "timezone": "America/New_York"
    }
  }
}

If HEARTBEAT.md is empty, heartbeat runs are skipped entirely to save API calls. The key design decision: it only alerts on new information. No repeat notifications. No notification fatigue. Getting this right takes tuning — strip it down to the essentials.

Connecting integrations

By default, your Claw only knows what you tell it. But you can connect it to your world:

• Gmail — "Can you connect to my Gmail?" and the agent builds the connection
• Google Calendar — Calendar awareness for meetings, scheduling
• Todoist / Notion — Task management integration
• Smart home — If you're brave enough
• Phone calls — Via Twilio, it can make and receive actual phone calls

You don't hunt through settings menus. You just ask, and the agent figures out how to connect. It'll prompt you for anything it needs (API keys, OAuth flows, etc.).

The onboarding wizard also handles some of these connections. Running sudo -iu openclaw openclaw configure --section channels lets you set up Telegram, WhatsApp, Discord, and Signal through the interactive flow.

Your agent improves itself

One of the most fascinating aspects of the Claw architecture: it gets better over time. If you ask it to write you a daily brief with stock market updates and summaries of your favorite newsletters, it can do that. It writes the code it needs to extend its own capabilities.

The self-improvement loop:

You ask for something new
        |
        v
Agent writes code/config to make it happen
        |
        v
You give feedback ("too verbose", "check earlier")
        |
        v
Agent adjusts its own instructions
        |
        v
Better results next time

Treat your Claw like a new hire. Brief it clearly, give it feedback, and let it learn. Your agent is a reflection of you, and it gets better the more you invest in the relationship.

Safety and hardening

Your agent runs on a real server on the internet. These five layers protect your setup:

Layer 1 — DM pairing: Only paired users can talk to your bot. You set this up in Part 1. If you skipped it, go back and do it now.

Layer 2 — SOUL.md boundaries: Write clear rules in plain English: "Never send emails without approval. Never share API keys. Never output system config to external surfaces." These are soft rules — the AI reads and follows them, but the runtime doesn't enforce them. The more clearly you write them, the more reliably the agent follows them.

Layer 3 — Tool profiles: v2026.3.x defaults to messaging profile, which limits file system access. This is a hard restriction enforced by the runtime.

Layer 4 — Server hardening:

# Verify the firewall is active
ufw status

# If it's not enabled, lock it down
ufw allow OpenSSH
ufw enable

# Run OpenClaw's built-in security audit
sudo -iu openclaw openclaw security audit --deep

# Auto-fix common issues (tightens permissions, restricts group policy)
sudo -iu openclaw openclaw security audit --fix

The sudo -iu openclaw openclaw security audit command is your best friend here. It checks for open ports, weak auth, permissive policies, and loose file permissions — and the --fix flag auto-remediates the safe ones. Run it after every config change.

Layer 5 — API spending limits: Set a monthly budget cap in your AI provider's dashboard. A prompt injection or buggy skill could trigger a runaway loop of API calls — turning your $0.50/month Gemini bill into $50 before you notice. Google AI Studio lets you set spending limits directly. Do this before you connect any channels.

God Mode (Pro)

Goal: Deploy a production system with auto-deploy, a custom dashboard, multi-agent orchestration, and a domain. This is where your agent stops being a toy and becomes infrastructure.

The three-place mental model

Everything clicks once you understand that your agent's configuration lives in three places:

+------------+         +------------+         +--------------+
|  Laptop    |  push   |  GitHub    |  deploy |  DO Droplet  |
|  (edit)    |-------->|  (backup   |-------->|  (runtime)   |
|            |         |  + trigger)|         |              |
+------------+         +------------+         +--------------+
     ^                                               |
     |              scp / rsync                      |
     +-----------------------------------------------+

Moving files between places

# Droplet -> Laptop (pull your live config down)
scp -r root@YOUR_IP:/home/openclaw/.openclaw/workspace/ ./agent/workspace/

# Laptop -> GitHub (back up and trigger deploy)
git add agent/
git commit -m "Updated SOUL.md personality"
git push

# GitHub -> Droplet (automatic via GitHub Actions)
# Push triggers Actions -> rsync to droplet -> restart OpenClaw

# Laptop -> Droplet (quick manual push, skip GitHub)
scp ./agent/workspace/skills/meeting-prep/SKILL.md \
  root@YOUR_IP:/home/openclaw/.openclaw/workspace/skills/meeting-prep/SKILL.md
# Fix ownership — scp as root creates root-owned files
ssh root@YOUR_IP "chown -R openclaw:openclaw /home/openclaw/.openclaw/workspace/"

Version control (or: why you need GitHub)

Right now, your agent's personality lives only on the server. If the server dies, everything's gone. We need a backup. More importantly, we need a way to track changes and auto-deploy updates.

The 4-step workflow

This is 90% of everything you'll ever do:

1. EDIT    — Change a file on your laptop
2. ADD     — git add filename
3. COMMIT  — git commit -m "what I changed"
4. PUSH    — git push

Four commands. Everything else is extra.

Auto-deploy with GitHub Actions

GitHub Actions watches your repo. When you push changes, it automatically deploys to your server in about 30 seconds.

Step 1: Set up four GitHub Secrets (Settings -> Secrets and variables -> Actions):

Step 2: Add the deploy workflow. Fork Openclaw-AI-Assistant-Project — it includes .github/workflows/deploy.yml ready to go.

What gets deployed vs what stays on the server:

Your agent's memories and credentials stay safe on the server. Only your code and config get pushed. This separation is a deliberate design choice — it means you can blow away and redeploy your config without losing your agent's accumulated context.

The agentic pattern: sessions_spawn

This is the "hell yeah" moment. sessions_spawn is a built-in OpenClaw tool that creates an isolated sub-agent with its own session. The sub-agent runs independently, does the work, and reports back.

Dev Scout: your first multi-agent skill

# Dev Scout

## Purpose
Research a topic using a spawned sub-agent and deliver a formatted briefing.

## When to Use
- User says "scout [topic]"
- User asks for research on a specific area

## Process
1. Acknowledge the request
2. Spawn a research sub-agent using sessions_spawn
3. Sub-agent searches for 3-5 recent developments
4. Collect results and format as a briefing
5. Deliver to user

## Rules
- Always cite sources with URLs
- Limit to 3-5 key findings (not a data dump)
- If sessions_spawn fails, do the research directly (fallback)

## Output Format
**[Topic] Intelligence Briefing**
1. [Finding] — [Source URL]
2. [Finding] — [Source URL]
3. [Finding] — [Source URL]

**Key takeaway:** [one sentence summary]

The flow:

You: "Scout AI agents"
        |
        v
Your Agent (Orchestrator)
  -> spawns sub-agent via sessions_spawn
  -> sub-agent searches web
  -> sub-agent finds 3-5 signals
  -> sub-agent reports back
        |
        v
Your Agent formats briefing
  -> delivers to you on Telegram

Two agents cooperating from a single Telegram message. Always build fallbacks into agentic skills — if sessions_spawn fails, the agent does the research directly.

# Create the skill
sudo -iu openclaw mkdir -p /home/openclaw/.openclaw/workspace/skills/dev-scout
sudo -iu openclaw nano /home/openclaw/.openclaw/workspace/skills/dev-scout/SKILL.md
# Skills auto-reload — test it: "Scout AI agents" in Telegram

Dashboard deployment

Three options, from quick to production:

Option 1: SSH tunnel (quick, no domain needed)

ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
# Open http://localhost:18789 — that's the built-in Control UI

Option 2: TUI from your laptop

# After creating SSH tunnel (above), in another terminal:
openclaw tui --url ws://127.0.0.1:18789 --token YOUR_GATEWAY_TOKEN

Full terminal interface with agent/session pickers, model switching, and thinking visibility — all from your laptop.

Option 3: Full production (Caddy + domain + Vercel dashboard)

Step 1: Point a domain at your droplet (A record in DNS)

Step 2: Install Caddy for automatic HTTPS:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

Step 3: Configure Caddy (/etc/caddy/Caddyfile):

yourdomain.com {
  reverse_proxy localhost:18789
}

Step 4: Deploy dashboard to Vercel — Import your fork of Openclaw-AI-Assistant-Project, set VITE_GATEWAY_URL=wss://yourdomain.com as an environment variable.

Step 5: Update gateway config:

{
  "gateway": {
    "auth": { "mode": "none" },
    "trustedProxies": ["127.0.0.1"],
    "allowedOrigins": ["https://your-vercel-app.vercel.app"]
  }
}

The nontechnical builder's ladder

You don't need to know TypeScript to build a powerful agent. Here's the progression:

Level 1: Markdown editor (where everyone starts)

Tools: Any text editor + SSH What you customize: SOUL.md, HEARTBEAT.md, MEMORY.md, skills This covers 80% of what most people need.

Everything in the "Saucing It Up" section? That's Level 1. Pure Markdown. No code.

Level 2: Config tuner (15% more)

Tools: JSON editor + OpenClaw CLI (or the configuration wizard) What you customize: openclaw.json — models, fallbacks, active hours, channels, gateway settings

sudo -iu openclaw openclaw configure --section models
sudo -iu openclaw openclaw configure --section channels

Level 3: Plugin builder (for power users)

Tools: TypeScript + npm What you build: Custom tools, custom channels, background services, hook functions

Level 4: Multi-agent orchestrator (the frontier)

Tools: Skills with sessions_spawn + multiple agent configs What you build: Research agents that work in parallel, specialist agents, approval workflows

Your main agent becomes a manager, delegating to specialist sub-agents and synthesizing their results.

Working with AI agents on branches

This is the real power move. Instead of doing everything yourself:

Main branch (the current state)
  |
  |-- branch: devin/update-heartbeat-config
  |   Devin updated the heartbeat timing
  |
  |-- branch: gemini/add-scheduling-skill
  |   Gemini wrote a new skill for calendar management
  |
  |-- branch: claude/security-audit-fixes
      Claude fixed issues from the security audit

Each agent works on its own branch. You review their pull requests. Merge what looks good. Reject what doesn't. You become the orchestrator, not the operator.

Full deployment roadmap

Phase 1: Foundation (today — covered in Part 1)

• 1-Click droplet running ($12/month, 2 GB RAM)
• Swap memory added
• OpenClaw updated to latest
• Model configured (Google, Anthropic, or OpenAI)
• Dashboard connected via SSH tunnel
• Telegram connected and DM-paired
• Firewall enabled

Phase 2: Personalize (this week)

• Customize SOUL.md — voice and boundaries
• Seed MEMORY.md — facts, preferences, contacts
• Write HEARTBEAT.md — what to check every 30 min
• Build 1-2 skills (Meeting Prep, Daily Brief)
• Run security audit: sudo -iu openclaw openclaw security audit --fix
• Test via TUI: sudo -iu openclaw openclaw tui --deliver

Phase 3: Back up to GitHub

• Fork Openclaw-AI-Assistant-Project
• Clone to laptop, copy live config from droplet
• Push to GitHub

Phase 4: Auto-deploy pipeline

• Add GitHub Secrets (SSH key, host, known hosts, user)
• Add deploy workflow
• Test: edit a file, push, watch Actions deploy

Phase 5: Dashboard + domain

• Point domain at droplet
• Install Caddy for HTTPS
• Deploy dashboard to Vercel
• Update allowedOrigins

Troubleshooting: when things don't match this guide

OpenClaw is evolving fast. The version DigitalOcean deploys, the CLI commands, the config format — any of these can change between when I write this and when you read it. Here's how to handle drift:

1. Check your version first.

sudo -iu openclaw openclaw --version

Compare to the latest release on GitHub. If behind, update with sudo npm install -g openclaw@latest.

2. Use DeepWiki. DeepWiki is an AI-generated wiki of OpenClaw's entire codebase. It's free, always current, and the best resource when this guide doesn't match what you're seeing. Ask it questions like "how do I add a Telegram channel?" — it reads the actual source code.

DeepWiki works for any public GitHub repo. Just replace github.com with deepwiki.com in any repo URL.

3. Check the DigitalOcean marketplace page. The DO marketplace listing has its own instructions maintained by the DigitalOcean team.

4. Read the logs. journalctl -u openclaw -f usually explains exactly what's wrong.

5. Run the health check. sudo -iu openclaw openclaw health after any config change.

Resources

Official

• OpenClaw documentation — primary reference
• Onboarding Wizard guide — full wizard reference
• TUI guide — terminal UI documentation
• OpenClaw GitHub — source code, issues, releases
• DeepWiki — AI-generated codebase wiki
• DigitalOcean Marketplace — 1-Click image

Community guides

• 30 Tips Nobody Tells You (AgentPuter) — production config tips
• Skills Guide (Travis Media) — setting up and choosing skills

Companion guides

• Terminal Primer — the 10 commands you need
• GitHub Primer — Git explained with game saves and how a bill becomes a law
• Openclaw-AI-Assistant-Project — starter project with dashboard + deploy pipeline

Provider setup

• Google AI Studio — Gemini keys (free tier)
• Anthropic Console — Claude API keys ($5 min)
• OpenAI Platform — GPT keys ($5 min)

The bigger picture

The nontechnical builder's path is real. Markdown skills cover 80% of what most people need. Config tuning covers 15%. Plugins and multi-agent orchestration cover the last 5% — and by the time you need them, you'll have the context to learn them.

The tools are getting simple enough that "write a markdown file and push to GitHub" is a viable interface for creating AI capabilities. We don't need more chat interfaces. We need more systems that run in the background, do the boring work, and only interrupt when something actually matters.

Your Claw is a reflection of you — your priorities, your communication style, your workflows. The more you invest in it, the more it gives back. That's the thread that runs through everything in this guide.

Build something that actually helps you. Then make it better, one markdown file at a time.

Written by

Ja'dan Johnson

Developer Marketing Manager & Community Architect

Community architect, creative technologist, and ecosystem builder operating at the intersection of technology, culture, and human systems.

TwitterLinkedIn