901 lines
22 KiB
Markdown
901 lines
22 KiB
Markdown
# 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](#1-openclaw-setup)
|
||
2. [Subagent Workflow Architecture](#2-subagent-workflow-architecture)
|
||
3. [Gantt Board Integration](#3-gantt-board-integration)
|
||
4. [Tools & Skills System](#4-tools--skills-system)
|
||
5. [Memory & Documentation](#5-memory--documentation)
|
||
6. [Project Structure & Conventions](#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:**
|
||
```bash
|
||
# 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):**
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# 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:**
|
||
```javascript
|
||
sessions_spawn({
|
||
task: "Detailed task description",
|
||
label: "Agent-Name",
|
||
agentId: "main"
|
||
})
|
||
```
|
||
|
||
**Managing Subagents:**
|
||
```bash
|
||
# 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:**
|
||
```javascript
|
||
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:**
|
||
```javascript
|
||
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:**
|
||
```javascript
|
||
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):**
|
||
```json
|
||
{
|
||
"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:**
|
||
```bash
|
||
# 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:**
|
||
```bash
|
||
./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:**
|
||
```bash
|
||
# 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:**
|
||
```bash
|
||
./task.sh delete <task-id>
|
||
```
|
||
|
||
### Project Management
|
||
|
||
**Create Project:**
|
||
```bash
|
||
./project.sh create \
|
||
--name "New Project" \
|
||
--description "Project description" \
|
||
--color "#3b82f6"
|
||
```
|
||
|
||
**List Projects:**
|
||
```bash
|
||
./project.sh list
|
||
./project.sh list --json
|
||
```
|
||
|
||
**Update Project:**
|
||
```bash
|
||
./project.sh update "Gantt Board" \
|
||
--name "Updated Name" \
|
||
--description "Updated description"
|
||
```
|
||
|
||
### Sprint Management
|
||
|
||
**Create Sprint:**
|
||
```bash
|
||
./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:**
|
||
```bash
|
||
./sprint.sh close "Sprint 2"
|
||
```
|
||
|
||
**List Sprints:**
|
||
```bash
|
||
./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:**
|
||
```bash
|
||
# 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:**
|
||
```markdown
|
||
# 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:**
|
||
```bash
|
||
# 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:**
|
||
```bash
|
||
git clone https://[your-gitea-host]:[port]/[org]/[repo-name].git
|
||
```
|
||
|
||
### Commit Identity Switching
|
||
|
||
**IMPORTANT: Switch Identity Based on Project Owner**
|
||
|
||
**Check current identity:**
|
||
```bash
|
||
git config user.name
|
||
git config user.email
|
||
```
|
||
|
||
**User's Projects:**
|
||
```bash
|
||
git config user.name "[YOUR_NAME]"
|
||
git config user.email "[YOUR_EMAIL]"
|
||
```
|
||
- iOS apps (Swift/Xcode)
|
||
- Personal projects
|
||
|
||
**AI Projects:**
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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:**
|
||
|
||
```bash
|
||
# 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.
|