Quick Start

Ubuntu VPS (Fresh Install)

SSH into your server and run:

# 1. Clone Clawdboss
apt-get update && apt-get install -y git
git clone https://github.com/NanoFlow-io/clawdboss.git
cd clawdboss

# 2. Run the setup wizard (auto-installs Node.js 22, Python, build tools, OpenClaw)
./setup.sh

That's it. The wizard auto-installs all dependencies (Node.js 22, Python, git, build-essential, OpenClaw) and walks you through everything else.

What You'll Need Ready

• An LLM provider — one of:
  • GitHub Copilot subscription (cheapest — uses copilot-api proxy)
  • OpenAI API key (sk-...)
  • Anthropic API key (sk-ant-...)
• A Discord bot token — create one here (if using Discord interface)
• A Telegram bot token — create one via @BotFather (if using Telegram interface)
• Optional: Brave Search API key, ElevenLabs API key, OpenAI key for image gen/whisper

The setup wizard will:

1. Ask about you — name, role, what you do, how you want to use your agent
2. Ask about your agent — name, personality, mission, domain expertise
3. Prompt for your API keys and Discord/Telegram credentials
4. Create your .env file (gitignored, never committed)
5. Generate openclaw.json with ${VAR} references to your .env
6. Create agent workspaces with security rules + WAL Protocol pre-baked
7. Offer optional tools: Graphthulhu, ApiTap, Scrapling, GitHub, Playwright, OCTAVE, Humanizer, Self-Improving Agent, Find Skills, Marketing Skills, Healthcheck, Clawmetry, ClawSec
8. Run OpenClaw's built-in skills wizard (Whisper, Nano Banana Pro, mcporter, TTS, email, etc.)
9. Start the gateway

Your agent starts its first session knowing who you are, what you do, and what personality it should have — zero manual config file editing needed.

Configuration Tiers

| Tier | Agents | Best For | |------|--------|----------| | Solo | Main only | Personal assistant, simple setups | | Team | Main + 1-2 specialists | Small business, multiple workflows | | Full Squad | Main + Comms + Research + Security | Full operations center |

File Structure

clawdboss/
├── README.md
├── setup.sh                    # Interactive setup wizard
├── .env.example                # Template showing required variables
├── .gitignore                  # Protects secrets
├── templates/
│   ├── openclaw.template.json  # Config with ${VAR} placeholders
│   ├── workspace/              # Main agent workspace files
│   │   ├── AGENTS.md           # Operating rules + WAL Protocol + security
│   │   ├── SOUL.md
│   │   ├── USER.md
│   │   ├── TOOLS.md
│   │   ├── IDENTITY.md
│   │   └── HEARTBEAT.md
│   └── agents/                 # Specialist agent templates
│       ├── comms/
│       ├── research/
│       └── security/
└── docs/
    ├── security.md             # Security architecture + WAL Protocol overview
    ├── customization.md        # How to customize your setup
    ├── recommended-tools.md    # Vetted ecosystem tools (Clawmetry, ClawSec)
    └── octave.md               # OCTAVE protocol guide

Interface Options

During setup, choose your preferred interface:

| Option | Best For | |--------|----------| | Discord | Power users who live in Discord. Channel-per-agent, reactions, threads. | | Telegram | Mobile-first. DM your bot or use group topics for multi-agent routing. | | ClawSuite Console | Visual dashboard with chat, file browser, terminal, cost analytics. Great for non-technical users. | | Any combination | Mix and match — Discord + Telegram, Discord + Console, all three, etc. |

ClawSuite Console is an open-source web dashboard — see ClawSuite on GitHub (MIT license).

Context Persistence (WAL Protocol + 3-Layer Memory)

Clawdboss agents don't lose your corrections and decisions when context resets:

• 3-Layer Memory — L1 (Brain, loaded every turn) → L2 (Memory, searched semantically) → L3 (Reference, opened on demand)
• L1 File Budget — 500-1,000 tokens per workspace file to prevent agents from skimming
• SESSION-STATE.md — Agent writes important details here BEFORE responding (Write-Ahead Log)
• Working Buffer — At ~60% context, every exchange is logged to survive compaction
• Compaction Recovery — Agent reads buffer + state files after context loss, never asks "what were we doing?"
• Breadcrumbs — Topic-organized files in memory/ that point to deep reference docs
• Trim — Weekly maintenance to keep L1 files lean, move excess to L2/L3
• Recalibrate — Drift correction, forces re-read of all files and behavior comparison

See docs/security.md for the full architecture.

Security

All API keys are stored in ~/.openclaw/.env and referenced via ${VAR_NAME} syntax in the config. Keys never appear in JSON config files.

All agents come with:

• Prompt injection defense (content isolation, pattern detection)
• Anti-loop rules (prevent token-burning attacks)
• External content security (emails, web pages treated as data-only)
• Relentless resourcefulness + VBR (Verify Before Reporting)

See docs/security.md for the full security architecture.

Recommended Ecosystem Tools

The setup wizard offers each of these individually. All are free and open-source:

| Tool | Purpose | Install Method | |------|---------|---------------| | Graphthulhu | Knowledge graph memory (entities, relationships, constraints) | Binary / cargo | | ApiTap | API discovery — intercepts web traffic, generates skill files | npm install -g @apitap/core | | Scrapling | Anti-bot web scraping with adaptive selectors | pip install scrapling | | Playwright MCP | Full browser automation (navigate, click, fill, screenshot) | clawhub install | | GitHub | Issues, PRs, CI/CD via gh CLI | clawhub install + gh CLI | | OCTAVE | 3-20x token compression for multi-agent handoffs | pip install octave-mcp | | Clawmetry | Real-time observability dashboard (costs, sessions, flow) | pip install clawmetry | | ClawSec | File integrity, advisory feed, malicious skill detection | Git clone | | Humanizer | Detect and remove AI writing patterns (24 patterns, 500+ terms) | clawhub install | | Self-Improving Agent | Capture errors, corrections, and lessons for continuous learning | clawhub install | | Find Skills | Discover and install new skills on-the-fly from ClawHub | clawhub install | | Marketing Skills | 15+ marketing reference skills (copywriting, CRO, SEO, email, ads) | clawhub install | | Healthcheck | Host security audits: firewall, SSH, updates, exposure | Built-in | | fail2ban | Brute-force protection — auto-bans malicious IPs | apt install fail2ban |

See docs/recommended-tools.md for detailed install guides.

After Install — Getting Your Agent Running

Once the wizard finishes, follow the next steps it shows:

1. Start the LLM Provider

GitHub Copilot (proxy):

# First run — shows a device auth URL + code. Open the URL, enter the code,
# authorize with a GitHub