---
read_when:
    - تحتاج إلى معرفة متغيرات البيئة التي يتم تحميلها، وبأي ترتيب
    - أنت تقوم بتصحيح أخطاء مفاتيح API المفقودة في Gateway
    - أنت توثق مصادقة المزوّد أو بيئات النشر
summary: حيث يحمّل OpenClaw متغيرات البيئة وترتيب الأولوية
title: متغيرات البيئة
x-i18n:
    generated_at: "2026-06-27T17:45:58Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 7e36f93efe29f9cc0e9942659c323a635d21fcaa436427dcb21f5694e5d0458b
    source_path: help/environment.md
    workflow: 16
---

يسحب 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` في مساحة العمل](/ar/gateway/security#workspace-env-files) لمعرفة المبرر الأمني.

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

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

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

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

لمفاتيح المزوّد المدعومة بملفات، استخدم SecretRef في حقل بيانات الاعتماد الذي
يدعمه:

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

راجع [إدارة الأسرار](/ar/gateway/secrets) و
[سطح بيانات اعتماد SecretRef](/ar/reference/secretref-credential-surface) لمعرفة
الحقول المدعومة.

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

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

```json5
{
  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}`:

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

راجع [الإعدادات: استبدال متغيرات البيئة](/ar/gateway/configuration-reference#env-var-substitution) للتفاصيل الكاملة.

## مراجع الأسرار مقابل نصوص `${ENV}`

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

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

كلاهما يحل من بيئة العملية وقت التفعيل. تفاصيل SecretRef موثقة في [إدارة الأسرار](/ar/gateway/secrets).
كتلة `env` في الإعدادات نفسها لا تحل مراجع SecretRef أو قيم الاختصار
`file:...`.

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

| المتغير                  | الغرض                                                                                                                                                                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_HOME`          | يتجاوز الدليل الرئيسي المستخدم لافتراضات مسارات OpenClaw الداخلية (`~/.openclaw/`، أدلة الوكلاء، الجلسات، بيانات الاعتماد، إعداد المثبّت، ومستودع dev checkout الافتراضي). مفيد عند تشغيل 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`       | تشخيصات سطح النموذج في وضع الكود، بما في ذلك إخفاء أدوات المزوّد وفرض exec/wait-only.                                                                                          |

### `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):

```xml
<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:

```bash
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](/ar/gateway/configuration)
- [الأسئلة الشائعة: متغيرات البيئة وتحميل .env](/ar/help/faq#env-vars-and-env-loading)
- [نظرة عامة على النماذج](/ar/concepts/models)