متغيرات البيئة

يسحب OpenClaw متغيرات البيئة من مصادر متعددة. القاعدة هي عدم تجاوز القيم الموجودة مطلقًا.

# الأسبقية (الأعلى → الأدنى)

1. بيئة العملية (ما تملكه عملية Gateway مسبقًا من الصدفة/الخدمة الأصلية).
2. .env في دليل العمل الحالي (افتراضي dotenv؛ لا يتجاوز).
3. .env العام في ~/.openclaw/.env (المعروف أيضًا باسم $OPENCLAW_STATE_DIR/.env؛ لا يتجاوز).
4. كتلة env في الإعدادات ضمن ~/.openclaw/openclaw.json (تُطبّق فقط إذا كانت مفقودة).
5. استيراد صدفة تسجيل الدخول الاختياري (env.shellEnv.enabled أو OPENCLAW_LOAD_SHELL_ENV=1)، ويُطبّق فقط على المفاتيح المتوقعة المفقودة.

في تثبيتات Ubuntu الجديدة التي تستخدم دليل الحالة الافتراضي، يعامل OpenClaw أيضًا ~/.config/openclaw/gateway.env كخيار توافق احتياطي بعد .env العام. إذا كان الملفان موجودين ومختلفين، يحتفظ OpenClaw بـ ~/.openclaw/.env ويطبع تحذيرًا.

إذا كان ملف الإعدادات مفقودًا بالكامل، يتم تخطي الخطوة 4؛ ويظل استيراد الصدفة يعمل إذا كان مفعّلًا.

# كتلة env في الإعدادات

طريقتان متكافئتان لتعيين متغيرات بيئة مضمّنة (كلاهما غير متجاوز):

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

# استيراد بيئة الصدفة

يشغّل env.shellEnv صدفة تسجيل الدخول لديك ويستورد فقط المفاتيح المتوقعة المفقودة:

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

مكافئات متغيرات البيئة:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

# متغيرات البيئة المحقونة وقت التشغيل

يحقن OpenClaw أيضًا علامات سياق في العمليات الفرعية التي ينشئها:

• OPENCLAW_SHELL=exec: تُعيّن للأوامر التي تُشغّل عبر أداة exec.
• OPENCLAW_SHELL=acp: تُعيّن لعمليات إنشاء عملية الواجهة الخلفية وقت تشغيل ACP (على سبيل المثال acpx).
• OPENCLAW_SHELL=acp-client: تُعيّن لـ openclaw acp client عندما ينشئ عملية جسر ACP.
• OPENCLAW_SHELL=tui-local: تُعيّن لأوامر صدفة ! المحلية في TUI.

هذه علامات وقت تشغيل (وليست إعدادات مستخدم مطلوبة). يمكن استخدامها في منطق الصدفة/الملف الشخصي لتطبيق قواعد خاصة بالسياق.

# متغيرات بيئة الواجهة

• OPENCLAW_THEME=light: يفرض لوحة TUI الفاتحة عندما تكون خلفية الطرفية لديك فاتحة.
• OPENCLAW_THEME=dark: يفرض لوحة TUI الداكنة.
• COLORFGBG: إذا كانت الطرفية لديك تصدّره، يستخدم OpenClaw تلميح لون الخلفية لاختيار لوحة TUI تلقائيًا.

# استبدال متغيرات البيئة في الإعدادات

يمكنك الإشارة إلى متغيرات البيئة مباشرة في قيم السلاسل داخل الإعدادات باستخدام صيغة ${VAR_NAME}:

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

راجع الإعدادات: استبدال متغيرات البيئة للحصول على التفاصيل الكاملة.

# مراجع الأسرار مقابل سلاسل ${ENV}

يدعم OpenClaw نمطين مدفوعين بمتغيرات البيئة:

• استبدال سلسلة ${VAR} في قيم الإعدادات.
• كائنات SecretRef ({ source: "env", provider: "default", id: "VAR" }) للحقول التي تدعم مراجع الأسرار.

يُحلان كلاهما من بيئة العملية وقت التفعيل. تفاصيل SecretRef موثقة في إدارة الأسرار.

