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

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

بدء سريع وأسئلة وأجوبة التشغيل الأول. للعمليات اليومية، والنماذج، والمصادقة، والجلسات، واستكشاف الأخطاء وإصلاحها، راجع الأسئلة الشائعة الرئيسية.

​
البدء السريع وإعداد التشغيل الأول

استخدم وكيل ذكاء اصطناعي محليًا يمكنه رؤية جهازك. هذا أكثر فاعلية بكثير من السؤال في Discord، لأن معظم حالات “أنا عالق” تكون مشكلات إعداد محلية أو مشكلات بيئة لا يستطيع المساعدون عن بُعد فحصها.يمكن لهذه الأدوات قراءة المستودع، وتشغيل الأوامر، وفحص السجلات، والمساعدة في إصلاح إعدادك على مستوى الجهاز (PATH، والخدمات، والأذونات، وملفات المصادقة). امنحها نسخة المصدر الكاملة عبر تثبيت قابل للتعديل (git):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
يؤدي هذا إلى تثبيت OpenClaw من نسخة git، بحيث يستطيع الوكيل قراءة الكود + المستندات والاستدلال على الإصدار الدقيق الذي تشغّله. يمكنك دائمًا الرجوع إلى الإصدار المستقر لاحقًا بإعادة تشغيل المثبّت دون --install-method git.نصيحة: اطلب من الوكيل تخطيط الإصلاح والإشراف عليه (خطوة بخطوة)، ثم تنفيذ الأوامر الضرورية فقط. هذا يبقي التغييرات صغيرة وأسهل في المراجعة.إذا اكتشفت خطأً حقيقيًا أو إصلاحًا، فيُرجى فتح مشكلة على GitHub أو إرسال PR: https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pullsابدأ بهذه الأوامر (شارك المخرجات عند طلب المساعدة):
openclaw status
openclaw models status
openclaw doctor
ما الذي تفعله:
  • openclaw status: لقطة سريعة لحالة gateway/agent + الإعداد الأساسي.
  • openclaw models status: يتحقق من مصادقة المزوّد + توفر النموذج.
  • openclaw doctor: يتحقق من مشكلات الإعداد/الحالة الشائعة ويصلحها.
فحوصات CLI مفيدة أخرى: openclaw status --all، وopenclaw logs --follow، وopenclaw gateway status، وopenclaw health --verbose.حلقة تصحيح سريعة: أول 60 ثانية إذا كان هناك شيء معطّل. مستندات التثبيت: التثبيت، رايات المثبّت، التحديث.
أسباب تخطي heartbeat الشائعة:
  • quiet-hours: خارج نافذة ساعات النشاط المضبوطة
  • empty-heartbeat-file: يوجد HEARTBEAT.md لكنه يحتوي فقط على هيكل فارغ/رؤوس فقط
  • no-tasks-due: وضع المهام في HEARTBEAT.md نشط، لكن لم يحن موعد أي من فواصل المهام بعد
  • alerts-disabled: كل ظهور heartbeat معطّل (showOk وshowAlerts وuseIndicator كلها متوقفة)
في وضع المهام، لا يتم تقديم الطوابع الزمنية المستحقة إلا بعد اكتمال تشغيل heartbeat حقيقي. لا تُعلّم عمليات التشغيل المتخطاة المهام كمكتملة.المستندات: Heartbeat، الأتمتة.
يوصي المستودع بالتشغيل من المصدر واستخدام الإعداد التمهيدي:
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
يمكن للمعالج أيضًا بناء أصول الواجهة تلقائيًا. بعد الإعداد التمهيدي، ستشغّل عادةً Gateway على المنفذ 18789.من المصدر (للمساهمين/التطوير):
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard
إذا لم يكن لديك تثبيت عام بعد، شغّله عبر pnpm openclaw onboard.
يفتح المعالج متصفحك بعنوان URL نظيف للوحة التحكم (غير مضمّن برمز) مباشرةً بعد الإعداد التمهيدي، ويطبع الرابط أيضًا في الملخص. أبقِ ذلك التبويب مفتوحًا؛ إذا لم يفتح، انسخ/الصق عنوان URL المطبوع على الجهاز نفسه.
Localhost (الجهاز نفسه):
  • افتح http://127.0.0.1:18789/.
  • إذا طلب مصادقة السر المشترك، فالصق الرمز أو كلمة المرور المضبوطة في إعدادات واجهة التحكم.
  • مصدر الرمز: gateway.auth.token (أو OPENCLAW_GATEWAY_TOKEN).
  • مصدر كلمة المرور: gateway.auth.password (أو OPENCLAW_GATEWAY_PASSWORD).
  • إذا لم يتم ضبط سر مشترك بعد، فأنشئ رمزًا باستخدام openclaw doctor --generate-gateway-token.
