Variabel lingkungan

OpenClaw mengambil variabel lingkungan dari beberapa sumber. Aturannya adalah jangan pernah menimpa nilai yang sudah ada. File .env ruang kerja adalah sumber dengan tingkat kepercayaan lebih rendah: OpenClaw mengabaikan kredensial penyedia dan kontrol runtime terlindungi dari .env ruang kerja sebelum menerapkan prioritas.

Prioritas (tertinggi → terendah)

Lingkungan proses (yang sudah dimiliki proses Gateway dari shell/daemon induk).
.env di direktori kerja saat ini (default dotenv; tidak menimpa; kredensial penyedia dan kontrol runtime terlindungi diabaikan).
.env global di ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; direkomendasikan untuk kunci API penyedia; tidak menimpa).
Blok env konfigurasi di ~/.openclaw/openclaw.json (diterapkan hanya jika belum ada).
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 state 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 sepenuhnya tidak ada, langkah 4 dilewati; impor shell tetap berjalan jika diaktifkan.

Kredensial penyedia dan `.env` ruang kerja

Jangan simpan kunci API penyedia hanya di .env ruang kerja. OpenClaw mengabaikan variabel lingkungan kredensial penyedia dari file .env ruang kerja, termasuk kunci umum seperti GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, dan FIRECRAWL_API_KEY. Gunakan salah satu sumber tepercaya ini untuk kredensial penyedia:

Lingkungan proses Gateway, seperti shell, unit launchd/systemd, rahasia kontainer, atau rahasia CI.
File dotenv runtime global di ~/.openclaw/.env atau $OPENCLAW_STATE_DIR/.env.
Blok env konfigurasi di ~/.openclaw/openclaw.json.
Impor login-shell opsional saat env.shellEnv.enabled atau OPENCLAW_LOAD_SHELL_ENV=1 diaktifkan.

Jika sebelumnya Anda menyimpan kunci penyedia hanya di .env ruang kerja, pindahkan ke salah satu sumber tepercaya di atas. .env ruang kerja masih dapat menyediakan variabel proyek biasa yang bukan kredensial, pengalihan endpoint, override host, atau kontrol runtime OPENCLAW_*. Lihat File .env ruang kerja untuk alasan keamanannya.

Blok `env` konfigurasi

Dua cara setara untuk menetapkan env vars inline (keduanya tidak menimpa):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Blok env konfigurasi hanya menerima nilai string literal. Blok ini tidak memperluas nilai file:...; misalnya, XAI_API_KEY: "file:secrets/xai-api-key.txt" diteruskan ke penyedia sebagai string persis tersebut. Untuk kunci penyedia berbasis file, gunakan SecretRef pada kolom kredensial yang mendukungnya:

{
  secrets: {
    providers: {
      xai_key_file: {
        source: "file",
        path: "~/.openclaw/secrets/xai-api-key.txt",
        mode: "singleValue",
      },
    },
  },
  models: {
    providers: {
      xai: {
        apiKey: { source: "file", provider: "xai_key_file", id: "value" },
      },
    },
  },
}

Lihat Manajemen Rahasia dan Permukaan kredensial SecretRef untuk kolom yang didukung.

Impor env shell

env.shellEnv menjalankan login shell Anda dan hanya mengimpor kunci yang diharapkan tetapi belum ada:

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Padanan env var:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Snapshot shell exec

Pada host Gateway non-Windows, perintah exec bash dan zsh menggunakan snapshot startup secara default. Tetapkan OPENCLAW_EXEC_SHELL_SNAPSHOT=0 di lingkungan proses Gateway untuk menonaktifkan jalur ini. Nilai false, no, dan off juga menonaktifkannya. Nilai exec.env per panggilan tidak dapat mengaktifkan/nonaktifkan snapshot atau mengalihkan cache snapshot.

Env vars yang disuntikkan runtime

OpenClaw juga menyuntikkan penanda konteks ke proses anak yang dibuat:

OPENCLAW_SHELL=exec: ditetapkan untuk perintah yang dijalankan melalui alat exec.
OPENCLAW_SHELL=acp: ditetapkan untuk pembuatan proses backend runtime ACP (misalnya acpx).
OPENCLAW_SHELL=acp-client: ditetapkan untuk openclaw acp client saat membuat proses jembatan ACP.
OPENCLAW_SHELL=tui-local: ditetapkan untuk perintah shell TUI lokal !.
OPENCLAW_CLI=1: ditetapkan untuk proses anak yang dibuat oleh titik masuk CLI.

