Langsung ke konten utama

​
Konfigurasi

OpenClaw membaca file konfigurasi opsional berformat dari ~/.openclaw/openclaw.json. Jika file tersebut tidak ada, OpenClaw akan menggunakan nilai default yang aman. Alasan umum untuk menambahkan konfigurasi adalah:
  • Menghubungkan saluran dan mengontrol siapa yang dapat mengirim pesan ke bot
  • Mengatur model, alat, sandboxing, atau otomatisasi (cron, hook)
  • Menyetel sesi, media, jaringan, atau UI
Lihat referensi lengkap untuk setiap bidang yang tersedia.
Baru pertama kali mengonfigurasi? Mulailah dengan openclaw onboard untuk pengaturan interaktif, atau lihat panduan Contoh Konfigurasi untuk konfigurasi yang bisa langsung disalin.

​
Konfigurasi minimal

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
Mengedit konfigurasi

openclaw onboard       # wizard pengaturan penuh
openclaw configure     # wizard konfigurasi

​
Validasi ketat

OpenClaw hanya menerima konfigurasi yang sepenuhnya cocok dengan skema. Kunci yang tidak dikenal, tipe data yang salah, atau nilai yang tidak valid akan menyebabkan Gateway menolak untuk dijalankan. Satu-satunya pengecualian di tingkat root adalah $schema (string), agar editor dapat menyertakan metadata JSON Schema.
Jika validasi gagal:
  • Gateway tidak akan berjalan (boot)
  • Hanya perintah diagnostik yang berfungsi (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Jalankan openclaw doctor untuk melihat masalah secara detail
  • Jalankan openclaw doctor --fix (atau --yes) untuk menerapkan perbaikan

​
Tugas umum

Masing-masing saluran memiliki bagian konfigurasi sendiri di bawah channels.<provider>. Lihat halaman saluran khusus untuk langkah-langkah pengaturan:Semua saluran berbagi pola kebijakan DM yang sama:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // hanya untuk allowlist/open
    },
  },
}
Atur model utama dan cadangan (fallback) opsional:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models menentukan katalog model dan bertindak sebagai daftar izinkan (allowlist) untuk perintah /model.
  • Referensi model menggunakan format penyedia/model (misal: anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx mengontrol pengecilan skala gambar transkrip/alat (default 1200); nilai yang lebih rendah biasanya mengurangi penggunaan token visi pada proses yang banyak menggunakan screenshot.
  • Lihat CLI Model untuk mengganti model dalam chat dan Failover Model untuk rotasi autentikasi dan perilaku fallback.
  • Untuk penyedia kustom/host mandiri, lihat Penyedia kustom di referensi.
Akses DM dikontrol per saluran melalui dmPolicy:
  • "pairing" (default): pengirim tidak dikenal akan mendapatkan kode pairing satu kali untuk disetujui
  • "allowlist": hanya pengirim dalam allowFrom (atau penyimpanan pasangan yang diizinkan)
  • "open": izinkan semua DM masuk (memerlukan allowFrom: ["*"])
  • "disabled": abaikan semua DM
Untuk grup, gunakan groupPolicy + groupAllowFrom atau daftar izinkan khusus saluran.Lihat referensi lengkap untuk detail per saluran.
Pesan grup secara default memerlukan sebutan (mention). Konfigurasikan pola per agen:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Sebutan metadata: sebutan (mention) asli @-mentions (WhatsApp tap-to-mention, Telegram @bot, dll.)
  • Pola teks: pola regex dalam mentionPatterns
  • Lihat referensi lengkap untuk override per saluran dan mode chat mandiri (self-chat).
Sesi mengontrol kelanjutan dan isolasi percakapan:
{
  session: {
    dmScope: "per-channel-peer",  // direkomendasikan untuk multi-user
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (bersama) | per-peer | per-channel-peer | per-account-channel-peer
  • Lihat Manajemen Sesi untuk cakupan (scoping), tautan identitas, dan kebijakan pengiriman.
  • Lihat referensi lengkap untuk semua bidang.
Jalankan sesi agen dalam kontainer Docker yang terisolasi:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Bangun citra (image) terlebih dahulu: scripts/sandbox-setup.shLihat Sandboxing untuk panduan lengkap dan referensi lengkap untuk semua opsi.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: string durasi (30m, 2h). Atur ke 0m untuk menonaktifkan.
  • target: last | whatsapp | telegram | discord | none
  • Lihat Heartbeat untuk panduan lengkap.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}
Lihat Cron job untuk ringkasan fitur dan contoh CLI.
Aktifkan titik akhir (endpoint) webhook HTTP pada Gateway:
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
Lihat referensi lengkap untuk semua opsi pemetaan dan integrasi Gmail.
Jalankan beberapa agen yang terisolasi dengan workspace dan sesi terpisah:
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
Lihat Multi-Agen dan referensi lengkap untuk aturan pengikatan (binding) dan profil akses per-agen.
Gunakan $include untuk mengatur konfigurasi yang besar:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • File tunggal: menggantikan objek yang menampungnya
  • Array file: digabungkan secara mendalam (deep-merge) sesuai urutan (yang terakhir menang)
  • Kunci selevel (sibling): digabungkan setelah include (menimpa nilai yang disertakan)
  • Include bersarang: didukung hingga kedalaman 10 tingkat
  • Jalur relatif: diselesaikan relatif terhadap file yang menyertakannya
  • Penanganan error: pesan error yang jelas untuk file yang hilang, kesalahan parsing, dan include yang melingkar (circular)

​
Hot reload konfigurasi

Gateway memantau ~/.openclaw/openclaw.json dan menerapkan perubahan secara otomatis — sebagian besar pengaturan tidak memerlukan restart manual.

​
Mode muat ulang (Reload)

ModePerilaku
hybrid (default)Menerapkan perubahan yang aman secara instan (hot-apply). Otomatis merestart untuk perubahan kritis.
hotHanya menerapkan perubahan yang aman (hot-safe). Mencatat peringatan saat restart diperlukan.
restartMerestart Gateway pada setiap perubahan konfigurasi, baik aman maupun tidak.
offMenonaktifkan pemantauan file. Perubahan akan berlaku pada restart manual berikutnya.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Apa yang bisa di-hot-apply vs apa yang butuh restart

Sebagian besar bidang dapat di-hot-apply tanpa waktu henti. Dalam mode hybrid, perubahan yang membutuhkan restart akan ditangani secara otomatis.
KategoriBidangButuh restart?
Saluranchannels.*, web (WhatsApp) — semua saluran bawaan dan ekstensiTidak
Agen & modelagent, agents, models, routingTidak
Otomatisasihooks, cron, agent.heartbeatTidak
Sesi & pesansession, messagesTidak
Alat & mediatools, browser, skills, audio, talkTidak
UI & lainnyaui, logging, identity, bindingsTidak
Server Gatewaygateway.* (port, bind, auth, tailscale, TLS, HTTP)Ya
Infrastrukturdiscovery, canvasHost, pluginsYa
gateway.reload dan gateway.remote adalah pengecualian — mengubah keduanya tidak memicu restart.

​
RPC Konfigurasi (pembaruan terprogram)

RPC penulisan control-plane (config.apply, config.patch, update.run) dibatasi (rate-limited) sebanyak 3 permintaan per 60 detik per deviceId+clientIp. Saat dibatasi, RPC mengembalikan UNAVAILABLE beserta retryAfterMs.
Melakukan validasi + menulis konfigurasi penuh dan merestart Gateway dalam satu langkah.
config.apply menggantikan seluruh konfigurasi. Gunakan config.patch untuk pembaruan parsial, atau openclaw config set untuk kunci tunggal.
Parameter:
  • raw (string) — payload JSON5 untuk seluruh konfigurasi
  • baseHash (opsional) — hash konfigurasi dari config.get (diperlukan jika konfigurasi sudah ada)
  • sessionKey (opsional) — kunci sesi untuk ping bangun setelah restart
  • note (opsional) — catatan untuk sentinel restart
  • restartDelayMs (opsional) — jeda sebelum restart (default 2000)
Permintaan restart akan disatukan (coalesced) jika ada yang masih tertunda, dan berlaku cooldown 30 detik antar siklus restart.
openclaw gateway call config.get --params '{}'  # dapatkan payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: "~/.openclaw/workspace" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'
Menggabungkan pembaruan parsial ke dalam konfigurasi yang sudah ada (semantik JSON merge patch):
  • Objek digabungkan secara rekursif
  • null menghapus kunci
  • Array akan diganti secara utuh
Parameter:
  • raw (string) — JSON5 berisi hanya kunci yang ingin diubah
  • baseHash (diperlukan) — hash konfigurasi dari config.get
  • sessionKey, note, restartDelayMs — sama dengan config.apply
Perilaku restart sama dengan config.apply.
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { "*": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

​
Variabel lingkungan (Env var)

OpenClaw membaca variabel lingkungan dari proses induk ditambah:
  • .env dari direktori kerja saat ini (jika ada)
  • ~/.openclaw/.env (cadangan global)
Kedua file tersebut tidak menimpa variabel lingkungan yang sudah ada. Anda juga dapat mengatur variabel lingkungan secara inline di konfigurasi: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Jika diaktifkan dan kunci yang diharapkan belum diatur, OpenClaw akan menjalankan shell login Anda dan hanya mengimpor kunci yang hilang:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Ekuivalen variabel lingkungan: OPENCLAW_LOAD_SHELL_ENV=1
Gunakan variabel lingkungan dalam nilai string konfigurasi apa pun dengan ${NAMA_VAR}:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Aturan:
  • Hanya nama huruf besar yang cocok: [A-Z_][A-Z0-9_]*
  • Variabel yang hilang/kosong akan memicu error saat dimuat
  • Gunakan $${VAR} untuk output literal (escape)
  • Berfungsi di dalam file $include
  • Substitusi inline: "${BASE}/v1" → "https://api.example.com/v1"
Lihat Lingkungan untuk urutan prioritas dan sumber selengkapnya.

​
Referensi lengkap

Untuk referensi lengkap bidang demi bidang, lihat Referensi Konfigurasi.