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

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

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

1. بيئة العملية (ما تملكه عملية Gateway بالفعل من الصدفة/الخدمة الخفية الأم).
2. .env في دليل العمل الحالي (الإعداد الافتراضي لـ dotenv؛ لا يتجاوز؛ يتم تجاهل بيانات اعتماد المزوّد وعناصر التحكم المحمية في وقت التشغيل).
3. ملف .env العام في ~/.openclaw/.env (ويعرف أيضا باسم $OPENCLAW_STATE_DIR/.env؛ موصى به لمفاتيح API الخاصة بالمزوّدين؛ لا يتجاوز).
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 في مساحة العمل

لا تحتفظ بمفاتيح 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.

استخدم أحد هذه المصادر الموثوقة لبيانات اعتماد المزوّد:

• بيئة عملية 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

لقطات صدفة exec

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

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

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

• OPENCLAW_SHELL=exec: يعيّن للأوامر التي تعمل عبر أداة exec.
• OPENCLAW_SHELL=acp: يعيّن لعمليات الواجهة الخلفية لوقت تشغيل ACP عند إنشائها (مثل acpx).
• 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_HOME دليل النظام الرئيسي ($HOME / os.homedir()) لافتراضات مسارات OpenClaw الداخلية. يشمل ذلك دليل الحالة الافتراضي، ومسار الإعدادات، وأدلة الوكلاء، وبيانات الاعتماد، ومساحة عمل إعداد المثبّت، ومستودع dev checkout الافتراضي المستخدم بواسطة openclaw update --channel dev.

الأسبقية: OPENCLAW_HOME > $HOME > USERPROFILE > مسار home الاحتياطي لـ Termux PREFIX على Android > os.homedir()

مثال (macOS LaunchDaemon):

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

يمكن أيضا تعيين OPENCLAW_HOME إلى مسار يبدأ بالتلدة (مثل ~/svc)، ويتم توسيعه باستخدام سلسلة fallback نفسها لمسار home في نظام التشغيل قبل الاستخدام.

لا تزال متغيرات المسار الصريحة مثل 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.crtopenclaw 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
• نظرة عامة على النماذج