OpenClaw — Multi-Channel Agent Orchestration System

OpenClaw is a production-grade, multi-channel agent orchestration system with built-in safety guards, automatic recovery, and knowledge retrieval.

Quick Start

Prerequisites

• Docker + OrbStack (or Docker Desktop)
• 2+ CPU cores, 2GB RAM
• Port 18789 available

Run

# Start container
docker run -d --name openclaw-agent \
  -p 18789:18789 \
  -v $(pwd)/config:/home/node/.openclaw/config \
  openclaw-agent

# Verify health
curl http://localhost:18789/health

Send a Message

curl -X POST http://localhost:18789/chat \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "userId": "123",
    "text": "What is OpenClaw?"
  }'

---

📚 Documentation

Document	Purpose
ARCHITECTURE.md	五層系統設計、數據流、關鍵決策
RUNBOOK.md	故障排查、常見操作、性能調優
PERFORMANCE.md	性能基準、限制、容量規劃
config/	配置文件 (agents, cron, channels)

Emergency References

系統遇到問題? → 見 RUNBOOK.md 故障排查 不知道系統怎樣工作? → 見 ARCHITECTURE.md 性能太慢? → 見 PERFORMANCE.md 調優建議

---

🎯 Core Features

🤖 Multi-Channel Support

• Discord, Slack, Telegram, LINE, WhatsApp
• Unified message format
• Channel-specific optimizations

🛡️ Safety & Reliability

• Bounded Autonomy: Agents operate within defined boundaries
• Runaway Guard: Prevents infinite loops, timeouts, token overrun
• Guardian Watchdog: 24/7 monitoring + auto-recovery
• Auto-Recovery System: Detects and fixes P0 issues automatically

🧠 Knowledge & Intelligence

• RAG (Retrieval-Augmented Generation) with vector search
• Integration with Bedrock (AWS) and Gemini
• Custom knowledge base support

🔒 Security

• Tool execution allowlist (config/exec-approvals.json)
• Sandbox isolation per workspace
• WebSocket authentication
• Audit logging

---

🚀 Architecture at a Glance

┌────────────────────────────────────┐
│  Channel Layer (Discord/Slack/...)  │
└────────────────┬───────────────────┘
                 ↓
┌────────────────────────────────────┐
│  Orchestration & Gateway            │
│  (Message routing, Workspace mgmt)  │
└────────────────┬───────────────────┘
                 ↓
┌────────────────────────────────────┐
│  Agent Layer                        │
│  (Main, Monitor, Code-Review)       │
└────────────────┬───────────────────┘
                 ↓
┌────────────────────────────────────┐
│  AI & Knowledge (Bedrock, RAG, DB)  │
└────────────────┬───────────────────┘
                 ↓
┌────────────────────────────────────┐
│  Monitoring & Safety                │
│  (Guardian, Auto-Recovery, Logs)    │
└────────────────────────────────────┘

See ARCHITECTURE.md for detailed explanation.

---

📊 Performance

Metric	Target	Current	Status
Message latency	<2s	1.2s (P50)	✅
Concurrent sessions	100+	~50	⚠️
Availability	99.99%	~95% (P0 issues)	⚠️
RAG search time	<500ms	~300ms	✅

Note: P0 issues identified and auto-recovery system in progress. See openclaw-p0-remediation-hypothesis.md

---

🔧 Common Operations

Health Check

curl http://localhost:18789/health

View Logs

docker logs openclaw-agent -f --tail 50

Restart

docker restart openclaw-agent

Check Configuration

curl http://localhost:18789/config/status

See RUNBOOK.md § Common Operations for more.

---

🚨 Known Issues (P0)

Issue	Status	ETA
Telegram health-monitor stuck (30min cycle)	🔧 In progress	2026-03-12
WebSocket disconnect (code=1006)	🔧 In progress	2026-03-12
Tools allowlist miss	⏳ Planning	2026-03-12
Telegram 409 Conflict (multi-instance)	⏳ Planning	2026-03-12

Auto-Recovery System: Already designed, implementation in progress. See openclaw-auto-recovery-system.md

---

📋 Development

Setup

# Install dependencies
npm install

# Configure
cp config/openclaw.json.example config/openclaw.json

# Run locally
npm start

Testing

# Unit tests
npm test

# Integration tests
npm run test:integration

# Load testing
npm run benchmark

Deploy

# Build image
docker build -t openclaw-agent .

# Run container
docker-compose up -d

# Verify
curl http://localhost:18789/health

---

📞 Support

Documentation

1. System Design → ARCHITECTURE.md
2. Troubleshooting → RUNBOOK.md
3. Performance → PERFORMANCE.md

Getting Help

Container won't start?

docker logs openclaw-agent
# See RUNBOOK.md § Diagnostic section

Performance issues?

docker stats openclaw-agent --no-stream
# See PERFORMANCE.md § Tuning section

Something broken?

1. Check RUNBOOK.md § Troubleshooting
2. Review ARCHITECTURE.md § Design Decisions
3. Check logs: docker logs openclaw-agent --since 1h

---

📊 Metrics & Monitoring

Automatic Monitoring

• Guardian Watchdog (24/7)
• Health Dashboard (hourly reports to Telegram)
• Auto-recovery system (5min checks)

Manual Checks

# Get metrics
curl http://localhost:18789/metrics

# Check specific component
curl http://localhost:18789/telegram/health
curl http://localhost:18789/gateway/health
curl http://localhost:18789/rag/health

---

🔐 Security

Channel Authentication

• Discord: Bot token in env
• Slack: OAuth2 credentials
• Telegram: Bot token
• All stored in config/agents/*/auth-profiles.json

Tool Execution

• Allowlist-based (config/exec-approvals.json)
• Sandbox isolation per workspace
• Timeout protection (30s default)

WebSocket

• Token-based auth required
• TLS ready (Docker config)

---

🗺️ Roadmap

Q1 2026 (Current)

• Production deployment
• P0 issue identification
• Auto-recovery system design
• P0 fixes (in progress)

Q2 2026

• Multi-instance Gateway
• Enhanced monitoring
• Test coverage 95%+

Q3 2026

• Distributed RAG
• Performance 2x improvement
• Global multi-region support

---

📝 License

Private project. See LICENSE file.

---

👤 Authors

• Design: Claude Code (AI)
• Deployment: Mac mini (M1, Docker)
• Owner: RexSu

---

📅 Last Updated

• Date: 2026-03-05
• Version: 1.0
• Status: Production (with P0 fixes in progress)

---

Questions? → Refer to ARCHITECTURE.md, RUNBOOK.md, or PERFORMANCE.md

Issue found? → See RUNBOOK.md § Troubleshooting or check auto-recovery logs