Konfigurasi — agen

​

Bawaan 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" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Hilangkan agents.defaults.skills untuk skill tanpa batasan secara bawaan.
• Hilangkan agents.list[].skills untuk mewarisi bawaan.
• Atur agents.list[].skills: [] untuk tanpa skill.
• Daftar agents.list[].skills yang tidak kosong adalah set final untuk agen tersebut; daftar itu tidak digabung dengan bawaan.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": giliran lanjutan yang aman (setelah respons asisten selesai) melewati penyuntikan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Jalankan Heartbeat dan percobaan ulang pasca-Compaction tetap membangun ulang konteks.
• "never": nonaktifkan bootstrap workspace dan penyuntikan file konteks pada setiap giliran. Gunakan ini hanya untuk agen yang sepenuhnya memiliki lifecycle prompt sendiri (mesin konteks kustom, runtime native yang membangun konteks sendiri, atau workflow khusus tanpa bootstrap). Giliran Heartbeat dan pemulihan Compaction juga melewati penyuntikan.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

Override profil bootstrap per agen

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": jangan pernah menyuntikkan teks pemberitahuan pemotongan ke prompt sistem.
• "once": suntikkan pemberitahuan ringkas satu kali per tanda tangan pemotongan unik.
• "always": suntikkan pemberitahuan ringkas pada setiap run saat ada pemotongan (direkomendasikan).

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

​

