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

يسحب OpenClaw متغيرات البيئة من مصادر متعددة. والقاعدة هي عدم تجاوز القيم الموجودة مطلقًا. تُعد ملفات .env في مساحة العمل مصدرًا أقل موثوقية: يتجاهل OpenClaw بيانات اعتماد المزوّد وعناصر التحكم المحمية في وقت التشغيل الواردة من ملف .env في مساحة العمل قبل تطبيق ترتيب الأولوية.

ترتيب الأولوية (من الأعلى إلى الأدنى)

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

في عمليات التثبيت الجديدة على Ubuntu التي تستخدم دليل الحالة الافتراضي، يعامل OpenClaw أيضًا الملف ~/.config/openclaw/gateway.env بوصفه خيار توافق احتياطيًا بعد ملف .env العام. إذا كان الملفان موجودين وكانت قيمهما متعارضة، يحتفظ OpenClaw بالقيم من ~/.openclaw/.env ويطبع تحذيرًا. إذا كان ملف الإعدادات مفقودًا بالكامل، تُتخطى الخطوة 4؛ ويظل استيراد الصدفة قيد التشغيل إذا كان مفعّلًا.

بيانات اعتماد المزوّد وملف `.env` في مساحة العمل

لا تحتفظ بمفاتيح API الخاصة بالمزوّدين في ملف .env داخل مساحة العمل فقط. يحظر OpenClaw مجموعة كبيرة من مفاتيح بيانات اعتماد المزوّد ومفاتيح إعادة توجيه نقاط النهاية الواردة من ملفات .env في مساحة العمل، بما في ذلك جميع متغيرات البيئة المعروفة لمصادقة المزوّدين (مثل 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)، بالإضافة إلى أي مفتاح ينتهي بـ _API_HOST أو _BASE_URL أو _HOMESERVER، وجميع مساحات الأسماء OPENCLAW_* وCLAWHUB_* وANTHROPIC_API_KEY_* وOPENAI_API_KEY_*. استخدم بدلًا من ذلك أحد المصادر الموثوقة التالية لبيانات اعتماد المزوّد:

بيئة عملية Gateway، مثل صدفة أو وحدة launchd/systemd أو سر حاوية أو سر CI.
ملف dotenv العام لوقت التشغيل في ~/.openclaw/.env أو $OPENCLAW_STATE_DIR/.env.
كتلة env في الإعدادات داخل ~/.openclaw/openclaw.json.
الاستيراد الاختياري من صدفة تسجيل الدخول عند تفعيل env.shellEnv.enabled أو OPENCLAW_LOAD_SHELL_ENV=1.

إذا كنت قد خزّنت مفاتيح المزوّدين سابقًا في ملف .env داخل مساحة العمل فقط، فانقلها إلى أحد المصادر الموثوقة المذكورة أعلاه. يظل بإمكان ملف .env في مساحة العمل توفير متغيرات المشروع العادية التي لا تمثل بيانات اعتماد أو عمليات إعادة توجيه لنقاط النهاية أو تجاوزات للمضيف أو عناصر تحكم OPENCLAW_* في وقت التشغيل. راجع ملفات .env في مساحة العمل لمعرفة المبررات الأمنية.

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

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

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

لا تقبل كتلة env في الإعدادات سوى قيم السلاسل النصية الحرفية. وهي لا توسّع قيم file:...؛ فعلى سبيل المثال، تُمرَّر القيمة XAI_API_KEY: "file:secrets/xai-api-key.txt" إلى المزوّدين بوصفها السلسلة النصية نفسها تمامًا. بالنسبة إلى مفاتيح المزوّدين المدعومة بملفات، استخدم SecretRef في حقل بيانات الاعتماد الذي يدعمها:

{
  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" },
      },
    },
  },
}

راجع إدارة الأسرار و سطح بيانات اعتماد SecretRef لمعرفة الحقول المدعومة.

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

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

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

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

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (القيمة الافتراضية 15000)

لقطات صدفة التنفيذ

على مضيفي Gateway من غير Windows، تستخدم أوامر exec في bash وzsh لقطة بدء تشغيل افتراضيًا. عيّن OPENCLAW_EXEC_SHELL_SNAPSHOT=0 في بيئة عملية Gateway لتعطيل هذا المسار. وتؤدي القيم false وno وoff أيضًا إلى تعطيله. لا يمكن لقيم exec.env الخاصة بكل استدعاء تبديل اللقطات أو إعادة توجيه ذاكرة التخزين المؤقت للقطات.

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

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

OPENCLAW_SHELL=exec: يُعيَّن للأوامر التي تُشغَّل من خلال أداة exec.
OPENCLAW_SHELL=acp-client: يُعيَّن لـ openclaw acp client عندما يُنشئ عملية جسر ACP.
OPENCLAW_SHELL=tui-local: يُعيَّن لأوامر الصدفة ! في TUI المحلي.
OPENCLAW_CLI=1: يُعيَّن للعمليات الفرعية التي تُنشئها نقطة دخول CLI.

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

