TopDogLabs/OpenClaw-Setup
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9dc95e0f29
OpenClaw-Setup/openclaw-setup-max/docs/openclaw-setup-guide.md

22 KiB
Raw Blame History

OpenClaw Setup & Subagent Workflow Guide

Version: 1.0 (Generic)
Purpose: High-level architectural guide for replicating the OpenClaw setup with subagent workflow

⚠️ Note: This is a generic guide. Replace all [PLACEHOLDERS] with your actual values.

Table of Contents

  1. OpenClaw Setup
  2. Subagent Workflow Architecture
  3. Gantt Board Integration
  4. Tools & Skills System
  5. Memory & Documentation
  6. Project Structure & Conventions

1. OpenClaw Setup

Installation Requirements

Prerequisites:

  • macOS, Linux, or Windows with WSL
  • Node.js v20 or later
  • Package manager (Homebrew, apt, etc.)
  • Git
  • jq (brew install jq or equivalent)

OpenClaw Gateway: The OpenClaw system consists of:

  • OpenClaw.app - Main application (UI)
  • OpenClaw Gateway - Daemon service that handles agent sessions

Managing the Gateway:

# Check status
openclaw gateway status

# Start gateway
openclaw gateway start

# Stop gateway
openclaw gateway stop

# Restart gateway
openclaw gateway restart

Repo-specific in-place upgrade (existing install):

cd /Volumes/Data/openclaw-setups/openclaw-setup-max
bash ./scripts/update_openclaw.sh

This script stops gateway, upgrades OpenClaw, reapplies schedule/budget guardrails, and restarts gateway.

Directory Structure

Workspace Location:

~/.openclaw/workspace/
├── AGENTS.md                 # Boot sequence and core rules
├── SOUL.md                   # Identity and personality
├── USER.md                   # User context
├── TOOLS.md                  # Tools, credentials, workflows
├── BRAIN.md                  # Active projects and patterns
├── SESSION_STARTUP.md        # Session initialization
├── BOOTSTRAP.md              # First-run setup (delete after use)
├── memory/                   # Daily logs
│   └── YYYY-MM-DD.md         # Daily activity logs
├── agents/                   # Subagent definitions
│   ├── TEAM-REGISTRY.md      # Team configuration
│   ├── alice-researcher/     # Alice subagent
│   │   ├── SOUL.md
│   │   └── AGENTS.md
│   ├── bob-implementer/      # Bob subagent
│   │   ├── SOUL.md
│   │   └── AGENTS.md
│   └── charlie-tester/       # Charlie subagent
│       ├── SOUL.md
│       └── AGENTS.md
├── skills/                   # Skill definitions
└── docs/                     # Documentation

Project Directory:

~/Documents/Projects/OpenClaw/
├── Documents/                # Documentation files
├── Web/                      # Web projects (Next.js/React)
│   ├── gantt-board/
│   ├── blog-backup/
│   ├── mission-control/
│   └── heartbeat-monitor/
└── iOS/                      # iOS projects (Swift/Xcode)

Configuration Files

Core Files (in ~/.openclaw/workspace/):

File Purpose When to Update
AGENTS.md Boot sequence, write discipline, project rules Add new conventions
SOUL.md Identity, personality, boundaries Personality evolves
USER.md User context, preferences, goals User info changes
TOOLS.md Tools, APIs, credentials New tools added
BRAIN.md Active projects, patterns, gotchas Project status changes

Boot Sequence

Every session automatically reads files in this order:

  1. SESSION_STARTUP.md - What to read and in what order
  2. SOUL.md - Identity
  3. USER.md - User context
  4. TOOLS.md - Tools and workflows
  5. BRAIN.md - Active projects
  6. memory/YYYY-MM-DD.md - Recent context
  7. PROJECT_SETUP.md - Where to create projects (if exists)
  8. learnings/LEARNINGS.md - Rules from mistakes (if exists)

Environment Variables (Pattern)

Configure these in your environment or .env files:

# Supabase (for Gantt Board)
SUPABASE_URL=[YOUR_SUPABASE_URL]
SUPABASE_SERVICE_ROLE_KEY=[YOUR_SERVICE_ROLE_KEY]

# Tavily API (for web research)
TAVILY_API_KEY=[YOUR_TAVILY_API_KEY]

# Gitea (local Git server)
GITEA_URL=https://[your-gitea-host]:[port]
GITEA_USER=[your-username]
GITEA_PASSWORD=[your-password]