Peta kepemilikan anggaran konteks

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: penyuntikan bootstrap workspace normal.
• agents.defaults.startupContext.*: prelude satu kali untuk run model reset/startup, termasuk file memory/*.md harian terbaru. Perintah chat polos /new dan /reset diakui tanpa memanggil model.
• skills.limits.*: daftar skills ringkas yang disuntikkan ke prompt sistem.
• agents.defaults.contextLimits.*: kutipan runtime berbatas dan blok milik runtime yang disuntikkan.
• memory.qmd.limits.*: ukuran snippet pencarian memori terindeks dan penyuntikan.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• 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,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: batas kutipan memory_get bawaan sebelum metadata pemotongan dan pemberitahuan lanjutan ditambahkan.
• memoryGetDefaultLines: jendela baris memory_get bawaan saat lines dihilangkan.
• toolResultMaxChars: batas atas hasil alat live tingkat lanjut yang digunakan untuk hasil persisten dan pemulihan overflow. Biarkan tidak diatur untuk batas otomatis konteks model: 16000 karakter di bawah 100K token, 32000 karakter pada 100K+ token, dan 64000 karakter pada 200K+ token. Nilai eksplisit hingga 1000000 diterima untuk model berkonteks panjang, tetapi batas efektif masih dibatasi sekitar 30% dari jendela konteks model. openclaw doctor --deep mencetak batas efektif, dan doctor hanya memperingatkan saat override eksplisit sudah usang atau tidak berpengaruh.
• postCompactionMaxChars: batas kutipan AGENTS.md yang digunakan selama penyuntikan refresh pasca-Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // advanced ceiling for this agent
        },
      },
    ],
  },
}

​

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.imageQuality

• auto: sesuaikan dengan batas model dan jumlah gambar.
• efficient: utamakan gambar yang lebih kecil untuk penggunaan token dan byte yang lebih rendah.
• balanced: gunakan tangga jalan tengah standar.
• high: pertahankan lebih banyak detail untuk screenshot, diagram, dan gambar dokumen.

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      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" }, // global default provider params
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "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 utama.
  • Bentuk objek menetapkan model utama plus model failover berurutan.
• imageModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh jalur alat image sebagai konfigurasi model vision-nya.
  • Juga digunakan sebagai perutean fallback ketika model yang dipilih/default tidak dapat menerima input gambar.
  • Utamakan ref provider/model eksplisit. ID polos diterima untuk kompatibilitas; jika ID polos cocok secara unik dengan entri berkemampuan gambar yang dikonfigurasi di models.providers.*.models, OpenClaw melengkapinya ke provider tersebut. Kecocokan terkonfigurasi yang ambigu memerlukan prefiks provider eksplisit.
• imageGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan gambar bersama dan permukaan alat/plugin masa depan apa pun yang menghasilkan gambar.
  • Nilai umum: google/gemini-3.1-flash-image-preview untuk pembuatan gambar Gemini native, fal/fal-ai/flux/dev untuk fal, openai/gpt-image-2 untuk OpenAI Images, atau openai/gpt-image-1.5 untuk output PNG/WebP OpenAI berlatar transparan.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga autentikasi provider yang cocok (misalnya GEMINI_API_KEY atau GOOGLE_API_KEY untuk google/*, OPENAI_API_KEY atau OpenAI Codex OAuth untuk openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY untuk fal/*).
  • Jika dihilangkan, image_generate masih dapat menyimpulkan default provider yang didukung autentikasi. Ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar yang tersisa dalam urutan ID provider.
• musicGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan musik bersama dan alat bawaan music_generate.
  • Nilai umum: google/lyria-3-clip-preview, google/lyria-3-pro-preview, atau minimax/music-2.6.
  • Jika dihilangkan, music_generate masih dapat menyimpulkan default provider yang didukung autentikasi. Ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar yang tersisa dalam urutan ID provider.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga autentikasi/kunci API provider yang cocok.
• videoGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan video bersama dan alat 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 masih dapat menyimpulkan default provider yang didukung autentikasi. Ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar yang tersisa dalam urutan ID provider.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga autentikasi/kunci API provider yang cocok.
  • Plugin pembuatan video Qwen resmi 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 alat pdf untuk perutean model.
  • Jika dihilangkan, alat PDF melakukan fallback ke imageModel, lalu ke model sesi/default yang telah diselesaikan.
• pdfMaxBytesMb: batas ukuran PDF default untuk alat pdf ketika maxBytesMb tidak diteruskan saat pemanggilan.
• pdfMaxPages: halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi di alat pdf.
• verboseDefault: tingkat verbose default untuk agen. Nilai: "off", "on", "full". Default: "off".
• toolProgressDetail: mode detail untuk ringkasan alat /verbose dan baris alat draf progres. Nilai: "explain" (default, label manusia ringkas) atau "raw" (tambahkan perintah/detail mentah bila tersedia). agents.list[].toolProgressDetail per agen menimpa default ini.
• reasoningDefault: visibilitas reasoning default untuk agen. Nilai: "off", "on", "stream". agents.list[].reasoningDefault per agen menimpa default ini. Default reasoning yang dikonfigurasi hanya diterapkan untuk pemilik, pengirim terotorisasi, atau konteks Gateway admin operator ketika tidak ada override reasoning per pesan atau sesi yang ditetapkan.
• elevatedDefault: tingkat output elevated default untuk agen. Nilai: "off", "on", "ask", "full". Default: "on".
• model.primary: format provider/model (misalnya openai/gpt-5.5 untuk akses kunci API OpenAI atau Codex OAuth). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan provider terkonfigurasi yang unik untuk ID model persis tersebut, dan baru setelah itu fallback ke provider default terkonfigurasi (perilaku kompatibilitas yang tidak digunakan lagi, jadi utamakan provider/model eksplisit). Jika provider tersebut tidak lagi mengekspos model default terkonfigurasi, OpenClaw fallback ke provider/model terkonfigurasi pertama alih-alih memunculkan default provider lama yang sudah dihapus.
• models: katalog model terkonfigurasi dan allowlist untuk /model. Setiap entri dapat menyertakan alias (pintasan) dan params (khusus provider, misalnya temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, perutean provider OpenRouter, chat_template_kwargs, extra_body/extraBody).
  • Gunakan entri provider/* seperti "openai/*": {} atau "vllm/*": {} untuk menampilkan semua model yang ditemukan untuk provider terpilih tanpa mencantumkan setiap ID model secara manual.
  • Tambahkan agentRuntime ke entri provider/* ketika setiap model yang ditemukan secara dinamis untuk provider tersebut harus menggunakan runtime yang sama. Kebijakan runtime provider/model persis tetap mengalahkan wildcard.
  • Edit 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 meneruskan --replace.
  • Alur configure/onboarding bercakupan provider menggabungkan model provider terpilih ke dalam map ini dan mempertahankan provider tidak terkait yang sudah dikonfigurasi.
  • Untuk model OpenAI Responses langsung, Compaction sisi server diaktifkan otomatis. Gunakan params.responsesServerCompaction: false untuk berhenti menyuntikkan context_management, atau params.responsesCompactThreshold untuk menimpa ambang batas. Lihat Compaction sisi server OpenAI.
• params: parameter provider default global yang diterapkan ke semua model. Diatur di agents.defaults.params (misalnya { cacheRetention: "long" }).
• Prioritas penggabungan params (konfigurasi): agents.defaults.params (basis global) ditimpa oleh agents.defaults.models["provider/model"].params (per model), lalu agents.list[].params (ID agen yang cocok) menimpa berdasarkan kunci. Lihat Prompt Caching untuk detail.
• models.providers.openrouter.params.provider: kebijakan perutean provider default untuk seluruh OpenRouter. OpenClaw meneruskan ini ke objek provider permintaan OpenRouter; agents.defaults.models["openrouter/<model>"].params.provider per model dan parameter agen menimpa berdasarkan kunci. Lihat perutean provider OpenRouter.
• params.extra_body/params.extraBody: JSON pass-through lanjutan yang digabungkan ke body permintaan api: "openai-completions" untuk proxy kompatibel OpenAI. Jika bertabrakan dengan kunci permintaan yang dihasilkan, body ekstra menang; rute completions non-native tetap menghapus store khusus OpenAI setelahnya.
• params.chat_template_kwargs: argumen chat-template kompatibel vLLM/OpenAI yang digabungkan ke body permintaan api: "openai-completions" tingkat atas. Untuk vllm/nemotron-3-* dengan thinking mati, plugin vLLM bawaan otomatis mengirim enable_thinking: false dan force_nonempty_content: true; chat_template_kwargs eksplisit menimpa default yang dihasilkan, dan extra_body.chat_template_kwargs tetap memiliki prioritas akhir. Model thinking Qwen dan Nemotron vLLM terkonfigurasi mengekspos pilihan /think biner (off, on) alih-alih tangga effort bertingkat.
• compat.thinkingFormat: gaya payload thinking kompatibel OpenAI. Gunakan "together" untuk reasoning.enabled gaya Together, "qwen" untuk enable_thinking tingkat atas gaya Qwen, atau "qwen-chat-template" untuk chat_template_kwargs.enable_thinking pada backend keluarga Qwen yang mendukung kwargs chat-template tingkat permintaan, seperti vLLM. OpenClaw memetakan thinking yang dinonaktifkan ke false dan thinking yang diaktifkan ke true, dan model Qwen vLLM terkonfigurasi mengekspos pilihan /think biner untuk format ini.
• compat.supportedReasoningEfforts: daftar effort reasoning kompatibel OpenAI per model. Sertakan "xhigh" untuk endpoint kustom yang benar-benar menerimanya; OpenClaw kemudian mengekspos /think xhigh di menu perintah, baris sesi Gateway, validasi patch sesi, validasi CLI agen, dan validasi llm-task untuk provider/model terkonfigurasi tersebut. Gunakan compat.reasoningEffortMap ketika backend menginginkan nilai khusus provider untuk level kanonis.
• params.preserveThinking: opt-in khusus Z.AI untuk thinking yang dipertahankan. Ketika diaktifkan dan thinking menyala, OpenClaw mengirim thinking.clear_thinking: false dan memutar ulang reasoning_content sebelumnya; lihat thinking Z.AI dan thinking yang dipertahankan.
• localService: manajer proses tingkat provider opsional untuk server model lokal/self-hosted. Ketika model yang dipilih milik provider tersebut, OpenClaw memeriksa healthUrl (atau baseUrl + "/models"), menjalankan command dengan args jika endpoint sedang turun, menunggu hingga readyTimeoutMs, lalu mengirim permintaan model. command harus berupa path absolut. idleStopMs: 0 membuat proses tetap hidup hingga OpenClaw keluar; nilai positif menghentikan proses yang dijalankan OpenClaw setelah idle selama jumlah milidetik tersebut. Lihat layanan model lokal.
• Kebijakan runtime berada pada provider atau model, bukan pada agents.defaults. Gunakan models.providers.<provider>.agentRuntime untuk aturan seluruh provider atau agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime untuk aturan khusus model. Model agen OpenAI pada provider OpenAI resmi memilih Codex secara default.
• Penulis konfigurasi yang memutasi 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 run agen paralel lintas sesi (setiap sesi tetap diserialisasi). Default: 4.

​

Kebijakan runtime

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

• id: "auto", "openclaw", id harness plugin terdaftar, atau alias backend CLI yang didukung. Plugin Codex bawaan mendaftarkan codex; plugin Anthropic bawaan menyediakan backend CLI claude-cli.
• id: "auto" memungkinkan harness plugin terdaftar mengklaim giliran yang didukung dan menggunakan OpenClaw saat tidak ada harness yang cocok. Runtime plugin eksplisit seperti id: "codex" memerlukan harness tersebut dan gagal tertutup jika tidak tersedia atau gagal.
• id: "pi" diterima hanya sebagai alias usang untuk openclaw guna mempertahankan config yang sudah dirilis dari v2026.5.22 dan sebelumnya. Config baru harus menggunakan openclaw.
• Prioritas runtime adalah kebijakan model persis terlebih dahulu (agents.list[].models["provider/model"], agents.defaults.models["provider/model"], atau models.providers.<provider>.models[]), lalu agents.list[] / agents.defaults.models["provider/*"], lalu kebijakan seluruh provider di models.providers.<provider>.agentRuntime.
• Kunci runtime seluruh agen bersifat legacy. agents.defaults.agentRuntime, agents.list[].agentRuntime, pin runtime sesi, dan OPENCLAW_AGENT_RUNTIME diabaikan oleh pemilihan runtime. Jalankan openclaw doctor --fix untuk menghapus nilai usang.
• Model agen OpenAI menggunakan harness Codex secara default; provider/model agentRuntime.id: "codex" tetap valid saat Anda ingin membuatnya eksplisit.
• Untuk deployment Claude CLI, pilih model: "anthropic/claude-opus-4-8" ditambah agentRuntime.id: "claude-cli" yang dicakup model. Ref model legacy claude-cli/claude-opus-4-7 masih berfungsi untuk kompatibilitas, tetapi config baru harus menjaga pemilihan provider/model tetap kanonis dan menempatkan backend eksekusi dalam kebijakan runtime provider/model.
• Ini hanya mengontrol eksekusi giliran agen teks. Pembuatan media, vision, PDF, musik, video, dan TTS tetap menggunakan pengaturan provider/model masing-masing.

​

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",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Backend CLI mengutamakan teks; tool selalu dinonaktifkan.
• Sesi didukung saat sessionArg ditetapkan.
• Pass-through gambar didukung saat imageArg menerima path file.
• reseedFromRawTranscriptWhenUncompacted: true memungkinkan backend memulihkan sesi yang aman tetapi sudah diinvalidasi dari ekor transkrip mentah OpenClaw yang dibatasi sebelum ringkasan Compaction pertama ada. Perubahan profil auth atau epoch kredensial tetap tidak pernah melakukan raw-reseed.

​

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 bertag tetap aktif.
• Legacy plugins.entries.openai.config.personality masih dibaca saat pengaturan bersama ini belum ditetapkan.

​

agents.defaults.heartbeat

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

• every: string durasi (ms/s/m/h). Default: 30m (auth kunci API) atau 1h (auth OAuth). Tetapkan ke 0m untuk menonaktifkan.
• includeSystemPromptSection: saat false, menghilangkan bagian Heartbeat dari prompt sistem dan melewati injeksi HEARTBEAT.md ke dalam konteks bootstrap. Default: true.
• suppressToolErrorWarnings: saat true, menekan payload peringatan error tool selama run Heartbeat.
• timeoutSeconds: waktu maksimum dalam detik yang diizinkan untuk giliran agen Heartbeat sebelum dibatalkan. Biarkan tidak ditetapkan untuk menggunakan agents.defaults.timeoutSeconds saat ditetapkan, jika tidak cadence Heartbeat dibatasi pada 600 detik.
• directPolicy: kebijakan pengiriman langsung/DM. allow (default) mengizinkan pengiriman target langsung. block menekan pengiriman target langsung dan menghasilkan reason=dm-blocked.
• lightContext: saat true, run Heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace.
• isolatedSession: saat true, setiap Heartbeat berjalan dalam 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.
• skipWhenBusy: saat true, run Heartbeat ditunda pada lane sibuk tambahan agen tersebut: subagen berkunci sesi miliknya sendiri atau pekerjaan command bertingkat. Lane Cron selalu menunda Heartbeat, bahkan tanpa flag ini.
• Per agen: tetapkan 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 of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default atau safeguard (peringkasan berpotongan untuk riwayat panjang). Lihat Compaction.
• provider: id dari plugin penyedia compaction yang terdaftar. Saat disetel, summarize() milik penyedia dipanggil alih-alih peringkasan LLM bawaan. Kembali ke bawaan jika gagal. Menyetel penyedia memaksa mode: "safeguard". Lihat Compaction.
• timeoutSeconds: jumlah detik maksimum yang diizinkan untuk satu operasi compaction sebelum OpenClaw membatalkannya. Default: 180.
• keepRecentTokens: anggaran titik potong agen untuk mempertahankan ekor transkrip terbaru secara verbatim. /compact manual menghormati ini saat disetel secara eksplisit; jika tidak, compaction manual adalah checkpoint keras.
• identifierPolicy: strict (default), off, atau custom. strict menambahkan panduan retensi pengenal buram bawaan di awal selama peringkasan compaction.
• identifierInstructions: teks pelestarian pengenal kustom opsional yang digunakan saat identifierPolicy=custom.
• qualityGuard: pemeriksaan coba-ulang-saat-output-cacat untuk ringkasan safeguard. Diaktifkan secara default dalam mode safeguard; setel enabled: false untuk melewati audit.
• midTurnPrecheck: pemeriksaan tekanan tool-loop opsional. Saat enabled: true, OpenClaw memeriksa tekanan konteks setelah hasil tool ditambahkan dan sebelum panggilan model berikutnya. Jika konteks tidak lagi muat, upaya saat ini dibatalkan sebelum mengirim prompt dan jalur pemulihan precheck yang ada digunakan ulang untuk memotong hasil tool atau melakukan compact lalu mencoba lagi. Berfungsi dengan mode compaction default dan safeguard. Default: dinonaktifkan.
• postCompactionSections: nama bagian H2/H3 AGENTS.md opsional untuk disuntikkan kembali setelah compaction. Penyuntikan ulang dinonaktifkan saat tidak disetel atau disetel ke []. Menyetel ["Session Startup", "Red Lines"] secara eksplisit mengaktifkan pasangan itu dan mempertahankan fallback lama Every Session/Safety. Aktifkan ini hanya saat konteks tambahan sepadan dengan risiko menggandakan panduan proyek yang sudah ditangkap dalam ringkasan compaction.
• model: provider/model-id opsional atau alias polos dari agents.defaults.models hanya untuk peringkasan compaction. Alias polos diselesaikan sebelum dispatch; ID model literal yang dikonfigurasi mempertahankan prioritas saat terjadi benturan. Gunakan ini saat sesi utama harus mempertahankan satu model tetapi ringkasan compaction harus berjalan pada model lain; saat tidak disetel, compaction menggunakan model utama sesi.
• maxActiveTranscriptBytes: ambang byte opsional (number atau string seperti "20mb") yang memicu compaction lokal normal sebelum run saat JSONL aktif tumbuh melewati ambang. Memerlukan truncateAfterCompaction agar compaction yang berhasil dapat merotasi ke transkrip penerus yang lebih kecil. Dinonaktifkan saat tidak disetel atau 0.
• notifyUser: saat true, mengirim pemberitahuan singkat kepada 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 auto-compaction untuk menyimpan memori tahan lama. Setel model ke penyedia/model persis seperti ollama/qwen3:8b saat giliran housekeeping ini harus tetap pada model lokal; override tidak mewarisi rantai fallback sesi aktif. Dilewati saat workspace bersifat read-only.

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // optional per-agent overrides
      },
    ],
  },
}

• base: jumlah dasar iterasi retry run untuk loop run luar. Default: 24.
• perProfile: iterasi retry run tambahan yang diberikan per kandidat profil fallback. Default: 8.
• min: batas absolut minimum untuk iterasi retry run. Default: 32.
• max: batas absolut maksimum untuk iterasi retry run guna mencegah eksekusi tak terkendali. Default: 160.

​

agents.defaults.contextPruning

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

​

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 (use 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 menggunakan default minChars: 1500.
• humanDelay: jeda acak antarbalasan blok. natural = 800–2500md. Override per agen: agents.list[].humanDelay.

​

Indikator pengetikan

{
  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",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

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

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

​

agents.list (penggantian 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", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: id agen stabil (wajib).
• default: ketika beberapa diatur, yang pertama menang (peringatan dicatat). Jika tidak ada yang diatur, entri daftar pertama menjadi default.
• model: bentuk string menetapkan primary per agen yang ketat tanpa fallback model; bentuk objek { primary } juga ketat kecuali Anda menambahkan fallbacks. Gunakan { primary, fallbacks: [...] } untuk mengikutsertakan agen tersebut ke fallback, atau { primary, fallbacks: [] } untuk membuat perilaku ketat eksplisit. Pekerjaan Cron yang hanya mengganti primary tetap mewarisi fallback default kecuali Anda mengatur fallbacks: [].
• params: parameter stream per agen yang digabungkan di atas entri model terpilih di agents.defaults.models. Gunakan ini untuk penggantian khusus agen seperti cacheRetention, temperature, atau maxTokens tanpa menduplikasi seluruh katalog model.
• tts: penggantian text-to-speech per agen opsional. Blok ini melakukan deep-merge di atas messages.tts, jadi simpan kredensial penyedia bersama dan kebijakan fallback di messages.tts dan atur hanya nilai khusus persona seperti penyedia, suara, model, gaya, atau mode otomatis di sini.
• skills: allowlist Skills per agen opsional. Jika dihilangkan, agen mewarisi agents.defaults.skills saat diatur; daftar eksplisit menggantikan default alih-alih menggabungkan, dan [] berarti tanpa skills.
• thinkingDefault: tingkat thinking default per agen opsional (off | minimal | low | medium | high | xhigh | adaptive | max). Mengganti agents.defaults.thinkingDefault untuk agen ini ketika tidak ada penggantian per pesan atau sesi yang diatur. Profil penyedia/model yang dipilih mengontrol nilai mana yang valid; untuk Google Gemini, adaptive mempertahankan thinking dinamis milik penyedia (thinkingLevel dihilangkan pada Gemini 3/3.1, thinkingBudget: -1 pada Gemini 2.5).
• reasoningDefault: visibilitas reasoning default per agen opsional (on | off | stream). Mengganti agents.defaults.reasoningDefault untuk agen ini ketika tidak ada penggantian reasoning per pesan atau sesi yang diatur.
• fastModeDefault: default per agen opsional untuk mode cepat ("auto" | true | false). Berlaku ketika tidak ada penggantian mode cepat per pesan atau sesi yang diatur.
• models: katalog model/penggantian runtime per agen opsional yang diindeks oleh id lengkap provider/model. Gunakan models["provider/model"].agentRuntime untuk pengecualian runtime per agen.
• runtime: deskriptor runtime per agen opsional. Gunakan type: "acp" dengan default runtime.acp (agent, backend, mode, cwd) saat agen harus default ke sesi harness ACP.
• identity.avatar: path relatif workspace, URL http(s), atau URI data:.
• File gambar identity.avatar lokal relatif workspace dibatasi hingga 2 MB. URL http(s) dan URI data: tidak diperiksa dengan batas ukuran file lokal.
• identity menurunkan default: ackReaction dari emoji, mentionPatterns dari name/emoji.
• subagents.allowAgents: allowlist id agen yang dikonfigurasi untuk target eksplisit sessions_spawn.agentId (["*"] = target terkonfigurasi apa pun; default: hanya agen yang sama). Sertakan id peminta saat panggilan agentId yang menargetkan diri sendiri harus diizinkan. Entri kedaluwarsa yang konfigurasi agennya telah dihapus ditolak oleh sessions_spawn dan dihilangkan dari agents_list; jalankan openclaw doctor --fix untuk membersihkannya, atau tambahkan entri minimal agents.list[] jika target tersebut harus tetap dapat di-spawn sambil mewarisi default.
• Penjaga pewarisan sandbox: jika sesi peminta tersandbox, sessions_spawn menolak target yang akan berjalan tanpa sandbox.
• subagents.requireAgentId: ketika true, blokir panggilan sessions_spawn yang menghilangkan agentId (memaksa pemilihan profil eksplisit; default: false).

​

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

​

Kolom kecocokan binding

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

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (tepat, tanpa peer/guild/team)
5. match.accountId: "*" (seluruh kanal)
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",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Pesan

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

​

Prefiks respons

​

Reaksi ack

• Default ke identity.emoji agen aktif, jika tidak ada "👀". Atur "" 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 pada channel yang mendukung reaksi seperti Slack, Discord, Signal, Telegram, WhatsApp, dan iMessage.
• messages.statusReactions.enabled: mengaktifkan reaksi status siklus hidup pada Slack, Discord, Signal, Telegram, dan WhatsApp. Pada Slack dan Discord, nilai yang tidak disetel mempertahankan reaksi status aktif saat reaksi ack aktif. Pada Signal, Telegram, dan WhatsApp, atur secara eksplisit ke true untuk mengaktifkan reaksi status siklus hidup.
• messages.statusReactions.emojis: meng-override kunci emoji siklus hidup: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft, dan stallHard. Telegram hanya mengizinkan kumpulan reaksi tetap, jadi emoji terkonfigurasi yang tidak didukung akan fallback ke varian status terdekat yang didukung untuk obrolan tersebut.

​

Debounce masuk

​

TTS (teks-ke-ucapan)

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

• auto mengontrol mode auto-TTS default: off, always, inbound, atau tagged. /tts on|off dapat mengganti preferensi lokal, dan /tts status menampilkan status efektif.
• summaryModel mengganti agents.defaults.model.primary untuk ringkasan otomatis.
• modelOverrides diaktifkan secara default; modelOverrides.allowProvider default-nya false (ikut serta secara eksplisit).
• Kunci API menggunakan fallback ke ELEVENLABS_API_KEY/XI_API_KEY dan OPENAI_API_KEY.
• Penyedia ucapan bawaan dimiliki oleh plugin. Jika plugins.allow diatur, sertakan setiap Plugin penyedia TTS yang ingin Anda gunakan, misalnya microsoft untuk Edge TTS. Id penyedia lama edge diterima sebagai alias untuk microsoft.
• providers.openai.baseUrl mengganti endpoint OpenAI TTS. Urutan resolusinya adalah konfigurasi, lalu OPENAI_TTS_BASE_URL, lalu https://api.openai.com/v1.
• Ketika providers.openai.baseUrl mengarah ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS yang kompatibel dengan OpenAI dan melonggarkan validasi model/suara.

​

Bicara

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider harus cocok dengan kunci di talk.providers ketika beberapa penyedia Bicara dikonfigurasi.
• Kunci Bicara datar lama (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) hanya untuk kompatibilitas. Jalankan openclaw doctor --fix untuk menulis ulang konfigurasi tersimpan ke talk.providers.<provider>.
• Id suara menggunakan fallback ke ELEVENLABS_VOICE_ID atau SAG_VOICE_ID.
• providers.*.apiKey menerima string teks biasa atau objek SecretRef.
• Fallback ELEVENLABS_API_KEY hanya berlaku ketika tidak ada kunci API Bicara yang dikonfigurasi.
• providers.*.voiceAliases memungkinkan direktif Bicara menggunakan nama yang mudah dikenali.
• providers.mlx.modelId memilih repo Hugging Face yang digunakan oleh pembantu MLX lokal macOS. Jika dihilangkan, macOS menggunakan mlx-community/Soprano-80M-bf16.
• Pemutaran MLX macOS berjalan melalui pembantu bawaan openclaw-mlx-tts saat tersedia, atau executable di PATH; OPENCLAW_MLX_TTS_BIN mengganti jalur pembantu untuk pengembangan.
• consultThinkingLevel mengontrol tingkat berpikir untuk eksekusi agen OpenClaw penuh di balik panggilan Control UI Bicara waktu nyata openclaw_agent_consult. Biarkan tidak diatur untuk mempertahankan perilaku sesi/model normal.
• consultFastMode menetapkan penggantian mode cepat sekali pakai untuk konsultasi Control UI Bicara waktu nyata tanpa mengubah pengaturan mode cepat normal sesi.
• speechLocale menetapkan id lokal BCP 47 yang digunakan oleh pengenalan ucapan Bicara iOS/macOS. Biarkan tidak diatur untuk menggunakan default perangkat.
• silenceTimeoutMs mengontrol berapa lama mode Bicara menunggu setelah pengguna diam sebelum mengirim transkrip. Tidak diatur mempertahankan jendela jeda default platform (700 ms on macOS and Android, 900 ms on iOS).
• realtime.instructions menambahkan instruksi sistem yang ditujukan ke penyedia ke prompt waktu nyata bawaan OpenClaw, sehingga gaya suara dapat dikonfigurasi tanpa kehilangan panduan default openclaw_agent_consult.
• realtime.consultRouting mengontrol fallback relai Gateway ketika penyedia waktu nyata menghasilkan transkrip pengguna final tanpa openclaw_agent_consult: provider-direct mempertahankan balasan penyedia langsung, sedangkan force-agent-consult merutekan permintaan yang telah difinalisasi melalui OpenClaw.

​

Terkait

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