متغيرات بيئة واجهة المستخدم

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 موثقة في إدارة الأسرار. ولا تحل كتلة env في الإعدادات نفسها كائنات SecretRef أو قيم الاختصار file:....

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

المتغير	الغرض
`OPENCLAW_HOME`	يتجاوز الدليل الرئيسي المستخدم للإعدادات الافتراضية لمسارات OpenClaw الداخلية (`~/.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_DEBUG_MODEL_TRANSPORT`	يصدر تشخيصات موجّهة لتوقيت طلبات/استجابات النموذج عند المستوى `info` من دون تفعيل سجلات تصحيح الأخطاء العامة.
`OPENCLAW_DEBUG_MODEL_PAYLOAD`	تشخيصات حمولة النموذج: `summary` أو `tools` أو `full-redacted`. تكون `full-redacted` محدودة الحجم ومنقّحة، لكنها قد تتضمن نص المطالبة/الرسالة.
`OPENCLAW_DEBUG_SSE`	تشخيصات البث: `events` لتوقيت أول حدث/الانتهاء، و`peek` لتضمين أول خمسة أحداث SSE منقّحة.
`OPENCLAW_DEBUG_CODE_MODE`	تشخيصات سطح النموذج في وضع الشيفرة، بما في ذلك إخفاء أدوات المزوّد وفرض التحكم/التوجيه المختصر.

`OPENCLAW_HOME`

عند تعيين OPENCLAW_HOME، فإنه يحل محل دليل النظام الرئيسي ($HOME / os.homedir()) في الإعدادات الافتراضية لمسارات OpenClaw الداخلية. يشمل ذلك دليل الحالة الافتراضي، ومسار الإعدادات، وأدلة الوكلاء، وبيانات الاعتماد، ومساحة عمل تهيئة برنامج التثبيت، ونسخة التطوير الافتراضية التي يستخدمها openclaw update --channel dev. ترتيب الأولوية: OPENCLAW_HOME > $HOME > USERPROFILE > خيار الدليل الرئيسي الاحتياطي لـ Termux والمستند إلى PREFIX على Android > os.homedir() مثال (LaunchDaemon في macOS):

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

يمكن أيضًا تعيين OPENCLAW_HOME إلى مسار يبدأ بعلامة التلدة (مثل ~/svc)، ويُوسَّع باستخدام سلسلة الخيارات الاحتياطية نفسها للدليل الرئيسي في نظام التشغيل قبل استخدامه. تظل متغيرات المسارات الصريحة، مثل OPENCLAW_STATE_DIR وOPENCLAW_CONFIG_PATH وOPENCLAW_GIT_DIR، ذات أولوية. وقد تستمر المهام المرتبطة بحساب نظام التشغيل، مثل اكتشاف ملف بدء تشغيل الصدفة وإعداد مدير الحزم وتوسيع ~ على المضيف، في استخدام دليل النظام الرئيسي الحقيقي.

مستخدمو 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)؛ ولا يكون للأسماء القديمة أي تأثير.

Start here

FAQ

Testing

Diagnostics

Community and meta

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

ترتيب الأولوية (من الأعلى إلى الأدنى)

بيانات اعتماد المزوّد وملف `.env` في مساحة العمل

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

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

لقطات صدفة التنفيذ

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

متغيرات بيئة واجهة المستخدم

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

مراجع الأسرار مقارنةً بسلاسل `${ENV}`

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

التسجيل

`OPENCLAW_HOME`

مستخدمو nvm: حالات فشل TLS في web_fetch

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

ذو صلة

​ترتيب الأولوية (من الأعلى إلى الأدنى)

​بيانات اعتماد المزوّد وملف .env في مساحة العمل

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

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

​لقطات صدفة التنفيذ

​متغيرات البيئة المُحقنة في وقت التشغيل

​متغيرات بيئة واجهة المستخدم

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

​مراجع الأسرار مقارنةً بسلاسل ${ENV}

​متغيرات البيئة المرتبطة بالمسارات

​التسجيل

​OPENCLAW_HOME

​مستخدمو nvm: حالات فشل TLS في web_fetch

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

​ذو صلة

ترتيب الأولوية (من الأعلى إلى الأدنى)

بيانات اعتماد المزوّد وملف `.env` في مساحة العمل

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

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

لقطات صدفة التنفيذ

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

متغيرات بيئة واجهة المستخدم

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

مراجع الأسرار مقارنةً بسلاسل `${ENV}`

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

التسجيل

`OPENCLAW_HOME`

مستخدمو nvm: حالات فشل TLS في web_fetch

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

ذو صلة