الانتقال إلى المحتوى الرئيسي

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

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

​
الأولوية (من الأعلى → إلى الأدنى)

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

​
كتلة env في التكوين

هناك طريقتان متكافئتان لتعيين متغيرات env المضمّنة (وكلتاهما لا تتجاوز القيم): 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

​
استيراد بيئة shell

يقوم env.shellEnv بتشغيل shell تسجيل الدخول لديك ويستورد فقط المفاتيح المتوقعة المفقودة: 
{
  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: يتم تعيينه لعمليات التشغيل التي يولدها backend وقت تشغيل ACP ‏(مثل acpx).
  • OPENCLAW_SHELL=acp-client: يتم تعيينه لأمر openclaw acp client عندما يشغّل عملية جسر ACP.
  • OPENCLAW_SHELL=tui-local: يتم تعيينه لأوامر shell المحلية ! في TUI.
هذه علامات وقت تشغيل (وليست تكوينًا مطلوبًا من المستخدم). ويمكن استخدامها في منطق shell/profile لتطبيق قواعد خاصة بالسياق.

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

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

​
استبدال متغيرات البيئة في التكوين

يمكنك الإشارة إلى متغيرات البيئة مباشرة داخل قيم السلاسل النصية في التكوين باستخدام الصيغة ${VAR_NAME}: 
{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}
راجع التكوين: استبدال متغيرات البيئة للحصول على التفاصيل الكاملة.

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

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

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

المتغيرالغرض
OPENCLAW_HOMEتجاوز الدليل المنزلي المستخدم لكل حل داخلي للمسارات (~/.openclaw/، وأدلة الوكلاء، والجلسات، وبيانات الاعتماد). مفيد عند تشغيل OpenClaw كمستخدم خدمة مخصص.
OPENCLAW_STATE_DIRتجاوز دليل الحالة (الافتراضي ~/.openclaw).
OPENCLAW_CONFIG_PATHتجاوز مسار ملف التكوين (الافتراضي ~/.openclaw/openclaw.json).

​
التسجيل

المتغيرالغرض
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 إلى مسار tilde ‏(مثل ~/svc) ويتم توسيعه باستخدام $HOME قبل الاستخدام.

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

إذا تم تثبيت Node.js عبر nvm ‏(وليس عبر مدير الحزم الخاص بالنظام)، فإن fetch() المدمج يستخدم مخزن CA المضمّن في nvm، والذي قد يفتقد إلى شهادات الجذر الحديثة (مثل 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 عند بدء العملية.

​
ذو صلة