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

​
الإعدادات

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

​
إعدادات دنيا

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

​
تعديل الإعدادات

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

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

لا يقبل OpenClaw إلا الإعدادات التي تطابق المخطط بالكامل. فالمفاتيح غير المعروفة، أو الأنواع المشوّهة، أو القيم غير الصالحة تجعل Gateway يرفض البدء. والاستثناء الوحيد على مستوى الجذر هو $schema ‏(سلسلة نصية)، حتى تتمكن المحررات من إرفاق بيانات JSON Schema الوصفية.
ملاحظات أدوات المخطط:
  • يطبع openclaw config schema عائلة JSON Schema نفسها المستخدمة بواسطة Control UI والتحقق من الإعدادات.
  • تُنقل قيمتا title وdescription للحقل إلى خرج المخطط من أجل المحررات وأدوات النماذج.
  • ترث إدخالات الكائنات المتداخلة، والبدل الشامل (*)، وعناصر المصفوفات ([]) بيانات التوثيق الوصفية نفسها حيث توجد وثائق حقول مطابقة.
  • ترث فروع التركيب anyOf / oneOf / allOf أيضًا بيانات التوثيق الوصفية نفسها، بحيث تحتفظ متغيرات union/intersection بمساعدة الحقول نفسها.
  • يعيد config.schema.lookup مسار إعدادات واحدًا مطبّعًا مع عقدة مخطط سطحية (title وdescription وtype وenum وconst والحدود الشائعة وحقول تحقق مشابهة)، وبيانات تلميحات واجهة مستخدم مطابقة، وملخصات الأبناء المباشرين لأدوات التفصيل.
  • يتم دمج مخططات plugin/channel وقت التشغيل عندما يتمكن gateway من تحميل سجل manifest الحالي.
عندما يفشل التحقق:
  • لا يقلع Gateway
  • تعمل فقط أوامر التشخيص (openclaw doctor وopenclaw logs وopenclaw health وopenclaw status)
  • شغّل openclaw doctor لرؤية المشكلات الدقيقة
  • شغّل openclaw doctor --fix ‏(أو --yes) لتطبيق الإصلاحات

​
المهام الشائعة

لكل قناة قسم إعدادات خاص بها تحت channels.<provider>. راجع صفحة القناة المخصصة لخطوات الإعداد:تشترك جميع القنوات في نمط سياسة الرسائل المباشرة نفسه:
{
  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-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • يعرّف agents.defaults.models فهرس النماذج ويعمل كقائمة سماح لـ /model.
  • تستخدم مراجع النماذج تنسيق provider/model ‏(مثل anthropic/claude-opus-4-6).
  • يتحكم agents.defaults.imageMaxDimensionPx في تصغير صور السجل النصي/الأدوات (الافتراضي 1200)؛ وتؤدي القيم الأقل عادةً إلى تقليل استخدام رموز الرؤية في التشغيلات الكثيفة لصور الشاشة.
  • راجع Models CLI لتبديل النماذج في الدردشة وModel Failover لسلوك تدوير المصادقة والتراجع.
  • بالنسبة إلى المزوّدين المخصصين/المستضافين ذاتيًا، راجع المزوّدون المخصصون في المرجع.
يتم التحكم في الوصول إلى الرسائل المباشرة لكل قناة عبر dmPolicy:
  • "pairing" (الافتراضي): يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة للموافقة
  • "allowlist": فقط المرسلون الموجودون في allowFrom ‏(أو مخزن السماح المقترن)
  • "open": السماح بجميع الرسائل المباشرة الواردة (يتطلب allowFrom: ["*"])
  • "disabled": تجاهل جميع الرسائل المباشرة
بالنسبة إلى المجموعات، استخدم groupPolicy + groupAllowFrom أو قوائم السماح الخاصة بالقناة.راجع المرجع الكامل لتفاصيل كل قناة.
تكون رسائل المجموعات افتراضيًا تتطلب إشارة. قم بإعداد الأنماط لكل وكيل:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • إشارات البيانات الوصفية: إشارات @ الأصلية (WhatsApp tap-to-mention، وTelegram @bot، إلخ)
  • أنماط النص: أنماط regex آمنة في mentionPatterns
  • راجع المرجع الكامل لتجاوزات كل قناة ووضع الدردشة الذاتية.
استخدم agents.defaults.skills لخط أساس مشترك، ثم تجاوز الوكلاء المحددين باستخدام agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}
  • احذف agents.defaults.skills للحصول على Skills غير مقيّدة افتراضيًا.
  • احذف agents.list[].skills للوراثة من الإعدادات الافتراضية.
  • اضبط agents.list[].skills: [] لعدم وجود Skills.
  • راجع Skills، وإعدادات Skills، و مرجع الإعدادات.
