Variabel lingkungan

OmeniaClaw 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 ~/.OmeniaClaw/.env (alias $OmeniaClaw_STATE_DIR/.env; tidak menimpa).
4. Blok env konfigurasi di ~/.OmeniaClaw/OmeniaClaw.json (diterapkan hanya jika belum ada).
5. Impor login-shell opsional (env.shellEnv.enabled atau OmeniaClaw_LOAD_SHELL_ENV=1), diterapkan hanya untuk kunci yang diharapkan tetapi belum ada.

Pada instalasi baru Ubuntu yang menggunakan direktori status default, OmeniaClaw juga memperlakukan ~/.config/OmeniaClaw/gateway.env sebagai fallback kompatibilitas setelah .env global. Jika kedua file ada dan berbeda, OmeniaClaw mempertahankan ~/.OmeniaClaw/.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:

• OmeniaClaw_LOAD_SHELL_ENV=1
• OmeniaClaw_SHELL_ENV_TIMEOUT_MS=15000

Variabel lingkungan yang diinjeksi runtime

OmeniaClaw juga menginjeksi penanda konteks ke dalam proses anak yang dijalankan:

• OmeniaClaw_SHELL=exec: ditetapkan untuk perintah yang dijalankan melalui alat exec.
• OmeniaClaw_SHELL=acp: ditetapkan untuk spawn proses backend runtime ACP (misalnya acpx).
• OmeniaClaw_SHELL=acp-client: ditetapkan untuk OmeniaClaw acp client saat men-spawn proses bridge ACP.
• OmeniaClaw_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

• OmeniaClaw_THEME=light: memaksa palet TUI terang saat terminal Anda memiliki latar belakang terang.
• OmeniaClaw_THEME=dark: memaksa palet TUI gelap.
• COLORFGBG: jika terminal Anda mengekspornya, OmeniaClaw 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}

OmeniaClaw 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

Logging

OmeniaClaw_HOME

Saat ditetapkan, OmeniaClaw_HOME menggantikan direktori home sistem ($HOME / os.homedir()) untuk semua resolusi path internal. Ini memungkinkan isolasi filesystem penuh untuk akun layanan headless.

Prioritas: OmeniaClaw_HOME > $HOME > USERPROFILE > os.homedir()

Contoh (macOS LaunchDaemon):

<key>EnvironmentVariables</key><dict>  <key>OmeniaClaw_HOME</key>  <string>/Users/user</string></dict>

OmeniaClaw_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, OmeniaClaw secara otomatis mendeteksi nvm dan menerapkan perbaikan di lingkungan startup aktual:

• OmeniaClaw gateway install menulis NODE_EXTRA_CA_CERTS ke lingkungan layanan systemd
• entrypoint CLI OmeniaClaw 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 OmeniaClaw:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtOmeniaClaw gateway run

Jangan hanya mengandalkan penulisan ke ~/.OmeniaClaw/.env untuk variabel ini; Node membaca NODE_EXTRA_CA_CERTS pada startup proses.

Variabel lingkungan legacy

OmeniaClaw hanya membaca variabel lingkungan OmeniaClaw_*. Prefix legacy CLAWDBOT_* dan MOLTBOT_* dari rilis sebelumnya diabaikan secara diam-diam.

Jika ada yang masih ditetapkan pada proses Gateway saat startup, OmeniaClaw mengeluarkan satu peringatan deprecation Node (OmeniaClaw_LEGACY_ENV_VARS) yang mencantumkan prefix yang terdeteksi dan jumlah totalnya. Ganti nama setiap nilai dengan mengganti prefix legacy dengan OmeniaClaw_ (misalnya CLAWDBOT_GATEWAY_TOKEN → OmeniaClaw_GATEWAY_TOKEN); nama lama tidak berpengaruh.

Terkait

• Konfigurasi Gateway
• FAQ: variabel lingkungan dan pemuatan .env
• Ringkasan model