---
read_when:
    - باید بدانید کدام متغیرهای محیطی بارگذاری می‌شوند و ترتیب بارگذاری آن‌ها چگونه است
    - شما در حال اشکال‌زدایی کلیدهای API مفقود در Gateway هستید
    - شما در حال مستندسازی احراز هویت ارائه‌دهنده یا محیط‌های استقرار هستید
summary: محل بارگذاری متغیرهای محیطی توسط OpenClaw و ترتیب اولویت آن‌ها
title: متغیرهای محیطی
x-i18n:
    generated_at: "2026-07-12T10:11:21Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: e0010465008969ea1ebf7bb79d01ee86b7be20f7b6d0d90da72d8b0a3b1ed273
    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 پس از فایل سراسری `.env`، فایل `~/.config/openclaw/gateway.env` را نیز به‌عنوان راهکار سازگاری جایگزین در نظر می‌گیرد. اگر هر دو فایل وجود داشته باشند و مقادیر متفاوتی داشته باشند، OpenClaw مقدار `~/.openclaw/.env` را حفظ می‌کند و هشداری نمایش می‌دهد.

اگر فایل پیکربندی کاملاً وجود نداشته باشد، مرحله ۴ رد می‌شود؛ درون‌ریزی پوسته، در صورت فعال بودن، همچنان اجرا می‌شود.

## اطلاعات احراز هویت ارائه‌دهندگان و `.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`) و نیز هر کلیدی با پسوند `_API_HOST`، `_BASE_URL` یا `_HOMESERVER` و تمام فضاهای نام `OPENCLAW_*`، `CLAWHUB_*`، `ANTHROPIC_API_KEY_*` و `OPENAI_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` فضای کاری](/fa/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" },
      },
    },
  },
}
```

برای فیلدهای پشتیبانی‌شده، به [مدیریت رازها](/fa/gateway/secrets) و
[سطح اطلاعات احراز هویت SecretRef](/fa/reference/secretref-credential-surface)
مراجعه کنید.

## درون‌ریزی محیط پوسته

`env.shellEnv` پوسته ورود شما را اجرا می‌کند و فقط کلیدهای مورد انتظارِ **فاقد مقدار** را درون‌ریزی می‌کند:

```json5
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
```

معادل‌های متغیر محیطی:

- `OPENCLAW_LOAD_SHELL_ENV=1`
- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000` (پیش‌فرض `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-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}",
      },
    },
  },
}
```

برای جزئیات کامل، به [پیکربندی: جایگزینی متغیر محیطی](/fa/gateway/configuration-reference#env-var-substitution) مراجعه کنید.

## ارجاع‌های راز در برابر رشته‌های `${ENV}`

OpenClaw از دو الگوی مبتنی بر محیط پشتیبانی می‌کند:

- جایگزینی رشته `${VAR}` در مقادیر پیکربندی.
- اشیای SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) برای فیلدهایی که از ارجاع راز پشتیبانی می‌کنند.

هر دو هنگام فعال‌سازی از محیط فرایند رفع می‌شوند. جزئیات SecretRef در [مدیریت رازها](/fa/gateway/secrets) مستند شده است.
خود بلوک `env` پیکربندی، SecretRefها یا مقادیر کوتاه‌نویسی
`file:...` را رفع نمی‌کند.

## متغیرهای محیطی مرتبط با مسیر

| متغیر                   | هدف                                                                                                                                                                                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_HOME`          | پوشه خانه مورداستفاده برای پیش‌فرض‌های مسیر داخلی OpenClaw را بازنویسی می‌کند (`~/.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`       | عیب‌یابی سطح مدلِ حالت کد، شامل پنهان‌سازی ابزار ارائه‌دهنده و اعمال مستقیم/کنترلی فشرده.                                                                                                                                    |

### `OPENCLAW_HOME`

هنگامی که تنظیم شود، `OPENCLAW_HOME` برای پیش‌فرض‌های مسیر داخلی OpenClaw جایگزین پوشه خانه سیستم (`$HOME` / `os.homedir()`) می‌شود. این شامل پوشه حالت پیش‌فرض، مسیر پیکربندی، پوشه‌های عامل، اطلاعات احراز هویت، فضای کاری راه‌اندازی اولیه نصب‌کننده و نسخه کاری توسعه پیش‌فرض مورداستفاده توسط `openclaw update --channel dev` است.

**ترتیب تقدم:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > راهکار جایگزین خانه `PREFIX` در Termux روی Android > `os.homedir()`

**نمونه** (LaunchDaemon در macOS):

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

`OPENCLAW_HOME` را می‌توان روی یک مسیر تیلدا نیز تنظیم کرد (برای نمونه `~/svc`) که پیش از استفاده، با همان زنجیره راهکار جایگزین خانه سیستم‌عامل بسط داده می‌شود.

متغیرهای مسیر صریح مانند `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` در بیشتر سایت‌های HTTPS با `"fetch failed"` شکست بخورد.

در Linux، OpenClaw به‌طور خودکار nvm را تشخیص می‌دهد و اصلاح را در محیط واقعی راه‌اندازی اعمال می‌کند:

- `openclaw gateway install` مقدار `NODE_EXTRA_CA_CERTS` را در محیط سرویس systemd می‌نویسد
- نقطه ورود CLI مربوط به `openclaw` پیش از راه‌اندازی Node، خود را با تنظیم `NODE_EXTRA_CA_CERTS` دوباره اجرا می‌کند

**اصلاح دستی (برای نسخه‌های قدیمی‌تر یا اجرای مستقیم `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](/fa/gateway/configuration)
- [پرسش‌های متداول: متغیرهای محیطی و بارگذاری .env](/fa/help/faq#env-vars-and-env-loading)
- [نمای کلی مدل‌ها](/fa/concepts/models)