.env dosyaları daha düşük güvenilirliğe sahip bir kaynaktır: OpenClaw, öncelik sırasını uygulamadan önce çalışma alanı .env içindeki sağlayıcı kimlik bilgilerini ve korumalı çalışma zamanı kontrollerini yok sayar.
Öncelik (en yüksekten en düşüğe)
- İşlem ortamı (Gateway işleminin üst kabuktan/daemon’dan zaten aldığı değerler).
- Geçerli çalışma dizinindeki
.env(dotenv varsayılanı; geçersiz kılmaz; sağlayıcı kimlik bilgileri ve korumalı çalışma zamanı kontrolleri yok sayılır). ~/.openclaw/.envkonumundaki genel.env($OPENCLAW_STATE_DIR/.envolarak da bilinir; sağlayıcı API anahtarları için önerilir; geçersiz kılmaz).~/.openclaw/openclaw.jsoniçindeki yapılandırmaenvbloğu (yalnızca eksikse uygulanır).- İsteğe bağlı oturum açma kabuğu içe aktarımı (
env.shellEnv.enabledveyaOPENCLAW_LOAD_SHELL_ENV=1), yalnızca eksik beklenen anahtarlara uygulanır.
.env sonrasında ~/.config/openclaw/gateway.env öğesini de uyumluluk için geri dönüş seçeneği olarak değerlendirir. Her iki dosya da mevcutsa ve birbiriyle uyuşmuyorsa OpenClaw, ~/.openclaw/.env öğesini korur ve bir uyarı yazdırır.
Yapılandırma dosyası hiç yoksa 4. adım atlanır; etkinleştirilmişse kabuk içe aktarımı yine çalışır.
Operatörlere yönelik desteklenen değişkenler
Aşağıdaki değişkenler, operatörler için desteklenen ortam sözleşmesidir. BelgelenmemişOPENCLAW_* değişkenleri dahili uygulama ayrıntılarıdır ve bildirimde bulunulmadan kaldırılabilir.
Yollar ve örnekler
Gateway ve kimlik doğrulama
Sağlayıcı kimlik bilgileri
Çekirdek ve paketle gelen sağlayıcı Plugin’leri aşağıdaki kimlik bilgisi ve sağlayıcı seçimi değişkenlerini tanır. İşlem genelinde tek bir değer yerine kapsamlı kimlik bilgilerine ihtiyaç duyduğunuzda her sağlayıcının yapılandırmasını veya SecretRef alanlarını tercih edin.AI_GATEWAY_API_KEY, ANTHROPIC_ADMIN_API_KEY, ANTHROPIC_ADMIN_KEY, ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, ARCEEAI_API_KEY, AZURE_OPENAI_API_KEY, AZURE_SPEECH_API_KEY, AZURE_SPEECH_KEY, AZURE_SPEECH_REGION, BASETEN_API_KEY, BRAVE_API_KEY, BYTEPLUS_API_KEY, BYTEPLUS_SEED_SPEECH_API_KEY, CEREBRAS_API_KEY, CHUTES_API_KEY, CHUTES_OAUTH_TOKEN, CLAWROUTER_API_KEY, CLOUDFLARE_AI_GATEWAY_API_KEY, CODEX_API_KEY, COHERE_API_KEY, COMFY_API_KEY, COMFY_CLOUD_API_KEY, COPILOT_GITHUB_TOKEN, DASHSCOPE_API_KEY, DEEPGRAM_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY, ELEVENLABS_API_KEY, EXA_API_KEY, FAL_API_KEY, FAL_KEY, FEATHERLESS_API_KEY, FIRECRAWL_API_KEY, FIREWORKS_API_KEY, GCLOUD_PROJECT, GEMINI_API_KEY, GH_TOKEN, GITHUB_TOKEN, GMI_API_KEY, GOOGLE_API_KEY, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_API_KEY, GOOGLE_CLOUD_LOCATION, GOOGLE_CLOUD_PROJECT, GRADIUM_API_KEY, GROQ_API_KEY, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, INWORLD_API_KEY, KILOCODE_API_KEY, KIMICODE_API_KEY, KIMI_API_KEY, LITELLM_API_KEY, LM_API_TOKEN, LONGCAT_API_KEY, MINIMAX_API_KEY, MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY, MINIMAX_OAUTH_TOKEN, MISTRAL_API_KEY, MODELSTUDIO_API_KEY, MODEL_API_KEY, MOONSHOT_API_KEY, NOVITA_API_KEY, NVIDIA_API_KEY, OLLAMA_API_KEY, OPENAI_ADMIN_KEY, OPENAI_API_KEY, OPENCODE_API_KEY, OPENCODE_ZEN_API_KEY, OPENROUTER_API_KEY, PARALLEL_API_KEY, PERPLEXITY_API_KEY, PIXVERSE_API_KEY, QIANFAN_API_KEY, QWEN_API_KEY, QWEN_TOKEN_PLAN_API_KEY, RUNWAYML_API_SECRET, RUNWAY_API_KEY, SENSEAUDIO_API_KEY, SGLANG_API_KEY, SPEECH_KEY, SPEECH_REGION, STEPFUN_API_KEY, SYNTHETIC_API_KEY, TAVILY_API_KEY, TOGETHER_API_KEY, TOKENHUB_API_KEY, TOKENPLAN_API_KEY, VENICE_API_KEY, VLLM_API_KEY, VOLCANO_ENGINE_API_KEY, VOLCENGINE_TTS_API_KEY, VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOYAGE_API_KEY, VYDRA_API_KEY, XAI_API_KEY, XIAOMI_API_KEY, XIAOMI_TOKEN_PLAN_API_KEY, XI_API_KEY, ZAI_API_KEY ve Z_AI_API_KEY.
Yüklü üçüncü taraf Plugin’ler, Plugin bildirimlerinde ek kimlik bilgisi değişkenleri tanımlayabilir; bu değişkenler, çekirdek OpenClaw değişkenleri değil, bunları bildiren Plugin’in sözleşmeleridir.
Günlük kaydı ve tanılama
Özellik ve çalışma zamanı geçişleri
Sağlayıcı kimlik bilgileri ve çalışma alanı .env
Sağlayıcı API anahtarlarını yalnızca bir çalışma alanı .env içinde tutmayın. OpenClaw, bilinen tüm sağlayıcı kimlik doğrulama ortam değişkenleri (örneğin 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, FIRECRAWL_API_KEY) dahil olmak üzere çok sayıda sağlayıcı kimlik bilgisi ve uç nokta yönlendirme anahtarını, ayrıca _API_HOST, _BASE_URL, _ENDPOINT veya _HOMESERVER ile biten tüm anahtarları ve OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_* ve OPENAI_API_KEY_* ad alanlarının tamamını çalışma alanı .env dosyalarından engeller.
Bunun yerine sağlayıcı kimlik bilgileri için şu güvenilen kaynaklardan birini kullanın:
- Bir kabuk, launchd/systemd birimi, kapsayıcı sırrı veya CI sırrı gibi Gateway işlem ortamı.
~/.openclaw/.envveya$OPENCLAW_STATE_DIR/.envkonumundaki genel çalışma zamanı dotenv dosyası.~/.openclaw/openclaw.jsoniçindeki yapılandırmaenvbloğu.env.shellEnv.enabledveyaOPENCLAW_LOAD_SHELL_ENV=1etkinleştirildiğinde isteğe bağlı oturum açma kabuğu içe aktarımı.
.env içinde sakladıysanız bunları yukarıdaki güvenilen kaynaklardan birine taşıyın. Çalışma alanı .env, kimlik bilgisi, uç nokta yönlendirmesi, ana makine geçersiz kılması veya OPENCLAW_* çalışma zamanı kontrolü olmayan sıradan proje değişkenlerini sağlamaya devam edebilir.
Güvenlik gerekçesi için Çalışma alanı .env dosyaları bölümüne bakın.
Yapılandırma env bloğu
Satır içi ortam değişkenlerini ayarlamanın eşdeğer iki yolu (ikisi de mevcut değerleri geçersiz kılmaz):
env bloğu yalnızca düz metin dize değerlerini kabul eder. file:... değerlerini
genişletmez; örneğin XAI_API_KEY: "file:secrets/xai-api-key.txt"
sağlayıcılara tam olarak bu dize biçiminde aktarılır.
Dosya destekli sağlayıcı anahtarları için bunu destekleyen kimlik bilgisi alanında bir SecretRef kullanın:
Kabuk ortamı içe aktarımı
env.shellEnv, oturum açma kabuğunuzu çalıştırır ve yalnızca eksik beklenen anahtarları içe aktarır:
OPENCLAW_LOAD_SHELL_ENV=1OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000(varsayılan15000)
Exec kabuk anlık görüntüleri
Windows dışındaki Gateway ana makinelerinde bash ve zshexec komutları varsayılan olarak bir başlangıç anlık görüntüsü kullanır.
Bu yolu devre dışı bırakmak için Gateway işlem ortamında OPENCLAW_EXEC_SHELL_SNAPSHOT=0 ayarlayın.
false, no ve off değerleri de bunu devre dışı bırakır. Çağrı başına exec.env değerleri,
anlık görüntüleri açıp kapatamaz veya anlık görüntü önbelleğini yeniden yönlendiremez.
Çalışma zamanında eklenen ortam değişkenleri
OpenClaw ayrıca oluşturulan alt işlemlere bağlam işaretçileri ekler:OPENCLAW_SHELL=exec:execaracı üzerinden çalıştırılan komutlar için ayarlanır.OPENCLAW_SHELL=acp-client: ACP köprü sürecini başlattığındaopenclaw acp clientiçin ayarlanır.OPENCLAW_SHELL=tui-local: yerel TUI!kabuk komutları için ayarlanır.OPENCLAW_CLI=1: CLI giriş noktası tarafından başlatılan alt süreçler için ayarlanır.
UI ortam değişkenleri
OPENCLAW_THEME=light: terminalinizin arka planı açıksa açık TUI paletini zorlar.OPENCLAW_THEME=dark: koyu TUI paletini zorlar.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:
Secret ref’leri ile ${ENV} dizeleri
OpenClaw, ortam değişkenlerine dayalı iki kalıbı destekler:
- Yapılandırma değerlerinde
${VAR}dize ikamesi. - Gizli bilgi referanslarını destekleyen alanlar için SecretRef nesneleri (
{ source: "env", provider: "default", id: "VAR" }).
env bloğunun kendisi SecretRef’leri veya file:...
kısa gösterim değerlerini çözümlemez.
Yolla ilgili ortam değişkenleri
Aracı yardımcı araç indirmeleri
OpenClaw’ın sabitlenmişfd ve ripgrep yardımcı ikili dosyalarını indirmesini
engellemek için OPENCLAW_OFFLINE=1 ayarlayın. OpenClaw araçları dizinindeki mevcut yardımcılar
ve çalışan sistem ikili dosyaları kullanılmaya devam edebilir; eksik bir yardımcı, ağ isteğini
tetiklemek yerine kullanılamaz durumda kalır.
Günlük Kaydı
OPENCLAW_HOME
Ayarlandığında OPENCLAW_HOME, dahili OpenClaw yol varsayılanları için sistem ana dizininin ($HOME / os.homedir()) yerini alır. Buna varsayılan durum dizini, yapılandırma yolu, aracı dizinleri, kimlik bilgileri, yükleyici ilk kurulum çalışma alanı ve openclaw update --channel dev tarafından kullanılan varsayılan geliştirme çalışma kopyası dahildir.
Öncelik: OPENCLAW_HOME > $HOME > USERPROFILE > Android’de Termux PREFIX ana dizin geri dönüşü > os.homedir()
Örnek (macOS LaunchDaemon):
OPENCLAW_HOME, tilde içeren bir yol olarak da ayarlanabilir (ör. ~/svc); bu yol kullanılmadan önce aynı işletim sistemi ana dizin geri dönüş zinciri kullanılarak genişletilir.
OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH ve OPENCLAW_GIT_DIR gibi açık yol değişkenleri yine önceliklidir. Kabuk başlangıç dosyası algılama, paket yöneticisi kurulumu ve ana makine ~ genişletmesi gibi işletim sistemi hesabı görevleri gerçek sistem ana dizinini kullanmaya devam edebilir.
nvm kullanıcıları: web_fetch TLS hataları
Node.js, sistem paket yöneticisi yerine nvm aracılığıyla kurulduysa yerleşikfetch(),
modern kök CA’ları (Let’s Encrypt için ISRG Root X1/X2, DigiCert Global Root G2 vb.) eksik olabilen
nvm’nin paketlenmiş CA deposunu kullanır. Bu, çoğu HTTPS sitesinde web_fetch işleminin "fetch failed" hatasıyla başarısız olmasına neden olur.
Linux’ta OpenClaw, nvm’yi otomatik olarak algılar ve düzeltmeyi gerçek başlangıç ortamında uygular:
openclaw gateway install,NODE_EXTRA_CA_CERTSdeğerini systemd hizmet ortamına yazaropenclawCLI giriş noktası, Node başlamadan önceNODE_EXTRA_CA_CERTSayarlanmış olarak kendisini yeniden çalıştırır
node ... başlatmaları için):
OpenClaw’ı başlatmadan önce değişkeni dışa aktarın:
~/.openclaw/.env dosyasına yazmaya güvenmeyin; Node,
NODE_EXTRA_CA_CERTS değerini süreç başlatılırken okur.
Eski ortam değişkenleri
OpenClaw yalnızcaOPENCLAW_* 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 hâlâ bunlardan biri ayarlıysa OpenClaw, algılanan önekleri
ve toplam sayıyı listeleyen tek bir Node kullanımdan kaldırma uyarısı (OPENCLAW_LEGACY_ENV_VARS)
yayınlar. Eski öneki OPENCLAW_ ile değiştirerek her değeri yeniden adlandırın
(örneğin CLAWDBOT_GATEWAY_TOKEN yerine OPENCLAW_GATEWAY_TOKEN); eski adların hiçbir etkisi yoktur.