Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw menarik variabel lingkungan dari beberapa sumber. Aturannya adalah jangan pernah menimpa nilai yang sudah ada.

​
Prioritas (tertinggi → terendah)

  1. Lingkungan proses (yang sudah dimiliki proses Gateway dari shell/daemon induk).
  2. .env di direktori kerja saat ini (default dotenv; tidak menimpa).
  3. .env global di ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; tidak menimpa).
  4. Blok env konfigurasi di ~/.openclaw/openclaw.json (diterapkan hanya jika belum ada).
  5. Impor login-shell opsional (env.shellEnv.enabled atau OPENCLAW_LOAD_SHELL_ENV=1), diterapkan hanya untuk kunci yang diharapkan tetapi belum ada.
Pada instalasi baru Ubuntu yang menggunakan direktori status default, OpenClaw juga memperlakukan ~/.config/openclaw/gateway.env sebagai fallback kompatibilitas setelah .env global. Jika kedua file ada dan berbeda, OpenClaw mempertahankan ~/.openclaw/.env dan mencetak peringatan. Jika file konfigurasi sama sekali tidak ada, langkah 4 dilewati; impor shell tetap berjalan jika diaktifkan.

​
Blok env konfigurasi

Dua cara setara untuk menetapkan variabel lingkungan inline (keduanya tidak menimpa): 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

​
Impor lingkungan shell

env.shellEnv menjalankan shell login Anda dan hanya mengimpor kunci yang diharapkan tetapi belum ada: 
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
Padanan variabel lingkungan:
  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

​
Variabel lingkungan yang diinjeksi runtime

OpenClaw juga menginjeksi penanda konteks ke dalam proses anak yang dijalankan:
  • OPENCLAW_SHELL=exec: ditetapkan untuk perintah yang dijalankan melalui alat exec.
  • OPENCLAW_SHELL=acp: ditetapkan untuk spawn proses backend runtime ACP (misalnya acpx).
  • OPENCLAW_SHELL=acp-client: ditetapkan untuk openclaw acp client saat men-spawn proses bridge ACP.
  • OPENCLAW_SHELL=tui-local: ditetapkan untuk perintah shell ! TUI lokal.
Ini adalah penanda runtime (bukan konfigurasi pengguna yang wajib). Penanda ini dapat digunakan dalam logika shell/profil untuk menerapkan aturan khusus konteks.

​
Variabel lingkungan UI

  • OPENCLAW_THEME=light: memaksa palet TUI terang saat terminal Anda memiliki latar belakang terang.
  • OPENCLAW_THEME=dark: memaksa palet TUI gelap.
  • COLORFGBG: jika terminal Anda mengekspornya, OpenClaw menggunakan petunjuk warna latar belakang untuk memilih palet TUI secara otomatis.

​
Substitusi variabel lingkungan dalam konfigurasi

Anda dapat mereferensikan variabel lingkungan langsung di nilai string konfigurasi menggunakan sintaks ${VAR_NAME}: 
{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}
Lihat Konfigurasi: Substitusi variabel lingkungan untuk detail lengkap.

​
Referensi rahasia vs string ${ENV}

OpenClaw mendukung dua pola berbasis lingkungan:
  • Substitusi string ${VAR} dalam nilai konfigurasi.
  • Objek SecretRef ({ source: "env", provider: "default", id: "VAR" }) untuk field yang mendukung referensi rahasia.
Keduanya di-resolve dari lingkungan proses pada waktu aktivasi. Detail SecretRef didokumentasikan di Manajemen Rahasia.

​
Variabel lingkungan terkait path

VariabelTujuan
OPENCLAW_HOMEMenimpa direktori home yang digunakan untuk semua resolusi path internal (~/.openclaw/, direktori agen, sesi, kredensial). Berguna saat menjalankan OpenClaw sebagai pengguna layanan khusus.
OPENCLAW_STATE_DIRMenimpa direktori status (default ~/.openclaw).
OPENCLAW_CONFIG_PATHMenimpa path file konfigurasi (default ~/.openclaw/openclaw.json).
OPENCLAW_INCLUDE_ROOTSDaftar path direktori tempat direktif $include dapat me-resolve file di luar direktori konfigurasi (default: tidak ada — $include dibatasi ke direktori konfigurasi). Tilde diperluas.

​
Logging

VariabelTujuan
OPENCLAW_LOG_LEVELMenimpa level log untuk file dan konsol (mis. debug, trace). Mengambil prioritas atas logging.level dan logging.consoleLevel dalam konfigurasi. Nilai tidak valid diabaikan dengan peringatan.
OPENCLAW_DEBUG_MODEL_TRANSPORTMengeluarkan diagnostik waktu request/response model yang tertarget pada level info tanpa mengaktifkan log debug global.
OPENCLAW_DEBUG_MODEL_PAYLOADDiagnostik payload model: summary, tools, atau full-redacted. full-redacted dibatasi dan disunting tetapi dapat menyertakan teks prompt/pesan.
OPENCLAW_DEBUG_SSEDiagnostik streaming: events untuk waktu awal/selesai, peek untuk menyertakan lima event SSE pertama yang telah disunting.
OPENCLAW_DEBUG_CODE_MODEDiagnostik permukaan model mode kode, termasuk penyembunyian alat provider dan penegakan hanya exec/wait.

​
OPENCLAW_HOME

Saat ditetapkan, OPENCLAW_HOME menggantikan direktori home sistem ($HOME / os.homedir()) untuk semua resolusi path internal. Ini memungkinkan isolasi filesystem penuh untuk akun layanan headless. Prioritas: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir() Contoh (macOS LaunchDaemon): 
<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/user</string>
</dict>
OPENCLAW_HOME juga dapat ditetapkan ke path tilde (mis. ~/svc), yang diperluas menggunakan $HOME sebelum digunakan.

​
Pengguna nvm: kegagalan TLS web_fetch

Jika Node.js diinstal melalui nvm (bukan manajer paket sistem), fetch() bawaan menggunakan penyimpanan CA bawaan nvm, yang mungkin tidak memiliki CA root modern (ISRG Root X1/X2 untuk Let’s Encrypt, DigiCert Global Root G2, dll.). Ini menyebabkan web_fetch gagal dengan "fetch failed" di sebagian besar situs HTTPS. Di Linux, OpenClaw secara otomatis mendeteksi nvm dan menerapkan perbaikan di lingkungan startup aktual:
  • openclaw gateway install menulis NODE_EXTRA_CA_CERTS ke lingkungan layanan systemd
  • entrypoint CLI openclaw menjalankan ulang dirinya sendiri dengan NODE_EXTRA_CA_CERTS ditetapkan sebelum startup Node
Perbaikan manual (untuk versi lama atau peluncuran langsung node ...): Ekspor variabel sebelum memulai OpenClaw: 
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run
Jangan hanya mengandalkan penulisan ke ~/.openclaw/.env untuk variabel ini; Node membaca NODE_EXTRA_CA_CERTS pada startup proses.

​
Variabel lingkungan legacy

OpenClaw hanya membaca variabel lingkungan OPENCLAW_*. Prefix legacy CLAWDBOT_* dan MOLTBOT_* dari rilis sebelumnya diabaikan secara diam-diam. Jika ada yang masih ditetapkan pada proses Gateway saat startup, OpenClaw mengeluarkan satu peringatan deprecation Node (OPENCLAW_LEGACY_ENV_VARS) yang mencantumkan prefix yang terdeteksi dan jumlah totalnya. Ganti nama setiap nilai dengan mengganti prefix legacy dengan OPENCLAW_ (misalnya CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); nama lama tidak berpengaruh.

​
Terkait