---
read_when:
    - يجب أن تعرف أي متغيرات بيئة يتم تحميلها، وبأي ترتيب
    - أنت تستكشف أخطاء مفاتيح API المفقودة في Gateway وتصلحها
    - أنت توثّق مصادقة المزوّد أو بيئات النشر
summary: المواضع التي يحمّل منها OpenClaw متغيرات البيئة وترتيب الأسبقية
title: متغيرات البيئة
x-i18n:
    generated_at: "2026-05-11T20:33:46Z"
    model: gpt-5.5
    provider: openai
    source_hash: b4b91e9bb3c386292f11a3ffe5ae718a74a800bd19fe95073da990d881e6069d
    source_path: help/environment.md
    workflow: 16
---

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

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

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

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

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

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

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

```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`: يُعيّن عند إنشاء عمليات الواجهة الخلفية لوقت تشغيل ACP (مثل `acpx`).
- `OPENCLAW_SHELL=acp-client`: يُعيّن لـ `openclaw acp client` عندما ينشئ عملية جسر ACP.
- `OPENCLAW_SHELL=tui-local`: يُعيّن لأوامر الصدفة `!` في TUI المحلي.

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

## متغيرات بيئة الواجهة

- `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).

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

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

### `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` إلى مسار يبدأ بتلدة (مثل `~/svc`)، وسيُوسّع باستخدام `$HOME` قبل الاستخدام.

## مستخدمو 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)