Langsung ke konten utama
OpenClaw membaca konfigurasi opsional dari ~/.openclaw/openclaw.json. Path konfigurasi aktif harus berupa file biasa. Tata letak openclaw.json bersymlink tidak didukung untuk penulisan yang dimiliki OpenClaw; penulisan atomik dapat mengganti path tersebut alih-alih mempertahankan symlink. Jika Anda menyimpan konfigurasi di luar direktori state bawaan, arahkan OPENCLAW_CONFIG_PATH langsung ke file sebenarnya. Jika file tidak ada, OpenClaw menggunakan default yang aman. Alasan umum untuk menambahkan konfigurasi:
  • Menghubungkan channel dan mengontrol siapa yang dapat mengirim pesan ke bot
  • Mengatur model, alat, sandboxing, atau otomasi (Cron, hook)
  • Menyetel sesi, media, jaringan, atau UI
Lihat referensi lengkap untuk setiap field yang tersedia. Agent dan otomasi sebaiknya menggunakan config.schema.lookup untuk dokumentasi tingkat field yang persis sebelum mengedit konfigurasi. Gunakan halaman ini untuk panduan berorientasi tugas dan Referensi konfigurasi untuk peta field dan default yang lebih luas.
Baru mengenal konfigurasi? Mulai dengan openclaw onboard untuk penyiapan interaktif, atau lihat panduan Contoh Konfigurasi untuk konfigurasi lengkap yang siap disalin-tempel.

​
Konfigurasi minimal

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

​
Mengedit konfigurasi

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

​
Validasi ketat

