Openclaw Agent Deployment

OpenClaw Agent Deployment

Amaç

Bir OpenClaw AI agent'ini yerel veya uzak ortamda production-ready olarak çalıştırın. Bu beceri; agent yapılandırması, ortam hazırlığı, kanal bağlantısı, güvenlik sertleştirmesi ve sürekli çalışma için gereken tüm adımları kapsar.

Kategori: AI Otomasyon

Girdiler

Zorunlu

• Agent Rolü: Agent'in ne yapacağı (örn: SEO analisti, kod inceleyici, proje yöneticisi)
• Hedef Platform: Nereye deploy edileceği (yerel makine, VPS, Docker, Raspberry Pi)
• LLM Tercihi: Hangi dil modeli kullanılacak (Claude, GPT-4o, Ollama/yerel model)

İsteğe Bağlı

• Kanal: Telegram, Slack, Discord veya WebChat
• Çoklu Agent: Birden fazla agent çalıştırılacaksa AGENTS.md yapılandırması
• Zamanlama: HEARTBEAT.md ile periyodik görevler

Sistem Bağlamı

Başlamadan önce:

• Mevcut proje bağlamı ve öncelikleri için memory.md'yi oku
• İlgili deployment kuralları veya kısıtlamalar için knowledge-base.md'yi kontrol et
• Hedef sunucunun donanım özelliklerini belirle (RAM, CPU, disk, GPU)
• Gerekli API anahtarlarının ve token'ların hazır olduğunu doğrula

Süreç

Adım 1: SOUL.md Yapılandırması

Agent'in kimliğini, kurallarını ve araçlarını tanımlayan SOUL.md dosyasını oluşturun:

# SOUL.md

## Kimlik
Sen [rol adı] agent'isın. [Tek cümlelik amaç].

## Kurallar
- [Sınır 1: ne yapmamalı]
- [Sınır 2: hangi dosyalara erişebilir]
- [Sınır 3: hangi durumlarda kullanıcıya sormalı]

## Araçlar
- [Araç 1: ne için kullanılır]
- [Araç 2: ne için kullanılır]

