Referensi konfigurasi

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

Mencakup permukaan konfigurasi utama OpenClaw dan menautkan ke luar ketika sebuah subsistem memiliki referensi yang lebih mendalam. Katalog perintah milik saluran dan plugin serta knob memori/QMD mendalam berada di halaman masing-masing, bukan di halaman ini.

Kebenaran kode:

• openclaw config schema mencetak JSON Schema langsung yang digunakan untuk validasi dan Control UI, dengan metadata terbundel/plugin/saluran digabungkan saat tersedia
• config.schema.lookup mengembalikan satu node skema terbatas jalur untuk tooling penelusuran mendalam
• pnpm config:docs:check / pnpm config:docs:gen memvalidasi hash baseline dokumen konfigurasi terhadap permukaan skema saat ini

Jalur pencarian agen: gunakan aksi tool gateway config.schema.lookup untuk dokumentasi dan batasan tingkat bidang yang tepat sebelum pengeditan. Gunakan Konfigurasi untuk panduan berorientasi tugas dan halaman ini untuk peta bidang yang lebih luas, default, dan 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 + terbundel saat ini
• halaman saluran/plugin pemilik untuk permukaan perintah khusus saluran

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

Saluran

Kunci konfigurasi per saluran dipindahkan ke halaman khusus - lihat Konfigurasi - saluran untuk channels.*, termasuk Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan saluran terbundel 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.consultThinkingLevel: override tingkat thinking untuk keseluruhan eksekusi agen OpenClaw di balik konsultasi realtime Control UI Talk
  • talk.consultFastMode: override sekali pakai mode cepat untuk konsultasi realtime Control UI Talk
  • talk.speechLocale: id locale BCP 47 opsional untuk pengenalan ucapan Talk di iOS/macOS
  • talk.silenceTimeoutMs: saat tidak disetel, Talk mempertahankan jendela jeda default platform sebelum mengirim transkrip (700 ms on macOS and Android, 900 ms on iOS)
  • talk.realtime.consultRouting: fallback relay Gateway untuk transkrip Talk realtime yang sudah final yang melewati openclaw_agent_consult

Tool dan penyedia kustom

Kebijakan tool, toggle eksperimental, konfigurasi tool berbasis penyedia, dan penyiapan penyedia / base-URL kustom dipindahkan ke halaman khusus - lihat Konfigurasi - tool dan penyedia kustom.

Model

