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

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 فضای کاری مراجعه کنید.

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

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

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

بلوک env پیکربندی فقط مقادیر رشته‌ای تحت‌اللفظی را می‌پذیرد. این بلوک مقادیر file:... را بسط نمی‌دهد؛ برای نمونه، XAI_API_KEY: "file:secrets/xai-api-key.txt" دقیقاً به‌صورت همین رشته به ارائه‌دهندگان ارسال می‌شود.

برای کلیدهای ارائه‌دهنده مبتنی بر فایل، در فیلد اطلاعات احراز هویتی که از آن پشتیبانی می‌کند از SecretRef استفاده کنید:

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

برای فیلدهای پشتیبانی‌شده، به مدیریت رازها و سطح اطلاعات احراز هویت SecretRef مراجعه کنید.

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

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

{  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} مستقیماً در مقادیر رشته‌ای پیکربندی به متغیرهای محیطی ارجاع دهید:

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

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

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

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

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

هر دو هنگام فعال‌سازی از محیط فرایند رفع می‌شوند. جزئیات SecretRef در مدیریت رازها مستند شده است. خود بلوک env پیکربندی، SecretRefها یا مقادیر کوتاه‌نویسی file:... را رفع نمی‌کند.

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

ثبت گزارش

OPENCLAW_HOME

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

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

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

<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، متغیر را صادر کنید:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw 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
• پرسش‌های متداول: متغیرهای محیطی و بارگذاری .env
• نمای کلی مدل‌ها