openclaw

# OpenClaw — Autonomous AI Agent System

**Production-grade autonomous agent for task execution, portfolio management, and multi-channel integration.**

See [architecture.mermaid](architecture.mermaid) for the system diagram (renders on GitHub)

---

## Why This Exists

OpenClaw is an autonomous AI agent system designed to handle continuous, unattended work execution. It operates 24/7 on AWS EC2, pulling tasks from a structured backlog, executing them independently, and reporting results across multiple channels (Slack, Telegram, GitHub). Built as a real-world demonstration of:

- **Agent orchestration** — task queue lifecycle, sub-agent spawning, autonomous decision-making
- **Production engineering** — systemd service management, cron scheduling, error recovery
- **Multi-channel integration** — Slack SDK, GitHub API, Google Workspace, Telegram
- **LLM-powered automation** — Claude API for reasoning, tool use, and task execution

This is not a toy project. It's a production system managing real work: job applications, portfolio builds, research tasks, and technical writing.

---

## Architecture Overview

```mermaid
graph TB
    subgraph "External Interfaces"
        SLACK[Slack Workspace]
        TELEGRAM[Telegram]
        GITHUB[GitHub API]
        GOOGLE[Google Workspace]
    end

    subgraph "OpenClaw Core (AWS EC2)"
        AGENT[Agent Loop<br/>Claude API]
        BACKLOG[BACKLOG.md<br/>Task Queue]
        CRON[Cron Scheduler<br/>systemd timer]
        MEMORY[Memory Files<br/>MEMORY.md + daily logs]
    end

    subgraph "Execution Flow"
        HEARTBEAT[Heartbeat Poll]
        TASK_PULL[Pull Highest Priority Task]
        EXECUTE[Execute Task]
        REPORT[Report Results]
        COMMIT[Commit BACKLOG Update]
    end

    CRON -->|Every 4hrs| HEARTBEAT
    HEARTBEAT -->|Check HEARTBEAT.md| AGENT
    AGENT -->|Read| BACKLOG
    BACKLOG -->|Priority-sorted tasks| TASK_PULL
    TASK_PULL --> EXECUTE
    EXECUTE -->|Claude API reasoning| AGENT
    EXECUTE -->|Read context| MEMORY
    EXECUTE -->|Tool use| GITHUB
    EXECUTE -->|Tool use| GOOGLE
    EXECUTE --> REPORT
    REPORT -->|Slack notification| SLACK
    REPORT -->|Telegram message| TELEGRAM
    REPORT --> COMMIT
    COMMIT -->|git push| GITHUB
    
    style AGENT fill:#58a6ff
    style BACKLOG fill:#3fb950
    style CRON fill:#f0ad4e
```

**Key Components:**

1. **Agent Loop** — Claude API-powered reasoning engine with tool use capabilities
2. **Task Queue** — BACKLOG.md in GitHub serves as persistent queue (survives restarts)
3. **Cron Scheduler** — systemd timer fires autonomous sprint every 4 hours
4. **Memory System** — MEMORY.md (long-term) + daily logs (session continuity)
5. **Multi-Channel Integration** — Slack, Telegram, GitHub, Google Workspace APIs

---

## Tech Stack