# متغيرات البيئة المتعلقة بالمسارات

المتغير	الغرض
OPENCLAW_HOME	تجاوز دليل المنزل المستخدم لكل حل داخلي للمسارات (~/.openclaw/، أدلة الوكلاء، الجلسات، بيانات الاعتماد). مفيد عند تشغيل OpenClaw كمستخدم خدمة مخصص.
OPENCLAW_STATE_DIR	تجاوز دليل الحالة (الافتراضي ~/.openclaw).
OPENCLAW_CONFIG_PATH	تجاوز مسار ملف الإعدادات (الافتراضي ~/.openclaw/openclaw.json).
OPENCLAW_INCLUDE_ROOTS	قائمة مسارات للأدلة التي يمكن لتوجيهات $include حل الملفات منها خارج دليل الإعدادات (الافتراضي: لا شيء — يقتصر $include على دليل الإعدادات). تُوسّع علامة التلدة.

# التسجيل

المتغير	الغرض
OPENCLAW_LOG_LEVEL	تجاوز مستوى السجل لكل من الملف ووحدة التحكم (مثل debug، trace). له الأسبقية على logging.level وlogging.consoleLevel في الإعدادات. يتم تجاهل القيم غير الصالحة مع تحذير.

# OPENCLAW_HOME

عند تعيينه، يستبدل OPENCLAW_HOME دليل المنزل في النظام ($HOME / os.homedir()) لكل حل داخلي للمسارات. يتيح ذلك عزلًا كاملًا لنظام الملفات لحسابات الخدمة بلا واجهة.

الأسبقية: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

مثال (macOS LaunchDaemon):

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

يمكن أيضًا تعيين OPENCLAW_HOME إلى مسار بعلامة تلدة (مثل ~/svc)، ويتم توسيعه باستخدام $HOME قبل الاستخدام.

# مستخدمو nvm: إخفاقات TLS في web_fetch

إذا كان Node.js مثبتًا عبر nvm (وليس مدير الحزم في النظام)، فإن fetch() المدمجة تستخدم مخزن شهادات CA المضمن في nvm، والذي قد يفتقد شهادات CA الجذرية الحديثة (ISRG Root X1/X2 لـ Let's Encrypt، وDigiCert Global Root G2، وغيرها). يؤدي ذلك إلى فشل web_fetch مع "fetch failed" في معظم مواقع HTTPS.

على Linux، يكتشف OpenClaw nvm تلقائيًا ويطبق الإصلاح في بيئة بدء التشغيل الفعلية:

• يكتب openclaw gateway install قيمة NODE_EXTRA_CA_CERTS في بيئة خدمة systemd
• يعيد مدخل CLI الخاص بـ openclaw تنفيذ نفسه مع تعيين NODE_EXTRA_CA_CERTS قبل بدء Node

إصلاح يدوي (للإصدارات الأقدم أو عمليات التشغيل المباشرة بـ node ...):

صدّر المتغير قبل بدء OpenClaw:

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

لا تعتمد على الكتابة فقط إلى ~/.openclaw/.env لهذا المتغير؛ يقرأ Node NODE_EXTRA_CA_CERTS عند بدء العملية.

# متغيرات البيئة القديمة

يقرأ OpenClaw فقط متغيرات البيئة OPENCLAW_*. يتم تجاهل البادئات القديمة CLAWDBOT_* وMOLTBOT_* من الإصدارات السابقة بصمت.

إذا بقي أي منها معيّنًا على عملية Gateway عند بدء التشغيل، يصدر OpenClaw تحذير إهمال واحدًا من Node (OPENCLAW_LEGACY_ENV_VARS) يسرد البادئات المكتشفة والعدد الإجمالي. أعد تسمية كل قيمة باستبدال البادئة القديمة بـ OPENCLAW_ (على سبيل المثال CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN)؛ الأسماء القديمة لا يكون لها أي تأثير.

# ذات صلة

• إعدادات Gateway
• الأسئلة الشائعة: متغيرات البيئة وتحميل .env
• نظرة عامة على النماذج