OpenClaw hanya menerima konfigurasi yang sepenuhnya cocok dengan skema. Key yang tidak dikenal, tipe yang salah bentuk, atau nilai tidak valid menyebabkan Gateway menolak untuk dimulai. Satu-satunya pengecualian tingkat root adalah $schema (string), sehingga editor dapat melampirkan metadata JSON Schema.
openclaw config schema mencetak JSON Schema kanonis yang digunakan oleh Control UI dan validasi. config.schema.lookup mengambil satu node dengan cakupan path plus ringkasan turunan untuk tooling penelusuran mendalam. Metadata dokumentasi field title/description dibawa melalui objek bersarang, wildcard (*), item array ([]), dan cabang anyOf/ oneOf/allOf. Skema Plugin dan channel runtime digabungkan saat registry manifest dimuat. Saat validasi gagal:
  • Gateway tidak melakukan boot
  • Hanya perintah diagnostik yang berfungsi (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Jalankan openclaw doctor untuk melihat masalah persisnya
  • Jalankan openclaw doctor --fix (atau --yes) untuk menerapkan perbaikan
Gateway menyimpan salinan tepercaya terakhir yang diketahui baik setelah setiap startup berhasil, tetapi startup dan hot reload tidak memulihkannya secara otomatis. Jika openclaw.json gagal validasi (termasuk validasi lokal Plugin), startup Gateway gagal atau reload dilewati dan runtime saat ini mempertahankan konfigurasi terakhir yang diterima. Jalankan openclaw doctor --fix (atau --yes) untuk memperbaiki konfigurasi yang diberi prefiks/tertindih atau memulihkan salinan terakhir yang diketahui baik. Promosi ke terakhir yang diketahui baik dilewati saat kandidat berisi placeholder secret yang disunting seperti ***.

​
Tugas umum

Setiap channel memiliki bagian konfigurasinya sendiri di bawah channels.<provider>. Lihat halaman channel khusus untuk langkah penyiapan:Semua channel menggunakan pola kebijakan DM yang sama:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
Atur model utama dan fallback opsional:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models mendefinisikan katalog model dan bertindak sebagai allowlist untuk /model; entri provider/* memfilter /model, /models, dan pemilih model ke provider yang dipilih sambil tetap menggunakan penemuan model dinamis.
  • Gunakan openclaw config set agents.defaults.models '<json>' --strict-json --merge untuk menambahkan entri allowlist tanpa menghapus model yang ada. Penggantian biasa yang akan menghapus entri ditolak kecuali Anda meneruskan --replace.
  • Referensi model menggunakan format provider/model (mis. anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx mengontrol downscaling gambar transkrip/alat (default 1200); nilai yang lebih rendah biasanya mengurangi penggunaan token vision pada run yang banyak screenshot.
  • Lihat CLI Model untuk mengganti model di chat dan Failover Model untuk rotasi autentikasi dan perilaku fallback.
  • Untuk provider kustom/self-hosted, lihat Provider kustom di referensi.
Akses DM dikontrol per channel melalui dmPolicy:
  • "pairing" (default): pengirim tidak dikenal mendapatkan kode pairing satu kali untuk disetujui
  • "allowlist": hanya pengirim di allowFrom (atau penyimpanan allow yang sudah dipasangkan)
  • "open": izinkan semua DM masuk (memerlukan allowFrom: ["*"])
  • "disabled": abaikan semua DM
Untuk grup, gunakan groupPolicy + groupAllowFrom atau allowlist khusus channel.Lihat referensi lengkap untuk detail per channel.
Pesan grup secara default memerlukan mention. Konfigurasikan pola pemicu per agent. Balasan grup/channel normal diposting secara otomatis; pilih path message-tool untuk room bersama tempat agent harus memutuskan kapan berbicara:
{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)
      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Mention metadata: @-mention native (tap-to-mention WhatsApp, @bot Telegram, dll.)
  • Pola teks: pola regex aman di mentionPatterns
  • Balasan terlihat: messages.visibleReplies dapat mewajibkan pengiriman message-tool secara global; messages.groupChat.visibleReplies menimpanya untuk grup/channel.
  • Lihat referensi lengkap untuk mode balasan terlihat, override per channel, dan mode self-chat.
Gunakan agents.defaults.skills untuk baseline bersama, lalu override agent tertentu dengan agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}
  • Hilangkan agents.defaults.skills agar Skills tidak dibatasi secara default.
  • Hilangkan agents.list[].skills untuk mewarisi default.
  • Atur agents.list[].skills: [] agar tidak ada Skills.
  • Lihat Skills, Konfigurasi Skills, dan Referensi Konfigurasi.
Kontrol seberapa agresif Gateway memulai ulang channel yang terlihat stale:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • Atur gateway.channelHealthCheckMinutes: 0 untuk menonaktifkan restart health-monitor secara global.
  • channelStaleEventThresholdMinutes harus lebih besar dari atau sama dengan interval pemeriksaan.
  • Gunakan channels.<provider>.healthMonitor.enabled atau channels.<provider>.accounts.<id>.healthMonitor.enabled untuk menonaktifkan restart otomatis untuk satu channel atau akun tanpa menonaktifkan monitor global.
  • Lihat Health Check untuk debugging operasional dan referensi lengkap untuk semua field.
Beri client lokal lebih banyak waktu untuk menyelesaikan handshake WebSocket pra-auth pada host yang terbebani atau berdaya rendah:
{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
  • Default-nya adalah 15000 milidetik.
  • OPENCLAW_HANDSHAKE_TIMEOUT_MS tetap didahulukan untuk override service atau shell satu kali.
  • Lebih baik perbaiki stall startup/event-loop terlebih dahulu; knob ini untuk host yang sehat tetapi lambat saat warmup.
Sesi mengontrol kontinuitas dan isolasi percakapan:
{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (bersama) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: default global untuk perutean sesi yang terikat thread (Discord mendukung /focus, /unfocus, /agents, /session idle, dan /session max-age).
  • Lihat Manajemen Sesi untuk cakupan, tautan identitas, dan kebijakan pengiriman.
  • Lihat referensi lengkap untuk semua bidang.
Jalankan sesi agen dalam runtime sandbox yang terisolasi:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Bangun image terlebih dahulu - dari checkout sumber jalankan scripts/sandbox-setup.sh, atau dari instalasi npm lihat perintah inline docker build di Sandboxing § Image dan penyiapan.Lihat Sandboxing untuk panduan lengkap dan referensi lengkap untuk semua opsi.
Push berbasis relay untuk build App Store publik menggunakan relay OpenClaw yang di-host: https://ios-push-relay.openclaw.ai.Deployment relay khusus memerlukan jalur build/deployment iOS yang sengaja dipisahkan, dengan URL relay yang cocok dengan URL relay gateway. Jika Anda menggunakan build relay khusus, atur ini dalam konfigurasi gateway:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
Padanan CLI:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
Yang dilakukan ini:
  • Memungkinkan gateway mengirim push.test, sinyal bangun, dan bangun sambung ulang melalui relay eksternal.
  • Menggunakan grant pengiriman bercakupan registrasi yang diteruskan oleh aplikasi iOS yang dipasangkan. Gateway tidak memerlukan token relay untuk seluruh deployment.
  • Mengikat setiap registrasi berbasis relay ke identitas gateway yang dipasangkan dengan aplikasi iOS, sehingga gateway lain tidak dapat menggunakan ulang registrasi yang tersimpan.
  • Mempertahankan build iOS lokal/manual pada APNs langsung. Pengiriman berbasis relay hanya berlaku untuk build resmi terdistribusi yang terdaftar melalui relay.
  • Harus cocok dengan URL dasar relay yang dibenamkan ke dalam build iOS, agar lalu lintas registrasi dan pengiriman mencapai deployment relay yang sama.
Alur ujung ke ujung:
  1. Instal aplikasi iOS resmi.
  2. Opsional: konfigurasikan gateway.push.apns.relay.baseUrl pada gateway hanya saat menggunakan build relay khusus yang sengaja dipisahkan.
  3. Pasangkan aplikasi iOS ke gateway dan biarkan sesi node serta operator tersambung.
  4. Aplikasi iOS mengambil identitas gateway, mendaftar ke relay menggunakan App Attest plus tanda terima aplikasi, lalu menerbitkan payload push.apns.register berbasis relay ke gateway yang dipasangkan.
  5. Gateway menyimpan handle relay dan grant pengiriman, lalu menggunakannya untuk push.test, sinyal bangun, dan bangun sambung ulang.
Catatan operasional:
  • Jika Anda mengalihkan aplikasi iOS ke gateway lain, sambungkan ulang aplikasi agar dapat menerbitkan registrasi relay baru yang terikat ke gateway tersebut.
  • Jika Anda mengirim build iOS baru yang menunjuk ke deployment relay lain, aplikasi menyegarkan registrasi relay yang di-cache, bukan menggunakan ulang asal relay lama.
Catatan kompatibilitas:
  • OPENCLAW_APNS_RELAY_BASE_URL dan OPENCLAW_APNS_RELAY_TIMEOUT_MS masih berfungsi sebagai override env sementara.
  • URL relay gateway khusus harus cocok dengan URL dasar relay yang dibenamkan ke dalam build iOS. Jalur rilis App Store publik menolak override URL relay iOS khusus.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true tetap menjadi celah pengembangan khusus loopback; jangan simpan URL relay HTTP dalam konfigurasi.
Lihat Aplikasi iOS untuk alur ujung ke ujung dan Alur autentikasi dan kepercayaan untuk model keamanan relay.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: string durasi (30m, 2h). Atur 0m untuk menonaktifkan.
  • target: last | none | <channel-id> (misalnya discord, matrix, telegram, atau whatsapp)
  • directPolicy: allow (default) atau block untuk target Heartbeat bergaya DM
  • Lihat Heartbeat untuk panduan lengkap.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: pangkas sesi run terisolasi yang telah selesai dari sessions.json (default 24h; atur false untuk menonaktifkan).
  • runLog: pangkas baris riwayat run Cron yang dipertahankan per pekerjaan. maxBytes tetap diterima untuk log run lama berbasis file.
  • Lihat Pekerjaan cron untuk ringkasan fitur dan contoh CLI.
Aktifkan 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,
      },
    ],
  },
}
Catatan keamanan:
  • Perlakukan semua konten payload hook/webhook sebagai input yang tidak tepercaya.
  • Gunakan hooks.token khusus; jangan gunakan ulang rahasia auth Gateway aktif (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN atau gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
  • Auth hook hanya melalui header (Authorization: Bearer ... atau x-openclaw-token); token query-string ditolak.
  • hooks.path tidak boleh /; pertahankan ingress Webhook pada subpath khusus seperti /hooks.
  • Biarkan flag bypass konten tidak aman tetap dinonaktifkan (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) kecuali untuk debugging yang cakupannya sangat ketat.
  • Jika Anda mengaktifkan hooks.allowRequestSessionKey, atur juga hooks.allowedSessionKeyPrefixes untuk membatasi kunci sesi yang dipilih pemanggil.
  • Untuk agen yang digerakkan hook, pilih tier model modern yang kuat dan kebijakan tool yang ketat (misalnya hanya perpesanan plus sandboxing jika memungkinkan).
Lihat referensi lengkap untuk semua opsi pemetaan dan integrasi Gmail.
Jalankan beberapa agen 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 binding dan profil akses per agen.
Gunakan $include untuk mengatur konfigurasi besar:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • File tunggal: menggantikan objek yang memuatnya
  • Array file: di-deep-merge secara berurutan (yang belakangan menang)
  • Kunci saudara: digabung setelah include (menimpa nilai yang di-include)
  • Include bertingkat: didukung hingga kedalaman 10 level
  • Path relatif: diselesaikan relatif terhadap file yang menyertakan
  • Format path: path include tidak boleh berisi byte null dan harus benar-benar lebih pendek dari 4096 karakter sebelum dan sesudah resolusi
  • Penulisan milik OpenClaw: saat penulisan hanya mengubah satu bagian top-level yang didukung oleh include file tunggal seperti plugins: { $include: "./plugins.json5" }, OpenClaw memperbarui file yang di-include tersebut dan membiarkan openclaw.json tetap utuh
  • Write-through yang tidak didukung: include root, array include, dan include dengan override saudara gagal tertutup untuk penulisan milik OpenClaw, alih-alih meratakan konfigurasi
  • Pembatasan: path $include harus terselesaikan di bawah direktori yang berisi openclaw.json. Untuk berbagi tree lintas mesin atau pengguna, atur OPENCLAW_INCLUDE_ROOTS ke daftar path (: pada POSIX, ; pada Windows) dari direktori tambahan yang dapat dirujuk oleh include. Symlink diselesaikan dan diperiksa ulang, sehingga path yang secara leksikal berada dalam dir konfigurasi tetapi target nyatanya keluar dari setiap root yang diizinkan tetap ditolak.
  • Penanganan error: error yang jelas untuk file yang hilang, error parse, include melingkar, format path tidak valid, dan panjang berlebihan

​
Hot reload konfigurasi

Gateway memantau ~/.openclaw/openclaw.json dan menerapkan perubahan secara otomatis - restart manual tidak diperlukan untuk sebagian besar pengaturan. Edit file langsung diperlakukan sebagai tidak tepercaya sampai tervalidasi. Watcher menunggu churn temp-write/rename editor reda, membaca file final, dan menolak edit eksternal yang tidak valid tanpa menulis ulang openclaw.json. Penulisan konfigurasi milik OpenClaw menggunakan gerbang skema yang sama sebelum menulis; clobber destruktif seperti menghapus gateway.mode atau mengecilkan file lebih dari separuh akan ditolak dan disimpan sebagai .rejected.* untuk diperiksa. Jika Anda melihat config reload skipped (invalid config) atau startup melaporkan Invalid config, periksa konfigurasi, jalankan openclaw config validate, lalu jalankan openclaw doctor --fix untuk perbaikan. Lihat Pemecahan masalah Gateway untuk checklist.

​
Mode reload

ModePerilaku
hybrid (default)Menerapkan perubahan aman secara hot seketika. Otomatis restart untuk perubahan kritis.
hotHanya menerapkan perubahan aman secara hot. Mencatat peringatan saat restart diperlukan - Anda yang menanganinya.
restartMe-restart Gateway pada perubahan konfigurasi apa pun, aman atau tidak.
offMenonaktifkan pemantauan file. Perubahan berlaku pada restart manual berikutnya.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Yang diterapkan secara hot vs yang memerlukan restart

Sebagian besar bidang diterapkan secara hot tanpa downtime. Dalam mode hybrid, perubahan yang memerlukan restart ditangani secara otomatis.
KategoriBidangPerlu mulai ulang?
Saluranchannels.*, web (WhatsApp) - semua saluran bawaan dan pluginTidak
Agen & modelagent, agents, models, routingTidak
Otomasihooks, cron, agent.heartbeatTidak
Sesi & pesansession, messagesTidak
Alat & mediatools, browser, skills, mcp, audio, talkTidak
UI & lain-lainui, logging, identity, bindingsTidak
Server Gatewaygateway.* (port, bind, auth, tailscale, TLS, HTTP)Ya
Infrastrukturdiscovery, pluginsYa
gateway.reload dan gateway.remote adalah pengecualian - mengubahnya tidak memicu mulai ulang.

​
Perencanaan pemuatan ulang

Saat Anda mengedit file sumber yang dirujuk melalui $include, OpenClaw merencanakan pemuatan ulang dari tata letak yang ditulis di sumber, bukan tampilan dalam memori yang sudah diratakan. Ini membuat keputusan hot-reload (hot-apply vs mulai ulang) tetap dapat diprediksi bahkan ketika satu bagian tingkat atas berada dalam file include miliknya sendiri seperti plugins: { $include: "./plugins.json5" }. Perencanaan pemuatan ulang gagal dalam mode tertutup jika tata letak sumber ambigu.

​
RPC konfigurasi (pembaruan terprogram)

Untuk tooling yang menulis konfigurasi melalui API Gateway, utamakan alur ini:
  • config.schema.lookup untuk memeriksa satu subtree (node skema dangkal + ringkasan anak)
  • config.get untuk mengambil snapshot saat ini plus hash
  • config.patch untuk pembaruan parsial (JSON merge patch: objek digabung, null menghapus, array diganti ketika dikonfirmasi secara eksplisit dengan replacePaths jika entri akan dihapus)
  • config.apply hanya ketika Anda bermaksud mengganti seluruh konfigurasi
  • update.run untuk self-update eksplisit plus mulai ulang; sertakan continuationMessage ketika sesi pasca-mulai ulang harus menjalankan satu turn tindak lanjut
  • update.status untuk memeriksa sentinel mulai ulang pembaruan terbaru dan memverifikasi versi yang berjalan setelah mulai ulang
Agen harus memperlakukan config.schema.lookup sebagai tempat pertama untuk dokumentasi dan batasan tingkat bidang yang presisi. Gunakan Referensi konfigurasi ketika mereka memerlukan peta konfigurasi yang lebih luas, default, atau tautan ke referensi subsistem khusus.
Penulisan control-plane (config.apply, config.patch, update.run) dibatasi lajunya hingga 3 permintaan per 60 detik per deviceId+clientIp. Permintaan mulai ulang digabung lalu menerapkan cooldown 30 detik antar siklus mulai ulang. update.status bersifat hanya-baca tetapi berada dalam cakupan admin karena sentinel mulai ulang dapat menyertakan ringkasan langkah pembaruan dan ekor output perintah.
Contoh patch parsial: 
openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
Baik config.apply maupun config.patch menerima raw, baseHash, sessionKey, note, dan restartDelayMs. baseHash wajib untuk kedua metode ketika konfigurasi sudah ada. config.patch juga menerima replacePaths, array jalur konfigurasi yang penggantian array-nya disengaja. Jika patch akan mengganti atau menghapus array yang sudah ada dengan entri lebih sedikit, Gateway menolak penulisan kecuali jalur persis itu muncul di replacePaths; array bertingkat di bawah entri array menggunakan [], seperti agents.list[].skills. Ini mencegah snapshot config.get yang terpotong secara diam-diam menimpa array routing atau allowlist. Gunakan config.apply ketika Anda bermaksud mengganti konfigurasi penuh.

​
Variabel lingkungan

OpenClaw membaca env vars dari proses induk plus:
  • .env dari direktori kerja saat ini (jika ada)
  • ~/.openclaw/.env (fallback global)
Kedua file tidak menimpa env vars yang sudah ada. Anda juga dapat menetapkan env vars inline dalam konfigurasi: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Jika diaktifkan dan key yang diharapkan belum diatur, OpenClaw menjalankan shell login Anda dan hanya mengimpor key yang hilang:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Padanan env var: OPENCLAW_LOAD_SHELL_ENV=1
Rujuk env vars di nilai string konfigurasi apa pun dengan ${VAR_NAME}:
{
  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_]*
  • Var yang hilang/kosong memunculkan error saat pemuatan
  • Escape dengan $${VAR} untuk output literal
  • Berfungsi di dalam file $include
  • Substitusi inline: "${BASE}/v1" → "https://api.example.com/v1"
Untuk bidang yang mendukung objek SecretRef, Anda dapat menggunakan:
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
Detail SecretRef (termasuk secrets.providers untuk env/file/exec) ada di Manajemen Rahasia. Jalur kredensial yang didukung tercantum di Permukaan Kredensial SecretRef.
Lihat Lingkungan untuk prioritas dan sumber lengkap.

​
Referensi lengkap

Untuk referensi lengkap bidang demi bidang, lihat Referensi Konfigurasi.
Terkait: Contoh Konfigurasi · Referensi Konfigurasi · Doctor

​
Terkait