| Component | Technology | Purpose |
|-----------|-----------|---------|
| **Agent Core** | Python 3.11, Claude API (Anthropic) | Reasoning, tool use, decision-making |
| **Web Framework** | FastAPI | Health checks, webhook endpoints |
| **Messaging** | Slack SDK, Telegram Bot API | Real-time notifications, DM responses |
| **Version Control** | GitHub API (PyGithub) | Task queue (BACKLOG.md), code management |
| **Productivity** | Google Workspace API (gog CLI) | Docs, Sheets, Calendar integration |
| **Scheduling** | systemd timer, cron | Autonomous sprint cycles |
| **Deployment** | AWS EC2 (t4g.small, ARM64), systemd | 24/7 operation, auto-restart on failure |
| **Memory** | Markdown files (MEMORY.md, memory/*.md) | Session continuity, long-term recall |

---

## Features

### ✅ Autonomous Operation
- **Cron-based sprints**: Runs every 4 hours, pulls highest-priority task from BACKLOG.md
- **Independent execution**: No human intervention required for routine tasks
- **Error recovery**: Handles API failures, rate limits, retries with exponential backoff

### ✅ Task Queue Protocol
- **BACKLOG.md**: GitHub-hosted Markdown file serving as persistent task queue
- **Priority system**: P0 (today), P1 (this week), P2 (next sprint), P3 (someday)
- **Status tracking**: `pending → in_progress → done | blocked`
- **Atomic updates**: Each status change committed to GitHub with explanation

### ✅ Multi-Channel Integration
- **Slack**: Real-time task notifications, status updates, question/answer loops
- **Telegram**: Mobile-first messaging, file uploads, media sharing
- **GitHub**: Code pushes, PR creation, issue management, repo setup
- **Google Workspace**: Document creation (Docs), data pipelines (Sheets), calendar management

### ✅ Memory System
- **Long-term memory**: MEMORY.md for important context, decisions, lessons learned
- **Daily logs**: `memory/YYYY-MM-DD.md` for session-specific work
- **Semantic search**: `memory_search` tool for context retrieval before answering

### ✅ Sub-Agent Orchestration
- **sessions_spawn**: Delegate complex tasks to isolated sub-agents
- **Parallel execution**: Multiple sub-agents run concurrently
- **Result aggregation**: Sub-agents report back to main session

---

## Setup Instructions

### Prerequisites
- Python 3.11+
- AWS EC2 instance (t4g.small or larger, Ubuntu 24.04 ARM64)
- Anthropic API key (Claude access)
- GitHub personal access token (classic, `repo` scope)
- Slack workspace + bot token
- Google Workspace account + OAuth credentials

### Installation

```bash
# Clone repository
git clone https://github.com/kevin-bot-openclaw-ops/openclaw.git
cd openclaw

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys:
#   ANTHROPIC_API_KEY=sk-ant-...
#   GITHUB_TOKEN=ghp_...
#   SLACK_BOT_TOKEN=xoxb-...
#   TELEGRAM_BOT_TOKEN=...

# Set up systemd service
sudo cp openclaw.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

# Verify service is running
sudo systemctl status openclaw
```

### Configuration

1. **BACKLOG.md**: Create in a private GitHub repo (e.g., `JerzyPlocha/kevin-backlog`)
2. **MEMORY.md**: Initialize in workspace with seed context
3. **Cron schedule**: Edit `openclaw.timer` for custom sprint frequency

---

## Demo

### Task Delegation Round-Trip

**1. Human adds task to BACKLOG.md:**
```markdown
### TASK-042: Research Kubernetes autoscaling patterns
- **Status**: pending
- **Priority**: P1
- **Acceptance criteria**: 
  - [ ] Compare HPA vs VPA vs KEDA
  - [ ] Cost analysis for each approach
  - [ ] Recommendation with rationale
```

**2. Cron fires, agent pulls task:**
```
08:00 UTC — Sprint start
Reading BACKLOG.md... found TASK-042 (P1, pending)
Marking in_progress... committed to GitHub
```

**3. Agent executes:**
```
web_search("Kubernetes HPA vs VPA benchmarks")
web_search("KEDA autoscaling pricing AWS EKS")
→ Synthesizes findings
→ Writes comparison.md
```

**4. Agent reports completion:**
```
TASK-042 complete ✅
- Deliverables: comparison.md (GitHub), cost_table.md
- Recommendation: KEDA for event-driven workloads, HPA for CPU/mem
- Duration: 18 minutes
→ Posted to Slack #ops
→ BACKLOG.md updated: status=done
→ Committed to GitHub
```

**5. Human reviews in Slack, approves:**
```
Jurek: "Good analysis. Apply this to the ml-serving repo."
Agent: "On it. Created TASK-043."
```

---

## Security & Privacy

- **No secrets in code**: All API keys stored in environment variables or systemd secrets
- **Private repos**: BACKLOG.md and MEMORY.md live in private GitHub repos
- **Scoped tokens**: GitHub PAT limited to specific repos, Slack bot has minimal permissions
- **Audit trail**: Every action logged, committed to GitHub with timestamps

**Secrets scan:**
```bash
# Verify no tokens committed
grep -r "xoxb-\|ghp_\|sk-ant-" . --exclude-dir=.git
# Should return: 0 matches
```

---

## Project Structure

```
openclaw/
├── README.md              # This file
├── architecture.mermaid   # System diagram source
├── architecture.png       # Rendered diagram
├── requirements.txt       # Python dependencies
├── .env.examp

[truncated…]