# Project-specific keys stored in project scripts/.env

2. Subagent Workflow Architecture

How Subagents Work

Spawning Subagents:

sessions_spawn({
  task: "Detailed task description",
  label: "Agent-Name",
  agentId: "main"
})

Managing Subagents:

# List all subagents
subagents list

# Kill a subagent
subagents kill <session-id>

# Send message to subagent
subagents steer <session-id> --message "Update"

The Alice → Bob → Charlie Workflow Pattern

Standard Flow (Complex Tasks):

Request → Alice (Research) → Bob (Implement) → Charlie (Test) → Done
          15 min             30 min             10 min

Quick Flow (Simple Tasks):

Request → Bob (Implement) → Charlie (Test) → Done
          20 min             10 min

Research-Only Flow:

Request → Alice (Research) → Report to User
          15 min

Team Members

Name Role Folder When to Use
Alice-Researcher Research & Analysis agents/alice-researcher/ Technology choice unclear, multiple approaches exist
Bob-Implementer Code Implementation agents/bob-implementer/ Requirements clear, ready to build
Charlie-Tester Testing & QA agents/charlie-tester/ Implementation done, need quality gate

Alice Spawn Command:

sessions_spawn({
  task: `Research: [question]

Context: [background]

Constraints: [budget/timeline/platform]

Read your SOUL.md at: ~/.openclaw/workspace/agents/alice-researcher/SOUL.md`,
  label: "Alice-Researcher",
  agentId: "main"
})

Bob Spawn Command:

sessions_spawn({
  task: `Implement: [feature]

Based on: [Alice's research / spec]

Requirements:
- [ ] Req 1
- [ ] Req 2

Tech stack: [iOS/Next.js/etc]

Read your SOUL.md at: ~/.openclaw/workspace/agents/bob-implementer/SOUL.md`,
  label: "Bob-Implementer",
  agentId: "main"
})

Charlie Spawn Command:

sessions_spawn({
  task: `Test: [feature]

Code to test: [files/code]

Requirements: [what it should do]

Focus areas: [tricky parts]

Read your SOUL.md at: ~/.openclaw/workspace/agents/charlie-tester/SOUL.md`,
  label: "Charlie-Tester",
  agentId: "main"
})

Task Lifecycle States

open/todo → in-progress → review → (user validates) → done
    ↓           ↑            ↑
  blocked     Charlie    Bob fixes
   issues     testing    issues

