Referensi konfigurasi

Referensi konfigurasi inti untuk ~/.openclaw/openclaw.json. Untuk ikhtisar berorientasi tugas, lihat Konfigurasi.

Mencakup permukaan konfigurasi utama OpenClaw dan menautkan keluar ketika suatu subsistem memiliki referensi yang lebih mendalam. Katalog perintah milik kanal dan Plugin serta kenop memori/QMD mendalam berada di halaman masing-masing, bukan di halaman ini.

Kebenaran kode:

• openclaw config schema mencetak JSON Schema live yang digunakan untuk validasi dan Control UI, dengan metadata bawaan/Plugin/kanal digabungkan saat tersedia
• config.schema.lookup mengembalikan satu node skema berbasis cakupan path untuk tooling drill-down
• pnpm config:docs:check / pnpm config:docs:gen memvalidasi hash baseline dokumentasi konfigurasi terhadap permukaan skema saat ini

Path pencarian agen: gunakan aksi alat gateway config.schema.lookup untuk dokumentasi dan batasan tingkat field yang tepat sebelum mengedit. Gunakan Konfigurasi untuk panduan berorientasi tugas dan halaman ini untuk peta field yang lebih luas, default, serta tautan ke referensi subsistem.

Referensi mendalam khusus:

• Referensi konfigurasi memori untuk agents.defaults.memorySearch.*, memory.qmd.*, memory.citations, dan konfigurasi dreaming di bawah plugins.entries.memory-core.config.dreaming
• Perintah slash untuk katalog perintah bawaan + paket saat ini
• halaman kanal/Plugin pemilik untuk permukaan perintah khusus kanal

Format konfigurasi adalah JSON5 (komentar + koma akhir diperbolehkan). Semua field bersifat opsional - OpenClaw menggunakan default aman saat dihilangkan.

# Kanal

Kunci konfigurasi per kanal dipindahkan ke halaman khusus - lihat Konfigurasi - kanal untuk channels.*, termasuk Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan kanal bawaan lainnya (auth, kontrol akses, multi-akun, gating mention).

# Default agen, multi-agen, sesi, dan pesan

Dipindahkan ke halaman khusus - lihat Konfigurasi - agen untuk:

• agents.defaults.* (workspace, model, thinking, heartbeat, memori, media, skills, sandbox)
• multiAgent.* (routing dan binding multi-agen)
• session.* (siklus hidup sesi, compaction, pruning)
• messages.* (pengiriman pesan, TTS, rendering markdown)
• talk.* (mode Talk)
  • talk.speechLocale: id locale BCP 47 opsional untuk pengenalan ucapan Talk di iOS/macOS
  • talk.silenceTimeoutMs: saat tidak diatur, Talk mempertahankan jendela jeda default platform sebelum mengirim transkrip (700 ms on macOS and Android, 900 ms on iOS)

# Alat dan provider kustom

Kebijakan alat, toggle eksperimental, konfigurasi alat berbasis provider, dan setup provider / URL dasar kustom dipindahkan ke halaman khusus - lihat Konfigurasi - alat dan provider kustom.

# Model

Definisi provider, allowlist model, dan setup provider kustom berada di Konfigurasi - alat dan provider kustom. Root models juga memiliki perilaku katalog model global.

