---
read_when:
    - تحتاج إلى معرفة متغيرات البيئة التي يتم تحميلها وبأي ترتيب
    - أنت تصحح أخطاء مفاتيح API المفقودة في Gateway
    - أنت توثّق مصادقة المزوّد أو بيئات النشر
summary: من أين يحمّل OpenClaw متغيرات البيئة وترتيب الأولوية
title: متغيرات البيئة
x-i18n:
    generated_at: "2026-04-05T12:45:21Z"
    model: gpt-5.4
    provider: openai
    source_hash: a80aea69ca2ffe19a4e93140f05dd81fd576955562ff9913135d38a685a0353c
    source_path: help/environment.md
    workflow: 15
---

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

يسحب 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 المضمّنة (وكلتاهما لا تتجاوز القيم):

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

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

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

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

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

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

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

يدعم OpenClaw نمطين معتمدين على env:

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

يتم حل كلا النمطين من بيئة العملية عند وقت التفعيل. ويتم توثيق تفاصيل SecretRef في [إدارة الأسرار](/gateway/secrets).

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

| المتغير               | الغرض                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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):

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

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

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

## ذو صلة

- [تكوين Gateway](/gateway/configuration)
- [الأسئلة الشائعة: متغيرات env وتحميل .env](/help/faq#env-vars-and-env-loading)
- [نظرة عامة على النماذج](/concepts/models)