ليس على localhost:
  • Tailscale Serve (موصى به): أبقِ الربط على local loopback، وشغّل openclaw gateway --tailscale serve، وافتح https://<magicdns>/. إذا كانت gateway.auth.allowTailscale تساوي true، فإن رؤوس الهوية تفي بمصادقة واجهة التحكم/WebSocket (لا حاجة للصق سر مشترك، مع افتراض أن مضيف Gateway موثوق)؛ لا تزال HTTP APIs تتطلب مصادقة السر المشترك ما لم تستخدم عمدًا none للإدخال الخاص أو مصادقة HTTP عبر وكيل موثوق. تتم تسلسلة محاولات مصادقة Serve المتزامنة الخاطئة من العميل نفسه قبل أن يسجلها محدد فشل المصادقة، لذلك قد تعرض إعادة المحاولة الخاطئة الثانية بالفعل retry later.
  • ربط Tailnet: شغّل openclaw gateway --bind tailnet --token "<token>" (أو اضبط مصادقة كلمة المرور)، وافتح http://<tailscale-ip>:18789/، ثم الصق السر المشترك المطابق في إعدادات لوحة التحكم.
  • وكيل عكسي واعٍ بالهوية: أبقِ Gateway خلف وكيل موثوق، واضبط gateway.auth.mode: "trusted-proxy"، ثم افتح عنوان URL الخاص بالوكيل. تتطلب وكلاء local loopback على المضيف نفسه ضبطًا صريحًا لـ gateway.auth.trustedProxy.allowLoopback = true.
  • نفق SSH: ssh -N -L 18789:127.0.0.1:18789 user@host ثم افتح http://127.0.0.1:18789/. لا تزال مصادقة السر المشترك تنطبق عبر النفق؛ الصق الرمز أو كلمة المرور المضبوطة إذا طُلب منك ذلك.
راجع لوحة التحكم وأسطح الويب لمعرفة أوضاع الربط وتفاصيل المصادقة.
إنها تتحكم في طبقات مختلفة:
  • approvals.exec: تمرر مطالبات الموافقة إلى وجهات الدردشة
  • channels.<channel>.execApprovals: يجعل تلك القناة تعمل كعميل موافقة أصلي لموافقات التنفيذ
لا تزال سياسة تنفيذ المضيف هي بوابة الموافقة الحقيقية. إعدادات الدردشة تتحكم فقط في مكان ظهور مطالبات الموافقة وكيف يمكن للأشخاص الرد عليها.في معظم الإعدادات لا تحتاج إلى كليهما:
  • إذا كانت الدردشة تدعم بالفعل الأوامر والردود، فإن /approve في الدردشة نفسها يعمل عبر المسار المشترك.
  • إذا كان بإمكان قناة أصلية مدعومة استنتاج الموافقين بأمان، فإن OpenClaw يفعّل الآن الموافقات الأصلية المعتمدة على الرسائل المباشرة أولًا تلقائيًا عندما تكون channels.<channel>.execApprovals.enabled غير مضبوطة أو "auto".
  • عندما تتوفر بطاقات/أزرار الموافقة الأصلية، تكون تلك الواجهة الأصلية هي المسار الأساسي؛ ويجب على الوكيل ألا يضمّن أمر /approve يدويًا إلا إذا قالت نتيجة الأداة إن موافقات الدردشة غير متاحة أو إن الموافقة اليدوية هي المسار الوحيد.
  • استخدم approvals.exec فقط عندما يجب أيضًا تمرير المطالبات إلى دردشات أخرى أو غرف عمليات صريحة.
  • استخدم channels.<channel>.execApprovals.target: "channel" أو "both" فقط عندما تريد صراحةً نشر مطالبات الموافقة مرة أخرى في الغرفة/الموضوع الأصلي.
  • موافقات Plugin منفصلة مرة أخرى: تستخدم /approve في الدردشة نفسها افتراضيًا، مع تمرير اختياري عبر approvals.plugin، وتُبقي بعض القنوات الأصلية فقط معالجة الموافقة الأصلية لـ Plugin فوق ذلك.
الخلاصة: التمرير مخصص للتوجيه، وإعداد العميل الأصلي مخصص لتجربة استخدام أغنى خاصة بالقناة. راجع موافقات التنفيذ.
يلزم Node >= 22. يوصى باستخدام pnpm. لا يوصى باستخدام Bun مع Gateway.
نعم. Gateway خفيف - تذكر المستندات أن 512MB-1GB RAM ونواة واحدة وحوالي 500MB من مساحة القرص تكفي للاستخدام الشخصي، وتشير إلى أن Raspberry Pi 4 يمكنه تشغيله.إذا أردت هامشًا إضافيًا (سجلات، ووسائط، وخدمات أخرى)، فيوصى بـ 2GB، لكنه ليس حدًا أدنى صارمًا.نصيحة: يمكن لـ Pi/VPS صغير استضافة Gateway، ويمكنك إقران العُقد على حاسوبك المحمول/هاتفك من أجل الشاشة/الكاميرا/اللوحة المحلية أو تنفيذ الأوامر. راجع العُقد.
الخلاصة: يعمل، لكن توقّع بعض الحواف الخشنة.
  • استخدم نظام تشغيل 64-bit وحافظ على Node >= 22.
  • فضّل التثبيت القابل للتعديل (git) حتى تتمكن من رؤية السجلات والتحديث بسرعة.
  • ابدأ من دون قنوات/Skills، ثم أضفها واحدة تلو الأخرى.
  • إذا واجهت مشكلات ثنائية غريبة، فهي عادةً مشكلة توافق ARM.