Definisi penyedia, allowlist model, dan penyiapan penyedia kustom berada di Konfigurasi - tool dan penyedia 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 penyedia (merge atau replace).
• models.providers: peta penyedia kustom yang dikunci oleh id penyedia.
• models.providers.*.localService: manajer proses on-demand opsional untuk server model lokal. OpenClaw memeriksa endpoint kesehatan yang dikonfigurasi, memulai command absolut saat diperlukan, menunggu kesiapan, lalu mengirim permintaan model. Lihat Layanan model lokal.
• models.pricing.enabled: mengontrol bootstrap harga latar belakang yang dimulai setelah sidecar dan saluran mencapai jalur siap Gateway. Saat false, Gateway melewati pengambilan 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 OpenClaw 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        timeout: 20,        connectTimeout: 5,        supportsParallelToolCalls: true,        headers: {          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",        },        auth: "oauth",        oauth: {          scope: "docs.read",        },        sslVerify: true,        clientCert: "/path/to/client.crt",        clientKey: "/path/to/client.key",        toolFilter: {          include: ["search_*"],          exclude: ["admin_*"],        },        // Optional Codex app-server projection controls.        codex: {          agents: ["main"],          defaultToolsApprovalMode: "approve", // auto | prompt | approve        },      },    },  },}

• mcp.servers: definisi server MCP stdio atau remote bernama untuk runtime yang mengekspos tool 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 dalam bidang transport kanonis.
• mcp.servers.<name>.enabled: setel false untuk mempertahankan definisi server tersimpan sekaligus mengecualikannya dari penemuan MCP OpenClaw tertanam dan proyeksi tool.
• mcp.servers.<name>.timeout / requestTimeoutMs: timeout permintaan MCP per server dalam detik atau milidetik.
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs: timeout koneksi per server dalam detik atau milidetik.
• mcp.servers.<name>.supportsParallelToolCalls: petunjuk konkurensi opsional untuk adapter yang dapat memilih apakah akan menerbitkan panggilan tool MCP paralel.
• mcp.servers.<name>.auth: setel "oauth" untuk server MCP HTTP yang memerlukan OAuth. Jalankan openclaw mcp login <name> untuk menyimpan token di bawah state OpenClaw.
• mcp.servers.<name>.oauth: override opsional untuk scope OAuth, URL redirect, dan URL metadata klien.
• mcp.servers.<name>.sslVerify, clientCert, clientKey: kontrol TLS HTTP untuk endpoint privat dan mutual TLS.
• mcp.servers.<name>.toolFilter: pemilihan tool per server opsional. include membatasi tool MCP yang ditemukan ke nama yang cocok; exclude menyembunyikan nama yang cocok. Entri adalah nama tool MCP persis atau glob * sederhana. Server dengan resource atau prompt juga menghasilkan nama tool utilitas (resources_list, resources_read, prompts_list, prompts_get), dan nama tersebut menggunakan filter yang sama.
• mcp.servers.<name>.codex: kontrol proyeksi server aplikasi Codex opsional. Blok ini adalah metadata OpenClaw hanya untuk thread server aplikasi Codex; ini tidak memengaruhi sesi ACP, konfigurasi harness Codex generik, atau adapter runtime lainnya. codex.agents yang tidak kosong membatasi server ke id agen OpenClaw yang terdaftar. Daftar agen terbatas yang kosong, blank, atau tidak valid ditolak oleh validasi konfigurasi dan dihilangkan oleh jalur proyeksi runtime alih-alih menjadi global. codex.defaultToolsApprovalMode memancarkan default_tools_approval_mode native Codex untuk server tersebut. OpenClaw menghapus blok codex sebelum meneruskan konfigurasi mcp_servers native ke Codex. Hilangkan blok untuk mempertahankan server diproyeksikan bagi setiap agen server aplikasi Codex dengan perilaku persetujuan MCP default Codex.
• mcp.sessionIdleTtlMs: TTL idle untuk runtime MCP terbundel yang terbatas sesi. Eksekusi tertanam sekali pakai meminta pembersihan akhir eksekusi; TTL ini adalah penopang untuk sesi jangka panjang dan pemanggil mendatang.
• Perubahan di bawah mcp.* diterapkan panas dengan membuang runtime MCP sesi yang di-cache. Penemuan/penggunaan tool berikutnya membuatnya ulang dari konfigurasi baru, sehingga entri mcp.servers yang dihapus dipanen segera alih-alih menunggu TTL idle.
• Penemuan runtime juga menghormati notifikasi perubahan daftar tool MCP dengan menjatuhkan katalog yang di-cache untuk sesi tersebut. Server yang mengiklankan resource atau prompt mendapatkan tool utilitas untuk mencantumkan/membaca resource dan mencantumkan/mengambil prompt. Kegagalan panggilan tool berulang menjeda server yang terdampak sebentar sebelum panggilan lain dicoba.

Lihat MCP dan Backend CLI untuk perilaku runtime.

Skills

{  skills: {    allowBundled: ["gemini", "peekaboo"],    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },    install: {      preferBrew: true,      nodeManager: "npm", // npm | pnpm | yarn | bun      allowUploadedArchives: false,    },    workshop: {      allowSymlinkTargetWrites: false,    },    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 skill terbundel (skill terkelola/workspace tidak terpengaruh).
• load.extraDirs: root skill bersama tambahan (presedensi terendah).
• load.allowSymlinkTargets: root target nyata tepercaya yang dapat menjadi tujuan resolusi symlink skill saat tautan berada di luar root sumber yang dikonfigurasi.
• workshop.allowSymlinkTargetWrites: memungkinkan Skill Workshop apply menulis melalui target symlink yang sudah tepercaya (default: false).
• install.preferBrew: saat true, utamakan 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).
• install.allowUploadedArchives: izinkan klien Gateway operator.admin tepercaya menginstal arsip zip privat yang dipentaskan melalui skills.upload.* (default: false). Ini hanya mengaktifkan jalur arsip unggahan; instal normal ClawHub tidak memerlukannya.
• entries.<skillKey>.enabled: false menonaktifkan skill meskipun terbundel/terinstal.
• entries.<skillKey>.apiKey: kemudahan untuk skill yang mendeklarasikan env var utama (string plaintext atau objek SecretRef).

Plugin

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

• Dimuat dari direktori paket atau bundel di bawah ~/.openclaw/extensions dan <workspace>/.openclaw/extensions, plus file atau direktori yang tercantum di plugins.load.paths.
• Letakkan file plugin mandiri di plugins.load.paths; root ekstensi yang ditemukan otomatis mengabaikan file .js, .mjs, dan .ts tingkat atas sehingga skrip pembantu di root tersebut tidak memblokir startup.
• Discovery menerima plugin OpenClaw native plus bundel Codex dan bundel Claude yang kompatibel, termasuk bundel tata letak default Claude tanpa manifes.
• Perubahan konfigurasi memerlukan restart gateway.
• allow: allowlist opsional (hanya plugin yang tercantum yang dimuat). deny menang.
• plugins.entries.<id>.apiKey: field kemudahan kunci API tingkat plugin (ketika didukung oleh plugin).
• plugins.entries.<id>.env: peta variabel env dengan cakupan plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: ketika 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 bundel yang didukung.
• plugins.entries.<id>.hooks.allowConversationAccess: ketika true, plugin non-bundled 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: percayai plugin ini secara eksplisit untuk meminta override provider dan model per-run untuk run subagent latar belakang.
• plugins.entries.<id>.subagent.allowedModels: allowlist opsional target provider/model kanonis untuk override subagent tepercaya. Gunakan "*" hanya ketika Anda memang ingin mengizinkan model apa pun.
• plugins.entries.<id>.llm.allowModelOverride: percayai plugin ini secara eksplisit untuk meminta override model untuk api.runtime.llm.complete.
• plugins.entries.<id>.llm.allowedModels: allowlist opsional target provider/model kanonis untuk override completion LLM plugin tepercaya. Gunakan "*" hanya ketika Anda memang ingin mengizinkan model apa pun.
• plugins.entries.<id>.llm.allowAgentIdOverride: percayai plugin ini secara eksplisit untuk menjalankan api.runtime.llm.complete terhadap id agen non-default.
• plugins.entries.<id>.config: objek konfigurasi yang didefinisikan plugin (divalidasi oleh skema plugin OpenClaw native jika tersedia).
• Pengaturan akun/runtime plugin channel berada di bawah channels.<id> dan harus dijelaskan oleh metadata channelConfigs manifes plugin pemilik, bukan oleh registry opsi OpenClaw terpusat.

Konfigurasi plugin harness Codex

Plugin codex bawaan memiliki pengaturan harness app-server Codex native di bawah plugins.entries.codex.config. Lihat referensi harness Codex untuk permukaan konfigurasi lengkap dan harness Codex untuk model runtime.

codexPlugins hanya berlaku untuk sesi yang memilih harness Codex native. Ini tidak mengaktifkan plugin Codex untuk run provider OpenClaw, binding percakapan ACP, atau harness non-Codex apa pun.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",                allow_destructive_actions: false,              },            },          },        },      },    },  },}

• plugins.entries.codex.config.codexPlugins.enabled: mengaktifkan dukungan plugin/aplikasi Codex native untuk harness Codex. Default: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: kebijakan destructive-action default untuk elisitasi aplikasi plugin yang dimigrasikan. Gunakan true untuk menerima skema approval Codex yang aman tanpa prompt, false untuk menolaknya, "auto" untuk merutekan approval yang diwajibkan Codex melalui approval plugin OpenClaw, atau "ask" untuk meminta prompt pada setiap tindakan tulis/destruktif plugin tanpa approval tahan lama. Mode "ask" menghapus override approval per-tool Codex yang tahan lama untuk aplikasi yang terdampak dan memilih peninjau approval manusia untuk aplikasi tersebut sebelum thread Codex dimulai. Default: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: mengaktifkan entri plugin yang dimigrasikan ketika codexPlugins.enabled global juga true. Default: true untuk entri eksplisit.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: identitas marketplace stabil. V1 hanya mendukung "openai-curated".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: identitas plugin Codex stabil dari migrasi, misalnya "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: override destructive-action per-plugin. Ketika dihilangkan, nilai global allow_destructive_actions digunakan. Nilai per-plugin menerima kebijakan true, false, "auto", atau "ask" yang sama.

Setiap aplikasi plugin yang diterima dan menggunakan "ask" merutekan permintaan approval aplikasi tersebut ke peninjau manusia. Aplikasi lain dan approval thread non-aplikasi tetap memakai peninjau yang dikonfigurasi, sehingga kebijakan plugin campuran tidak mewarisi perilaku "ask".

codexPlugins.enabled adalah direktif pengaktifan global. Entri plugin eksplisit yang ditulis oleh migrasi adalah set instalasi tahan lama dan kelayakan perbaikan. plugins["*"] tidak didukung, tidak ada switch install, dan nilai marketplacePath lokal sengaja bukan field konfigurasi karena bersifat spesifik host.

Pemeriksaan kesiapan app/list di-cache selama satu jam dan disegarkan secara asinkron ketika basi. Konfigurasi aplikasi thread Codex dihitung saat pembentukan sesi harness Codex, bukan pada setiap turn; gunakan /new, /reset, atau restart gateway setelah mengubah konfigurasi plugin native.

• plugins.entries.firecrawl.config.webFetch: pengaturan provider pengambilan web Firecrawl.
  • apiKey: kunci API Firecrawl opsional untuk batas yang lebih tinggi (menerima SecretRef). Fallback ke plugins.entries.firecrawl.config.webSearch.apiKey, tools.web.fetch.firecrawl.apiKey legacy, atau variabel env FIRECRAWL_API_KEY.
  • baseUrl: URL dasar API Firecrawl (default: https://api.firecrawl.dev; override self-hosted harus menarget endpoint privat/internal).
  • onlyMainContent: ekstrak 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: aktifkan provider X Search.
  • model: model Grok yang digunakan untuk pencarian (mis. "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: pengaturan dreaming memori. Lihat Dreaming untuk fase dan ambang batas.
  • enabled: switch dreaming utama (default false).
  • frequency: cadence cron untuk setiap sweep dreaming penuh ("0 3 * * *" secara default).
  • model: override model subagent Dream Diary opsional. Memerlukan plugins.entries.memory-core.subagent.allowModelOverride: true; pasangkan dengan allowedModels untuk membatasi target. Error model tidak tersedia mencoba ulang sekali dengan model default sesi; kegagalan trust atau allowlist tidak fallback secara diam-diam.
  • kebijakan fase dan ambang batas adalah detail implementasi (bukan kunci konfigurasi yang terlihat 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 bundel Claude yang diaktifkan juga dapat menyumbangkan default OpenClaw 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 turn percakapan dan mengirimkannya melalui run heartbeat.

• commitments.enabled: aktifkan 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.

Peramban

{  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 yang dilacak setelah waktu idle atau ketika sesi melampaui batasnya. Atur idleMinutes: 0 atau maxTabsPerSession: 0 untuk menonaktifkan masing-masing mode pembersihan tersebut.
• ssrfPolicy.dangerouslyAllowPrivateNetwork dinonaktifkan saat tidak diatur, sehingga navigasi browser tetap ketat secara default.
• Atur ssrfPolicy.dangerouslyAllowPrivateNetwork: true hanya saat Anda dengan 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 hanya lampir (start/stop/reset dinonaktifkan).
• profiles.*.cdpUrl menerima http://, https://, ws://, dan wss://. Gunakan HTTP(S) saat Anda ingin OpenClaw menemukan /json/version; gunakan WS(S) saat penyedia Anda memberi URL DevTools WebSocket langsung.
• remoteCdpTimeoutMs dan remoteCdpHandshakeTimeoutMs berlaku untuk keterjangkauan CDP jarak jauh dan attachOnly serta 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 alih-alih CDP dan dapat melampir pada host yang dipilih atau melalui simpul browser yang terhubung.
• Profil existing-session dapat mengatur userDataDir untuk menargetkan profil browser berbasis Chromium tertentu seperti Brave atau Edge.
• Profil existing-session dapat mengatur cdpUrl saat Chrome sudah berjalan di belakang endpoint penemuan HTTP(S) DevTools atau endpoint WS(S) langsung. Dalam mode itu OpenClaw meneruskan endpoint ke Chrome MCP alih-alih menggunakan koneksi otomatis; userDataDir diabaikan untuk argumen peluncuran Chrome MCP.
• Profil existing-session mempertahankan batas rute Chrome MCP saat ini: tindakan berbasis snapshot/ref alih-alih penargetan selector 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 cdpPort dan cdpUrl secara otomatis; atur cdpUrl secara eksplisit hanya untuk profil CDP jarak jauh atau lampiran endpoint existing-session.
• Profil terkelola lokal dapat mengatur executablePath untuk mengganti browser.executablePath global untuk profil tersebut. Gunakan ini untuk menjalankan satu profil di Chrome dan profil lain di Brave.
• Profil terkelola lokal menggunakan browser.localLaunchTimeoutMs untuk penemuan HTTP Chrome CDP 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 berpacu dengan startup. Kedua nilai harus berupa bilangan bulat positif hingga 120000 md; 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 beranda OS Anda sebelum peluncuran Chromium. userDataDir per profil pada profil existing-session juga diperluas tilde-nya.
• 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: penggantian 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://127.0.0.1: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 for owner/admin callers      allow: ["gateway"],    },    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          timeoutMs: 10000,        },      },    },  },}

Endpoint yang kompatibel dengan OpenAI

• RPC HTTP Admin: nonaktif secara bawaan sebagai Plugin admin-http-rpc. Aktifkan Plugin untuk mendaftarkan POST /api/v1/admin/rpc. Lihat RPC HTTP Admin.
• Chat Completions: dinonaktifkan secara bawaan. 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 tidak 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 kendalikan; lihat Autentikasi Proxy Tepercaya)

Isolasi multi-instance

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 kemudahan: --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) (bawaan: false).
• autoGenerate: menghasilkan otomatis pasangan sertifikat/kunci lokal self-signed ketika file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev.
• certPath: path filesystem ke file sertifikat TLS.
• keyPath: path filesystem ke file kunci privat TLS; jaga agar izinnya 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 pengeditan konfigurasi diterapkan saat runtime.
  • "off": abaikan pengeditan langsung; perubahan memerlukan restart eksplisit.
  • "restart": selalu restart proses Gateway saat konfigurasi berubah.
  • "hot": terapkan perubahan dalam proses tanpa restart.
  • "hybrid" (default): coba hot reload terlebih dahulu; gunakan 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 kanal. Hilangkan untuk menggunakan waktu tunggu berbatas default (300000); atur 0 untuk menunggu tanpa batas dan mencatat peringatan berkala bahwa masih ada yang tertunda.

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 string kueri ditolak.

Catatan validasi dan keamanan:

• hooks.enabled=true memerlukan hooks.token yang tidak kosong.
• hooks.token sebaiknya berbeda dari autentikasi shared-secret Gateway aktif (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN atau gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD); startup mencatat peringatan keamanan non-fatal saat mendeteksi penggunaan ulang.
• openclaw security audit menandai penggunaan ulang autentikasi hook/Gateway sebagai temuan kritis, termasuk autentikasi kata sandi Gateway yang diberikan hanya saat audit (--auth password --password <password>). Jalankan openclaw doctor --fix untuk merotasi hooks.token yang tersimpan dan digunakan ulang, lalu perbarui pengirim hook eksternal agar menggunakan token hook baru.
• hooks.path tidak boleh berupa /; gunakan subpath khusus seperti /hooks.
• Jika hooks.allowRequestSessionKey=true, batasi hooks.allowedSessionKeyPrefixes (misalnya ["hook:"]).
• Jika pemetaan atau preset menggunakan sessionKey berbasis templat, atur hooks.allowedSessionKeyPrefixes dan hooks.allowRequestSessionKey=true. Kunci pemetaan statis tidak memerlukan opt-in tersebut.

Endpoint:

• 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 diterima hanya ketika hooks.allowRequestSessionKey=true (default: false).
• POST /hooks/<name> → diselesaikan melalui hooks.mappings
  • Nilai sessionKey pemetaan yang dirender dari templat diperlakukan sebagai nilai yang disediakan 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 berbasis templat.

{  hooks: {    gmail: {      account: "openclaw@gmail.com",      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 ketika dikonfigurasi. Atur OPENCLAW_SKIP_GMAIL_WATCHER=1 untuk menonaktifkan.
• Jangan jalankan gog gmail watch serve terpisah bersama 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 sebuah node dipasangkan dan terhubung, Gateway mengiklankan URL kapabilitas berbatas node untuk akses canvas/A2UI.
• URL kapabilitas terikat ke sesi WS node aktif dan kedaluwarsa dengan cepat. Fallback berbasis IP tidak digunakan.
• Menyisipkan klien live-reload ke HTML yang disajikan.
• Otomatis membuat index.html awal saat kosong.
• Juga menyajikan A2UI di /__openclaw__/a2ui/.
• Perubahan memerlukan restart 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 bundel diaktifkan): hilangkan cliPath + sshPort dari catatan TXT.
• full: sertakan cliPath + sshPort; iklan multicast LAN tetap memerlukan Plugin bonjour bundel untuk diaktifkan.
• off: tekan iklan multicast LAN tanpa mengubah pengaktifan Plugin.
• Plugin bonjour bundel otomatis dimulai di host macOS dan bersifat opt-in di Linux, Windows, serta deployment Gateway terkontainerisasi.
• Hostname default ke hostname 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 split Tailscale.

Penyiapan: openclaw dns setup --apply.

Lingkungan

env (variabel env inline)

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

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

Substitusi variabel env

Rujuk variabel env 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 memunculkan error saat konfigurasi dimuat.
• Escape dengan $${VAR} untuk literal ${VAR}.
• Bekerja 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}$ (mendukung selektor gaya AWS secret#json_key)
• id source: "exec" tidak boleh berisi segmen path berbatas slash . atau .. (misalnya a/../b ditolak)

Permukaan kredensial yang didukung

• Matriks kanonis: Permukaan Kredensial SecretRef
• secrets apply menargetkan path kredensial openclaw.json yang didukung.
• 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 fail closed ketika verifikasi ACL Windows tidak tersedia. Atur 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. Atur allowSymlinkCommand: true untuk mengizinkan path symlink sambil memvalidasi path target yang diselesaikan.
• Jika trustedDirs dikonfigurasi, pemeriksaan trusted-dir berlaku pada path target yang diselesaikan.
• Lingkungan child exec minimal secara default; teruskan variabel yang diperlukan secara eksplisit dengan passEnv.
• Referensi rahasia diselesaikan pada waktu aktivasi menjadi snapshot dalam memori, lalu path permintaan hanya membaca snapshot tersebut.
• Pemfilteran permukaan aktif berlaku selama aktivasi: referensi yang tidak terselesaikan 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:personal": { provider: "openai", mode: "oauth" },    },    order: {      anthropic: ["anthropic:default", "anthropic:work"],      openai: ["openai:personal"],    },  },}

• Profil per agen disimpan di <agentDir>/auth-profiles.json.
• auth-profiles.json mendukung referensi tingkat nilai (keyRef untuk api_key, tokenRef untuk token) untuk mode kredensial statis.
• Peta datar lama auth-profiles.json seperti { "provider": { "apiKey": "..." } } bukan format runtime; openclaw doctor --fix menulis ulangnya menjadi profil kunci API kanonis provider:default dengan cadangan .legacy-flat.*.bak.
• Profil mode OAuth (auth.profiles.<id>.mode = "oauth") tidak mendukung kredensial profil auth berbasis SecretRef.
• Kredensial runtime statis berasal dari snapshot terselesaikan dalam memori; entri statis lama auth.json dibersihkan saat ditemukan.
• Impor OAuth lama dari ~/.openclaw/credentials/oauth.json.
• Lihat OAuth.
• Perilaku runtime rahasia dan alat 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 saat profil gagal karena galat penagihan/kredit-tidak-mencukupi yang sebenarnya (default: 5). Teks penagihan eksplisit dapat tetap masuk ke sini bahkan pada respons 401/403, tetapi pencocok teks spesifik penyedia tetap dibatasi pada penyedia yang memilikinya (misalnya OpenRouter Key limit exceeded). Pesan HTTP 402 yang dapat dicoba ulang untuk jendela penggunaan atau batas pembelanjaan organisasi/workspace tetap berada di jalur rate_limit sebagai gantinya.
• billingBackoffHoursByProvider: override opsional per penyedia untuk jam backoff penagihan.
• billingMaxHours: batas dalam jam untuk pertumbuhan eksponensial backoff penagihan (default: 24).
• authPermanentBackoffMinutes: backoff dasar dalam menit untuk kegagalan auth_permanent berkeyakinan tinggi (default: 10).
• authPermanentMaxMinutes: batas dalam menit untuk pertumbuhan backoff auth_permanent (default: 60).
• failureWindowHours: jendela berjalan dalam jam yang digunakan untuk penghitung backoff (default: 24).
• overloadedProfileRotations: rotasi profil auth penyedia yang sama maksimum untuk galat overload sebelum beralih ke fallback model (default: 1). Bentuk penyedia-sibuk seperti ModelNotReadyException masuk ke sini.
• overloadedBackoffMs: jeda tetap sebelum mencoba ulang rotasi penyedia/profil yang overload (default: 0).
• rateLimitedProfileRotations: rotasi profil auth penyedia yang sama maksimum untuk galat batas laju sebelum beralih ke fallback model (default: 1). Bucket batas laju itu 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 jalur yang stabil.
• consoleLevel naik ke debug saat --verbose.
• maxFileBytes: ukuran file log aktif maksimum 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, rekaman log OTLP, dan teks transkrip sesi yang dipersistenkan. redactSensitive: "off" hanya menonaktifkan kebijakan log/transkrip umum ini; permukaan keamanan UI/alat/diagnostik tetap meredaksi rahasia sebelum emisi.

Diagnostik

{  diagnostics: {    enabled: true,    flags: ["telegram.*"],    stuckSessionWarnMs: 30000,    stuckSessionAbortMs: 300000,    memoryPressureSnapshot: false,     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,      logsExporter: "otlp",      sampleRate: 1.0,      flushIntervalMs: 5000,      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: 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, alat, 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 macet dan memenuhi syarat dapat di-abort-drain untuk pemulihan. Jika tidak disetel, OpenClaw menggunakan jendela embedded-run diperpanjang yang lebih aman, minimal 5 menit dan 3x stuckSessionWarnMs.
• memoryPressureSnapshot: menangkap snapshot stabilitas pra-OOM yang diredaksi saat tekanan memori mencapai critical (default: false). Setel ke true untuk menambahkan pemindaian/penulisan file bundel stabilitas sambil tetap mempertahankan peristiwa tekanan memori normal.
• otel.enabled: mengaktifkan pipeline ekspor OpenTelemetry (default: false). Untuk konfigurasi lengkap, katalog sinyal, dan model privasi, lihat Ekspor OpenTelemetry.
• otel.endpoint: URL kolektor untuk ekspor OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: endpoint OTLP opsional khusus sinyal. Saat disetel, nilai ini menimpa 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.logsExporter: sink ekspor log: "otlp" (default), "stdout" untuk satu objek JSON per baris stdout, atau "both".
• otel.sampleRate: laju sampling trace 0-1.
• otel.flushIntervalMs: interval flush telemetri berkala dalam ms.
• otel.captureContent: penangkapan konten mentah berbasis opt-in untuk atribut span OTEL. Defaultnya nonaktif. Boolean true menangkap konten pesan/alat non-sistem; bentuk objek memungkinkan Anda mengaktifkan inputMessages, outputMessages, toolInputs, toolOutputs, systemPrompt, dan toolDefinitions secara eksplisit.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: toggle lingkungan untuk bentuk span inferensi GenAI eksperimental terbaru, termasuk nama span {gen_ai.operation.name} {gen_ai.request.model}, jenis span CLIENT, dan gen_ai.provider.name alih-alih gen_ai.system lama. Secara default span mempertahankan openclaw.model.call dan 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 menjaga listener diagnostik tetap aktif.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, dan OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: variabel lingkungan endpoint khusus sinyal yang digunakan saat kunci konfigurasi yang sesuai tidak disetel.
• cacheTrace.enabled: catat snapshot trace cache untuk embedded run (default: false).
• cacheTrace.filePath: jalur 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 pembaruan otomatis latar belakang untuk instalasi paket (default: false).
• auto.stableDelayHours: jeda minimum dalam jam sebelum penerapan otomatis kanal stable (default: 6; maks: 168).
• auto.stableJitterHours: jendela sebaran rollout kanal stable tambahan 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: gerbang fitur ACP global (default: true; setel false untuk menyembunyikan dispatch ACP dan affordance spawn).
• dispatch.enabled: gerbang independen untuk dispatch turn sesi ACP (default: true). Setel false agar perintah ACP tetap tersedia sambil memblokir eksekusi.
• backend: id backend runtime ACP default (harus cocok dengan Plugin runtime ACP yang 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 saat 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/alat berulang per turn (default: true).
• stream.deliveryMode: "live" melakukan stream secara inkremental; "final_only" menahan buffer hingga peristiwa terminal turn.
• stream.hiddenBoundarySeparator: pemisah sebelum teks terlihat setelah peristiwa alat tersembunyi (default: "paragraph").
• stream.maxOutputChars: karakter output asisten maksimum yang diproyeksikan per turn ACP.
• stream.maxSessionUpdateChars: karakter maksimum untuk baris status/pembaruan ACP yang diproyeksikan.
• stream.tagVisibility: catatan nama tag ke override visibilitas boolean untuk peristiwa yang di-stream.
• runtime.ttlMinutes: TTL idle dalam menit untuk worker sesi ACP sebelum memenuhi syarat untuk cleanup.
• 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 berganti-ganti.
  • "default": tagline netral tetap (All your chats, one OpenClaw.).
  • "off": tanpa teks tagline (judul/versi banner tetap ditampilkan).
• Untuk menyembunyikan seluruh banner (bukan hanya tagline), set env OPENCLAW_HIDE_BANNER=1.

Wizard

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",    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",  },}

Identitas

Lihat kolom identitas agents.list di bawah Default agen.

Bridge (legacy, dihapus)

Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui Gateway WebSocket. Kunci bridge.* tidak lagi menjadi bagian dari skema config (validasi gagal sampai kunci 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: 8, // default; 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 sesi run Cron terisolasi yang sudah selesai dipertahankan sebelum dipangkas dari sessions.json. Ini juga mengontrol pembersihan transkrip Cron terhapus yang diarsipkan. Default: 24h; set false untuk menonaktifkan.
• runLog.maxBytes: diterima untuk kompatibilitas dengan log run Cron lama berbasis file. Default: 2_000_000 byte.
• runLog.keepLines: baris riwayat run SQLite terbaru yang dipertahankan per job. 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 legacy yang sudah tidak digunakan (http/https) yang digunakan oleh openclaw doctor --fix untuk memigrasikan job tersimpan yang masih memiliki notify: true; pengiriman runtime menggunakan delivery.mode="webhook" per job plus delivery.to, atau delivery.completionDestination saat mempertahankan pengiriman announce.

cron.retry

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

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

Job sekali jalan tetap aktif sampai percobaan retry habis, lalu dinonaktifkan sambil mempertahankan status error akhir. Job berulang menggunakan kebijakan retry sementara yang sama untuk berjalan lagi setelah backoff sebelum slot terjadwal berikutnya; error permanen atau retry sementara yang habis kembali ke jadwal berulang normal dengan backoff error.

cron.failureAlert

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

• enabled: aktifkan alert kegagalan untuk job Cron (default: false).
• after: kegagalan berturut-turut sebelum alert dikirim (bilangan bulat positif, min: 1).
• cooldownMs: milidetik minimum antara alert berulang untuk job yang sama (bilangan bulat non-negatif).
• includeSkipped: hitung run yang dilewati berturut-turut terhadap ambang alert (default: false). Run yang dilewati dilacak terpisah dan tidak memengaruhi backoff error eksekusi.
• mode: mode pengiriman - "announce" mengirim melalui pesan saluran; "webhook" memposting ke Webhook yang dikonfigurasi.
• accountId: akun atau id saluran opsional untuk membatasi cakupan pengiriman alert.

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" saat data target mencukupi.
• channel: override saluran untuk pengiriman announce. "last" menggunakan kembali saluran 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 mengesampingkan default global ini.
• Saat tujuan kegagalan global maupun per job tidak diset, job yang sudah mengirim melalui announce kembali menggunakan target announce utama itu 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 template model media

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

Include config ($include)

Pisahkan config menjadi beberapa file:

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

Perilaku merge:

• Satu file: menggantikan objek yang memuatnya.
• Array file: di-deep-merge sesuai urutan (yang lebih akhir mengesampingkan yang lebih awal).
• Kunci sibling: di-merge setelah include (mengesampingkan nilai yang di-include).
• Include bersarang: hingga kedalaman 10 level.
• Path: di-resolve relatif terhadap file yang meng-include, tetapi harus tetap berada di dalam direktori config tingkat atas (dirname dari openclaw.json). Bentuk absolut/../ hanya diizinkan saat tetap di-resolve di dalam batas tersebut. Path tidak boleh berisi byte null dan harus benar-benar lebih pendek dari 4096 karakter sebelum dan sesudah resolution.
• Penulisan milik OpenClaw yang hanya mengubah satu bagian tingkat atas yang didukung oleh include satu file akan menulis tembus ke file yang di-include tersebut. Misalnya, plugins install memperbarui plugins: { $include: "./plugins.json5" } di plugins.json5 dan membiarkan openclaw.json tetap utuh.
• Include root, array include, dan include dengan override sibling bersifat read-only untuk penulisan milik OpenClaw; penulisan tersebut gagal tertutup alih-alih meratakan config.
• Error: pesan yang jelas untuk file yang hilang, error parse, include sirkular, format path tidak valid, dan panjang berlebihan.

Terkait: Konfigurasi · Contoh Konfigurasi · Doctor

Terkait

• Konfigurasi
• Contoh konfigurasi