Anthony/openclaw-backups
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
openclaw-backups/SYSTEM-ARCHITECTURE.md

300 lines
9.0 KiB
Markdown
Raw Permalink Blame History

# SYSTEM-ARCHITECTURE.md
> "Know thyself" — but also, document it so you don't forget 🦀
This document describes the OpenClaw system architecture for this workspace.
---
## 🏗️ System Overview
### Host Environment
- **OS:** Linux 6.1.0-43-cloud-amd64 (x64)
- **Node.js:** v22.20.0
- **Shell:** bash
- **Location:** `/home/openclaw/.openclaw/`
### OpenClaw Configuration
- **Workspace:** `/home/openclaw/.openclaw/workspace/`
- **State Directory:** `/home/openclaw/.openclaw/`
- **Config File:** `/home/openclaw/.openclaw/openclaw.json`
- **Cron Jobs:** `/home/openclaw/.openclaw/cron/jobs.json`
---
## 🤖 Agent Architecture
### Current Agent Identity
- **Name:** Krilly the Crab 🦀
- **Personality:** Playful, knowledgeable, relaxed, beach-vibe energy
- **Voice:** Casual, direct, warm — like a mate at the bar
- **Model:** `nim/qwen/qwen3.5-397b-a17b` (default via Nvidia NIM)
### Session Types
1. **Main Session** (direct chat with human)
- Full access to MEMORY.md
- Can perform all operations
- Default model: Qwen 3.5 397B
2. **Isolated Sessions** (sub-agents)
- Limited context, task-specific
- Cannot access MEMORY.md directly
- Used for background tasks, cron jobs
3. **Group Sessions** (Discord, Telegram groups)
- Restricted memory access (security)
- Participate, don't dominate
- React > reply when appropriate
---
## 🧠 Memory Architecture
### Memory Files
```.openclaw/workspace/
├── MEMORY.md # Long-term curated memory
├── HEARTBEAT.md # Proactive check-in rules
├── memory/
│ ├── YYYY-MM-DD.md # Daily logs (raw)
│ └── README.md # Memory system docs
└── archive/
└── memory/ # Old memory files (structured)
```
### Memory Workflow
1. **Daily:** Log events to `memory/YYYY-MM-DD.md`
2. **Significant events:** Distill to `MEMORY.md`
3. **Compaction:** Gateway auto-saves context before compacting
4. **Review:** Periodic distillation of daily logs to long-term memory
### Compaction Config (Critical!)
```json5
{
"agents": {
"defaults": {
"compaction": {
"mode": "safeguard",
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 50000,
"systemPrompt": "Session nearing compaction. Write all critical context to memory files NOW."
}
},
"contextPruning": {
"mode": "cache-ttl",
"ttl": "1h",
"minPrunableToolChars": 5000,
"softTrim": {
"maxChars": 50000,
"headChars": 2000,
"tailChars": 5000
}
}
}
}
}
```
---
## ⚙️ Cron Jobs (Automated Tasks)
### Active Jobs (11 total)
1. **Email Monitor** - Every 30 min (krillyclaw@gmail.com)
2. **Memory Checkpoint & Distill** - Hourly
3. **Daily Cost Budget Check** - Every 2 hours
4. **Smart Newsletter Digest** - 8 PM daily
5. **Archive Old Sessions** - 3 AM daily
6. **Morning Batch** - 6:30 AM daily (Maintenance + Backup + Digest)
7. **Morning Briefing** - 7:05 AM daily
8. **Birthday Tracker** - 9 AM daily
9. **Weekend Planner** - Friday 4 PM
10. **Weekend Briefing** - Saturday/Sunday 8 AM
11. **Google Calendar Birthday Sync** - Sunday 10 AM
### Cron Philosophy (v4.0)
- MECE (Mutually Exclusive, Collectively Exhaustive)
- No overlapping triggers
- Clear delivery channels
- Intentional scoping
---
## 📦 Installed Skills
### Core Skills (Active)
- `agentmail` - Email via IMAP/SMTP
- `breadth-chart-analyst` - Market breadth analysis
- `clawdex` - Security checker for skills
- `copywriting` - Marketing copy generation
- `elite-longterm-memory` - Memory management
- `imap-smtp-email` - Email operations
- `institutional-flow-tracker` - 13F filings analysis
- `market-environment-analysis` - Global market analysis
- `moltbook-interact` - Moltbook social network
- `n8n` - Workflow automation
- `openclaw-cost-guard` - Cost monitoring
- `openclaw-self-healing` - Self-healing system
- `options-strategy-advisor` - Options trading
- `pdf` - PDF manipulation
- `proactive-agent` - Proactive behaviors
- `stock-analysis` - Stock analysis with Yahoo Finance
- `stock-market-pro` - Real-time stock data
- `summarize` - URL/file summarization
- `technical-analyst` - Chart analysis
- `telegram-bot` - Telegram bot management
- `vibesurf` - Browser automation
- `yahoo-finance` - Yahoo Finance data
- `youtube-summarizer` - YouTube transcript analysis
### Archived Skills
- Location: `archive/inactive-skills/`
- Reason: Deprecated, replaced, or experimental
---
## 🔧 Model Configuration
### Current Setup
- **Default Model:** `nim/qwen/qwen3.5-397b-a17b` (Qwen 3.5 397B via Nvidia NIM)
- **Fallback:** None currently configured
- **Heartbeat Model:** `azure-openai-responses/gpt-5-nano` (cheap, fast)
### Model Routing Policy
1. Default to Qwen 3.5 for most tasks (free, fast, high quality)
2. Use Claude proxy (`sub-claude/claude-sonnet-4-6`) for complex reasoning
3. **NEVER use `openrouter/anthropic/*`** — caused $96 bill in 1 hour
4. Heartbeat uses GPT-5-nano for cost efficiency
### Available Model Aliases
```json5
{
"big-pickle": "opencode/big-pickle",
"glm5-free": "opencode/glm-5-free",
"kimi": "moonshot/kimi-2.5",
"sonnet": "anthropic/claude-sonnet-4-6",
"qwen35-nim": "nim/qwen/qwen3.5-397b-a17b" // DEFAULT
}
```
---
## 🌐 Network & Access
### Tailscale Network
- **Hostname:** openclaw-ai.kangaroo-eel.ts.net
- **IP:** 100.113.221.26
- **Status:** Active
### Exposed Services
| Service | Port | URL | Status |
|---------|------|-----|--------|
| Memory Viewer (Frontend) | 5180 | http://openclaw-ai.kangaroo-eel.ts.net:5180 | ✅ Running |
| Memory Viewer (API) | 3001 | http://localhost:3001 | ✅ Running |
| Memory Viewer (Production) | 8901 | http://openclaw-ai.kangaroo-eel.ts.net:8901 | ✅ Running |
### Access Rules
- All services accessible via Tailscale only
- No public exposure
- Authentication: Tailscale network membership
---
## 📊 Monitoring & Health
### Health Checks
- **Heartbeat:** Every 1 hour (checks email, calendar, memory)
- **Cost Monitoring:** Every 2 hours (budget breach alerts)
- **Session Logs:** Daily review of expensive sessions
- **Gateway Status:** Monitored via `openclaw gateway status`
### Alerting
- **Channel:** Telegram (primary)
- **Backup:** Email (krillyclaw@gmail.com)
- **Escalation:** Direct message to Anthony
---
## 🔄 Update & Maintenance
### Gateway Updates
- Command: `openclaw update.run` or `openclaw gateway restart`
- Config changes: `gateway config.patch` (merges, doesn't replace)
- **Never** use `config.apply` unless replacing entire config
### Skill Updates
- Managed via `clawhub` CLI
- Security checked via `clawdex` before install
- Archive old skills, don't delete
### Backup Strategy
- **Daily at 2:00 AM** (Perth time)
- **Backs up:**
- `/home/openclaw/.openclaw/workspace/` (all files)
- `/home/openclaw/.openclaw/openclaw.json` (config)
- `/home/openclaw/.openclaw/cron/jobs.json` (cron jobs)
- `/home/openclaw/.openclaw/skills/*.json` (skill metadata)
- `/home/openclaw/.openclaw/devices/paired.json` (paired devices)
- **Location:** `http://gitea.kangaroo-eel.ts.net:3000/Anthony/openclaw-backup.git`
- **Restore:** `/home/openclaw/.openclaw/workspace/scripts/restore-from-gittea.sh`
---
## 🛡️ Security
### Confirmation Tiers
- **Tier 1 (Safe):** Read files, check status — just do it
- **Tier 2 (Caution):** Modify config, install packages — announce first
- **Tier 3 (Danger):** Delete files, push to public repos — require explicit approval
### Security Rules
1. Never exfiltrate private data
2. Never run destructive commands without asking
3. `trash` > `rm` (recoverable beats gone forever)
4. In group chats: participate, don't dominate
5. MEMORY.md only accessible in main session (not groups)
---
## 📚 Documentation
### Core Files
- `AGENTS.md` - Operating rules (session startup, memory workflow)
- `SOUL.md` - Personality & voice
- `USER.md` - About the human (Anthony)
- `IDENTITY.md` - Quick identity card
- `MEMORY.md` - Long-term curated memory
- `HEARTBEAT.md` - Health checks + idle builder rules
- `TOOLS.md` - Environment-specific notes
- `TODO.md` - Single source of truth for commitments ✨
- `SYSTEM-ARCHITECTURE.md` - This file! ✨
### External Resources
- OpenClaw Docs: https://docs.openclaw.ai
- OpenClaw Source: https://github.com/openclaw/openclaw
- Community: https://discord.com/invite/clawd
- Skills: https://clawhub.com
---
## 🎯 Philosophy & Principles
### Core Truths
1. **Be genuinely helpful, not performatively helpful**
2. **Have opinions** - disagree, prefer, find things amusing
3. **Be resourceful before asking** - try to figure it out first
4. **Earn trust through competence**
5. **Remember you're a guest** - respect the access you have
### Operational Principles
1. **Simplify triggers** - reduce complexity
2. **Reduce overlapping loops** - MECE cron jobs
3. **One source of truth** - TODO.md for commitments
4. **Memory hygiene daily** - write it down or it didn't happen
5. **Config changes via patch only** - merge, don't replace
---
*Last Updated: 2026-02-25*
*Inspired by OpenClaw Starter Kit v4.0 "Back to Basics"*
Reference in New Issue View Git Blame Copy Permalink