المستندات: Linux، التثبيت.
تعتمد تلك الشاشة على كون Gateway قابلًا للوصول ومصادقًا. يرسل TUI أيضًا “Wake up, my friend!” تلقائيًا عند أول فقس. إذا رأيت ذلك السطر مع عدم وجود رد وبقاء الرموز عند 0، فهذا يعني أن الوكيل لم يعمل مطلقًا.
  1. أعد تشغيل Gateway:
openclaw gateway restart
  1. تحقق من الحالة + المصادقة:
openclaw status
openclaw models status
openclaw logs --follow
  1. إذا ظل عالقًا، شغّل:
openclaw doctor
إذا كان Gateway بعيدًا، فتأكد من أن النفق/اتصال Tailscale يعمل وأن الواجهة تشير إلى Gateway الصحيح. راجع الوصول البعيد.
نعم. انسخ دليل الحالة ومساحة العمل، ثم شغّل Doctor مرة واحدة. هذا يبقي بوتك “كما هو تمامًا” (الذاكرة، وسجل الجلسات، والمصادقة، وحالة القنوات) ما دمت تنسخ كلا الموقعين:
  1. ثبّت OpenClaw على الجهاز الجديد.
  2. انسخ $OPENCLAW_STATE_DIR (الافتراضي: ~/.openclaw) من الجهاز القديم.
  3. انسخ مساحة عملك (الافتراضي: ~/.openclaw/workspace).
  4. شغّل openclaw doctor وأعد تشغيل خدمة Gateway.
يحافظ ذلك على الإعداد، وملفات تعريف المصادقة، وبيانات اعتماد WhatsApp، والجلسات، والذاكرة. إذا كنت في الوضع البعيد، فتذكّر أن مضيف gateway يملك مخزن الجلسات ومساحة العمل.مهم: إذا كنت تلتزم/تدفع مساحة عملك فقط إلى GitHub، فأنت تنسخ احتياطيًا الذاكرة + ملفات bootstrap، لكن ليس سجل الجلسات أو المصادقة. هذه موجودة تحت ~/.openclaw/ (على سبيل المثال ~/.openclaw/agents/<agentId>/sessions/).ذو صلة: الترحيل، أين توجد الأشياء على القرص، مساحة عمل الوكيل، Doctor، الوضع البعيد.
تحقق من سجل تغييرات GitHub: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.mdأحدث الإدخالات في الأعلى. إذا كان القسم العلوي موسومًا غير منشور، فإن القسم المؤرخ التالي هو أحدث إصدار تم شحنه. تُجمّع الإدخالات حسب أبرز الميزات والتغييرات و الإصلاحات (بالإضافة إلى أقسام المستندات/الأقسام الأخرى عند الحاجة).
تحظر بعض اتصالات Comcast/Xfinity نطاق docs.openclaw.ai خطأً عبر Xfinity Advanced Security. عطّله أو أضف docs.openclaw.ai إلى قائمة السماح، ثم أعد المحاولة. يُرجى مساعدتنا في رفع الحظر عنه بالإبلاغ هنا: https://spa.xfinity.com/check_url_status.إذا كنت لا تزال غير قادر على الوصول إلى الموقع، فالمستندات منسوخة على GitHub: https://github.com/openclaw/openclaw/tree/main/docs
المستقر وبيتا هما وسما توزيع npm، وليسا خطي شيفرة منفصلين:
  • latest = مستقر
  • beta = إصدار مبكر للاختبار
عادة، يصل الإصدار المستقر إلى بيتا أولا، ثم تنقل خطوة ترقية صريحة ذلك الإصدار نفسه إلى latest. يمكن للمشرفين أيضا النشر مباشرة إلى latest عند الحاجة. لهذا يمكن أن يشير بيتا والمستقر إلى الإصدار نفسه بعد الترقية.راجع ما تغير: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.mdللحصول على أوامر التثبيت المختصرة والفرق بين بيتا ونسخة التطوير، راجع الأكورديون أدناه.
بيتا هو وسم توزيع npm beta (قد يطابق latest بعد الترقية). التطوير هو الرأس المتحرك لفرع main (git)؛ وعند نشره، يستخدم وسم توزيع npm dev.أوامر مختصرة (macOS/Linux):
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
مثبت Windows (PowerShell): https://openclaw.ai/install.ps1تفاصيل أكثر: قنوات التطوير وأعلام المثبت.
خياران:
  1. قناة التطوير (git checkout):
openclaw update --channel dev
يبدل هذا إلى فرع main ويحدث من المصدر.
  1. تثبيت قابل للتعديل (من موقع المثبت):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
يمنحك ذلك مستودعا محليا يمكنك تحريره، ثم تحديثه عبر git.إذا كنت تفضل استنساخا نظيفا يدويا، فاستخدم:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
الوثائق: التحديث، قنوات التطوير، التثبيت.
دليل تقريبي:
  • التثبيت: من 2 إلى 5 دقائق
  • الإعداد الأولي: من 5 إلى 15 دقيقة بحسب عدد القنوات/النماذج التي تضبطها