## Çıktı Formatı
[Agent'in yanıt formatı]

Kurallar bölümü, agent güvenilirliğinin %80'ini belirler. Kimlik kısmından önce kuralları netleştirin.

İpucu: SOUL.md'yi sıfırdan yazmak yerine, crewclaw.com üzerinden rol seçip hazır şablon oluşturabilir veya awesome-openclaw-agents deposundaki 177 şablondan birini başlangıç noktası olarak kullanabilirsiniz.

Adım 2: Ortam Hazırlığı

Seçenek A: Docker (önerilen)

# docker-compose.yml
version: "3.8"
services:
  openclaw:
    image: node:22-slim
    working_dir: /app
    volumes:
      - ./agents:/app/agents
      - ./.env:/app/.env
    ports:
      - "127.0.0.1:18789:18789"
    command: npx openclaw gateway start
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Seçenek B: Bare Metal (pm2)

# Node.js 22 kurulumu
curl -fsSL https://openclaw.ai/install.sh | bash

# Agent dizini oluştur
mkdir -p agents/my-agent
cp SOUL.md agents/my-agent/

# pm2 ile daemon olarak çalıştır
npm i -g pm2
pm2 start "npx openclaw gateway start" --name openclaw
pm2 save
pm2 startup

Seçenek C: Raspberry Pi / Düşük Kaynak

# Minimum gereksinim: 512MB RAM, Node.js 22
# Ollama ile yerel model kullanılacaksa: 4GB+ RAM
curl -fsSL https://openclaw.ai/install.sh | bash

Adım 3: LLM Provider Yapılandırması

# .env dosyası
# Claude (önerilen - en iyi tool calling)
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI alternatifi
OPENAI_API_KEY=sk-...

# Ollama ile ücretsiz yerel model
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.3

Provider seçimi:

Adım 4: Kanal Bağlantısı

Telegram

# 1. @BotFather'dan bot oluştur, token al
# 2. .env'ye ekle
TELEGRAM_BOT_TOKEN=123456:ABC...

# 3. Agent'a Telegram kanalını ekle
openclaw config set --agent my-agent --channel telegram

Slack

# 1. Slack App oluştur (api.slack.com/apps)
# 2. Bot Token Scopes: chat:write, app_mentions:read
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

openclaw config set --agent my-agent --channel slack

Discord

# 1. Discord Developer Portal'dan bot oluştur
DISCORD_BOT_TOKEN=...

openclaw config set --agent my-agent --channel discord

Adım 5: Gateway Güvenlik Sertleştirmesi

# Gateway'i sadece localhost'a bağla (zorunlu)
openclaw config set gateway.host 127.0.0.1

# Uzaktan erişim gerekiyorsa SSH tüneli kullan
ssh -L 18789:localhost:18789 user@sunucu

# Rate limiting aktifleştir
openclaw config set gateway.rateLimit 60

# API anahtarlarını .env'de tut, ASLA koda gömme
echo ".env" >> .gitignore

Güvenlik kontrol listesi:

• Gateway port 18789 dışarıya kapalı
• API anahtarları .env dosyasında
• .env dosyası .gitignore'da
• SSH erişimi anahtar tabanlı (şifre değil)
• Agent dosya erişimi SOUL.md'de sınırlandırılmış
• Shell komutları gerekli minimumda

Adım 6: HEARTBEAT.md ile Sağlık Kontrolü

# HEARTBEAT.md

## Periyodik Kontroller (her 30 dakika)
- Gateway bağlantısını doğrula
- Son 30 dakikadaki hata sayısını kontrol et
- API kredi bakiyesini kontrol et
- Disk kullanımını kontrol et (log dosyaları)

## Günlük Görevler (her gün 09:00)
- Günlük özet raporu oluştur
- Log dosyalarını rotasyona al
- Bağımlılık güncellemelerini kontrol et

Adım 7: Monitoring ve Loglama

# Log çıktısını dosyaya yönlendir
pm2 logs openclaw --lines 100

# Basit uptime monitoring
# crontab -e ile ekle:
*/5 * * * * curl -sf http://localhost:18789/health || pm2 restart openclaw

# Hata bildirimi (ntfy.sh ile ücretsiz push notification)
*/5 * * * * curl -sf http://localhost:18789/health || curl -d "OpenClaw agent down!" ntfy.sh/my-alerts

Adım 8: Güncelleme Stratejisi

# OpenClaw güncelleme
npm update -g openclaw

# Agent yapılandırma güncellemesi (sıfır kesinti)
# 1. Yeni SOUL.md'yi hazırla
# 2. Test ortamında doğrula
openclaw agent --agent my-agent --message "test: merhaba"
# 3. Production'a kopyala
cp SOUL.md.new agents/my-agent/SOUL.md
# 4. Gateway'i yeniden yükle (restart gerekmez)
openclaw gateway reload

Kalite Doğrulama

• Agent SOUL.md dosyası net kurallar ve sınırlar içeriyor
• Docker veya pm2 ile daemon olarak çalışıyor
• Gateway sadece localhost'a bağlı
• API anahtarları güvenli saklanıyor
• En az bir kanal (Telegram/Slack/Discord) bağlı ve test edilmiş
• HEARTBEAT.md ile periyodik sağlık kontrolü aktif
• Log rotasyonu yapılandırılmış
• Hata durumunda bildirim mekanizması var
• Güncelleme prosedürü belgelenmiş

Çıktı Formatı

# Deployment Raporu: [Agent Adı]

## Özet
- **Agent**: [Rol ve amaç]
- **Platform**: [Docker / VPS / Raspberry Pi]
- **LLM**: [Provider ve model]
- **Kanal**: [Telegram / Slack / Discord]
- **Durum**: [Çalışıyor / Hata]

## Bağlantı Bilgileri
- **Gateway**: localhost:18789
- **Kanal**: [Bot kullanıcı adı veya webhook URL]
- **Loglar**: [Log dosya yolu]

## Güvenlik
- Gateway: [localhost bağlı / açık]
- API anahtarları: [.env'de / güvensiz]
- Dosya erişimi: [sınırlı / sınırsız]

## Monitoring
- Uptime kontrolü: [aktif / pasif]
- Hata bildirimi: [aktif / pasif]
- Log rotasyonu: [aktif / pasif]

## Sonraki Adımlar
- [ ] [İlk test mesajı gönder]
- [ ] [HEARTBEAT.md yapılandır]
- [ ] [Yedekleme planı oluştur]

Temel Metrikler

• Uptime: %99.5+ hedef (ayda max 3.6 saat kesinti)
• Yanıt Süresi: İlk yanıt < 5 saniye
• API Maliyeti: Agent başına günlük maliyet takibi
• Hata Oranı: Başarısız görev yüzdesi < %5
• Bağlam Taşması: Session başına ortalama token kullanımı

En İyi Pratikler

• Agent başına tek sorumluluk — geniş kapsamlı agent'lar yerine dar odaklı agent'lar tercih et
• SOUL.md'deki kurallar bölümü güvenilirliğin %80'ini belirler — önce kuralları yaz
• Çoklu agent takımları 3-5 agent'ta en iyi çalışır — daha fazlası koordinasyon yükü getirir
• Yerel modeller (Ollama) basit routing görevleri için yeterli — her şey için Claude gerekmez
• Gateway'i asla internete açma — her zaman SSH tüneli veya VPN kullan
• Log dosyalarını rotasyona al — kontrol edilmeyen loglar diski doldurur
• Güncellemeden önce her zaman test ortamında doğrula

Tamamlandıktan Sonra

• Agent yapılandırması ve erişim bilgileri için memory.md'yi güncelle
• Deployment sırasında öğrenilen kuralları knowledge-nominations.md'ye ekle
• Takip eylemleri (monitoring, yedekleme) için .claude/workspace/TaskBoard.md'ye görev ekle
• Çoklu agent gerekiyorsa multi-agent-workflow skill'ini öner