Yapılandırma — aracılar

​

Ajan varsayılanları

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

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

• Varsayılan olarak sınırsız Skills için agents.defaults.skills değerini belirtmeyin.
• Varsayılanları devralmak için agents.entries.*.skills değerini belirtmeyin.
• Skills olmaması için agents.entries.*.skills: [] değerini ayarlayın.
• Boş olmayan bir agents.entries.*.skills listesi, ilgili ajan için nihai kümedir; varsayılanlarla birleştirilmez.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": güvenli devam turlarında (tamamlanmış bir asistan yanıtından sonra) çalışma alanı önyüklemesinin yeniden eklenmesi atlanarak istem boyutu küçültülür. Heartbeat çalıştırmaları ve Compaction sonrası yeniden denemeler bağlamı yine yeniden oluşturur.
• "never": her turda çalışma alanı önyüklemesini ve bağlam dosyası eklemeyi devre dışı bırakır. Bunu yalnızca istem yaşam döngüsünün tamamına sahip olan ajanlar (özel bağlam motorları, kendi bağlamını oluşturan yerel çalışma zamanları veya önyüklemesiz özel iş akışları) için kullanın. Heartbeat ve Compaction kurtarma turlarında da ekleme atlanır.

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

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

Ajan başına önyükleme profili geçersiz kılmaları

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": kesilme bildirimi metnini sistem istemine hiçbir zaman eklemez.
• "once": her benzersiz kesilme imzası için bir kez kısa bir bildirim ekler.
• "always": kesilme olduğunda her çalıştırmada kısa bir bildirim ekler (önerilir).

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

​

Bağlam bütçesi sahiplik haritası

• agents.entries.*.skillsLimits.maxSkillsPromptChars
• agents.entries.*.contextInjection
• agents.entries.*.bootstrapMaxChars
• agents.entries.*.bootstrapTotalMaxChars
• agents.entries.*.contextLimits.*

​

agents.defaults.startupContext

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

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: kesilme meta verileri ve devam bildirimi eklenmeden önce varsayılan memory_get alıntı sınırı.
• memory_get, lines değerini içermediğinde OpenClaw yerleşik 120 satırlık bir pencere kullanır ve ardından memoryGetMaxChars değerini uygular.
• Canlı araç sonuçları model bağlamına göre otomatik bir sınır kullanır: 100K token’ın altında 16000 karakter, 100K+ token’da 32000 karakter ve 200K+ token’da 64000 karakter.
• postCompactionMaxChars: Compaction sonrası yenileme eklemesi sırasında kullanılan AGENTS.md alıntı sınırı.

​

agents.entries.*.contextLimits

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

​

skills.limits.maxSkillsPromptChars

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

​

agents.entries.*.skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.imageQuality

• auto: model sınırlarına ve görüntü sayısına uyarlanır.
• efficient: daha düşük token ve bayt kullanımı için daha küçük görüntüler tercih edilir.
• balanced: standart dengeli kademe kullanılır.
• high: ekran görüntüleri, diyagramlar ve belge görüntüleri için daha fazla ayrıntı korunur.

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

{
  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"],
      },
      utilityModel: "openai/gpt-5.4-mini",
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      mediaModels: {
        image: {
          primary: "openai/gpt-image-2",
          fallbacks: ["google/gemini-3.1-flash-image"],
        },
        video: {
          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
      pdfMaxMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 4,
    },
  },
}

• model: bir dizeyi ("provider/model") veya 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.
• utilityModel: kısa dahili görevler için isteğe bağlı provider/model başvurusu veya diğer adı. Şu anda oluşturulan Control UI oturum başlıklarını, Telegram DM konu başlıklarını, Discord otomatik ileti dizisi başlıklarını ve ilerleme taslağı anlatımını destekler. Ayarlanmadığında OpenClaw, varsa birincil sağlayıcının bildirdiği küçük model varsayılanını türetir (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5); aksi hâlde başlık görevleri aracının birincil modelini kullanır ve anlatım kapalı kalır. Ayrı bir yardımcı model oluşturulan başlığı hazırlayamaz veya tamamlayamazsa OpenClaw, bu başlığı birincil modelle bir kez daha dener. Pano başlıklarında otomatik yardımcı model türetme ve normal geri dönüş, etkin oturum sağlayıcısını ve kimlik doğrulama profilini kullanır; açıkça belirtilen bir yardımcı model ise yapılandırılmış sağlayıcısını/kimlik doğrulamasını korur. Alternatif yardımcı rotayı atlamak için utilityModel: "" değerini ayarlayın; pano başlığı oluşturma yine doğrudan normal oturum modeliyle devam eder. agents.entries.*.utilityModel varsayılanı geçersiz kılar, işleme özgü bir model geçersiz kılması ise her ikisine de üstün gelir. Yardımcı görevler ayrı model çağrıları yapar ve göreve özgü içeriği seçilen model sağlayıcısına gönderir. Pano başlığı oluşturma, komut olmayan ilk mesajın en fazla ilk 1.000 karakterini gönderir; anlatım ise gelen isteği ve kısa, hassas bilgileri çıkarılmış araç özetlerini gönderir. Maliyet ve veri işleme gereksinimlerinize uygun bir sağlayıcı seçin.
• imageModel: bir dizeyi ("provider/model") veya bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Etkin model görüntüleri kabul edemediğinde, image araç yolu tarafından görüntü modeli yapılandırması olarak kullanılır. Yerel görüntü destekli modeller bunun yerine yüklenen görüntü baytlarını doğrudan alır.
  • Seçilen/varsayılan model görüntü girdisini kabul edemediğinde geri dönüş yönlendirmesi olarak da kullanılır.
  • Açık provider/model başvurularını tercih edin. Yalın kimlikler uyumluluk amacıyla kabul edilir; yalın bir kimlik models.providers.*.models içindeki yapılandırılmış, görüntü destekli bir girdiyle benzersiz şekilde eşleşirse OpenClaw bunu ilgili sağlayıcıyla niteler. Birden fazla yapılandırılmış eşleşme varsa açık bir sağlayıcı öneki gerekir.