إذا توقف، فاستخدم تعطل المثبت وحلقة التصحيح السريعة في أنا عالق.
أعد تشغيل المثبت مع مخرجات تفصيلية:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
تثبيت بيتا مع مخرجات تفصيلية:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
لتثبيت قابل للتعديل (git):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
المكافئ في Windows (PowerShell):
# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
خيارات أكثر: أعلام المثبت.
مشكلتان شائعتان في Windows:1) خطأ npm spawn git / لم يتم العثور على git
  • ثبت Git for Windows وتأكد من أن git موجود في PATH.
  • أغلق PowerShell وأعد فتحه، ثم شغل المثبت من جديد.
2) لا يتم التعرف على openclaw بعد التثبيت
  • مجلد bin العام في npm غير موجود في PATH.
  • تحقق من المسار: 
    npm config get prefix
  • أضف ذلك الدليل إلى PATH الخاص بالمستخدم (لا حاجة إلى لاحقة \bin في Windows؛ في معظم الأنظمة يكون %AppData%\npm).
  • أغلق PowerShell وأعد فتحه بعد تحديث PATH.
إذا كنت تريد أسلس إعداد على Windows، فاستخدم WSL2 بدلا من Windows الأصلي. الوثائق: Windows.
يكون هذا عادة عدم تطابق في صفحة ترميز الطرفية على أغلفة Windows الأصلية.الأعراض:
  • تعرض مخرجات system.run/exec النص الصيني كنص مشوه
  • يبدو الأمر نفسه سليما في ملف تعريف طرفية آخر
حل سريع في PowerShell:
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
ثم أعد تشغيل Gateway وجرب الأمر مرة أخرى:
openclaw gateway restart
إذا ظل بإمكانك إعادة إنتاج ذلك على أحدث OpenClaw، فتتبعه/أبلغ عنه في:
استخدم التثبيت القابل للتعديل (git) ليكون لديك المصدر الكامل والوثائق محليا، ثم اسأل بوتك (أو Claude/Codex) من ذلك المجلد حتى يتمكن من قراءة المستودع والإجابة بدقة.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
تفاصيل أكثر: التثبيت وأعلام المثبت.
الإجابة المختصرة: اتبع دليل Linux، ثم شغل الإعداد الأولي.
يعمل أي VPS يعمل بنظام Linux. ثبته على الخادم، ثم استخدم SSH/Tailscale للوصول إلى Gateway.الأدلة: exe.dev، Hetzner، Fly.io. الوصول عن بعد: Gateway عن بعد.
نحتفظ بمركز استضافة يضم المزودين الشائعين. اختر واحدا واتبع الدليل:طريقة عمله في السحابة: يعمل Gateway على الخادم، وتصل إليه من الحاسوب المحمول/الهاتف عبر واجهة التحكم (أو Tailscale/SSH). حالتك + مساحة عملك موجودتان على الخادم، لذا تعامل مع المضيف باعتباره مصدر الحقيقة وخذ نسخة احتياطية منه.يمكنك إقران العقد (Mac/iOS/Android/بدون واجهة) مع ذلك Gateway السحابي للوصول إلى الشاشة/الكاميرا/اللوحة المحلية أو تشغيل أوامر على حاسوبك المحمول مع إبقاء Gateway في السحابة.المركز: المنصات. الوصول عن بعد: Gateway عن بعد. العقد: العقد، CLI العقد.
الإجابة المختصرة: ممكن، لكنه غير موصى به. يمكن لمسار التحديث إعادة تشغيل Gateway (ما يسقط الجلسة النشطة)، وقد يحتاج إلى git checkout نظيف، ويمكن أن يطلب تأكيدا. الأكثر أمانا: شغل التحديثات من shell بصفتك المشغل.استخدم CLI:
openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart
إذا كان لا بد من الأتمتة من وكيل:
openclaw update --yes --no-restart
openclaw gateway restart
الوثائق: التحديث، التحديثات.
openclaw onboard هو مسار الإعداد الموصى به. في الوضع المحلي يرشدك عبر:
  • إعداد النموذج/المصادقة (OAuth للمزود، مفاتيح API، رمز إعداد Anthropic، إضافة إلى خيارات النماذج المحلية مثل LM Studio)
  • موقع مساحة العمل + ملفات التمهيد
  • إعدادات Gateway (الربط/المنفذ/المصادقة/tailscale)
  • القنوات (WhatsApp، Telegram، Discord، Mattermost، Signal، iMessage، إضافة إلى Plugins القنوات المضمنة مثل QQ Bot)
  • تثبيت Daemon (LaunchAgent على macOS؛ وحدة مستخدم systemd على Linux/WSL2)
  • فحوصات الصحة واختيار Skills
