Ortam değişkenleri

OpenClaw, ortam değişkenlerini birden çok kaynaktan çeker. Kural şudur: mevcut değerleri asla geçersiz kılma.

Öncelik (en yüksek → en düşük)

1. Süreç ortamı (Gateway sürecinin üst kabuk/daemon'dan zaten sahip olduğu değerler).
2. Geçerli çalışma dizinindeki .env (dotenv varsayılanı; geçersiz kılmaz).
3. Global .env konumu ~/.openclaw/.env (diğer adıyla $OPENCLAW_STATE_DIR/.env; geçersiz kılmaz).
4. ~/.openclaw/openclaw.json içindeki yapılandırma env bloğu (yalnızca eksikse uygulanır).
5. İsteğe bağlı login-shell içe aktarımı (env.shellEnv.enabled veya OPENCLAW_LOAD_SHELL_ENV=1), yalnızca eksik beklenen anahtarlar için uygulanır.

Varsayılan durum dizinini kullanan yeni Ubuntu kurulumlarında OpenClaw, global .env sonrasında uyumluluk yedeği olarak ~/.config/openclaw/gateway.env dosyasını da değerlendirir. İki dosya da varsa ve uyuşmuyorsa OpenClaw ~/.openclaw/.env dosyasını korur ve bir uyarı yazdırır.

Yapılandırma dosyası tamamen eksikse 4. adım atlanır; kabuk içe aktarımı etkinse yine çalışır.

Yapılandırma env bloğu

Satır içi ortam değişkenlerini ayarlamanın eşdeğer iki yolu (ikisi de geçersiz kılmaz):

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

Kabuk ortamı içe aktarımı

env.shellEnv, login shell'inizi çalıştırır ve yalnızca eksik beklenen anahtarları içe aktarır:

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

Ortam değişkeni eşdeğerleri:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Çalışma zamanında enjekte edilen ortam değişkenleri

OpenClaw ayrıca başlatılan alt süreçlere bağlam işaretleyicileri enjekte eder:

• OPENCLAW_SHELL=exec: exec aracı üzerinden çalıştırılan komutlar için ayarlanır.
• OPENCLAW_SHELL=acp: ACP çalışma zamanı arka uç süreç başlatmaları için ayarlanır (örneğin acpx).
• OPENCLAW_SHELL=acp-client: ACP köprü sürecini başlattığında openclaw acp client için ayarlanır.
• OPENCLAW_SHELL=tui-local: yerel TUI ! kabuk komutları için ayarlanır.

Bunlar çalışma zamanı işaretleyicileridir (gerekli kullanıcı yapılandırması değildir). Bağlama özgü kurallar uygulamak için kabuk/profil mantığında kullanılabilirler.

UI ortam değişkenleri

• OPENCLAW_THEME=light: terminaliniz açık renkli bir arka plana sahipse açık TUI paletini zorunlu kılar.
• OPENCLAW_THEME=dark: koyu TUI paletini zorunlu kılar.
• COLORFGBG: terminaliniz bunu dışa aktarıyorsa OpenClaw, TUI paletini otomatik seçmek için arka plan rengi ipucunu kullanır.

Yapılandırmada ortam değişkeni ikamesi

${VAR_NAME} söz dizimini kullanarak yapılandırma dizesi değerlerinde ortam değişkenlerine doğrudan başvurabilirsiniz:

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

Tam ayrıntılar için Yapılandırma: Ortam değişkeni ikamesi bölümüne bakın.

Gizli referansları ve ${ENV} dizeleri

OpenClaw, ortam odaklı iki deseni destekler:

• Yapılandırma değerlerinde ${VAR} dize ikamesi.
• Gizli referanslarını destekleyen alanlar için SecretRef nesneleri ({ source: "env", provider: "default", id: "VAR" }).

İkisi de etkinleştirme zamanında süreç ortamından çözümlenir. SecretRef ayrıntıları Gizli Anahtar Yönetimi bölümünde belgelenmiştir.

Yolla ilgili ortam değişkenleri

Günlükleme

OPENCLAW_HOME

Ayarlı olduğunda OPENCLAW_HOME, tüm dahili yol çözümlemesi için sistem giriş dizininin ($HOME / os.homedir()) yerini alır. Bu, başsız hizmet hesapları için tam dosya sistemi yalıtımı sağlar.

Öncelik: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Örnek (macOS LaunchDaemon):

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

OPENCLAW_HOME ayrıca tilde yolu olarak da ayarlanabilir (örn. ~/svc); bu yol kullanılmadan önce $HOME kullanılarak genişletilir.

nvm kullanıcıları: web_fetch TLS hataları

Node.js nvm üzerinden kurulduysa (sistem paket yöneticisiyle değil), yerleşik fetch() nvm'nin paketlenmiş CA deposunu kullanır; bu depo modern kök CA'ları eksik olabilir (Let's Encrypt için ISRG Root X1/X2, DigiCert Global Root G2 vb.). Bu, web_fetch aracının çoğu HTTPS sitesinde "fetch failed" hatasıyla başarısız olmasına neden olur.

Linux'ta OpenClaw, nvm'yi otomatik algılar ve düzeltmeyi gerçek başlangıç ortamında uygular:

• openclaw gateway install, NODE_EXTRA_CA_CERTS değerini systemd hizmet ortamına yazar
• openclaw CLI giriş noktası, Node başlatılmadan önce NODE_EXTRA_CA_CERTS ayarlı olacak şekilde kendini yeniden çalıştırır

Elle düzeltme (eski sürümler veya doğrudan node ... başlatmaları için):

OpenClaw'ı başlatmadan önce değişkeni dışa aktarın:

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

Bu değişken için yalnızca ~/.openclaw/.env dosyasına yazmaya güvenmeyin; Node NODE_EXTRA_CA_CERTS değerini süreç başlangıcında okur.

Eski ortam değişkenleri

OpenClaw yalnızca OPENCLAW_* ortam değişkenlerini okur. Önceki sürümlerdeki eski CLAWDBOT_* ve MOLTBOT_* önekleri sessizce yok sayılır.

Başlangıçta Gateway sürecinde bunlardan herhangi biri hâlâ ayarlıysa OpenClaw, algılanan önekleri ve toplam sayıyı listeleyen tek bir Node kullanımdan kaldırma uyarısı (OPENCLAW_LEGACY_ENV_VARS) yayar. Her değeri, eski öneki OPENCLAW_ ile değiştirerek yeniden adlandırın (örneğin CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); eski adların hiçbir etkisi yoktur.

İlgili

• Gateway yapılandırması
• SSS: ortam değişkenleri ve .env yükleme
• Modellere genel bakış