​

Configuration Reference

​

Kanallar

​

DM ve grup erişimi

​

Kanal model geçersiz kılmaları

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Kanal varsayılanları ve heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: bir sağlayıcı düzeyindeki groupPolicy ayarlı değilse geri dönüş grup ilkesi.
• channels.defaults.contextVisibility: tüm kanallar için varsayılan ek bağlam görünürlüğü kipi. Değerler: all (varsayılan, alıntılanan/iş parçacığı/geçmiş bağlamının tümünü dahil et), allowlist (yalnızca izin verilen gönderenlerden gelen bağlamı dahil et), allowlist_quote (allowlist ile aynı, ancak açık alıntı/yanıt bağlamını korur). Kanal başına geçersiz kılma: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: heartbeat çıktısında sağlıklı kanal durumlarını dahil et.
• channels.defaults.heartbeat.showAlerts: heartbeat çıktısında bozulmuş/hatalı durumları dahil et.
• channels.defaults.heartbeat.useIndicator: kompakt gösterge tarzı heartbeat çıktısı oluştur.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // mavi tikler (self-chat kipinde false)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (varsayılan: off; önizleme-düzenleme hız sınırlarından kaçınmak için açıkça katılım gerekir)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Bot token’ı: channels.telegram.botToken veya channels.telegram.tokenFile (yalnızca normal dosya; symlink’ler reddedilir), varsayılan hesap için TELEGRAM_BOT_TOKEN geri dönüşüyle birlikte.
• İsteğe bağlı channels.telegram.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.
• Çok hesaplı kurulumlarda (2+ hesap kimliği), geri dönüş yönlendirmesini önlemek için açık bir varsayılan ayarlayın (channels.telegram.defaultAccount veya channels.telegram.accounts.default); bu eksik veya geçersiz olduğunda openclaw doctor uyarır.
• configWrites: false, Telegram tarafından başlatılan yapılandırma yazımlarını engeller (supergroup kimlik taşıma işlemleri, /config set|unset).
• type: "acp" içeren üst düzey bindings[] girdileri forum başlıkları için kalıcı ACP bağlamalarını yapılandırır (match.peer.id içinde kanonik chatId:topic:topicId kullanın). Alan semantiği ACP Agents bölümünde paylaşılır.
• Telegram akış önizlemeleri sendMessage + editMessageText kullanır (doğrudan ve grup sohbetlerinde çalışır).
• Yeniden deneme ilkesi: bkz. Retry policy.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress, Discord üzerinde partial olarak eşlenir)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // sessions_spawn({ thread: true }) için katılımlı
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, varsayılan hesap için DISCORD_BOT_TOKEN geri dönüşüyle birlikte.
• Açık bir Discord token sağlayan doğrudan giden çağrılar, bu token’ı çağrı için kullanır; hesap yeniden deneme/ilke ayarları yine etkin çalışma zamanı anlık görüntüsünde seçilen hesaptan gelir.
• İsteğe bağlı channels.discord.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.
• Teslim hedefleri için user:<id> (DM) veya channel:<id> (guild kanalı) kullanın; yalın sayısal kimlikler reddedilir.
• Guild slug’ları küçük harftir ve boşluklar - ile değiştirilir; kanal anahtarları slug’lanmış adı kullanır (# yok). Guild kimliklerini tercih edin.
• Bot tarafından yazılan mesajlar varsayılan olarak yok sayılır. allowBots: true bunları etkinleştirir; yalnızca bottan bahseden bot mesajlarını kabul etmek için allowBots: "mentions" kullanın (kendi mesajları yine filtrelenir).
• channels.discord.guilds.<id>.ignoreOtherMentions (ve kanal geçersiz kılmaları), bottan bahsetmeyen ama başka bir kullanıcıdan veya rolden bahseden mesajları düşürür (@everyone/@here hariç).
• maxLinesPerMessage (varsayılan 17), mesaj 2000 karakterin altında olsa bile uzun mesajları böler.
• channels.discord.threadBindings, Discord iş parçacığına bağlı yönlendirmeyi denetler:
  • enabled: iş parçacığına bağlı oturum özellikleri için Discord geçersiz kılması (/focus, /unfocus, /agents, /session idle, /session max-age, ve bağlı teslim/yönlendirme)
  • idleHours: saat cinsinden hareketsizlik sonrası otomatik odak kaldırma için Discord geçersiz kılması (0 devre dışı bırakır)
  • maxAgeHours: saat cinsinden kesin maksimum yaş için Discord geçersiz kılması (0 devre dışı bırakır)
  • spawnSubagentSessions: sessions_spawn({ thread: true }) otomatik iş parçacığı oluşturma/bağlama için katılımlı anahtar
• type: "acp" içeren üst düzey bindings[] girdileri kanal ve iş parçacıkları için kalıcı ACP bağlamalarını yapılandırır (match.peer.id içinde kanal/iş parçacığı kimliği kullanın). Alan semantiği ACP Agents bölümünde paylaşılır.
• channels.discord.ui.components.accentColor, Discord components v2 kapsayıcıları için vurgu rengini ayarlar.
• channels.discord.voice, Discord ses kanalı konuşmalarını ve isteğe bağlı otomatik katılma + TTS geçersiz kılmalarını etkinleştirir.
• channels.discord.voice.daveEncryption ve channels.discord.voice.decryptionFailureTolerance, @discordjs/voice DAVE seçeneklerine geçirir (varsayılan olarak true ve 24).
• OpenClaw ayrıca tekrar eden çözme hatalarından sonra bir ses oturumundan ayrılıp yeniden katılarak ses alımını kurtarmaya da çalışır.
• channels.discord.streaming kanonik akış kipi anahtarıdır. Eski streamMode ve boolean streaming değerleri otomatik taşınır.
• channels.discord.autoPresence, çalışma zamanı kullanılabilirliğini bot varlığına eşler (sağlıklı => online, bozulmuş => idle, tükenmiş => dnd) ve isteğe bağlı durum metni geçersiz kılmalarına izin verir.
• channels.discord.dangerouslyAllowNameMatching, değişebilir ad/etiket eşleştirmesini yeniden etkinleştirir (son çare uyumluluk kipi).
• channels.discord.execApprovals: Discord-yerel exec onayı teslimi ve onaylayıcı yetkilendirmesi.
  • enabled: true, false veya "auto" (varsayılan). Otomatik kipte, onaylayıcılar approvers veya commands.ownerAllowFrom üzerinden çözümlenebildiğinde exec onayları etkinleşir.
  • approvers: exec isteklerini onaylamasına izin verilen Discord kullanıcı kimlikleri. Atlanırsa commands.ownerAllowFrom alanına geri döner.
  • agentFilter: isteğe bağlı agent kimliği izin listesi. Tüm agent’lar için onayları iletmek için atlayın.
  • sessionFilter: isteğe bağlı oturum anahtarı desenleri (alt dize veya regex).
  • target: onay istemlerinin nereye gönderileceği. "dm" (varsayılan) onaylayıcı DM’lerine gönderir, "channel" kaynak kanala gönderir, "both" ikisine de gönderir. Hedef "channel" içerdiğinde, düğmeler yalnızca çözülmüş onaylayıcılar tarafından kullanılabilir.
  • cleanupAfterResolve: true olduğunda, onay, red veya zaman aşımından sonra onay DM’lerini siler.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• Hizmet hesabı JSON’u: satır içi (serviceAccount) veya dosya tabanlı (serviceAccountFile).
• Hizmet hesabı SecretRef de desteklenir (serviceAccountRef).
• Ortam geri dönüşleri: GOOGLE_CHAT_SERVICE_ACCOUNT veya GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Teslim hedefleri için spaces/<spaceId> veya users/<userId> kullanın.
• channels.googlechat.dangerouslyAllowNameMatching, değişebilir e-posta ana prensip eşleştirmesini yeniden etkinleştirir (son çare uyumluluk kipi).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress (önizleme kipi)
      nativeStreaming: true, // streaming=partial iken Slack yerel streaming API’sini kullan
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket mode hem botToken hem appToken gerektirir (varsayılan hesap ortam geri dönüşü için SLACK_BOT_TOKEN + SLACK_APP_TOKEN).
• HTTP mode botToken artı signingSecret gerektirir (kök düzeyde veya hesap başına).
• botToken, appToken, signingSecret ve userToken düz metin dizeleri veya SecretRef nesneleri kabul eder.
• Slack hesap anlık görüntüleri botTokenSource, botTokenStatus, appTokenStatus ve HTTP kipinde signingSecretStatus gibi kimlik bilgisi başına kaynak/durum alanlarını sunar. configured_unavailable, hesabın SecretRef üzerinden yapılandırıldığı ancak geçerli komut/çalışma zamanı yolunun gizli değeri çözemediği anlamına gelir.
• configWrites: false, Slack tarafından başlatılan yapılandırma yazımlarını engeller.
• İsteğe bağlı channels.slack.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.
• channels.slack.streaming kanonik akış kipi anahtarıdır. Eski streamMode ve boolean streaming değerleri otomatik taşınır.
• Teslim hedefleri için user:<id> (DM) veya channel:<id> kullanın.

• typingReaction, bir yanıt çalışırken gelen Slack mesajına geçici bir tepki ekler, ardından tamamlandığında bunu kaldırır. "hourglass_flowing_sand" gibi bir Slack emoji kısa kodu kullanın.
• channels.slack.execApprovals: Slack-yerel exec onayı teslimi ve onaylayıcı yetkilendirmesi. Discord ile aynı şema: enabled (true/false/"auto"), approvers (Slack kullanıcı kimlikleri), agentFilter, sessionFilter ve target ("dm", "channel" veya "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // katılımlı
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Ters proxy/herkese açık dağıtımlar için isteğe bağlı açık URL
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath tam URL değil, bir yol olmalıdır (örneğin /api/channels/mattermost/command).
• commands.callbackUrl, OpenClaw gateway uç noktasına çözülmeli ve Mattermost sunucusundan erişilebilir olmalıdır.
• Yerel slash callback’leri, Mattermost tarafından slash komut kaydı sırasında döndürülen komut başına token’larla kimlik doğrular. Kayıt başarısız olursa veya etkinleştirilen komut yoksa, OpenClaw callback’leri Unauthorized: invalid command token. ile reddeder.
• Özel/tailnet/iç callback ana makineleri için Mattermost, ServiceSettings.AllowedUntrustedInternalConnections içine callback ana makinesini/alanını eklemenizi isteyebilir. Tam URL değil, ana makine/alan adı değerleri kullanın.
• channels.mattermost.configWrites: Mattermost tarafından başlatılan yapılandırma yazımlarına izin verir veya reddeder.
• channels.mattermost.requireMention: kanallarda yanıt vermeden önce @mention gerektir.
• channels.mattermost.groups.<channelId>.requireMention: kanal başına bahsetme geçidi geçersiz kılması (varsayılan için "*").
• İsteğe bağlı channels.mattermost.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // isteğe bağlı hesap bağlaması
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: kanal başlangıcını belirli bir Signal hesap kimliğine sabitler.
• channels.signal.configWrites: Signal tarafından başlatılan yapılandırma yazımlarına izin verir veya reddeder.
• İsteğe bağlı channels.signal.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, grup denetimleri ve gelişmiş eylemler:
      // bkz. /channels/bluebubbles
    },
  },
}

