الانتقال إلى المحتوى الرئيسي

​
التهيئة

يقرأ OpenClaw ملف تهيئة اختياري بصيغة من ~/.openclaw/openclaw.json. إذا كان الملف مفقودًا، يستخدم OpenClaw إعدادات افتراضية آمنة. من الأسباب الشائعة لإضافة ملف تهيئة:
  • ربط القنوات والتحكّم في من يمكنه مراسلة البوت
  • تعيين النماذج، الأدوات، العزل (sandboxing)، أو الأتمتة (cron، hooks)
  • ضبط الجلسات، الوسائط، الشبكات، أو واجهة المستخدم
اطّلع على المرجع الكامل لجميع الحقول المتاحة.
جديد على التهيئة؟ ابدأ بالأمر openclaw onboard للإعداد التفاعلي، أو راجع دليل أمثلة التهيئة للحصول على إعدادات كاملة جاهزة للنسخ.

​
أقل تهيئة ممكنة

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
تعديل التهيئة

openclaw onboard       # معالج الإعداد الكامل
openclaw configure     # معالج التهيئة

​
التحقق الصارم

يقبل OpenClaw فقط التهيئات التي تطابق المخطط بالكامل. المفاتيح غير المعروفة، أو الأنواع غير الصحيحة، أو القيم غير الصالحة تجعل البوابة ترفض البدء. الاستثناء الوحيد على مستوى الجذر هو $schema (من نوع string) لتمكين المحررات من إرفاق بيانات JSON Schema.
عند فشل التحقق:
  • لا تبدأ البوابة
  • تعمل فقط أوامر التشخيص (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • شغّل openclaw doctor لرؤية الأخطاء بالتفصيل
  • شغّل openclaw doctor --fix (أو --yes) لتطبيق الإصلاحات

​
مهام شائعة

لكل قناة قسم خاص بها تحت channels.<provider>. راجع صفحة القناة المخصّصة لخطوات الإعداد:تشترك جميع القنوات في نفس نمط سياسة الرسائل الخاصة (DM):
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
عيّن النموذج الأساسي مع بدائل احتياطية:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
  • يعرّف agents.defaults.models كتالوج النماذج ويعمل كقائمة سماح لأمر /model.
  • تستخدم مراجع النماذج صيغة provider/model (مثال: anthropic/claude-opus-4-6).
  • راجع Models CLI لتبديل النماذج داخل الدردشة وModel Failover لسلوك التبديل الاحتياطي.
  • لمزوّدين مخصّصين/مستضافين ذاتيًا، راجع Custom providers.
يتم التحكم في الوصول إلى الرسائل الخاصة لكل قناة عبر dmPolicy:
  • "pairing" (افتراضي): يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة
  • "allowlist": فقط المرسلون ضمن allowFrom (أو مخزن الاقتران)
  • "open": السماح بجميع الرسائل الخاصة الواردة (يتطلب allowFrom: ["*"])
  • "disabled": تجاهل جميع الرسائل الخاصة
للمجموعات، استخدم groupPolicy مع groupAllowFrom أو قوائم سماح خاصة بالقناة.راجع المرجع الكامل للتفاصيل.
رسائل المجموعات تتطلب الإشارة افتراضيًا. قم بالتهيئة لكل وكيل:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • إشارات وصفية: إشارات @ الأصلية في المنصة
  • أنماط نصية: تعابير regex في mentionPatterns
  • راجع المرجع الكامل.
تتحكم الجلسات في استمرارية المحادثة:
{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
تشغيل جلسات الوكيل داخل حاويات Docker معزولة:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
أنشئ الصورة أولًا: scripts/sandbox-setup.shراجع Sandboxing والمرجع الكامل.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: مدة مثل 30m أو 2h (استخدم 0m للتعطيل)
  • target: last | whatsapp | telegram | discord | none
  • راجع Heartbeat.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}
راجع Cron jobs.
تفعيل نقاط HTTP في البوابة:
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
راجع المرجع الكامل.
تشغيل عدة وكلاء معزولين:
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
راجع Multi-Agent والمرجع الكامل.
استخدم $include لتنظيم التهيئات الكبيرة:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • ملف واحد: يستبدل الكائن الحاوي
  • مصفوفة ملفات: دمج عميق حسب الترتيب
  • مفاتيح شقيقة: تُدمج بعد التضمين
  • تضمينات متداخلة: حتى 10 مستويات
  • مسارات نسبية: نسبةً إلى الملف المُضمِّن
  • معالجة الأخطاء: رسائل واضحة للملفات المفقودة أو الدائرية

​
إعادة التحميل الساخن للتهيئة

تراقب البوابة الملف ~/.openclaw/openclaw.json وتطبّق التغييرات تلقائيًا — دون الحاجة لإعادة تشغيل يدوي في معظم الحالات.

​
أوضاع إعادة التحميل

الوضعالسلوك
hybrid (افتراضي)يطبّق التغييرات الآمنة فورًا ويعيد التشغيل تلقائيًا عند الحاجة
hotيطبّق التغييرات الآمنة فقط ويسجّل تحذيرًا عند الحاجة لإعادة التشغيل
restartيعيد تشغيل البوابة عند أي تغيير
offيعطّل المراقبة؛ تسري التغييرات بعد إعادة تشغيل يدوي
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}
gateway.reload و gateway.remote لا يتطلبان إعادة تشغيل.

​
متغيرات البيئة

يقرأ OpenClaw متغيرات البيئة من العملية الأب، بالإضافة إلى:
  • .env في دليل العمل الحالي (إن وُجد)
  • ~/.openclaw/.env (احتياطي عام)
لا يتجاوز أي منهما القيم الموجودة مسبقًا. يمكن أيضًا تحديد متغيرات ضمن التهيئة: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
عند التفعيل، وإذا لم تكن المفاتيح المطلوبة مضبوطة، يشغّل OpenClaw صدفة تسجيل الدخول ويستورد المفاتيح المفقودة فقط:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
المكافئ عبر البيئة: OPENCLAW_LOAD_SHELL_ENV=1
يمكنك الإشارة إلى متغيرات البيئة داخل أي قيمة نصية باستخدام ${VAR_NAME}:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
القواعد:
  • يُطابق فقط الأسماء الكبيرة: [A-Z_][A-Z0-9_]*
  • المتغيرات المفقودة أو الفارغة تسبب خطأ عند التحميل
  • استخدم $${VAR} لإخراج حرفي
  • يعمل داخل ملفات $include
  • مثال: "${BASE}/v1" → "https://api.example.com/v1"
راجع Environment للتفاصيل الكاملة.

​
المرجع الكامل

للاطلاع على شرح تفصيلي لكل حقل، راجع Configuration Reference.
روابط ذات صلة: أمثلة التهيئة · Configuration Reference · Doctor