English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Diagnostics

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

Edit source

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

تقدم (بیشترین → کمترین)

  1. محیط فرایند (چیزی که فرایند Gateway از قبل از shell/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 سراسری به‌عنوان جایگزین سازگاری در نظر می‌گیرد. اگر هر دو فایل وجود داشته باشند و با هم ناسازگار باشند، OpenClaw مقدار ~/.openclaw/.env را نگه می‌دارد و یک هشدار چاپ می‌کند.

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

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

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

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

واردسازی محیط shell

env.shellEnv، login 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 برای اعمال قواعد وابسته به زمینه استفاده کرد.

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

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

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

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

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

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

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

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

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

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

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

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

ثبت رویداد

متغیر هدف
OPENCLAW_LOG_LEVEL بازنویسی سطح log برای هر دو خروجی فایل و console (مثلاً debug، trace). نسبت به logging.level و logging.consoleLevel در پیکربندی تقدم دارد. مقادیر نامعتبر با هشدار نادیده گرفته می‌شوند.
OPENCLAW_DEBUG_MODEL_TRANSPORT انتشار diagnostics هدفمند زمان‌بندی request/response مدل در سطح info بدون فعال کردن logهای debug سراسری.
OPENCLAW_DEBUG_MODEL_PAYLOAD diagnostics payload مدل: summary، tools، یا full-redacted. full-redacted محدود و redacted است اما ممکن است متن prompt/message را شامل شود.
OPENCLAW_DEBUG_SSE diagnostics جریان‌دهی: events برای زمان‌بندی first/done، peek برای شامل کردن پنج رویداد redacted SSE نخست.
OPENCLAW_DEBUG_CODE_MODE diagnostics سطح مدل code-mode، شامل پنهان‌سازی provider-tool و اعمال محدودیت exec/wait-only.

OPENCLAW_HOME

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

تقدم: 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 استفاده می‌کند که ممکن است CAهای ریشه مدرن را نداشته باشد (ISRG Root X1/X2 برای Let's Encrypt، DigiCert Global Root G2 و غیره). این باعث می‌شود web_fetch در بیشتر سایت‌های HTTPS با "fetch failed" شکست بخورد.

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

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

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

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

bash
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw gateway run

برای این متغیر فقط به نوشتن در ~/.openclaw/.env تکیه نکنید؛ Node مقدار NODE_EXTRA_CA_CERTS را هنگام startup فرایند می‌خواند.

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

OpenClaw فقط متغیرهای محیطی OPENCLAW_* را می‌خواند. پیشوندهای قدیمی CLAWDBOT_* و MOLTBOT_* از نسخه‌های قبلی بی‌صدا نادیده گرفته می‌شوند.

اگر هنگام startup هنوز هرکدام از آن‌ها روی فرایند Gateway تنظیم شده باشند، OpenClaw یک هشدار deprecation واحد Node (OPENCLAW_LEGACY_ENV_VARS) منتشر می‌کند که پیشوندهای شناسایی‌شده و تعداد کل را فهرست می‌کند. هر مقدار را با جایگزین کردن پیشوند قدیمی با OPENCLAW_ تغییر نام دهید (برای مثال CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN)؛ نام‌های قدیمی هیچ اثری ندارند.

مرتبط

Was this useful?