• mediaModels.image: bir dizeyi ("provider/model") veya bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Paylaşılan görüntü oluşturma yeteneği ve görüntü oluşturan gelecekteki araç/Plugin yüzeyleri tarafından kullanılır.
  • Tipik değerler: yerel Gemini görüntü oluşturma için google/gemini-3.1-flash-image, 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.
  • Bir sağlayıcı/modeli doğrudan 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ını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından kalan kayıtlı görüntü oluşturma sağlayıcılarını sağlayıcı kimliği sırasına göre dener.
• mediaModels.music: bir dizeyi ("provider/model") veya bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Paylaşılan müzik oluşturma 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ını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından kalan kayıtlı müzik oluşturma sağlayıcılarını sağlayıcı kimliği sırasına göre dener.
  • Bir sağlayıcı/modeli doğrudan seçerseniz eşleşen sağlayıcı kimlik doğrulamasını/API anahtarını da yapılandırın.
• mediaModels.video: bir dizeyi ("provider/model") veya bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Paylaşılan video oluşturma 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ını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından kalan kayıtlı video oluşturma sağlayıcılarını sağlayıcı kimliği sırasına göre dener.
  • Bir sağlayıcı/modeli doğrudan seçerseniz eşleşen sağlayıcı kimlik doğrulamasını/API anahtarını da yapılandırın.
  • Resmî Qwen video oluşturma Plugin’i en fazla 1 çıkış videosunu, 1 giriş görüntüsünü, 4 giriş videosunu, 10 saniyelik süreyi ve sağlayıcı düzeyindeki size, aspectRatio, resolution, audio ve watermark seçeneklerini destekler.
• pdfModel: bir dizeyi ("provider/model") veya bir nesneyi ({ primary, fallbacks }) kabul eder.
  • Model yönlendirmesi için pdf aracı tarafından kullanılır.
  • Atlanırsa PDF aracı önce imageModel değerine, ardından çözümlenen oturum/varsayılan modele geri döner.