{
  models: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• models.mode: perilaku katalog provider (merge atau replace).
• models.providers: peta provider kustom yang dikunci berdasarkan id provider.
• models.pricing.enabled: mengontrol bootstrap harga latar belakang yang dimulai setelah sidecar dan kanal mencapai path Gateway siap. Saat false, Gateway melewati fetch katalog harga OpenRouter dan LiteLLM; nilai models.providers.*.models[].cost yang dikonfigurasi tetap berfungsi untuk estimasi biaya lokal.

# MCP

Definisi server MCP yang dikelola OpenClaw berada di bawah mcp.servers dan dikonsumsi oleh Pi tertanam serta adapter runtime lainnya. Perintah openclaw mcp list, show, set, dan unset mengelola blok ini tanpa terhubung ke server target selama pengeditan konfigurasi.

{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• mcp.servers: definisi server MCP stdio atau remote bernama untuk runtime yang mengekspos alat MCP yang dikonfigurasi. Entri remote menggunakan transport: "streamable-http" atau transport: "sse"; type: "http" adalah alias native CLI yang dinormalisasi oleh openclaw mcp set dan openclaw doctor --fix ke field transport kanonis.
• mcp.sessionIdleTtlMs: TTL idle untuk runtime MCP bawaan berbasis cakupan sesi. Eksekusi tertanam sekali jalan meminta pembersihan akhir eksekusi; TTL ini adalah penyangga untuk sesi berumur panjang dan pemanggil mendatang.
• Perubahan di bawah mcp.* diterapkan panas dengan membuang runtime MCP sesi yang di-cache. Discovery/penggunaan alat berikutnya membuatnya ulang dari konfigurasi baru, sehingga entri mcp.servers yang dihapus langsung dipanen alih-alih menunggu TTL idle.

Lihat MCP dan Backend CLI untuk perilaku runtime.

# Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: allowlist opsional hanya untuk Skills bawaan (Skills terkelola/workspace tidak terpengaruh).
• load.extraDirs: root skill bersama tambahan (presedensi terendah).
• install.preferBrew: saat true, lebih memilih installer Homebrew ketika brew tersedia sebelum fallback ke jenis installer lain.
• install.nodeManager: preferensi installer Node untuk spesifikasi metadata.openclaw.install (npm | pnpm | yarn | bun).
• entries.<skillKey>.enabled: false menonaktifkan skill meskipun bawaan/terinstal.
• entries.<skillKey>.apiKey: kemudahan untuk Skills yang mendeklarasikan env var utama (string plaintext atau objek SecretRef).

# Plugin

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    bundledDiscovery: "allowlist",
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• Dimuat dari ~/.openclaw/extensions, <workspace>/.openclaw/extensions, ditambah plugins.load.paths.
• Discovery menerima Plugin native OpenClaw plus bundle Codex yang kompatibel dan bundle Claude, termasuk bundle layout default Claude tanpa manifest.
• Perubahan konfigurasi memerlukan restart gateway.
• allow: allowlist opsional (hanya Plugin yang tercantum yang dimuat). deny menang.
• bundledDiscovery: default ke "allowlist" untuk konfigurasi baru, sehingga plugins.allow yang tidak kosong juga membatasi Plugin provider bawaan, termasuk provider runtime web-search. Doctor menulis "compat" untuk konfigurasi allowlist legacy yang dimigrasikan untuk mempertahankan perilaku provider bawaan yang ada sampai Anda ikut serta.
• plugins.entries.<id>.apiKey: field kemudahan kunci API tingkat Plugin (saat didukung oleh Plugin).
• plugins.entries.<id>.env: peta env var berbasis cakupan Plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: saat false, core memblokir before_prompt_build dan mengabaikan field yang memutasi prompt dari before_agent_start legacy, sambil mempertahankan modelOverride dan providerOverride legacy. Berlaku untuk hook Plugin native dan direktori hook yang disediakan bundle yang didukung.
• plugins.entries.<id>.hooks.allowConversationAccess: saat true, Plugin non-bawaan tepercaya dapat membaca konten percakapan mentah dari hook bertipe seperti llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, dan agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: secara eksplisit memercayai Plugin ini untuk meminta override provider dan model per-eksekusi untuk eksekusi subagen latar belakang.
• plugins.entries.<id>.subagent.allowedModels: allowlist opsional target provider/model kanonis untuk override subagen tepercaya. Gunakan "*" hanya saat Anda sengaja ingin mengizinkan model apa pun.
• plugins.entries.<id>.config: objek konfigurasi yang didefinisikan Plugin (divalidasi oleh skema Plugin native OpenClaw saat tersedia).
• Pengaturan akun/runtime Plugin kanal berada di bawah channels.<id> dan harus dijelaskan oleh metadata channelConfigs manifest Plugin pemiliknya, bukan oleh registry opsi OpenClaw pusat.
• plugins.entries.firecrawl.config.webFetch: pengaturan provider web-fetch Firecrawl.
  • apiKey: kunci API Firecrawl (menerima SecretRef). Fallback ke plugins.entries.firecrawl.config.webSearch.apiKey, legacy tools.web.fetch.firecrawl.apiKey, atau env var FIRECRAWL_API_KEY.
  • baseUrl: URL dasar API Firecrawl (default: https://api.firecrawl.dev; override self-hosted harus menarget endpoint private/internal).
  • onlyMainContent: mengekstrak hanya konten utama dari halaman (default: true).
  • maxAgeMs: usia cache maksimum dalam milidetik (default: 172800000 / 2 hari).
  • timeoutSeconds: timeout permintaan scrape dalam detik (default: 60).
• plugins.entries.xai.config.xSearch: pengaturan xAI X Search (pencarian web Grok).
  • enabled: mengaktifkan provider X Search.
  • model: model Grok yang digunakan untuk pencarian (misalnya "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: pengaturan memory dreaming. Lihat Dreaming untuk fase dan ambang.
  • enabled: sakelar utama dreaming (default false).
  • frequency: cadence Cron untuk setiap sweep dreaming penuh ("0 3 * * *" secara default).
  • model: override model subagen Dream Diary opsional. Memerlukan plugins.entries.memory-core.subagent.allowModelOverride: true; padukan dengan allowedModels untuk membatasi target. Error model tidak tersedia dicoba ulang sekali dengan model default sesi; kegagalan kepercayaan atau allowlist tidak fallback diam-diam.
  • kebijakan fase dan ambang adalah detail implementasi (bukan kunci konfigurasi yang berhadapan dengan pengguna).
• Konfigurasi memori lengkap berada di Referensi konfigurasi memori:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Plugin bundle Claude yang diaktifkan juga dapat menyumbangkan default Pi tertanam dari settings.json; OpenClaw menerapkannya sebagai pengaturan agen yang disanitasi, bukan sebagai patch konfigurasi OpenClaw mentah.
• plugins.slots.memory: pilih id Plugin memori aktif, atau "none" untuk menonaktifkan Plugin memori.
• plugins.slots.contextEngine: pilih id Plugin mesin konteks aktif; default ke "legacy" kecuali Anda menginstal dan memilih mesin lain.

Lihat Plugin.

# Komitmen

commitments mengontrol memori tindak lanjut yang disimpulkan: OpenClaw dapat mendeteksi check-in dari giliran percakapan dan mengirimkannya melalui eksekusi heartbeat.

• commitments.enabled: mengaktifkan ekstraksi LLM tersembunyi, penyimpanan, dan pengiriman heartbeat untuk komitmen tindak lanjut yang disimpulkan. Default: false.
• commitments.maxPerDay: jumlah maksimum komitmen tindak lanjut yang disimpulkan yang dikirim per sesi agen dalam hari bergulir. Default: 3.

Lihat Komitmen yang disimpulkan.

# Browser

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false menonaktifkan act:evaluate dan wait --fn.
• tabCleanup mengambil kembali tab agen utama terlacak setelah waktu idle atau ketika sebuah sesi melebihi batasnya. Atur idleMinutes: 0 atau maxTabsPerSession: 0 untuk menonaktifkan masing-masing mode pembersihan tersebut.
• ssrfPolicy.dangerouslyAllowPrivateNetwork dinonaktifkan ketika tidak diatur, sehingga navigasi browser tetap ketat secara default.
• Atur ssrfPolicy.dangerouslyAllowPrivateNetwork: true hanya ketika Anda sengaja memercayai navigasi browser jaringan privat.
• Dalam mode ketat, endpoint profil CDP jarak jauh (profiles.*.cdpUrl) tunduk pada pemblokiran jaringan privat yang sama selama pemeriksaan keterjangkauan/penemuan.
• ssrfPolicy.allowPrivateNetwork tetap didukung sebagai alias lama.
• Dalam mode ketat, gunakan ssrfPolicy.hostnameAllowlist dan ssrfPolicy.allowedHostnames untuk pengecualian eksplisit.
• Profil jarak jauh bersifat hanya-lampirkan (mulai/henti/reset dinonaktifkan).
• profiles.*.cdpUrl menerima http://, https://, ws://, dan wss://. Gunakan HTTP(S) ketika Anda ingin OpenClaw menemukan /json/version; gunakan WS(S) ketika penyedia Anda memberi URL WebSocket DevTools langsung.
• remoteCdpTimeoutMs dan remoteCdpHandshakeTimeoutMs berlaku untuk keterjangkauan CDP jarak jauh dan attachOnly, plus permintaan pembukaan tab. Profil loopback terkelola mempertahankan default CDP lokal.
• Jika layanan CDP yang dikelola secara eksternal dapat dijangkau melalui loopback, atur attachOnly: true pada profil tersebut; jika tidak, OpenClaw memperlakukan port loopback sebagai profil browser terkelola lokal dan dapat melaporkan kesalahan kepemilikan port lokal.
• Profil existing-session menggunakan Chrome MCP, bukan CDP, dan dapat melampirkan pada host yang dipilih atau melalui node browser yang terhubung.
• Profil existing-session dapat mengatur userDataDir untuk menargetkan profil browser berbasis Chromium tertentu seperti Brave atau Edge.
• Profil existing-session mempertahankan batas rute Chrome MCP saat ini: tindakan berbasis snapshot/ref, bukan penargetan pemilih CSS, hook unggah satu file, tanpa penggantian batas waktu dialog, tanpa wait --load networkidle, dan tanpa responsebody, ekspor PDF, intersepsi unduhan, atau tindakan batch.
• Profil openclaw terkelola lokal menetapkan otomatis cdpPort dan cdpUrl; hanya atur cdpUrl secara eksplisit untuk CDP jarak jauh.
• Profil terkelola lokal dapat mengatur executablePath untuk mengganti browser.executablePath global pada profil tersebut. Gunakan ini untuk menjalankan satu profil di Chrome dan profil lain di Brave.
• Profil terkelola lokal menggunakan browser.localLaunchTimeoutMs untuk penemuan HTTP CDP Chrome setelah proses dimulai dan browser.localCdpReadyTimeoutMs untuk kesiapan websocket CDP pascapeluncuran. Naikkan nilainya pada host yang lebih lambat ketika Chrome berhasil dimulai tetapi pemeriksaan kesiapan berkejaran dengan startup. Kedua nilai harus berupa bilangan bulat positif hingga 120000 ms; nilai konfigurasi yang tidak valid ditolak.
• Urutan deteksi otomatis: browser default jika berbasis Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath dan browser.profiles.<name>.executablePath sama-sama menerima ~ dan ~/... untuk direktori home OS Anda sebelum peluncuran Chromium. userDataDir per profil pada profil existing-session juga diperluas dari tilde.
• Layanan kontrol: hanya loopback (port diturunkan dari gateway.port, default 18791).
• extraArgs menambahkan flag peluncuran ekstra ke startup Chromium lokal (misalnya --disable-gpu, ukuran jendela, atau flag debug).

# UI

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: warna aksen untuk chrome UI aplikasi native (warna gelembung Talk Mode, dll.).
• assistant: pengganti identitas Control UI. Kembali ke identitas agen aktif jika tidak diatur.

# Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

# Endpoint kompatibel OpenAI

• Chat Completions: dinonaktifkan secara default. Aktifkan dengan gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Penguatan input URL Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Daftar izin kosong diperlakukan sebagai belum diatur; gunakan gateway.http.endpoints.responses.files.allowUrl=false dan/atau gateway.http.endpoints.responses.images.allowUrl=false untuk menonaktifkan pengambilan URL.
• Header penguatan respons opsional:
  • gateway.http.securityHeaders.strictTransportSecurity (atur hanya untuk asal HTTPS yang Anda kontrol; lihat Auth Proxy Tepercaya)

# Isolasi multi-instans

Jalankan beberapa gateway pada satu host dengan port dan direktori state unik:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

Flag praktis: --dev (menggunakan ~/.openclaw-dev + port 19001), --profile <name> (menggunakan ~/.openclaw-<name>).

Lihat Beberapa Gateway.

# gateway.tls

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

• enabled: mengaktifkan terminasi TLS pada listener gateway (HTTPS/WSS) (default: false).
• autoGenerate: menghasilkan otomatis pasangan cert/key lokal self-signed ketika file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev.
• certPath: path sistem berkas ke file sertifikat TLS.
• keyPath: path sistem berkas ke file kunci privat TLS; jaga agar izin tetap terbatas.
• caPath: path bundle CA opsional untuk verifikasi klien atau rantai kepercayaan kustom.

# gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

• mode: mengontrol bagaimana edit konfigurasi diterapkan saat runtime.
  • "off": abaikan edit langsung; perubahan memerlukan restart eksplisit.
  • "restart": selalu restart proses gateway saat konfigurasi berubah.
  • "hot": terapkan perubahan di dalam proses tanpa restart.
  • "hybrid" (default): coba hot reload terlebih dahulu; fallback ke restart jika diperlukan.
• debounceMs: jendela debounce dalam ms sebelum perubahan konfigurasi diterapkan (bilangan bulat non-negatif).
• deferralTimeoutMs: waktu maksimum opsional dalam ms untuk menunggu operasi yang sedang berjalan sebelum memaksa restart atau hot reload channel. Hilangkan untuk menggunakan tunggu berbatas default (300000); atur 0 untuk menunggu tanpa batas dan mencatat peringatan masih-tertunda secara berkala.

# Hook

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

Autentikasi: Authorization: Bearer <token> atau x-openclaw-token: <token>. Token hook dalam query string ditolak.

Catatan validasi dan keamanan:

• hooks.enabled=true memerlukan hooks.token yang tidak kosong.
• hooks.token harus berbeda dari gateway.auth.token; penggunaan ulang token Gateway ditolak.
• hooks.path tidak boleh berupa /; gunakan subjalur khusus seperti /hooks.
• Jika hooks.allowRequestSessionKey=true, batasi hooks.allowedSessionKeyPrefixes (misalnya ["hook:"]).
• Jika pemetaan atau preset menggunakan sessionKey bertemplat, atur hooks.allowedSessionKeyPrefixes dan hooks.allowRequestSessionKey=true. Kunci pemetaan statis tidak memerlukan opt-in tersebut.

Titik akhir:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey dari payload permintaan hanya diterima jika hooks.allowRequestSessionKey=true (default: false).
• POST /hooks/<name> → diselesaikan melalui hooks.mappings
  • Nilai sessionKey pemetaan yang dirender dari templat diperlakukan sebagai nilai yang dipasok secara eksternal dan juga memerlukan hooks.allowRequestSessionKey=true.

# Integrasi Gmail

• Preset Gmail bawaan menggunakan sessionKey: "hook:gmail:{{messages[0].id}}".
• Jika Anda mempertahankan perutean per-pesan tersebut, atur hooks.allowRequestSessionKey: true dan batasi hooks.allowedSessionKeyPrefixes agar cocok dengan namespace Gmail, misalnya ["hook:", "hook:gmail:"].
• Jika Anda memerlukan hooks.allowRequestSessionKey: false, timpa preset dengan sessionKey statis alih-alih default bertemplat.

{
  hooks: {
    gmail: {
      account: "[email protected]",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gateway otomatis memulai gog gmail watch serve saat boot jika dikonfigurasi. Atur OPENCLAW_SKIP_GMAIL_WATCHER=1 untuk menonaktifkannya.
• Jangan menjalankan gog gmail watch serve terpisah bersamaan dengan Gateway.

# Host Plugin Canvas

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            root: "~/.openclaw/workspace/canvas",
            liveReload: true,
            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

• Menyajikan HTML/CSS/JS yang dapat diedit agen dan A2UI melalui HTTP di bawah port Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Hanya lokal: pertahankan gateway.bind: "loopback" (default).
• Bind non-loopback: rute canvas memerlukan autentikasi Gateway (token/kata sandi/proxy tepercaya), sama seperti permukaan HTTP Gateway lainnya.
• Node WebViews biasanya tidak mengirim header autentikasi; setelah node dipasangkan dan terhubung, Gateway mengiklankan URL capability bercakupan node untuk akses canvas/A2UI.
• URL capability terikat ke sesi WS node aktif dan cepat kedaluwarsa. Fallback berbasis IP tidak digunakan.
• Menyisipkan klien live-reload ke HTML yang disajikan.
• Otomatis membuat index.html starter saat kosong.
• Juga menyajikan A2UI di /__openclaw__/a2ui/.
• Perubahan memerlukan mulai ulang gateway.
• Nonaktifkan live reload untuk direktori besar atau error EMFILE.

# Penemuan

# mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (default ketika Plugin bonjour bawaan diaktifkan): hilangkan cliPath + sshPort dari record TXT.
• full: sertakan cliPath + sshPort; iklan multicast LAN tetap memerlukan Plugin bonjour bawaan untuk diaktifkan.
• off: menekan iklan multicast LAN tanpa mengubah pengaktifan Plugin.
• Plugin bonjour bawaan otomatis dimulai pada host macOS dan bersifat opt-in pada deployment Gateway Linux, Windows, dan terkontainerisasi.
• Nama host default ke nama host sistem ketika merupakan label DNS yang valid, dengan fallback ke openclaw. Timpa dengan OPENCLAW_MDNS_HOSTNAME.

# Area luas (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

Menulis zona DNS-SD unicast di bawah ~/.openclaw/dns/. Untuk penemuan lintas jaringan, pasangkan dengan server DNS (CoreDNS direkomendasikan) + DNS terpisah Tailscale.

Penyiapan: openclaw dns setup --apply.

# Lingkungan

# env (variabel lingkungan inline)

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• Variabel lingkungan inline hanya diterapkan jika variabel lingkungan proses tidak memiliki key tersebut.
• File .env: .env CWD + ~/.openclaw/.env (keduanya tidak menimpa variabel yang sudah ada).
• shellEnv: mengimpor key yang diharapkan tetapi belum ada dari profil shell login Anda.
• Lihat Lingkungan untuk prioritas lengkap.

# Substitusi variabel lingkungan

Rujuk variabel lingkungan dalam string konfigurasi apa pun dengan ${VAR_NAME}:

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Hanya nama huruf besar yang cocok: [A-Z_][A-Z0-9_]*.
• Variabel yang hilang/kosong akan memunculkan error saat konfigurasi dimuat.
• Escape dengan $${VAR} untuk literal ${VAR}.
• Berfungsi dengan $include.

# Rahasia

Referensi rahasia bersifat aditif: nilai plaintext tetap berfungsi.

# SecretRef

Gunakan satu bentuk objek:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Validasi:

• Pola provider: ^[a-z][a-z0-9_-]{0,63}$
• Pola id source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• id source: "file": pointer JSON absolut (misalnya "/providers/openai/apiKey")
• Pola id source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• id source: "exec" tidak boleh berisi segmen path yang dipisahkan slash berupa . atau .. (misalnya a/../b ditolak)

# Permukaan kredensial yang didukung

• Matriks kanonis: Permukaan Kredensial SecretRef
• Target secrets apply mendukung path kredensial openclaw.json.
• Referensi auth-profiles.json disertakan dalam resolusi runtime dan cakupan audit.

# Konfigurasi penyedia rahasia

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

Catatan:

• Penyedia file mendukung mode: "json" dan mode: "singleValue" (id harus berupa "value" dalam mode singleValue).
• Path penyedia file dan exec gagal tertutup saat verifikasi ACL Windows tidak tersedia. Tetapkan allowInsecurePath: true hanya untuk path tepercaya yang tidak dapat diverifikasi.
• Penyedia exec memerlukan path command absolut dan menggunakan payload protokol pada stdin/stdout.
• Secara default, path perintah symlink ditolak. Tetapkan allowSymlinkCommand: true untuk mengizinkan path symlink sambil memvalidasi path target yang di-resolve.
• Jika trustedDirs dikonfigurasi, pemeriksaan direktori tepercaya diterapkan pada path target yang di-resolve.
• Lingkungan child exec minimal secara default; teruskan variabel yang diperlukan secara eksplisit dengan passEnv.
• Referensi rahasia di-resolve saat aktivasi menjadi snapshot dalam memori, lalu path permintaan hanya membaca snapshot tersebut.
• Pemfilteran permukaan aktif diterapkan selama aktivasi: referensi yang belum di-resolve pada permukaan yang diaktifkan menggagalkan startup/reload, sedangkan permukaan tidak aktif dilewati dengan diagnostik.

# Penyimpanan autentikasi

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex:personal"],
    },
  },
}

• Profil per-agent disimpan di <agentDir>/auth-profiles.json.
• auth-profiles.json mendukung referensi tingkat nilai (keyRef untuk api_key, tokenRef untuk token) untuk mode kredensial statis.
• Map datar lama auth-profiles.json seperti { "provider": { "apiKey": "..." } } bukan format runtime; openclaw doctor --fix menulis ulang map tersebut menjadi profil API-key provider:default kanonis dengan cadangan .legacy-flat.*.bak.
• Profil mode OAuth (auth.profiles.<id>.mode = "oauth") tidak mendukung kredensial auth-profile yang didukung SecretRef.
• Kredensial runtime statis berasal dari snapshot yang telah di-resolve dalam memori; entri statis lama auth.json dibersihkan saat ditemukan.
• Impor OAuth lama berasal dari ~/.openclaw/credentials/oauth.json.
• Lihat OAuth.
• Perilaku runtime rahasia dan tooling audit/configure/apply: Manajemen Rahasia.

# auth.cooldowns

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

• billingBackoffHours: backoff dasar dalam jam ketika profil gagal karena kesalahan billing/kredit-tidak-mencukupi yang sebenarnya (default: 5). Teks billing eksplisit masih dapat masuk ke sini bahkan pada respons 401/403, tetapi pencocok teks khusus penyedia tetap dibatasi pada penyedia yang memilikinya (misalnya OpenRouter Key limit exceeded). Pesan HTTP 402 yang dapat dicoba ulang untuk jendela penggunaan atau batas pengeluaran organisasi/workspace tetap berada di jalur rate_limit.
• billingBackoffHoursByProvider: override opsional per penyedia untuk jam backoff billing.
• billingMaxHours: batas dalam jam untuk pertumbuhan eksponensial backoff billing (default: 24).
• authPermanentBackoffMinutes: backoff dasar dalam menit untuk kegagalan auth_permanent dengan keyakinan tinggi (default: 10).
• authPermanentMaxMinutes: batas dalam menit untuk pertumbuhan backoff auth_permanent (default: 60).
• failureWindowHours: jendela bergulir dalam jam yang digunakan untuk penghitung backoff (default: 24).
• overloadedProfileRotations: jumlah maksimum rotasi auth-profile pada penyedia yang sama untuk kesalahan overloaded sebelum beralih ke fallback model (default: 1). Bentuk provider-busy seperti ModelNotReadyException masuk ke sini.
• overloadedBackoffMs: jeda tetap sebelum mencoba ulang rotasi penyedia/profil yang overloaded (default: 0).
• rateLimitedProfileRotations: jumlah maksimum rotasi auth-profile pada penyedia yang sama untuk kesalahan rate-limit sebelum beralih ke fallback model (default: 1). Bucket rate-limit tersebut mencakup teks berbentuk penyedia seperti Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, dan resource exhausted.

# Pencatatan log

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• File log default: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Atur logging.file untuk path yang stabil.
• consoleLevel naik menjadi debug ketika --verbose.
• maxFileBytes: ukuran maksimum file log aktif dalam byte sebelum rotasi (bilangan bulat positif; default: 104857600 = 100 MB). OpenClaw menyimpan hingga lima arsip bernomor di samping file aktif.
• redactSensitive / redactPatterns: penyamaran upaya terbaik untuk output konsol, log file, catatan log OTLP, dan teks transkrip sesi yang dipersistenkan. redactSensitive: "off" hanya menonaktifkan kebijakan log/transkrip umum ini; permukaan keamanan UI/tool/diagnostik tetap menyamarkan rahasia sebelum emisi.

# Diagnostik

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 600000,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• enabled: toggle utama untuk output instrumentasi (default: true).
• flags: array string flag yang mengaktifkan output log tertarget (mendukung wildcard seperti "telegram.*" atau "*").
• stuckSessionWarnMs: ambang usia tanpa progres dalam ms untuk mengklasifikasikan sesi pemrosesan berjalan lama sebagai session.long_running, session.stalled, atau session.stuck. Balasan, tool, status, blok, dan progres ACP mereset timer; diagnostik session.stuck berulang melakukan backoff selama tidak berubah.
• stuckSessionAbortMs: ambang usia tanpa progres dalam ms sebelum pekerjaan aktif yang stalled dan memenuhi syarat dapat di-abort-drain untuk pemulihan. Jika tidak disetel, OpenClaw menggunakan jendela embedded-run diperpanjang yang lebih aman setidaknya 10 menit dan 5x stuckSessionWarnMs.
• otel.enabled: mengaktifkan pipeline ekspor OpenTelemetry (default: false). Untuk konfigurasi lengkap, katalog sinyal, dan model privasi, lihat Ekspor OpenTelemetry.
• otel.endpoint: URL collector untuk ekspor OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: endpoint OTLP opsional khusus sinyal. Ketika disetel, nilai ini menggantikan otel.endpoint hanya untuk sinyal tersebut.
• otel.protocol: "http/protobuf" (default) atau "grpc".
• otel.headers: header metadata HTTP/gRPC tambahan yang dikirim dengan permintaan ekspor OTel.
• otel.serviceName: nama layanan untuk atribut resource.
• otel.traces / otel.metrics / otel.logs: aktifkan ekspor trace, metrik, atau log.
• otel.sampleRate: tingkat sampling trace 0-1.
• otel.flushIntervalMs: interval flush telemetri berkala dalam ms.
• otel.captureContent: pengambilan konten mentah opt-in untuk atribut span OTEL. Defaultnya nonaktif. Boolean true menangkap konten pesan/tool non-sistem; bentuk objek memungkinkan Anda mengaktifkan inputMessages, outputMessages, toolInputs, toolOutputs, dan systemPrompt secara eksplisit.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: toggle lingkungan untuk atribut penyedia span GenAI eksperimental terbaru. Secara default, span mempertahankan atribut lama gen_ai.system untuk kompatibilitas; metrik GenAI menggunakan atribut semantik terbatas.
• OPENCLAW_OTEL_PRELOADED=1: toggle lingkungan untuk host yang sudah mendaftarkan SDK OpenTelemetry global. OpenClaw kemudian melewati startup/shutdown SDK milik Plugin sambil tetap menjaga listener diagnostik aktif.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, dan OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: env var endpoint khusus sinyal yang digunakan ketika kunci konfigurasi yang sesuai tidak disetel.
• cacheTrace.enabled: catat snapshot trace cache untuk embedded run (default: false).
• cacheTrace.filePath: path output untuk JSONL trace cache (default: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: mengontrol apa yang disertakan dalam output trace cache (semua default: true).

# Pembaruan

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• channel: kanal rilis untuk instalasi npm/git - "stable", "beta", atau "dev".
• checkOnStart: periksa pembaruan npm saat gateway dimulai (default: true).
• auto.enabled: aktifkan auto-update latar belakang untuk instalasi paket (default: false).
• auto.stableDelayHours: jeda minimum dalam jam sebelum auto-apply kanal stable (default: 6; maks: 168).
• auto.stableJitterHours: jendela sebaran rollout tambahan kanal stable dalam jam (default: 12; maks: 168).
• auto.betaCheckIntervalHours: seberapa sering pemeriksaan kanal beta berjalan dalam jam (default: 1; maks: 24).

# ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• enabled: feature gate ACP global (default: true; setel false untuk menyembunyikan dispatch ACP dan affordance spawn).
• dispatch.enabled: gate independen untuk dispatch giliran sesi ACP (default: true). Setel false untuk menjaga perintah ACP tetap tersedia sambil memblokir eksekusi.
• backend: id backend runtime ACP default (harus cocok dengan Plugin runtime ACP terdaftar). Instal Plugin backend terlebih dahulu, dan jika plugins.allow disetel, sertakan id Plugin backend (misalnya acpx) atau backend ACP tidak akan dimuat.
• defaultAgent: id agen target ACP fallback ketika spawn tidak menentukan target eksplisit.
• allowedAgents: allowlist id agen yang diizinkan untuk sesi runtime ACP; kosong berarti tidak ada pembatasan tambahan.
• maxConcurrentSessions: jumlah maksimum sesi ACP aktif secara bersamaan.
• stream.coalesceIdleMs: jendela flush idle dalam ms untuk teks yang di-stream.
• stream.maxChunkChars: ukuran chunk maksimum sebelum memecah proyeksi blok yang di-stream.
• stream.repeatSuppression: tekan baris status/tool berulang per giliran (default: true).
• stream.deliveryMode: "live" melakukan stream secara bertahap; "final_only" melakukan buffer hingga event terminal giliran.
• stream.hiddenBoundarySeparator: pemisah sebelum teks terlihat setelah event tool tersembunyi (default: "paragraph").
• stream.maxOutputChars: karakter output asisten maksimum yang diproyeksikan per giliran ACP.
• stream.maxSessionUpdateChars: karakter maksimum untuk baris status/pembaruan ACP yang diproyeksikan.
• stream.tagVisibility: catatan nama tag ke override visibilitas boolean untuk event yang di-stream.
• runtime.ttlMinutes: TTL idle dalam menit untuk worker sesi ACP sebelum memenuhi syarat untuk pembersihan.
• runtime.installCommand: perintah instal opsional untuk dijalankan saat melakukan bootstrap lingkungan runtime ACP.

# CLI

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• cli.banner.taglineMode mengontrol gaya tagline banner:
  • "random" (default): tagline lucu/musiman yang berotasi.
  • "default": tagline netral tetap (All your chats, one OpenClaw.).
  • "off": tidak ada teks tagline (judul/versi banner tetap ditampilkan).
• Untuk menyembunyikan seluruh banner (bukan hanya tagline), setel env OPENCLAW_HIDE_BANNER=1.

# Panduan

Metadata yang ditulis oleh alur penyiapan terpandu CLI (onboard, configure, doctor):

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

# Identitas

Lihat kolom identitas agents.list di bawah Default agen.

# Jembatan (lama, dihapus)

Build saat ini tidak lagi menyertakan jembatan TCP. Node terhubung melalui WebSocket Gateway. Kunci bridge.* tidak lagi menjadi bagian dari skema konfigurasi (validasi gagal hingga dihapus; openclaw doctor --fix dapat menghapus kunci yang tidak dikenal).

{
"bridge": {
  "enabled": true,
  "port": 18790,
  "bind": "tailnet",
  "tls": {
    "enabled": true,
    "autoGenerate": true
  }
}
}

# Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention: berapa lama menyimpan sesi eksekusi Cron terisolasi yang sudah selesai sebelum dipangkas dari sessions.json. Juga mengontrol pembersihan transkrip Cron terhapus yang diarsipkan. Default: 24h; atur false untuk menonaktifkan.
• runLog.maxBytes: ukuran maksimum per berkas log eksekusi (cron/runs/<jobId>.jsonl) sebelum dipangkas. Default: 2_000_000 byte.
• runLog.keepLines: baris terbaru yang dipertahankan saat pemangkasan log eksekusi dipicu. Default: 2000.
• webhookToken: token bearer yang digunakan untuk pengiriman POST Webhook Cron (delivery.mode = "webhook"), jika dihilangkan tidak ada header auth yang dikirim.
• webhook: URL Webhook fallback lama yang sudah tidak digunakan (http/https) yang hanya digunakan untuk job tersimpan yang masih memiliki notify: true.

# cron.retry

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• maxAttempts: retry maksimum untuk job sekali jalan pada error sementara (default: 3; rentang: 0-10).
• backoffMs: array penundaan backoff dalam md untuk setiap percobaan retry (default: [30000, 60000, 300000]; 1-10 entri).
• retryOn: jenis error yang memicu retry - "rate_limit", "overloaded", "network", "timeout", "server_error". Hilangkan untuk me-retry semua jenis sementara.

Hanya berlaku untuk job Cron sekali jalan. Job berulang menggunakan penanganan kegagalan terpisah.

# cron.failureAlert

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

• enabled: mengaktifkan peringatan kegagalan untuk job Cron (default: false).
• after: kegagalan berturut-turut sebelum peringatan dikirim (bilangan bulat positif, min: 1).
• cooldownMs: milidetik minimum antara peringatan berulang untuk job yang sama (bilangan bulat non-negatif).
• includeSkipped: menghitung eksekusi yang dilewati secara berturut-turut ke ambang peringatan (default: false). Eksekusi yang dilewati dilacak secara terpisah dan tidak memengaruhi backoff error eksekusi.
• mode: mode pengiriman - "announce" mengirim melalui pesan channel; "webhook" mem-posting ke Webhook yang dikonfigurasi.
• accountId: akun opsional atau id channel untuk membatasi cakupan pengiriman peringatan.

# cron.failureDestination

{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• Tujuan default untuk notifikasi kegagalan Cron di semua job.
• mode: "announce" atau "webhook"; default ke "announce" ketika data target yang cukup tersedia.
• channel: override channel untuk pengiriman announce. "last" menggunakan kembali channel pengiriman terakhir yang diketahui.
• to: target announce eksplisit atau URL Webhook. Wajib untuk mode Webhook.
• accountId: override akun opsional untuk pengiriman.
• delivery.failureDestination per job menggantikan default global ini.
• Ketika tujuan kegagalan global maupun per job tidak disetel, job yang sudah mengirim melalui announce fallback ke target announce utama tersebut saat gagal.
• delivery.failureDestination hanya didukung untuk job sessionTarget="isolated" kecuali delivery.mode utama job adalah "webhook".

Lihat Job Cron. Eksekusi Cron terisolasi dilacak sebagai tugas latar belakang.

# Variabel templat model media

Placeholder templat yang diperluas di tools.media.models[].args:

# Penyertaan konfigurasi ($include)

Pisahkan konfigurasi ke beberapa berkas:

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

Perilaku penggabungan:

• Satu berkas: mengganti objek yang memuatnya.
• Array berkas: digabungkan secara mendalam berurutan (yang lebih akhir menggantikan yang lebih awal).
• Kunci sibling: digabungkan setelah penyertaan (menggantikan nilai yang disertakan).
• Penyertaan bersarang: hingga 10 tingkat kedalaman.
• Path: di-resolve relatif terhadap berkas yang menyertakan, tetapi harus tetap berada di dalam direktori konfigurasi tingkat atas (dirname dari openclaw.json). Bentuk absolut/../ hanya diizinkan saat hasil resolve tetap berada di dalam batas tersebut.
• Penulisan milik OpenClaw yang hanya mengubah satu bagian tingkat atas yang didukung oleh penyertaan satu berkas menulis tembus ke berkas yang disertakan tersebut. Misalnya, plugins install memperbarui plugins: { $include: "./plugins.json5" } di plugins.json5 dan membiarkan openclaw.json tetap utuh.
• Penyertaan root, array penyertaan, dan penyertaan dengan override sibling bersifat baca-saja untuk penulisan milik OpenClaw; penulisan tersebut gagal tertutup alih-alih meratakan konfigurasi.
• Error: pesan yang jelas untuk berkas yang hilang, error parsing, dan penyertaan sirkular.

Terkait: Konfigurasi · Contoh konfigurasi · Doctor

# Terkait

• Konfigurasi
• Contoh konfigurasi