Ini adalah penanda runtime (bukan konfigurasi pengguna yang wajib). Penanda ini dapat digunakan dalam logika shell/profil untuk menerapkan aturan khusus konteks.

Env vars UI

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

Substitusi env var dalam konfigurasi

Anda dapat merujuk env vars secara langsung dalam nilai string konfigurasi menggunakan sintaks ${VAR_NAME}:

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

Lihat Konfigurasi: Substitusi env var untuk detail lengkap.

Secret refs vs string `${ENV}`

OpenClaw mendukung dua pola berbasis env:

Substitusi string ${VAR} dalam nilai konfigurasi.
Objek SecretRef ({ source: "env", provider: "default", id: "VAR" }) untuk kolom yang mendukung referensi rahasia.

Keduanya diselesaikan dari env proses pada waktu aktivasi. Detail SecretRef didokumentasikan dalam Manajemen Rahasia. Blok env konfigurasi itu sendiri tidak menyelesaikan SecretRefs atau nilai shorthand file:....

Env vars terkait path

Variabel	Tujuan
`OPENCLAW_HOME`	Override direktori home yang digunakan untuk default path internal OpenClaw (`~/.openclaw/`, direktori agen, sesi, kredensial, onboarding installer, dan checkout dev default). Berguna saat menjalankan OpenClaw sebagai pengguna layanan khusus.
`OPENCLAW_STATE_DIR`	Override direktori state (default `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Override path file konfigurasi (default `~/.openclaw/openclaw.json`).
`OPENCLAW_INCLUDE_ROOTS`	Daftar path direktori tempat direktif `$include` dapat menyelesaikan file di luar direktori konfigurasi (default: tidak ada — `$include` dibatasi ke direktori konfigurasi). Tilde diperluas.

Logging

Variabel	Tujuan
`OPENCLAW_LOG_LEVEL`	Override level log untuk file dan konsol (mis. `debug`, `trace`). Diprioritaskan atas `logging.level` dan `logging.consoleLevel` dalam konfigurasi. Nilai tidak valid diabaikan dengan peringatan.
`OPENCLAW_DEBUG_MODEL_TRANSPORT`	Mengeluarkan diagnostik timing permintaan/respons model yang tertarget pada level `info` tanpa mengaktifkan log debug global.
`OPENCLAW_DEBUG_MODEL_PAYLOAD`	Diagnostik payload model: `summary`, `tools`, atau `full-redacted`. `full-redacted` dibatasi dan disunting tetapi mungkin menyertakan teks prompt/pesan.
`OPENCLAW_DEBUG_SSE`	Diagnostik streaming: `events` untuk timing awal/selesai, `peek` untuk menyertakan lima event SSE pertama yang disunting.
`OPENCLAW_DEBUG_CODE_MODE`	Diagnostik permukaan model mode kode, termasuk penyembunyian alat penyedia dan penegakan hanya exec/wait.

`OPENCLAW_HOME`

Saat ditetapkan, OPENCLAW_HOME menggantikan direktori home sistem ($HOME / os.homedir()) untuk default path internal OpenClaw. Ini mencakup direktori state default, path konfigurasi, direktori agen, kredensial, ruang kerja onboarding installer, dan checkout dev default yang digunakan oleh openclaw update --channel dev. Prioritas: OPENCLAW_HOME > $HOME > USERPROFILE > fallback home Termux PREFIX di Android > 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 rantai fallback home OS yang sama sebelum digunakan. Variabel path eksplisit seperti OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, dan OPENCLAW_GIT_DIR tetap diprioritaskan. Tugas akun OS seperti deteksi file startup shell, setup package-manager, dan ekspansi host ~ masih dapat menggunakan home sistem yang sebenarnya.

Pengguna nvm: kegagalan TLS web_fetch

Jika Node.js diinstal melalui nvm (bukan package manager sistem), fetch() bawaan menggunakan penyimpanan CA bundel 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 otomatis mendeteksi nvm dan menerapkan perbaikan di lingkungan startup sebenarnya:

openclaw gateway install menulis NODE_EXTRA_CA_CERTS ke lingkungan layanan systemd
titik masuk CLI openclaw menjalankan ulang dirinya 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 mengandalkan penulisan hanya ke ~/.openclaw/.env untuk variabel ini; Node membaca NODE_EXTRA_CA_CERTS saat startup proses.