Yapılandırma — ajanlar

​

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, weather devralır
      { id: "docs", skills: ["docs-search"] }, // varsayılanların yerini alır
      { id: "locked-down", skills: [] }, // hiç Skill yok
    ],
  },
}

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

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "continuation-skip": güvenli devam turları (tamamlanmış bir asistan yanıtından sonra), çalışma alanı bootstrap yeniden enjeksiyonunu atlar ve istem boyutunu azaltır. Heartbeat çalıştırmaları ve Compaction sonrası yeniden denemeler yine bağlamı yeniden oluşturur.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": sistem istemine asla uyarı metni enjekte etmez.
• "once": benzersiz her kesme imzası için uyarıyı bir kez enjekte eder (önerilir).
• "always": kesme mevcut olduğunda her çalıştırmada uyarıyı enjekte eder.

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

​

Bağlam bütçesi sahiplik eşlemesi

• 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 /new ve /reset başlangıç önsözü.
• 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ına ait bloklar.
• memory.qmd.limits.*: dizinlenmiş bellek arama parçacığı ve enjeksiyon boyutlandırması.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].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,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

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

​

agents.list[].contextLimits

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

​

skills.limits.maxSkillsPromptChars

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

​

agents.list[].skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

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"],
      },
      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
      embeddedHarness: {
        runtime: "auto", // auto | pi | kayıtlı harness kimliği, ör. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: string ("provider/model") veya nesne ({ primary, fallbacks }) kabul eder.
  • String biçimi yalnızca birincil modeli ayarlar.
  • Nesne biçimi, birincil modeli ve sıralı failover modellerini ayarlar.
• imageModel: string ("provider/model") veya nesne ({ primary, fallbacks }) kabul eder.
  • image araç yolu tarafından vision-model yapılandırması olarak kullanılır.
  • Seçilen/varsayılan model görsel girdiyi kabul edemediğinde fallback yönlendirme için de kullanılır.
• imageGenerationModel: string ("provider/model") veya nesne ({ primary, fallbacks }) kabul eder.
  • Paylaşılan görsel üretim yeteneği ve gelecekte görsel üreten tüm araç/Plugin yüzeyleri tarafından kullanılır.
  • Tipik değerler: yerel Gemini görsel üretimi için google/gemini-3.1-flash-image-preview, fal için fal/fal-ai/flux/dev veya OpenAI Images için openai/gpt-image-2.
  • Bir sağlayıcı/modeli doğrudan seçerseniz eşleşen sağlayıcı kimlik doğrulamasını da yapılandırın (google/* için GEMINI_API_KEY veya GOOGLE_API_KEY, openai/gpt-image-2 için OPENAI_API_KEY veya OpenAI Codex OAuth, fal/* için FAL_KEY gibi).
  • Belirtilmezse image_generate yine de auth destekli bir sağlayıcı varsayılanını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, sonra sağlayıcı kimliği sırasına göre kalan kayıtlı görsel üretim sağlayıcılarını dener.
• musicGenerationModel: string ("provider/model") veya nesne ({ primary, fallbacks }) kabul eder.
  • Paylaşılan müzik üretim 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.5+.
  • Belirtilmezse music_generate yine de auth destekli bir sağlayıcı varsayılanını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, sonra sağlayıcı kimliği sırasına göre kalan kayıtlı müzik üretim sağlayıcılarını 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.
• videoGenerationModel: string ("provider/model") veya nesne ({ primary, fallbacks }) kabul eder.
  • Paylaşılan video üretim 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.
  • Belirtilmezse video_generate yine de auth destekli bir sağlayıcı varsayılanını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, sonra sağlayıcı kimliği sırasına göre kalan kayıtlı video üretim sağlayıcılarını 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.
  • Paketlenmiş Qwen video üretim sağlayıcısı en fazla 1 çıktı videosu, 1 giriş görseli, 4 giriş videosu, 10 saniye süre ve sağlayıcı düzeyinde size, aspectRatio, resolution, audio ve watermark seçeneklerini destekler.
• pdfModel: string ("provider/model") veya nesne ({ primary, fallbacks }) kabul eder.
  • pdf aracı tarafından model yönlendirmesi için kullanılır.
  • Belirtilmezse PDF aracı önce imageModel, sonra çözümlenmiş oturum/varsayılan modele geri düşer.
• pdfMaxBytesMb: çağrı sırasında maxBytesMb geçilmediğinde pdf aracı için varsayılan PDF boyut sınırı.
• pdfMaxPages: pdf aracında çıkarım fallback modu tarafından dikkate alınan varsayılan azami sayfa sayısı.
• verboseDefault: ajanlar için varsayılan verbose düzeyi. Değerler: "off", "on", "full". Varsayılan: "off".
• elevatedDefault: ajanlar için varsayılan elevated-output düzeyi. Değerler: "off", "on", "ask", "full". Varsayılan: "on".
• model.primary: biçim provider/model (ör. API anahtarı erişimi için openai/gpt-5.4 veya Codex OAuth için openai-codex/gpt-5.5). Sağlayıcıyı belirtmezseniz OpenClaw önce takma adı, sonra tam model kimliği için benzersiz yapılandırılmış sağlayıcı eşleşmesini dener ve ancak ondan sonra yapılandırılmış varsayılan sağlayıcıya geri düşer (kullanımdan kaldırılmış uyumluluk davranışı, bu yüzden 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üşer.
• 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) içerebilir.
  • Güvenli düzenlemeler: girdiler eklemek için openclaw config set agents.defaults.models '<json>' --strict-json --merge kullanın. config set, siz --replace geçmedikçe mevcut izin listesi girdilerini kaldıracak değiştirmeleri reddeder.
  • Sağlayıcı kapsamlı configure/onboarding akışları seçilen sağlayıcı modellerini bu eşlemeye birleştirir ve önceden yapılandırılmış ilgisiz sağlayıcıları korur.
  • Doğrudan OpenAI Responses modelleri için sunucu tarafı Compaction otomatik etkinleştirilir. context_management enjeksiyonunu 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 altında ayarlanır (ö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, sonra agents.list[].params (eşleşen ajan kimliği) anahtar bazında geçersiz kılar. Ayrıntılar için İstem Önbellekleme bölümüne bakın.
• embeddedHarness: varsayılan düşük düzey gömülü ajan çalışma zamanı politikası. Kayıtlı Plugin harness’lerinin desteklenen modelleri sahiplenmesine izin vermek için runtime: "auto", yerleşik PI harness’ini zorlamak için runtime: "pi" veya runtime: "codex" gibi kayıtlı bir harness kimliği kullanın. Otomatik PI fallback’ini devre dışı bırakmak için fallback: "none" ayarlayın.
• Bu alanları değiştiren yapılandırma yazarları (örneğin /models set, /models set-image ve fallback ekleme/kaldırma komutları) mümkün olduğunda kanonik nesne biçimini kaydeder ve mevcut fallback listelerini korur.
• maxConcurrent: oturumlar genelinde eşzamanlı en fazla ajan çalıştırması (her oturum yine serileştirilir). Varsayılan: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi" veya kayıtlı bir Plugin harness kimliği. Paketlenmiş Codex Plugin’i codex kaydeder.
• fallback: "pi" veya "none". "pi", hiçbir Plugin harness seçilmediğinde yerleşik PI harness’ini uyumluluk fallback’i olarak tutar. "none", eksik veya desteklenmeyen Plugin harness seçiminin PI kullanmak yerine başarısız olmasını sağlar. Seçilen Plugin harness hataları her zaman doğrudan yüzeye çıkar.
• Ortam geçersiz kılmaları: OPENCLAW_AGENT_RUNTIME=<id|auto|pi>, runtime değerini geçersiz kılar; OPENCLAW_AGENT_HARNESS_FALLBACK=none, o süreç için PI fallback’ini devre dışı bırakır.
• Yalnızca Codex dağıtımları için model: "openai/gpt-5.5", embeddedHarness.runtime: "codex" ve embeddedHarness.fallback: "none" ayarlayın.
• Harness seçimi ilk gömülü çalıştırmadan sonra oturum kimliği başına sabitlenir. Yapılandırma/env değişiklikleri mevcut bir transkripti değil, yeni veya sıfırlanmış oturumları etkiler. Transkript geçmişi olan ama kaydedilmiş sabitlemesi olmayan eski oturumlar PI’ye sabitlenmiş kabul edilir. /status, Fast yanında codex gibi PI dışı harness kimliklerini gösterir.
• Bu yalnızca gömülü sohbet harness’ini kontrol eder. Medya üretimi, vision, PDF, müzik, video ve TTS yine kendi sağlayıcı/model ayarlarını kullanır.

​

agents.defaults.cliBackends

{
  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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI backend’leri öncelikle metindir; araçlar her zaman devre dışıdır.
• sessionArg ayarlı olduğunda oturumlar desteklenir.
• imageArg, dosya yollarını kabul ettiğinde görsel aktarımı desteklenir.

​

agents.defaults.systemPromptOverride

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

​

agents.defaults.promptOverlays

{
  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; etiketli GPT-5 davranış sözleşmesi etkin kalır.
• Eski plugins.entries.openai.config.personality, bu paylaşılan ayar belirtilmediğinde yine okunur.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m devre dışı bırakır
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // varsayılan: true; false, sistem istemindeki Heartbeat bölümünü çıkarır
        lightContext: false, // varsayılan: false; true, çalışma alanı bootstrap dosyalarından yalnızca HEARTBEAT.md dosyasını tutar
        isolatedSession: false, // varsayılan: false; true, her Heartbeat'i yeni bir oturumda çalıştırır (konuşma geçmişi yok)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (varsayılan) | block
        target: "none", // varsayılan: none | seçenekler: 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 ayarlayın.
• includeSystemPromptSection: false olduğunda sistem isteminden Heartbeat bölümünü çıkarır ve bootstrap bağlamına HEARTBEAT.md enjeksiyonunu atlar. Varsayılan: true.
• suppressToolErrorWarnings: true olduğunda Heartbeat çalıştırmaları sırasında araç hata uyarısı payload’larını bastırır.
• timeoutSeconds: bir Heartbeat ajan turu iptal edilmeden önce izin verilen azami süre saniye cinsinden. Belirtilmezse agents.defaults.timeoutSeconds kullanılır.
• directPolicy: doğrudan/DM teslim politikası. allow (varsayılan) doğrudan hedef teslimine izin verir. block doğrudan hedef teslimini bastırır ve reason=dm-blocked yayar.
• lightContext: true olduğunda Heartbeat çalıştırmaları hafif bootstrap bağlamı kullanır ve çalışma alanı bootstrap dosyalarından yalnızca HEARTBEAT.md dosyasını tutar.
• isolatedSession: true olduğunda her Heartbeat yeni bir oturumda, önceki konuşma geçmişi olmadan çalışır. Cron sessionTarget: "isolated" ile aynı yalıtım deseni. Heartbeat başına token maliyetini ~100K’dan ~2-5K token’a düşürür.
• Ajan başına: agents.list[].heartbeat ayarlayın. Herhangi bir ajan heartbeat tanımlarsa yalnızca o ajanlar Heartbeat çalıştırır.
• Heartbeat’ler tam ajan turları çalıştırır — daha kısa aralıklar daha fazla token yakar.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // kayıtlı bir Compaction sağlayıcı Plugin'inin kimliği (isteğe bağlı)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // identifierPolicy=custom olduğunda kullanılır
        postCompactionSections: ["Session Startup", "Red Lines"], // [] yeniden enjeksiyonu devre dışı bırakır
        model: "openrouter/anthropic/claude-sonnet-4-6", // yalnızca Compaction için isteğe bağlı model geçersiz kılması
        notifyUser: true, // Compaction başladığında ve tamamlandığında kısa bildirimler gönderir (varsayılan: false)
        memoryFlush: {
          enabled: true,
          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’inin kimliği. Ayarlandığında, yerleşik LLM özetlemesi yerine sağlayıcının summarize() fonksiyonu çağrılır. Başarısızlıkta yerleşik olana geri düşer. Bir sağlayıcı ayarlamak mode: "safeguard" zorlar. Bkz. Compaction.
• timeoutSeconds: OpenClaw’ın iptal etmesinden önce tek bir Compaction işlemi için izin verilen azami saniye. Varsayılan: 900.
• identifierPolicy: strict (varsayılan), off veya custom. strict, Compaction özetlemesi sırasında yerleşik opak tanımlayıcı koruma yönlendirmesini başa ekler.
• identifierInstructions: identifierPolicy=custom olduğunda kullanılan isteğe bağlı özel tanımlayıcı koruma metni.
• postCompactionSections: Compaction sonrasında yeniden enjekte edilecek isteğe bağlı AGENTS.md H2/H3 bölüm adları. Varsayılan ["Session Startup", "Red Lines"]; devre dışı bırakmak için [] ayarlayın. Ayarlı değilse veya açıkça bu varsayılan çift ayarlanmışsa, eski Every Session/Safety başlıkları da legacy fallback olarak kabul edilir.
• model: yalnızca Compaction özetlemesi için isteğe bağlı provider/model-id geçersiz kılması. Ana oturum bir modeli korurken Compaction özetlerinin başka bir modelde çalışmasını istiyorsanız bunu kullanın; belirtilmezse Compaction oturumun birincil modelini kullanır.
• notifyUser: true olduğunda Compaction başladığında ve tamamlandığında kullanıcıya kısa bildirimler gönderir (örneğin “Compacting context…” ve “Compaction complete”). Varsayılan olarak kapalıdır, böylece Compaction sessiz kalır.
• memoryFlush: otomatik Compaction öncesinde dayanıklı anıları saklamak için sessiz ajanik tur. Çalışma alanı salt okunursa atlanır.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // süre (ms/s/m/h), varsayılan birim: dakika
        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"] },
      },
    },
  },
}

​

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 (minMs/maxMs kullanın)
    },
  }
}

• Telegram dışındaki 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 kullanır.
• humanDelay: blok yanıtları arasında rastgele gecikme. natural = 800–2500ms. Ajan başına geçersiz kılma: agents.list[].humanDelay.

​

Yazıyor göstergeleri

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

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

​

agents.defaults.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",
          // SecretRef / 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", // mirror | remote
          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 politika kimliği
          providers: ["openai"], // isteğe bağlı
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # ana sandbox image'ı
scripts/sandbox-browser-setup.sh   # isteğe bağlı browser image'ı

​

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

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // veya { primary, fallbacks }
        thinkingDefault: "high", // ajan başına thinking düzeyi geçersiz kılması
        reasoningDefault: "on", // ajan başına reasoning görünürlüğü geçersiz kılması
        fastModeDefault: false, // ajan başına hızlı mod geçersiz kılması
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // eşleşen defaults.models parametrelerini anahtar bazında geçersiz kılar
        skills: ["docs-search"], // ayarlandığında agents.defaults.skills değerinin yerini alır
        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 (gerekli).
• default: birden fazla ayarlanmışsa ilki kazanır (uyarı günlüğe yazılır). Hiçbiri ayarlı değilse ilk liste girdisi varsayılandır.
• model: string biçimi yalnızca primary değerini geçersiz kılar; nesne biçimi { primary, fallbacks } her ikisini de geçersiz kılar ([] genel fallback’leri devre dışı bırakır). Yalnızca primary geçersiz kılan Cron işleri, siz fallbacks: [] ayarlamadıkça varsayılan fallback’leri yine devralır.
• params: agents.defaults.models içindeki seçili model girdisi üzerine birleştirilen ajan başına akış parametreleri. Tüm model kataloğunu çoğaltmadan cacheRetention, temperature veya maxTokens gibi ajana özgü geçersiz kılmalar için bunu kullanın.
• skills: isteğe bağlı ajan başına Skill izin listesi. Belirtilmezse ajan, ayarlıysa agents.defaults.skills değerini devralır; açık bir liste varsayılanlarla birleşmek yerine onların yerini alır ve [] hiç Skill olmadığını belirtir.
• thinkingDefault: isteğe bağlı ajan başına varsayılan thinking düzeyi (off | minimal | low | medium | high | xhigh | adaptive | max). Mesaj başına veya oturum geçersiz kılması ayarlı değilse bu ajan için agents.defaults.thinkingDefault değerini geçersiz kılar.
• reasoningDefault: isteğe bağlı ajan başına varsayılan reasoning görünürlüğü (on | off | stream). Mesaj başına veya oturum reasoning geçersiz kılması ayarlı değilse uygulanır.
• fastModeDefault: hızlı mod için isteğe bağlı ajan başına varsayılan (true | false). Mesaj başına veya oturum hızlı mod geçersiz kılması ayarlı değilse uygulanır.
• embeddedHarness: isteğe bağlı ajan başına düşük düzey harness politikası geçersiz kılması. Bir ajanı yalnızca Codex yaparken diğer ajanları varsayılan PI fallback ile bırakmak için { runtime: "codex", fallback: "none" } kullanın.
• runtime: isteğe bağlı ajan başına çalışma zamanı tanımlayıcısı. Ajan varsayılan olarak ACP harness oturumlarını kullanacaksa 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ğerlerinden mentionPatterns.
• subagents.allowAgents: sessions_spawn için ajan kimliği izin listesi (["*"] = herhangi biri; varsayılan: yalnızca aynı ajan).
• Sandbox devralma koruması: istek yapan oturum sandbox içindeyse sessions_spawn, sandbox olmadan çalışacak hedefleri reddeder.
• subagents.requireAgentId: true olduğunda agentId belirtilmeyen sessions_spawn çağrılarını engeller (açık profil seçimini zorlar; varsayılan: false).

​

Çoklu ajan yönlendirmesi

{
  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 (eksik type, varsayılan olarak route olur), kalıcı ACP konuşma bağlamaları için acp.
• match.channel (gerekli)
• match.accountId (isteğe bağlı; * = herhangi bir hesap; belirtilmezse 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şleşme, peer/guild/team yok)
5. match.accountId: "*" (kanal genelinde)
6. Varsayılan ajan

​

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

​

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",
    parentForkMaxTokens: 100000, // bu token sayısının üstünde üst konu fork'u atlanır (0 devre dışı bırakır)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // süre veya false
      maxDiskBytes: "500mb", // isteğe bağlı sabit bütçe
      highWaterBytes: "400mb", // isteğe bağlı temizleme hedefi
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // varsayılan hareketsizlik sonrası otomatik unfocus süresi saat cinsinden (`0` devre dışı bırakır)
      maxAgeHours: 0, // varsayılan sabit azami yaş saat cinsinden (`0` devre dışı bırakır)
    },
    mainKey: "main", // eski alan (çalışma zamanı her zaman "main" kullanır)
    agentToAgent: { maxPingPongTurns: 5 },
    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
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 devre dışı bırakır
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Yanıt öneki

​

Ack tepkisi

• Varsayılan olarak etkin ajanın identity.emoji değeri kullanılır, aksi halde "👀". 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 fallback’i.
• Kapsam: group-mentions (varsayılan), group-all, direct, all.
• removeAckAfterReply: Slack, Discord ve Telegram’da yanıttan sonra ack’i kaldırır.
• messages.statusReactions.enabled: Slack, Discord ve Telegram’da yaşam döngüsü durum tepkilerini etkinleştirir. Slack ve Discord’da ayarsız bırakmak, ack tepkileri etkin olduğunda durum tepkilerini etkin tutar. Telegram’da yaşam döngüsü durum tepkilerini etkinleştirmek için bunu açıkça true yapın.

​

Gelen debounce

​

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",
      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,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• auto, varsayılan otomatik TTS modunu kontrol eder: 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 değerindedir (opt-in).
• API anahtarları ELEVENLABS_API_KEY/XI_API_KEY ve OPENAI_API_KEY değerlerine geri düşer.
• openai.baseUrl, OpenAI TTS uç noktasını geçersiz kılar. Çözümleme sırası yapılandırma, sonra OPENAI_TTS_BASE_URL, sonra https://api.openai.com/v1 şeklindedir.
• openai.baseUrl OpenAI dışı bir uç noktayı gösterdiğinde OpenClaw bunu OpenAI uyumlu bir TTS sunucusu olarak değerlendirir ve model/voice doğrulamasını gevşetir.

​

Konuşma

{
  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",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• talk.provider, birden çok Talk sağlayıcısı yapılandırıldığında 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 ve talk.providers.<provider> içine otomatik taşınır.
• Voice kimlikleri ELEVENLABS_VOICE_ID veya SAG_VOICE_ID değerlerine geri düşer.
• providers.*.apiKey, düz metin string’leri veya SecretRef nesnelerini kabul eder.
• ELEVENLABS_API_KEY fallback’i yalnızca hiçbir Talk API anahtarı yapılandırılmadığında uygulanır.
• providers.*.voiceAliases, Talk yönergelerinin dostça adlar kullanmasına izin verir.
• silenceTimeoutMs, Konuşma modunun transkripti göndermeden önce kullanıcı sessizliğinden sonra ne kadar bekleyeceğini kontrol eder. Ayarlanmazsa platformun varsayılan duraklama penceresi korunur (macOS ve Android'de 700 ms, iOS'ta 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