Yapılandırma — ajanlar

agents.*, multiAgent.*, session.*, messages.* ve talk.* altındaki aracı kapsamlı yapılandırma anahtarları. Kanallar, araçlar, Gateway çalışma zamanı ve diğer üst düzey anahtarlar için bkz. Yapılandırma başvurusu.

# Aracı varsayılanları

# agents.defaults.workspace

Varsayılan: ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

# agents.defaults.repoRoot

Sistem isteminin Runtime satırında gösterilen isteğe bağlı depo kökü. Ayarlanmazsa OpenClaw, çalışma alanından yukarı doğru ilerleyerek otomatik olarak algılar.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

# agents.defaults.skills

agents.list[].skills ayarlamayan aracılar için isteğe bağlı varsayılan Skills izin listesi.

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // github, weather devralır
      { id: "docs", skills: ["docs-search"] }, // varsayılanların yerini alır
      { id: "locked-down", skills: [] }, // skills yok
    ],
  },
}

• Varsayılan olarak sınırsız Skills için agents.defaults.skills değerini atlayın.
• Varsayılanları devralmak için agents.list[].skills değerini atlayın.
• Skills olmaması için agents.list[].skills: [] ayarlayın.
• Boş olmayan bir agents.list[].skills listesi, o aracı için son kümedir; varsayılanlarla birleştirilmez.

# agents.defaults.skipBootstrap

Çalışma alanı bootstrap dosyalarının (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md) otomatik oluşturulmasını devre dışı bırakır.

{
  agents: { defaults: { skipBootstrap: true } },
}

# agents.defaults.skipOptionalBootstrapFiles

Gerekli bootstrap dosyalarını yazmaya devam ederken seçilen isteğe bağlı çalışma alanı dosyalarının oluşturulmasını atlar. Geçerli değerler: SOUL.md, USER.md, HEARTBEAT.md ve IDENTITY.md.

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

# agents.defaults.contextInjection

Çalışma alanı bootstrap dosyalarının sistem istemine ne zaman enjekte edileceğini denetler. Varsayılan: "always".

• "continuation-skip": güvenli devam dönüşlerinde (tamamlanmış bir asistan yanıtından sonra) çalışma alanı bootstrap yeniden enjeksiyonu atlanır ve istem boyutu azaltılır. Heartbeat çalıştırmaları ve Compaction sonrası yeniden denemeler bağlamı yine yeniden oluşturur.
• "never": her dönüşte çalışma alanı bootstrap ve bağlam dosyası enjeksiyonunu devre dışı bırakır. Bunu yalnızca istem yaşam döngüsünün tamamına sahip olan aracılar için kullanın (özel bağlam motorları, kendi bağlamını oluşturan yerel çalışma zamanları veya bootstrap içermeyen özel iş akışları). Heartbeat ve Compaction kurtarma dönüşleri de enjeksiyonu atlar.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

# agents.defaults.bootstrapMaxChars

Kırpma öncesinde çalışma alanı bootstrap dosyası başına en fazla karakter sayısı. Varsayılan: 12000.

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

# agents.defaults.bootstrapTotalMaxChars

Tüm çalışma alanı bootstrap dosyaları genelinde enjekte edilen en fazla toplam karakter sayısı. Varsayılan: 60000.

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

# agents.defaults.bootstrapPromptTruncationWarning

Bootstrap bağlamı kırpıldığında aracının görebileceği sistem istemi bildirimini denetler. Varsayılan: "once".

• "off": kırpma bildirimi metnini sistem istemine hiçbir zaman enjekte etmez.
• "once": benzersiz kırpma imzası başına bir kez kısa bir bildirim enjekte eder (önerilir).
• "always": kırpma varsa her çalıştırmada kısa bir bildirim enjekte eder.

Ayrıntılı ham/enjekte edilmiş sayımlar ve yapılandırma ayarlama alanları, bağlam/durum raporları ve günlükler gibi tanılama çıktılarında kalır; rutin WebChat kullanıcı/çalışma zamanı bağlamı yalnızca kısa kurtarma bildirimini alır.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

# Bağlam bütçesi sahiplik haritası