كما يحذر إذا كان النموذج المضبوط غير معروف أو يفتقد المصادقة.
لا. يمكنك تشغيل OpenClaw باستخدام مفاتيح API (Anthropic/OpenAI/غيرها) أو باستخدام نماذج محلية فقط بحيث تبقى بياناتك على جهازك. الاشتراكات (Claude Pro/Max أو OpenAI Codex) هي طرق اختيارية لمصادقة هؤلاء المزودين.بالنسبة إلى Anthropic في OpenClaw، يكون التقسيم العملي كالتالي:
  • مفتاح Anthropic API: فوترة Anthropic API العادية
  • مصادقة Claude CLI / اشتراك Claude في OpenClaw: أخبرنا موظفو Anthropic أن هذا الاستخدام مسموح به مرة أخرى، ويتعامل OpenClaw مع استخدام claude -p على أنه معتمد لهذا التكامل ما لم تنشر Anthropic سياسة جديدة
بالنسبة إلى مضيفي Gateway طويل الأمد، تظل مفاتيح Anthropic API هي الإعداد الأكثر قابلية للتنبؤ. OpenAI Codex OAuth مدعوم صراحة للأدوات الخارجية مثل OpenClaw.يدعم OpenClaw أيضا خيارات أخرى مستضافة بنمط الاشتراك، بما في ذلك Qwen Cloud Coding Plan وMiniMax Coding Plan و Z.AI / GLM Coding Plan.الوثائق: Anthropic، OpenAI، Qwen Cloud، MiniMax، نماذج GLM، النماذج المحلية، النماذج.
نعم.أخبرنا موظفو Anthropic أن استخدام Claude CLI بأسلوب OpenClaw مسموح به مرة أخرى، لذلك يتعامل OpenClaw مع مصادقة اشتراك Claude واستخدام claude -p على أنهما معتمدان لهذا التكامل ما لم تنشر Anthropic سياسة جديدة. إذا كنت تريد إعدادا جانب الخادم أكثر قابلية للتنبؤ، فاستخدم مفتاح Anthropic API بدلا من ذلك.
نعم.أخبرنا موظفو Anthropic أن هذا الاستخدام مسموح به مرة أخرى، لذلك يتعامل OpenClaw مع إعادة استخدام Claude CLI واستخدام claude -p على أنهما معتمدان لهذا التكامل ما لم تنشر Anthropic سياسة جديدة.لا يزال رمز إعداد Anthropic متاحا كمسار رمز مدعوم في OpenClaw، لكن OpenClaw يفضل الآن إعادة استخدام Claude CLI وclaude -p عند توفرهما. بالنسبة إلى أحمال عمل الإنتاج أو متعددة المستخدمين، تظل مصادقة مفتاح Anthropic API الخيار الأكثر أمانا وقابلية للتنبؤ. إذا كنت تريد خيارات مستضافة أخرى بنمط الاشتراك في OpenClaw، فراجع OpenAI، Qwen / Model Cloud، MiniMax، ونماذج GLM.
يعني ذلك أن حصة/حد معدل Anthropic لديك قد استنفدت للنافذة الحالية. إذا كنت تستخدم Claude CLI، فانتظر حتى يعاد ضبط النافذة أو رق خطة اشتراكك. إذا كنت تستخدم مفتاح Anthropic API، فتحقق من Anthropic Console لمعرفة الاستخدام/الفوترة وارفع الحدود حسب الحاجة.إذا كانت الرسالة تحديدا: Extra usage is required for long context requests، فهذا يعني أن الطلب يحاول استخدام بيتا سياق 1M من Anthropic (context1m: true). لا يعمل ذلك إلا عندما تكون بيانات اعتمادك مؤهلة لفوترة السياق الطويل (فوترة مفتاح API أو مسار تسجيل دخول Claude في OpenClaw مع تفعيل Extra Usage).نصيحة: عيّن نموذجًا احتياطيًا حتى يتمكن OpenClaw من متابعة الرد عندما يكون مزود محدودًا بمعدل الاستخدام. راجع النماذج، وOAuth، و /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.
نعم. يحتوي OpenClaw على مزود Amazon Bedrock (Converse) مضمّن. عند وجود مؤشرات بيئة AWS، يستطيع OpenClaw اكتشاف كتالوج Bedrock للبث/النص تلقائيًا ودمجه كمزود amazon-bedrock ضمني؛ وإلا يمكنك تفعيل plugins.entries.amazon-bedrock.config.discovery.enabled صراحةً أو إضافة إدخال مزود يدوي. راجع Amazon Bedrock ومزودو النماذج. إذا كنت تفضل تدفق مفاتيح مُدارًا، فلا يزال استخدام وكيل متوافق مع OpenAI أمام Bedrock خيارًا صالحًا.
يدعم OpenClaw OpenAI Code (Codex) عبر OAuth (تسجيل الدخول إلى ChatGPT). استخدم openai/gpt-5.5 للإعداد الشائع: مصادقة اشتراك ChatGPT/Codex بالإضافة إلى تنفيذ خادم تطبيق Codex الأصلي. مراجع نماذج openai-codex/gpt-* هي إعدادات قديمة يصلحها openclaw doctor --fix. يظل الوصول المباشر بمفتاح OpenAI API متاحًا لأسطح OpenAI API غير الخاصة بالوكلاء ولنماذج الوكلاء عبر ملف تعريف مفتاح API مرتب لـ openai-codex. راجع مزودو النماذج والإعداد الأولي (CLI).
openai-codex هو معرّف المزود وملف تعريف المصادقة لـ OAuth الخاص بـ ChatGPT/Codex. استخدمت الإعدادات الأقدم هذا أيضًا كبادئة نموذج:
  • openai/gpt-5.5 = مصادقة اشتراك ChatGPT/Codex مع وقت تشغيل Codex الأصلي لدورات الوكيل
  • openai-codex/gpt-5.5 = مسار نموذج قديم يصلحه openclaw doctor --fix
  • openai/gpt-5.5 بالإضافة إلى ملف تعريف مفتاح API مرتب لـ openai-codex = مصادقة مفتاح API لنموذج وكيل OpenAI
  • openai-codex:... = معرّف ملف تعريف المصادقة، وليس مرجع نموذج