تحكّم في مدى شدة إعادة تشغيل gateway للقنوات التي تبدو قديمة:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • اضبط gateway.channelHealthCheckMinutes: 0 لتعطيل عمليات إعادة التشغيل الناتجة عن مراقبة الصحة عالميًا.
  • يجب أن تكون channelStaleEventThresholdMinutes أكبر من أو مساوية لفاصل التحقق.
  • استخدم channels.<provider>.healthMonitor.enabled أو channels.<provider>.accounts.<id>.healthMonitor.enabled لتعطيل إعادة التشغيل التلقائي لقناة أو حساب واحد من دون تعطيل المراقب العام.
  • راجع فحوصات الصحة لتصحيح العمليات، والمرجع الكامل لجميع الحقول.
تتحكم الجلسات في استمرارية المحادثة والعزل:
{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: ‏main ‏(مشترك) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: إعدادات افتراضية عامة لتوجيه الجلسات المرتبطة بالسلاسل (يدعم Discord الأوامر /focus و/unfocus و/agents و/session idle و/session max-age).
  • راجع إدارة الجلسات للنطاقات وروابط الهوية وسياسة الإرسال.
  • راجع المرجع الكامل لجميع الحقول.
شغّل جلسات الوكيل داخل حاويات Docker معزولة:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
أنشئ الصورة أولًا: scripts/sandbox-setup.shراجع Sandboxing للدليل الكامل والمرجع الكامل لجميع الخيارات.
يتم إعداد push المدعوم عبر relay في openclaw.json.اضبط هذا في إعدادات gateway:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
مكافئ CLI:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
ما الذي يفعله هذا:
  • يتيح لـ gateway إرسال push.test وطلبات التنبيه wake nudges وتنبيهات إعادة الاتصال عبر relay الخارجي.
  • يستخدم منح إرسال ضمن نطاق التسجيل تعيد توجيهه تطبيقات iOS المقترنة. ولا يحتاج gateway إلى رمز relay عام على مستوى النشر.
  • يربط كل تسجيل مدعوم عبر relay بهوية gateway التي اقترن بها تطبيق iOS، بحيث لا يستطيع gateway آخر إعادة استخدام التسجيل المخزن.
  • يُبقي إصدارات iOS المحلية/اليدوية على APNs المباشر. وتنطبق عمليات الإرسال المدعومة عبر relay فقط على الإصدارات الرسمية الموزعة التي سجّلت عبر relay.
  • يجب أن يطابق عنوان URL الأساسي الخاص بـ relay المضمّن في إصدار iOS الرسمي/TestFlight، حتى تصل حركة التسجيل والإرسال إلى نشر relay نفسه.
التدفق الكامل:
  1. ثبّت إصدار iOS رسميًا/TestFlight تم تجميعه بعنوان URL أساسي لـ relay نفسه.
  2. اضبط gateway.push.apns.relay.baseUrl على gateway.
  3. اقترن بتطبيق iOS مع gateway ودع جلسات node وoperator تتصل.
  4. يجلب تطبيق iOS هوية gateway، ويسجّل مع relay باستخدام App Attest وإيصال التطبيق، ثم ينشر حمولة push.apns.register المدعومة عبر relay إلى gateway المقترن.
  5. يخزن gateway مقبض relay ومنح الإرسال، ثم يستخدمهما في push.test وطلبات التنبيه وتنبيهات إعادة الاتصال.
ملاحظات تشغيلية:
  • إذا بدّلت تطبيق iOS إلى gateway مختلف، فأعد توصيل التطبيق حتى يتمكن من نشر تسجيل relay جديد مرتبط بذلك gateway.
  • إذا أصدرت إصدار iOS جديدًا يشير إلى نشر relay مختلف، فسيقوم التطبيق بتحديث تسجيل relay المخبأ بدلًا من إعادة استخدام مصدر relay القديم.
ملاحظة التوافق:
  • لا يزال كل من OPENCLAW_APNS_RELAY_BASE_URL وOPENCLAW_APNS_RELAY_TIMEOUT_MS يعملان كتجاوزات بيئة مؤقتة.
  • يظل OPENCLAW_APNS_RELAY_ALLOW_HTTP=true منفذ هروب تطويريًا محصورًا بـ loopback فقط؛ لا تحفظ عناوين URL لـ relay عبر HTTP في الإعدادات.
راجع تطبيق iOS للتدفق الكامل وتدفق المصادقة والثقة لنموذج أمان relay.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: سلسلة مدة (30m و2h). اضبط 0m للتعطيل.
  • target: ‏last | none | <channel-id> ‏(مثل discord أو matrix أو telegram أو whatsapp)
  • directPolicy: ‏allow ‏(الافتراضي) أو block لأهداف heartbeat من نمط الرسائل المباشرة
  • راجع Heartbeat للدليل الكامل.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: تقليم جلسات التشغيل المعزولة المكتملة من sessions.json ‏(الافتراضي 24h؛ اضبط false للتعطيل).
  • runLog: تقليم cron/runs/<jobId>.jsonl حسب الحجم والأسطر المحتفظ بها.
  • راجع مهام Cron لنظرة عامة على الميزات وأمثلة CLI.
فعّل نقاط نهاية HTTP webhook على Gateway:
{
  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,
      },
    ],
  },
}
ملاحظة أمان:
  • تعامل مع كل محتوى حمولة hook/webhook على أنه إدخال غير موثوق.
  • استخدم hooks.token مخصصًا؛ لا تعِد استخدام رمز Gateway المشترك.
  • تكون مصادقة hook عبر الترويسات فقط (Authorization: Bearer ... أو x-openclaw-token)؛ وتُرفض الرموز الموجودة في سلسلة الاستعلام.
  • لا يمكن أن يكون hooks.path هو /؛ أبقِ إدخال webhook على مسار فرعي مخصص مثل /hooks.
  • أبقِ أعلام تجاوز المحتوى غير الآمن معطلة (hooks.gmail.allowUnsafeExternalContent وhooks.mappings[].allowUnsafeExternalContent) ما لم تكن تجري تصحيحًا محكم النطاق.
  • إذا فعّلت hooks.allowRequestSessionKey، فاضبط أيضًا hooks.allowedSessionKeyPrefixes لتقييد مفاتيح الجلسات التي يحددها المتصل.
  • بالنسبة إلى الوكلاء المدفوعين عبر hook، فضّل مستويات النماذج الحديثة القوية وسياسة الأدوات الصارمة (على سبيل المثال الرسائل فقط مع sandboxing حيثما أمكن).