OpenClaw'da birden fazla yüksek hacimli istem/bağlam bütçesi vardır ve bunlar tek bir genel düğmeden geçmek yerine bilinçli olarak alt sisteme göre bölünmüştür.

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normal çalışma alanı bootstrap enjeksiyonu.
• agents.defaults.startupContext.*: son günlük memory/*.md dosyaları dahil olmak üzere tek seferlik sıfırlama/başlatma model çalıştırması başlangıç bölümü. Yalın sohbet /new ve /reset komutları, modeli çağırmadan onaylanır.
• skills.limits.*: sistem istemine enjekte edilen kompakt Skills listesi.
• agents.defaults.contextLimits.*: sınırlı çalışma zamanı alıntıları ve enjekte edilen çalışma zamanı sahipli bloklar.
• memory.qmd.limits.*: dizinlenmiş bellek arama parçacığı ve enjeksiyon boyutlandırması.

Eşleşen aracı başına geçersiz kılmayı yalnızca bir aracı farklı bir bütçeye ihtiyaç duyduğunda kullanın:

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

# agents.defaults.startupContext

Sıfırlama/başlatma model çalıştırmalarında enjekte edilen ilk dönüş başlatma başlangıç bölümünü denetler. Yalın sohbet /new ve /reset komutları, modeli çağırmadan sıfırlamayı onaylar; bu nedenle bu başlangıç bölümünü yüklemezler.

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

# agents.defaults.contextLimits

Sınırlı çalışma zamanı bağlam yüzeyleri için paylaşılan varsayılanlar.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: kırpma meta verileri ve devam bildirimi eklenmeden önce varsayılan memory_get alıntı sınırı.
• memoryGetDefaultLines: lines atlandığında varsayılan memory_get satır penceresi.
• toolResultMaxChars: kalıcı sonuçlar ve taşma kurtarması için kullanılan canlı araç sonucu sınırı.
• postCompactionMaxChars: Compaction sonrası yenileme enjeksiyonu sırasında kullanılan AGENTS.md alıntı sınırı.

# agents.list[].contextLimits

Paylaşılan contextLimits düğmeleri için aracı başına geçersiz kılma. Atlanan alanlar agents.defaults.contextLimits içinden devralınır.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

# skills.limits.maxSkillsPromptChars

Sistem istemine enjekte edilen kompakt Skills listesi için genel sınır. Bu, gerektiğinde SKILL.md dosyalarının okunmasını etkilemez.

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

# agents.list[].skillsLimits.maxSkillsPromptChars

Skills istem bütçesi için aracı başına geçersiz kılma.

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

# agents.defaults.imageMaxDimensionPx

Sağlayıcı çağrılarından önce transcript/araç görsel bloklarında en uzun görsel kenarı için en fazla piksel boyutu. Varsayılan: 1200.

Daha düşük değerler, ekran görüntüsü ağırlıklı çalıştırmalar için genellikle görsel token kullanımını ve istek yükü boyutunu azaltır. Daha yüksek değerler daha fazla görsel ayrıntıyı korur.

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

# agents.defaults.userTimezone

Sistem istemi bağlamı için saat dilimi (mesaj zaman damgaları değil). Ana makine saat dilimine geri döner.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

# agents.defaults.timeFormat

Sistem istemindeki saat biçimi. Varsayılan: auto (işletim sistemi tercihi).

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

# agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // genel varsayılan sağlayıcı parametreleri
      agentRuntime: {
        id: "pi", // pi | auto | kayıtlı harness id, ör. codex
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: ya bir dizeyi ("provider/model") ya da bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Dize biçimi yalnızca birincil modeli ayarlar.
  • Nesne biçimi birincil modeli ve sıralı yük devretme modellerini ayarlar.
• imageModel: ya bir dizeyi ("provider/model") ya da bir nesneyi ({ primary, fallbacks }) kabul eder.
  • image araç yolu tarafından görüntü modeli yapılandırması olarak kullanılır.
  • Seçili/varsayılan model görüntü girdisini kabul edemediğinde geri dönüş yönlendirmesi olarak da kullanılır.
  • Açık provider/model referanslarını tercih edin. Yalın kimlikler uyumluluk için kabul edilir; yalın bir kimlik models.providers.*.models içinde yapılandırılmış, görüntü destekli bir girdiye benzersiz şekilde eşleşirse OpenClaw bunu o sağlayıcıyla niteler. Belirsiz yapılandırılmış eşleşmeler açık bir sağlayıcı ön eki gerektirir.
• imageGenerationModel: ya bir dizeyi ("provider/model") ya da bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Paylaşılan görüntü üretme yeteneği ve görüntü üreten gelecekteki tüm araç/Plugin yüzeyleri tarafından kullanılır.
  • Tipik değerler: yerel Gemini görüntü üretimi için google/gemini-3.1-flash-image-preview, fal için fal/fal-ai/flux/dev, OpenAI Images için openai/gpt-image-2 veya şeffaf arka planlı OpenAI PNG/WebP çıktısı için openai/gpt-image-1.5.
  • Doğrudan bir sağlayıcı/model seçerseniz, eşleşen sağlayıcı kimlik doğrulamasını da yapılandırın (örneğin google/* için GEMINI_API_KEY veya GOOGLE_API_KEY, openai/gpt-image-2 / openai/gpt-image-1.5 için OPENAI_API_KEY veya OpenAI Codex OAuth, fal/* için FAL_KEY).
  • Atlanırsa image_generate yine de kimlik doğrulama destekli bir sağlayıcı varsayılanı çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından kalan kayıtlı görüntü üretme sağlayıcılarını sağlayıcı kimliği sırasına göre dener.
• musicGenerationModel: ya bir dizeyi ("provider/model") ya da bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Paylaşılan müzik üretme yeteneği ve yerleşik music_generate aracı tarafından kullanılır.
  • Tipik değerler: google/lyria-3-clip-preview, google/lyria-3-pro-preview veya minimax/music-2.6.
  • Atlanırsa music_generate yine de kimlik doğrulama destekli bir sağlayıcı varsayılanı çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından kalan kayıtlı müzik üretme sağlayıcılarını sağlayıcı kimliği sırasına göre dener.
  • Doğrudan bir sağlayıcı/model seçerseniz, eşleşen sağlayıcı kimlik doğrulamasını/API anahtarını da yapılandırın.
• videoGenerationModel: ya bir dizeyi ("provider/model") ya da bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Paylaşılan video üretme yeteneği ve yerleşik video_generate aracı tarafından kullanılır.
  • Tipik değerler: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash veya qwen/wan2.7-r2v.
  • Atlanırsa video_generate yine de kimlik doğrulama destekli bir sağlayıcı varsayılanı çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından kalan kayıtlı video üretme sağlayıcılarını sağlayıcı kimliği sırasına göre dener.
  • Doğrudan bir sağlayıcı/model seçerseniz, eşleşen sağlayıcı kimlik doğrulamasını/API anahtarını da yapılandırın.
  • Paketlenmiş Qwen video üretme sağlayıcısı en fazla 1 çıktı videosunu, 1 girdi görüntüsünü, 4 girdi videosunu, 10 saniye süreyi ve sağlayıcı düzeyi size, aspectRatio, resolution, audio ve watermark seçeneklerini destekler.
• pdfModel: ya bir dizeyi ("provider/model") ya da bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Model yönlendirmesi için pdf aracı tarafından kullanılır.
  • Atlanırsa PDF aracı imageModel değerine, ardından çözümlenmiş oturum/varsayılan modele geri döner.
• pdfMaxBytesMb: çağrı sırasında maxBytesMb geçirilmediğinde pdf aracı için varsayılan PDF boyutu sınırı.
• pdfMaxPages: pdf aracında çıkarma geri dönüş modu tarafından dikkate alınan varsayılan en fazla sayfa sayısı.
• verboseDefault: aracılar için varsayılan ayrıntı düzeyi. Değerler: "off", "on", "full". Varsayılan: "off".
• toolProgressDetail: /verbose araç özetleri ve ilerleme taslağı araç satırları için ayrıntı modu. Değerler: "explain" (varsayılan, kompakt insan etiketleri) veya "raw" (varsa ham komut/ayrıntı ekler). Aracı başına agents.list[].toolProgressDetail bu varsayılanı geçersiz kılar.
• reasoningDefault: aracılar için varsayılan akıl yürütme görünürlüğü. Değerler: "off", "on", "stream". Aracı başına agents.list[].reasoningDefault bu varsayılanı geçersiz kılar. Yapılandırılmış akıl yürütme varsayılanları, yalnızca sahipler, yetkili gönderenler veya operatör-yönetici Gateway bağlamları için, mesaj başına ya da oturum düzeyi akıl yürütme geçersiz kılması ayarlanmadığında uygulanır.
• elevatedDefault: aracılar için varsayılan yükseltilmiş çıktı düzeyi. Değerler: "off", "on", "ask", "full". Varsayılan: "on".
• model.primary: biçim provider/model (örn. OpenAI API anahtarı veya Codex OAuth erişimi için openai/gpt-5.5). Sağlayıcıyı atlarsanız OpenClaw önce bir takma ad dener, ardından tam model kimliği için benzersiz bir yapılandırılmış sağlayıcı eşleşmesi dener ve ancak bundan sonra yapılandırılmış varsayılan sağlayıcıya geri döner (kullanımdan kaldırılmış uyumluluk davranışı, bu nedenle açık provider/model tercih edin). Bu sağlayıcı artık yapılandırılmış varsayılan modeli sunmuyorsa OpenClaw eski, kaldırılmış sağlayıcı varsayılanını göstermek yerine ilk yapılandırılmış sağlayıcı/modele geri döner.
• models: /model için yapılandırılmış model kataloğu ve izin listesi. Her girdi alias (kısayol) ve params (sağlayıcıya özgü; örneğin temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody) içerebilir.
  • Güvenli düzenlemeler: girdi eklemek için openclaw config set agents.defaults.models '<json>' --strict-json --merge kullanın. config set, --replace geçirmediğiniz sürece mevcut izin listesi girdilerini kaldıracak değiştirmeleri reddeder.
  • Sağlayıcı kapsamlı yapılandırma/başlatma akışları, seçili sağlayıcı modellerini bu haritaya birleştirir ve zaten yapılandırılmış ilgisiz sağlayıcıları korur.
  • Doğrudan OpenAI Responses modelleri için sunucu tarafı compaction otomatik olarak etkinleştirilir. context_management eklemeyi durdurmak için params.responsesServerCompaction: false kullanın veya eşiği geçersiz kılmak için params.responsesCompactThreshold kullanın. Bkz. OpenAI sunucu tarafı compaction.
• params: tüm modellere uygulanan genel varsayılan sağlayıcı parametreleri. agents.defaults.params üzerinde ayarlanır (örn. { cacheRetention: "long" }).
• params birleştirme önceliği (yapılandırma): agents.defaults.params (genel taban), agents.defaults.models["provider/model"].params (model başına) tarafından geçersiz kılınır; ardından agents.list[].params (eşleşen aracı kimliği) anahtara göre geçersiz kılar. Ayrıntılar için İstem Önbelleğe Alma bölümüne bakın.
• params.extra_body/params.extraBody: OpenAI uyumlu proxy’ler için api: "openai-completions" istek gövdelerine birleştirilen gelişmiş doğrudan geçişli JSON. Üretilen istek anahtarlarıyla çakışırsa ek gövde kazanır; yerel olmayan completions rotaları yine de sonrasında yalnızca OpenAI’ye özgü store değerini çıkarır.
• params.chat_template_kwargs: üst düzey api: "openai-completions" istek gövdelerine birleştirilen vLLM/OpenAI uyumlu sohbet şablonu bağımsız değişkenleri. Düşünme kapalıyken vllm/nemotron-3-* için paketlenmiş vLLM Plugin otomatik olarak enable_thinking: false ve force_nonempty_content: true gönderir; açık chat_template_kwargs üretilen varsayılanları geçersiz kılar ve extra_body.chat_template_kwargs yine son önceliğe sahiptir. vLLM Qwen düşünme denetimleri için bu model girdisinde params.qwenThinkingFormat değerini "chat-template" veya "top-level" olarak ayarlayın.
• compat.supportedReasoningEfforts: model başına OpenAI uyumlu akıl yürütme çabası listesi. Gerçekten kabul eden özel uç noktalar için "xhigh" ekleyin; OpenClaw ardından bu yapılandırılmış sağlayıcı/model için komut menülerinde, Gateway oturum satırlarında, oturum yaması doğrulamasında, aracı CLI doğrulamasında ve llm-task doğrulamasında /think xhigh seçeneğini gösterir. Arka uç kanonik bir düzey için sağlayıcıya özgü bir değer istiyorsa compat.reasoningEffortMap kullanın.
• params.preserveThinking: korunmuş düşünme için yalnızca Z.AI’ye özgü katılım seçeneği. Etkinleştirildiğinde ve düşünme açıkken OpenClaw thinking.clear_thinking: false gönderir ve önceki reasoning_content değerini yeniden oynatır; bkz. Z.AI düşünme ve korunmuş düşünme.
• agentRuntime: varsayılan düşük düzey aracı çalışma zamanı ilkesi. Atlanan kimlik varsayılan olarak OpenClaw Pi olur. Yerleşik PI koşumunu zorlamak için id: "pi", kayıtlı Plugin koşumlarının desteklenen modelleri sahiplenmesine ve hiçbiri eşleşmediğinde PI kullanmasına izin vermek için id: "auto", bu koşumu zorunlu kılmak için id: "codex" gibi kayıtlı bir koşum kimliği veya id: "claude-cli" gibi desteklenen bir CLI arka uç takma adı kullanın. Açık Plugin çalışma zamanları, koşum kullanılamadığında veya başarısız olduğunda kapalı şekilde başarısız olur. Model referanslarını provider/model olarak kanonik tutun; Codex, Claude CLI, Gemini CLI ve diğer yürütme arka uçlarını eski çalışma zamanı sağlayıcı ön ekleri yerine çalışma zamanı yapılandırması üzerinden seçin. Bunun sağlayıcı/model seçiminden nasıl farklı olduğunu görmek için Aracı çalışma zamanları bölümüne bakın.
• Bu alanları değiştiren yapılandırma yazıcıları (örneğin /models set, /models set-image ve geri dönüş ekleme/kaldırma komutları) kanonik nesne biçimini kaydeder ve mümkün olduğunda mevcut geri dönüş listelerini korur.
• maxConcurrent: oturumlar genelinde en fazla paralel aracı çalıştırması (her oturum yine serileştirilir). Varsayılan: 4.

# agents.defaults.agentRuntime

agentRuntime, aracı dönüşlerini hangi düşük düzey yürütücünün çalıştıracağını denetler. Çoğu dağıtım varsayılan OpenClaw Pi çalışma zamanını korumalıdır. Güvenilir bir Plugin, paketlenmiş Codex uygulama sunucusu koşumu gibi yerel bir koşum sağladığında veya Claude CLI gibi desteklenen bir CLI arka ucu istediğinizde bunu kullanın. Zihinsel model için Aracı çalışma zamanları bölümüne bakın.

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• id: "auto", "pi", kayıtlı bir Plugin koşum kimliği veya desteklenen bir CLI arka uç takma adı. Paketlenmiş Codex Plugin codex değerini kaydeder; paketlenmiş Anthropic Plugin claude-cli CLI arka ucunu sağlar.
• id: "auto" kayıtlı Plugin koşumlarının desteklenen dönüşleri sahiplenmesine izin verir ve hiçbir koşum eşleşmediğinde PI kullanır. id: "codex" gibi açık bir Plugin çalışma zamanı bu koşumu gerektirir ve kullanılamazsa veya başarısız olursa kapalı şekilde başarısız olur.
• Ortam geçersiz kılması: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> bu işlem için id değerini geçersiz kılar.
• OpenAI aracı modelleri varsayılan olarak Codex koşumunu kullanır; bunu açık hale getirmek istediğinizde agentRuntime.id: "codex" geçerli kalır.
• Claude CLI dağıtımları için model: "anthropic/claude-opus-4-7" ile agentRuntime.id: "claude-cli" değerini tercih edin. Eski claude-cli/claude-opus-4-7 model referansları uyumluluk için hâlâ çalışır, ancak yeni yapılandırma sağlayıcı/model seçimini kanonik tutmalı ve yürütme arka ucunu agentRuntime.id içine koymalıdır.
• Daha eski çalışma zamanı ilkesi anahtarları openclaw doctor --fix tarafından agentRuntime olarak yeniden yazılır.
• Koşum seçimi, ilk gömülü çalıştırmadan sonra oturum kimliği başına sabitlenir. Yapılandırma/ortam değişiklikleri mevcut bir dökümü değil, yeni veya sıfırlanmış oturumları etkiler. Döküm geçmişi olan ancak kaydedilmiş sabitlemesi olmayan eski OpenAI oturumları Codex kullanır; eski OpenAI PI sabitlemeleri openclaw doctor --fix ile onarılabilir. /status etkili çalışma zamanını bildirir; örneğin Runtime: OpenClaw Pi Default veya Runtime: OpenAI Codex.
• Bu yalnızca metin aracı dönüşü yürütmesini denetler. Medya üretimi, görüntü anlama, PDF, müzik, video ve TTS hâlâ kendi sağlayıcı/model ayarlarını kullanır.

Yerleşik takma ad kısayolları (yalnızca model agents.defaults.models içinde olduğunda uygulanır):

Yapılandırılmış takma adlarınız her zaman varsayılanlara üstün gelir.

Z.AI GLM-4.x modelleri, --thinking off ayarını yapmadığınız veya agents.defaults.models["zai/<model>"].params.thinking değerini kendiniz tanımlamadığınız sürece düşünme modunu otomatik olarak etkinleştirir. Z.AI modelleri, araç çağrısı akışı için varsayılan olarak tool_stream etkinleştirir. Devre dışı bırakmak için agents.defaults.models["zai/<model>"].params.tool_stream değerini false olarak ayarlayın. Anthropic Claude 4.6 modelleri, açık bir düşünme düzeyi ayarlanmadığında varsayılan olarak adaptive düşünmeyi kullanır.

# agents.defaults.cliBackends

Yalnızca metin yedek çalıştırmaları için isteğe bağlı CLI arka uçları (araç çağrısı yok). API sağlayıcıları başarısız olduğunda yedek olarak kullanışlıdır.

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI arka uçları metin önceliklidir; araçlar her zaman devre dışıdır.
• sessionArg ayarlandığında oturumlar desteklenir.
• imageArg dosya yollarını kabul ettiğinde görüntü aktarma desteklenir.

# agents.defaults.systemPromptOverride

OpenClaw tarafından oluşturulan sistem isteminin tamamını sabit bir dizeyle değiştirin. Varsayılan düzeyde (agents.defaults.systemPromptOverride) veya ajan başına (agents.list[].systemPromptOverride) ayarlayın. Ajan başına değerler önceliklidir; boş veya yalnızca boşluk karakterlerinden oluşan değer yok sayılır. Kontrollü istem deneyleri için kullanışlıdır.

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

# agents.defaults.promptOverlays

Model ailesine göre uygulanan, sağlayıcıdan bağımsız istem katmanları. GPT-5 ailesi model kimlikleri sağlayıcılar arasında paylaşılan davranış sözleşmesini alır; personality yalnızca dostça etkileşim tarzı katmanını denetler.

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly" (varsayılan) ve "on" dostça etkileşim tarzı katmanını etkinleştirir.
• "off" yalnızca dostça katmanı devre dışı bırakır; etiketlenmiş GPT-5 davranış sözleşmesi etkin kalır.
• Eski plugins.entries.openai.config.personality, bu paylaşılan ayar belirlenmediğinde hâlâ okunur.

# agents.defaults.heartbeat

Periyodik Heartbeat çalıştırmaları.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: süre dizesi (ms/s/m/h). Varsayılan: 30m (API anahtarı kimlik doğrulaması) veya 1h (OAuth kimlik doğrulaması). Devre dışı bırakmak için 0m olarak ayarlayın.
• includeSystemPromptSection: false olduğunda, Heartbeat bölümünü sistem isteminden çıkarır ve HEARTBEAT.md dosyasının önyükleme bağlamına enjekte edilmesini atlar. Varsayılan: true.
• suppressToolErrorWarnings: true olduğunda, Heartbeat çalıştırmaları sırasında araç hata uyarısı yüklerini bastırır.
• timeoutSeconds: bir Heartbeat ajan turu iptal edilmeden önce izin verilen azami süre, saniye cinsinden. agents.defaults.timeoutSeconds kullanmak için ayarlanmamış bırakın.
• directPolicy: doğrudan/DM teslim ilkesi. allow (varsayılan) doğrudan hedefe teslimata izin verir. block doğrudan hedefe teslimatı bastırır ve reason=dm-blocked yayar.
• lightContext: true olduğunda, Heartbeat çalıştırmaları hafif önyükleme bağlamı kullanır ve çalışma alanı önyükleme dosyalarından yalnızca HEARTBEAT.md dosyasını tutar.
• isolatedSession: true olduğunda, her Heartbeat önceki konuşma geçmişi olmayan yeni bir oturumda çalışır. Cron sessionTarget: "isolated" ile aynı yalıtım kalıbı. Heartbeat başına token maliyetini yaklaşık 100K'den yaklaşık 2-5K token'a düşürür.
• skipWhenBusy: true olduğunda, Heartbeat çalıştırmaları ek meşgul hatlarda ertelenir: alt ajan veya iç içe komut işleri. Cron hatları, bu bayrak olmadan bile Heartbeat'leri her zaman erteler.
• Ajan başına: agents.list[].heartbeat ayarlayın. Herhangi bir ajan heartbeat tanımladığında, Heartbeat'leri yalnızca o ajanlar çalıştırır.
• Heartbeat'ler tam ajan turları çalıştırır; daha kısa aralıklar daha fazla token tüketir.

# agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default veya safeguard (uzun geçmişler için parçalı özetleme). Bkz. Compaction.
• provider: kayıtlı bir Compaction sağlayıcı Plugin kimliği. Ayarlandığında, yerleşik LLM özetlemesi yerine sağlayıcının summarize() işlevi çağrılır. Başarısızlıkta yerleşik olana geri döner. Sağlayıcı ayarlamak mode: "safeguard" değerini zorunlu kılar. Bkz. Compaction.
• timeoutSeconds: OpenClaw işlemi iptal etmeden önce tek bir Compaction işlemi için izin verilen azami saniye. Varsayılan: 900.
• keepRecentTokens: en güncel transkript kuyruğunu birebir tutmak için Pi kesme noktası bütçesi. Manuel /compact açıkça ayarlandığında buna uyar; aksi halde manuel Compaction sert bir kontrol noktasıdır.
• identifierPolicy: strict (varsayılan), off veya custom. strict, Compaction özetlemesi sırasında yerleşik opak tanımlayıcı saklama yönergelerini başa ekler.
• identifierInstructions: identifierPolicy=custom olduğunda kullanılan isteğe bağlı özel tanımlayıcı koruma metni.
• qualityGuard: safeguard özetleri için hatalı biçimlendirilmiş çıktı durumunda yeniden deneme denetimleri. Safeguard modunda varsayılan olarak etkindir; denetimi atlamak için enabled: false ayarlayın.
• midTurnPrecheck: isteğe bağlı Pi araç döngüsü baskı denetimi. enabled: true olduğunda, OpenClaw araç sonuçları eklendikten sonra ve sonraki model çağrısından önce bağlam baskısını denetler. Bağlam artık sığmıyorsa, istemi göndermeden önce geçerli denemeyi iptal eder ve araç sonuçlarını kırpmak veya Compaction yapıp yeniden denemek için mevcut ön denetim kurtarma yolunu yeniden kullanır. Hem default hem de safeguard Compaction modlarıyla çalışır. Varsayılan: devre dışı.
• postCompactionSections: Compaction sonrasında yeniden enjekte edilecek isteğe bağlı AGENTS.md H2/H3 bölüm adları. Varsayılan olarak ["Session Startup", "Red Lines"]; yeniden enjeksiyonu devre dışı bırakmak için [] ayarlayın. Ayarlanmamışsa veya açıkça bu varsayılan çifte ayarlanmışsa, eski Every Session/Safety başlıkları da eskiye dönük yedek olarak kabul edilir.
• model: yalnızca Compaction özetlemesi için isteğe bağlı provider/model-id geçersiz kılması. Ana oturumun bir modeli koruması, ancak Compaction özetlerinin başka bir modelde çalışması gerektiğinde bunu kullanın; ayarlanmamışsa Compaction oturumun birincil modelini kullanır.
• maxActiveTranscriptBytes: aktif JSONL eşiği aştığında bir çalıştırmadan önce normal yerel Compaction tetikleyen isteğe bağlı bayt eşiği (number veya "20mb" gibi dizeler). Başarılı Compaction'ın daha küçük bir ardıl transkripte dönebilmesi için truncateAfterCompaction gerektirir. Ayarlanmamışsa veya 0 ise devre dışıdır.
• notifyUser: true olduğunda, Compaction başladığında ve tamamlandığında kullanıcıya kısa bildirimler gönderir (örneğin, "Bağlam sıkıştırılıyor..." ve "Compaction tamamlandı"). Compaction'ı sessiz tutmak için varsayılan olarak devre dışıdır.
• memoryFlush: otomatik Compaction öncesinde kalıcı anıları saklamak için sessiz ajanik tur. Bu bakım turunun yerel bir modelde kalması gerektiğinde model değerini ollama/qwen3:8b gibi tam bir sağlayıcı/model olarak ayarlayın; geçersiz kılma etkin oturum yedek zincirini devralmaz. Çalışma alanı salt okunur olduğunda atlanır.

# agents.defaults.contextPruning

LLM'ye göndermeden önce bellek içi bağlamdan eski araç sonuçlarını budar. Diskteki oturum geçmişini değiştirmez.

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

Davranış ayrıntıları için Oturum Budama bölümüne bakın.

# Blok akışı

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Telegram dışı kanallar, blok yanıtlarını etkinleştirmek için açık *.blockStreaming: true gerektirir.
• Kanal geçersiz kılmaları: channels.<channel>.blockStreamingCoalesce (ve hesap başına varyantlar). Signal/Slack/Discord/Google Chat varsayılanı minChars: 1500.
• humanDelay: blok yanıtları arasında rastgele duraklama. natural = 800-2500 ms. Ajan başına geçersiz kılma: agents.list[].humanDelay.

Davranış ve parçalama ayrıntıları için Akış bölümüne bakın.

# Yazma göstergeleri

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Varsayılanlar: doğrudan sohbetler/bahsetmeler için instant, bahsedilmeyen grup sohbetleri için message.
• Oturum başına geçersiz kılmalar: session.typingMode, session.typingIntervalSeconds.

Bkz. Yazma Göstergeleri.

# agents.defaults.sandbox

Gömülü agent için isteğe bağlı sandbox. Tam kılavuz için bkz. Sandbox.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
plugins: {
  entries: {
    openshell: {
      enabled: true,
      config: {
        mode: "mirror", // mirror | remote
        from: "openclaw",
        remoteWorkspaceDir: "/sandbox",
        remoteAgentWorkspaceDir: "/agent",
        gateway: "lab", // optional
        gatewayEndpoint: "https://lab.example", // optional
        policy: "strict", // optional OpenShell policy id
        providers: ["openai"], // optional
        autoProviders: true,
        timeoutSeconds: 120,
      },
    },
  },
},
}

Tarayıcı sandbox’ı ve sandbox.docker.binds yalnızca Docker içindir.

Görüntüleri derleyin (kaynak checkout’tan):

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

Kaynak checkout olmadan npm kurulumları için, satır içi docker build komutları için bkz. Sandbox § Görüntüler ve kurulum.

# agents.list (agent başına geçersiz kılmalar)

Bir agent’a kendi TTS sağlayıcısını, sesini, modelini, stilini veya otomatik TTS modunu vermek için agents.list[].tts kullanın. Agent bloğu genel messages.tts üzerine derin birleştirilir; böylece paylaşılan kimlik bilgileri tek bir yerde kalırken tekil agent’lar yalnızca ihtiyaç duydukları ses veya sağlayıcı alanlarını geçersiz kılabilir. Etkin agent’ın geçersiz kılması otomatik sesli yanıtlara, /tts audio, /tts status komutlarına ve tts agent aracına uygulanır. Sağlayıcı örnekleri ve öncelik için bkz. Metinden konuşmaya.

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        agentRuntime: { id: "auto" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: kararlı ajan kimliği (zorunlu).
• default: birden fazla ayarlandığında ilk olan kazanır (uyarı günlüğe yazılır). Hiçbiri ayarlanmadıysa, listedeki ilk giriş varsayılandır.
• model: dize biçimi, model yedeği olmadan ajan başına katı bir birincil model ayarlar; nesne biçimi { primary } de fallbacks eklemediğiniz sürece katıdır. O ajanı yedeğe dahil etmek için { primary, fallbacks: [...] }, katı davranışı açıkça belirtmek için { primary, fallbacks: [] } kullanın. Yalnızca primary değerini geçersiz kılan Cron işleri, fallbacks: [] ayarlamadığınız sürece varsayılan yedekleri devralmaya devam eder.
• params: agents.defaults.models içindeki seçili model girdisinin üzerine birleştirilen ajan başına akış parametreleri. Tüm model kataloğunu çoğaltmadan cacheRetention, temperature veya maxTokens gibi ajana özel geçersiz kılmalar için bunu kullanın.
• tts: ajan başına isteğe bağlı metinden konuşmaya geçersiz kılmaları. Blok, messages.tts üzerine derin birleştirme yapar; bu nedenle paylaşılan sağlayıcı kimlik bilgilerini ve yedek politikasını messages.tts içinde tutun ve burada yalnızca sağlayıcı, ses, model, stil veya otomatik mod gibi kişiliğe özel değerleri ayarlayın.
• skills: ajan başına isteğe bağlı Skills izin listesi. Atlanırsa ajan, ayarlandığında agents.defaults.skills değerini devralır; açık bir liste, varsayılanlarla birleştirmek yerine onların yerine geçer ve [] Skills yoktur anlamına gelir.
• thinkingDefault: ajan başına isteğe bağlı varsayılan düşünme düzeyi (off | minimal | low | medium | high | xhigh | adaptive | max). Mesaj başına veya oturum geçersiz kılması ayarlanmadığında bu ajan için agents.defaults.thinkingDefault değerini geçersiz kılar. Seçili sağlayıcı/model profili hangi değerlerin geçerli olduğunu denetler; Google Gemini için adaptive, sağlayıcıya ait dinamik düşünmeyi korur (Gemini 3/3.1 üzerinde thinkingLevel atlanır, Gemini 2.5 üzerinde thinkingBudget: -1).
• reasoningDefault: ajan başına isteğe bağlı varsayılan akıl yürütme görünürlüğü (on | off | stream). Mesaj başına veya oturum akıl yürütme geçersiz kılması ayarlanmadığında bu ajan için agents.defaults.reasoningDefault değerini geçersiz kılar.
• fastModeDefault: hızlı mod için ajan başına isteğe bağlı varsayılan (true | false). Mesaj başına veya oturum hızlı mod geçersiz kılması ayarlanmadığında uygulanır.
• agentRuntime: ajan başına isteğe bağlı düşük düzey çalışma zamanı politikası geçersiz kılması. Diğer ajanlar auto modunda varsayılan PI yedeğini korurken bir ajanı yalnızca Codex yapmak için { id: "codex" } kullanın.
• runtime: ajan başına isteğe bağlı çalışma zamanı tanımlayıcısı. Ajan varsayılan olarak ACP harness oturumlarını kullanmalıysa runtime.acp varsayılanlarıyla (agent, backend, mode, cwd) birlikte type: "acp" kullanın.
• identity.avatar: çalışma alanına göreli yol, http(s) URL’si veya data: URI’si.
• identity varsayılanları türetir: emoji değerinden ackReaction, name/emoji değerinden mentionPatterns.
• subagents.allowAgents: açık sessions_spawn.agentId hedefleri için ajan kimliklerinin izin listesi (["*"] = herhangi biri; varsayılan: yalnızca aynı ajan). Kendi kendini hedefleyen agentId çağrılarına izin verilmesi gerekiyorsa istekte bulunan kimliği ekleyin.
• Sandbox devralma koruması: istekte bulunan oturum sandbox içindeyse, sessions_spawn sandbox olmadan çalışacak hedefleri reddeder.
• subagents.requireAgentId: true olduğunda, agentId atlayan sessions_spawn çağrılarını engeller (açık profil seçimini zorunlu kılar; varsayılan: false).

# Çok ajanlı yönlendirme

Tek bir Gateway içinde birden fazla yalıtılmış ajan çalıştırın. Bkz. Çok Ajanlı.

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

# Bağlama eşleşme alanları

• type (isteğe bağlı): normal yönlendirme için route (eksik tür varsayılan olarak route olur), kalıcı ACP konuşma bağlamaları için acp.
• match.channel (zorunlu)
• match.accountId (isteğe bağlı; * = herhangi bir hesap; atlanırsa = varsayılan hesap)
• match.peer (isteğe bağlı; { kind: direct|group|channel, id })
• match.guildId / match.teamId (isteğe bağlı; kanala özel)
• acp (isteğe bağlı; yalnızca type: "acp" için): { mode, label, cwd, backend }

Deterministik eşleşme sırası:

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (tam, peer/guild/team yok)
5. match.accountId: "*" (kanal genelinde)
6. Varsayılan ajan

Her katman içinde, eşleşen ilk bindings girdisi kazanır.

type: "acp" girdileri için OpenClaw, tam konuşma kimliğine göre (match.channel + hesap + match.peer.id) çözümler ve yukarıdaki route bağlama katman sırasını kullanmaz.

# Ajan başına erişim profilleri

{
agents: {
  list: [
    {
      id: "personal",
      workspace: "~/.openclaw/workspace-personal",
      sandbox: { mode: "off" },
    },
  ],
},
}

{
agents: {
  list: [
    {
      id: "family",
      workspace: "~/.openclaw/workspace-family",
      sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
      tools: {
        allow: [
          "read",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
      },
    },
  ],
},
}

{
agents: {
  list: [
    {
      id: "public",
      workspace: "~/.openclaw/workspace-public",
      sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
      tools: {
        allow: [
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
          "whatsapp",
          "telegram",
          "slack",
          "discord",
          "gateway",
        ],
        deny: [
          "read",
          "write",
          "edit",
          "apply_patch",
          "exec",
          "process",
          "browser",
          "canvas",
          "nodes",
          "cron",
          "gateway",
          "image",
        ],
      },
    },
  ],
},
}

Öncelik ayrıntıları için Çoklu Aracı Sandbox ve Araçlar bölümüne bakın.

# Oturum

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

# Mesajlar

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "steer",
        telegram: "steer",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

# Yanıt öneki

Kanal/hesap başına geçersiz kılmalar: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix.

Çözümleme (en özel olan kazanır): hesap → kanal → genel. "" devre dışı bırakır ve kademeyi durdurur. "auto" [{identity.name}] değerini türetir.

Şablon değişkenleri:

Değişkenler büyük/küçük harfe duyarsızdır. {think}, {thinkingLevel} için bir takma addır.

# Onay tepkisi

• Varsayılan olarak etkin aracının identity.emoji değeri, aksi halde "👀". Devre dışı bırakmak için "" olarak ayarlayın.
• Kanal başına geçersiz kılmalar: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Çözümleme sırası: hesap → kanal → messages.ackReaction → kimlik geri dönüşü.
• Kapsam: group-mentions (varsayılan), group-all, direct, all.
• removeAckAfterReply: Slack, Discord, Telegram, WhatsApp ve BlueBubbles gibi tepki destekli kanallarda yanıttan sonra onayı kaldırır.
• messages.statusReactions.enabled: Slack, Discord ve Telegram üzerinde yaşam döngüsü durum tepkilerini etkinleştirir. Slack ve Discord üzerinde, ayarlanmamış değer onay tepkileri etkin olduğunda durum tepkilerini etkin tutar. Telegram üzerinde, yaşam döngüsü durum tepkilerini etkinleştirmek için bunu açıkça true olarak ayarlayın.

# Gelen mesaj geciktirme

Aynı gönderenden hızla gelen yalnızca metin mesajlarını tek bir aracı turunda toplar. Medya/ekler hemen boşaltılır. Denetim komutları geciktirmeyi atlar.

# TTS (metinden sese)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
        microsoft: {
          voice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
      },
    },
  },
}

• auto, varsayılan otomatik TTS modunu denetler: off, always, inbound veya tagged. /tts on|off yerel tercihleri geçersiz kılabilir ve /tts status etkin durumu gösterir.
• summaryModel, otomatik özet için agents.defaults.model.primary değerini geçersiz kılar.
• modelOverrides varsayılan olarak etkindir; modelOverrides.allowProvider varsayılan olarak false olur (tercihe bağlı etkinleştirme).
• API anahtarları ELEVENLABS_API_KEY/XI_API_KEY ve OPENAI_API_KEY değerlerine geri döner.
• Paketle gelen konuşma sağlayıcıları Plugin’e aittir. plugins.allow ayarlanmışsa, kullanmak istediğiniz her TTS sağlayıcı Plugin’ini ekleyin; örneğin Edge TTS için microsoft. Eski edge sağlayıcı kimliği, microsoft için takma ad olarak kabul edilir.
• providers.openai.baseUrl, OpenAI TTS uç noktasını geçersiz kılar. Çözümleme sırası yapılandırma, ardından OPENAI_TTS_BASE_URL, ardından https://api.openai.com/v1 şeklindedir.
• providers.openai.baseUrl OpenAI olmayan bir uç noktayı gösterdiğinde OpenClaw bunu OpenAI uyumlu bir TTS sunucusu olarak ele alır ve model/ses doğrulamasını gevşetir.

# Talk

Talk modu için varsayılanlar (macOS/iOS/Android).

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime",
          voice: "alloy",
        },
      },
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• Birden fazla Talk sağlayıcısı yapılandırıldığında talk.provider, talk.providers içindeki bir anahtarla eşleşmelidir.
• Eski düz Talk anahtarları (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) yalnızca uyumluluk içindir. Kalıcı yapılandırmayı talk.providers.<provider> biçimine yeniden yazmak için openclaw doctor --fix çalıştırın.
• Ses kimlikleri ELEVENLABS_VOICE_ID veya SAG_VOICE_ID değerlerine geri döner.
• providers.*.apiKey düz metin dizelerini veya SecretRef nesnelerini kabul eder.
• ELEVENLABS_API_KEY geri dönüşü yalnızca hiçbir Talk API anahtarı yapılandırılmadığında uygulanır.
• providers.*.voiceAliases, Talk yönergelerinin kolay adlar kullanmasını sağlar.
• providers.mlx.modelId, macOS yerel MLX yardımcısı tarafından kullanılan Hugging Face deposunu seçer. Atlanırsa macOS mlx-community/Soprano-80M-bf16 kullanır.
• macOS MLX oynatma, varsa paketle gelen openclaw-mlx-tts yardımcısı üzerinden veya PATH üzerindeki bir çalıştırılabilir dosya üzerinden çalışır; OPENCLAW_MLX_TTS_BIN geliştirme için yardımcı yolunu geçersiz kılar.
• speechLocale, iOS/macOS Talk konuşma tanıma tarafından kullanılan BCP 47 yerel ayar kimliğini ayarlar. Aygıt varsayılanını kullanmak için ayarlamadan bırakın.
• silenceTimeoutMs, Talk modunun kullanıcı sessizliğinden sonra transkripti göndermeden önce ne kadar bekleyeceğini denetler. Ayarlanmamış değer platform varsayılan duraklama penceresini korur (macOS ve Android üzerinde 700 ms, iOS üzerinde 900 ms).

# İlgili

• Yapılandırma başvurusu — diğer tüm yapılandırma anahtarları
• Yapılandırma — yaygın görevler ve hızlı kurulum
• Yapılandırma örnekleri