متغیرهای محیطی

OpenClaw متغیرهای محیطی را از چند منبع می‌خواند. قاعده این است: هرگز مقدارهای موجود را بازنویسی نکنید.

# اولویت (بالاترین → پایین‌ترین)

1. محیط فرایند (چیزی که فرایند Gateway از قبل از شل/daemon والد دارد).
2. .env در دایرکتوری کاری فعلی (پیش‌فرض dotenv؛ بازنویسی نمی‌کند).
3. .env سراسری در ~/.openclaw/.env (یا همان $OPENCLAW_STATE_DIR/.env؛ بازنویسی نمی‌کند).
4. بلوک env پیکربندی در ~/.openclaw/openclaw.json (فقط اگر موجود نباشد اعمال می‌شود).
5. درون‌ریزی اختیاری login-shell (env.shellEnv.enabled یا OPENCLAW_LOAD_SHELL_ENV=1)، فقط برای کلیدهای مورد انتظارِ ناموجود اعمال می‌شود.

در نصب‌های تازه Ubuntu که از دایرکتوری وضعیت پیش‌فرض استفاده می‌کنند، OpenClaw همچنین ~/.config/openclaw/gateway.env را پس از .env سراسری به‌عنوان fallback سازگاری در نظر می‌گیرد. اگر هر دو فایل وجود داشته باشند و با هم متفاوت باشند، OpenClaw مقدار ~/.openclaw/.env را نگه می‌دارد و یک هشدار چاپ می‌کند.

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

# بلوک env پیکربندی

دو روش معادل برای تنظیم متغیرهای محیطی درون‌خطی (هر دو بدون بازنویسی هستند):

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

# درون‌ریزی محیط شل

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

{
  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: برای فرمان‌های شل ! در TUI محلی تنظیم می‌شود.

این‌ها نشانگرهای زمان اجرا هستند (نه پیکربندی الزامی کاربر). می‌توان از آن‌ها در منطق شل/پروفایل برای اعمال قواعد وابسته به زمینه استفاده کرد.

# متغیرهای محیطی UI

• OPENCLAW_THEME=light: هنگامی که ترمینال شما پس‌زمینه روشن دارد، پالت روشن TUI را اجباری می‌کند.
• OPENCLAW_THEME=dark: پالت تیره TUI را اجباری می‌کند.
• COLORFGBG: اگر ترمینال شما آن را صادر کند، OpenClaw از راهنمای رنگ پس‌زمینه برای انتخاب خودکار پالت TUI استفاده می‌کند.

# جایگزینی متغیر محیطی در پیکربندی

می‌توانید با استفاده از نحو ${VAR_NAME} مستقیماً در مقدارهای رشته‌ای پیکربندی به متغیرهای محیطی ارجاع دهید:

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

برای جزئیات کامل، پیکربندی: جایگزینی متغیر محیطی را ببینید.

# ارجاع‌های محرمانه در برابر رشته‌های ${ENV}

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

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

هر دو در زمان فعال‌سازی از محیط فرایند resolve می‌شوند. جزئیات SecretRef در مدیریت محرمانه‌ها مستند شده است.

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

متغیر	هدف
OPENCLAW_HOME	دایرکتوری خانه استفاده‌شده برای همه resolveهای مسیر داخلی را بازنویسی می‌کند (~/.openclaw/، دایرکتوری‌های عامل، نشست‌ها، credentials). هنگام اجرای OpenClaw به‌عنوان کاربر سرویس اختصاصی مفید است.
OPENCLAW_STATE_DIR	دایرکتوری وضعیت را بازنویسی می‌کند (پیش‌فرض ~/.openclaw).
OPENCLAW_CONFIG_PATH	مسیر فایل پیکربندی را بازنویسی می‌کند (پیش‌فرض ~/.openclaw/openclaw.json).
OPENCLAW_INCLUDE_ROOTS	فهرست مسیرِ دایرکتوری‌هایی که directiveهای $include می‌توانند فایل‌های خارج از دایرکتوری پیکربندی را از آن‌ها resolve کنند (پیش‌فرض: هیچ‌کدام — $include به دایرکتوری پیکربندی محدود است). Tilde-expanded.

# ثبت گزارش

متغیر	هدف
OPENCLAW_LOG_LEVEL	سطح گزارش را برای فایل و کنسول بازنویسی می‌کند (مثلاً debug، trace). بر logging.level و logging.consoleLevel در پیکربندی اولویت دارد. مقدارهای نامعتبر با یک هشدار نادیده گرفته می‌شوند.

# OPENCLAW_HOME

وقتی تنظیم شود، OPENCLAW_HOME دایرکتوری خانه سیستم ($HOME / os.homedir()) را برای همه resolveهای مسیر داخلی جایگزین می‌کند. این کار ایزولاسیون کامل فایل‌سیستم را برای حساب‌های سرویس headless ممکن می‌کند.

اولویت: 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 store همراه 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 می‌نویسد
• entrypoint مربوط به CLI با نام openclaw پیش از راه‌اندازی Node خود را با تنظیم NODE_EXTRA_CA_CERTS دوباره اجرا می‌کند

اصلاح دستی (برای نسخه‌های قدیمی‌تر یا اجراهای مستقیم node ...):

پیش از شروع OpenClaw متغیر را export کنید:

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 یک هشدار deprecation واحد از Node (OPENCLAW_LEGACY_ENV_VARS) منتشر می‌کند که پیشوندهای تشخیص‌داده‌شده و تعداد کل را فهرست می‌کند. هر مقدار را با جایگزینی پیشوند قدیمی با OPENCLAW_ تغییر نام دهید (برای مثال CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN)؛ نام‌های قدیمی هیچ اثری ندارند.

# مرتبط

• پیکربندی Gateway
• پرسش‌های متداول: متغیرهای محیطی و بارگذاری .env
• نمای کلی مدل‌ها