• Burada kapsanan çekirdek anahtar yolları: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• İsteğe bağlı channels.bluebubbles.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.
• type: "acp" içeren üst düzey bindings[] girdileri, BlueBubbles konuşmalarını kalıcı ACP oturumlarına bağlayabilir. match.peer.id içinde bir BlueBubbles handle veya hedef dizesi (chat_id:*, chat_guid:*, chat_identifier:*) kullanın. Paylaşılan alan semantiği: ACP Agents.
• Tam BlueBubbles kanal yapılandırması BlueBubbles bölümünde belgelenmiştir.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• İsteğe bağlı channels.imessage.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.
• Messages DB’si için Full Disk Access gerektirir.
• chat_id:<id> hedeflerini tercih edin. Sohbetleri listelemek için imsg chats --limit 20 kullanın.
• cliPath bir SSH sarmalayıcısını gösterebilir; SCP ek getirme işlemleri için remoteHost (host veya user@host) ayarlayın.
• attachmentRoots ve remoteAttachmentRoots, gelen ek yollarını sınırlar (varsayılan: /Users/*/Library/Messages/Attachments).
• SCP sıkı host-key kontrolü kullanır, bu nedenle relay ana makine anahtarının zaten ~/.ssh/known_hosts içinde bulunduğundan emin olun.
• channels.imessage.configWrites: iMessage tarafından başlatılan yapılandırma yazımlarına izin verir veya reddeder.
• type: "acp" içeren üst düzey bindings[] girdileri, iMessage konuşmalarını kalıcı ACP oturumlarına bağlayabilir. match.peer.id içinde normalize edilmiş bir handle veya açık bir sohbet hedefi (chat_id:*, chat_guid:*, chat_identifier:*) kullanın. Paylaşılan alan semantiği: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• Token kimlik doğrulaması accessToken kullanır; parola kimlik doğrulaması userId + password kullanır.
• channels.matrix.proxy, Matrix HTTP trafiğini açık bir HTTP(S) proxy üzerinden yönlendirir. Adlandırılmış hesaplar bunu channels.matrix.accounts.<id>.proxy ile geçersiz kılabilir.
• channels.matrix.allowPrivateNetwork, özel/iç homeserver’lara izin verir. proxy ve allowPrivateNetwork bağımsız denetimlerdir.
• channels.matrix.defaultAccount, çok hesaplı kurulumlarda tercih edilen hesabı seçer.
• channels.matrix.execApprovals: Matrix-yerel exec onayı teslimi ve onaylayıcı yetkilendirmesi.
  • enabled: true, false veya "auto" (varsayılan). Otomatik kipte, onaylayıcılar approvers veya commands.ownerAllowFrom üzerinden çözümlenebildiğinde exec onayları etkinleşir.
  • approvers: exec isteklerini onaylamasına izin verilen Matrix kullanıcı kimlikleri (ör. @owner:example.org).
  • agentFilter: isteğe bağlı agent kimliği izin listesi. Tüm agent’lar için onayları iletmek için atlayın.
  • sessionFilter: isteğe bağlı oturum anahtarı desenleri (alt dize veya regex).
  • target: onay istemlerinin nereye gönderileceği. "dm" (varsayılan), "channel" (kaynak oda) veya "both".
  • Hesap başına geçersiz kılmalar: channels.matrix.accounts.<id>.execApprovals.
• Matrix durum probe’ları ve canlı dizin aramaları, çalışma zamanı trafiğiyle aynı proxy ilkesini kullanır.
• Tam Matrix yapılandırması, hedefleme kuralları ve kurulum örnekleri Matrix bölümünde belgelenmiştir.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, takım/kanal ilkeleri:
      // bkz. /channels/msteams
    },
  },
}

• Burada kapsanan çekirdek anahtar yolları: channels.msteams, channels.msteams.configWrites.
• Tam Teams yapılandırması (kimlik bilgileri, webhook, DM/grup ilkesi, takım/kanal başına geçersiz kılmalar) Microsoft Teams bölümünde belgelenmiştir.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Burada kapsanan çekirdek anahtar yolları: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• İsteğe bağlı channels.irc.defaultAccount, yapılandırılmış bir hesap kimliğiyle eşleşiyorsa varsayılan hesap seçimini geçersiz kılar.
• Tam IRC kanal yapılandırması (host/port/TLS/kanallar/izin listeleri/bahsetme geçidi) IRC bölümünde belgelenmiştir.

​

Çok hesaplı (tüm kanallar)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• accountId atlandığında default kullanılır (CLI + yönlendirme).
• Ortam token’ları yalnızca default hesap için geçerlidir.
• Temel kanal ayarları, hesap başına geçersiz kılınmadığı sürece tüm hesaplara uygulanır.
• Her hesabı farklı bir agent’a yönlendirmek için bindings[].match.accountId kullanın.
• Tek hesaplı üst düzey kanal yapılandırmasındayken openclaw channels add (veya kanal onboarding) ile varsayılan olmayan bir hesap eklerseniz, OpenClaw önce hesap kapsamlı üst düzey tek hesap değerlerini kanal hesap eşlemesine taşır, böylece özgün hesap çalışmaya devam eder. Çoğu kanal bunları channels.<channel>.accounts.default içine taşır; Matrix bunun yerine mevcut eşleşen adlandırılmış/default hedefi koruyabilir.
• Mevcut yalnızca kanala ait bağlamalar (accountId olmadan) varsayılan hesapla eşleşmeye devam eder; hesap kapsamlı bağlamalar isteğe bağlı kalır.
• openclaw doctor --fix, hesap kapsamlı üst düzey tek hesap değerlerini o kanal için seçilen taşınmış hesaba taşıyarak karışık şekilleri de onarır. Çoğu kanal accounts.default kullanır; Matrix bunun yerine mevcut eşleşen adlandırılmış/default hedefi koruyabilir.

​

Diğer eklenti kanalları

​

Grup sohbeti bahsetme geçidi

• Meta veri bahsetmeleri: Yerel platform @-bahsetmeleri. WhatsApp self-chat kipinde yok sayılır.
• Metin desenleri: agents.list[].groupChat.mentionPatterns içindeki güvenli regex desenleri. Geçersiz desenler ve güvenli olmayan iç içe tekrarlar yok sayılır.
• Bahsetme geçidi yalnızca algılama mümkün olduğunda uygulanır (yerel bahsetmeler veya en az bir desen).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

DM geçmiş sınırları

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Self-chat kipi

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Komutlar (sohbet komutu işleme)

{
  commands: {
    native: "auto", // desteklendiğinde yerel komutları kaydet
    text: true, // sohbet mesajlarında /commands ayrıştır
    bash: false, // ! izin ver (takma ad: /bash)
    bashForegroundMs: 2000,
    config: false, // /config izin ver
    debug: false, // /debug izin ver
    restart: false, // /restart + gateway restart tool izin ver
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Agent 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 yerine geçer
      { id: "locked-down", skills: [] }, // hiç Skills yok
    ],
  },
}

• Varsayılan olarak sınırsız Skills için agents.defaults.skills alanını atlayın.
• Varsayılanları devralmak için agents.list[].skills alanını atlayın.
• Hiç Skills olmaması için agents.list[].skills: [] ayarlayın.
• Boş olmayan bir agents.list[].skills listesi, bu agent için son kümedir; varsayılanlarla birleşmez.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

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-1",
        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
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: bir dize ("provider/model") veya bir nesne ({ primary, fallbacks }) kabul eder.
  • Dize biçimi yalnızca birincil modeli ayarlar.
  • Nesne biçimi, birincil model artı sıralı failover modelleri ayarlar.
• imageModel: bir dize ("provider/model") veya bir nesne ({ primary, fallbacks }) kabul eder.
  • image tool yolu tarafından vision-model yapılandırması olarak kullanılır.
  • Ayrıca seçilen/varsayılan model görüntü girdisini kabul edemediğinde geri dönüş yönlendirmesi olarak kullanılır.
• imageGenerationModel: bir dize ("provider/model") veya bir nesne ({ primary, fallbacks }) kabul eder.
  • Paylaşılan görüntü üretim yeteneği ve görüntü üreten gelecekteki tüm tool/plugin yüzeyleri tarafından kullanılır.
  • Tipik değerler: yerel Gemini görüntü üretimi için google/gemini-3.1-flash-image-preview, fal için fal/fal-ai/flux/dev veya OpenAI Images için openai/gpt-image-1.
  • Bir sağlayıcı/modeli doğrudan seçerseniz, eşleşen sağlayıcı auth/API anahtarını da yapılandırın (örneğin google/* için GEMINI_API_KEY veya GOOGLE_API_KEY, openai/* için OPENAI_API_KEY, fal/* için FAL_KEY).
  • Atlanırsa image_generate yine de auth destekli bir sağlayıcı varsayılanını çıkarabilir. Önce geçerli varsayılan sağlayıcıyı, ardından sağlayıcı kimliği sırasıyla kayıtlı diğer görüntü üretim sağlayıcılarını dener.
• videoGenerationModel: bir dize ("provider/model") veya bir nesne ({ primary, fallbacks }) kabul eder.
  • Paylaşılan video üretim yeteneği 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.
  • Paylaşılan video üretimini kullanmadan önce bunu açıkça ayarlayın. imageGenerationModel alanından farklı olarak video üretim çalışma zamanı henüz bir sağlayıcı varsayılanı çıkarmaz.
  • Bir sağlayıcı/modeli doğrudan seçerseniz, eşleşen sağlayıcı auth/API anahtarını da yapılandırın.
  • Paketlenmiş Qwen video üretim sağlayıcısı şu anda en fazla 1 çıktı videosu, 1 girdi görüntüsü, 4 girdi videosu, 10 saniye süre ve sağlayıcı düzeyinde size, aspectRatio, resolution, audio ve watermark seçeneklerini destekler.
• pdfModel: bir dize ("provider/model") veya bir nesne ({ primary, fallbacks }) kabul eder.
  • pdf tool’u tarafından model yönlendirmesi için kullanılır.
  • Atlanırsa PDF tool’u önce imageModel, ardından çözümlenmiş oturum/varsayılan modele geri döner.
• pdfMaxBytesMb: pdf tool’unda çağrı zamanında maxBytesMb geçirilmediğinde varsayılan PDF boyut sınırı.
• pdfMaxPages: pdf tool’unda ayıklama geri dönüş kipinin dikkate aldığı varsayılan en fazla sayfa.
• verboseDefault: agent’lar için varsayılan ayrıntı düzeyi. Değerler: "off", "on", "full". Varsayılan: "off".
• elevatedDefault: agent’lar için varsayılan elevated-output düzeyi. Değerler: "off", "on", "ask", "full". Varsayılan: "on".
• model.primary: provider/model biçimi (ör. openai/gpt-5.4). Sağlayıcıyı atlayırsanız OpenClaw önce bir takma adı, ardından tam model kimliği için benzersiz yapılandırılmış bir sağlayıcı eşleşmesini dener ve yalnızca bundan sonra yapılandırılmış varsayılan sağlayıcıya geri döner (kullanım dışı uyumluluk davranışı, bu nedenle açık provider/model tercih edilir). Bu sağlayıcı artık yapılandırılmış varsayılan modeli sunmuyorsa, OpenClaw eski kaldırılmış sağlayıcı varsayılanını göstermek yerine ilk yapılandırılmış sağlayıcı/modele geri döner.
• models: /model için yapılandırılmış model kataloğu ve izin listesi. Her girdi alias (kısayol) ve params (sağlayıcıya özgü, örneğin temperature, maxTokens, cacheRetention, context1m) içerebilir.
• 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 taban), agents.defaults.models["provider/model"].params (model başına) tarafından geçersiz kılınır, ardından agents.list[].params (eşleşen agent kimliği) anahtar bazında geçersiz kılar. Ayrıntılar için Prompt Caching bölümüne bakın.
• Bu alanları değiştiren yapılandırma yazıcıları (örneğin /models set, /models set-image ve fallback ekleme/kaldırma komutları) kanonik nesne biçimini kaydeder ve mümkün olduğunda mevcut fallback listelerini korur.
• maxConcurrent: oturumlar arasında en fazla paralel agent çalıştırması (her oturum yine seri hale getirilir). Varsayılan: 4.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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 metin önceliklidir; araçlar her zaman devre dışıdır.
• sessionArg ayarlandığında oturumlar desteklenir.
• imageArg dosya yollarını kabul ettiğinde görüntü geçişi desteklenir.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m devre dışı bırakır
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        lightContext: false, // varsayılan: false; true yalnızca çalışma alanı bootstrap dosyalarından HEARTBEAT.md 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,
      },
    },
  },
}

• every: süre dizesi (ms/s/m/h). Varsayılan: 30m (API anahtarı auth) veya 1h (OAuth auth). Devre dışı bırakmak için 0m ayarlayın.
• suppressToolErrorWarnings: true olduğunda heartbeat çalıştırmalarında tool hata uyarısı payload’larını bastırır.
• directPolicy: doğrudan/DM teslim ilkesi. allow (varsayılan) doğrudan hedef teslimine izin verir. block doğrudan hedef teslimini bastırır ve reason=dm-blocked üretir.
• 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 önceki konuşma geçmişi olmadan yeni bir oturumda çalışır. Cron sessionTarget: "isolated" ile aynı yalıtım deseni. Heartbeat başına token maliyetini ~100K’den ~2-5K tokene düşürür.
• Agent başına: agents.list[].heartbeat ayarlayın. Herhangi bir agent heartbeat tanımlarsa, heartbeat yalnızca o agent’lar için çalışır.
• Heartbeat’ler tam agent turları çalıştırır — daha kısa aralıklar daha fazla token harcar.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // identifierPolicy=custom iken kullanılır
        postCompactionSections: ["Session Startup", "Red Lines"], // [] yeniden eklemeyi devre dışı bırakır
        model: "openrouter/anthropic/claude-sonnet-4-6", // isteğe bağlı yalnızca compaction modeli geçersiz kılması
        notifyUser: true, // sıkıştırma başladığında kısa bildirim gönder (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.
• timeoutSeconds: OpenClaw’un tek bir sıkıştırma işlemi için iptal etmeden önce izin verdiği en fazla saniye. Varsayılan: 900.
• identifierPolicy: strict (varsayılan), off veya custom. strict, sıkıştırma özetlemesi sırasında yerleşik opak tanımlayıcı koruma yönlendirmesini başa ekler.
• identifierInstructions: identifierPolicy=custom iken kullanılan isteğe bağlı özel tanımlayıcı koruma metni.
• postCompactionSections: sıkıştırma sonrası 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. Ayarlanmamışsa veya açıkça o varsayılan çifte ayarlanmışsa, eski Every Session/Safety başlıkları da eski uyumluluk geri dönüşü olarak kabul edilir.
• model: yalnızca sıkıştırma özetlemesi için isteğe bağlı provider/model-id geçersiz kılması. Ana oturum bir modeli kullanırken sıkıştırma özetlerinin başka bir modelde çalışmasını istediğinizde bunu kullanın; ayarlanmamışsa sıkıştırma oturumun birincil modelini kullanır.
• notifyUser: true olduğunda, sıkıştırma başladığında kullanıcıya kısa bir bildirim gönderir (örneğin, “Compacting context…”). Sıkıştırmayı sessiz tutmak için varsayılan olarak kapalıdır.
• memoryFlush: kalıcı anıları depolamak için otomatik sıkıştırma öncesi sessiz agent turu. Ç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 streaming

{
  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)
    },
  },
}

• 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.
• humanDelay: blok yanıtlar arasında rastgele gecikme. natural = 800–2500ms. Agent 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/bahsetmeler için instant, bahsedilmeyen 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çerik 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 ilke kimliği
          providers: ["openai"], // isteğe bağlı
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # ana sandbox imajı
scripts/sandbox-browser-setup.sh   # isteğe bağlı tarayıcı imajı

​

agents.list (agent 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", // agent başına thinking düzeyi geçersiz kılması
        reasoningDefault: "on", // agent başına reasoning görünürlüğü geçersiz kılması
        fastModeDefault: false, // agent başına fast mode geçersiz kılması
        params: { cacheRetention: "none" }, // eşleşen defaults.models params değerlerini anahtar bazında geçersiz kılar
        skills: ["docs-search"], // ayarlandığında agents.defaults.skills alanının yerine geçer
        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ı agent kimliği (zorunlu).
• default: birden çok ayarlandığında ilk kazanan olur (uyarı günlüğe yazılır). Hiçbiri ayarlı değilse, listedeki ilk girdi varsayılan olur.
• model: dize biçimi yalnızca primary alanını 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, fallbacks: [] ayarlamazsanız varsayılan fallback’leri yine devralır.
• params: seçilen model girdisindeki agents.defaults.models üzerinde birleştirilen agent başına akış parametreleri. Tüm model kataloğunu çoğaltmadan cacheRetention, temperature veya maxTokens gibi agent’a özgü geçersiz kılmalar için bunu kullanın.
• skills: isteğe bağlı agent başına Skills izin listesi. Atlanırsa, agent ayarlıysa agents.defaults.skills alanını devralır; açık liste varsayılanlarla birleşmek yerine onların yerine geçer ve [] hiç Skills olmadığı anlamına gelir.
• thinkingDefault: isteğe bağlı agent başına varsayılan thinking düzeyi (off | minimal | low | medium | high | xhigh | adaptive). Bu agent için mesaj başına veya oturum geçersiz kılması ayarlanmamışsa agents.defaults.thinkingDefault alanının önüne geçer.
• reasoningDefault: isteğe bağlı agent başına varsayılan reasoning görünürlüğü (on | off | stream). Mesaj başına veya oturum reasoning geçersiz kılması ayarlanmamışsa uygulanır.
• fastModeDefault: isteğe bağlı agent başına fast mode varsayılanı (true | false). Mesaj başına veya oturum fast-mode geçersiz kılması ayarlanmamışsa uygulanır.
• runtime: isteğe bağlı agent başına çalışma zamanı tanımlayıcısı. Agent’ın varsayılan olarak ACP harness oturumlarını kullanması gerekiyorsa runtime.acp varsayılanları (agent, backend, mode, cwd) ile 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: ackReaction değerini emoji içinden, mentionPatterns değerini name/emoji içinden.
• subagents.allowAgents: sessions_spawn için agent kimliği izin listesi (["*"] = herhangi biri; varsayılan: yalnızca aynı agent).
• Sandbox devralma koruması: istekte bulunan oturum sandbox içindeyse, sessions_spawn sandbox dışında çalışacak hedefleri reddeder.
• subagents.requireAgentId: true olduğunda agentId içermeyen sessions_spawn çağrılarını engeller (açık profil seçimi zorlar; varsayılan: false).

​

Çok agent’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şme alanları

• type (isteğe bağlı): normal yönlendirme için route (type eksikse varsayılan route olur), kalıcı ACP konuşma bağlamaları için acp.
• match.channel (zorunlu)
• match.accountId (isteğe bağlı; * = herhangi bir hesap; atlanırsa varsayılan hesap)
• match.peer (isteğe bağlı; { kind: direct|group|channel, id })
• match.guildId / match.teamId (isteğe bağlı; kanala ö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 olmadan)
5. match.accountId: "*" (kanal geneli)
6. Varsayılan agent

​

Agent 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 üzerindeyse üst iş parçacığı fork’unu atla (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ı sert bütçe
      highWaterBytes: "400mb", // isteğe bağlı temizlik hedefi
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // saat cinsinden varsayılan hareketsizlik otomatik odak kaldırma (`0` devre dışı bırakır)
      maxAgeHours: 0, // saat cinsinden varsayılan kesin maksimum yaş (`0` devre dışı bırakır)
    },
    mainKey: "main", // eski (ç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 reaction

• Varsayılan olarak etkin agent’ın identity.emoji değeri kullanılır, yoksa "👀". 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.
• 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 ayarlanmamışsa ack reaction’lar etkinken durum tepkileri etkin kalır. Telegram’da yaşam döngüsü durum tepkilerini etkinleştirmek için bunu açıkça true olarak ayarlayın.

​

Gelen debounce

​

TTS (text-to-speech)

{
  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, otomatik TTS’yi denetler. /tts off|always|inbound|tagged bunu oturum başına geçersiz kılar.
• summaryModel, otomatik özet için agents.defaults.model.primary alanını geçersiz kılar.
• modelOverrides varsayılan olarak etkindir; modelOverrides.allowProvider varsayılanı false’tur (katılımlı).
• API anahtarları ELEVENLABS_API_KEY/XI_API_KEY ve OPENAI_API_KEY alanlarına geri döner.
• 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.
• openai.baseUrl OpenAI dışı bir uç noktayı gösterdiğinde, OpenClaw bunu OpenAI uyumlu bir TTS sunucusu olarak değerlendirir ve model/ses doğrulamasını gevşetir.

​

Talk

{
  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,
  },
}

• Birden çok Talk sağlayıcısı yapılandırıldığında talk.provider, talk.providers içindeki bir anahtarla eşleşmelidir.
• Eski düz Talk anahtarları (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) yalnızca uyumluluk içindir ve otomatik olarak talk.providers.<provider> içine taşınır.
• Voice kimlikleri ELEVENLABS_VOICE_ID veya SAG_VOICE_ID alanlarına geri döner.
• providers.*.apiKey düz metin dizeleri veya SecretRef nesneleri kabul eder.
• ELEVENLABS_API_KEY geri dönüşü yalnızca hiçbir Talk API anahtarı yapılandırılmamışsa uygulanır.
• providers.*.voiceAliases, Talk yönergelerinin kolay adlar kullanmasına izin verir.
• silenceTimeoutMs, Talk kipinin transkripti göndermeden önce kullanıcı sessizliğinden sonra ne kadar bekleyeceğini denetler. Ayarlanmamışsa platform varsayılan duraklama penceresi korunur (macOS ve Android’de 700 ms, iOS’te 900 ms).

​

Araçlar

​

Araç profilleri

​

Araç grupları

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}