Statuses:

  • open - Newly created
  • todo - Ready to start
  • blocked - Blocked by dependencies
  • in-progress - Currently working
  • review - Ready for review
  • validate - Needs validation (Charlie's recommendation)
  • done - Completed

Rules:

  • Alice/Bob/Charlie CANNOT mark tasks as done
  • Only humans can mark tasks done
  • Charlie marks review if bugs found
  • Add progress comments at EACH step

Communication Patterns

Announcement Format:

  • Alice: "Alice-Researcher ✅ 5 options evaluated – Recommended: X – Ready for Bob"
  • Bob: "Bob-Implementer ✅ [feature] implemented – 3 files changed – Ready for Charlie"
  • Charlie: "Charlie-Tester ✅ 12 tests passed – 2 bugs found – Recommendation"

Comment Format (APPEND to existing):

{
  "id": "{timestamp}-{random}",
  "text": "[YYYY-MM-DD HH:MM] 🔄 In Progress\n\n**What was just done:**\n- Step completed\n\n**What is next:**\n- Next action\n\n**What is left to do:**\n- Remaining work",
  "replies": [],
  "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
  "commentAuthorId": "[AGENT_USER_ID]"
}

When to Use Subagents vs Main Session

Use Subagents When:

  • Task takes >5 minutes
  • Task has >3 steps
  • Parallel work possible
  • Research + implementation phases
  • Independent from main conversation

Use Main Session When:

  • Quick questions (<5 min)
  • Simple lookups
  • Status checks
  • Direct user conversation

3. Gantt Board Integration

Overview

The Gantt Board is the task management system for OpenClaw projects:

  • Stack: Next.js + Supabase + Vercel
  • Local Dev: http://localhost:3000
  • Live URL: Deployed to your hosting platform

CLI Scripts Location

~/.openclaw/workspace/scripts/
├── task.sh              # Task management
├── project.sh           # Project management
├── sprint.sh            # Sprint management
├── attach-file.sh       # File attachments
├── view-attachment.sh   # View attachments
└── README.md            # Full documentation

Task Management

Create Task:

# Minimal task
./task.sh create --title "Fix bug"

# Full task
./task.sh create \
  --title "Implement OAuth" \
  --description "Add OAuth2 login support" \
  --type task \
  --status todo \
  --priority high \
  --project "Gantt Board" \
  --sprint "current" \
  --assignee "[AGENT_NAME]" \
  --due-date "YYYY-MM-DD" \
  --tags "auth,security"

# From JSON file
./task.sh create --file task.json

List Tasks:

./task.sh list                          # All tasks
./task.sh list --status todo            # Filter by status
./task.sh list --priority high          # Filter by priority
./task.sh list --project "Gantt Board"  # Filter by project
./task.sh list --assignee "[AGENT]"     # Filter by assignee
./task.sh list --type bug               # Filter by type
./task.sh list --json                   # JSON output

Update Task:

# Update status
./task.sh update <task-id> --status in-progress

# Add comment
./task.sh update <task-id> --add-comment "Progress update"

# Update multiple fields
./task.sh update <task-id> \
  --status done \
  --priority low

Delete Task:

./task.sh delete <task-id>

Project Management

Create Project:

./project.sh create \
  --name "New Project" \
  --description "Project description" \
  --color "#3b82f6"

List Projects:

./project.sh list
./project.sh list --json

Update Project:

./project.sh update "Gantt Board" \
  --name "Updated Name" \
  --description "Updated description"

Sprint Management

Create Sprint:

./sprint.sh create \
  --name "Sprint 3" \
  --project "Gantt Board" \
  --goal "Complete API integration" \
  --start-date "YYYY-MM-DD" \
  --end-date "YYYY-MM-DD"

Close Sprint:

./sprint.sh close "Sprint 2"

List Sprints:

./sprint.sh list
./sprint.sh list --active
./sprint.sh list --project "Gantt Board"

Status Updates and Commenting Rules

Required Comment Format:

[YYYY-MM-DD HH:MM] 🔄 Status Update

**What was just done:**
- Completed action 1
- Completed action 2

**What is next:**
- Next action to take

**What is left to do:**
- Remaining work

When to Comment:

  • When starting work (mark in-progress)
  • Every 15 minutes during long tasks
  • When handing off to another agent
  • When status changes
  • When completing work

Current Sprint vs Backlog

Current Sprint:

  • Active work that should be done now
  • 24/7 automated worker only processes current sprint
  • Statuses: open, todo, in-progress

Backlog:

  • Future work, not currently being processed
  • Tasks in backlog wait for sprint assignment
  • Status: backlog

Sprint Workflow:

User creates task → Add to current sprint → Automated worker picks up hourly → Work on it → Move to review → User validates → Move to done

Task Assignment Workflow

Default Assignees:

  • [AGENT_NAME]: [AGENT_USER_ID] (AI Agent)
  • [USER_NAME]: [USER_ID] (Human)

Name Resolution:

  • Projects: "Gantt Board" → auto-resolves to UUID
  • Sprints: "current" → most recent active sprint
  • Assignees: "[AGENT_NAME]" or "[USER_NAME]" → auto-resolves to UUID

4. Tools & Skills System

How Skills Work

Skill Definition: Skills are reusable capabilities defined in SKILL.md files. Each skill contains:

  • When to use the skill
  • Prerequisites
  • Commands and parameters
  • Examples
  • Troubleshooting

Skill Invocation:

1. User asks for something
2. Determine which skill applies
3. Read the skill's SKILL.md
4. Follow the instructions
5. Execute tools as specified

Skill Locations

System Skills (shared):

.agents/skills/
├── brainstorming/
├── dispatching-parallel-agents/
├── executing-plans/
├── finishing-a-development-branch/
├── receiving-code-review/
├── requesting-code-review/
├── subagent-driven-development/
├── systematic-debugging/
├── test-driven-development/
├── using-git-worktrees/
├── using-superpowers/
├── verification-before-completion/
├── writing-plans/
└── writing-skills/

User Skills (workspace-specific):

~/.openclaw/workspace/skills/
├── brainstorming -> ../.agents/skills/brainstorming  (symlink)
├── content-strategy/
├── copywriting/
├── dispatching-parallel-agents -> ../.agents/skills/...
├── executing-plans -> ../.agents/skills/...
├── finishing-a-development-branch -> ../.agents/skills/...
├── intelligent-article-research/
├── receiving-code-review -> ../.agents/skills/...
├── requesting-code-review -> ../.agents/skills/...
├── social-content/
├── subagent-driven-development -> ../.agents/skills/...
├── systematic-debugging -> ../.agents/skills/...
├── tavily-web-research/
├── test-driven-development -> ../.agents/skills/...
├── url-research-documents/
├── using-git-worktrees -> ../.agents/skills/...
├── using-superpowers -> ../.agents/skills/...
├── verification-before-completion -> ../.agents/skills/...
├── writing-plans -> ../.agents/skills/...
└── writing-skills -> ../.agents/skills/...

Example Skills in Use

Tavily Web Research:

# Search
mcporter call tavily.tavily_search "query=OpenAI news" max_results=5

# Extract URL
mcporter call tavily.tavily_extract 'urls=["https://example.com"]' extract_depth=advanced

# Deep research
mcporter call tavily.tavily_research "input=Research question" model=pro

Subagent-Driven Development:

  • Spawns Alice → Bob → Charlie for complex tasks
  • Defined workflow patterns
  • Automatic handoffs

Writing Skills:

  • Standard formats for different document types
  • Templates for README, plans, etc.

When to Read Skills vs Use Tools Directly

Read SKILL.md When:

  • First time using a capability
  • Complex multi-step process
  • Need to understand prerequisites
  • Troubleshooting issues

Use Tools Directly When:

  • Simple, one-shot operations
  • Already familiar with the tool
  • Quick file reads, web searches
  • Standard git operations

5. Memory & Documentation

Core Memory Files

AGENTS.md:

  • Boot sequence (SESSION_STARTUP.md first)
  • Write discipline (MANDATORY - log every task)
  • Project creation rules
  • Safety guidelines
  • Memory system architecture
  • Task management workflow
  • Git commit identity switching

SOUL.md:

  • Identity (AI Agent name/persona)
  • Personality traits
  • Mission and goals
  • Boundaries
  • What drives you

USER.md:

  • User preferences and context
  • Work style and schedule
  • Family details
  • Goals
  • Pet peeves

TOOLS.md:

  • All tools and their locations
  • API credentials
  • Project URLs
  • CLI usage examples
  • Subagent team info
  • Daily digest system

BRAIN.md:

  • Active projects
  • Technical patterns
  • Gotchas and lessons learned

Daily Logs Structure

Location: ~/.openclaw/workspace/memory/YYYY-MM-DD.md

Format:

# YYYY-MM-DD - Day

## Tasks Completed

### [HH:MM] Task Name
- What was requested
- What was decided
- What was done
- Any blockers or follow-ups

## Learnings
- New patterns discovered
- Mistakes to avoid

## Tomorrow
- Pending items

Task Logging Requirements:

After EVERY task completion, write to disk:

  1. Task Log → memory/YYYY-MM-DD.md

    • What was requested (1 sentence)
    • What was decided (if applicable)
    • What was done (bullet points)
    • Any blockers or follow-ups

  2. If Mistake Made → memory/LEARNINGS.md

    • What went wrong
    • Root cause
    • Prevention for next time

  3. If Significant Context → Update MEMORY.md or BRAIN.md

    • Only during heartbeat reviews
    • Curated wisdom, not raw logs
    • MEMORY.md for personal context
    • BRAIN.md for technical patterns

Write Discipline

Rule: ALWAYS write to disk

  • Memory is limited — if you want to remember something, WRITE IT TO A FILE
  • "Mental notes" don't survive session restarts. Files do.
  • When someone says "remember this" → update memory/YYYY-MM-DD.md
  • When you learn a lesson → update memory/LEARNINGS.md
  • When you make a mistake → document it
  • Text > Brain 📝

Security Rules for MEMORY.md

  • ONLY load in main session (direct chats with human)
  • DO NOT load in shared contexts (Discord, group chats, other people)
  • This is for security — contains personal context
  • You can read, edit, and update MEMORY.md in main sessions

6. Project Structure & Conventions

Where to Create Projects

ALWAYS create new projects in:

~/Documents/Projects/OpenClaw/

By Type:

  • Web projects: OpenClaw/Web/[project-name]/
  • iOS projects: OpenClaw/iOS/[project-name]/
  • Documents: OpenClaw/Documents/

NEVER create projects in:

  • ~/ (home root)
  • ~/.openclaw/workspace/ (agent workspace)
  • Random other locations

Web vs iOS Project Locations

Web Projects:

OpenClaw/Web/
├── gantt-board/          # Task management
├── blog-backup/          # Blog backup system
├── mission-control/      # Dashboard
└── heartbeat-monitor/    # Health checks

iOS Projects:

OpenClaw/iOS/
├── [app-name]/           # Swift/Xcode projects

Key Difference:

  • Web = AI Agent projects
  • iOS = User's projects

Git Workflow

Gitea Server Setup:

  • Install Gitea on a server (can be local machine or VPS)
  • Configure your chosen port (default: 3000)
  • Create organization for your projects
  • Note the login credentials for the CLI scripts

Backup Rule - MANDATORY:

# ALWAYS push to Gitea after significant changes:
cd ~/.openclaw/workspace
git add -A
git commit -m "Description of changes"
git push origin master

Push after:

  • New skills or agent profiles created
  • TOOLS.md, SOUL.md, AGENTS.md updates
  • New cron jobs or automation
  • Significant memory/documentation changes
  • New project scaffolding

Clone from Gitea:

git clone https://[your-gitea-host]:[port]/[org]/[repo-name].git

Commit Identity Switching

IMPORTANT: Switch Identity Based on Project Owner

Check current identity:

git config user.name
git config user.email

User's Projects:

git config user.name "[YOUR_NAME]"
git config user.email "[YOUR_EMAIL]"
  • iOS apps (Swift/Xcode)
  • Personal projects

AI Projects:

git config user.name "[AI_AGENT_NAME]"
git config user.email "[AI_AGENT_EMAIL]"
  • Web projects (Next.js/React)
  • Infrastructure/DevOps
  • Automation tools

Visual Reminder:

  • Web projects (Next.js/React) = AI Agent
  • iOS projects (Swift/Xcode) = User
  • Infrastructure/DevOps = AI Agent
  • When in doubt, ASK or check Gitea org

Appendix A: Quick Reference

Essential Commands

# Gateway control
openclaw gateway status/start/stop/restart

# Gantt Board CLI
cd ~/.openclaw/workspace/scripts
./task.sh create --title "New Task"
./task.sh list --status todo
./project.sh list
./sprint.sh list --active

# Memory
# Write to memory/YYYY-MM-DD.md after every task

# Git backup
cd ~/.openclaw/workspace
git add -A && git commit -m "message" && git push origin master

# Subagents
subagents list
subagents kill <session-id>
sessions_spawn({ task: "...", label: "Agent", agentId: "main" })

File Locations

File Path
AGENTS.md ~/.openclaw/workspace/AGENTS.md
SOUL.md ~/.openclaw/workspace/SOUL.md
USER.md ~/.openclaw/workspace/USER.md
TOOLS.md ~/.openclaw/workspace/TOOLS.md
BRAIN.md ~/.openclaw/workspace/BRAIN.md
Daily Logs ~/.openclaw/workspace/memory/YYYY-MM-DD.md
Team Registry ~/.openclaw/workspace/agents/TEAM-REGISTRY.md
Skills ~/.openclaw/workspace/skills/
Projects ~/Documents/Projects/OpenClaw/

URL Patterns

Resource Pattern
Gantt Board Local http://localhost:3000
Gantt Board Live [YOUR_DEPLOYED_URL]
Gitea Server https://[your-gitea-host]:[port]
Supabase URL [YOUR_SUPABASE_URL]

User IDs (Pattern)

Role Pattern
AI Agent ID [UUID-FOR-AI-AGENT]
Human User ID [UUID-FOR-HUMAN]

Appendix B: Session Continuity Guarantee

What Survives Reboots:

✅ All config files (SOUL.md, USER.md, TOOLS.md, etc.)
✅ Subagent team definitions
✅ Git repository and history
✅ Cron jobs (stored in OpenClaw config)
✅ Daily memory logs

Protection Mechanisms:

  1. Git Repository - Full version control
  2. Gitea Remote - Backup server at your configured host
  3. Disk Storage - Files on disk, not in memory
  4. Deterministic Boot - Same files, same order

Recovery Commands:

# If workspace folder deleted
cd ~/.openclaw
git clone https://[your-gitea-host]:[port]/[org]/[repo-name].git workspace

# If file corrupted
cd ~/.openclaw/workspace
git checkout HEAD -- filename.md

# Verify after reboot
cd ~/.openclaw/workspace
git log --oneline -3
openclaw cron list

Document Version: 1.0 (Generic)
Last Updated: 2026-02-24
Maintained by: Alice-Researcher

Note: This guide contains no specific credentials, URLs, or sensitive information. Replace all [PLACEHOLDERS] with your actual values when setting up your own instance.