• pdfMaxMb: çağrı sırasında maxBytesMb iletilmediğinde pdf aracı için varsayılan PDF boyutu sınırı.
• pdfMaxPages: pdf aracındaki ayıklama geri dönüş modunun dikkate aldığı varsayılan azami 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, kısa ve insan tarafından okunabilir etiketler) veya "raw" (varsa ham komutu/ayrıntıyı ekler). Aracı başına agents.entries.*.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.entries.*.reasoningDefault bu varsayılanı geçersiz kılar. Yapılandırılmış akıl yürütme varsayılanları, yalnızca mesaj veya oturum başına bir akıl yürütme geçersiz kılması ayarlanmamışsa sahipler, yetkili göndericiler ya da operatör-yönetici Gateway bağlamları için 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: provider/model biçimi (ör. Codex OAuth erişimi için openai/gpt-5.6-sol). Sağlayıcıyı atlarsanız OpenClaw önce bir diğer adı, ardından tam olarak bu model kimliği için yapılandırılmış sağlayıcılar arasındaki benzersiz eşleşmeyi 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, kaldırılmış sağlayıcıya ait geçersiz bir varsayılanı göstermek yerine yapılandırılmış ilk sağlayıcıya/modele geri döner.
• contextTokens: isteğe bağlı, aracı genelinde geçerli üst sınır. Daha büyük bir modelin etkin bütçesini azaltabilir ancak bir modeli yapılandırılmış veya keşfedilmiş contextTokens değerinin üzerine çıkaramaz. Tek bir doğrudan OpenAI modelini daha büyük yerel penceresine dahil etmek için bu modelde models.providers.openai.models[].contextWindow ve contextTokens değerlerini ayarlayın; bkz. OpenAI bağlam penceresi varsayılanları.
• models: yapılandırılmış diğer adlar ve model başına ayarlar. Her girdi alias (kısayol) ve params (sağlayıcıya özgü; örneğin temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, OpenRouter provider yönlendirmesi, chat_template_kwargs, extra_body/extraBody) içerebilir. Girdi eklemek model geçersiz kılmalarını kısıtlamaz.
  • Her model kimliğini elle listelemeden seçilen sağlayıcılara ait keşfedilmiş tüm modelleri göstermek için "openai/*": {} veya "vllm/*": {} gibi provider/* girdilerini kullanın.
  • Bu sağlayıcı için dinamik olarak keşfedilen her modelin aynı çalışma zamanını kullanması gerektiğinde bir provider/* girdisine agentRuntime ekleyin. Tam provider/model çalışma zamanı ilkesi yine joker karaktere üstün gelir.
  • Güvenli meta veri düzenlemeleri: girdi eklemek için openclaw config set agents.defaults.models '<json>' --strict-json --merge kullanın. --replace iletmediğiniz sürece config set, mevcut girdileri kaldıracak değiştirmeleri reddeder.
• modelPolicy.allow: açık geçersiz kılma izin listesi. Diğer adları, tam provider/model başvurularını ve openai/* veya clawrouter/anthropic/* gibi sondaki önek joker karakterlerini kabul eder. Herhangi bir modele izin vermek için bunu atlayın veya [] kullanın. agents.entries.*.modelPolicy.allow, ilgili aracının varsayılan ilkesinin yerini alır; açıkça belirtilen boş liste, bu aracı için tümüne izin verilmesini etkinleştirir.
  • Sağlayıcı kapsamlı yapılandırma/ilk katılım akışları, seçilen sağlayıcı modellerini bu haritayla birleştirir ve önceden yapılandırılmış ilgisiz sağlayıcıları korur.
  • Doğrudan OpenAI Responses modellerinde sunucu tarafı Compaction otomatik olarak etkinleştirilir. context_management eklenmesini durdurmak için params.responsesServerCompaction: false, 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 konumunda ayarlayın (ör. { cacheRetention: "long" }).
• params birleştirme önceliği (yapılandırma): agents.defaults.params (genel temel) agents.defaults.models["provider/model"].params (model başına) tarafından geçersiz kılınır, ardından agents.entries.*.params (eşleşen aracı kimliği) anahtar bazında geçersiz kılar. Ayrıntılar için İstem Önbelleğe Alma bölümüne bakın.
• models.providers.openrouter.params.provider: OpenRouter genelindeki varsayılan sağlayıcı yönlendirme ilkesi. OpenClaw bunu OpenRouter’ın istek provider nesnesine iletir; model başına agents.defaults.models["openrouter/<model>"].params.provider ve aracı parametreleri anahtar bazında geçersiz kılar. Bkz. OpenRouter sağlayıcı yönlendirmesi.
• params.extra_body/params.extraBody: OpenAI uyumlu vekiller için api: "openai-completions" istek gövdeleriyle birleştirilen gelişmiş doğrudan geçişli JSON. Oluşturulan istek anahtarlarıyla çakışırsa ek gövde üstün gelir; yerel olmayan tamamlama rotaları daha sonra yine yalnızca OpenAI’a özgü store değerini çıkarır.
• params.chat_template_kwargs: üst düzey api: "openai-completions" istek gövdeleriyle 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’i otomatik olarak enable_thinking: false ve force_nonempty_content: true gönderir; açık chat_template_kwargs oluşturulan varsayılanları geçersiz kılar ve extra_body.chat_template_kwargs yine son önceliğe sahiptir. Yapılandırılmış vLLM Qwen ve Nemotron düşünme modelleri, çok düzeyli çaba kademesi yerine ikili /think seçenekleri (off, on) sunar.
• compat.thinkingFormat: OpenAI uyumlu düşünme yükü biçemi. Together tarzı reasoning.enabled için "together", Qwen tarzı üst düzey enable_thinking için "qwen" veya vLLM gibi istek düzeyinde sohbet şablonu anahtar sözcük bağımsız değişkenlerini destekleyen Qwen ailesi arka uçlarında chat_template_kwargs.enable_thinking için "qwen-chat-template" kullanın. OpenClaw, devre dışı düşünmeyi false değerine ve etkin düşünmeyi true değerine eşler; yapılandırılmış vLLM Qwen modelleri bu biçimler için ikili /think seçenekleri sunar.
• compat.supportedReasoningEfforts: model başına OpenAI uyumlu akıl yürütme eforu listesi. Bunu gerçekten kabul eden özel uç noktalar için "xhigh" öğesini ekleyin; OpenClaw ardından yapılandırılan sağlayıcı/model için komut menülerinde, Gateway oturum satırlarında, oturum yaması doğrulamasında, ajan CLI doğrulamasında ve llm-task doğrulamasında /think xhigh öğesini sunar. Arka uç, standart bir düzey için sağlayıcıya özgü bir değer istediğinde compat.reasoningEffortMap kullanın.
• params.preserveThinking: korunan düşünme için yalnızca Z.AI’a özgü isteğe bağlı etkinleştirme. Etkinleştirildiğinde ve düşünme açıkken OpenClaw, thinking.clear_thinking: false gönderir ve önceki reasoning_content öğelerini yeniden oynatır; bkz. Z.AI düşünme ve korunan düşünme.
• localService: yerel/kendi barındırılan model sunucuları için isteğe bağlı, sağlayıcı düzeyinde süreç yöneticisi. Seçilen model bu sağlayıcıya ait olduğunda OpenClaw, healthUrl (veya baseUrl + "/models") yoklaması yapar; uç nokta çalışmıyorsa command öğesini args ile başlatır, readyTimeoutMs süresine kadar bekler ve ardından model isteğini gönderir. command mutlak bir yol olmalıdır. idleStopMs: 0, OpenClaw kapanana kadar süreci çalışır durumda tutar; pozitif bir değer, OpenClaw tarafından başlatılan süreci belirtilen sayıda milisaniye boşta kaldıktan sonra durdurur. Bkz. Yerel model hizmetleri.
• Çalışma zamanı politikası agents.defaults üzerinde değil, sağlayıcılar veya modeller üzerinde tanımlanmalıdır. Sağlayıcı genelindeki kurallar için models.providers.<provider>.agentRuntime, modele özgü kurallar için agents.defaults.models["provider/model"].agentRuntime / agents.entries.*.models["provider/model"].agentRuntime kullanın. Sağlayıcı/model öneki tek başına hiçbir zaman bir çalıştırma düzeneği seçmez. Çalışma zamanı ayarlanmamışsa veya auto ise OpenAI, yalnızca tam olarak resmî bir HTTPS Platform Responses veya ChatGPT Responses rotası kullanıldığında ve istekte kullanıcı tarafından belirtilmiş bir geçersiz kılma olmadığında Codex’i örtük olarak seçebilir. Bkz. OpenAI örtük ajan çalışma zamanı.
• 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ı), standart nesne biçiminde kaydeder ve mümkün olduğunda mevcut geri dönüş listelerini korur.
• maxConcurrent: oturumlar genelinde aynı anda çalışabilen en fazla ajan çalıştırması sayısı (her oturum yine sıralı olarak çalıştırılır). Varsayılan: 4.

​

Çalışma zamanı politikası

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id: "auto", "openclaw", kayıtlı bir plugin çalışma düzeneği kimliği veya desteklenen bir CLI arka uç diğer adı. Birlikte gelen Codex plugin’i codex kaydını yapar; birlikte gelen Anthropic plugin’i claude-cli CLI arka ucunu sağlar.
• id: "auto", kayıtlı plugin çalışma düzeneklerinin destek sözleşmelerini bildiren veya başka şekilde karşılayan etkin rotaları üstlenmesine olanak tanır ve hiçbir çalışma düzeneği eşleşmediğinde OpenClaw’ı kullanır. id: "codex" gibi açık bir plugin çalışma zamanı, söz konusu çalışma düzeneğini ve uyumlu bir etkin rotayı gerektirir; bunlardan biri kullanılamıyorsa veya yürütme başarısız olursa güvenli biçimde başarısız olur.
• id: "pi", v2026.5.22 ve önceki sürümlerden dağıtılmış yapılandırmaları korumak için yalnızca openclaw öğesinin kullanımdan kaldırılmış diğer adı olarak kabul edilir. Yeni yapılandırma openclaw kullanmalıdır.
• Çalışma zamanı önceliğinde önce tam model politikası (agents.entries.*.models["provider/model"], agents.defaults.models["provider/model"] veya models.providers.<provider>.models[]), ardından agents.entries.* / agents.defaults.models["provider/*"], son olarak models.providers.<provider>.agentRuntime konumundaki sağlayıcı genelindeki politika uygulanır.
• Tüm ajana yönelik çalışma zamanı anahtarları eskidir. agents.defaults.agentRuntime, agents.entries.*.agentRuntime, oturum çalışma zamanı sabitlemeleri ve OPENCLAW_AGENT_RUNTIME çalışma zamanı seçiminde yok sayılır. Eski değerleri kaldırmak için openclaw doctor --fix komutunu çalıştırın.
• Yazılmış bir istek geçersiz kılması bulunmayan uygun ve tam resmî HTTPS OpenAI Responses/ChatGPT rotaları, Codex çalışma düzeneğini örtük olarak kullanabilir. Sağlayıcı/model agentRuntime.id: "codex", Codex’i güvenli biçimde başarısız olan bir gereksinim hâline getirir ancak uyumsuz bir rotayı uyumlu hâle getirmez.
• Claude CLI dağıtımları için model: "anthropic/claude-opus-5" ile model kapsamlı agentRuntime.id: "claude-cli" kullanımını tercih edin. Eski claude-cli/<model> başvuruları uyumluluk amacıyla çalışmaya devam eder ancak yeni yapılandırma, sağlayıcı/model seçimini standart biçimde tutmalı ve yürütme arka ucunu sağlayıcı/model çalışma zamanı politikasına yerleştirmelidir.
• Bu yalnızca metin ajan turu yürütmesini denetler. Medya oluşturma, görüntü, PDF, müzik, video ve TTS yine kendi sağlayıcı/model ayarlarını kullanır.

​

CLI arka ucu seçimi

​

agents.defaults.promptOverlays

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

• "friendly" (varsayılan) ve "on", kullanıcı dostu etkileşim stili katmanını etkinleştirir.
• "off" yalnızca kullanıcı dostu katmanı devre dışı bırakır; etiketli GPT-5 davranış sözleşmesi etkin kalır.
• Bu paylaşılan ayar belirlenmediğinde eski plugins.entries.openai.config.personality değeri okunmaya devam eder.

​

agents.defaults.heartbeat

{
  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 skips workspace bootstrap files for heartbeat runs
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Follow the heartbeat monitor scratch context...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: süre dizesi (ms/s/m/h). Varsayılan: 30m (API anahtarıyla kimlik doğrulama) veya 1h (OAuth kimlik doğrulaması). Devre dışı bırakmak için 0m olarak ayarlayın.
• Sıklık, sistemin sahip olduğu bir Cron izleyicisi satırına yazılır. Eksik veya eski bir satırı oluşturmak için openclaw doctor --fix komutunu çalıştırın. Cron devre dışıysa zamanlanmış Heartbeat’ler çalışmaz ve Gateway başlangıçta bir uyarı günlüğe kaydeder.
• includeSystemPromptSection: false olduğunda Heartbeat bölümünü sistem isteminden çıkarır. Varsayılan: true.
• suppressToolErrorWarnings: true olduğunda Heartbeat çalıştırmaları sırasında araç hatası uyarı yüklerini engeller.
• timeoutSeconds: bir Heartbeat ajan turunun iptal edilmeden önce çalışmasına izin verilen saniye cinsinden azami süre. Ayarlanmışsa agents.defaults.timeoutSeconds değerini, aksi takdirde 600 saniyeyle sınırlandırılmış Heartbeat sıklığını kullanmak için ayarlamadan bırakın.
• directPolicy: doğrudan/DM teslimat politikası. allow (varsayılan), doğrudan hedefe teslimata izin verir. block, doğrudan hedefe teslimatı engeller ve reason=dm-blocked üretir.
• lightContext: true olduğunda Heartbeat çalıştırmaları hafif başlangıç bağlamı kullanır ve çalışma alanı başlangıç dosyalarını atlar. İzleyici karalama alanı her iki durumda da Heartbeat çalıştırıcısı tarafından eklenir.
• isolatedSession: true olduğunda her Heartbeat, önceden konuşma geçmişi olmadan yeni bir oturumda çalışır. Cron sessionTarget: "isolated" ile aynı yalıtım örüntüsüdür. Heartbeat başına token maliyetini ~100K’dan ~2-5K token’a düşürür.
• skipWhenBusy: true olduğunda Heartbeat çalıştırmaları, ilgili ajanın ek meşgul kulvarlarında ertelenir: kendi oturum anahtarlı alt ajanı veya iç içe komut çalışması. Bu bayrak olmasa bile Cron kulvarları Heartbeat’leri her zaman erteler.
• Ajan başına: agents.entries.*.heartbeat ayarını yapın. Herhangi bir ajan heartbeat tanımladığında Heartbeat’leri yalnızca bu 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)
        thinkingLevel: "low", // optional compaction-only thinking override
        timeoutSeconds: 180,
        keepRecentTokens: 50000,
        recentTurnsPreserve: 3,
        identifierPolicy: "strict", // strict | off
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
        postIndexSync: "async", // off | async | await
        postCompactionSections: ["Session Startup", "Red Lines"],
        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, // notices when compaction starts/completes and on memory-flush degradation (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          forceFlushTranscriptBytes: "2mb",
        },
      },
    },
  },
}

• mode: default veya safeguard (uzun geçmişler için parçalı özetleme). Bkz. Compaction.
• provider: kayıtlı bir Compaction sağlayıcı Plugin’inin 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ık durumunda yerleşik işlev kullanılır. Bir sağlayıcı ayarlamak mode: "safeguard" kullanımını zorunlu kılar. Bkz. Compaction.
• thinkingLevel: yalnızca gömülü OpenClaw Compaction özetleri için kullanılan isteğe bağlı düşünme düzeyi (off, minimal, low, medium, high, xhigh, adaptive, max veya ultra). Oturumun geçerli düşünme düzeyini geçersiz kılar ve seçilen Compaction modeline/çalışma zamanına göre sınırlandırılır. Oturum düzeyini devralmak için ayarlamayın. Yerel Codex app-server Compaction işlemi bu ayarı yok sayar çünkü yerel compact isteğinde işlem başına düşünme geçersiz kılması yoktur; yapılandırıldığında OpenClaw bir uyarı kaydeder.
• timeoutSeconds: OpenClaw’ın tek bir Compaction işlemini iptal etmesinden önce izin verilen azami saniye sayısı. Varsayılan: 180.
• keepRecentTokens: en son transkript kuyruğunu olduğu gibi tutmaya yönelik ajan kesme noktası bütçesi. Açıkça ayarlandığında manuel /compact buna uyar; aksi takdirde manuel Compaction kesin bir denetim noktasıdır.
• recentTurnsPreserve: koruma özetlemesinin dışında olduğu gibi tutulan en son kullanıcı/asistan dönüşlerinin sayısı. Varsayılan: 3.
• identifierPolicy: strict (varsayılan) veya off. strict, Compaction özetlemesi sırasında yerleşik opak tanımlayıcı koruma yönergelerini başa ekler.
• qualityGuard: koruma özetleri için hatalı biçimlendirilmiş çıktıda yeniden deneme kontrolleri. Koruma modunda varsayılan olarak etkindir; denetimi atlamak için enabled: false olarak ayarlayın.
• midTurnPrecheck: isteğe bağlı araç döngüsü baskısı denetimi. enabled: true olduğunda OpenClaw, araç sonuçları eklendikten sonra ve bir 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 ya da Compaction gerçekleştirip 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ışı.
• postIndexSync: Compaction sonrası oturum belleğini yeniden indeksleme modu. Varsayılan: "async". En yüksek güncellik için "await", daha düşük Compaction gecikmesi için "async" veya yalnızca oturum belleği eşitlemesi başka bir yerde gerçekleştiriliyorsa "off" kullanın.
• postCompactionSections: Compaction sonrasında yeniden eklenecek isteğe bağlı AGENTS.md H2/H3 bölüm adları. Devre dışı bırakmak için ayarlamayın veya [] kullanın.
• model: yalnızca Compaction özetlemesi için isteğe bağlı provider/model-id veya agents.defaults.models içinden yalın takma ad. Yalın takma adlar gönderimden önce çözümlenir; yapılandırılmış değişmez model kimlikleri çakışmalarda önceliğini korur. Ana oturumun bir modeli kullanmaya devam etmesi, ancak Compaction özetlerinin başka bir modelde çalışması gerektiğinde bunu kullanın; ayarlanmadığında Compaction, oturumun birincil modelini kullanır.
• truncateAfterCompaction: Compaction sonrasında etkin oturum transkriptini döndürür; böylece önceki tam transkript arşivlenmiş olarak kalırken gelecekteki dönüşler yalnızca özeti ve özetlenmemiş kuyruğu yükler. Uzun süre çalışan oturumlarda etkin transkriptin sınırsız büyümesini önler. Varsayılan: false.
• maxActiveTranscriptBytes: transkript geçmişi eşiği aştığında bir çalıştırmadan önce normal yerel Compaction işlemini tetikleyen isteğe bağlı bayt eşiği (number veya "20mb" gibi dizeler). Başarılı Compaction işleminin daha küçük bir ardıl transkripte dönebilmesi için truncateAfterCompaction gerektirir. Ayarlanmadığında veya 0 olduğunda devre dışıdır.
• notifyUser: true olduğunda kullanıcıya kısa bağlam bakımı bildirimleri gönderir: Compaction başladığında ve tamamlandığında (örneğin, “Bağlam sıkıştırılıyor…” ve “Compaction tamamlandı”) ve Compaction öncesi bellek boşaltma olanakları tükendiğinde, böylece yanıt kısıtlı bir durumda devam ettiğinde (örneğin, “Bellek bakımı geçici olarak başarısız oldu; yanıtınız sürdürülüyor.”). Bu bildirimlerin sessiz kalması için varsayılan olarak devre dışıdır.
• memoryFlush: kalıcı anıları depolamak amacıyla otomatik Compaction öncesinde gerçekleştirilen sessiz ajansal dönüş. Bu bakım dönüşünün 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 oturumun geri dönüş zincirini devralmaz. forceFlushTranscriptBytes, belirteç sayaçları güncel olmasa bile transkript boyutu eşiğe ulaştığında boşaltmayı zorunlu kılar. Çalışma alanı salt okunur olduğunda atlanır.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // kapalı (varsayılan) | cache-ttl
      },
    },
  },
}

​

Blok akışı

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph" },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off (varsayılan) | natural | custom (minMs/maxMs kullanın)
    },
  },
}

• Telegram dışındaki kanallarda blok yanıtlarını etkinleştirmek için açıkça *.streaming.block.enabled: true gerekir. QQ Bot istisnadır: streaming.block anahtarları yoktur ve channels.qqbot.streaming.mode, "off" olmadığı sürece blok yanıtlarını akışla gönderir.
• Kanal geçersiz kılmaları: channels.<channel>.streaming.block.coalesce (ve hesap başına değişkenleri). Discord, Google Chat, Mattermost, MS Teams, Signal ve Slack varsayılan olarak minChars: 1500 / idleMs: 1000 kullanır.
• blockStreamingChunk.breakPreference: tercih edilen parça sınırı ("paragraph" | "newline" | "sentence").
• humanDelay: blok yanıtları arasındaki rastgele bekleme. Varsayılan: off. natural = 800-2500ms. custom, minMs/maxMs kullanır (ayarlanmamış herhangi bir sınır için doğal aralığa geri döner). Ajan başına geçersiz kılma: agents.entries.*.humanDelay.

​

Yazma göstergeleri

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

• Varsayılanlar: doğrudan sohbetler/bahsetmeler için instant, bahsetme içermeyen grup sohbetleri için message.
• typingIntervalSeconds varsayılanı: 6.
• Ajan başına geçersiz kılma: agents.entries.*.typingMode.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off (varsayılan) | non-main | all
        backend: "docker", // docker (varsayılan) | ssh | openshell
        scope: "agent", // session | agent (varsayılan) | shared
        workspaceAccess: "none", // none (varsayılan) | 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,
          gpus: "all",
          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 / satır içi içerikler de desteklenir:
          // 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", // yansıtma (varsayılan) | uzak
          command: "openshell",
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // isteğe bağlı
          gatewayEndpoint: "https://lab.example", // isteğe bağlı
          policy: "strict", // isteğe bağlı OpenShell ilkesi kimliği
          providers: ["openai"], // isteğe bağlı
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # ana korumalı alan görüntüsü
scripts/sandbox-browser-setup.sh   # isteğe bağlı tarayıcı görüntüsü

​

agents.entries (aracı başına geçersiz kılmalar)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Ana Aracı",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // veya { primary, fallbacks }
        utilityModel: "openai/gpt-5.4-mini",
        thinkingDefault: "high", // aracı başına düşünme düzeyi geçersiz kılması
        reasoningDefault: "on", // aracı başına akıl yürütme görünürlüğü geçersiz kılması
        fastModeDefault: false, // aracı başına hızlı mod geçersiz kılması
        params: { cacheRetention: "none" }, // eşleşen defaults.models parametrelerini anahtara göre geçersiz kılar
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // ayarlandığında agents.defaults.skills değerinin yerini alır
        identity: {
          name: "Samantha",
          theme: "yardımsever tembel hayvan",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent", // kalıcı | tek seferlik
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: sabit aracı kimliği (zorunlu).
• default: birden fazla ayarlandığında ilki geçerli olur (uyarı günlüğe kaydedilir). Hiçbiri ayarlanmamışsa ilk liste girdisi varsayılandır.
• model: dize biçimi, model geri dönüşü olmadan aracı başına katı birincil model ayarlar; nesne biçimi { primary } de fallbacks eklemediğiniz sürece katıdır. Bu aracı için geri dönüşü etkinleştirmek üzere { 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: [] ayarlanmadıkça varsayılan geri dönüşleri devralmaya devam eder.
• utilityModel: oluşturulan oturum ve iş parçacığı başlıkları gibi kısa dahili görevler için isteğe bağlı aracı başına geçersiz kılma. Önce agents.defaults.utilityModel, ardından etkin oturum sağlayıcısının bildirdiği varsayılan küçük model kullanılır. Pano başlıkları, etkin normal oturum modeliyle bir kez daha denenir. Boş bir dize, pano başlığı oluşturmayı devre dışı bırakmadan bu aracı için alternatif yardımcı program yolunu atlar.
• params: agents.defaults.models içindeki seçili model girdisinin üzerine birleştirilen aracı başına akış parametreleri. Model kataloğunun tamamını çoğaltmadan cacheRetention, temperature veya maxTokens gibi aracıya özgü geçersiz kılmalar için bunu kullanın.
• tts: isteğe bağlı aracı başına metinden konuşmaya geçersiz kılmaları. Blok, tts üzerine derinlemesine birleştirilir; bu nedenle paylaşılan sağlayıcı kimlik bilgilerini ve geri dönüş politikasını tts içinde tutun ve burada yalnızca sağlayıcı, ses, model, stil veya otomatik mod gibi kişiliğe özgü değerleri ayarlayın.
• skills: isteğe bağlı aracı başına skill izin listesi. Belirtilmezse aracı, ayarlanmış olduğunda agents.defaults.skills değerini devralır; açık bir liste birleştirilmek yerine varsayılanların yerini alır ve [] hiçbir skill olmadığı anlamına gelir.
• thinkingDefault: isteğe bağlı aracı başına varsayılan düşünme düzeyi (off | minimal | low | medium | high | xhigh | adaptive | max). İleti veya oturum başına geçersiz kılma ayarlanmadığında bu aracı için agents.defaults.thinkingDefault değerini geçersiz kılar. Hangi değerlerin geçerli olduğunu seçili sağlayıcı/model profili belirler; Google Gemini için adaptive, sağlayıcının yönettiği dinamik düşünmeyi korur (Gemini 3/3.1 üzerinde thinkingLevel belirtilmez, Gemini 2.5 üzerinde thinkingBudget: -1).
• reasoningDefault: isteğe bağlı aracı başına varsayılan akıl yürütme görünürlüğü (on | off | stream). İleti veya oturum başına akıl yürütme geçersiz kılması ayarlanmadığında bu aracı için agents.defaults.reasoningDefault değerini geçersiz kılar.
• fastModeDefault: hızlı mod için isteğe bağlı aracı başına varsayılan değer ("auto" | true | false). İleti veya oturum başına hızlı mod geçersiz kılması ayarlanmadığında uygulanır.
• models: tam provider/model kimlikleriyle anahtarlanan isteğe bağlı aracı başına model kataloğu/çalışma zamanı geçersiz kılmaları. Aracı başına çalışma zamanı istisnaları için models["provider/model"].agentRuntime kullanın.
• runtime: isteğe bağlı aracı başına çalışma zamanı tanımlayıcısı. Aracının varsayılan olarak ACP koşum takımı oturumlarını kullanması gerektiğinde runtime.acp varsayılanlarıyla (agent, backend, mode, cwd) type: "acp" kullanın.
• identity.avatar: çalışma alanına göreli yol, http(s) URL’si veya data: URI’si.
• Çalışma alanına göreli yerel identity.avatar görüntü dosyaları 2 MB ile sınırlıdır. http(s) URL’leri ve data: URI’leri yerel dosya boyutu sınırına göre denetlenmez.
• identity varsayılanları türetir: emoji değerinden ackReaction, name/emoji değerlerinden mentionPatterns.
• subagents.allowAgents: açık sessions_spawn.agentId hedefleri için yapılandırılmış aracı kimliklerinin izin listesi (["*"] = yapılandırılmış herhangi bir hedef; varsayılan: yalnızca aynı aracı). Kendi kendini hedefleyen agentId çağrılarına izin verilmesi gerekiyorsa istekte bulunanın kimliğini ekleyin. Aracı yapılandırması silinmiş eski girdiler sessions_spawn tarafından reddedilir ve agents_list içinden çıkarılır; bunları temizlemek için openclaw doctor --fix çalıştırın veya bu hedefin varsayılanları devralırken oluşturulabilir kalması gerekiyorsa asgari bir agents.entries.* girdisi ekleyin.
• Korumalı alan devralma denetimi: istekte bulunan oturum korumalı alandaysa sessions_spawn, korumalı alan dışında çalışacak hedefleri reddeder.
• subagents.requireAgentId: true olduğunda agentId belirtmeyen sessions_spawn çağrılarını engeller (açık profil seçimini zorunlu kılar; varsayılan: false).
• subagents.maxConcurrent: alt aracı yürütmesindeki eşzamanlı alt aracı çalıştırmalarının azami sayısı. Varsayılan: 8.
• subagents.maxChildrenPerAgent: tek bir aracı oturumunun oluşturabileceği etkin alt öğelerin azami sayısı. Varsayılan: 5.
• subagents.maxSpawnDepth: alt aracı oluşturma için azami iç içe geçme derinliği (1-5). Varsayılan: 1 (iç içe geçme yok).
• subagents.archiveAfterMinutes: tamamlanan alt aracı durumunun arşivlenmesinden önceki süre. Varsayılan: 60.

​

Çok aracılı yönlendirme

{
  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ştirme alanları

• type (isteğe bağlı): normal yönlendirme için route (türün belirtilmemesi 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; belirtilmemesi = varsayılan hesap)
• match.peer (isteğe bağlı; { kind: direct|group|channel, id })
• match.guildId / match.teamId (isteğe bağlı; kanala özgü)
• acp (isteğe bağlı; yalnızca type: "acp" için): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (tam, eş/sunucu/ekip yok)
5. match.accountId: "*" (kanal genelinde)
6. Varsayılan aracı

​

Aracı 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",
          ],
        },
      },
    ],
  },
}

​

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 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 30 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      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)
    },
    sharing: {
      readOnly: true,
      suggest: true,
      drafts: true,
    },
    mainKey: "main", // legacy (runtime always uses "main")
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Mesajlar

{
  messages: {
    responsePrefix: "🦞", // veya "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none
    queue: {
      mode: "steer", // steer (varsayılan) | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize (varsayılan)
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 devre dışı bırakır
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Yanıt öneki

​

Onay tepkisi

• Varsayılan olarak etkin ajanın identity.emoji değerini, aksi durumda "👀" değerini kullanır. Devre dışı bırakmak için "" 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 veya off/none (onay tepkilerini tamamen devre dışı bırakır).
• messages.statusReactions.enabled: Slack, Discord, Signal, Telegram ve WhatsApp’ta yaşam döngüsü durum tepkilerini etkinleştirir. Discord’da ayarlanmamış olması, onay tepkileri etkin olduğunda durum tepkilerini etkin tutar. Slack, Signal, Telegram ve WhatsApp’ta yaşam döngüsü durum tepkilerini etkinleştirmek için bunu açıkça true olarak ayarlayın. Slack, yapılandırılmış onay tepkisini sabit tutarken ilerleme durumu için varsayılan olarak yerel asistan ileti dizisi durumunu ve dönüşümlü yükleme mesajlarını kullanır.

​

Kuyruk

• mode: bir oturum çalıştırması etkinken gelen mesajlar için kuyruk stratejisi. Varsayılan: "steer".
  • steer: yeni istemi etkin çalıştırmaya ekler.
  • followup: yeni istemi etkin çalıştırma tamamlandıktan sonra çalıştırır.
  • collect: uyumlu mesajları toplu işler ve daha sonra birlikte çalıştırır.
  • interrupt: en yeni istemi başlatmadan önce etkin çalıştırmayı iptal eder.
• debounceMs: kuyruğa alınmış/yönlendirilmiş bir mesajı göndermeden önceki gecikme. Varsayılan: 500.
• cap: çıkarma politikası uygulanmadan önceki azami kuyruk mesajı sayısı. Varsayılan: 20.
• drop: sınır aşıldığındaki strateji. "summarize" (varsayılan), kısa özetleri koruyarak en eski girdileri çıkarır; "old" en eski girdileri özetler olmadan çıkarır; "new" en yeni öğeyi reddeder.
• byChannel: sağlayıcı kimliğine göre anahtarlanan kanal başına mode geçersiz kılmaları.
• debounceMsByChannel: sağlayıcı kimliğine göre anahtarlanan kanal başına debounceMs geçersiz kılmaları.

​

Gelen ileti bekletmesi

​

Diğer mesaj anahtarları

• channels.whatsapp.responsePrefix: giden WhatsApp yanıt öneki. Doctor, kullanımdan kaldırılmış gelen messagePrefix değerini yalnızca bu kanonik değer ayarlanmamışsa buraya taşır.
• messages.visibleReplies: doğrudan, grup ve kanal konuşmalarındaki görünür kaynak yanıtlarını denetler ("message_tool" görünür çıktı için message(action=send) gerektirir; "automatic" normal yanıtları önceki gibi gönderir).
• messages.usageTemplate / messages.responseUsage: özel /usage altbilgi şablonu ve yanıt başına varsayılan kullanım modu (off | tokens | full, ayrıca tokens için eski on diğer adı).
• messages.groupChat.mentionPatterns / historyLimit: grup mesajı bahsetme tetikleyicileri ve geçmiş penceresi boyutlandırması.
• messages.suppressToolErrors: true olduğunda, kullanıcıya gösterilen ⚠️ araç hatası uyarılarını bastırır (ajan hataları bağlamda görmeye devam eder ve yeniden deneyebilir). Varsayılan: false.

​

TTS (metinden sese)

{
  tts: {
    auto: "off", // off (varsayılan) | always | inbound | tagged
    mode: "final", // final | all
    provider: "elevenlabs",
    summaryModel: "openai/gpt-5.4-mini",
    modelOverrides: { enabled: true },
    maxTextLength: 4000,
    timeoutMs: 30000,
    providers: {
      elevenlabs: {
        apiKey: "example-elevenlabs-api-key",
        baseUrl: "https://api.elevenlabs.io",
        speakerVoiceId: "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: {
        speakerVoice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
      },
      openai: {
        apiKey: "example-openai-api-key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        speakerVoice: "coral",
      },
    },
  },
}

• auto varsayılan otomatik TTS modunu denetler: off, always, inbound veya tagged. /tts on|off yerel tercihleri geçersiz kılabilir ve /tts status geçerli durumu gösterir.
• summaryModel, otomatik özetleme için agents.defaults.model.primary değerini geçersiz kılar.
• modelOverrides varsayılan olarak etkindir (enabled !== false); modelOverrides.allowProvider isteğe bağlıdır.
• 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ının sahipliği pluginlere aittir. plugins.allow ayarlanmışsa kullanmak istediğiniz her TTS sağlayıcı pluginini ekleyin; örneğin Edge TTS için microsoft. Eski edge sağlayıcı kimliği, microsoft için bir diğer 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.
• providers.openai.baseUrl, OpenAI dışı bir uç noktaya işaret ettiğinde OpenClaw bunu OpenAI uyumlu bir TTS sunucusu olarak değerlendirir ve model/ses doğrulamasını esnetir.

​

Konuşma

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_multilingual_v2",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
      instructions: "Sıcak bir üslupla konuşun ve yanıtları kısa tutun.",
      mode: "realtime", // realtime | stt-tts | transcription
      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room
      vadThreshold: 0.5,
      silenceDurationMs: 500,
      prefixPaddingMs: 300,
      reasoningEffort: "medium",
      brain: "agent-consult", // agent-consult | direct-tools | none
    },
  },
}

• Birden fazla Konuşma sağlayıcısı yapılandırıldığında talk.provider, talk.providers içindeki bir anahtarla eşleşmelidir.
• Eski düz Konuşma 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çiminde yeniden yazmak için openclaw doctor --fix komutunu çalıştırın.
• Ses kimlikleri, ELEVENLABS_VOICE_ID veya SAG_VOICE_ID değerine geri döner (macOS Konuşma istemcisi davranışı).
• providers.*.apiKey, düz metin dizelerini veya SecretRef nesnelerini kabul eder.
• ELEVENLABS_API_KEY geri dönüşü yalnızca hiçbir Konuşma API anahtarı yapılandırılmadığında uygulanır.
• providers.*.voiceAliases, Konuşma yönergelerinin kolay anlaşılır adlar kullanmasına olanak tanır.
• providers.mlx.modelId, macOS yerel MLX yardımcısının kullandığı Hugging Face deposunu seçer. Belirtilmezse macOS, mlx-community/Soprano-80M-bf16 kullanır.
• macOS MLX oynatma, mevcut olduğunda paketle gelen openclaw-mlx-tts yardımcısı veya PATH üzerindeki bir çalıştırılabilir dosya üzerinden yürütülür; OPENCLAW_MLX_TTS_BIN, geliştirme amacıyla yardımcı yolunu geçersiz kılar.
• consultThinkingLevel, Denetim Kullanıcı Arayüzü Konuşma gerçek zamanlı openclaw_agent_consult çağrılarının arkasındaki tam OpenClaw aracı çalıştırmasının düşünme düzeyini denetler. Normal oturum/model davranışını korumak için ayarlamayın.
• consultFastMode, oturumun normal hızlı mod ayarını değiştirmeden Denetim Kullanıcı Arayüzü Konuşma gerçek zamanlı danışmaları için tek seferlik bir hızlı mod geçersiz kılması ayarlar.
• speechLocale, Android, iOS ve macOS Konuşma konuşma tanımanın kullandığı BCP 47 yerel ayar kimliğini belirler. Android ayrıca gerçek zamanlı giriş transkripsiyonuna yön vermek için bunun dil bileşenini kullanır. Cihazın varsayılanını kullanmak için ayarlamayın.
• silenceTimeoutMs, Konuşma modunun kullanıcı sessizliğinden sonra transkripti göndermeden önce ne kadar bekleyeceğini denetler. Ayarlanmaması, platformun varsayılan duraklama aralığını korur (700 ms on macOS and Android, 900 ms on iOS).
• realtime.instructions, sağlayıcıya yönelik sistem talimatlarını OpenClaw’ın yerleşik gerçek zamanlı istemine ekler; böylece varsayılan openclaw_agent_consult yönlendirmesi kaybedilmeden ses stili yapılandırılabilir.
• realtime.vadThreshold, sağlayıcının ses etkinliği eşiğini 0 (en hassas) ile 1 (en az hassas) arasında ayarlar. Ayarlanmaması, sağlayıcının varsayılanını korur.
• realtime.silenceDurationMs, sağlayıcı gerçek zamanlı bir kullanıcı sırasını kesinleştirmeden önceki pozitif tam sayı sessizlik aralığını ayarlar. Ayarlanmaması, sağlayıcının varsayılanını korur.
• realtime.prefixPaddingMs, algılanan konuşma başlamadan önce tutulan negatif olmayan tam sayı ses miktarını ayarlar. Ayarlanmaması, sağlayıcının varsayılanını korur.
• realtime.reasoningEffort, gerçek zamanlı oturumlar için sağlayıcıya özgü akıl yürütme düzeyini ayarlar. Ayarlanmaması, sağlayıcının varsayılanını korur.
• realtime.consultRouting: "provider-direct" (varsayılan), gerçek zamanlı sağlayıcı openclaw_agent_consult olmadan nihai bir kullanıcı transkripti ürettiğinde doğrudan sağlayıcı yanıtlarını korur. Bunun yerine "force-agent-consult", kesinleştirilmiş isteği OpenClaw üzerinden yönlendirir.

​

İlgili

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