راجع المرجع الكامل لجميع خيارات mappings وتكامل Gmail.
شغّل عدة وكلاء معزولين مع مساحات عمل وجلسات منفصلة:
{
  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 مستويات
  • المسارات النسبية: تُحل نسبةً إلى الملف الذي يتضمنها
  • التعامل مع الأخطاء: أخطاء واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية

​
إعادة التحميل السريع للإعدادات

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

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

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

​
ما الذي يُطبَّق مباشرة وما الذي يحتاج إلى إعادة تشغيل

تُطبّق معظم الحقول مباشرة من دون توقف. وفي وضع hybrid، تتم معالجة التغييرات التي تتطلب إعادة تشغيل تلقائيًا.
الفئةالحقولهل يلزم إعادة تشغيل؟
القنواتchannels.* وweb ‏(WhatsApp) — جميع القنوات المضمنة وقنوات pluginsلا
الوكيل والنماذجagent وagents وmodels وroutingلا
الأتمتةhooks وcron وagent.heartbeatلا
الجلسات والرسائلsession وmessagesلا
الأدوات والوسائطtools وbrowser وskills وaudio وtalkلا
واجهة المستخدم ومتفرقاتui وlogging وidentity وbindingsلا
خادم Gatewaygateway.* ‏(المنفذ، والربط، والمصادقة، وtailscale، وTLS، وHTTP)نعم
البنية التحتيةdiscovery وcanvasHost وpluginsنعم
يُعد كل من gateway.reload وgateway.remote استثناءين — فالتغيير فيهما لا يؤدي إلى إعادة تشغيل.

​
Config RPC ‏(تحديثات برمجية)

تخضع استدعاءات RPC الخاصة بالكتابة في مستوى التحكم (config.apply وconfig.patch وupdate.run) لحد معدل يبلغ 3 طلبات لكل 60 ثانية لكل deviceId+clientIp. وعند تطبيق الحد، يعيد RPC القيمة UNAVAILABLE مع retryAfterMs.
التدفق الآمن/الافتراضي:
  • config.schema.lookup: فحص شجرة إعدادات واحدة ضمن نطاق مسار واحد مع عقدة مخطط سطحية، وبيانات تلميحات مطابقة، وملخصات الأبناء المباشرين
  • config.get: جلب اللقطة الحالية + hash
  • config.patch: المسار المفضل للتحديث الجزئي
  • config.apply: استبدال الإعدادات الكاملة فقط
  • update.run: تحديث ذاتي صريح + إعادة تشغيل
عندما لا تستبدل الإعدادات بالكامل، فافضّل config.schema.lookup ثم config.patch.
يتحقق من الإعدادات الكاملة ويكتبها ثم يعيد تشغيل Gateway في خطوة واحدة.
يستبدل config.apply الإعدادات بالكامل. استخدم config.patch للتحديثات الجزئية، أو openclaw config set للمفاتيح المفردة.
المعلمات:
  • raw ‏(string) — حمولة JSON5 للإعدادات الكاملة
  • baseHash ‏(اختياري) — hash الإعدادات من config.get ‏(مطلوب عندما تكون الإعدادات موجودة)
  • sessionKey ‏(اختياري) — مفتاح الجلسة لتنبيه wake-up بعد إعادة التشغيل
  • note ‏(اختياري) — ملاحظة لـ restart sentinel
  • restartDelayMs ‏(اختياري) — تأخير قبل إعادة التشغيل (الافتراضي 2000)
يتم دمج طلبات إعادة التشغيل بينما يكون أحدها معلقًا/قيد التنفيذ بالفعل، ويُطبَّق تبريد لمدة 30 ثانية بين دورات إعادة التشغيل.
openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
يدمج تحديثًا جزئيًا في الإعدادات الحالية (وفق دلالات JSON merge patch):
  • تُدمج الكائنات بشكل متكرر
  • تحذف null المفتاح
  • تستبدل المصفوفات
المعلمات:
  • raw ‏(string) — JSON5 يحتوي فقط على المفاتيح المطلوب تغييرها
  • baseHash ‏(مطلوب) — hash الإعدادات من config.get
  • sessionKey وnote وrestartDelayMs — مثل config.apply
يطابق سلوك إعادة التشغيل الأمر config.apply: إعادة التشغيلات المعلقة المدمجة بالإضافة إلى تبريد 30 ثانية بين دورات إعادة التشغيل.
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

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

يقرأ OpenClaw متغيرات البيئة من العملية الأصلية بالإضافة إلى:
  • .env من دليل العمل الحالي (إن وجد)
  • ~/.openclaw/.env ‏(تراجع عام)
لا يقوم أي من الملفين بتجاوز متغيرات البيئة الموجودة. ويمكنك أيضًا ضبط متغيرات بيئة مضمنة في الإعدادات: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
إذا كان مفعّلًا ولم تكن المفاتيح المتوقعة مضبوطة، فإن OpenClaw يشغّل shell تسجيل الدخول الخاص بك ويستورد فقط المفاتيح المفقودة:
{
  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"
بالنسبة إلى الحقول التي تدعم كائنات SecretRef، يمكنك استخدام:
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
توجد تفاصيل SecretRef ‏(بما في ذلك secrets.providers الخاصة بـ env/file/exec) في إدارة الأسرار. وتُسرد مسارات بيانات الاعتماد المدعومة في سطح بيانات اعتماد SecretRef.
راجع البيئة للأولوية الكاملة والمصادر.

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

للحصول على مرجع كامل لكل حقل، راجع مرجع الإعدادات.
ذو صلة: أمثلة الإعدادات · مرجع الإعدادات · Doctor