chore(i18n): refresh tr translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
41ae35e536
commit
33a137e83f
File diff suppressed because it is too large
Load Diff
@ -1,103 +1,81 @@
|
||||
---
|
||||
read_when:
|
||||
- Sistem istemi metnini, araç listesini veya zaman/heartbeat bölümlerini düzenleme
|
||||
- Çalışma alanı önyükleme işlemini veya Skills ekleme davranışını değiştirme
|
||||
summary: OpenClaw sistem isteminin neler içerdiği ve nasıl bir araya getirildiği
|
||||
- Sistem istemi metnini, araçlar listesini ya da zaman/heartbeat bölümlerini düzenleme
|
||||
- Çalışma alanı önyüklemesini veya Skills ekleme davranışını değiştirme
|
||||
summary: OpenClaw sistem isteminin neler içerdiği ve nasıl oluşturulduğu
|
||||
title: Sistem İstemi
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T08:32:52Z"
|
||||
generated_at: "2026-04-15T19:41:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
|
||||
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Sistem İstemi
|
||||
|
||||
OpenClaw, her agent çalıştırması için özel bir sistem istemi oluşturur. Bu istem **OpenClaw tarafından sahiplenilir** ve pi-coding-agent varsayılan istemini kullanmaz.
|
||||
OpenClaw, her ajan çalıştırması için özel bir sistem istemi oluşturur. Bu istem **OpenClaw tarafından sahiplenilir** ve pi-coding-agent varsayılan istemini kullanmaz.
|
||||
|
||||
İstem, OpenClaw tarafından bir araya getirilir ve her agent çalıştırmasına enjekte edilir.
|
||||
İstem, OpenClaw tarafından oluşturulur ve her ajan çalıştırmasına enjekte edilir.
|
||||
|
||||
Sağlayıcı eklentileri, OpenClaw’a ait tam istemin yerini almadan önbellek farkındalığına sahip istem yönlendirmeleri ekleyebilir. Sağlayıcı çalışma zamanı şunları yapabilir:
|
||||
Sağlayıcı Plugin'leri, tam OpenClaw sahipli istemi değiştirmeden önbellek farkında istem yönlendirmesi sağlayabilir. Sağlayıcı çalışma zamanı şunları yapabilir:
|
||||
|
||||
- adlandırılmış az sayıda çekirdek bölümü değiştirebilir (`interaction_style`,
|
||||
- adlandırılmış az sayıdaki çekirdek bölümü değiştirebilir (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- istem önbelleği sınırının üstüne **kararlı bir önek** enjekte edebilir
|
||||
- istem önbelleği sınırının üzerine **kararlı bir önek** enjekte edebilir
|
||||
- istem önbelleği sınırının altına **dinamik bir sonek** enjekte edebilir
|
||||
|
||||
Model ailesine özgü ayarlar için sağlayıcıya ait katkıları kullanın. Eski
|
||||
`before_prompt_build` istem mutasyonunu uyumluluk veya gerçekten genel istem
|
||||
değişiklikleri için saklayın; normal sağlayıcı davranışı için değil.
|
||||
Model ailesine özgü ayarlamalar için sağlayıcıya ait katkıları kullanın. Eski
|
||||
`before_prompt_build` istem mutasyonunu, normal sağlayıcı davranışı için değil,
|
||||
uyumluluk veya gerçekten genel istem değişiklikleri için koruyun.
|
||||
|
||||
## Yapı
|
||||
|
||||
İstem bilerek kompakt tutulur ve sabit bölümler kullanır:
|
||||
İstem bilinçli olarak kompakt tutulur ve sabit bölümler kullanır:
|
||||
|
||||
- **Araçlar**: yapılandırılmış araçlar için doğruluk kaynağı hatırlatması ve çalışma zamanı araç kullanımı yönlendirmesi.
|
||||
- **Güvenlik**: güç peşinde koşan davranışlardan veya denetimi aşmaktan kaçınmak için kısa koruma hatırlatması.
|
||||
- **Skills** (varsa): modele gerektiğinde skill yönergelerini nasıl yükleyeceğini söyler.
|
||||
- **OpenClaw Self-Update**: yapılandırmayı
|
||||
`config.schema.lookup` ile güvenli biçimde nasıl inceleyeceği, yapılandırmayı `config.patch` ile nasıl yamalayacağı, tam yapılandırmayı
|
||||
`config.apply` ile nasıl değiştireceği ve `update.run` komutunu yalnızca
|
||||
açık kullanıcı isteğiyle nasıl çalıştıracağı. Yalnızca sahip için kullanılabilen `gateway` aracı ayrıca
|
||||
`tools.exec.ask` / `tools.exec.security` yeniden yazmayı da reddeder; buna bu korumalı exec yollarına normalize edilen eski `tools.bash.*`
|
||||
takma adları da dahildir.
|
||||
- **Çalışma Alanı**: çalışma dizini (`agents.defaults.workspace`).
|
||||
- **Belgeler**: OpenClaw belgelerine giden yerel yol (repo veya npm paketi) ve bunların ne zaman okunacağı.
|
||||
- **Çalışma Alanı Dosyaları (enjekte edilir)**: önyükleme dosyalarının aşağıya dahil edildiğini belirtir.
|
||||
- **Korumalı Alan** (etkin olduğunda): korumalı çalışma zamanını, korumalı alan yollarını ve yükseltilmiş exec kullanılabilirliğini belirtir.
|
||||
- **Geçerli Tarih ve Saat**: kullanıcı yerel saati, saat dilimi ve saat biçimi.
|
||||
- **Yanıt Etiketleri**: desteklenen sağlayıcılar için isteğe bağlı yanıt etiketi sözdizimi.
|
||||
- **Heartbeat’ler**: varsayılan agent için heartbeat’ler etkin olduğunda heartbeat istemi ve onay davranışı.
|
||||
- **Çalışma Zamanı**: ana makine, işletim sistemi, node, model, repo kökü (algılandığında), düşünme düzeyi (tek satır).
|
||||
- **Akıl Yürütme**: geçerli görünürlük düzeyi + /reasoning geçiş ipucu.
|
||||
- **Araçlar**: yapılandırılmış araçlar için kaynak gerçeklik hatırlatması ve çalışma zamanı araç kullanımı yönlendirmesi.
|
||||
- **Güvenlik**: güç peşinde koşan davranışlardan veya denetimi atlamaktan kaçınmak için kısa koruma hatırlatması.
|
||||
- **Skills** (mevcut olduğunda): modele, ihtiyaç halinde skill talimatlarını nasıl yükleyeceğini söyler.
|
||||
- **OpenClaw Self-Update**: yapılandırmayı `config.schema.lookup` ile güvenli biçimde nasıl inceleyeceği, yapılandırmayı `config.patch` ile nasıl yamalayacağı, tam yapılandırmayı `config.apply` ile nasıl değiştireceği ve `update.run` komutunu yalnızca kullanıcı açıkça isterse nasıl çalıştıracağı. Yalnızca sahipte kullanılabilen `gateway` aracı ayrıca, korunan exec yollarına normalize edilen eski `tools.bash.*` takma adları dahil olmak üzere `tools.exec.ask` / `tools.exec.security` değerlerini yeniden yazmayı reddeder.
|
||||
- **Workspace**: çalışma dizini (`agents.defaults.workspace`).
|
||||
- **Documentation**: OpenClaw belgelerinin yerel yolu (repo veya npm paketi) ve bunların ne zaman okunacağı.
|
||||
- **Workspace Files (injected)**: önyükleme dosyalarının aşağıda dahil edildiğini belirtir.
|
||||
- **Sandbox** (etkin olduğunda): sandbox'lı çalışma zamanını, sandbox yollarını ve yükseltilmiş exec kullanımının mevcut olup olmadığını belirtir.
|
||||
- **Current Date & Time**: kullanıcı yerel saati, saat dilimi ve saat biçimi.
|
||||
- **Reply Tags**: desteklenen sağlayıcılar için isteğe bağlı yanıt etiketi sözdizimi.
|
||||
- **Heartbeats**: varsayılan ajan için heartbeat etkin olduğunda heartbeat istemi ve onay davranışı.
|
||||
- **Runtime**: host, işletim sistemi, node, model, repo kökü (tespit edildiğinde), düşünme seviyesi (tek satır).
|
||||
- **Reasoning**: geçerli görünürlük seviyesi + `/reasoning` geçiş ipucu.
|
||||
|
||||
Araçlar bölümü ayrıca uzun süren işler için çalışma zamanı yönlendirmeleri de içerir:
|
||||
Araçlar bölümü ayrıca uzun süren işler için çalışma zamanı yönlendirmesi de içerir:
|
||||
|
||||
- gelecekteki takip işlemleri için cron kullanın (`daha sonra tekrar kontrol et`, hatırlatmalar, yinelenen işler);
|
||||
`exec` uyku döngüleri, `yieldMs` gecikme hileleri veya yinelenen `process`
|
||||
yoklaması yerine
|
||||
- `exec` / `process` araçlarını yalnızca şimdi başlayan ve arka planda
|
||||
çalışmayı sürdüren komutlar için kullanın
|
||||
- otomatik tamamlanma uyandırması etkin olduğunda, komutu bir kez başlatın ve
|
||||
çıktı ürettiğinde veya başarısız olduğunda itme tabanlı uyandırma yoluna güvenin
|
||||
- gelecekteki takipler için (`daha sonra tekrar kontrol et`, hatırlatmalar, yinelenen işler) `exec` uyku döngüleri, `yieldMs` gecikme hileleri veya tekrarlanan `process` yoklaması yerine cron kullanın
|
||||
- `exec` / `process` yalnızca şimdi başlayan ve arka planda çalışmaya devam eden komutlar için kullanın
|
||||
- otomatik tamamlanma uyandırması etkinse, komutu bir kez başlatın ve çıktı verdiğinde veya başarısız olduğunda push tabanlı uyandırma yoluna güvenin
|
||||
- çalışan bir komutu incelemeniz gerektiğinde günlükler, durum, girdi veya müdahale için `process` kullanın
|
||||
- görev daha büyükse `sessions_spawn` tercih edin; alt agent tamamlanması
|
||||
itme tabanlıdır ve istekte bulunana otomatik olarak duyurulur
|
||||
- yalnızca tamamlanmayı beklemek için `subagents list` / `sessions_list` araçlarını döngü içinde yoklamayın
|
||||
- görev daha büyükse, `sessions_spawn` tercih edin; alt ajan tamamlanması push tabanlıdır ve istekte bulunana otomatik olarak bildirilir
|
||||
- yalnızca tamamlanmayı beklemek için döngü içinde `subagents list` / `sessions_list` yoklaması yapmayın
|
||||
|
||||
Deneysel `update_plan` aracı etkin olduğunda, Araçlar bölümü modele ayrıca
|
||||
bunu yalnızca önemsiz olmayan çok adımlı işler için kullanmasını, tam olarak bir
|
||||
`in_progress` adımı tutmasını ve her güncellemeden sonra tüm planı
|
||||
tekrarlamaktan kaçınmasını söyler.
|
||||
Deneysel `update_plan` aracı etkin olduğunda, Araçlar bölümü ayrıca modele bunu yalnızca önemsiz olmayan çok adımlı işler için kullanmasını, tam olarak bir `in_progress` adımı tutmasını ve her güncellemeden sonra tüm planı tekrarlamaktan kaçınmasını söyler.
|
||||
|
||||
Sistem istemindeki güvenlik korumaları tavsiye niteliğindedir. Model davranışını yönlendirirler ancak politikayı zorla uygulatmazlar. Kesin uygulama için araç politikası, exec onayları, korumalı alan ve kanal izin listelerini kullanın; operatörler tasarım gereği bunları devre dışı bırakabilir.
|
||||
Sistem istemindeki güvenlik korumaları yönlendiricidir. Model davranışına rehberlik ederler ancak politikayı zorunlu kılmazlar. Sıkı uygulama için araç politikasını, exec onaylarını, sandboxing'i ve kanal izin listelerini kullanın; operatörler bunları tasarım gereği devre dışı bırakabilir.
|
||||
|
||||
Yerel onay kartları/düğmeleri bulunan kanallarda, çalışma zamanı istemi artık
|
||||
agent’e önce bu yerel onay arayüzüne güvenmesini söyler. Yalnızca araç sonucu sohbet içi onayların kullanılamadığını veya
|
||||
tek yolun manuel onay olduğunu belirtiyorsa elle yazılan bir
|
||||
`/approve` komutu eklemelidir.
|
||||
Yerel onay kartları/düğmeleri olan kanallarda, çalışma zamanı istemi artık ajana önce bu yerel onay arayüzüne güvenmesini söyler. Yalnızca araç sonucu sohbet içi onayların kullanılamadığını veya tek yolun manuel onay olduğunu söylediğinde manuel bir `/approve` komutu eklemelidir.
|
||||
|
||||
## İstem modları
|
||||
## İstem kipleri
|
||||
|
||||
OpenClaw, alt agent’ler için daha küçük sistem istemleri oluşturabilir. Çalışma zamanı her çalıştırma için bir
|
||||
`promptMode` ayarlar (kullanıcıya dönük bir yapılandırma değildir):
|
||||
OpenClaw, alt ajanlar için daha küçük sistem istemleri oluşturabilir. Çalışma zamanı her çalıştırma için bir `promptMode` ayarlar (kullanıcıya açık bir yapılandırma değildir):
|
||||
|
||||
- `full` (varsayılan): yukarıdaki tüm bölümleri içerir.
|
||||
- `minimal`: alt agent’ler için kullanılır; **Skills**, **Memory Recall**, **OpenClaw
|
||||
Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
|
||||
**Messaging**, **Silent Replies** ve **Heartbeats** bölümlerini çıkarır. Araçlar, **Güvenlik**,
|
||||
Çalışma Alanı, Korumalı Alan, Geçerli Tarih ve Saat (biliniyorsa), Çalışma Zamanı ve enjekte edilen
|
||||
bağlam kullanılabilir olmaya devam eder.
|
||||
- `minimal`: alt ajanlar için kullanılır; **Skills**, **Memory Recall**, **OpenClaw Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, **Messaging**, **Silent Replies** ve **Heartbeats** bölümlerini çıkarır. Araçlar, **Güvenlik**, Workspace, Sandbox, Current Date & Time (biliniyorsa), Runtime ve enjekte edilen bağlam kullanılabilir olmaya devam eder.
|
||||
- `none`: yalnızca temel kimlik satırını döndürür.
|
||||
|
||||
`promptMode=minimal` olduğunda, ek enjekte edilen istemler **Group Chat Context** yerine **Subagent
|
||||
Context** olarak etiketlenir.
|
||||
`promptMode=minimal` olduğunda, fazladan enjekte edilen istemler **Group Chat Context** yerine **Subagent Context** olarak etiketlenir.
|
||||
|
||||
## Çalışma alanı önyükleme enjeksiyonu
|
||||
## Workspace önyükleme ekleme işlemi
|
||||
|
||||
Önyükleme dosyaları kırpılır ve **Project Context** altında eklenir; böylece model, açık okuma gerektirmeden kimlik ve profil bağlamını görür:
|
||||
Önyükleme dosyaları kırpılır ve **Project Context** altında eklenir; böylece model, açıkça okuma gerektirmeden kimlik ve profil bağlamını görür:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -106,66 +84,51 @@ Context** olarak etiketlenir.
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (yalnızca yepyeni çalışma alanlarında)
|
||||
- varsa `MEMORY.md`, yoksa küçük harfli geri dönüş olarak `memory.md`
|
||||
- varsa `MEMORY.md`, yoksa küçük harfli yedek olarak `memory.md`
|
||||
|
||||
Bu dosyaların tümü, dosyaya özgü bir geçit uygulanmadığı sürece, her turda **bağlam penceresine enjekte edilir**.
|
||||
`HEARTBEAT.md`, normal çalıştırmalarda heartbeat’ler varsayılan agent için devre dışıysa veya
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` false ise
|
||||
çıkarılır. Enjekte edilen dosyaları kısa tutun — özellikle zamanla büyüyebilen ve
|
||||
beklenmedik ölçüde yüksek bağlam kullanımına ve daha sık sıkıştırmaya yol açabilen `MEMORY.md` dosyasını.
|
||||
Bu dosyaların tümü, dosyaya özel bir geçit uygulanmadığı sürece, her turda **bağlam penceresine enjekte edilir**. `HEARTBEAT.md`, varsayılan ajan için heartbeat devre dışıysa veya `agents.defaults.heartbeat.includeSystemPromptSection` false ise normal çalıştırmalarda çıkarılır. Enjekte edilen dosyaları kısa tutun — özellikle zaman içinde büyüyebilen ve beklenmedik derecede yüksek bağlam kullanımına ve daha sık Compaction işlemine yol açabilen `MEMORY.md` dosyasını.
|
||||
|
||||
> **Not:** `memory/*.md` günlük dosyaları, normal önyükleme
|
||||
> Project Context’in parçası **değildir**. Normal turlarda bunlara
|
||||
> `memory_search` ve `memory_get` araçları aracılığıyla ihtiyaç halinde erişilir; bu nedenle model bunları açıkça okumadıkça
|
||||
> bağlam penceresine dahil olmazlar. Salt `/new` ve
|
||||
> `/reset` turları istisnadır: çalışma zamanı, bu ilk tur için
|
||||
> son günlük belleği tek seferlik bir başlangıç bağlamı bloğu olarak öne ekleyebilir.
|
||||
> Project Context parçası **değildir**. Normal turlarda bunlara
|
||||
> `memory_search` ve `memory_get` araçları aracılığıyla ihtiyaç üzerine erişilir; bu nedenle model bunları açıkça okumadıkça
|
||||
> bağlam penceresinden pay almazlar. Çıplak `/new` ve
|
||||
> `/reset` turları istisnadır: çalışma zamanı ilk tur için
|
||||
> yakın tarihli günlük belleği tek seferlik bir başlangıç bağlamı bloğu olarak öne ekleyebilir.
|
||||
|
||||
Büyük dosyalar bir işaretleyiciyle kırpılır. Dosya başına azami boyut
|
||||
`agents.defaults.bootstrapMaxChars` tarafından kontrol edilir (varsayılan: 20000). Dosyalar arasında enjekte edilen toplam önyükleme
|
||||
içeriği `agents.defaults.bootstrapTotalMaxChars`
|
||||
tarafından sınırlandırılır (varsayılan: 150000). Eksik dosyalar kısa bir eksik-dosya işaretleyicisi enjekte eder. Kırpma
|
||||
olduğunda OpenClaw, Project Context içine bir uyarı bloğu enjekte edebilir; bunu
|
||||
Büyük dosyalar bir işaretleyici ile kesilir. Dosya başına maksimum boyut
|
||||
`agents.defaults.bootstrapMaxChars` tarafından kontrol edilir (varsayılan: 20000). Dosyalar genelinde enjekte edilen toplam önyükleme içeriği
|
||||
`agents.defaults.bootstrapTotalMaxChars` ile sınırlandırılır
|
||||
(varsayılan: 150000). Eksik dosyalar kısa bir eksik dosya işaretleyicisi enjekte eder. Kesilme olduğunda, OpenClaw Project Context içinde bir uyarı bloğu enjekte edebilir; bunu
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` ile kontrol edin (`off`, `once`, `always`;
|
||||
varsayılan: `once`).
|
||||
|
||||
Alt agent oturumları yalnızca `AGENTS.md` ve `TOOLS.md` enjekte eder (diğer önyükleme dosyaları
|
||||
alt agent bağlamını küçük tutmak için filtrelenir).
|
||||
Alt ajan oturumları yalnızca `AGENTS.md` ve `TOOLS.md` enjekte eder (alt ajan bağlamını küçük tutmak için diğer önyükleme dosyaları filtrelenir).
|
||||
|
||||
İç hook’lar bu adımı `agent:bootstrap` aracılığıyla durdurup enjekte edilen önyükleme dosyalarını değiştirebilir veya
|
||||
yerine koyabilir (örneğin `SOUL.md` yerine alternatif bir persona kullanmak gibi).
|
||||
Dahili hook'lar bu adımı `agent:bootstrap` üzerinden yakalayarak enjekte edilen önyükleme dosyalarını değiştirebilir veya değiştirilmiş sürümleriyle değiştirebilir (örneğin `SOUL.md` yerine alternatif bir persona kullanmak gibi).
|
||||
|
||||
Agent’in daha az genel duyulmasını istiyorsanız, başlangıç noktası olarak
|
||||
[SOUL.md Personality Guide](/tr/concepts/soul) belgesini kullanın.
|
||||
Ajanın daha az genel duyulmasını istiyorsanız,
|
||||
[SOUL.md Personality Guide](/tr/concepts/soul) ile başlayın.
|
||||
|
||||
Her enjekte edilen dosyanın ne kadar katkı yaptığını incelemek için (ham ve enjekte edilen boyut, kırpma ve araç şeması ek yükü dahil), `/context list` veya `/context detail` kullanın. Bkz. [Context](/tr/concepts/context).
|
||||
Her enjekte edilen dosyanın ne kadar katkıda bulunduğunu (ham ve enjekte edilen, kesilme, ayrıca araç şeması ek yükü) incelemek için `/context list` veya `/context detail` kullanın. Bkz. [Context](/tr/concepts/context).
|
||||
|
||||
## Zaman işleme
|
||||
|
||||
Kullanıcı saat dilimi biliniyorsa sistem istemi özel bir **Geçerli Tarih ve Saat** bölümü içerir.
|
||||
İstem önbelleğini kararlı tutmak için artık yalnızca **saat dilimini** içerir (dinamik saat veya saat biçimi yoktur).
|
||||
Sistem istemi, kullanıcı saat dilimi bilindiğinde özel bir **Current Date & Time** bölümü içerir. İstem önbelleğini kararlı tutmak için artık yalnızca **saat dilimini** içerir (dinamik saat veya saat biçimi yoktur).
|
||||
|
||||
Agent’in geçerli saati bilmesi gerektiğinde `session_status` kullanın; durum kartı
|
||||
bir zaman damgası satırı içerir. Aynı araç isteğe bağlı olarak oturum başına bir model
|
||||
geçersiz kılma da ayarlayabilir (`model=default` bunu temizler).
|
||||
Ajanın geçerli saati bilmesi gerektiğinde `session_status` kullanın; durum kartı bir zaman damgası satırı içerir. Aynı araç isteğe bağlı olarak oturum başına model geçersiz kılma da ayarlayabilir (`model=default` bunu temizler).
|
||||
|
||||
Şunlarla yapılandırın:
|
||||
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
Davranışın tüm ayrıntıları için bkz. [Date & Time](/tr/date-time).
|
||||
Tam davranış ayrıntıları için bkz. [Date & Time](/tr/date-time).
|
||||
|
||||
## Skills
|
||||
|
||||
Uygun skill’ler mevcut olduğunda OpenClaw, her skill için **dosya yolunu** içeren kompakt bir **kullanılabilir skill listesi**
|
||||
(`formatSkillsForPrompt`) enjekte eder. İstem, modele listelenen
|
||||
konumdaki SKILL.md dosyasını yüklemek için `read` kullanmasını söyler (çalışma alanı, yönetilen veya paketlenmiş). Uygun skill yoksa
|
||||
Skills bölümü çıkarılır.
|
||||
Uygun Skills mevcut olduğunda, OpenClaw her skill için **dosya yolunu** içeren kompakt bir **kullanılabilir skills listesi** (`formatSkillsForPrompt`) enjekte eder. İstem, modele listelenen konumdaki SKILL.md dosyasını yüklemek için `read` kullanmasını söyler (workspace, yönetilen veya paketlenmiş). Uygun skill yoksa Skills bölümü çıkarılır.
|
||||
|
||||
Uygunluk; skill meta veri geçitlerini, çalışma zamanı ortamı/yapılandırma kontrollerini
|
||||
ve `agents.defaults.skills` veya
|
||||
`agents.list[].skills` yapılandırıldığında etkin agent skill izin listesini içerir.
|
||||
Uygunluk; skill meta veri geçitlerini, çalışma zamanı ortamı/yapılandırma kontrollerini ve `agents.defaults.skills` veya `agents.list[].skills` yapılandırıldığında etkin ajan skill izin listesini içerir.
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
@ -177,13 +140,20 @@ ve `agents.defaults.skills` veya
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Bu, hedefe yönelik skill kullanımını yine de mümkün kılarken temel istemi küçük tutar.
|
||||
Bu, temel istemi küçük tutarken hedefli skill kullanımını yine de mümkün kılar.
|
||||
|
||||
Skills listesi bütçesi Skills alt sistemi tarafından yönetilir:
|
||||
|
||||
- Genel varsayılan: `skills.limits.maxSkillsPromptChars`
|
||||
- Ajan başına geçersiz kılma: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Genel sınırlı çalışma zamanı alıntıları farklı bir yüzey kullanır:
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
Bu ayrım, Skills boyutlandırmasını `memory_get`, canlı araç sonuçları ve Compaction sonrası AGENTS.md yenilemeleri gibi çalışma zamanı okuma/ekleme boyutlandırmasından ayrı tutar.
|
||||
|
||||
## Belgeler
|
||||
|
||||
Mevcut olduğunda sistem istemi, yerel OpenClaw belgeleri dizinine işaret eden bir **Belgeler** bölümü içerir
|
||||
(repo çalışma alanındaki `docs/` veya paketlenmiş npm
|
||||
paketi belgeleri) ve ayrıca herkese açık yansıyı, kaynak repo’yu, topluluk Discord’unu ve
|
||||
skill keşfi için ClawHub’ı ([https://clawhub.ai](https://clawhub.ai)) belirtir. İstem, modelin OpenClaw davranışı, komutlar, yapılandırma veya mimari için
|
||||
önce yerel belgelere başvurmasını ve mümkün olduğunda
|
||||
`openclaw status` komutunu kendisinin çalıştırmasını söyler (erişimi olmadığında yalnızca kullanıcıya sorar).
|
||||
Mevcut olduğunda, sistem istemi yerel OpenClaw belge dizinine işaret eden bir **Documentation** bölümü içerir (repo çalışma alanındaki `docs/` veya paketlenmiş npm paketi belgeleri) ve ayrıca genel aynayı, kaynak repoyu, topluluk Discord sunucusunu ve Skills keşfi için ClawHub'ı ([https://clawhub.ai](https://clawhub.ai)) belirtir. İstem, modele OpenClaw davranışı, komutlar, yapılandırma veya mimari için önce yerel belgelere başvurmasını ve mümkün olduğunda `openclaw status` komutunu kendisinin çalıştırmasını (erişimi yoksa yalnızca kullanıcıya sormasını) söyler.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,110 +1,88 @@
|
||||
---
|
||||
read_when:
|
||||
- Yeni bir mesajlaşma kanal Plugin'i oluşturuyorsunuz
|
||||
- OpenClaw'ı bir mesajlaşma platformuna bağlamak istiyorsunuz
|
||||
- Yeni bir mesajlaşma kanalı Plugin'i oluşturuyorsunuz
|
||||
- OpenClaw'u bir mesajlaşma platformuna bağlamak istiyorsunuz
|
||||
- ChannelPlugin bağdaştırıcı yüzeyini anlamanız gerekiyor
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: OpenClaw için bir mesajlaşma kanal Plugin'i oluşturma adım adım kılavuzu
|
||||
summary: OpenClaw için bir mesajlaşma kanalı Plugin'i oluşturma adım adım kılavuzu
|
||||
title: Kanal Plugin'leri Oluşturma
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T08:53:15Z"
|
||||
generated_at: "2026-04-15T19:41:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65
|
||||
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Kanal Plugin'leri Oluşturma
|
||||
|
||||
Bu kılavuz, OpenClaw'ı bir mesajlaşma platformuna bağlayan bir kanal plugin'i oluşturma sürecini adım adım açıklar. Sonunda DM güvenliği, eşleme, yanıt iş parçacığı oluşturma ve giden mesajlaşma özelliklerine sahip çalışan bir kanalınız olacak.
|
||||
Bu kılavuz, OpenClaw'u bir mesajlaşma platformuna bağlayan bir kanal plugin'i oluşturma sürecini anlatır. Sonunda DM güvenliği, eşleştirme, yanıt dizileme ve giden mesajlaşma özelliklerine sahip çalışan bir kanalınız olacak.
|
||||
|
||||
<Info>
|
||||
Daha önce hiç OpenClaw plugin'i oluşturmadıysanız, temel paket
|
||||
yapısı ve manifest kurulumu için önce [Başlangıç](/tr/plugins/building-plugins)
|
||||
bölümünü okuyun.
|
||||
Daha önce hiç OpenClaw plugin'i oluşturmadıysanız, temel paket yapısı ve manifest kurulumu için önce [Başlangıç](/tr/plugins/building-plugins) bölümünü okuyun.
|
||||
</Info>
|
||||
|
||||
## Kanal plugin'leri nasıl çalışır
|
||||
|
||||
Kanal plugin'lerinin kendi send/edit/react araçlarına ihtiyacı yoktur. OpenClaw, çekirdekte tek bir paylaşılan `message` aracını tutar. Plugin'iniz şunlardan sorumludur:
|
||||
Kanal plugin'lerinin kendi gönder/düzenle/tepki ver araçlarına ihtiyacı yoktur. OpenClaw, çekirdekte tek bir paylaşılan `message` aracını tutar. Plugin'iniz şunlardan sorumludur:
|
||||
|
||||
- **Config** — hesap çözümleme ve kurulum sihirbazı
|
||||
- **Security** — DM ilkesi ve izin listeleri
|
||||
- **Pairing** — DM onay akışı
|
||||
- **Session grammar** — sağlayıcıya özgü konuşma kimliklerinin temel sohbetlere, iş parçacığı kimliklerine ve üst öğe geri dönüşlerine nasıl eşlendiği
|
||||
- **Outbound** — platforma metin, medya ve anket gönderme
|
||||
- **Threading** — yanıtların nasıl iş parçacığına alındığı
|
||||
- **Yapılandırma** — hesap çözümleme ve kurulum sihirbazı
|
||||
- **Güvenlik** — DM ilkesi ve izin listeleri
|
||||
- **Eşleştirme** — DM onay akışı
|
||||
- **Oturum dil bilgisi** — sağlayıcıya özgü konuşma kimliklerinin temel sohbetlere, iş parçacığı kimliklerine ve üst öğe geri dönüşlerine nasıl eşlendiği
|
||||
- **Giden** — platforma metin, medya ve anket gönderme
|
||||
- **Dizileme** — yanıtların nasıl dizilendiği
|
||||
|
||||
Çekirdek; paylaşılan message aracından, istem bağlamasından, dış oturum-anahtarı biçiminden, genel `:thread:` kayıtlarından ve dağıtımdan sorumludur.
|
||||
Çekirdek; paylaşılan mesaj aracından, istem kablolamasından, dış oturum anahtarı biçiminden, genel `:thread:` kayıtlarından ve dağıtımdan sorumludur.
|
||||
|
||||
Kanalınız medya kaynakları taşıyan message-tool parametreleri ekliyorsa, bu
|
||||
parametre adlarını `describeMessageTool(...).mediaSourceParams` üzerinden açığa çıkarın.
|
||||
Çekirdek bu açık listeyi sandbox yol normalleştirmesi ve giden medya erişim
|
||||
ilkesi için kullanır; böylece plugin'lerin sağlayıcıya özgü avatar,
|
||||
ek veya kapak görseli parametreleri için paylaşılan çekirdekte özel durumlara
|
||||
ihtiyacı olmaz.
|
||||
Tercihen
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }` gibi eylem anahtarlı bir eşleme döndürün; böylece ilgisiz eylemler başka bir eylemin medya argümanlarını devralmaz.
|
||||
Düz bir dizi de, açığa çıkarılan tüm eylemler arasında bilerek paylaşılan
|
||||
parametreler için çalışmaya devam eder.
|
||||
Kanalınız medya kaynakları taşıyan mesaj aracı parametreleri ekliyorsa, bu parametre adlarını `describeMessageTool(...).mediaSourceParams` üzerinden sunun. Çekirdek, bu açık listeyi sandbox yol normalizasyonu ve giden medya erişim ilkesi için kullanır; böylece plugin'lerin sağlayıcıya özgü avatar, ek veya kapak görseli parametreleri için paylaşılan çekirdekte özel durumlara ihtiyacı olmaz.
|
||||
İlgisiz eylemlerin başka bir eylemin medya argümanlarını devralmaması için tercihen
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }`
|
||||
gibi eylem anahtarlı bir eşleme döndürün. Düz bir dizi de, tüm sunulan eylemler arasında kasıtlı olarak paylaşılan parametreler için yine çalışır.
|
||||
|
||||
Platformunuz konuşma kimlikleri içinde ek kapsam depoluyorsa, bu ayrıştırmayı
|
||||
plugin içinde `messaging.resolveSessionConversation(...)` ile tutun. Bu,
|
||||
`rawId` değerini temel konuşma kimliğine, isteğe bağlı iş parçacığı
|
||||
kimliğine, açık `baseConversationId` değerine ve herhangi bir
|
||||
`parentConversationCandidates` değerine eşlemek için kanonik kancadır.
|
||||
Platformunuz konuşma kimlikleri içinde ek kapsam saklıyorsa, bu ayrıştırmayı plugin içinde `messaging.resolveSessionConversation(...)` ile tutun. `rawId` değerini temel konuşma kimliğine, isteğe bağlı iş parçacığı kimliğine, açık `baseConversationId` değerine ve herhangi bir `parentConversationCandidates` değerine eşlemek için kanonik kanca budur.
|
||||
`parentConversationCandidates` döndürdüğünüzde, bunları en dar üst öğeden en geniş/temel konuşmaya doğru sıralı tutun.
|
||||
|
||||
Kanal kayıt defteri başlatılmadan önce aynı ayrıştırmaya ihtiyaç duyan paketli
|
||||
plugin'ler ayrıca eşleşen bir
|
||||
`resolveSessionConversation(...)` dışa aktarımı içeren üst düzey bir `session-key-api.ts`
|
||||
dosyası da sunabilir. Çekirdek bu önyükleme açısından güvenli yüzeyi
|
||||
yalnızca çalışma zamanı plugin kayıt defteri henüz kullanılabilir olmadığında kullanır.
|
||||
Kanal kayıt defteri başlatılmadan önce aynı ayrıştırmaya ihtiyaç duyan paketlenmiş plugin'ler, eşleşen bir `resolveSessionConversation(...)` dışa aktarımı ile üst düzey bir `session-key-api.ts` dosyası da sunabilir. Çekirdek, yalnızca çalışma zamanı plugin kayıt defteri henüz mevcut değilse bu bootstrap için güvenli yüzeyi kullanır.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)`, bir plugin yalnızca
|
||||
genel/raw kimliğin üzerine üst öğe geri dönüşlerine ihtiyaç duyduğunda eski
|
||||
uyumluluk geri dönüşü olarak kullanılmaya devam eder. Her iki kanca da varsa,
|
||||
çekirdek önce
|
||||
`resolveSessionConversation(...).parentConversationCandidates` kullanır ve yalnızca kanonik kanca bunları
|
||||
atlanırsa `resolveParentConversationCandidates(...)` kancasına geri döner.
|
||||
`messaging.resolveParentConversationCandidates(...)`, bir plugin yalnızca genel/raw kimliğin üzerine üst öğe geri dönüşlerine ihtiyaç duyduğunda eski uyumluluk geri dönüşü olarak kullanılmaya devam eder. Her iki kanca da varsa çekirdek önce `resolveSessionConversation(...).parentConversationCandidates` kullanır ve yalnızca kanonik kanca bunları atladığında `resolveParentConversationCandidates(...)` kancasına geri döner.
|
||||
|
||||
## Onaylar ve kanal yetenekleri
|
||||
|
||||
Çoğu kanal plugin'inin onaya özgü koda ihtiyacı yoktur.
|
||||
|
||||
- Çekirdek aynı sohbet içi `/approve`, paylaşılan onay düğmesi payload'ları ve genel geri dönüş teslimatından sorumludur.
|
||||
- Çekirdek; aynı sohbette `/approve`, paylaşılan onay düğmesi payload'ları ve genel geri dönüş teslimatından sorumludur.
|
||||
- Kanal onaya özgü davranış gerektiriyorsa, kanal plugin'inde tek bir `approvalCapability` nesnesini tercih edin.
|
||||
- `ChannelPlugin.approvals` kaldırıldı. Onay teslimatı/yerel işleme/görselleştirme/yetkilendirme bilgilerini `approvalCapability` içine koyun.
|
||||
- `plugin.auth` yalnızca giriş/çıkış içindir; çekirdek artık bu nesneden onay yetkilendirme kancalarını okumaz.
|
||||
- `approvalCapability.authorizeActorAction` ve `approvalCapability.getActionAvailabilityState`, onay yetkilendirmesi için kanonik kancadır.
|
||||
- Aynı sohbet içi onay yetkilendirme kullanılabilirliği için `approvalCapability.getActionAvailabilityState` kullanın.
|
||||
- Kanalınız yerel exec onaylarını açığa çıkarıyorsa, başlatıcı yüzey/yerel istemci durumu aynı sohbet içi onay yetkilendirmesinden farklı olduğunda `approvalCapability.getExecInitiatingSurfaceState` kullanın. Çekirdek bu exec'e özgü kancayı `enabled` ile `disabled` durumlarını ayırt etmek, başlatıcı kanalın yerel exec onaylarını destekleyip desteklemediğine karar vermek ve kanalı yerel istemci geri dönüş yönlendirmesine dahil etmek için kullanır. `createApproverRestrictedNativeApprovalCapability(...)` bunu yaygın durum için doldurur.
|
||||
- `approvalCapability.authorizeActorAction` ve `approvalCapability.getActionAvailabilityState`, onay yetkilendirmesi için kanonik bağlantı yüzeyidir.
|
||||
- Aynı sohbette onay yetkilendirme kullanılabilirliği için `approvalCapability.getActionAvailabilityState` kullanın.
|
||||
- Kanalınız yerel exec onaylarını sunuyorsa, başlatan yüzey/yerel istemci durumu aynı sohbetteki onay yetkilendirmesinden farklı olduğunda `approvalCapability.getExecInitiatingSurfaceState` kullanın. Çekirdek bu exec'e özgü kancayı `enabled` ile `disabled` ayrımını yapmak, başlatan kanalın yerel exec onaylarını destekleyip desteklemediğine karar vermek ve kanalı yerel istemci geri dönüş rehberliğine dahil etmek için kullanır. `createApproverRestrictedNativeApprovalCapability(...)`, yaygın durum için bunu doldurur.
|
||||
- Yinelenen yerel onay istemlerini gizleme veya teslimattan önce yazıyor göstergeleri gönderme gibi kanala özgü payload yaşam döngüsü davranışları için `outbound.shouldSuppressLocalPayloadPrompt` veya `outbound.beforeDeliverPayload` kullanın.
|
||||
- `approvalCapability.delivery` yalnızca yerel onay yönlendirmesi veya geri dönüş bastırma için kullanın.
|
||||
- Kanala ait yerel onay bilgileri için `approvalCapability.nativeRuntime` kullanın. Bunu sıcak kanal giriş noktalarında `createLazyChannelApprovalNativeRuntimeAdapter(...)` ile tembel tutun; bu, çekirdeğin onay yaşam döngüsünü oluşturmaya devam etmesine izin verirken çalışma zamanı modülünüzü gerektiğinde içe aktarabilir.
|
||||
- Kanalın paylaşılan oluşturucu yerine gerçekten özel onay payload'larına ihtiyacı olduğunda yalnızca `approvalCapability.render` kullanın.
|
||||
- Kanal, devre dışı yol yanıtının yerel exec onaylarını etkinleştirmek için gereken tam config ayarlarını açıklamasını istiyorsa `approvalCapability.describeExecApprovalSetup` kullanın. Bu kanca `{ channel, channelLabel, accountId }` alır; adlandırılmış hesap kanalları, üst düzey varsayılanlar yerine `channels.<channel>.accounts.<id>.execApprovals.*` gibi hesap kapsamlı yolları oluşturmalıdır.
|
||||
- Bir kanal mevcut config'den kararlı sahip benzeri DM kimliklerini çıkarabiliyorsa, onaya özgü çekirdek mantığı eklemeden aynı sohbet içi `/approve` erişimini kısıtlamak için `openclaw/plugin-sdk/approval-runtime` içinden `createResolvedApproverActionAuthAdapter` kullanın.
|
||||
- Kanalın yerel onay teslimatına ihtiyacı varsa, kanal kodunu hedef normalizasyonu ile taşıma/sunum bilgilerine odaklı tutun. `openclaw/plugin-sdk/approval-runtime` içinden `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` ve `createApproverRestrictedNativeApprovalCapability` kullanın. Kanala özgü bilgileri `approvalCapability.nativeRuntime` arkasına koyun; tercihen `createChannelApprovalNativeRuntimeAdapter(...)` veya `createLazyChannelApprovalNativeRuntimeAdapter(...)` üzerinden. Böylece çekirdek işleyiciyi oluşturabilir ve istek filtreleme, yönlendirme, tekilleştirme, süre sonu, Gateway aboneliği ve başka yere yönlendirildi bildirimlerini yönetebilir. `nativeRuntime` birkaç küçük parçaya ayrılmıştır:
|
||||
- `availability` — hesabın yapılandırılmış olup olmadığı ve bir isteğin işlenip işlenmemesi gerektiği
|
||||
- `presentation` — paylaşılan onay görünüm modelini beklemede/çözümlendi/süresi doldu yerel payload'larına veya son eylemlere eşleme
|
||||
- `approvalCapability.delivery` değerini yalnızca yerel onay yönlendirmesi veya geri dönüş bastırma için kullanın.
|
||||
- Kanalın sahip olduğu yerel onay bilgileri için `approvalCapability.nativeRuntime` kullanın. Çekirdeğin onay yaşam döngüsünü bir araya getirmesine izin verirken çalışma zamanı modülünüzü isteğe bağlı olarak içe aktarabilen `createLazyChannelApprovalNativeRuntimeAdapter(...)` ile bunu sıcak kanal giriş noktalarında tembel tutun.
|
||||
- `approvalCapability.render` değerini yalnızca bir kanal, paylaşılan işleyici yerine gerçekten özel onay payload'larına ihtiyaç duyduğunda kullanın.
|
||||
- Kanal devre dışı yol yanıtının yerel exec onaylarını etkinleştirmek için gereken tam yapılandırma ayarlarını açıklamasını istiyorsa `approvalCapability.describeExecApprovalSetup` kullanın. Kanca `{ channel, channelLabel, accountId }` alır; adlandırılmış hesap kanalları, üst düzey varsayılanlar yerine `channels.<channel>.accounts.<id>.execApprovals.*` gibi hesap kapsamlı yollar üretmelidir.
|
||||
- Bir kanal mevcut yapılandırmadan kararlı sahip benzeri DM kimliklerini çıkarabiliyorsa, onaya özgü çekirdek mantığı eklemeden aynı sohbette `/approve` kısıtlamak için `openclaw/plugin-sdk/approval-runtime` içinden `createResolvedApproverActionAuthAdapter` kullanın.
|
||||
- Kanalınız yerel onay teslimatına ihtiyaç duyuyorsa, kanal kodunu hedef normalizasyonu ile aktarım/sunum bilgilerine odaklı tutun. `openclaw/plugin-sdk/approval-runtime` içinden `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` ve `createApproverRestrictedNativeApprovalCapability` kullanın. Kanala özgü bilgileri `approvalCapability.nativeRuntime` arkasına koyun; ideal olarak `createChannelApprovalNativeRuntimeAdapter(...)` veya `createLazyChannelApprovalNativeRuntimeAdapter(...)` aracılığıyla. Böylece çekirdek işleyiciyi bir araya getirebilir ve istek filtreleme, yönlendirme, tekilleştirme, süre sonu, Gateway aboneliği ve başka yere yönlendirildi bildirimlerinden sorumlu olabilir. `nativeRuntime` birkaç küçük yüzeye ayrılmıştır:
|
||||
- `availability` — hesabın yapılandırılıp yapılandırılmadığı ve bir isteğin işlenip işlenmemesi gerektiği
|
||||
- `presentation` — paylaşılan onay görünüm modelini bekleyen/çözümlenmiş/süresi dolmuş yerel payload'lara veya son eylemlere eşleme
|
||||
- `transport` — hedefleri hazırlama ve yerel onay mesajlarını gönderme/güncelleme/silme
|
||||
- `interactions` — yerel düğmeler veya tepkiler için isteğe bağlı bind/unbind/clear-action kancaları
|
||||
- `interactions` — yerel düğmeler veya tepkiler için isteğe bağlı bağla/çöz/eylem temizleme kancaları
|
||||
- `observe` — isteğe bağlı teslimat tanılama kancaları
|
||||
- Kanalın istemci, token, Bolt uygulaması veya Webhook alıcısı gibi çalışma zamanına ait nesnelere ihtiyacı varsa, bunları `openclaw/plugin-sdk/channel-runtime-context` üzerinden kaydedin. Genel runtime-context kayıt defteri, çekirdeğin onaya özgü sarmalayıcı yapıştırıcısı eklemeden kanal başlangıç durumundan yetenek odaklı işleyicileri önyüklemesine olanak tanır.
|
||||
- Yalnızca yetenek odaklı kanca henüz yeterince ifade gücüne sahip değilse daha alt düzey `createChannelApprovalHandler` veya `createChannelNativeApprovalRuntime` çözümlerine başvurun.
|
||||
- Yerel onay kanalları, bu yardımcılar üzerinden hem `accountId` hem de `approvalKind` yönlendirmelidir. `accountId`, çok hesaplı onay ilkesini doğru bot hesabı kapsamına taşır; `approvalKind` ise exec ile plugin onayı davranışını çekirdekte sabit kodlu dallanmalar olmadan kanal için kullanılabilir tutar.
|
||||
- Çekirdek artık onay yeniden yönlendirme bildirimlerinden de sorumludur. Kanal plugin'leri, `createChannelNativeApprovalRuntime` içinden kendi "onay DM'lere / başka bir kanala gitti" takip mesajlarını göndermemelidir; bunun yerine paylaşılan onay yeteneği yardımcıları üzerinden doğru origin + approver-DM yönlendirmesini açığa çıkarın ve çekirdek, başlatıcı sohbete herhangi bir bildirim göndermeden önce gerçek teslimatları toplasın.
|
||||
- Teslim edilen onay kimliği türünü uçtan uca koruyun. Yerel istemciler exec ile plugin onayı yönlendirmesini kanal yerel durumundan tahmin etmemeli veya yeniden yazmamalıdır.
|
||||
- Farklı onay türleri bilerek farklı yerel yüzeyler açığa çıkarabilir.
|
||||
Güncel paketli örnekler:
|
||||
- Kanalın istemci, token, Bolt uygulaması veya Webhook alıcısı gibi çalışma zamanına ait nesnelere ihtiyacı varsa, bunları `openclaw/plugin-sdk/channel-runtime-context` üzerinden kaydedin. Genel runtime-context kayıt defteri, çekirdeğin onaya özgü sarmalayıcı yapıştırıcı eklemeden kanal başlatma durumundan yetenek odaklı işleyicileri bootstrap etmesine olanak tanır.
|
||||
- Daha alt düzey `createChannelApprovalHandler` veya `createChannelNativeApprovalRuntime` seçeneklerine yalnızca yetenek odaklı yüzey henüz yeterince ifade edici değilse başvurun.
|
||||
- Yerel onay kanalları bu yardımcılar üzerinden hem `accountId` hem de `approvalKind` yönlendirmelidir. `accountId`, çok hesaplı onay ilkesini doğru bot hesabı kapsamında tutar; `approvalKind` ise çekirdekte sabit kodlanmış dallanmalar olmadan exec ile plugin onay davranışını kanala kullanılabilir halde tutar.
|
||||
- Çekirdek artık onay yeniden yönlendirme bildirimlerinden de sorumludur. Kanal plugin'leri, `createChannelNativeApprovalRuntime` içinden kendi "onay DM'lere / başka bir kanala gitti" takip mesajlarını göndermemelidir; bunun yerine paylaşılan onay yeteneği yardımcıları üzerinden doğru kaynak + onaylayıcı-DM yönlendirmesini sunmalı ve başlatan sohbete herhangi bir bildirim göndermeden önce çekirdeğin gerçek teslimatları toplamasına izin vermelidir.
|
||||
- Teslim edilen onay kimliği türünü uçtan uca koruyun. Yerel istemciler, exec ile plugin onay yönlendirmesini kanal yerel durumundan tahmin etmemeli veya yeniden yazmamalıdır.
|
||||
- Farklı onay türleri kasıtlı olarak farklı yerel yüzeyler sunabilir.
|
||||
Mevcut paketlenmiş örnekler:
|
||||
- Slack, hem exec hem de plugin kimlikleri için yerel onay yönlendirmesini kullanılabilir tutar.
|
||||
- Matrix, yetkilendirmenin onay türüne göre farklılaşmasına izin verirken exec ve plugin onayları için aynı yerel DM/kanal yönlendirmesi ve tepki kullanıcı deneyimini korur.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` uyumluluk sarmalayıcısı olarak hâlâ vardır, ancak yeni kod `capability` oluşturucusunu tercih etmeli ve plugin üzerinde `approvalCapability` açığa çıkarmalıdır.
|
||||
- Matrix, exec ve plugin onayları için aynı yerel DM/kanal yönlendirmesini ve tepki UX'ini korurken, yine de yetkilendirmenin onay türüne göre farklılaşmasına izin verir.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` hâlâ uyumluluk sarmalayıcısı olarak mevcuttur, ancak yeni kod `capability` oluşturucuyu tercih etmeli ve plugin üzerinde `approvalCapability` sunmalıdır.
|
||||
|
||||
Sıcak kanal giriş noktaları için, bu ailenin yalnızca bir parçasına
|
||||
ihtiyacınız olduğunda daha dar runtime alt yollarını tercih edin:
|
||||
Sıcak kanal giriş noktalarında, bu ailenin yalnızca bir parçasına ihtiyacınız olduğunda daha dar çalışma zamanı alt yollarını tercih edin:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -116,101 +94,90 @@ ihtiyacınız olduğunda daha dar runtime alt yollarını tercih edin:
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
- `openclaw/plugin-sdk/channel-runtime-context`
|
||||
|
||||
Benzer şekilde, daha geniş şemsiye
|
||||
yüzeye ihtiyacınız yoksa `openclaw/plugin-sdk/setup-runtime`,
|
||||
Benzer şekilde, daha geniş şemsiye yüzeye ihtiyacınız yoksa `openclaw/plugin-sdk/setup-runtime`,
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
`openclaw/plugin-sdk/reply-runtime`,
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
`openclaw/plugin-sdk/reply-reference` ve
|
||||
`openclaw/plugin-sdk/reply-chunking` yollarını tercih edin.
|
||||
`openclaw/plugin-sdk/reply-chunking`
|
||||
yollarını tercih edin.
|
||||
|
||||
Kurulum için özel olarak:
|
||||
Özellikle kurulum için:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime`, çalışma zamanında güvenli kurulum yardımcılarını kapsar:
|
||||
içe aktarma açısından güvenli kurulum yama bağdaştırıcıları (`createPatchedAccountSetupAdapter`,
|
||||
içe aktarma için güvenli kurulum yama bağdaştırıcıları (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`), lookup-note çıktısı,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` ve devredilmiş
|
||||
`createSetupInputPresenceValidator`), arama notu çıktısı,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` ve temsil edilen
|
||||
setup-proxy oluşturucuları
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime`, `createEnvPatchedAccountSetupAdapter`
|
||||
için dar, ortam farkındalıklı bağdaştırıcı
|
||||
kancasıdır
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime`, `createEnvPatchedAccountSetupAdapter` için dar, ortam farkındalıklı bağdaştırıcı yüzeyidir
|
||||
- `openclaw/plugin-sdk/channel-setup`, isteğe bağlı kurulum oluşturucularını ve birkaç kurulum açısından güvenli ilkel öğeyi kapsar:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
Kanalınız ortam güdümlü kurulum veya yetkilendirme destekliyorsa ve genel başlangıç/config
|
||||
akışlarının çalışma zamanı yüklenmeden önce bu ortam adlarını bilmesi gerekiyorsa,
|
||||
bunları plugin manifest içinde `channelEnvVars` ile bildirin. Kanal çalışma zamanı `envVars`
|
||||
veya yerel sabitlerini yalnızca operatöre dönük metinler için kullanın.
|
||||
Kanalınız ortam değişkeni güdümlü kurulum veya yetkilendirmeyi destekliyorsa ve genel başlatma/yapılandırma akışlarının çalışma zamanı yüklenmeden önce bu ortam adlarını bilmesi gerekiyorsa, bunları plugin manifest'inde `channelEnvVars` ile bildirin. Kanal çalışma zamanı `envVars` değerlerini veya yerel sabitleri yalnızca operatör odaklı kopya için tutun.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` ve
|
||||
`splitSetupEntries`
|
||||
|
||||
- yalnızca daha ağır paylaşılan kurulum/config yardımcılarına da ihtiyaç duyduğunuzda
|
||||
daha geniş `openclaw/plugin-sdk/setup` kancasını kullanın; örneğin
|
||||
- yalnızca daha ağır paylaşılan kurulum/yapılandırma yardımcılarına da ihtiyacınız varsa daha geniş `openclaw/plugin-sdk/setup` yüzeyine başvurun; örneğin
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Kanalınız yalnızca kurulum yüzeylerinde "önce bu plugin'i yükleyin" bilgisini
|
||||
duyurmak istiyorsa, `createOptionalChannelSetupSurface(...)` çözümünü tercih edin. Üretilen
|
||||
bağdaştırıcı/sihirbaz config yazımlarında ve sonlandırmada güvenli biçimde başarısız olur
|
||||
ve doğrulama, sonlandırma ve docs-link
|
||||
metinlerinde aynı yükleme gerekli mesajını yeniden kullanır.
|
||||
Kanalınız yalnızca kurulum yüzeylerinde "önce bu plugin'i yükleyin" bilgisini göstermek istiyorsa, `createOptionalChannelSetupSurface(...)` tercih edin. Üretilen bağdaştırıcı/sihirbaz yapılandırma yazımlarında ve sonlandırmada kapalı varsayılanla başarısız olur ve aynı kurulum gerekli mesajını doğrulama, sonlandırma ve belge bağlantısı metni boyunca yeniden kullanır.
|
||||
|
||||
Diğer sıcak kanal yolları için, daha geniş eski yüzeyler yerine daha dar
|
||||
yardımcıları tercih edin:
|
||||
Diğer sıcak kanal yolları için, daha geniş eski yüzeyler yerine dar yardımcıları tercih edin:
|
||||
|
||||
- çok hesaplı config ve
|
||||
varsayılan hesap geri dönüşü için `openclaw/plugin-sdk/account-core`,
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
`openclaw/plugin-sdk/account-id`,
|
||||
`openclaw/plugin-sdk/account-resolution` ve
|
||||
`openclaw/plugin-sdk/account-helpers`
|
||||
- gelen rota/zarf ve
|
||||
kaydet-ve-dağıt bağlaması için `openclaw/plugin-sdk/inbound-envelope` ve
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch`
|
||||
- hedef ayrıştırma/eşleştirme için `openclaw/plugin-sdk/messaging-targets`
|
||||
- medya yükleme ile giden
|
||||
kimlik/gönderim delegeleri için `openclaw/plugin-sdk/outbound-media` ve
|
||||
`openclaw/plugin-sdk/outbound-runtime`
|
||||
- iş parçacığı bağlama yaşam döngüsü
|
||||
ve bağdaştırıcı kaydı için `openclaw/plugin-sdk/thread-bindings-runtime`
|
||||
- yalnızca eski agent/media
|
||||
payload alan düzeni hâlâ gerekiyorsa `openclaw/plugin-sdk/agent-media-payload`
|
||||
- Telegram özel komut
|
||||
normalizasyonu, yinelenen/çakışan doğrulama ve geri dönüş açısından kararlı komut
|
||||
config sözleşmesi için `openclaw/plugin-sdk/telegram-command-config`
|
||||
`openclaw/plugin-sdk/account-helpers` çok hesaplı yapılandırma ve
|
||||
varsayılan hesap geri dönüşü için
|
||||
- `openclaw/plugin-sdk/inbound-envelope` ve
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` gelen rota/zarf ile
|
||||
kaydet-ve-dağıt kablolaması için
|
||||
- `openclaw/plugin-sdk/messaging-targets` hedef ayrıştırma/eşleştirme için
|
||||
- `openclaw/plugin-sdk/outbound-media` ve
|
||||
`openclaw/plugin-sdk/outbound-runtime` medya yükleme ile giden
|
||||
kimlik/gönderme temsilcileri için
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` iş parçacığı bağlama yaşam döngüsü
|
||||
ve bağdaştırıcı kaydı için
|
||||
- `openclaw/plugin-sdk/agent-media-payload` yalnızca eski bir agent/media
|
||||
payload alan düzeni hâlâ gerekiyorsa
|
||||
- `openclaw/plugin-sdk/telegram-command-config` Telegram özel komut
|
||||
normalizasyonu, yinelenen/çakışan doğrulama ve geri dönüşte kararlı komut
|
||||
yapılandırması sözleşmesi için
|
||||
|
||||
Yalnızca yetkilendirme kullanan kanallar genellikle varsayılan yolda kalabilir: çekirdek onayları yönetir ve plugin yalnızca outbound/auth yeteneklerini açığa çıkarır. Matrix, Slack, Telegram ve özel sohbet taşıma katmanları gibi yerel onay kanalları, kendi onay yaşam döngülerini yazmak yerine paylaşılan yerel yardımcıları kullanmalıdır.
|
||||
Yalnızca yetkilendirme yapan kanallar genellikle varsayılan yolda kalabilir: çekirdek onayları yönetir ve plugin yalnızca giden/yetkilendirme yeteneklerini sunar. Matrix, Slack, Telegram ve özel sohbet taşıma katmanları gibi yerel onay kanalları, kendi onay yaşam döngülerini yazmak yerine paylaşılan yerel yardımcıları kullanmalıdır.
|
||||
|
||||
## Gelen mention ilkesi
|
||||
## Gelen bahsetme ilkesi
|
||||
|
||||
Gelen mention işlemeyi iki katmana bölünmüş tutun:
|
||||
Gelen bahsetme işlemesini iki katmana ayrılmış halde tutun:
|
||||
|
||||
- plugin'e ait kanıt toplama
|
||||
- plugin'in sahip olduğu kanıt toplama
|
||||
- paylaşılan ilke değerlendirmesi
|
||||
|
||||
Paylaşılan katman için `openclaw/plugin-sdk/channel-inbound` kullanın.
|
||||
|
||||
Plugin'e yerel mantık için uygun örnekler:
|
||||
|
||||
- bot'a yanıt algılama
|
||||
- bot alıntısı algılama
|
||||
- bota yanıt tespiti
|
||||
- bottan alıntı tespiti
|
||||
- iş parçacığı katılımı kontrolleri
|
||||
- servis/sistem mesajı hariç tutmaları
|
||||
- bot katılımını kanıtlamak için gereken platforma özgü önbellekler
|
||||
- hizmet/sistem mesajı hariç tutmaları
|
||||
- bot katılımını kanıtlamak için gereken platform yerel önbellekleri
|
||||
|
||||
Paylaşılan yardımcı için uygun örnekler:
|
||||
|
||||
- `requireMention`
|
||||
- açık mention sonucu
|
||||
- örtük mention izin listesi
|
||||
- açık bahsetme sonucu
|
||||
- örtük bahsetme izin listesi
|
||||
- komut baypası
|
||||
- son atlama kararı
|
||||
|
||||
Tercih edilen akış:
|
||||
|
||||
1. Yerel mention bilgilerini hesaplayın.
|
||||
1. Yerel bahsetme bilgilerini hesaplayın.
|
||||
2. Bu bilgileri `resolveInboundMentionDecision({ facts, policy })` içine geçirin.
|
||||
3. Gelen kapınızda `decision.effectiveWasMentioned`, `decision.shouldBypassMention` ve `decision.shouldSkip` değerlerini kullanın.
|
||||
3. Gelen kapısında `decision.effectiveWasMentioned`, `decision.shouldBypassMention` ve `decision.shouldSkip` kullanın.
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -249,8 +216,7 @@ const decision = resolveInboundMentionDecision({
|
||||
if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions`, çalışma zamanı enjeksiyonuna zaten bağımlı olan
|
||||
paketlenmiş kanal plugin'leri için aynı paylaşılan mention yardımcılarını sunar:
|
||||
`api.runtime.channel.mentions`, çalışma zamanı enjeksiyonuna zaten bağımlı olan paketlenmiş kanal plugin'leri için aynı paylaşılan bahsetme yardımcılarını sunar:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -258,19 +224,18 @@ paketlenmiş kanal plugin'leri için aynı paylaşılan mention yardımcıların
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Eski `resolveMentionGating*` yardımcıları,
|
||||
yalnızca uyumluluk dışa aktarımları olarak
|
||||
Eski `resolveMentionGating*` yardımcıları, yalnızca uyumluluk dışa aktarımları olarak
|
||||
`openclaw/plugin-sdk/channel-inbound` üzerinde kalmaya devam eder. Yeni kod
|
||||
`resolveInboundMentionDecision({ facts, policy })` kullanmalıdır.
|
||||
|
||||
## Adım adım örnek
|
||||
## Adım adım
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Paket ve manifest">
|
||||
Standart plugin dosyalarını oluşturun. `package.json` içindeki `channel` alanı
|
||||
Standart plugin dosyalarını oluşturun. `package.json` içindeki `channel` alanı,
|
||||
bunun bir kanal plugin'i olmasını sağlar. Tam paket meta verisi yüzeyi için
|
||||
bkz. [Plugin Kurulumu ve Config](/tr/plugins/sdk-setup#openclaw-channel):
|
||||
[Plugin Kurulumu ve Yapılandırma](/tr/plugins/sdk-setup#openclaw-channel) bölümüne bakın:
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -284,7 +249,7 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
"channel": {
|
||||
"id": "acme-chat",
|
||||
"label": "Acme Chat",
|
||||
"blurb": "OpenClaw'ı Acme Chat'e bağlayın."
|
||||
"blurb": "OpenClaw'u Acme Chat'e bağlayın."
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -320,10 +285,9 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
</Step>
|
||||
|
||||
<Step title="Kanal plugin nesnesini oluşturun">
|
||||
`ChannelPlugin` arayüzü birçok isteğe bağlı bağdaştırıcı yüzeyine sahiptir. En az
|
||||
gereksinimle başlayın — `id` ve `setup` — ve ihtiyaç duydukça bağdaştırıcılar ekleyin.
|
||||
`ChannelPlugin` arayüzünün birçok isteğe bağlı bağdaştırıcı yüzeyi vardır. En az olanla başlayın — `id` ve `setup` — ve ihtiyaç duydukça bağdaştırıcılar ekleyin.
|
||||
|
||||
`src/channel.ts` dosyasını oluşturun:
|
||||
`src/channel.ts` oluşturun:
|
||||
|
||||
```typescript src/channel.ts
|
||||
import {
|
||||
@ -372,7 +336,7 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
},
|
||||
}),
|
||||
|
||||
// DM güvenliği: bota kim mesaj gönderebilir
|
||||
// DM security: who can message the bot
|
||||
security: {
|
||||
dm: {
|
||||
channelKey: "acme-chat",
|
||||
@ -382,21 +346,21 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
},
|
||||
},
|
||||
|
||||
// Eşleme: yeni DM kişileri için onay akışı
|
||||
// Pairing: approval flow for new DM contacts
|
||||
pairing: {
|
||||
text: {
|
||||
idLabel: "Acme Chat kullanıcı adı",
|
||||
message: "Kimliğinizi doğrulamak için bu kodu gönderin:",
|
||||
notify: async ({ target, code }) => {
|
||||
await acmeChatApi.sendDm(target, `Eşleme kodu: ${code}`);
|
||||
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// İş parçacığı oluşturma: yanıtlar nasıl teslim edilir
|
||||
// Threading: how replies are delivered
|
||||
threading: { topLevelReplyToMode: "reply" },
|
||||
|
||||
// Giden: platforma mesaj gönder
|
||||
// Outbound: send messages to the platform
|
||||
outbound: {
|
||||
attachedResults: {
|
||||
sendText: async (params) => {
|
||||
@ -417,24 +381,22 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
```
|
||||
|
||||
<Accordion title="createChatChannelPlugin sizin için ne yapar">
|
||||
Düşük seviyeli bağdaştırıcı arayüzlerini elle uygulamak yerine,
|
||||
bildirime dayalı seçenekler verirsiniz ve oluşturucu bunları birleştirir:
|
||||
Alt düzey bağdaştırıcı arayüzlerini elle uygulamak yerine, bildirimsel seçenekler geçirirsiniz ve oluşturucu bunları birleştirir:
|
||||
|
||||
| Seçenek | Bağladığı şey |
|
||||
| --- | --- |
|
||||
| `security.dm` | Config alanlarından kapsamlı DM güvenlik çözümleyicisi |
|
||||
| `pairing.text` | Kod alışverişiyle metin tabanlı DM eşleme akışı |
|
||||
| `threading` | Reply-to modu çözümleyicisi (sabit, hesap kapsamlı veya özel) |
|
||||
| `outbound.attachedResults` | Sonuç meta verisi döndüren gönderim fonksiyonları (mesaj kimlikleri) |
|
||||
| `security.dm` | Yapılandırma alanlarından kapsamlı DM güvenlik çözümleyicisi |
|
||||
| `pairing.text` | Kod değiş tokuşu ile metin tabanlı DM eşleştirme akışı |
|
||||
| `threading` | Reply-to kip çözümleyicisi (sabit, hesap kapsamlı veya özel) |
|
||||
| `outbound.attachedResults` | Sonuç meta verisi döndüren gönderme işlevleri (mesaj kimlikleri) |
|
||||
|
||||
Tam denetime ihtiyaç duyarsanız bildirime dayalı seçenekler yerine ham
|
||||
bağdaştırıcı nesneleri de geçebilirsiniz.
|
||||
Tam denetime ihtiyacınız varsa bildirimsel seçenekler yerine ham bağdaştırıcı nesneleri de geçirebilirsiniz.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Giriş noktasını bağlayın">
|
||||
`index.ts` dosyasını oluşturun:
|
||||
`index.ts` oluşturun:
|
||||
|
||||
```typescript index.ts
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -469,17 +431,13 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
});
|
||||
```
|
||||
|
||||
Kanalın sahip olduğu CLI tanımlayıcılarını `registerCliMetadata(...)` içine koyun; böylece OpenClaw
|
||||
tam kanal çalışma zamanını etkinleştirmeden bunları kök yardımda gösterebilir,
|
||||
normal tam yüklemeler de gerçek komut kaydı için aynı tanımlayıcıları alır.
|
||||
`registerFull(...)` yöntemini çalışma zamanına özgü işler için kullanın.
|
||||
Kanalın sahip olduğu CLI tanımlayıcılarını `registerCliMetadata(...)` içine koyun; böylece OpenClaw, tam kanal çalışma zamanını etkinleştirmeden bunları kök yardımda gösterebilir. Normal tam yüklemeler de gerçek komut kaydı için aynı tanımlayıcıları almaya devam eder. `registerFull(...)` değerini yalnızca çalışma zamanına özgü işler için tutun.
|
||||
`registerFull(...)` Gateway RPC yöntemleri kaydediyorsa,
|
||||
plugin'e özgü bir önek kullanın. Çekirdek yönetici ad alanları (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) ayrılmıştır ve her zaman
|
||||
`operator.admin` çözümüne gider.
|
||||
`defineChannelPluginEntry`, kayıt modu ayrımını otomatik olarak yönetir. Tüm
|
||||
seçenekler için bkz.
|
||||
[Giriş Noktaları](/tr/plugins/sdk-entrypoints#definechannelpluginentry).
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) ayrılmış kalır ve her zaman
|
||||
`operator.admin` olarak çözülür.
|
||||
`defineChannelPluginEntry`, kayıt kipi ayrımını otomatik olarak işler. Tüm
|
||||
seçenekler için [Giriş Noktaları](/tr/plugins/sdk-entrypoints#definechannelpluginentry) bölümüne bakın.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -493,28 +451,32 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
OpenClaw, kanal devre dışıysa
|
||||
veya yapılandırılmamışsa tam giriş yerine bunu yükler.
|
||||
Bu, kurulum akışları sırasında ağır çalışma zamanı kodunun yüklenmesini önler.
|
||||
Ayrıntılar için bkz. [Kurulum ve Config](/tr/plugins/sdk-setup#setup-entry).
|
||||
OpenClaw, kanal devre dışıyken veya yapılandırılmamışken tam giriş yerine bunu yükler.
|
||||
Bu, kurulum akışları sırasında ağır çalışma zamanı kodunun çekilmesini önler.
|
||||
Ayrıntılar için [Kurulum ve Yapılandırma](/tr/plugins/sdk-setup#setup-entry) bölümüne bakın.
|
||||
|
||||
Kurulum açısından güvenli dışa aktarımları yan modüllere ayıran paketlenmiş çalışma alanı kanalları,
|
||||
açık bir kurulum zamanı runtime setter'a da ihtiyaç duyduklarında
|
||||
`openclaw/plugin-sdk/channel-entry-contract` içinden
|
||||
`defineBundledChannelSetupEntry(...)` kullanabilir.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Gelen mesajları işleyin">
|
||||
Plugin'inizin platformdan mesaj alması ve bunları
|
||||
OpenClaw'a iletmesi gerekir. Tipik desen, isteği doğrulayan
|
||||
ve kanalınızın gelen işleyicisi üzerinden dağıtan bir Webhook'tur:
|
||||
Plugin'inizin platformdan mesaj alması ve bunları OpenClaw'a iletmesi gerekir.
|
||||
Tipik kalıp, isteği doğrulayan ve kanalınızın gelen işleyicisi üzerinden
|
||||
dağıtan bir Webhook'tur:
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
api.registerHttpRoute({
|
||||
path: "/acme-chat/webhook",
|
||||
auth: "plugin", // plugin tarafından yönetilen auth (imzaları kendiniz doğrulayın)
|
||||
auth: "plugin", // plugin tarafından yönetilen yetkilendirme (imzaları kendiniz doğrulayın)
|
||||
handler: async (req, res) => {
|
||||
const event = parseWebhookPayload(req);
|
||||
|
||||
// Gelen işleyiciniz mesajı OpenClaw'a dağıtır.
|
||||
// Tam bağlama platform SDK'nıza bağlıdır —
|
||||
// Kesin kablolama platform SDK'nıza bağlıdır —
|
||||
// gerçek bir örnek için paketlenmiş Microsoft Teams veya Google Chat plugin paketine bakın.
|
||||
await handleAcmeChatInbound(api, event);
|
||||
|
||||
@ -528,23 +490,22 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
|
||||
<Note>
|
||||
Gelen mesaj işleme kanala özgüdür. Her kanal plugin'i
|
||||
kendi gelen işlem hattına sahiptir. Gerçek desenler için paketlenmiş kanal plugin'lerine
|
||||
(örneğin Microsoft Teams veya Google Chat plugin paketi)
|
||||
bakın.
|
||||
kendi gelen işlem hattına sahiptir. Gerçek kalıplar için paketlenmiş kanal plugin'lerine
|
||||
(örneğin Microsoft Teams veya Google Chat plugin paketi) bakın.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Test">
|
||||
`src/channel.test.ts` içinde aynı yerde testler yazın:
|
||||
<Step title="Test edin">
|
||||
Eş konumlu testleri `src/channel.test.ts` içinde yazın:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { acmeChatPlugin } from "./channel.js";
|
||||
|
||||
describe("acme-chat plugin", () => {
|
||||
it("config içinden hesabı çözümler", () => {
|
||||
it("resolves account from config", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
|
||||
@ -554,7 +515,7 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
expect(account.token).toBe("test-token");
|
||||
});
|
||||
|
||||
it("gizli verileri somutlaştırmadan hesabı inceler", () => {
|
||||
it("inspects account without materializing secrets", () => {
|
||||
const cfg = {
|
||||
channels: { "acme-chat": { token: "test-token" } },
|
||||
} as any;
|
||||
@ -563,7 +524,7 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
expect(result.tokenStatus).toBe("available");
|
||||
});
|
||||
|
||||
it("eksik config'i bildirir", () => {
|
||||
it("reports missing config", () => {
|
||||
const cfg = { channels: {} } as any;
|
||||
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
|
||||
expect(result.configured).toBe(false);
|
||||
@ -575,7 +536,7 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Paylaşılan test yardımcıları için bkz. [Test](/tr/plugins/sdk-testing).
|
||||
Paylaşılan test yardımcıları için [Test](/tr/plugins/sdk-testing) bölümüne bakın.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -585,7 +546,7 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # openclaw.channel meta verileri
|
||||
├── openclaw.plugin.json # Config şemalı manifest
|
||||
├── openclaw.plugin.json # Yapılandırma şemalı Manifest
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Genel dışa aktarımlar (isteğe bağlı)
|
||||
@ -600,30 +561,30 @@ yalnızca uyumluluk dışa aktarımları olarak
|
||||
## Gelişmiş konular
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="İş parçacığı seçenekleri" icon="git-branch" href="/tr/plugins/sdk-entrypoints#registration-mode">
|
||||
Sabit, hesap kapsamlı veya özel yanıt modları
|
||||
<Card title="Dizileme seçenekleri" icon="git-branch" href="/tr/plugins/sdk-entrypoints#registration-mode">
|
||||
Sabit, hesap kapsamlı veya özel yanıt kipleri
|
||||
</Card>
|
||||
<Card title="Message tool entegrasyonu" icon="puzzle" href="/tr/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="Mesaj aracı entegrasyonu" icon="puzzle" href="/tr/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool ve eylem keşfi
|
||||
</Card>
|
||||
<Card title="Hedef çözümleme" icon="crosshair" href="/tr/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Çalışma zamanı yardımcıları" icon="settings" href="/tr/plugins/sdk-runtime">
|
||||
api.runtime üzerinden TTS, STT, medya, alt ajan
|
||||
api.runtime üzerinden TTS, STT, medya, alt agent
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Bazı paketlenmiş yardımcı kancalar, paketlenmiş plugin bakımı ve
|
||||
uyumluluk için hâlâ mevcuttur. Bunlar yeni kanal plugin'leri için önerilen desen değildir;
|
||||
o paketlenmiş plugin ailesini doğrudan siz bakımını yapmıyorsanız,
|
||||
Bazı paketlenmiş yardımcı yüzeyleri, paketlenmiş plugin bakımı ve
|
||||
uyumluluk için hâlâ mevcuttur. Bunlar yeni kanal plugin'leri için önerilen
|
||||
kalıp değildir; bu paketlenmiş plugin ailesini doğrudan korumuyorsanız,
|
||||
ortak SDK yüzeyindeki genel channel/setup/reply/runtime alt yollarını tercih edin.
|
||||
</Note>
|
||||
|
||||
## Sonraki adımlar
|
||||
|
||||
- [Provider Plugin'leri](/tr/plugins/sdk-provider-plugins) — plugin'iniz aynı zamanda modeller de sağlıyorsa
|
||||
- [Provider Plugin'leri](/tr/plugins/sdk-provider-plugins) — plugin'iniz ayrıca model de sağlıyorsa
|
||||
- [SDK Genel Bakış](/tr/plugins/sdk-overview) — tam alt yol içe aktarma başvurusu
|
||||
- [SDK Test](/tr/plugins/sdk-testing) — test yardımcıları ve sözleşme testleri
|
||||
- [Plugin Manifesti](/tr/plugins/manifest) — tam manifest şeması
|
||||
- [SDK Test](/tr/plugins/sdk-testing) — test yardımcı araçları ve sözleşme testleri
|
||||
- [Plugin Manifest](/tr/plugins/manifest) — tam manifest şeması
|
||||
|
||||
@ -1,37 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- definePluginEntry veya defineChannelPluginEntry için tam tür imzasına ihtiyaç duyduğunuzda
|
||||
- kayıt modunu anlamak istediğinizde (tam, kurulum veya CLI meta verisi)
|
||||
- giriş noktası seçeneklerine baktığınızda
|
||||
- definePluginEntry veya defineChannelPluginEntry için tam tür imzasına ihtiyacınız var
|
||||
- Kayıt modunu anlamak istiyorsunuz (tam, kurulum veya CLI meta verileri)
|
||||
- Giriş noktası seçeneklerini arıyorsunuz
|
||||
sidebarTitle: Entry Points
|
||||
summary: definePluginEntry, defineChannelPluginEntry ve defineSetupPluginEntry için başvuru
|
||||
summary: definePluginEntry, defineChannelPluginEntry ve defineSetupPluginEntry için referans
|
||||
title: Plugin Giriş Noktaları
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:01:59Z"
|
||||
generated_at: "2026-04-15T19:41:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f
|
||||
source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4
|
||||
source_path: plugins/sdk-entrypoints.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Plugin Giriş Noktaları
|
||||
|
||||
Her plugin varsayılan bir giriş nesnesi dışa aktarır. SDK bunları oluşturmak
|
||||
için üç yardımcı sağlar.
|
||||
Her Plugin varsayılan bir giriş nesnesi dışa aktarır. SDK, bunları oluşturmak için
|
||||
üç yardımcı sağlar.
|
||||
|
||||
<Tip>
|
||||
**Adım adım bir kılavuz mu arıyorsunuz?** Adım adım kılavuzlar için
|
||||
[Channel Plugins](/plugins/sdk-channel-plugins) veya
|
||||
[Provider Plugins](/plugins/sdk-provider-plugins) sayfalarına bakın.
|
||||
**Adım adım bir rehber mi arıyorsunuz?** Adım adım kılavuzlar için [Kanal Pluginleri](/tr/plugins/sdk-channel-plugins)
|
||||
veya [Sağlayıcı Pluginleri](/tr/plugins/sdk-provider-plugins) sayfalarına bakın.
|
||||
</Tip>
|
||||
|
||||
## `definePluginEntry`
|
||||
|
||||
**İçe aktarma:** `openclaw/plugin-sdk/plugin-entry`
|
||||
|
||||
Provider plugin'leri, araç plugin'leri, hook plugin'leri ve mesajlaşma kanalı
|
||||
**olmayan** her şey için.
|
||||
Sağlayıcı pluginleri, araç pluginleri, kanca pluginleri ve bir mesajlaşma
|
||||
kanalı **olmayan** her şey için.
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -60,19 +59,19 @@ export default definePluginEntry({
|
||||
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Hayır | Boş nesne şeması |
|
||||
| `register` | `(api: OpenClawPluginApi) => void` | Evet | — |
|
||||
|
||||
- `id`, `openclaw.plugin.json` manifest dosyanızla eşleşmelidir.
|
||||
- `kind`, ayrıcalıklı slot'lar içindir: `"memory"` veya `"context-engine"`.
|
||||
- `configSchema`, gecikmeli değerlendirme için bir işlev olabilir.
|
||||
- OpenClaw bu şemayı ilk erişimde çözer ve belleğe alır; böylece maliyetli şema
|
||||
- `id`, `openclaw.plugin.json` manifestinizle eşleşmelidir.
|
||||
- `kind`, özel yuvalar içindir: `"memory"` veya `"context-engine"`.
|
||||
- `configSchema`, geç değerlendirme için bir fonksiyon olabilir.
|
||||
- OpenClaw bu şemayı ilk erişimde çözümler ve belleğe alır; böylece maliyetli şema
|
||||
oluşturucular yalnızca bir kez çalışır.
|
||||
|
||||
## `defineChannelPluginEntry`
|
||||
|
||||
**İçe aktarma:** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Kanal-özel bağlamayla `definePluginEntry`'yi sarar. Otomatik olarak
|
||||
`api.registerChannel({ plugin })` çağırır, isteğe bağlı bir kök yardım CLI meta
|
||||
verisi yüzeyi sunar ve `registerFull` işlemini kayıt moduna göre sınırlar.
|
||||
Kanal özelindeki bağlantıları ekleyerek `definePluginEntry` işlevini sarmalar.
|
||||
`api.registerChannel({ plugin })` çağrısını otomatik olarak yapar, isteğe bağlı bir
|
||||
kök yardım CLI meta verisi arayüzü sunar ve `registerFull` çağrısını kayıt moduna göre sınırlar.
|
||||
|
||||
```typescript
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -103,25 +102,25 @@ export default defineChannelPluginEntry({
|
||||
| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Hayır | — |
|
||||
| `registerFull` | `(api: OpenClawPluginApi) => void` | Hayır | — |
|
||||
|
||||
- `setRuntime`, çalışma zamanı başvurusunu saklayabilmeniz için kayıt sırasında
|
||||
çağrılır (genellikle `createPluginRuntimeStore` ile). CLI meta verisi
|
||||
- `setRuntime`, kayıt sırasında çağrılır; böylece çalışma zamanı başvurusunu
|
||||
saklayabilirsiniz (genellikle `createPluginRuntimeStore` aracılığıyla). CLI meta verisi
|
||||
yakalama sırasında atlanır.
|
||||
- `registerCliMetadata`, hem `api.registrationMode === "cli-metadata"`
|
||||
hem de `api.registrationMode === "full"` sırasında çalışır.
|
||||
Bunu, kök yardımın etkinleştirme yapmamasını sağlarken normal CLI komut kaydının
|
||||
tam plugin yüklemeleriyle uyumlu kalması için kanalın sahip olduğu CLI tanımlayıcılarının
|
||||
standart yeri olarak kullanın.
|
||||
- `registerFull`, yalnızca `api.registrationMode === "full"` olduğunda çalışır.
|
||||
Yalnızca kurulum yüklemesi sırasında atlanır.
|
||||
- `definePluginEntry` gibi `configSchema` da gecikmeli bir fabrika olabilir ve
|
||||
OpenClaw çözülen şemayı ilk erişimde belleğe alır.
|
||||
- `registerCliMetadata`, hem `api.registrationMode === "cli-metadata"` hem de
|
||||
`api.registrationMode === "full"` sırasında çalışır.
|
||||
Bunu, kanala ait CLI tanımlayıcıları için kanonik yer olarak kullanın; böylece kök yardım
|
||||
etkinleştirme yapmadan kalır ve normal CLI komut kaydı tam Plugin yüklemeleriyle
|
||||
uyumlu olmaya devam eder.
|
||||
- `registerFull` yalnızca `api.registrationMode === "full"` olduğunda çalışır. Yalnızca kurulum
|
||||
yüklemesi sırasında atlanır.
|
||||
- `definePluginEntry` gibi, `configSchema` da geç bir fabrika olabilir ve OpenClaw
|
||||
çözümlenen şemayı ilk erişimde belleğe alır.
|
||||
- Plugin'e ait kök CLI komutları için, komutun kök CLI ayrıştırma ağacından
|
||||
kaybolmadan gecikmeli yüklenmesini istediğinizde
|
||||
`api.registerCli(..., { descriptors: [...] })` tercih edin. Kanal plugin'leri için
|
||||
bu tanımlayıcıları `registerCliMetadata(...)` içinden kaydetmeyi tercih edin ve
|
||||
`registerFull(...)` işlemini yalnızca çalışma zamanı işlerine odaklı tutun.
|
||||
- `registerFull(...)` ayrıca gateway RPC yöntemleri de kaydediyorsa bunları
|
||||
plugin'e özgü bir önek üzerinde tutun. Ayrılmış çekirdek yönetici ad alanları
|
||||
kaybolmadan geç yüklenmesini istiyorsanız `api.registerCli(..., { descriptors: [...] })`
|
||||
kullanımını tercih edin. Kanal pluginlerinde, bu tanımlayıcıları
|
||||
`registerCliMetadata(...)` içinden kaydetmeyi tercih edin ve `registerFull(...)`
|
||||
işlevini yalnızca çalışma zamanına özgü işlere odaklı tutun.
|
||||
- Eğer `registerFull(...)` aynı zamanda Gateway RPC yöntemlerini de kaydediyorsa,
|
||||
bunları Plugin'e özgü bir önek altında tutun. Ayrılmış çekirdek yönetici ad alanları
|
||||
(`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) her zaman
|
||||
`operator.admin` olarak zorlanır.
|
||||
|
||||
@ -129,7 +128,7 @@ export default defineChannelPluginEntry({
|
||||
|
||||
**İçe aktarma:** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Hafif `setup-entry.ts` dosyası için. Çalışma zamanı veya CLI bağlaması olmadan
|
||||
Hafif `setup-entry.ts` dosyası için. Çalışma zamanı veya CLI bağlantısı olmadan
|
||||
yalnızca `{ plugin }` döndürür.
|
||||
|
||||
```typescript
|
||||
@ -138,37 +137,60 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
OpenClaw bunu, bir kanal devre dışı olduğunda, yapılandırılmadığında veya
|
||||
ertelenmiş yükleme etkin olduğunda tam giriş yerine yükler. Bunun ne zaman önemli
|
||||
olduğu için [Setup and Config](/plugins/sdk-setup#setup-entry) sayfasına bakın.
|
||||
OpenClaw, bir kanal devre dışı olduğunda, yapılandırılmadığında veya ertelenmiş
|
||||
yükleme etkin olduğunda tam giriş yerine bunu yükler. Bunun ne zaman önemli olduğunu
|
||||
öğrenmek için [Kurulum ve Yapılandırma](/tr/plugins/sdk-setup#setup-entry) sayfasına bakın.
|
||||
|
||||
Pratikte `defineSetupPluginEntry(...)` ile dar kurulum yardımcı ailelerini eşleyin:
|
||||
Pratikte, `defineSetupPluginEntry(...)` işlevini dar kapsamlı kurulum yardımcı
|
||||
aileleriyle eşleştirin:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime`:
|
||||
içe aktarma açısından güvenli kurulum yama bağdaştırıcıları, lookup-note çıktısı,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` ve devredilmiş kurulum proxy'leri gibi
|
||||
çalışma zamanı açısından güvenli kurulum yardımcıları için
|
||||
- `openclaw/plugin-sdk/channel-setup`:
|
||||
isteğe bağlı yükleme kurulum yüzeyleri için
|
||||
- `openclaw/plugin-sdk/setup-tools`:
|
||||
kurulum/yükleme CLI/arşiv/belge yardımcıları için
|
||||
- `openclaw/plugin-sdk/setup-runtime`: içe aktarması güvenli kurulum yama bağdaştırıcıları,
|
||||
lookup-note çıktısı, `promptResolvedAllowFrom`, `splitSetupEntries` ve devredilen kurulum
|
||||
proxy'leri gibi çalışma zamanında güvenli kurulum yardımcıları için
|
||||
- `openclaw/plugin-sdk/channel-setup`: isteğe bağlı kurulum yapı yüzeyleri için
|
||||
- `openclaw/plugin-sdk/setup-tools`: kurulum/kurma CLI/arşiv/belgeler yardımcıları için
|
||||
|
||||
Ağır SDK'ları, CLI kaydını ve uzun ömürlü çalışma zamanı hizmetlerini tam
|
||||
girişte tutun.
|
||||
Ağır SDK'ları, CLI kaydını ve uzun ömürlü çalışma zamanı hizmetlerini tam girişte
|
||||
tutun.
|
||||
|
||||
Kurulum ve çalışma zamanı yüzeylerini ayıran paketlenmiş çalışma alanı kanalları,
|
||||
bunun yerine `openclaw/plugin-sdk/channel-entry-contract` içinden
|
||||
`defineBundledChannelSetupEntry(...)` kullanabilir. Bu sözleşme, kurulum girişinin
|
||||
hafif bir çalışma zamanı ayarlayıcısı sunmaya devam ederken kuruluma güvenli
|
||||
Plugin/gizli anahtar dışa aktarımlarını korumasını sağlar:
|
||||
|
||||
```typescript
|
||||
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
|
||||
|
||||
export default defineBundledChannelSetupEntry({
|
||||
importMetaUrl: import.meta.url,
|
||||
plugin: {
|
||||
specifier: "./channel-plugin-api.js",
|
||||
exportName: "myChannelPlugin",
|
||||
},
|
||||
runtime: {
|
||||
specifier: "./runtime-api.js",
|
||||
exportName: "setMyChannelRuntime",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Bu paketlenmiş sözleşmeyi yalnızca kurulum akışlarının, tam kanal girişi yüklenmeden
|
||||
önce gerçekten hafif bir çalışma zamanı ayarlayıcısına ihtiyaç duyduğu durumlarda kullanın.
|
||||
|
||||
## Kayıt modu
|
||||
|
||||
`api.registrationMode`, plugin'inize nasıl yüklendiğini söyler:
|
||||
`api.registrationMode`, Plugininize nasıl yüklendiğini bildirir:
|
||||
|
||||
| Mod | Ne zaman | Ne kaydedilmeli |
|
||||
| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Normal gateway başlangıcı | Her şey |
|
||||
| `"setup-only"` | Devre dışı/yapılandırılmamış kanal | Yalnızca kanal kaydı |
|
||||
| `"setup-runtime"` | Çalışma zamanı mevcut kurulum akışı | Kanal kaydı artı tam giriş yüklenmeden önce gereken yalnızca hafif çalışma zamanı |
|
||||
| `"cli-metadata"` | Kök yardım / CLI meta verisi yakalama | Yalnızca CLI tanımlayıcıları |
|
||||
| Mod | Ne zaman | Ne kaydedilmeli |
|
||||
| ----------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Normal Gateway başlatma | Her şey |
|
||||
| `"setup-only"` | Devre dışı/yapılandırılmamış kanal | Yalnızca kanal kaydı |
|
||||
| `"setup-runtime"` | Çalışma zamanı mevcut kurulum akışı | Kanal kaydı ve tam giriş yüklenmeden önce gereken yalnızca hafif çalışma zamanı |
|
||||
| `"cli-metadata"` | Kök yardım / CLI meta verisi yakalama | Yalnızca CLI tanımlayıcıları |
|
||||
|
||||
`defineChannelPluginEntry` bu ayrımı otomatik olarak yönetir. Bir kanal için
|
||||
doğrudan `definePluginEntry` kullanıyorsanız modu kendiniz denetleyin:
|
||||
`defineChannelPluginEntry` bu ayrımı otomatik olarak yönetir. Bir kanal için doğrudan
|
||||
`definePluginEntry` kullanırsanız, modu kendiniz denetleyin:
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -180,43 +202,43 @@ register(api) {
|
||||
api.registerChannel({ plugin: myPlugin });
|
||||
if (api.registrationMode !== "full") return;
|
||||
|
||||
// Yalnızca çalışma zamanına ait ağır kayıtlar
|
||||
// Yalnızca çalışma zamanına özgü ağır kayıtlar
|
||||
api.registerService(/* ... */);
|
||||
}
|
||||
```
|
||||
|
||||
`"setup-runtime"` durumunu, tam paketlenmiş kanal çalışma zamanına yeniden
|
||||
girmeden yalnızca kurulum başlangıç yüzeylerinin var olması gereken pencere
|
||||
olarak değerlendirin. Uygun örnekler arasında kanal kaydı, kurulum açısından güvenli
|
||||
HTTP rotaları, kurulum açısından güvenli gateway yöntemleri ve devredilmiş
|
||||
kurulum yardımcıları bulunur. Ağır arka plan hizmetleri, CLI kaydedicileri ve
|
||||
provider/client SDK önyüklemeleri yine `"full"` moduna aittir.
|
||||
`"setup-runtime"` modunu, yalnızca kurulum başlangıç yüzeylerinin tam paketlenmiş kanal
|
||||
çalışma zamanına yeniden girmeden var olması gereken pencere olarak değerlendirin.
|
||||
Buna uygun örnekler arasında kanal kaydı, kuruluma güvenli HTTP rotaları, kuruluma
|
||||
güvenli Gateway yöntemleri ve devredilen kurulum yardımcıları bulunur. Ağır arka plan
|
||||
hizmetleri, CLI kaydedicileri ve sağlayıcı/istemci SDK önyüklemeleri ise yine `"full"`
|
||||
moduna aittir.
|
||||
|
||||
Özellikle CLI kaydedicileri için:
|
||||
|
||||
- Kaydedici bir veya daha fazla kök komutun sahibiyse ve OpenClaw'un ilk çağrıda
|
||||
gerçek CLI modülünü gecikmeli yüklemesini istiyorsanız `descriptors` kullanın
|
||||
- Bu tanımlayıcıların, kaydedici tarafından açığa çıkarılan her üst düzey komut
|
||||
kökünü kapsadığından emin olun
|
||||
- Açgözlü uyumluluk yolları için yalnızca `commands` kullanın
|
||||
- Kaydedici bir veya daha fazla kök komuta sahipse ve gerçek CLI modülünün ilk çağrıda
|
||||
OpenClaw tarafından geç yüklenmesini istiyorsanız `descriptors` kullanın
|
||||
- Bu tanımlayıcıların, kaydedici tarafından açığa çıkarılan her üst düzey komut kökünü
|
||||
kapsadığından emin olun
|
||||
- Yalnızca hevesli uyumluluk yolları için tek başına `commands` kullanın
|
||||
|
||||
## Plugin şekilleri
|
||||
## Plugin biçimleri
|
||||
|
||||
OpenClaw, yüklü plugin'leri kayıt davranışlarına göre sınıflandırır:
|
||||
OpenClaw, yüklenen pluginleri kayıt davranışlarına göre sınıflandırır:
|
||||
|
||||
| Şekil | Açıklama |
|
||||
| -------------------- | ----------------------------------------------------- |
|
||||
| **plain-capability** | Tek yetenek türü (ör. yalnızca provider) |
|
||||
| **hybrid-capability**| Birden çok yetenek türü (ör. provider + speech) |
|
||||
| **hook-only** | Yetenek yok, yalnızca hook'lar |
|
||||
| **non-capability** | Araçlar/komutlar/hizmetler var ama yetenek yok |
|
||||
| Biçim | Açıklama |
|
||||
| -------------------- | -------------------------------------------------- |
|
||||
| **plain-capability** | Tek bir yetenek türü (ör. yalnızca sağlayıcı) |
|
||||
| **hybrid-capability** | Birden fazla yetenek türü (ör. sağlayıcı + konuşma) |
|
||||
| **hook-only** | Yalnızca kancalar, yetenek yok |
|
||||
| **non-capability** | Araçlar/komutlar/hizmetler var ama yetenek yok |
|
||||
|
||||
Bir plugin'in şeklini görmek için `openclaw plugins inspect <id>` kullanın.
|
||||
Bir Pluginin biçimini görmek için `openclaw plugins inspect <id>` kullanın.
|
||||
|
||||
## İlgili
|
||||
|
||||
- [SDK Genel Bakış](/plugins/sdk-overview) — kayıt API'si ve alt yol başvurusu
|
||||
- [Çalışma Zamanı Yardımcıları](/plugins/sdk-runtime) — `api.runtime` ve `createPluginRuntimeStore`
|
||||
- [Kurulum ve Yapılandırma](/plugins/sdk-setup) — manifest, kurulum girişi, ertelenmiş yükleme
|
||||
- [Channel Plugins](/plugins/sdk-channel-plugins) — `ChannelPlugin` nesnesini oluşturma
|
||||
- [Provider Plugins](/plugins/sdk-provider-plugins) — provider kaydı ve hook'lar
|
||||
- [SDK Genel Bakış](/tr/plugins/sdk-overview) — kayıt API'si ve alt yol referansı
|
||||
- [Çalışma Zamanı Yardımcıları](/tr/plugins/sdk-runtime) — `api.runtime` ve `createPluginRuntimeStore`
|
||||
- [Kurulum ve Yapılandırma](/tr/plugins/sdk-setup) — manifest, kurulum girişi, ertelenmiş yükleme
|
||||
- [Kanal Pluginleri](/tr/plugins/sdk-channel-plugins) — `ChannelPlugin` nesnesini oluşturma
|
||||
- [Sağlayıcı Pluginleri](/tr/plugins/sdk-provider-plugins) — sağlayıcı kaydı ve kancalar
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Bir eklentiden çekirdek yardımcıları çağırmanız gerekiyor (TTS, STT, görüntü üretimi, web araması, alt aracı)
|
||||
- '`api.runtime`’ın neleri kullanıma sunduğunu anlamak istiyorsunuz'
|
||||
- Bir eklentiden çekirdek yardımcıları çağırmanız gerekir (TTS, STT, görüntü oluşturma, web araması, alt aracı)
|
||||
- '`api.runtime`''ın neleri sunduğunu anlamak istiyorsunuz'
|
||||
- Eklenti kodundan yapılandırma, aracı veya medya yardımcılarına erişiyorsunuz
|
||||
sidebarTitle: Runtime Helpers
|
||||
summary: api.runtime -- eklentiler için kullanılabilir enjekte edilmiş çalışma zamanı yardımcıları
|
||||
title: Eklenti Çalışma Zamanı Yardımcıları
|
||||
summary: api.runtime -- eklentiler için kullanılabilir olan enjekte edilmiş çalışma zamanı yardımcıları
|
||||
title: Plugin Çalışma Zamanı Yardımcıları
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:46Z"
|
||||
generated_at: "2026-04-15T19:41:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be
|
||||
source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Eklenti Çalışma Zamanı Yardımcıları
|
||||
# Plugin Çalışma Zamanı Yardımcıları
|
||||
|
||||
Kayıt sırasında her eklentiye enjekte edilen `api.runtime` nesnesi için başvuru.
|
||||
Ana bilgisayar iç bileşenlerini doğrudan içe aktarmak yerine bu yardımcıları kullanın.
|
||||
Doğrudan ana makine iç bileşenlerini içe aktarmak yerine bu yardımcıları kullanın.
|
||||
|
||||
<Tip>
|
||||
**Adım adım bir rehber mi arıyorsunuz?** Bu yardımcıların bağlam içinde nasıl
|
||||
kullanıldığını gösteren yönergeli kılavuzlar için [Channel Plugins](/tr/plugins/sdk-channel-plugins)
|
||||
veya [Provider Plugins](/tr/plugins/sdk-provider-plugins) bölümlerine bakın.
|
||||
**Adım adım bir rehber mi arıyorsunuz?** Bu yardımcıları bağlam içinde
|
||||
gösteren adım adım kılavuzlar için [Kanal Eklentileri](/tr/plugins/sdk-channel-plugins)
|
||||
veya [Sağlayıcı Eklentileri](/tr/plugins/sdk-provider-plugins) sayfalarına bakın.
|
||||
</Tip>
|
||||
|
||||
```typescript
|
||||
@ -48,7 +48,7 @@ const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
|
||||
// Aracı kimliğini al
|
||||
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
|
||||
|
||||
// Varsayılan düşünme seviyesini al
|
||||
// Varsayılan düşünme düzeyini al
|
||||
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
|
||||
|
||||
// Aracı zaman aşımını al
|
||||
@ -57,7 +57,7 @@ const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
|
||||
// Çalışma alanının var olduğundan emin ol
|
||||
await api.runtime.agent.ensureAgentWorkspace(cfg);
|
||||
|
||||
// Gömülü bir aracı dönüşü çalıştır
|
||||
// Gömülü bir aracı turu çalıştır
|
||||
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
|
||||
const result = await api.runtime.agent.runEmbeddedAgent({
|
||||
sessionId: "my-plugin:task-1",
|
||||
@ -69,13 +69,13 @@ const result = await api.runtime.agent.runEmbeddedAgent({
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)`, eklenti kodundan normal bir OpenClaw
|
||||
aracı dönüşü başlatmak için nötr yardımcıdır. Kanal tetiklemeli yanıtlarla aynı
|
||||
sağlayıcı/model çözümlemesini ve aracı harness seçimini kullanır.
|
||||
`runEmbeddedAgent(...)`, eklenti kodundan normal bir OpenClaw aracı turu
|
||||
başlatmak için tarafsız yardımcıdır. Kanal tarafından tetiklenen yanıtlarla aynı
|
||||
sağlayıcı/model çözümlemesini ve aracı koşum takımı seçimini kullanır.
|
||||
|
||||
`runEmbeddedPiAgent(...)` uyumluluk takma adı olarak kalır.
|
||||
`runEmbeddedPiAgent(...)`, uyumluluk takma adı olarak kalmaktadır.
|
||||
|
||||
**Oturum deposu yardımcıları** `api.runtime.agent.session` altında bulunur:
|
||||
**Oturum deposu yardımcıları** `api.runtime.agent.session` altındadır:
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -124,21 +124,23 @@ await api.runtime.subagent.deleteSession({
|
||||
|
||||
<Warning>
|
||||
Model geçersiz kılmaları (`provider`/`model`), yapılandırmada
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true` ile operatör onayı gerektirir.
|
||||
Güvenilmeyen eklentiler yine de alt aracı çalıştırabilir, ancak geçersiz kılma istekleri reddedilir.
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true` aracılığıyla
|
||||
operatör onayı gerektirir. Güvenilmeyen eklentiler yine de alt aracılar
|
||||
çalıştırabilir, ancak geçersiz kılma istekleri reddedilir.
|
||||
</Warning>
|
||||
|
||||
### `api.runtime.taskFlow`
|
||||
|
||||
Bir Task Flow çalışma zamanını mevcut bir OpenClaw oturum anahtarına veya güvenilir araç
|
||||
bağlamına bağlayın, ardından her çağrıda sahip bilgisi geçmeden Task Flow'lar oluşturup yönetin.
|
||||
Bir TaskFlow çalışma zamanını mevcut bir OpenClaw oturum anahtarına veya güvenilir
|
||||
araç bağlamına bağlayın, ardından her çağrıda sahip bilgisi geçmeden TaskFlow'lar
|
||||
oluşturun ve yönetin.
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
|
||||
|
||||
const created = taskFlow.createManaged({
|
||||
controllerId: "my-plugin/review-batch",
|
||||
goal: "Yeni pull request'leri incele",
|
||||
goal: "Yeni çekme isteklerini incele",
|
||||
});
|
||||
|
||||
const child = taskFlow.runTask({
|
||||
@ -159,11 +161,12 @@ const waiting = taskFlow.setWaiting({
|
||||
```
|
||||
|
||||
Kendi bağlama katmanınızdan zaten güvenilir bir OpenClaw oturum anahtarınız varsa
|
||||
`bindSession({ sessionKey, requesterOrigin })` kullanın. Ham kullanıcı girdisinden bağlama yapmayın.
|
||||
`bindSession({ sessionKey, requesterOrigin })` kullanın. Ham kullanıcı girdisinden
|
||||
bağlama yapmayın.
|
||||
|
||||
### `api.runtime.tts`
|
||||
|
||||
Metinden sese sentezi.
|
||||
Metinden konuşma sentezi.
|
||||
|
||||
```typescript
|
||||
// Standart TTS
|
||||
@ -172,7 +175,7 @@ const clip = await api.runtime.tts.textToSpeech({
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
// Telefoni için optimize edilmiş TTS
|
||||
// Telefon için optimize edilmiş TTS
|
||||
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
|
||||
text: "OpenClaw'dan merhaba",
|
||||
cfg: api.config,
|
||||
@ -186,14 +189,14 @@ const voices = await api.runtime.tts.listVoices({
|
||||
```
|
||||
|
||||
Çekirdek `messages.tts` yapılandırmasını ve sağlayıcı seçimini kullanır. PCM ses
|
||||
tamponu + örnekleme hızı döndürür.
|
||||
arabelleği + örnekleme oranı döndürür.
|
||||
|
||||
### `api.runtime.mediaUnderstanding`
|
||||
|
||||
Görüntü, ses ve video analizi.
|
||||
|
||||
```typescript
|
||||
// Bir görseli tanımla
|
||||
// Bir görüntüyü tanımla
|
||||
const image = await api.runtime.mediaUnderstanding.describeImageFile({
|
||||
filePath: "/tmp/inbound-photo.jpg",
|
||||
cfg: api.config,
|
||||
@ -204,7 +207,7 @@ const image = await api.runtime.mediaUnderstanding.describeImageFile({
|
||||
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
|
||||
filePath: "/tmp/inbound-audio.ogg",
|
||||
cfg: api.config,
|
||||
mime: "audio/ogg", // MIME çıkarılamadığında isteğe bağlı
|
||||
mime: "audio/ogg", // MIME çıkarılamadığında isteğe bağlıdır
|
||||
});
|
||||
|
||||
// Bir videoyu tanımla
|
||||
@ -224,12 +227,13 @@ const result = await api.runtime.mediaUnderstanding.runFile({
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)`, uyumluluk takma adı olarak
|
||||
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` için varlığını sürdürür.
|
||||
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` için kullanılmaya
|
||||
devam etmektedir.
|
||||
</Info>
|
||||
|
||||
### `api.runtime.imageGeneration`
|
||||
|
||||
Görüntü üretimi.
|
||||
Görüntü oluşturma.
|
||||
|
||||
```typescript
|
||||
const result = await api.runtime.imageGeneration.generate({
|
||||
@ -255,7 +259,7 @@ const result = await api.runtime.webSearch.search({
|
||||
|
||||
### `api.runtime.media`
|
||||
|
||||
Düşük seviyeli medya yardımcı programları.
|
||||
Düşük düzey medya yardımcı programları.
|
||||
|
||||
```typescript
|
||||
const webMedia = await api.runtime.media.loadWebMedia(url);
|
||||
@ -310,7 +314,7 @@ const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" },
|
||||
|
||||
### `api.runtime.modelAuth`
|
||||
|
||||
Model ve sağlayıcı auth çözümlemesi.
|
||||
Model ve sağlayıcı kimlik doğrulama çözümlemesi.
|
||||
|
||||
```typescript
|
||||
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
|
||||
@ -322,7 +326,7 @@ const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
|
||||
|
||||
### `api.runtime.state`
|
||||
|
||||
Durum dizini çözümleme.
|
||||
Durum dizini çözümlemesi.
|
||||
|
||||
```typescript
|
||||
const stateDir = api.runtime.state.resolveStateDir();
|
||||
@ -342,8 +346,8 @@ api.runtime.tools.registerMemoryCli(/* ... */);
|
||||
|
||||
Kanala özgü çalışma zamanı yardımcıları (bir kanal eklentisi yüklendiğinde kullanılabilir).
|
||||
|
||||
`api.runtime.channel.mentions`, çalışma zamanı enjeksiyonu kullanan
|
||||
paketli kanal eklentileri için paylaşılan gelen bahsetme ilkesi yüzeyidir:
|
||||
`api.runtime.channel.mentions`, çalışma zamanı enjeksiyonu kullanan paketli kanal
|
||||
eklentileri için paylaşılan gelen mention ilkesi yüzeyidir:
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -370,7 +374,7 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
|
||||
});
|
||||
```
|
||||
|
||||
Kullanılabilir bahsetme yardımcıları:
|
||||
Kullanılabilir mention yardımcıları:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -379,24 +383,27 @@ Kullanılabilir bahsetme yardımcıları:
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions`, eski
|
||||
`resolveMentionGating*` uyumluluk yardımcılarını bilerek açığa çıkarmaz. Normalize edilmiş
|
||||
`{ facts, policy }` yolunu tercih edin.
|
||||
`resolveMentionGating*` uyumluluk yardımcılarını kasıtlı olarak açığa çıkarmaz.
|
||||
Normalize edilmiş `{ facts, policy }` yolunu tercih edin.
|
||||
|
||||
## Çalışma zamanı referanslarını saklama
|
||||
## Çalışma zamanı başvurularını saklama
|
||||
|
||||
`register` geri çağrısının dışında kullanmak için çalışma zamanı referansını saklamak üzere
|
||||
`createPluginRuntimeStore` kullanın:
|
||||
`register` geri çağrısı dışında kullanılmak üzere çalışma zamanı başvurusunu
|
||||
saklamak için `createPluginRuntimeStore` kullanın:
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
|
||||
const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");
|
||||
const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
pluginId: "my-plugin",
|
||||
errorMessage: "my-plugin runtime başlatılmadı",
|
||||
});
|
||||
|
||||
// Giriş noktanızda
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
name: "Eklentim",
|
||||
name: "My Plugin",
|
||||
description: "Örnek",
|
||||
plugin: myPlugin,
|
||||
setRuntime: store.setRuntime,
|
||||
@ -412,22 +419,26 @@ export function tryGetRuntime() {
|
||||
}
|
||||
```
|
||||
|
||||
Çalışma zamanı deposu kimliği için `pluginId` tercih edin. Daha düşük düzeyli
|
||||
`key` biçimi, bir eklentinin kasıtlı olarak birden fazla çalışma zamanı yuvasına
|
||||
ihtiyaç duyduğu alışılmadık durumlar içindir.
|
||||
|
||||
## Diğer üst düzey `api` alanları
|
||||
|
||||
`api.runtime` dışında API nesnesi ayrıca şunları da sağlar:
|
||||
`api.runtime` ötesinde, API nesnesi ayrıca şunları da sağlar:
|
||||
|
||||
| Alan | Tür | Açıklama |
|
||||
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Eklenti kimliği |
|
||||
| `api.name` | `string` | Eklenti görünen adı |
|
||||
| Alan | Tür | Açıklama |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Plugin kimliği |
|
||||
| `api.name` | `string` | Plugin görüntüleme adı |
|
||||
| `api.config` | `OpenClawConfig` | Geçerli yapılandırma anlık görüntüsü (varsa etkin bellek içi çalışma zamanı anlık görüntüsü) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | `plugins.entries.<id>.config` içinden eklentiye özgü yapılandırma |
|
||||
| `api.logger` | `PluginLogger` | Kapsamlı günlükleyici (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Geçerli yükleme modu; `"setup-runtime"` tam giriş öncesi hafif başlatma/kurulum penceresidir |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Eklenti köküne göre bir yolu çözümle |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | `plugins.entries.<id>.config` içinden eklentiye özgü yapılandırma |
|
||||
| `api.logger` | `PluginLogger` | Kapsamlı günlükleyici (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Geçerli yükleme modu; `"setup-runtime"` hafif tam giriş öncesi başlatma/kurulum penceresidir |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Eklenti köküne göre bir yolu çözümle |
|
||||
|
||||
## İlgili
|
||||
|
||||
- [SDK Overview](/tr/plugins/sdk-overview) -- alt yol başvurusu
|
||||
- [SDK Entry Points](/tr/plugins/sdk-entrypoints) -- `definePluginEntry` seçenekleri
|
||||
- [Plugin Internals](/tr/plugins/architecture) -- yetenek modeli ve kayıt defteri
|
||||
- [SDK Genel Bakış](/tr/plugins/sdk-overview) -- alt yol başvurusu
|
||||
- [SDK Giriş Noktaları](/tr/plugins/sdk-entrypoints) -- `definePluginEntry` seçenekleri
|
||||
- [Plugin İç Bileşenleri](/tr/plugins/architecture) -- yetenek modeli ve kayıt defteri
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Bir plugin'e kurulum sihirbazı ekliyorsunuz
|
||||
- setup-entry.ts ile index.ts arasındaki farkı anlamanız gerekiyor
|
||||
- Plugin yapılandırma şemalarını veya package.json içindeki openclaw meta verilerini tanımlıyorsunuz
|
||||
- Bir Plugin'e kurulum sihirbazı ekliyorsunuz
|
||||
- '`setup-entry.ts` ile `index.ts` arasındaki farkı anlamanız gerekir'
|
||||
- Plugin yapılandırma şemalarını veya `package.json` içindeki `openclaw` meta verilerini tanımlıyorsunuz
|
||||
sidebarTitle: Setup and Config
|
||||
summary: Kurulum sihirbazları, setup-entry.ts, yapılandırma şemaları ve package.json meta verileri
|
||||
title: Plugin Kurulumu ve Yapılandırması
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:11:07Z"
|
||||
generated_at: "2026-04-15T19:41:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9
|
||||
source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b
|
||||
source_path: plugins/sdk-setup.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,18 +18,18 @@ x-i18n:
|
||||
# Plugin Kurulumu ve Yapılandırması
|
||||
|
||||
Plugin paketleme (`package.json` meta verileri), manifestler
|
||||
(`openclaw.plugin.json`), kurulum girişleri ve yapılandırma şemaları için başvuru.
|
||||
(`openclaw.plugin.json`), kurulum girişleri ve yapılandırma şemaları için
|
||||
başvuru.
|
||||
|
||||
<Tip>
|
||||
**Adım adım bir kılavuz mu arıyorsunuz?** Nasıl yapılır kılavuzları paketlemeyi bağlam içinde ele alır:
|
||||
**Adım adım bir rehber mi arıyorsunuz?** Nasıl yapılır rehberleri paketlemeyi bağlam içinde ele alır:
|
||||
[Kanal Plugin'leri](/tr/plugins/sdk-channel-plugins#step-1-package-and-manifest) ve
|
||||
[Sağlayıcı Plugin'leri](/tr/plugins/sdk-provider-plugins#step-1-package-and-manifest).
|
||||
</Tip>
|
||||
|
||||
## Paket meta verileri
|
||||
|
||||
`package.json` dosyanızda, plugin sistemine
|
||||
plugin'inizin ne sağladığını söyleyen bir `openclaw` alanı bulunmalıdır:
|
||||
`package.json` dosyanızda, plugin sistemine plugin'inizin ne sağladığını söyleyen bir `openclaw` alanı bulunmalıdır:
|
||||
|
||||
**Kanal plugin'i:**
|
||||
|
||||
@ -50,7 +50,7 @@ plugin'inizin ne sağladığını söyleyen bir `openclaw` alanı bulunmalıdır
|
||||
}
|
||||
```
|
||||
|
||||
**Sağlayıcı plugin'i / ClawHub yayımlama temeli:**
|
||||
**Sağlayıcı plugin'i / ClawHub yayımlama tabanı:**
|
||||
|
||||
```json openclaw-clawhub-package.json
|
||||
{
|
||||
@ -79,39 +79,39 @@ alanları zorunludur. Kanonik yayımlama parçacıkları
|
||||
|
||||
| Alan | Tür | Açıklama |
|
||||
| ------------ | ---------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `extensions` | `string[]` | Giriş noktası dosyaları (paket kök dizinine göre göreli) |
|
||||
| `setupEntry` | `string` | Hafif, yalnızca kurulum için giriş (isteğe bağlı) |
|
||||
| `extensions` | `string[]` | Giriş noktası dosyaları (paket kök dizinine göre) |
|
||||
| `setupEntry` | `string` | Yalnızca kurulum için hafif giriş (isteğe bağlı) |
|
||||
| `channel` | `object` | Kurulum, seçici, hızlı başlangıç ve durum yüzeyleri için kanal katalog meta verileri |
|
||||
| `providers` | `string[]` | Bu plugin tarafından kaydedilen sağlayıcı kimlikleri |
|
||||
| `install` | `object` | Kurulum ipuçları: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` |
|
||||
| `startup` | `object` | Başlangıç davranışı bayrakları |
|
||||
| `startup` | `object` | Başlatma davranışı bayrakları |
|
||||
|
||||
### `openclaw.channel`
|
||||
|
||||
`openclaw.channel`, çalışma zamanı yüklenmeden önce kanal keşfi ve kurulum
|
||||
yüzeyleri için düşük maliyetli paket meta verileridir.
|
||||
yüzeyleri için düşük maliyetli paket meta verisidir.
|
||||
|
||||
| Alan | Tür | Anlamı |
|
||||
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
|
||||
| `id` | `string` | Kanonik kanal kimliği. |
|
||||
| `label` | `string` | Birincil kanal etiketi. |
|
||||
| `selectionLabel` | `string` | `label` değerinden farklı olması gerektiğinde seçici/kurulum etiketi. |
|
||||
| `detailLabel` | `string` | Daha zengin kanal katalogları ve durum yüzeyleri için ikincil ayrıntı etiketi.|
|
||||
| `detailLabel` | `string` | Daha zengin kanal katalogları ve durum yüzeyleri için ikincil ayrıntı etiketi. |
|
||||
| `docsPath` | `string` | Kurulum ve seçim bağlantıları için belge yolu. |
|
||||
| `docsLabel` | `string` | Kanal kimliğinden farklı olması gerektiğinde belgeler bağlantısı için geçersiz kılma etiketi. |
|
||||
| `docsLabel` | `string` | Kanal kimliğinden farklı olması gerektiğinde belge bağlantıları için kullanılan geçersiz kılma etiketi. |
|
||||
| `blurb` | `string` | Kısa onboarding/katalog açıklaması. |
|
||||
| `order` | `number` | Kanal kataloglarındaki sıralama düzeni. |
|
||||
| `aliases` | `string[]` | Kanal seçimi için ek arama diğer adları. |
|
||||
| `preferOver` | `string[]` | Bu kanalın geride bırakması gereken daha düşük öncelikli plugin/kanal kimlikleri. |
|
||||
| `systemImage` | `string` | Kanal UI katalogları için isteğe bağlı simge/sistem görseli adı. |
|
||||
| `preferOver` | `string[]` | Bu kanalın daha üstte yer alması gereken daha düşük öncelikli plugin/kanal kimlikleri. |
|
||||
| `systemImage` | `string` | Kanal UI katalogları için isteğe bağlı simge/system-image adı. |
|
||||
| `selectionDocsPrefix` | `string` | Seçim yüzeylerinde belge bağlantılarından önce gelen önek metin. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Seçim metninde etiketli belge bağlantısı yerine belge yolunu doğrudan gösterir. |
|
||||
| `selectionExtras` | `string[]` | Seçim metnine eklenen ek kısa dizeler. |
|
||||
| `markdownCapable` | `boolean` | Giden biçimlendirme kararları için kanalı markdown uyumlu olarak işaretler. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Seçim metninde etiketli bir belge bağlantısı yerine belge yolunu doğrudan gösterir. |
|
||||
| `selectionExtras` | `string[]` | Seçim metnine eklenen kısa ek dizeler. |
|
||||
| `markdownCapable` | `boolean` | Giden biçimlendirme kararları için kanalı markdown destekli olarak işaretler. |
|
||||
| `exposure` | `object` | Kurulum, yapılandırılmış listeler ve belge yüzeyleri için kanal görünürlük denetimleri. |
|
||||
| `quickstartAllowFrom` | `boolean` | Bu kanalı standart hızlı başlangıç `allowFrom` kurulum akışına dahil eder. |
|
||||
| `forceAccountBinding` | `boolean` | Yalnızca bir hesap olsa bile açık hesap bağlamasını zorunlu kılar. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Bu kanal için duyuru hedeflerini çözerken oturum aramasını tercih eder. |
|
||||
| `forceAccountBinding` | `boolean` | Yalnızca bir hesap olsa bile açık hesap bağlamayı zorunlu kılar. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Duyuru hedeflerini çözümlerken bu kanal için oturum aramasını tercih eder. |
|
||||
|
||||
Örnek:
|
||||
|
||||
@ -145,11 +145,11 @@ yüzeyleri için düşük maliyetli paket meta verileridir.
|
||||
|
||||
`exposure` şunları destekler:
|
||||
|
||||
- `configured`: kanalı yapılandırılmış/durum benzeri listeleme yüzeylerine dahil et
|
||||
- `setup`: kanalı etkileşimli kurulum/yapılandırma seçicilerine dahil et
|
||||
- `docs`: kanalı belge/gezinme yüzeylerinde herkese açık olarak işaretle
|
||||
- `configured`: kanalı yapılandırılmış/durum tarzı listeleme yüzeylerine dahil eder
|
||||
- `setup`: kanalı etkileşimli kurulum/yapılandırma seçicilerine dahil eder
|
||||
- `docs`: kanalı belge/gezinme yüzeylerinde herkese açık olarak işaretler
|
||||
|
||||
`showConfigured` ve `showInSetup` eski diğer adlar olarak desteklenmeye devam eder. Tercihen
|
||||
`showConfigured` ve `showInSetup` eski takma adlar olarak desteklenmeye devam eder. Tercihen
|
||||
`exposure` kullanın.
|
||||
|
||||
### `openclaw.install`
|
||||
@ -159,23 +159,23 @@ yüzeyleri için düşük maliyetli paket meta verileridir.
|
||||
| Alan | Tür | Anlamı |
|
||||
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
|
||||
| `npmSpec` | `string` | Kurulum/güncelleme akışları için kanonik npm belirtimi. |
|
||||
| `localPath` | `string` | Yerel geliştirme veya paketli kurulum yolu. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Her ikisi de mevcutsa tercih edilen kurulum kaynağı. |
|
||||
| `minHostVersion` | `string` | `>=x.y.z` biçiminde desteklenen en düşük OpenClaw sürümü. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Paketli plugin yeniden kurulum akışlarının belirli eski yapılandırma hatalarından kurtulmasını sağlar. |
|
||||
| `localPath` | `string` | Yerel geliştirme veya paketlenmiş kurulum yolu. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Her ikisi de mevcut olduğunda tercih edilen kurulum kaynağı. |
|
||||
| `minHostVersion` | `string` | `>=x.y.z` biçimindeki minimum desteklenen OpenClaw sürümü. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Paketlenmiş plugin yeniden kurulum akışlarının belirli eski yapılandırma hatalarından kurtulmasına izin verir. |
|
||||
|
||||
`minHostVersion` ayarlanmışsa hem kurulum hem de manifest-kayıt defteri yükleme bunu
|
||||
uygular. Eski ana bilgisayarlar plugin'i atlar; geçersiz sürüm dizeleri reddedilir.
|
||||
`minHostVersion` ayarlanmışsa, hem kurulum hem de manifest-kayıt yükleme bunu
|
||||
zorunlu kılar. Daha eski host'lar plugin'i atlar; geçersiz sürüm dizeleri reddedilir.
|
||||
|
||||
`allowInvalidConfigRecovery`, bozuk yapılandırmalar için genel bir baypas değildir. Bu
|
||||
yalnızca dar kapsamlı paketli plugin kurtarma içindir; böylece yeniden kurulum/kurulum,
|
||||
eksik paketli plugin yolu veya aynı plugin için eski `channels.<id>`
|
||||
girdisi gibi bilinen yükseltme kalıntılarını onarabilir. Yapılandırma
|
||||
ilgisiz nedenlerle bozuksa kurulum yine kapalı güvenli şekilde başarısız olur ve operatöre `openclaw doctor --fix` çalıştırmasını söyler.
|
||||
`allowInvalidConfigRecovery`, bozuk yapılandırmalar için genel bir atlama yolu değildir. Bu,
|
||||
yalnızca dar kapsamlı paketlenmiş plugin kurtarma içindir; böylece yeniden kurulum/kurulum,
|
||||
eksik paketlenmiş plugin yolu veya aynı plugin için eski `channels.<id>`
|
||||
girdisi gibi bilinen yükseltme kalıntılarını onarabilir. Yapılandırma ilgisiz nedenlerle bozuksa, kurulum
|
||||
yine kapalı şekilde başarısız olur ve operatöre `openclaw doctor --fix` çalıştırmasını söyler.
|
||||
|
||||
### Ertelenmiş tam yükleme
|
||||
|
||||
Kanal plugin'leri şu şekilde ertelenmiş yüklemeyi seçebilir:
|
||||
Kanal plugin'leri şu şekilde ertelenmiş yüklemeyi tercih edebilir:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -189,25 +189,21 @@ Kanal plugin'leri şu şekilde ertelenmiş yüklemeyi seçebilir:
|
||||
}
|
||||
```
|
||||
|
||||
Etkinleştirildiğinde OpenClaw, ön dinleme başlangıç
|
||||
aşamasında, önceden yapılandırılmış kanallar için bile yalnızca `setupEntry` yükler. Tam giriş, gateway dinlemeye başladıktan sonra yüklenir.
|
||||
Etkinleştirildiğinde, OpenClaw ön-dinleme başlatma aşamasında, daha önce yapılandırılmış kanallar için bile yalnızca `setupEntry` yükler. Tam giriş, Gateway dinlemeye başladıktan sonra yüklenir.
|
||||
|
||||
<Warning>
|
||||
Ertelenmiş yüklemeyi yalnızca `setupEntry` dosyanız gateway'in
|
||||
dinlemeye başlamadan önce ihtiyaç duyduğu her şeyi kaydediyorsa etkinleştirin
|
||||
(kanal kaydı, HTTP yolları, gateway yöntemleri). Tam giriş gerekli başlangıç yeteneklerine sahipse
|
||||
varsayılan davranışı koruyun.
|
||||
Ertelenmiş yüklemeyi yalnızca `setupEntry` dosyanız, Gateway dinlemeye başlamadan önce ihtiyaç duyduğu her şeyi kaydediyorsa etkinleştirin (kanal kaydı, HTTP rotaları, Gateway yöntemleri). Tam giriş gerekli başlatma yeteneklerine sahipse, varsayılan davranışı koruyun.
|
||||
</Warning>
|
||||
|
||||
Kurulum/tam girişiniz gateway RPC yöntemleri kaydediyorsa bunları
|
||||
plugin'e özgü bir önek altında tutun. Ayrılmış çekirdek yönetici ad alanları (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) çekirdeğe ait kalır ve her zaman
|
||||
`operator.admin` değerine çözülür.
|
||||
Kurulum/tam girişiniz Gateway RPC yöntemleri kaydediyorsa, bunları
|
||||
plugin'e özgü bir önekte tutun. Ayrılmış çekirdek yönetici ad alanları (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) çekirdeğe aittir ve her zaman
|
||||
`operator.admin` olarak çözülür.
|
||||
|
||||
## Plugin manifesti
|
||||
|
||||
Her yerel plugin paket kök dizininde bir `openclaw.plugin.json` dosyası taşımalıdır.
|
||||
OpenClaw bunu, plugin kodunu yürütmeden yapılandırmayı doğrulamak için kullanır.
|
||||
Her yerel plugin, paket kök dizininde bir `openclaw.plugin.json` ile gelmelidir.
|
||||
OpenClaw bunu, plugin kodunu çalıştırmadan yapılandırmayı doğrulamak için kullanır.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -242,7 +238,7 @@ Kanal plugin'leri için `kind` ve `channels` ekleyin:
|
||||
}
|
||||
```
|
||||
|
||||
Yapılandırması olmayan plugin'ler bile bir şema taşımalıdır. Boş bir şema geçerlidir:
|
||||
Yapılandırması olmayan plugin'ler bile bir şema ile gelmelidir. Boş bir şema geçerlidir:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -254,25 +250,25 @@ Yapılandırması olmayan plugin'ler bile bir şema taşımalıdır. Boş bir ş
|
||||
}
|
||||
```
|
||||
|
||||
Tam şema başvurusu için bkz. [Plugin Manifest](/tr/plugins/manifest).
|
||||
Tam şema başvurusu için bkz. [Plugin Manifesti](/tr/plugins/manifest).
|
||||
|
||||
## ClawHub'da yayımlama
|
||||
## ClawHub yayımlama
|
||||
|
||||
Plugin paketleri için pakete özel ClawHub komutunu kullanın:
|
||||
Plugin paketleri için pakete özgü ClawHub komutunu kullanın:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
Eski yalnızca-skill yayımlama diğer adı skill'ler içindir. Plugin paketleri
|
||||
Eski, yalnızca Skills için yayımlama takma adı Skills içindir. Plugin paketleri
|
||||
her zaman `clawhub package publish` kullanmalıdır.
|
||||
|
||||
## Kurulum girişi
|
||||
|
||||
`setup-entry.ts` dosyası, OpenClaw'ın yalnızca kurulum yüzeylerine ihtiyaç duyduğunda yüklediği
|
||||
(index.ts'ye göre) hafif bir alternatiftir (onboarding, yapılandırma onarımı,
|
||||
devre dışı kanal incelemesi).
|
||||
`setup-entry.ts` dosyası, OpenClaw'un yalnızca kurulum yüzeylerine ihtiyaç duyduğunda yüklediği
|
||||
(onboarding, yapılandırma onarımı,
|
||||
devre dışı kanal incelemesi) `index.ts` için hafif bir alternatiftir.
|
||||
|
||||
```typescript
|
||||
// setup-entry.ts
|
||||
@ -282,70 +278,76 @@ import { myChannelPlugin } from "./src/channel.js";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
Bu, kurulum akışları sırasında ağır çalışma zamanı kodlarının (kripto kitaplıkları, CLI kayıtları,
|
||||
arka plan servisleri) yüklenmesini önler.
|
||||
Bu, kurulum akışları sırasında ağır çalışma zamanı kodunun (kriptografi kütüphaneleri, CLI kayıtları,
|
||||
arka plan hizmetleri) yüklenmesini önler.
|
||||
|
||||
**OpenClaw'ın tam giriş yerine `setupEntry` kullandığı durumlar:**
|
||||
Kuruluma güvenli dışa aktarımları yardımcı modüllerde tutan paketlenmiş çalışma alanı kanalları,
|
||||
`defineSetupPluginEntry(...)` yerine
|
||||
`openclaw/plugin-sdk/channel-entry-contract` içinden `defineBundledChannelSetupEntry(...)`
|
||||
kullanabilir. Bu paketlenmiş sözleşme ayrıca isteğe bağlı bir
|
||||
`runtime` dışa aktarımını da destekler; böylece kurulum zamanındaki çalışma zamanı bağlantıları hafif ve açık kalabilir.
|
||||
|
||||
**OpenClaw'un tam giriş yerine `setupEntry` kullandığı durumlar:**
|
||||
|
||||
- Kanal devre dışıdır ancak kurulum/onboarding yüzeylerine ihtiyaç duyar
|
||||
- Kanal etkindir ancak yapılandırılmamıştır
|
||||
- Ertelenmiş yükleme etkindir (`deferConfiguredChannelFullLoadUntilAfterListen`)
|
||||
|
||||
**`setupEntry` tarafından kaydedilmesi gerekenler:**
|
||||
**`setupEntry` dosyasının kaydetmesi gerekenler:**
|
||||
|
||||
- Kanal plugin nesnesi (`defineSetupPluginEntry` aracılığıyla)
|
||||
- Gateway dinlemesinden önce gerekli olan tüm HTTP yolları
|
||||
- Başlangıç sırasında gereken tüm gateway yöntemleri
|
||||
- Gateway dinlemeye başlamadan önce gerekli tüm HTTP rotaları
|
||||
- Başlatma sırasında gereken tüm Gateway yöntemleri
|
||||
|
||||
Bu başlangıç gateway yöntemleri yine de `config.*` veya `update.*`
|
||||
gibi ayrılmış çekirdek yönetici ad alanlarından kaçınmalıdır.
|
||||
Bu başlatma Gateway yöntemleri yine de `config.*` veya `update.*` gibi ayrılmış çekirdek yönetici
|
||||
ad alanlarından kaçınmalıdır.
|
||||
|
||||
**`setupEntry` içinde OLMAMASI gerekenler:**
|
||||
|
||||
- CLI kayıtları
|
||||
- Arka plan servisleri
|
||||
- Ağır çalışma zamanı içe aktarımları (kripto, SDK'lar)
|
||||
- Yalnızca başlangıç sonrası gereken gateway yöntemleri
|
||||
- Arka plan hizmetleri
|
||||
- Ağır çalışma zamanı içe aktarımları (kriptografi, SDK'ler)
|
||||
- Yalnızca başlatmadan sonra gereken Gateway yöntemleri
|
||||
|
||||
### Dar kurulum yardımcı içe aktarımları
|
||||
|
||||
Sıcak yalnızca-kurulum yolları için, kurulum yüzeyinin yalnızca bir bölümüne ihtiyaç duyduğunuzda
|
||||
daha geniş `plugin-sdk/setup` şemsiyesi yerine dar kurulum yardımcı bağlantı yüzeylerini tercih edin:
|
||||
Yalnızca kurulum için kullanılan sıcak yollar için, kurulum yüzeyinin yalnızca bir bölümüne ihtiyacınız olduğunda daha geniş
|
||||
`plugin-sdk/setup` şemsiyesi yerine dar kurulum yardımcı dikişlerini tercih edin:
|
||||
|
||||
| İçe aktarma yolu | Şunun için kullanın | Temel dışa aktarımlar |
|
||||
| --------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | `setupEntry` / ertelenmiş kanal başlangıcında kullanılabilir kalan kurulum zamanı çalışma zamanı yardımcıları | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | ortam farkındalıklı hesap kurulum bağdaştırıcıları | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | kurulum/yükleme CLI/arşiv/belge yardımcıları | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| İçe aktarma yolu | Kullanım amacı | Temel dışa aktarımlar |
|
||||
| ----------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | `setupEntry` / ertelenmiş kanal başlatmasında kullanılabilir kalan kurulum zamanı çalışma zamanı yardımcıları | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | ortama duyarlı hesap kurulum bağdaştırıcıları | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | kurulum/yükleme CLI/arşiv/belge yardımcıları | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
|
||||
Yapılandırma yama yardımcıları gibi tam paylaşılan kurulum
|
||||
araç kutusunu istediğinizde daha geniş `plugin-sdk/setup` bağlantı yüzeyini kullanın; örneğin
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
|
||||
Yapılandırma yama yardımcıları gibi
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)` da dahil olmak üzere tam paylaşılan kurulum
|
||||
araç kutusunu istediğinizde daha geniş `plugin-sdk/setup` dikişini kullanın.
|
||||
|
||||
Kurulum yama bağdaştırıcıları içe aktarma sırasında sıcak yol için güvenli kalır. Bunların paketli
|
||||
tek hesap yükseltme sözleşme-yüzeyi araması tembeldir; yani
|
||||
`plugin-sdk/setup-runtime` içe aktarmak, bağdaştırıcı fiilen kullanılmadan önce paketli sözleşme-yüzeyi
|
||||
keşfini erken yüklemez.
|
||||
Kurulum yama bağdaştırıcıları, içe aktarıldığında sıcak yol açısından güvenli kalır. Paketlenmiş
|
||||
tek hesap yükseltme sözleşme-yüzeyi araması tembeldir; bu nedenle
|
||||
`plugin-sdk/setup-runtime` içe aktarmak, bağdaştırıcı gerçekten kullanılmadan önce paketlenmiş sözleşme-yüzeyi
|
||||
keşfini hevesli şekilde yüklemez.
|
||||
|
||||
### Kanalın sahip olduğu tek hesap yükseltmesi
|
||||
### Kanala ait tek hesap yükseltmesi
|
||||
|
||||
Bir kanal tek hesaplı üst düzey yapılandırmadan
|
||||
`channels.<id>.accounts.*` yapısına yükseltildiğinde, varsayılan paylaşılan davranış
|
||||
yükseltilen hesap kapsamlı değerleri `accounts.default` içine taşımaktır.
|
||||
Bir kanal, tek hesaplı üst düzey bir yapılandırmadan
|
||||
`channels.<id>.accounts.*` yapısına yükseltildiğinde, varsayılan paylaşılan davranış yükseltilen
|
||||
hesap kapsamlı değerleri `accounts.default` içine taşımaktır.
|
||||
|
||||
Paketli kanallar bu yükseltmeyi kurulum
|
||||
sözleşme yüzeyleri üzerinden daraltabilir veya geçersiz kılabilir:
|
||||
Paketlenmiş kanallar, kurulum
|
||||
sözleşme yüzeyleri aracılığıyla bu yükseltmeyi daraltabilir veya geçersiz kılabilir:
|
||||
|
||||
- `singleAccountKeysToMove`: yükseltilen
|
||||
hesaba taşınması gereken ek üst düzey anahtarlar
|
||||
- `namedAccountPromotionKeys`: adlandırılmış hesaplar zaten varsa yalnızca bu
|
||||
anahtarlar yükseltilen hesaba taşınır; paylaşılan ilke/teslimat anahtarları kanal kökünde kalır
|
||||
- `namedAccountPromotionKeys`: adlandırılmış hesaplar zaten mevcutsa, yalnızca bu
|
||||
anahtarlar yükseltilen hesaba taşınır; paylaşılan ilke/teslim anahtarları kanal kökünde kalır
|
||||
- `resolveSingleAccountPromotionTarget(...)`: yükseltilen değerleri hangi mevcut hesabın
|
||||
alacağını seçer
|
||||
|
||||
Mevcut paketli örnek Matrix'tir. Zaten tam olarak bir adlandırılmış Matrix hesabı
|
||||
varsa veya `defaultAccount`, `Ops` gibi mevcut kanonik olmayan bir anahtarı
|
||||
işaret ediyorsa yükseltme yeni bir `accounts.default` girdisi oluşturmak yerine bu hesabı korur.
|
||||
Matrix mevcut paketlenmiş örnektir. Tam olarak bir adlandırılmış Matrix hesabı
|
||||
zaten varsa veya `defaultAccount`, `Ops` gibi mevcut ancak kanonik olmayan bir anahtarı işaret ediyorsa,
|
||||
yükseltme yeni bir `accounts.default` girdisi oluşturmak yerine bu hesabı korur.
|
||||
|
||||
## Yapılandırma şeması
|
||||
|
||||
@ -366,7 +368,7 @@ plugin'leri şu şekilde yapılandırır:
|
||||
}
|
||||
```
|
||||
|
||||
Plugin'iniz bu yapılandırmayı kayıt sırasında `api.pluginConfig` olarak alır.
|
||||
Plugin'iniz, kayıt sırasında bu yapılandırmayı `api.pluginConfig` olarak alır.
|
||||
|
||||
Kanala özgü yapılandırma için bunun yerine kanal yapılandırma bölümünü kullanın:
|
||||
|
||||
@ -383,7 +385,7 @@ Kanala özgü yapılandırma için bunun yerine kanal yapılandırma bölümün
|
||||
|
||||
### Kanal yapılandırma şemaları oluşturma
|
||||
|
||||
Bir Zod şemasını OpenClaw'ın doğruladığı `ChannelConfigSchema`
|
||||
Bir Zod şemasını OpenClaw'un doğruladığı `ChannelConfigSchema`
|
||||
sarmalayıcısına dönüştürmek için `openclaw/plugin-sdk/core` içinden `buildChannelConfigSchema` kullanın:
|
||||
|
||||
```typescript
|
||||
@ -402,7 +404,7 @@ const configSchema = buildChannelConfigSchema(accountSchema);
|
||||
|
||||
## Kurulum sihirbazları
|
||||
|
||||
Kanal plugin'leri `openclaw onboard` için etkileşimli kurulum sihirbazları sağlayabilir.
|
||||
Kanal plugin'leri, `openclaw onboard` için etkileşimli kurulum sihirbazları sağlayabilir.
|
||||
Sihirbaz, `ChannelPlugin` üzerindeki bir `ChannelSetupWizard` nesnesidir:
|
||||
|
||||
```typescript
|
||||
@ -438,23 +440,21 @@ const setupWizard: ChannelSetupWizard = {
|
||||
|
||||
`ChannelSetupWizard` türü `credentials`, `textInputs`,
|
||||
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` ve daha fazlasını destekler.
|
||||
Tam örnekler için paketli plugin paketlerine (örneğin Discord plugin'inin `src/channel.setup.ts` dosyasına) bakın.
|
||||
Tam örnekler için paketlenmiş plugin paketlerine bakın (örneğin Discord plugin'i `src/channel.setup.ts`).
|
||||
|
||||
Yalnızca standart
|
||||
`not -> prompt -> parse -> merge -> patch` akışına ihtiyaç duyan DM izin listesi istemleri için
|
||||
`openclaw/plugin-sdk/setup` içindeki paylaşılan kurulum
|
||||
`note -> prompt -> parse -> merge -> patch` akışına ihtiyaç duyan DM izin listesi istemleri için, `openclaw/plugin-sdk/setup` içindeki paylaşılan kurulum
|
||||
yardımcılarını tercih edin: `createPromptParsedAllowFromForAccount(...)`,
|
||||
`createTopLevelChannelParsedAllowFromPrompt(...)` ve
|
||||
`createNestedChannelParsedAllowFromPrompt(...)`.
|
||||
|
||||
Yalnızca etiketler, puanlar ve isteğe bağlı
|
||||
ek satırlarda değişen kanal kurulum durum blokları için,
|
||||
her plugin'de aynı `status` nesnesini elle yazmak yerine
|
||||
`openclaw/plugin-sdk/setup` içinden `createStandardChannelSetupStatus(...)` kullanın.
|
||||
ek satırlar bakımından değişen kanal kurulum durum blokları için, aynı `status` nesnesini
|
||||
her plugin'de elle yazmak yerine `openclaw/plugin-sdk/setup` içindeki `createStandardChannelSetupStatus(...)`
|
||||
kullanın.
|
||||
|
||||
Yalnızca belirli bağlamlarda görünmesi gereken isteğe bağlı kurulum yüzeyleri için
|
||||
`openclaw/plugin-sdk/channel-setup` içinden
|
||||
`createOptionalChannelSetupSurface` kullanın:
|
||||
Yalnızca belirli bağlamlarda görünmesi gereken isteğe bağlı kurulum yüzeyleri için,
|
||||
`openclaw/plugin-sdk/channel-setup` içinden `createOptionalChannelSetupSurface` kullanın:
|
||||
|
||||
```typescript
|
||||
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
|
||||
@ -468,41 +468,42 @@ const setupSurface = createOptionalChannelSetupSurface({
|
||||
// Returns { setupAdapter, setupWizard }
|
||||
```
|
||||
|
||||
`plugin-sdk/channel-setup`, yalnızca bu isteğe bağlı kurulum yüzeyinin
|
||||
yarısına ihtiyaç duyduğunuzda daha düşük seviyeli
|
||||
`plugin-sdk/channel-setup`, ayrıca
|
||||
isteğe bağlı yükleme yüzeyinin yalnızca bir yarısına ihtiyacınız olduğunda daha düşük seviyeli
|
||||
`createOptionalChannelSetupAdapter(...)` ve
|
||||
`createOptionalChannelSetupWizard(...)` oluşturucularını da sunar.
|
||||
`createOptionalChannelSetupWizard(...)` oluşturucularını da dışa aktarır.
|
||||
|
||||
Üretilen isteğe bağlı bağdaştırıcı/sihirbaz, gerçek yapılandırma yazmalarında kapalı güvenli davranır. Bunlar
|
||||
Oluşturulan isteğe bağlı bağdaştırıcı/sihirbaz, gerçek yapılandırma yazımlarında kapalı şekilde başarısız olur. Bunlar
|
||||
`validateInput`,
|
||||
`applyAccountConfig` ve `finalize` arasında tek bir kurulum-gerekli iletisini yeniden kullanır ve `docsPath`
|
||||
ayarlıysa bir belge bağlantısı ekler.
|
||||
`applyAccountConfig` ve `finalize` genelinde tek bir yükleme-gerekli iletisini yeniden kullanır ve `docsPath`
|
||||
ayarlandığında bir belge bağlantısı ekler.
|
||||
|
||||
İkili dosya destekli kurulum arayüzleri için, her kanala aynı ikili/durum yapıştırıcısını
|
||||
İkili dosya destekli kurulum UI'leri için, her kanala aynı ikili/durum yapıştırıcısını
|
||||
kopyalamak yerine paylaşılan devredilmiş yardımcıları tercih edin:
|
||||
|
||||
- yalnızca etiketler,
|
||||
ipuçları, puanlar ve ikili algılamasında değişen durum blokları için `createDetectedBinaryStatus(...)`
|
||||
- yol destekli metin girişleri için `createCliPathTextInput(...)`
|
||||
- `setupEntry` daha ağır bir tam sihirbaza tembel biçimde iletmek zorundaysa
|
||||
- Yalnızca etiketler,
|
||||
ipuçları, puanlar ve ikili algılama bakımından değişen durum blokları için `createDetectedBinaryStatus(...)`
|
||||
- Yol destekli metin girdileri için `createCliPathTextInput(...)`
|
||||
- `setupEntry` tembel şekilde daha ağır bir tam sihirbaza iletmesi gerektiğinde
|
||||
`createDelegatedSetupWizardStatusResolvers(...)`,
|
||||
`createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` ve
|
||||
`createDelegatedResolveConfigured(...)`
|
||||
- `setupEntry` yalnızca bir `textInputs[*].shouldPrompt` kararını
|
||||
devretmek zorundaysa `createDelegatedTextInputShouldPrompt(...)`
|
||||
devretmek zorunda olduğunda `createDelegatedTextInputShouldPrompt(...)`
|
||||
|
||||
## Yayımlama ve kurulum
|
||||
|
||||
**Harici plugin'ler:** [ClawHub](/tr/tools/clawhub) veya npm üzerinde yayımlayın, sonra kurun:
|
||||
**Harici plugin'ler:** [ClawHub](/tr/tools/clawhub) veya npm'e yayımlayın, ardından kurun:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
OpenClaw önce ClawHub'ı dener ve sonra otomatik olarak npm'e geri döner. ClawHub'ı açıkça zorlamak için de şunu kullanabilirsiniz:
|
||||
OpenClaw önce ClawHub'ı dener ve otomatik olarak npm'e geri döner. Ayrıca
|
||||
ClawHub'ı açıkça zorlayabilirsiniz:
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # yalnızca ClawHub
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # Yalnızca ClawHub
|
||||
```
|
||||
|
||||
Buna karşılık gelen bir `npm:` geçersiz kılması yoktur. ClawHub geri dönüşünden sonra npm yolunu
|
||||
@ -512,17 +513,17 @@ istediğinizde normal npm paket belirtimini kullanın:
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
**Repo içi plugin'ler:** paketli plugin çalışma alanı ağacı altına yerleştirin; derleme sırasında otomatik
|
||||
olarak keşfedilirler.
|
||||
**Depo içi plugin'ler:** paketlenmiş plugin çalışma alanı ağacının altına yerleştirin; bunlar derleme sırasında otomatik olarak
|
||||
keşfedilir.
|
||||
|
||||
**Kullanıcılar şunu kurabilir:**
|
||||
**Kullanıcılar şunu yükleyebilir:**
|
||||
|
||||
```bash
|
||||
openclaw plugins install <package-name>
|
||||
```
|
||||
|
||||
<Info>
|
||||
npm kaynaklı kurulumlarda `openclaw plugins install`,
|
||||
npm kaynaklı kurulumlar için, `openclaw plugins install`
|
||||
`npm install --ignore-scripts` çalıştırır (yaşam döngüsü betikleri yoktur). Plugin bağımlılık
|
||||
ağaçlarını saf JS/TS tutun ve `postinstall` derlemeleri gerektiren paketlerden kaçının.
|
||||
</Info>
|
||||
@ -530,5 +531,5 @@ openclaw plugins install <package-name>
|
||||
## İlgili
|
||||
|
||||
- [SDK Giriş Noktaları](/tr/plugins/sdk-entrypoints) -- `definePluginEntry` ve `defineChannelPluginEntry`
|
||||
- [Plugin Manifest](/tr/plugins/manifest) -- tam manifest şeması başvurusu
|
||||
- [Plugin Oluşturma](/tr/plugins/building-plugins) -- adım adım başlangıç kılavuzu
|
||||
- [Plugin Manifesti](/tr/plugins/manifest) -- tam manifest şema başvurusu
|
||||
- [Plugin Oluşturma](/tr/plugins/building-plugins) -- adım adım başlangıç rehberi
|
||||
|
||||
@ -1,36 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Bir plugin için test yazarken
|
||||
- plugin SDK'dan test yardımcılarına ihtiyaç duyduğunuzda
|
||||
- paketlenmiş plugin'ler için sözleşme testlerini anlamak istediğinizde
|
||||
- Bir plugin için testler yazıyorsunuz
|
||||
- Plugin SDK'den test yardımcı programlarına ihtiyacınız var
|
||||
- Paketlenmiş plugin'ler için sözleşme testlerini anlamak istiyorsunuz
|
||||
sidebarTitle: Testing
|
||||
summary: OpenClaw plugin'leri için test yardımcıları ve kalıpları
|
||||
title: Plugin Testleri
|
||||
summary: OpenClaw Plugin'leri için test yardımcı programları ve kalıpları
|
||||
title: Plugin Testi
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:02:49Z"
|
||||
generated_at: "2026-04-15T19:42:21Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe
|
||||
source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09
|
||||
source_path: plugins/sdk-testing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Plugin Testleri
|
||||
# Plugin Testi
|
||||
|
||||
OpenClaw plugin'leri için test yardımcıları, kalıplar ve lint zorunluluğuna
|
||||
ilişkin başvuru.
|
||||
OpenClaw plugin'leri için test yardımcı programları, kalıpları ve lint zorlamasına ilişkin başvuru.
|
||||
|
||||
<Tip>
|
||||
**Test örnekleri mi arıyorsunuz?** Nasıl yapılır kılavuzları, işlenmiş test örnekleri içerir:
|
||||
[Channel plugin testleri](/plugins/sdk-channel-plugins#step-6-test) ve
|
||||
[Provider plugin testleri](/plugins/sdk-provider-plugins#step-6-test).
|
||||
**Test örnekleri mi arıyorsunuz?** Nasıl yapılır kılavuzları, üzerinde çalışılmış test örnekleri içerir:
|
||||
[Kanal plugin testleri](/tr/plugins/sdk-channel-plugins#step-6-test) ve
|
||||
[Sağlayıcı plugin testleri](/tr/plugins/sdk-provider-plugins#step-6-test).
|
||||
</Tip>
|
||||
|
||||
## Test yardımcıları
|
||||
## Test yardımcı programları
|
||||
|
||||
**İçe aktarma:** `openclaw/plugin-sdk/testing`
|
||||
|
||||
Testing alt yolu, plugin yazarları için dar bir yardımcı kümesi dışa aktarır:
|
||||
Testing alt yolu, plugin yazarları için dar kapsamlı bir yardımcı kümesi dışa aktarır:
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -42,15 +41,15 @@ import {
|
||||
|
||||
### Kullanılabilir dışa aktarımlar
|
||||
|
||||
| Dışa aktarım | Amaç |
|
||||
| -------------------------------------- | ----------------------------------------------------- |
|
||||
| Dışa aktarma | Amaç |
|
||||
| ------------------------------------ | ------------------------------------------------------ |
|
||||
| `installCommonResolveTargetErrorCases` | Hedef çözümleme hata işleme için paylaşılan test durumları |
|
||||
| `shouldAckReaction` | Bir kanalın ack reaction ekleyip eklememesi gerektiğini denetler |
|
||||
| `removeAckReactionAfterReply` | Yanıt tesliminden sonra ack reaction'ı kaldırır |
|
||||
| `shouldAckReaction` | Bir kanalın ack tepkisi ekleyip eklememesi gerektiğini kontrol eder |
|
||||
| `removeAckReactionAfterReply` | Yanıt tesliminden sonra ack tepkisini kaldırır |
|
||||
|
||||
### Türler
|
||||
|
||||
Testing alt yolu, test dosyalarında yararlı olan türleri de yeniden dışa aktarır:
|
||||
Testing alt yolu ayrıca test dosyalarında kullanışlı türleri yeniden dışa aktarır:
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
@ -65,8 +64,7 @@ import type {
|
||||
|
||||
## Hedef çözümlemeyi test etme
|
||||
|
||||
Kanal hedef çözümlemesi için standart hata durumları eklemek üzere
|
||||
`installCommonResolveTargetErrorCases` kullanın:
|
||||
Kanal hedef çözümlemesi için standart hata durumlarını eklemek üzere `installCommonResolveTargetErrorCases` kullanın:
|
||||
|
||||
```typescript
|
||||
import { describe } from "vitest";
|
||||
@ -75,13 +73,13 @@ import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testin
|
||||
describe("my-channel target resolution", () => {
|
||||
installCommonResolveTargetErrorCases({
|
||||
resolveTarget: ({ to, mode, allowFrom }) => {
|
||||
// Kanalınızın hedef çözümleme mantığı
|
||||
// Your channel's target resolution logic
|
||||
return myChannelResolveTarget({ to, mode, allowFrom });
|
||||
},
|
||||
implicitAllowFrom: ["user1", "user2"],
|
||||
});
|
||||
|
||||
// Kanala özgü test durumları ekleyin
|
||||
// Add channel-specific test cases
|
||||
it("should resolve @username targets", () => {
|
||||
// ...
|
||||
});
|
||||
@ -90,7 +88,7 @@ describe("my-channel target resolution", () => {
|
||||
|
||||
## Test kalıpları
|
||||
|
||||
### Bir channel plugin'ini birim testiyle test etme
|
||||
### Bir kanal plugin'ini birim testi ile test etme
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
@ -120,13 +118,13 @@ describe("my-channel plugin", () => {
|
||||
const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
|
||||
expect(inspection.configured).toBe(true);
|
||||
expect(inspection.tokenStatus).toBe("available");
|
||||
// Hiçbir token değeri açığa çıkarılmaz
|
||||
// No token value exposed
|
||||
expect(inspection).not.toHaveProperty("token");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Bir provider plugin'ini birim testiyle test etme
|
||||
### Bir sağlayıcı plugin'ini birim testi ile test etme
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -135,7 +133,7 @@ describe("my-provider plugin", () => {
|
||||
it("should resolve dynamic models", () => {
|
||||
const model = myProvider.resolveDynamicModel({
|
||||
modelId: "custom-model-v2",
|
||||
// ... bağlam
|
||||
// ... context
|
||||
});
|
||||
|
||||
expect(model.id).toBe("custom-model-v2");
|
||||
@ -146,7 +144,7 @@ describe("my-provider plugin", () => {
|
||||
it("should return catalog when API key is available", async () => {
|
||||
const result = await myProvider.catalog.run({
|
||||
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
|
||||
// ... bağlam
|
||||
// ... context
|
||||
});
|
||||
|
||||
expect(result?.provider?.models).toHaveLength(2);
|
||||
@ -154,51 +152,54 @@ describe("my-provider plugin", () => {
|
||||
});
|
||||
```
|
||||
|
||||
### Plugin çalışma zamanını taklit etme
|
||||
### Plugin çalışma zamanını mock'lama
|
||||
|
||||
`createPluginRuntimeStore` kullanan kod için testlerde çalışma zamanını taklit edin:
|
||||
`createPluginRuntimeStore` kullanan kodlar için testlerde çalışma zamanını mock'layın:
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
|
||||
const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
|
||||
const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
pluginId: "test-plugin",
|
||||
errorMessage: "test runtime not set",
|
||||
});
|
||||
|
||||
// Test kurulumu içinde
|
||||
// In test setup
|
||||
const mockRuntime = {
|
||||
agent: {
|
||||
resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
|
||||
// ... diğer taklitler
|
||||
// ... other mocks
|
||||
},
|
||||
config: {
|
||||
loadConfig: vi.fn(),
|
||||
writeConfigFile: vi.fn(),
|
||||
},
|
||||
// ... diğer ad alanları
|
||||
// ... other namespaces
|
||||
} as unknown as PluginRuntime;
|
||||
|
||||
store.setRuntime(mockRuntime);
|
||||
|
||||
// Testlerden sonra
|
||||
// After tests
|
||||
store.clearRuntime();
|
||||
```
|
||||
|
||||
### Örnek başına stub'larla test etme
|
||||
|
||||
Prototype mutation yerine örnek başına stub'ları tercih edin:
|
||||
Prototype mutasyonu yerine örnek başına stub'ları tercih edin:
|
||||
|
||||
```typescript
|
||||
// Tercih edilen: örnek başına stub
|
||||
// Preferred: per-instance stub
|
||||
const client = new MyChannelClient();
|
||||
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
|
||||
|
||||
// Kaçının: prototype mutation
|
||||
// Avoid: prototype mutation
|
||||
// MyChannelClient.prototype.sendMessage = vi.fn();
|
||||
```
|
||||
|
||||
## Sözleşme testleri (repo içi plugin'ler)
|
||||
|
||||
Paketlenmiş plugin'lerin, kayıt sahipliğini doğrulayan sözleşme testleri vardır:
|
||||
Paketlenmiş plugin'lerde kayıt sahipliğini doğrulayan sözleşme testleri vardır:
|
||||
|
||||
```bash
|
||||
pnpm test -- src/plugins/contracts/
|
||||
@ -206,10 +207,10 @@ pnpm test -- src/plugins/contracts/
|
||||
|
||||
Bu testler şunları doğrular:
|
||||
|
||||
- Hangi plugin'lerin hangi provider'ları kaydettiği
|
||||
- Hangi plugin'lerin hangi speech provider'larını kaydettiği
|
||||
- Kayıt şeklinin doğruluğu
|
||||
- Çalışma zamanı sözleşmesine uyumluluk
|
||||
- Hangi plugin'lerin hangi sağlayıcıları kaydettiğini
|
||||
- Hangi plugin'lerin hangi konuşma sağlayıcılarını kaydettiğini
|
||||
- Kayıt şeklinin doğruluğunu
|
||||
- Çalışma zamanı sözleşmesine uyumluluğu
|
||||
|
||||
### Kapsamlı testleri çalıştırma
|
||||
|
||||
@ -227,32 +228,31 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts
|
||||
pnpm test -- src/plugins/contracts/runtime.contract.test.ts
|
||||
```
|
||||
|
||||
## Lint zorunluluğu (repo içi plugin'ler)
|
||||
## Lint zorlaması (repo içi plugin'ler)
|
||||
|
||||
Repo içi plugin'ler için `pnpm check` tarafından üç kural zorunlu tutulur:
|
||||
Repo içi plugin'ler için `pnpm check` tarafından üç kural zorlanır:
|
||||
|
||||
1. **Monolitik kök içe aktarımları yok** -- `openclaw/plugin-sdk` kök barrel reddedilir
|
||||
2. **Doğrudan `src/` içe aktarımları yok** -- plugin'ler `../../src/` yolunu doğrudan içe aktaramaz
|
||||
3. **Kendi kendine içe aktarma yok** -- plugin'ler kendi `plugin-sdk/<name>` alt yolunu içe aktaramaz
|
||||
1. **Monolitik kök içe aktarmalar yok** -- `openclaw/plugin-sdk` kök barrel reddedilir
|
||||
2. **Doğrudan `src/` içe aktarmaları yok** -- plugin'ler `../../src/` yolunu doğrudan içe aktaramaz
|
||||
3. **Kendini içe aktarma yok** -- plugin'ler kendi `plugin-sdk/<name>` alt yolunu içe aktaramaz
|
||||
|
||||
Harici plugin'ler bu lint kurallarına tabi değildir, ancak aynı kalıpların
|
||||
izlenmesi önerilir.
|
||||
Harici plugin'ler bu lint kurallarına tabi değildir, ancak aynı kalıpların izlenmesi önerilir.
|
||||
|
||||
## Test yapılandırması
|
||||
|
||||
OpenClaw, V8 kapsam eşikleriyle Vitest kullanır. Plugin testleri için:
|
||||
OpenClaw, V8 kapsam eşikleriyle birlikte Vitest kullanır. Plugin testleri için:
|
||||
|
||||
```bash
|
||||
# Tüm testleri çalıştır
|
||||
# Run all tests
|
||||
pnpm test
|
||||
|
||||
# Belirli plugin testlerini çalıştır
|
||||
# Run specific plugin tests
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts
|
||||
|
||||
# Belirli bir test adı filtresiyle çalıştır
|
||||
# Run with a specific test name filter
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"
|
||||
|
||||
# Kapsamla birlikte çalıştır
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
```
|
||||
|
||||
@ -264,7 +264,7 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
|
||||
|
||||
## İlgili
|
||||
|
||||
- [SDK Genel Bakış](/plugins/sdk-overview) -- içe aktarma kuralları
|
||||
- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- channel plugin arabirimi
|
||||
- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- provider plugin hook'ları
|
||||
- [Plugin Geliştirme](/plugins/building-plugins) -- başlangıç kılavuzu
|
||||
- [SDK Genel Bakış](/tr/plugins/sdk-overview) -- içe aktarma kuralları
|
||||
- [SDK Kanal Plugin'leri](/tr/plugins/sdk-channel-plugins) -- kanal plugin arayüzü
|
||||
- [SDK Sağlayıcı Plugin'leri](/tr/plugins/sdk-provider-plugins) -- sağlayıcı plugin hook'ları
|
||||
- [Plugin Oluşturma](/tr/plugins/building-plugins) -- başlangıç kılavuzu
|
||||
|
||||
@ -1,131 +1,146 @@
|
||||
---
|
||||
read_when:
|
||||
- Token kullanımını, maliyetleri veya bağlam pencerelerini açıklama
|
||||
- Bağlam büyümesini veya sıkıştırma davranışını hata ayıklama
|
||||
summary: OpenClaw’ın istem bağlamını nasıl oluşturduğu ve token kullanımını + maliyetleri nasıl raporladığı
|
||||
- Bağlam büyümesini veya Compaction davranışını hata ayıklama
|
||||
summary: OpenClaw'ın istem bağlamını nasıl oluşturduğu ve token kullanımını + maliyetleri nasıl raporladığı
|
||||
title: Token Kullanımı ve Maliyetler
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T08:33:31Z"
|
||||
generated_at: "2026-04-15T19:42:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
|
||||
source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5
|
||||
source_path: reference/token-use.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Token kullanımı ve maliyetler
|
||||
|
||||
OpenClaw **karakterleri değil, token’ları** izler. Token’lar modele özgüdür, ancak çoğu
|
||||
OpenAI tarzı model İngilizce metinde token başına ortalama ~4 karakter kullanır.
|
||||
OpenClaw, karakterleri değil **token**'ları izler. Token'lar modele özeldir, ancak çoğu
|
||||
OpenAI tarzı model İngilizce metinde ortalama token başına ~4 karakter kullanır.
|
||||
|
||||
## Sistem istemi nasıl oluşturulur
|
||||
|
||||
OpenClaw her çalıştırmada kendi sistem istemini oluşturur. Şunları içerir:
|
||||
|
||||
- Araç listesi + kısa açıklamalar
|
||||
- Skills listesi (yalnızca meta veriler; yönergeler ihtiyaç halinde `read` ile yüklenir)
|
||||
- Self-update yönergeleri
|
||||
- Çalışma alanı + önyükleme dosyaları (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, yeni olduğunda `BOOTSTRAP.md`, ayrıca varsa `MEMORY.md` veya küçük harfli geri dönüş olarak `memory.md`). Büyük dosyalar `agents.defaults.bootstrapMaxChars` ile kırpılır (varsayılan: 20000) ve toplam önyükleme enjeksiyonu `agents.defaults.bootstrapTotalMaxChars` ile sınırlandırılır (varsayılan: 150000). `memory/*.md` günlük dosyaları normal önyükleme isteminin parçası değildir; normal turlarda bellek araçları üzerinden ihtiyaç halinde erişilebilir olarak kalırlar, ancak çıplak `/new` ve `/reset` ilk tur için son günlük belleği içeren tek seferlik bir başlangıç bağlamı bloğunu başa ekleyebilir. Bu başlangıç giriş bölümü `agents.defaults.startupContext` ile kontrol edilir.
|
||||
- Skills listesi (yalnızca meta veri; talimatlar ihtiyaç halinde `read` ile yüklenir).
|
||||
Kompakt skills bloğu `skills.limits.maxSkillsPromptChars` ile sınırlandırılır,
|
||||
ve ajan başına isteğe bağlı geçersiz kılma
|
||||
`agents.list[].skillsLimits.maxSkillsPromptChars` konumundadır.
|
||||
- Self-update talimatları
|
||||
- Workspace + önyükleme dosyaları (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, yeniyse `BOOTSTRAP.md`, ayrıca varsa `MEMORY.md` veya küçük harfli yedek olarak `memory.md`). Büyük dosyalar `agents.defaults.bootstrapMaxChars` ile kesilir (varsayılan: 12000), toplam önyükleme ekleme ise `agents.defaults.bootstrapTotalMaxChars` ile sınırlandırılır (varsayılan: 60000). `memory/*.md` günlük dosyaları normal önyükleme isteminin parçası değildir; normal turlarda memory araçları üzerinden ihtiyaç halinde kalırlar, ancak çıplak `/new` ve `/reset` ilk tur için son günlük belleği içeren tek seferlik bir başlangıç bağlamı bloğunu öne ekleyebilir. Bu başlangıç ön eki `agents.defaults.startupContext` tarafından kontrol edilir.
|
||||
- Zaman (UTC + kullanıcı saat dilimi)
|
||||
- Yanıt etiketleri + heartbeat davranışı
|
||||
- Çalışma zamanı meta verileri (ana makine/işletim sistemi/model/düşünme)
|
||||
- Çalışma zamanı meta verileri (host/OS/model/düşünme)
|
||||
|
||||
Tam döküm için bkz. [System Prompt](/tr/concepts/system-prompt).
|
||||
|
||||
## Bağlam penceresinde ne sayılır
|
||||
## Bağlam penceresinde neler sayılır
|
||||
|
||||
Modelin aldığı her şey bağlam sınırına dahil edilir:
|
||||
Modele gönderilen her şey bağlam sınırına dahil olur:
|
||||
|
||||
- Sistem istemi (yukarıda listelenen tüm bölümler)
|
||||
- Konuşma geçmişi (kullanıcı + asistan mesajları)
|
||||
- Araç çağrıları ve araç sonuçları
|
||||
- Ekler/dökümler (görseller, ses, dosyalar)
|
||||
- Sıkıştırma özetleri ve budama artifaktları
|
||||
- Sağlayıcı sarmalayıcıları veya güvenlik başlıkları (görünmezler, ancak yine de sayılırlar)
|
||||
- Ekler/transkriptler (görseller, ses, dosyalar)
|
||||
- Compaction özetleri ve budama yapıtları
|
||||
- Sağlayıcı sarmalayıcıları veya güvenlik başlıkları (görünmezler, ama yine de sayılırlar)
|
||||
|
||||
Görseller için OpenClaw, sağlayıcı çağrılarından önce döküm/araç görsel yüklerini küçültür.
|
||||
Bazı çalışma zamanı açısından ağır yüzeylerin kendi açık sınırları vardır:
|
||||
|
||||
- `agents.defaults.contextLimits.memoryGetMaxChars`
|
||||
- `agents.defaults.contextLimits.memoryGetDefaultLines`
|
||||
- `agents.defaults.contextLimits.toolResultMaxChars`
|
||||
- `agents.defaults.contextLimits.postCompactionMaxChars`
|
||||
|
||||
Ajan başına geçersiz kılmalar `agents.list[].contextLimits` altında bulunur. Bu ayarlar
|
||||
sınırlı çalışma zamanı alıntıları ve çalışma zamanına ait enjekte edilen bloklar
|
||||
içindir. Önyükleme sınırlarından, başlangıç bağlamı sınırlarından ve skills istem
|
||||
sınırlarından ayrıdırlar.
|
||||
|
||||
Görseller için OpenClaw, sağlayıcı çağrılarından önce transkript/araç görsel yüklerini küçültür.
|
||||
Bunu ayarlamak için `agents.defaults.imageMaxDimensionPx` kullanın (varsayılan: `1200`):
|
||||
|
||||
- Daha düşük değerler genellikle vision token kullanımını ve yük boyutunu azaltır.
|
||||
- Daha yüksek değerler OCR/arayüz ağırlıklı ekran görüntülerinde daha fazla görsel ayrıntıyı korur.
|
||||
- Daha yüksek değerler OCR/UI ağırlıklı ekran görüntüleri için daha fazla görsel ayrıntıyı korur.
|
||||
|
||||
Pratik bir döküm için (enjekte edilen dosya başına, araçlar, skills ve sistem istemi boyutu), `/context list` veya `/context detail` kullanın. Bkz. [Context](/tr/concepts/context).
|
||||
Pratik bir döküm için (enjekte edilen dosya başına, araçlar, Skills ve sistem istemi boyutu), `/context list` veya `/context detail` kullanın. Bkz. [Context](/tr/concepts/context).
|
||||
|
||||
## Geçerli token kullanımını nasıl görebilirsiniz
|
||||
## Geçerli token kullanımı nasıl görülür
|
||||
|
||||
Sohbette şunları kullanın:
|
||||
|
||||
- `/status` → oturum modelini, bağlam kullanımını,
|
||||
son yanıtın girdi/çıktı token’larını ve **tahmini maliyeti** (yalnızca API anahtarı) gösteren **emoji açısından zengin durum kartı**.
|
||||
- `/usage off|tokens|full` → her yanıta **yanıt başına kullanım altbilgisi** ekler.
|
||||
- `/status` → oturum modeli, bağlam kullanımı,
|
||||
son yanıt giriş/çıkış token'ları ve **tahmini maliyet** içeren
|
||||
**emoji açısından zengin durum kartı** (yalnızca API anahtarı).
|
||||
- `/usage off|tokens|full` → her yanıta **yanıt başına kullanım alt bilgisi** ekler.
|
||||
- Oturum başına kalıcıdır (`responseUsage` olarak saklanır).
|
||||
- OAuth kimlik doğrulaması **maliyeti gizler** (yalnızca token’lar).
|
||||
- OAuth kimlik doğrulaması **maliyeti gizler** (yalnızca token'lar).
|
||||
- `/usage cost` → OpenClaw oturum günlüklerinden yerel bir maliyet özeti gösterir.
|
||||
|
||||
Diğer yüzeyler:
|
||||
|
||||
- **TUI/Web TUI:** `/status` + `/usage` desteklenir.
|
||||
- **CLI:** `openclaw status --usage` ve `openclaw channels list`
|
||||
normalize edilmiş sağlayıcı kota pencerelerini gösterir (`%X kaldı`, yanıt başına maliyet değil).
|
||||
- **CLI:** `openclaw status --usage` ve `openclaw channels list`,
|
||||
normalize edilmiş sağlayıcı kota pencerelerini gösterir
|
||||
(`%X kaldı`, yanıt başına maliyet değil).
|
||||
Geçerli kullanım penceresi sağlayıcıları: Anthropic, GitHub Copilot, Gemini CLI,
|
||||
OpenAI Codex, MiniMax, Xiaomi ve z.ai.
|
||||
|
||||
Kullanım yüzeyleri, görüntülemeden önce yaygın sağlayıcıya özgü alan takma adlarını normalize eder.
|
||||
Kullanım yüzeyleri, gösterimden önce yaygın sağlayıcıya özgü alan takma adlarını normalize eder.
|
||||
OpenAI ailesi Responses trafiği için buna hem `input_tokens` /
|
||||
`output_tokens` hem de `prompt_tokens` / `completion_tokens` dahildir; böylece taşıma biçimine özgü
|
||||
`output_tokens` hem de `prompt_tokens` / `completion_tokens` dahildir; böylece iletime özgü
|
||||
alan adları `/status`, `/usage` veya oturum özetlerini değiştirmez.
|
||||
Gemini CLI JSON kullanımı da normalize edilir: yanıt metni `response` alanından gelir ve
|
||||
CLI açık bir `stats.input` alanı vermediğinde
|
||||
`stats.cached`, `cacheRead` alanına eşlenir ve `stats.input_tokens - stats.cached`
|
||||
kullanılır.
|
||||
Yerel OpenAI ailesi Responses trafiğinde WebSocket/SSE kullanım takma adları da
|
||||
aynı şekilde normalize edilir ve `total_tokens` eksikse veya `0` ise toplamlar normalize edilmiş girdi + çıktıdan geri alınır.
|
||||
Gemini CLI JSON kullanımı da normalize edilir: yanıt metni `response` içinden gelir ve
|
||||
CLI açık bir `stats.input` alanı vermediğinde `stats.cached`, `cacheRead` olarak eşlenir;
|
||||
`stats.input_tokens - stats.cached` kullanılır.
|
||||
Yerel OpenAI ailesi Responses trafiğinde, WebSocket/SSE kullanım takma adları da
|
||||
aynı şekilde normalize edilir ve `total_tokens` eksikse veya `0` ise toplamlar normalize edilmiş giriş + çıkıştan geri doldurulur.
|
||||
Geçerli oturum anlık görüntüsü seyrek olduğunda, `/status` ve `session_status`
|
||||
ayrıca en son döküm kullanım günlüğünden token/önbellek sayaçlarını ve etkin çalışma zamanı model etiketini de
|
||||
geri alabilir.
|
||||
Var olan sıfır olmayan canlı değerler yine de döküm geri dönüş değerlerinden önceliklidir ve daha büyük istem odaklı
|
||||
döküm toplamları, saklanan toplamlar eksikse veya daha küçükse üstün gelebilir.
|
||||
Sağlayıcı kota pencereleri için kullanım kimlik doğrulaması, mevcut olduğunda sağlayıcıya özgü hook’lardan gelir;
|
||||
aksi takdirde OpenClaw, auth profilleri, ortam veya yapılandırmadan eşleşen OAuth/API anahtarı kimlik bilgilerine geri döner.
|
||||
ayrıca en son transkript kullanım günlüğünden token/önbellek sayaçlarını ve etkin çalışma zamanı model etiketini de kurtarabilir.
|
||||
Mevcut sıfır olmayan canlı değerler yine de transkript geri doldurma değerlerine göre önceliklidir ve depolanan toplamlar eksikse veya daha küçükse
|
||||
istem odaklı daha büyük transkript toplamları kazanabilir.
|
||||
Sağlayıcı kota pencereleri için kullanım kimlik doğrulaması, mevcut olduğunda sağlayıcıya özgü hook'lardan gelir; aksi halde OpenClaw auth profillerinden, ortamdan veya yapılandırmadan eşleşen OAuth/API anahtarı kimlik bilgilerine geri döner.
|
||||
|
||||
## Maliyet tahmini (gösterildiğinde)
|
||||
|
||||
Maliyetler model fiyatlandırma yapılandırmanızdan tahmin edilir:
|
||||
Maliyetler, model fiyatlandırma yapılandırmanızdan tahmin edilir:
|
||||
|
||||
```
|
||||
models.providers.<provider>.models[].cost
|
||||
```
|
||||
|
||||
Bunlar `input`, `output`, `cacheRead` ve
|
||||
`cacheWrite` için **1 milyon token başına USD** değerleridir. Fiyatlandırma eksikse OpenClaw yalnızca token’ları gösterir. OAuth token’ları
|
||||
`cacheWrite` için **1M token başına USD** cinsindendir. Fiyatlandırma eksikse OpenClaw yalnızca token'ları gösterir. OAuth token'ları
|
||||
asla dolar maliyeti göstermez.
|
||||
|
||||
## Önbellek TTL’si ve budama etkisi
|
||||
## Önbellek TTL ve budama etkisi
|
||||
|
||||
Sağlayıcı istem önbelleklemesi yalnızca önbellek TTL penceresi içinde uygulanır. OpenClaw
|
||||
isteğe bağlı olarak **cache-ttl budaması** çalıştırabilir: önbellek TTL’si
|
||||
sona erdiğinde oturumu budar, ardından önbellek penceresini sıfırlar; böylece sonraki istekler tüm geçmişi yeniden önbelleğe almak yerine
|
||||
yeni önbelleğe alınmış bağlamı yeniden kullanabilir. Bu, bir oturum TTL sonrasına kadar boşta kalırsa
|
||||
önbellek yazma maliyetlerini daha düşük tutar.
|
||||
Sağlayıcı istem önbelleklemesi yalnızca önbellek TTL penceresi içinde geçerlidir. OpenClaw
|
||||
isteğe bağlı olarak **cache-ttl pruning** çalıştırabilir: önbellek TTL süresi
|
||||
dolduğunda oturumu budar, sonra önbellek penceresini sıfırlar; böylece sonraki
|
||||
istekler tam geçmişi tekrar önbelleğe yazmak yerine yeni önbelleğe alınmış bağlamı yeniden kullanabilir.
|
||||
Bu, bir oturum TTL sonrasında boşta kaldığında önbellek yazma maliyetlerini
|
||||
daha düşük tutar.
|
||||
|
||||
Bunu [Gateway configuration](/tr/gateway/configuration) altında yapılandırın ve
|
||||
davranış ayrıntıları için [Session pruning](/tr/concepts/session-pruning) belgesine bakın.
|
||||
Bunu [Gateway configuration](/tr/gateway/configuration) içinde yapılandırın ve
|
||||
davranış ayrıntılarını [Session pruning](/tr/concepts/session-pruning) içinde görün.
|
||||
|
||||
Heartbeat, boşluk süreleri boyunca önbelleği **sıcak** tutabilir. Model önbellek TTL’niz
|
||||
`1h` ise, heartbeat aralığını bunun hemen altına ayarlamak (örneğin `55m`) tüm istemin
|
||||
yeniden önbelleğe alınmasını önleyebilir ve önbellek yazma maliyetlerini azaltabilir.
|
||||
Heartbeat, önbelleği boşta geçen aralıklarda **sıcak** tutabilir. Model önbellek TTL'niz
|
||||
`1h` ise, heartbeat aralığını bunun biraz altına ayarlamak (`55m` gibi)
|
||||
tam istemin yeniden önbelleğe alınmasını önleyebilir ve önbellek yazma maliyetlerini azaltabilir.
|
||||
|
||||
Çok agent’li kurulumlarda, tek bir paylaşılan model yapılandırmasını koruyabilir ve önbellek davranışını
|
||||
agent başına `agents.list[].params.cacheRetention` ile ayarlayabilirsiniz.
|
||||
Çok ajanlı kurulumlarda, ortak bir model yapılandırmasını koruyup önbellek davranışını
|
||||
ajan başına `agents.list[].params.cacheRetention` ile ayarlayabilirsiniz.
|
||||
|
||||
Düğme düğme tam rehber için bkz. [Prompt Caching](/tr/reference/prompt-caching).
|
||||
Düğme bazında tam kılavuz için bkz. [Prompt Caching](/tr/reference/prompt-caching).
|
||||
|
||||
Anthropic API fiyatlandırmasında, önbellek okumaları girdi
|
||||
token’larından belirgin ölçüde daha ucuzdur; önbellek yazmaları ise daha yüksek bir çarpanla faturalandırılır. En güncel oranlar ve TTL çarpanları için Anthropic’in
|
||||
Anthropic API fiyatlandırmasında, önbellek okumaları giriş
|
||||
token'larından belirgin biçimde daha ucuzdur; önbellek yazmaları ise daha yüksek bir çarpanla ücretlendirilir. En güncel oranlar ve TTL çarpanları için Anthropic’in
|
||||
istem önbellekleme fiyatlandırmasına bakın:
|
||||
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
|
||||
|
||||
### Örnek: heartbeat ile 1 saatlik önbelleği sıcak tutma
|
||||
### Örnek: heartbeat ile 1h önbelleği sıcak tutma
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -140,7 +155,7 @@ agents:
|
||||
every: "55m"
|
||||
```
|
||||
|
||||
### Örnek: agent başına önbellek stratejisiyle karma trafik
|
||||
### Örnek: ajan başına önbellek stratejisiyle karma trafik
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -150,7 +165,7 @@ agents:
|
||||
models:
|
||||
"anthropic/claude-opus-4-6":
|
||||
params:
|
||||
cacheRetention: "long" # çoğu agent için varsayılan temel çizgi
|
||||
cacheRetention: "long" # çoğu ajan için varsayılan temel çizgi
|
||||
list:
|
||||
- id: "research"
|
||||
default: true
|
||||
@ -158,17 +173,17 @@ agents:
|
||||
every: "55m" # derin oturumlar için uzun önbelleği sıcak tut
|
||||
- id: "alerts"
|
||||
params:
|
||||
cacheRetention: "none" # patlamalı bildirimler için önbellek yazmalarını önle
|
||||
cacheRetention: "none" # patlamalı bildirimler için önbellek yazımlarını önle
|
||||
```
|
||||
|
||||
`agents.list[].params`, seçili modelin `params` alanının üzerine birleştirilir; böylece yalnızca
|
||||
`cacheRetention` değerini geçersiz kılabilir ve diğer model varsayılanlarını değiştirmeden devralabilirsiniz.
|
||||
`agents.list[].params`, seçilen modelin `params` alanının üzerine birleştirilir; böylece yalnızca
|
||||
`cacheRetention` değerini geçersiz kılıp diğer model varsayılanlarını değiştirmeden devralabilirsiniz.
|
||||
|
||||
### Örnek: Anthropic 1M bağlam beta başlığını etkinleştirme
|
||||
|
||||
Anthropic’in 1M bağlam penceresi şu anda beta kapısıyla sınırlandırılmıştır. OpenClaw,
|
||||
desteklenen Opus
|
||||
veya Sonnet modellerinde `context1m` etkinleştirildiğinde gerekli `anthropic-beta` değerini enjekte edebilir.
|
||||
Anthropic'in 1M bağlam penceresi şu anda beta geçidi arkasındadır. OpenClaw, desteklenen Opus
|
||||
veya Sonnet modellerinde `context1m` etkinleştirildiğinde gerekli
|
||||
`anthropic-beta` değerini enjekte edebilir.
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -179,22 +194,22 @@ agents:
|
||||
context1m: true
|
||||
```
|
||||
|
||||
Bu, Anthropic’in `context-1m-2025-08-07` beta başlığına eşlenir.
|
||||
Bu, Anthropic'in `context-1m-2025-08-07` beta başlığına eşlenir.
|
||||
|
||||
Bu yalnızca o model girdisinde `context1m: true` ayarlandığında uygulanır.
|
||||
Bu yalnızca ilgili model girdisinde `context1m: true` ayarlandığında geçerlidir.
|
||||
|
||||
Gereksinim: kimlik bilgisi uzun bağlam kullanımı için uygun olmalıdır. Değilse,
|
||||
Anthropic bu istek için sağlayıcı taraflı bir hız sınırı hatası döndürür.
|
||||
Gereksinim: kimlik bilgilerinin uzun bağlam kullanımı için uygun olması gerekir. Aksi halde,
|
||||
Anthropic o istek için sağlayıcı taraflı hız sınırı hatası döndürür.
|
||||
|
||||
Anthropic’i OAuth/abonelik token’larıyla (`sk-ant-oat-*`) kimlik doğrularsanız,
|
||||
OpenClaw `context-1m-*` beta başlığını atlar; çünkü Anthropic şu anda
|
||||
bu birleşimi HTTP 401 ile reddetmektedir.
|
||||
Anthropic'e OAuth/abonelik token'larıyla (`sk-ant-oat-*`) kimlik doğrulaması yaparsanız,
|
||||
OpenClaw `context-1m-*` beta başlığını atlar çünkü Anthropic şu anda
|
||||
bu birleşimi HTTP 401 ile reddeder.
|
||||
|
||||
## Token baskısını azaltma ipuçları
|
||||
|
||||
- Uzun oturumları özetlemek için `/compact` kullanın.
|
||||
- İş akışlarınızda büyük araç çıktıları kırpın.
|
||||
- Ekran görüntüsü ağırlıklı oturumlarda `agents.defaults.imageMaxDimensionPx` değerini düşürün.
|
||||
- İş akışlarınızda büyük araç çıktılarını kırpın.
|
||||
- Ekran görüntüsü ağırlıklı oturumlar için `agents.defaults.imageMaxDimensionPx` değerini düşürün.
|
||||
- Skill açıklamalarını kısa tutun (skill listesi isteme enjekte edilir).
|
||||
- Ayrıntılı, keşif amaçlı işler için daha küçük modelleri tercih edin.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user