Bu belge, OpenClaw Agent tarafından LLM'ye gönderilen tam Sistem Prompt yapısının ayrıntılı bir dökümünü sunar.
Sürüm:
v2.1
Güncelleme Zamanı:
2026-03-05
Genel Mimari Diyagramı
Hızlı Gezinme (TL;DR)
Yeni Başlayanlar için Mutlaka Okunmalı:
- Katman 7 (Çalışma Alanı Dosyaları) - Doğrudan düzenleyebileceğiniz yapılandırma dosyaları.
- Katman 8 (Önyükleme Kancası) - İçeriği dinamik olarak eklemek için betikler yazabileceğiniz yer.
- Diğer katmanlar framework tarafından otomatik olarak oluşturulur; sadece anlamanız yeterli.
Sık Karşılaşılan İhtiyaçlar:
- Agent kimliği tanımlamak mı istiyorsunuz? → Katman 7'deki IDENTITY.md dosyasını düzenleyin.
- Proje dokümantasyonu eklemek mi istiyorsunuz? → Katman 8'deki bootstrap-extra-files Kancasını kullanın.
- Gerçek zamanlı bağlam eklemek mi istiyorsunuz? → Katman 8'deki before_prompt_build Kancasını kullanın.
- Dosya boyutunu kontrol etmek mi istiyorsunuz? → bootstrapMaxChars yapılandırmasını ayarlayın.
Katman 1: OpenClaw Framework Çekirdeği
Analoji
Bir kullanım kılavuzunun "Kullanım Talimatları" bölümü gibi—LLM'ye kim olduğunuzu, neler yapabileceğinizi ve nasıl yanıt vermeniz gerektiğini söyler.
Bileşenler
Pratik Örnek
"Yaratıcı Ortak" olarak, bir AI içerik oluşturma uzmanı Agent olarak çalışıyorsunuz.
Geçerli Zaman: 2026-03-05 14:37:00 CST
=== Araç Çağırma Spesifikasyonu ===
- XML tarzı araç çağırma formatı kullanın.
- Her araç çağrısı benzersiz bir tool_call_id içermelidir.
- Araç sonuçları <tool_result> etiketleri aracılığıyla döndürülür.
- Araçları yürütürken iptali desteklemek için AbortSignal'i göz önünde bulundurun.
=== Güvenlik Sınırları ===
- Yıkıcı işlemleri (rm -rf, biçimlendirme vb.) yürütmek kesinlikle yasaktır.
- Hassas kullanıcı bilgileri işlenirken şifrelenmelidir.
- Yetkisiz kanallara mesaj göndermek yasaktır.
Tasarım Ödünleşimleri
Neden bu şekilde tasarlandı?
- Ödünleşim: Esneklik ve Tutarlılık
- Karar: Framework katmanında birleşik oluşturma, tüm Agent'lar için tutarlı temel davranış sağlar.
- Faydalar: Kullanıcılar her Agent için temel kuralları tekrarlamak zorunda kalmaz. Framework yükseltildiğinde tüm Agent'lar otomatik olarak yeni yetenekler kazanır. Yapılandırma hataları riskini azaltır.
- Maliyet: Kullanıcılar bu temel kuralları değiştiremez. Özel davranışlar dolaylı olarak Katman 7/8 aracılığıyla uygulanmalıdır.
Katman 2: Araç Tanımları
Analoji
Bir İsviçre çakısının araç listesi gibi—LLM'ye hangi araçlara sahip olduğunuzu, her birinin ne işe yaradığını ve nasıl kullanılacağını söyler.
Bileşenler
Araç Tanımı Örneği
{
"name": "read",
"description": "Dosya içeriğini oku. Metin dosyalarını ve görselleri (jpg/png/gif/webp) destekler. Görseller ek olarak gönderilir. Metin çıktısı 2000 satır veya 50KB ile sınırlıdır.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Dosya yolu (göreceli veya mutlak)"
},
"offset": {
"type": "number",
"description": "Başlangıç satır numarası (1'den başlar)"
},
"limit": {
"type": "number",
"description": "Okunacak maksimum satır sayısı"
}
},
"required": ["path"]
}
}
Tasarım Ödünleşimleri
Neden JSON Schema kullanılıyor?
- Ödünleşim: Esneklik ve Tip Güvenliği
- Karar: Araç parametrelerini tanımlamak için katı JSON Schema kullanın.
- Faydalar: LLM araç kullanımını daha doğru anlar. Framework, çağrı yapmadan önce parametreleri doğrulayabilir. Otomatik olarak dokümantasyon ve tip tanımları oluşturur.
- Maliyet: Yeni araç eklemek için tam bir Schema yazılması gerekir. Tamamen dinamik parametre yapılarını destekleyemez.
Katman 3: Beceri Kaydı
Analoji
Bir restoranın "Özel Menü"sü gibi—LLM'ye hangi profesyonel "tariflerin" çağrılabileceğini söyler.
Tasarım Ödünleşimleri
Neden manuel kayıt yerine dizin taraması kullanılıyor?
- Ödünleşim: Esneklik ve Bakım Maliyeti
- Karar: ~/development/openclaw/skills/ dizinini otomatik olarak tarayın.
- Faydalar: Yeni bir Beceri eklemek için dosyayı dizine yerleştirmek yeterlidir; yapılandırma değişikliği gerekmez. Tüm Agent'lar otomatik olarak yeni Beceriyi alır. Yapılandırma hatası risklerini azaltır.
- Maliyet: Her Agent için hangi Becerilerin kullanılabileceği tam olarak kontrol edilemez. Tüm Beceriler Sistem Prompt'una eklenir (token tüketimini artırır).
Bileşenler
Katman 4: Model Takma Adları
Analoji
"Kısayollar" gibi—karmaşık model yollarına kolay çağrı için kısa takma adlar verir.
Tasarım Ödünleşimleri
Neden model takma adlarına ihtiyaç var?
- Ödünleşim: Esneklik ve Okunabilirlik
- Karar: Kullanıcıların sık kullanılan modeller için kısa takma adlar tanımlamasına izin verin.
- Faydalar: Model çağrılarını basitleştirir (zhipu/glm-5 yerine glm-5). Birden çok Sağlayıcı arasında geçişi destekler (aynı takma ad farklı Sağlayıcılara eşlenebilir). A/B testini ve model geçişini kolaylaştırır.
- Maliyet: Bir takma ad yapılandırma dosyasının bakımını gerektirir. Kafa karışıklığına neden olabilir (aynı takma ad farklı Agent'lar için farklı modellere işaret edebilir).
Bileşenler
Pratik Örnek
Sistem Prompt'unda model takma adları şu şekilde görüntülenir:
Model Takma Adları
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
LLM'ler modelleri değiştirmek için takma adları kullanabilir: /model glm-5
Katman 5: Protokol Spesifikasyonları
Analoji
"Trafik Kuralları" gibi—Agent'ın sistemle etkileşimi için standart protokolleri tanımlar.
Tasarım Ödünleşimleri
Neden protokol spesifikasyonlarına ihtiyaç var?
- Ödünleşim: Özgürlük ve Tutarlılık
- Karar: Standartlaştırılmış etkileşim protokolleri (Sessiz Yanıtlar, Sinyaller, Yanıt Etiketleri vb.) tanımlayın.
- Faydalar: Tüm Agent'larda tutarlı davranış sağlar. Otomatik izleme ve sağlık kontrollerini destekler. Çoklu Agent iş birliğini basitleştirir.
- Maliyet: Agent'ın ifade özgürlüğünü sınırlar. LLM'nin protokollere sıkı sıkıya uymasını gerektirir (göz ardı edilebilir).
Bileşenler
Pratik Örnek
Sessiz Yanıt Örneği:
Kullanıcı: Alındı
Agent: NO_REPLY
Sinyal Örneği:
Sistem: [Heartbeat Poll]
Agent: HEARTBEAT_OK
Yanıt Etiketi Örneği:
Agent: [[reply_to_current]] Görev tamamlandı ✓
Katman 6: Çalışma Zamanı Bilgisi
Analoji
Bir "Gösterge Paneli" gibi—LLM'ye mevcut çalışma ortamının gerçek zamanlı durumunu söyler.
Tasarım Ödünleşimleri
Neden her seferinde çalışma zamanı bilgisi ekleniyor?
- Ödünleşim: Token Tüketimi ve Bağlam Doğruluğu
- Karar: Her istekle birlikte en son çalışma zamanı durumunu ekleyin.
- Faydalar: LLM geçerli zamanı bilir (zaman karışıklığını önler). LLM geçerli modeli bilir (yetenek yanlış değerlendirmesini önler). LLM geçerli ortamı bilir (yol hatalarını önler).
- Maliyet: İstek başına ~2KB token tüketir. Bilgi gereksizlik içerebilir.
Bileşenler
Pratik Örnek
Çalışma Zamanı
Katman 7: Çalışma Alanı Dosyaları ★ Kullanıcı Tarafından Kontrol Edilebilir
Analoji
"Çalışma Notlarınız" gibi—bunlar doğrudan düzenleyebileceğiniz statik yapılandırma dosyalarıdır.
Tasarım Ödünleşimleri
Neden yalnızca bu katman statik olarak düzenlenebilir?
- Ödünleşim: Framework Kararlılığı ve Kullanıcı Özgürlüğü
- Karar: "Değişeni" "değişmeyenden" ayırın; framework katmanı tutarlılığı sağlarken kullanıcı katmanı kişiselleştirmeye izin verir.
- Faydalar: Kullanıcılar Agent kimliğini, iş tanımlarını ve hafızayı tanımlayabilir. Framework yükseltmeleri kullanıcı yapılandırmalarını bozmaz. Yapılandırma dosyaları sürüm kontrolüne alınabilir, yedeklenebilir ve paylaşılabilir.
- Maliyet: Kullanıcılar çekirdek framework davranışını değiştiremez. TELOS framework'ünü ve dosya yapısını öğrenmeyi gerektirir.
Temel Dosyalar
Katman 8: Önyükleme Kanca Sistemi ★ Kullanıcı Tarafından Kontrol Edilebilir
Analoji
"Programlanabilir bir Şırınga" gibi—çalışma zamanında Sistem Prompt'una dinamik olarak içerik eklemek için betikler yazabilirsiniz.
Tasarım Ödünleşimleri
Neden bir Kanca sistemine ihtiyaç var?
- Ödünleşim: Statik Yapılandırmanın Basitliği ve Dinamik Eklemenin Esnekliği
- Karar: Statik Çalışma Alanı Dosyalarının yanında dinamik bir Kanca mekanizması sağlayın.
- Faydalar: Bağlama göre (kanal, gönderen, zaman) eklenen içeriği dinamik olarak ayarlayabilir. Kabuk komutlarını yürütebilir ve çıktıyı ekleyebilir (ör. güncel hava durumu, Git durumu). Harici dosyaları okuyabilir ve ekleyebilir (ör. proje dökümanları, API dökümanları). Koşullu mantığı (if/else) destekler.
- Maliyet: Kanca sistemi sözdizimini ve tetikleme mekanizmalarını öğrenmeyi gerektirir. Kanca betiği hataları Sistem Prompt'unda anormalliklere neden olabilir. Sistem karmaşıklığını artırır.
Dört Kanca Mekanizması
- agent:bootstrap Kancası (Dahili Kanca Sistemi)
Tetikleme Konumu: bootstrap-hooks.ts dosyasındaki applyBootstrapHookOverrides() işlevi
Yetenekler:
- bootstrapFiles dizisi üzerinde tam kontrol.
- Dosya ekleyebilir, silebilir veya değiştirebilir.
- Dosyaları yeniden sıralayabilir.
- Dosya içeriğini değiştirebilir.
Kimler kayıt yaptırabilir:
- OpenClaw eklentileri.
- Çalışma Alanı Kancaları (~/.openclaw/workspace-*/hooks/ dizini).
- Dahili modüller.
Kod Örneği:
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// bootstrapFiles dizisi üzerinde tam kontrol
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "Özel İçerik" }
];
});
- bootstrap-extra-files Kancası (Paketlenmiş Kanca)
Tetikleme Konumu: hooks/bundled/bootstrap-extra-files/ dizinindeki handler.ts
Yetenekler:
- Yalnızca dosya ekler; mevcut dosyaları değiştirmez.
- Ek dosyaları yapılandırma dosyası aracılığıyla belirtir.
Yapılandırma Örneği:
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
Uygulanabilir Senaryolar:
- Projeye özel bağlam dosyalarını eklemeniz gerekiyor.
- Varsayılan 8 Önyükleme dosyasını değiştirmek istemiyorsunuz.
- Ek dokümantasyonu dinamik olarak yüklemeniz gerekiyor.
- before_prompt_build Kancası (Eklenti Kancası)
Tetikleme Konumu: attempt.ts dosyasındaki runBeforePromptBuild() işlevi
Yetenekler:
- Son promptu değiştirir (sistem promptu oluşturulduktan sonra, LLM'ye gönderilmeden önce).
- Bağlam ekleyebilir (prompttan önce içerik ekleyebilir).
- systemPrompt'u geçersiz kılabilir.
Olay Verileri:
{
prompt: string; // Kullanıcı girişi
messages: unknown[]; // Oturum mesaj geçmişi
}
Dönüş Değeri:
{
prependContext?: string; // Prompttan önce eklenen içerik
systemPrompt?: string; // Sistem promptunu geçersiz kılar
}
Uygulanabilir Senaryolar:
- Oturum geçmişine göre promptu dinamik olarak ayarlamanız gerekiyor.
- Gerçek zamanlı bağlam eklemeniz gerekiyor (ör. geçerli zaman, hava durumu).
- Sistem promptunu tamamen değiştirmeniz gerekiyor.
- bootstrapMaxChars / bootstrapTotalMaxChars (Yapılandırma Öğesi)
Tür: Yapılandırma öğesi (kanca değil)
Yetenekler:
- Karakter bütçesini kontrol eder.
- Tek dosya varsayılanı: 20K.
- Toplam varsayılan: 150K.
- Fazlalık, ilk %70 + son %20 alınarak kesilir.
Yapılandırma Konumu:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
Pratik Tavsiyeler
Senaryo 1: Proje dokümantasyonu eklemek istiyorum
Önerilen Çözüm: bootstrap-extra-files
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
Senaryo 2: Görev türüne göre dosyaları dinamik olarak yüklemek istiyorum
Önerilen Çözüm: Özel agent:bootstrap Kancası
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
const sessionKey = context.sessionKey;
// Oturum türüne göre farklı dosyalar yükle
if (sessionKey.includes("coding")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
Senaryo 3: Gerçek zamanlı bağlam eklemek istiyorum (geçerli zaman gibi)
Önerilen Çözüm: before_prompt_build Kancası
on("before_prompt_build", (event, ctx) => {
return {
prependContext: Geçerli Zaman: ${new Date().toISOString()}
};
});
Katman 9: Gelen Bağlam
Analoji
"Gerçek Zamanlı Trafik Bilgisi" gibi—her istekle birlikte geçerli konuşmanın bağlam bilgisini dinamik olarak ekler.
Tasarım Ödünleşimleri
Neden her seferinde bağlam ekleniyor?
- Ödünleşim: Token Tüketimi ve Konuşma Tutarlılığı
- Karar: Her istekle birlikte en son mesaj meta verilerini, gönderen bilgilerini ve konuşma geçmişini ekleyin.
- Faydalar: LLM kimin konuştuğunu bilir (gönderen karışıklığını önler). LLM konuşma geçmişini bilir (bağlam tutarlılığını korur). LLM kendisinden @bahsedilip bahsedilmediğini bilir (yanıt verip vermeyeceğine karar verir).
- Maliyet: İstek başına ~3KB token tüketir. Konuşma geçmişi gürültü içerebilir.
Bileşenler
Tam Sistem Prompt Oluşturma Süreci
Kullanıcı Tarafından Kontrol Edilebilir Katmanların Özeti
OpenClaw, 3 tür kullanıcı tarafından kontrol edilebilir mekanizma sağlar:
- Katman 7 (Çalışma Alanı Dosyaları) - Statik yapılandırma dosyaları. Senaryo: Agent kimliğini, iş tanımlarını, hafızayı tanımlama. Artıları: Basit, sezgisel, kolay sürüm kontrolü. Eksileri: Dinamik olarak ayarlanamaz.
- Katman 8 (Önyükleme Kanca Sistemi) - Dinamik ekleme betikleri. Senaryo: Bağlama göre içerik ekleme, komutları yürütme, harici dosyaları okuma. Artıları: Esnek, güçlü, mantığı ve komutları destekler. Eksileri: Kanca sistemini öğrenmeyi gerektirir; betik hataları sorunlara neden olur.
- Katman 9'un (Gelen Bağlam) Dolaylı Kontrolü - Mesaj göndererek bağlamı etkileme. Senaryo: Sohbet geçmişi veya alıntılanan mesajlar aracılığıyla LLM davranışını etkileme. Artıları: Yapılandırma gerektirmez, doğal etkileşim. Eksileri: Tam olarak kontrol edilemez.
Boyut Karşılaştırma Tablosu
⚠️
Not: Aşağıdaki veriler tahminidir; gerçek boyutlar yapılandırmaya ve çalışma zamanı bağlamına göre değişir. Framework katmanları (Katman 1-6 + 9) teorik olarak aynı olmalıdır ancak araç tanımları, yüklenen Beceriler vb. nedeniyle biraz farklılık gösterebilir.
Notlar:
- Katman 7 ve Katman 8 kullanıcı tarafından kontrol edilebilir; boyutlar Agent yapılandırmasına göre değişir.
- Diğer katmanlar otomatik olarak oluşturulur ve teorik olarak tüm Agent'larda aynıdır.
- Gerçek ölçümler, araç kullanılabilirliği, Beceri yüklemesi ve çalışma zamanı bağlamına bağlı olarak farklılık gösterebilir.
Optimizasyon Önerileri
- Kullanıcı Tarafından Kontrol Edilebilir Kısım Optimizasyonu (Katman 7 + 8)
Katman 7 ve 8 kullanıcı tarafından kontrol edildiğinden, işte optimizasyon stratejileri:
Katman 7 (Statik Dosyalar) Optimizasyonu:
✅ Önerilen Yalın Stratejiler:
- IDENTITY.md: Çekirdek TELOS framework'ünü koruyun, gereksiz açıklamaları kaldırın, paragraflar yerine tablolar kullanın.
- AGENTS.md: Uzun paragraflar yerine kontrol listeleri kullanın, komutları kod bloklarında gösterin, yinelenen kural açıklamalarını kaldırın.
- MEMORY.md: MemOS otomatik dışa aktarımına güvenin; içeriği manuel olarak eklemeyin—sistemin bakımını yapmasına izin verin.
❌ Kaçınılması Gereken Uygulamalar:
- OpenClaw framework'ünün zaten bildiği açıklamaları tekrarlamayın.
- Ayrıntılı Beceri açıklamalarını Çalışma Alanı Dosyalarına kopyalamayın.
- Aşırı retorik veya süsleyici dil kullanmayın.
Katman 8 (Kanca Sistemi) Optimizasyonu:
✅ Önerilen Kullanım Stratejileri:
- Öncelikle bootstrap-extra-files'ı kullanın (basit senaryolar).
- Koşullu mantık gerektiğinde agent:bootstrap kullanın (karmaşık senaryolar).
- Gerçek zamanlı bağlam için before_prompt_build kullanın (dinamik senaryolar).
❌ Kaçınılması Gereken Uygulamalar:
- Kancalarda zaman alan işlemler yürütmeyin (Sistem Promptu oluşturmayı engeller).
- Kancalara çok fazla içerik eklemeyin (token sınırlarını aşar).
- Kancalarda kararsız harici bağımlılıklar kullanmayın (başlatma hatasına neden olur).
- Prompt Budama Stratejisi
Sistem Promptu çok büyükse, şunları göz önünde bulundurun:
Sonuç
OpenClaw'un Sistem Promptu tek bir dosya değil, özenle düzenlenmiş 9 katmanlı bir mimaridir:
- Katman 1-6: Framework tarafından otomatik oluşturulur, tutarlılık ve kararlılık sağlar.
- Katman 7: Kullanıcı tarafından düzenlenebilir statik yapılandırma dosyaları (IDENTITY.md, AGENTS.md vb.).
- Katman 8: Kullanıcı tarafından programlanabilir dinamik ekleme betikleri (Önyükleme Kanca Sistemi).
- Katman 9: Framework tarafından otomatik eklenen gerçek zamanlı bağlam (Gelen Bağlam).
2 kullanıcı tarafından kontrol edilebilir katman vardır (Katman 7 + 8), daha önce yanlışlıkla belirtildiği gibi yalnızca Katman 7 değil.
Bu katmanlar arasındaki farkları ve bağlantıları anlamak, OpenClaw yapılandırmasında ustalaşmanın anahtarıdır.
