Konfigurasi — agen

​

Default agen

​

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" }, // mewarisi github, weather
      { id: "docs", skills: ["docs-search"] }, // menggantikan default
      { id: "locked-down", skills: [] }, // tanpa Skills
    ],
  },
}

• Hilangkan agents.defaults.skills untuk Skills tak dibatasi secara default.
• Hilangkan agents.list[].skills untuk mewarisi default.
• Setel agents.list[].skills: [] untuk tanpa Skills.
• Daftar agents.list[].skills yang tidak kosong adalah kumpulan final untuk agen tersebut; daftar ini tidak digabungkan dengan default.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "continuation-skip": giliran lanjutan yang aman (setelah respons asisten selesai) melewati penyuntikan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Proses Heartbeat dan retry pasca-Compaction tetap membangun ulang konteks.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": jangan pernah menyuntikkan teks peringatan ke system prompt.
• "once": suntikkan peringatan sekali per signature pemotongan unik (disarankan).
• "always": suntikkan peringatan pada setiap proses ketika ada pemotongan.

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

​

Peta kepemilikan anggaran konteks

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: penyuntikan bootstrap workspace normal.
• agents.defaults.startupContext.*: prelude startup sekali pakai untuk /new dan /reset, termasuk file memory/*.md harian terbaru.
• skills.limits.*: daftar Skills ringkas yang disuntikkan ke system prompt.
• agents.defaults.contextLimits.*: kutipan runtime terbatas dan blok milik runtime yang disuntikkan.
• memory.qmd.limits.*: ukuran cuplikan dan injeksi memory-search yang diindeks.

• 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: batas kutipan memory_get default sebelum metadata pemotongan dan pemberitahuan lanjutan ditambahkan.
• memoryGetDefaultLines: jendela baris memory_get default saat lines dihilangkan.
• toolResultMaxChars: batas hasil tool langsung yang digunakan untuk hasil yang disimpan dan pemulihan overflow.
• postCompactionMaxChars: batas kutipan AGENTS.md yang digunakan selama penyuntikan refresh pasca-Compaction.

​

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" }, // parameter provider default global
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, mis. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Bentuk string hanya menetapkan model primary.
  • Bentuk objek menetapkan primary plus model failover berurutan.
• imageModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh jalur tool image sebagai konfigurasi vision model.
  • Juga digunakan sebagai routing fallback saat model yang dipilih/default tidak dapat menerima input gambar.
• imageGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan gambar bersama dan semua surface tool/plugin masa depan yang membuat gambar.
  • Nilai umum: google/gemini-3.1-flash-image-preview untuk pembuatan gambar Gemini native, fal/fal-ai/flux/dev untuk fal, atau openai/gpt-image-2 untuk OpenAI Images.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth provider yang sesuai (misalnya GEMINI_API_KEY atau GOOGLE_API_KEY untuk google/*, OPENAI_API_KEY atau OpenAI Codex OAuth untuk openai/gpt-image-2, FAL_KEY untuk fal/*).
  • Jika dihilangkan, image_generate tetap dapat menyimpulkan default provider berbasis auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya dalam urutan provider-id.
• musicGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan musik bersama dan tool bawaan music_generate.
  • Nilai umum: google/lyria-3-clip-preview, google/lyria-3-pro-preview, atau minimax/music-2.5+.
  • Jika dihilangkan, music_generate tetap dapat menyimpulkan default provider berbasis auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya dalam urutan provider-id.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang sesuai.
• videoGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan video bersama dan tool bawaan video_generate.
  • Nilai umum: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, atau qwen/wan2.7-r2v.
  • Jika dihilangkan, video_generate tetap dapat menyimpulkan default provider berbasis auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya dalam urutan provider-id.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang sesuai.
  • Provider pembuatan video Qwen bawaan mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, serta opsi tingkat provider size, aspectRatio, resolution, audio, dan watermark.
• pdfModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh tool pdf untuk routing model.
  • Jika dihilangkan, tool PDF akan fallback ke imageModel, lalu ke model sesi/default yang telah diselesaikan.
• pdfMaxBytesMb: batas ukuran PDF default untuk tool pdf saat maxBytesMb tidak diberikan pada waktu pemanggilan.
• pdfMaxPages: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi di tool pdf.
• verboseDefault: level verbose default untuk agen. Nilai: "off", "on", "full". Default: "off".
• elevatedDefault: level elevated-output default untuk agen. Nilai: "off", "on", "ask", "full". Default: "on".
• model.primary: format provider/model (mis. openai/gpt-5.4 untuk akses API key atau openai-codex/gpt-5.5 untuk Codex OAuth). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan unik configured-provider untuk model id persis itu, dan baru kemudian fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas lama yang sudah deprecated, jadi lebih baik gunakan provider/model eksplisit). Jika provider tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw akan fallback ke provider/model pertama yang dikonfigurasi alih-alih menampilkan default provider lama yang sudah dihapus.
• models: katalog model yang dikonfigurasi dan allowlist untuk /model. Setiap entri dapat menyertakan alias (shortcut) dan params (spesifik provider, misalnya temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold).
  • Pengeditan aman: gunakan openclaw config set agents.defaults.models '<json>' --strict-json --merge untuk menambahkan entri. config set menolak penggantian yang akan menghapus entri allowlist yang ada kecuali Anda memberikan --replace.
  • Alur configure/onboarding dengan cakupan provider akan menggabungkan model provider yang dipilih ke peta ini dan mempertahankan provider lain yang tidak terkait yang sudah dikonfigurasi.
  • Untuk model OpenAI Responses langsung, Compaction sisi server diaktifkan secara otomatis. Gunakan params.responsesServerCompaction: false untuk berhenti menyuntikkan context_management, atau params.responsesCompactThreshold untuk menimpa ambang batas. Lihat OpenAI server-side compaction.
• params: parameter provider default global yang diterapkan ke semua model. Disetel di agents.defaults.params (mis. { cacheRetention: "long" }).
• Prioritas penggabungan params (konfigurasi): agents.defaults.params (dasar global) ditimpa oleh agents.defaults.models["provider/model"].params (per model), lalu agents.list[].params (id agen yang cocok) menimpa per key. Lihat Prompt Caching untuk detailnya.
• embeddedHarness: kebijakan runtime agen tersemat tingkat rendah default. Gunakan runtime: "auto" agar harness plugin yang terdaftar dapat mengklaim model yang didukung, runtime: "pi" untuk memaksa harness PI bawaan, atau id harness terdaftar seperti runtime: "codex". Setel fallback: "none" untuk menonaktifkan fallback PI otomatis.
• Penulis konfigurasi yang memutasi field-field ini (misalnya /models set, /models set-image, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada bila memungkinkan.
• maxConcurrent: jumlah maksimum proses agen paralel di seluruh sesi (setiap sesi tetap diserialkan). Default: 4.

​

agents.defaults.embeddedHarness

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

• runtime: "auto", "pi", atau id harness plugin yang terdaftar. Plugin Codex bawaan mendaftarkan codex.
• fallback: "pi" atau "none". "pi" mempertahankan harness PI bawaan sebagai fallback kompatibilitas saat tidak ada harness plugin yang dipilih. "none" membuat pemilihan harness plugin yang hilang atau tidak didukung gagal alih-alih diam-diam menggunakan PI. Kegagalan harness plugin yang dipilih selalu ditampilkan secara langsung.
• Override environment: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> menimpa runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none menonaktifkan fallback PI untuk proses tersebut.
• Untuk deployment khusus Codex, setel model: "openai/gpt-5.5", embeddedHarness.runtime: "codex", dan embeddedHarness.fallback: "none".
• Pilihan harness dipasang per id sesi setelah proses tersemat pertama. Perubahan konfigurasi/env memengaruhi sesi baru atau yang di-reset, bukan transkrip yang sudah ada. Sesi lama dengan riwayat transkrip tetapi tanpa pin yang terekam diperlakukan sebagai dipin ke PI. /status menampilkan id harness non-PI seperti codex di samping Fast.
• Ini hanya mengontrol harness chat tersemat. Pembuatan media, vision, PDF, musik, video, dan TTS tetap menggunakan pengaturan provider/model masing-masing.

​

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 bersifat text-first; tool selalu dinonaktifkan.
• Sesi didukung saat sessionArg disetel.
• Pass-through gambar didukung saat imageArg menerima path file.

​

agents.defaults.systemPromptOverride

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

​

agents.defaults.promptOverlays

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

• "friendly" (default) dan "on" mengaktifkan lapisan gaya interaksi yang ramah.
• "off" hanya menonaktifkan lapisan ramah; kontrak perilaku GPT-5 yang diberi tag tetap aktif.
• plugins.entries.openai.config.personality lama masih dibaca saat pengaturan bersama ini tidak disetel.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m menonaktifkan
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false menghilangkan bagian Heartbeat dari system prompt
        lightContext: false, // default: false; true hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace
        isolatedSession: false, // default: false; true menjalankan setiap Heartbeat di sesi baru (tanpa riwayat percakapan)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | opsi: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: string durasi (ms/s/m/h). Default: 30m (auth API key) atau 1h (auth OAuth). Setel ke 0m untuk menonaktifkan.
• includeSystemPromptSection: saat false, menghilangkan bagian Heartbeat dari system prompt dan melewati penyuntikan HEARTBEAT.md ke konteks bootstrap. Default: true.
• suppressToolErrorWarnings: saat true, menekan payload peringatan error tool selama proses Heartbeat.
• timeoutSeconds: waktu maksimum dalam detik yang diizinkan untuk satu giliran agen Heartbeat sebelum dibatalkan. Biarkan tidak disetel untuk menggunakan agents.defaults.timeoutSeconds.
• directPolicy: kebijakan pengiriman langsung/DM. allow (default) mengizinkan pengiriman target langsung. block menekan pengiriman target langsung dan mengeluarkan reason=dm-blocked.
• lightContext: saat true, proses Heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace.
• isolatedSession: saat true, setiap Heartbeat berjalan di sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama seperti Cron sessionTarget: "isolated". Mengurangi biaya token per Heartbeat dari ~100K menjadi ~2-5K token.
• Per agen: setel agents.list[].heartbeat. Saat agen mana pun mendefinisikan heartbeat, hanya agen tersebut yang menjalankan Heartbeat.
• Heartbeat menjalankan giliran agen penuh — interval yang lebih pendek membakar lebih banyak token.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id dari plugin provider Compaction yang terdaftar (opsional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // digunakan saat identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] menonaktifkan penyuntikan ulang
        model: "openrouter/anthropic/claude-sonnet-4-6", // override model khusus Compaction opsional
        notifyUser: true, // kirim notifikasi singkat saat Compaction dimulai dan selesai (default: 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 atau safeguard (peringkasan bertahap untuk riwayat panjang). Lihat Compaction.
• provider: id dari plugin provider Compaction yang terdaftar. Saat disetel, summarize() milik provider dipanggil alih-alih peringkasan LLM bawaan. Fallback ke bawaan saat gagal. Menyetel provider memaksa mode: "safeguard". Lihat Compaction.
• timeoutSeconds: jumlah detik maksimum yang diizinkan untuk satu operasi Compaction sebelum OpenClaw membatalkannya. Default: 900.
• identifierPolicy: strict (default), off, atau custom. strict menambahkan panduan retensi identifier opak bawaan selama peringkasan Compaction.
• identifierInstructions: teks pelestarian identifier kustom opsional yang digunakan saat identifierPolicy=custom.
• postCompactionSections: nama bagian H2/H3 AGENTS.md opsional untuk disuntikkan ulang setelah Compaction. Default ke ["Session Startup", "Red Lines"]; setel [] untuk menonaktifkan penyuntikan ulang. Saat tidak disetel atau secara eksplisit disetel ke pasangan default tersebut, heading lama Every Session/Safety juga diterima sebagai fallback lama.
• model: override provider/model-id opsional hanya untuk peringkasan Compaction. Gunakan ini saat sesi utama harus tetap memakai satu model tetapi ringkasan Compaction harus dijalankan pada model lain; saat tidak disetel, Compaction menggunakan model utama sesi.
• notifyUser: saat true, mengirim notifikasi singkat ke pengguna saat Compaction dimulai dan saat selesai (misalnya, “Memadatkan konteks…” dan “Compaction selesai”). Dinonaktifkan secara default agar Compaction tetap senyap.
• memoryFlush: giliran agentic senyap sebelum Compaction otomatis untuk menyimpan memori tahan lama. Dilewati saat workspace bersifat read-only.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // durasi (ms/s/m/h), unit default: menit
        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"] },
      },
    },
  },
}

​

Streaming blok

{
  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 (gunakan minMs/maxMs)
    },
  },
}

• Channel non-Telegram memerlukan *.blockStreaming: true eksplisit untuk mengaktifkan balasan blok.
• Override channel: channels.<channel>.blockStreamingCoalesce (dan varian per akun). Signal/Slack/Discord/Google Chat default ke minChars: 1500.
• humanDelay: jeda acak di antara balasan blok. natural = 800–2500ms. Override per agen: agents.list[].humanDelay.

​

Indikator mengetik

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

• Default: instant untuk chat langsung/mention, message untuk chat grup tanpa mention.
• Override per sesi: 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 / konten inline juga didukung:
          // 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", // opsional
          gatewayEndpoint: "https://lab.example", // opsional
          policy: "strict", // id kebijakan OpenShell opsional
          providers: ["openai"], // opsional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # image sandbox utama
scripts/sandbox-browser-setup.sh   # image browser opsional

​

agents.list (override per agen)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // atau { primary, fallbacks }
        thinkingDefault: "high", // override level thinking per agen
        reasoningDefault: "on", // override visibilitas reasoning per agen
        fastModeDefault: false, // override fast mode per agen
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // menimpa params defaults.models yang cocok per key
        skills: ["docs-search"], // menggantikan agents.defaults.skills saat disetel
        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: id agen stabil (wajib).
• default: saat beberapa disetel, yang pertama menang (peringatan dicatat). Jika tidak ada yang disetel, entri daftar pertama menjadi default.
• model: bentuk string hanya menimpa primary; bentuk objek { primary, fallbacks } menimpa keduanya ([] menonaktifkan fallback global). Tugas Cron yang hanya menimpa primary tetap mewarisi fallback default kecuali Anda menyetel fallbacks: [].
• params: params stream per agen yang digabungkan di atas entri model yang dipilih di agents.defaults.models. Gunakan ini untuk override khusus agen seperti cacheRetention, temperature, atau maxTokens tanpa menduplikasi seluruh katalog model.
• skills: allowlist Skills per agen opsional. Jika dihilangkan, agen mewarisi agents.defaults.skills saat disetel; daftar eksplisit menggantikan default alih-alih digabungkan, dan [] berarti tanpa Skills.
• thinkingDefault: level thinking default per agen opsional (off | minimal | low | medium | high | xhigh | adaptive | max). Menimpa agents.defaults.thinkingDefault untuk agen ini saat tidak ada override per pesan atau sesi.
• reasoningDefault: visibilitas reasoning default per agen opsional (on | off | stream). Berlaku saat tidak ada override reasoning per pesan atau sesi.
• fastModeDefault: default per agen opsional untuk fast mode (true | false). Berlaku saat tidak ada override fast-mode per pesan atau sesi.
• embeddedHarness: override kebijakan harness tingkat rendah per agen opsional. Gunakan { runtime: "codex", fallback: "none" } agar satu agen hanya Codex sementara agen lain tetap menggunakan fallback PI default.
• runtime: deskriptor runtime per agen opsional. Gunakan type: "acp" dengan default runtime.acp (agent, backend, mode, cwd) saat agen seharusnya default ke sesi harness ACP.
• identity.avatar: path relatif workspace, URL http(s), atau URI data:.
• identity menurunkan default: ackReaction dari emoji, mentionPatterns dari name/emoji.
• subagents.allowAgents: allowlist id agen untuk sessions_spawn (["*"] = apa saja; default: hanya agen yang sama).
• Guard pewarisan sandbox: jika sesi peminta disandbox, sessions_spawn menolak target yang akan berjalan tanpa sandbox.
• subagents.requireAgentId: saat true, blokir pemanggilan sessions_spawn yang menghilangkan agentId (memaksa pemilihan profil eksplisit; default: false).

​

Routing multi-agen

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

​

Field pencocokan binding

• type (opsional): route untuk routing normal (type yang hilang default ke route), acp untuk binding percakapan ACP persisten.
• match.channel (wajib)
• match.accountId (opsional; * = akun apa saja; dihilangkan = akun default)
• match.peer (opsional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opsional; khusus channel)
• acp (opsional; hanya untuk entri type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (persis, tanpa peer/guild/team)
5. match.accountId: "*" (seluruh channel)
6. Agen default

​

Profil akses per agen

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

​

Sesi

{
  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, // lewati fork thread induk di atas jumlah token ini (0 menonaktifkan)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // durasi atau false
      maxDiskBytes: "500mb", // hard budget opsional
      highWaterBytes: "400mb", // target pembersihan opsional
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // auto-unfocus default karena tidak aktif dalam jam (`0` menonaktifkan)
      maxAgeHours: 0, // usia maksimum keras default dalam jam (`0` menonaktifkan)
    },
    mainKey: "main", // lama (runtime selalu menggunakan "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Pesan

{
  messages: {
    responsePrefix: "🦞", // atau "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 menonaktifkan
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefiks respons

​

Reaksi ack

• Default ke identity.emoji agen aktif, jika tidak ada maka "👀". Setel "" untuk menonaktifkan.
• Override per channel: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Urutan resolusi: akun → channel → messages.ackReaction → fallback identitas.
• Cakupan: group-mentions (default), group-all, direct, all.
• removeAckAfterReply: menghapus ack setelah balasan di Slack, Discord, dan Telegram.
• messages.statusReactions.enabled: mengaktifkan reaksi status siklus hidup di Slack, Discord, dan Telegram. Di Slack dan Discord, jika tidak disetel maka reaksi status tetap aktif saat reaksi ack aktif. Di Telegram, setel secara eksplisit ke true untuk mengaktifkan reaksi status siklus hidup.

​

Debounce masuk

​

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 mengontrol mode auto-TTS default: off, always, inbound, atau tagged. /tts on|off dapat menimpa preferensi lokal, dan /tts status menampilkan status efektif.
• summaryModel menimpa agents.defaults.model.primary untuk ringkasan otomatis.
• modelOverrides aktif secara default; modelOverrides.allowProvider default ke false (perlu opt-in).
• API key fallback ke ELEVENLABS_API_KEY/XI_API_KEY dan OPENAI_API_KEY.
• openai.baseUrl menimpa endpoint OpenAI TTS. Urutan resolusi adalah config, lalu OPENAI_TTS_BASE_URL, lalu https://api.openai.com/v1.
• Saat openai.baseUrl mengarah ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS yang kompatibel dengan OpenAI dan melonggarkan validasi model/voice.

​

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

• talk.provider harus cocok dengan key di talk.providers saat beberapa provider Talk dikonfigurasi.
• Key Talk datar lama (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) hanya untuk kompatibilitas dan dimigrasikan otomatis ke talk.providers.<provider>.
• Voice ID fallback ke ELEVENLABS_VOICE_ID atau SAG_VOICE_ID.
• providers.*.apiKey menerima string plaintext atau objek SecretRef.
• Fallback ELEVENLABS_API_KEY hanya berlaku saat tidak ada API key Talk yang dikonfigurasi.
• providers.*.voiceAliases memungkinkan direktif Talk menggunakan nama yang ramah.
• silenceTimeoutMs mengontrol berapa lama mode Talk menunggu setelah pengguna diam sebelum mengirim transkrip. Jika tidak disetel, jendela jeda default platform tetap digunakan (700 ms di macOS dan Android, 900 ms di iOS).

​

Terkait

• Referensi konfigurasi — semua key konfigurasi lainnya
• Konfigurasi — tugas umum dan penyiapan cepat
• Contoh konfigurasi