OpenClaw Starter Kit Reference

This document describes the OpenClaw Starter Kit, a workspace template for OpenClaw that gives an AI agent persistent memory, personality, autonomy, and a multi-agent squad. The kit maintains a clean separation between user-customized files and infrastructure files that can be updated without overwriting user data.

Purpose and When to Use

The starter kit is designed for setting up a personal AI assistant with long-term memory and personality. Use it when creating a multi-agent squad (content, dev, research) that coordinates autonomously, establishing safety policies with auto-approve rules and hard stops for dangerous actions, or implementing browser-driven smoke tests for web apps before merge. It also supports routing Anthropic model calls through Claude Code CLI to use a Max/Pro subscription, stretching a $200/month Claude Max subscription 3-5x via token optimization, delegating heavy compute to a second machine (e.g., Mac Mini forge), and creating per-repo AI playbooks that give agents ground truth about repo shape, risk areas, and verification steps.

Prerequisites

Before using the starter kit, ensure you have:

• Node.js and npm installed
• OpenClaw installed globally: npm i -g openclaw
• For web-verify: npm install in managed/tools/web-verify (installs Playwright + Chromium)
• For Claude Code CLI auth: Claude Code CLI installed and configured with a Max/Pro subscription
• For OpenAI Codex auth: ChatGPT Plus/Pro subscription
• For Anthropic API key auth: An Anthropic API key
• A workspace directory (default: ~/clawd/)

The kit is compatible with OpenClaw 2026.4.18+ and supports Claude Opus 4.7.

Quick Start Installation

Follow these steps to set up a new workspace:

1. Install OpenClaw: npm i -g openclaw (or see docs)
2. Copy the starter kit files into your OpenClaw workspace (default: ~/clawd/): cp -r openclaw-starter-kit/* ~/clawd/
3. Create memory directory: mkdir -p ~/clawd/memory
4. Fill in user/USER.md with your info
5. Fill in user/IDENTITY.md to name your AI
6. Start OpenClaw: openclaw gateway start
7. Start chatting — your AI will evolve from there

Authentication Setup

The starter kit supports multiple authentication paths. The recommended method uses your Claude subscription via the Claude Code CLI.

Recommended: Claude Subscription via Claude Code CLI

Run the following command:

openclaw onboard --auth-choice anthropic-cli

OpenClaw routes Anthropic model calls through the Claude Code CLI, keeping your subscription-included usage intact. This supports Claude Opus 4.7 and the rest of the Claude 4 family. Note that the direct Claude Max/Pro path into OpenClaw broke earlier; on the current release it works again when routed through Claude Code CLI.

Alternative: OpenAI Codex OAuth

Run the following command:

openclaw onboard --auth-choice openai-codex

This uses your ChatGPT Plus/Pro subscription.

Alternative: Anthropic API Key

Export your API key and run onboard:

export ANTHROPIC_API_KEY="sk-ant-..."
openclaw onboard

This uses direct API billing (pay-as-you-go).

Other Authentication Paths

The --auth-choice parameter also supports OpenRouter, local LM Studio/Ollama, DeepSeek, Kimi, and Gemini paths.

Upgrade Procedures

Upgrade from v2.3 to v2.4

1. rsync or copy the latest managed/ into your workspace — safe, no user/ file is touched
2. cd managed/tools/web-verify && npm install (installs Playwright + Chromium)
3. Copy flows/example-home.json to a real flow for each app, set baseUrl plus a couple of expectText assertions
4. Wire it into your ship-loop's smoke step

Upgrade from v2.2 to v2.3

1. rsync or copy the latest managed/ into your workspace — safe, no user/ file is touched
2. Existing user/MEMORY.md stays as-is. If you want the slim index, diff against this repo's user/MEMORY.md and trim manually
3. In each of your product repos, copy managed/templates/AI_PLAYBOOK-template.md to AI_PLAYBOOK.md and managed/templates/smoke-web.sh.template to scripts/smoke-web.sh, then fill them in
4. Re-run onboard if your auth currently points at openai-codex or apiKey and you would prefer subscription routing: openclaw onboard --auth-choice anthropic-cli

Capabilities

Persistent Memory

The kit provides persistent typed file-based memory across sessions with a lean index loaded every conversation. Fresh installs get a lean 20-line MEMORY.md index; existing installs are untouched during upgrades. Memory docs were pulled out of hot context in v2.3 — managed/guides/MEMORY.md now contains the approximately 55 lines of how-it-works prose. The memory system shape includes types, what not to store, and consolidation guidance.

Personality

Real personality is defined in user files (tone, opinions, boundaries). Fill in user/USER.md and user/IDENTITY.md to customize your AI's identity.

Multi-Agent Squad

The kit supports a multi-agent squad: content-agent, dev-agent, and research-agent that trigger each other autonomously. Agent reactions allow agents to trigger each other (e.g., tweet posted triggers analyze engagement which triggers draft followup). The reaction triggers are defined in managed/ops/reaction-matrix.json. Note that the content-agent never posts without approval.

Safety Policies

Safety policies include auto-approve rules, daily caps, and hard stops for dangerous actions. These are configured in managed/ops/policies.json.

Proactive Behavior

The AI checks email, calendar, and mentions without being asked.

Browser-Driven Smoke Tests

The managed/tools/web-verify tool drives real Chromium through a JSON flow spec against a live or preview URL. It captures screenshots plus console, page, and network errors, then returns deterministic pass/fail (exit 0/1). It catches render failures, broken auth redirects, dead buttons, and client-side JS exceptions that a 200 status hides. The tool supports public and authed example flows, secret-safe credential refs, and a --base flag to smoke-test preview deploys before merge.

Per-Repo AI Playbooks

Each repo can have an AI_PLAYBOOK.md file with ground truth about the repo's shape, risk areas, gotchas, and verification steps. This mitigates the risk of an agent touching the wrong thing in a repo.

Public Smoke Script Template

The managed/templates/smoke-web.sh.template is parameterized with BASE_URL and PAGES. It fails loud on non-200s or runtime-error bodies, and optionally verifies the Vercel production alias.

Mistake Tracking

Track mistakes via user/MISTAKES.md: log what happened, why, what you fixed, and a rule to prevent it.

Token Optimization

The kit includes a token optimization guide to stretch a $200/month Claude Max subscription 3-5x.

Multi-Machine Setup

A multi-machine setup guide is included for delegating compute across machines (e.g., a Mac Mini forge for heavy compute).

Health Checks, Backups, Utilities

These are located in managed/scripts/.

Parameters

--auth-choice

Specifies the authentication path for OpenClaw. Options include anthropic-cli (recommended), openai-codex, or others (OpenRouter, local LM Studio/Ollama, DeepSeek, Kimi, Gemini). Required for the onboard command.

ANTHROPIC_API_KEY

Environment variable for direct Anthropic API billing (pay-as-you-go). Required only if using the Anthropic API key auth path.

--base

Flag for web-verify smoke test to target a preview deploy URL before merge. Optional.

BASE_URL

Parameter for smoke-web.sh.template: the base URL of the app to smoke-test. Required for smoke-web.sh.

PAGES

Parameter for smoke-web.sh.template: list of top pages to check. Required for smoke-web.sh.

baseUrl

Property in a web-verify flow JSON spec: the base URL of the app to test. Required for web-verify flows.

expectText

Property in a web-verify flow JSON spec: text assertions to verify on pages. Optional but recommended.

Constraints and Caveats

• Starter kit updates only ever touch managed/ — user/ files are sacred and never overwritten
• Fresh installs get a lean 20-line MEMORY.md index; existing installs are untouched
• The direct Claude Max/Pro path into OpenClaw broke earlier; on the current release it works again when routed through Claude Code CLI
• Content-agent never posts without approval
• Background work spawned from a turn may get reaped (documented in GOTCHAS.md)
• Remote/long builds may die mid-run (documented in GOTCHAS.md)
• "It returned 200" does not mean "it works" — browser smoke tests catch what curl misses
• Heartbeat spam is a known failure mode (documented in GOTCHAS.md)
• Memory docs were pulled out of hot context in v2.3 — managed/guides/MEMORY.md now contains the approximately 55 lines of how-it-works prose
• Existing user/MEMORY.md stays as-is during upgrades; manual diff/trim required if you want the slim index

Failure Modes

• Background work spawned from a turn gets reaped
• Remote/long builds dying mid-run
• "It returned 200" but the page has render failures, broken auth redirects, dead buttons, or client-side JS exceptions
• Agent touches the wrong thing in a repo (mitigated by per-repo AI playbooks)
• Heartbeat spam

Examples

Quick Start

Copy starter kit to ~/clawd/, create memory dir, fill in user files, start gateway.

Authentication via Claude Code CLI

openclaw onboard --auth-choice anthropic-cli

Authentication via OpenAI Codex

openclaw onboard --auth-choice openai-codex

Authentication via Anthropic API Key

export ANTHROPIC_API_KEY="sk-ant-..."
openclaw onboard

Upgrade from v2.3

rsync managed/, npm install in web-verify, copy example flow, wire into smoke step.

Upgrade from v2.2

rsync managed/, optionally trim MEMORY.md, copy playbook and smoke script templates, re-run onboard if needed.

Browser Smoke Test

Uses a JSON flow spec with baseUrl and expectText assertions, drives Chromium, captures screenshots and errors, returns pass/fail.

Public Smoke Script

Parameterized with BASE_URL and PAGES, checks top pages, fails on non-200s or runtime errors, optionally verifies Vercel production alias.

Cost Considerations

The token optimization guide helps stretch a $200/month Claude Max subscription 3-5x. A $2k annual budget would cover approximately 10 months of such a subscription at full price, though optimization can extend this significantly. The 2026 version of OpenClaw supports Claude Opus 4.7 and the rest of the Claude 4 family.