إذا أردت مسار الفوترة/الحدود المباشر لـ OpenAI Platform، فعيّن OPENAI_API_KEY. إذا أردت مصادقة اشتراك ChatGPT/Codex، فسجّل الدخول باستخدام openclaw models auth login --provider openai-codex. أبقِ مرجع النموذج على openai/gpt-5.5؛ مراجع نماذج openai-codex/* هي إعدادات قديمة يعيد openclaw doctor --fix كتابتها.
يستخدم Codex OAuth نوافذ حصة مُدارة من OpenAI وتعتمد على الخطة. عمليًا، قد تختلف هذه الحدود عن تجربة موقع/تطبيق ChatGPT، حتى عندما يكون كلاهما مرتبطًا بالحساب نفسه.يستطيع OpenClaw عرض نوافذ استخدام/حصة المزود المرئية حاليًا في openclaw models status، لكنه لا يخترع استحقاقات ChatGPT على الويب أو يطبعها كصلاحية وصول مباشر إلى API. إذا أردت مسار الفوترة/الحدود المباشر لـ OpenAI Platform، فاستخدم openai/* مع مفتاح API.
نعم. يدعم OpenClaw بالكامل OAuth لاشتراك OpenAI Code (Codex). تسمح OpenAI صراحةً باستخدام OAuth الخاص بالاشتراك في الأدوات/تدفقات العمل الخارجية مثل OpenClaw. يمكن للإعداد الأولي تشغيل تدفق OAuth نيابةً عنك.راجع OAuth، ومزودو النماذج، والإعداد الأولي (CLI).
يستخدم Gemini CLI تدفق مصادقة Plugin، وليس معرّف عميل أو سرًا في openclaw.json.الخطوات:
  1. ثبّت Gemini CLI محليًا بحيث يكون gemini موجودًا على PATH
    • Homebrew: brew install gemini-cli
    • npm: npm install -g @google/gemini-cli
  2. فعّل Plugin: openclaw plugins enable google
  3. سجّل الدخول: openclaw models auth login --provider google-gemini-cli --set-default
  4. النموذج الافتراضي بعد تسجيل الدخول: google-gemini-cli/gemini-3-flash-preview
  5. إذا فشلت الطلبات، فعيّن GOOGLE_CLOUD_PROJECT أو GOOGLE_CLOUD_PROJECT_ID على مضيف Gateway
يخزّن هذا رموز OAuth في ملفات تعريف المصادقة على مضيف Gateway. التفاصيل: مزودو النماذج.
غالبًا لا. يحتاج OpenClaw إلى سياق كبير + أمان قوي؛ البطاقات الصغيرة تقتطع وتسرّب. إذا كان لا بد من ذلك، فشغّل أكبر بناء نموذج يمكنك تشغيله محليًا (LM Studio) وراجع /gateway/local-models. تزيد النماذج الأصغر/المكمّمة خطر حقن الموجهات - راجع الأمان.
اختر نقاط نهاية مثبتة بالمنطقة. يوفّر OpenRouter خيارات مستضافة في الولايات المتحدة لـ MiniMax وKimi وGLM؛ اختر النسخة المستضافة في الولايات المتحدة لإبقاء البيانات داخل المنطقة. لا يزال بإمكانك إدراج Anthropic/OpenAI إلى جانب هذه باستخدام models.mode: "merge" حتى تظل النماذج الاحتياطية متاحة مع احترام المزود الإقليمي الذي تختاره.
لا. يعمل OpenClaw على macOS أو Linux (Windows عبر WSL2). جهاز Mac mini اختياري - يشتريه بعض الأشخاص كمضيف دائم التشغيل، لكن VPS صغيرًا أو خادمًا منزليًا أو صندوقًا من فئة Raspberry Pi يعمل أيضًا.تحتاج إلى Mac فقط للأدوات الخاصة بـ macOS فقط. بالنسبة إلى iMessage، استخدم iMessage مع imsg على أي Mac مسجل الدخول إلى Messages. إذا كان Gateway يعمل على Linux أو في مكان آخر، فعيّن channels.imessage.cliPath إلى غلاف SSH يشغّل imsg على ذلك الـ Mac. إذا أردت أدوات أخرى خاصة بـ macOS فقط، فشغّل Gateway على Mac أو أقرن Node macOS.الوثائق: iMessage، Nodes، وضع Mac البعيد.
تحتاج إلى جهاز macOS ما مسجل الدخول إلى Messages. لا يجب أن يكون Mac mini - أي Mac يفي بالغرض. استخدم iMessage مع imsg؛ يمكن أن يعمل Gateway على ذلك الـ Mac، أو يمكن أن يعمل في مكان آخر مع غلاف SSH cliPath.الإعدادات الشائعة:
  • شغّل Gateway على Linux/VPS، وعيّن channels.imessage.cliPath إلى غلاف SSH يشغّل imsg على Mac مسجل الدخول إلى Messages.
  • شغّل كل شيء على الـ Mac إذا أردت أبسط إعداد على جهاز واحد.
الوثائق: iMessage، Nodes، وضع Mac البعيد.
نعم. يمكن لـ Mac mini تشغيل Gateway، ويمكن لـ MacBook Pro الخاص بك الاتصال كـ Node (جهاز مرافق). لا تشغّل Nodes الـ Gateway - بل توفر قدرات إضافية مثل الشاشة/الكاميرا/اللوحة وsystem.run على ذلك الجهاز.النمط الشائع:
  • Gateway على Mac mini (دائم التشغيل).
  • يشغّل MacBook Pro تطبيق macOS أو مضيف Node ويقترن بـ Gateway.
  • استخدم openclaw nodes status / openclaw nodes list لرؤيته.
الوثائق: Nodes، CLI الخاص بـ Nodes.
Bun غير موصى به. نرى أخطاء وقت تشغيل، خاصةً مع WhatsApp وTelegram. استخدم Node لبوابات مستقرة.إذا كنت لا تزال تريد تجربة Bun، فافعل ذلك على Gateway غير إنتاجي بدون WhatsApp/Telegram.
channels.telegram.allowFrom هو معرّف مستخدم Telegram للمرسل البشري (رقمي). وليس اسم مستخدم البوت.يطلب الإعداد معرّفات المستخدمين الرقمية فقط. إذا كانت لديك بالفعل إدخالات @username قديمة في الإعدادات، يمكن لـ openclaw doctor --fix محاولة حلها.أكثر أمانًا (بدون بوت تابع لجهة خارجية):
  • أرسل رسالة مباشرة إلى البوت، ثم شغّل openclaw logs --follow واقرأ from.id.
Bot API الرسمية:
  • أرسل رسالة مباشرة إلى البوت، ثم استدعِ https://api.telegram.org/bot<bot_token>/getUpdates واقرأ message.from.id.
جهة خارجية (أقل خصوصية):
  • أرسل رسالة مباشرة إلى @userinfobot أو @getidsbot.
راجع /channels/telegram.
نعم، عبر توجيه متعدد الوكلاء. اربط الرسالة المباشرة لكل مرسل في WhatsApp (نظير kind: "direct"، والمرسل بتنسيق E.164 مثل +15551234567) بـ agentId مختلف، بحيث يحصل كل شخص على مساحة عمل ومخزن جلسات خاصين به. ستظل الردود صادرة من حساب WhatsApp نفسه، ويكون التحكم في وصول الرسائل المباشرة (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) عامًا لكل حساب WhatsApp. راجع التوجيه متعدد الوكلاء وWhatsApp.
نعم. استخدم التوجيه متعدد الوكلاء: امنح كل وكيل نموذجه الافتراضي الخاص، ثم اربط المسارات الواردة (حساب المزود أو نظراء محددين) بكل وكيل. يوجد مثال إعداد في التوجيه متعدد الوكلاء. راجع أيضًا النماذج والإعدادات.
نعم. يدعم Homebrew نظام Linux (Linuxbrew). إعداد سريع:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>
إذا شغّلت OpenClaw عبر systemd، فتأكد من أن PATH الخاص بالخدمة يتضمن /home/linuxbrew/.linuxbrew/bin (أو بادئة brew الخاصة بك) حتى تُحل أدوات brew المثبتة في الصدف غير الخاصة بتسجيل الدخول. تضيف البنيات الحديثة أيضًا أدلة bin الشائعة للمستخدم في خدمات Linux systemd (على سبيل المثال ~/.local/bin، و~/.npm-global/bin، و~/.local/share/pnpm، و~/.bun/bin) وتحترم PNPM_HOME وNPM_CONFIG_PREFIX وBUN_INSTALL وVOLTA_HOME وASDF_DATA_DIR وNVM_DIR وFNM_DIR عند تعيينها.
  • تثبيت قابل للتعديل (git): نسخة كاملة من المصدر، قابلة للتحرير، والأفضل للمساهمين. تشغّل عمليات البناء محليًا ويمكنك تعديل الكود/الوثائق.
  • تثبيت npm: تثبيت CLI عالمي، بدون مستودع، والأفضل لمن يريد “تشغيله فقط”. تأتي التحديثات من وسوم توزيع npm.
الوثائق: بدء الاستخدام، التحديث.
نعم. استخدم openclaw update --channel ... عندما يكون OpenClaw مثبتًا بالفعل. هذا لا يحذف بياناتك - بل يغير تثبيت كود OpenClaw فقط. تظل حالتك (~/.openclaw) ومساحة عملك (~/.openclaw/workspace) دون تغيير.من npm إلى git:
openclaw update --channel dev
من git إلى npm:
openclaw update --channel stable
أضف --dry-run لمعاينة تبديل الوضع المخطط له أولًا. يشغّل المحدّث متابعات Doctor، ويحدّث مصادر Plugin للقناة المستهدفة، ويعيد تشغيل Gateway ما لم تمرر --no-restart.يمكن للمثبّت فرض أي من الوضعين أيضًا:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
نصائح النسخ الاحتياطي: راجع استراتيجية النسخ الاحتياطي.
الإجابة المختصرة: إذا أردت موثوقية 24/7، فاستخدم VPS. إذا أردت أقل قدر من التعقيد ولا تمانع السكون/إعادة التشغيل، فشغّله محليًا.الحاسوب المحمول (Gateway محلي)
  • الإيجابيات: لا تكلفة خادم، وصول مباشر إلى الملفات المحلية، نافذة متصفح حية.
  • السلبيات: السكون/انقطاع الشبكة = انقطاعات اتصال، تحديثات/إعادات تشغيل نظام التشغيل تقاطع العمل، يجب أن يبقى مستيقظًا.
VPS / السحابة
  • الإيجابيات: يعمل دائمًا، شبكة مستقرة، لا مشكلات نوم الحاسوب المحمول، أسهل في إبقائه قيد التشغيل.
  • السلبيات: غالبًا يعمل بلا واجهة مرئية (استخدم لقطات الشاشة)، الوصول إلى الملفات عن بُعد فقط، ويجب استخدام SSH للتحديثات.
ملاحظة خاصة بـ OpenClaw: تعمل WhatsApp/Telegram/Slack/Mattermost/Discord كلها بشكل جيد من VPS. المفاضلة الحقيقية الوحيدة هي متصفح بلا واجهة مرئية مقابل نافذة مرئية. راجع المتصفح.الإعداد الافتراضي الموصى به: VPS إذا واجهت انقطاعات في Gateway سابقًا. المحلي رائع عندما تستخدم Mac بنشاط وتريد الوصول المحلي إلى الملفات أو أتمتة واجهة المستخدم مع متصفح مرئي.
ليس مطلوبًا، لكنه موصى به للاعتمادية والعزل.
  • مضيف مخصص (VPS/Mac mini/Pi): يعمل دائمًا، انقطاعات أقل بسبب النوم/إعادة التشغيل، أذونات أنظف، وأسهل في إبقائه قيد التشغيل.
  • حاسوب محمول/مكتبي مشترك: مناسب تمامًا للاختبار والاستخدام النشط، لكن توقّع توقفات مؤقتة عندما يدخل الجهاز في وضع السكون أو يُحدَّث.
إذا أردت أفضل ما في الخيارين، فأبقِ Gateway على مضيف مخصص واقرن حاسوبك المحمول باعتباره Node لأدوات الشاشة/الكاميرا/التنفيذ المحلية. راجع Nodes. للحصول على إرشادات الأمان، اقرأ الأمان.
OpenClaw خفيف الوزن. للحصول على Gateway أساسي + قناة دردشة واحدة:
  • الحد الأدنى المطلق: 1 vCPU، ذاكرة RAM بسعة 1GB، قرص بسعة ~500MB.
  • الموصى به: 1-2 vCPU، ذاكرة RAM بسعة 2GB أو أكثر لهامش إضافي (السجلات، الوسائط، القنوات المتعددة). يمكن أن تكون أدوات Node وأتمتة المتصفح مستهلكة للموارد.
نظام التشغيل: استخدم Ubuntu LTS (أو أي Debian/Ubuntu حديث). مسار التثبيت على Linux هو الأفضل اختبارًا هناك.الوثائق: Linux، استضافة VPS.
نعم. تعامل مع VM مثل VPS: يجب أن يكون قيد التشغيل دائمًا، وقابلًا للوصول، ولديه ذاكرة RAM كافية لـ Gateway وأي قنوات تفعّلها.إرشادات الأساس:
  • الحد الأدنى المطلق: 1 vCPU، ذاكرة RAM بسعة 1GB.
  • الموصى به: ذاكرة RAM بسعة 2GB أو أكثر إذا كنت تشغّل قنوات متعددة، أو أتمتة المتصفح، أو أدوات الوسائط.
  • نظام التشغيل: Ubuntu LTS أو Debian/Ubuntu حديث آخر.
إذا كنت تستخدم Windows، فإن WSL2 هو أسهل إعداد بأسلوب VM ولديه أفضل توافق مع الأدوات. راجع Windows، استضافة VPS. إذا كنت تشغّل macOS في VM، فراجع macOS VM.

​
ذو صلة