تثبيت OpenClaw على Raspberry Pi مع Docker: دليل شامل

ربما اصطدمت بنفس العقبات التي واجهتها مع Raspberry Pi: حاويات (Containers) تتوقف عن العمل بعد إعادة التشغيل، مشاكل غامضة في صور ARM، و"بوابة" (Gateway) كشفتها للإنترنت عن طريق الخطأ. هذا الدليل يشرح إعداد OpenClaw (المعروف سابقاً باسم Clawdbot/MoltBot) على Raspberry Pi باستخدام Docker Compose لضمان عمله بعد إعادة التشغيل، وتحديثه بسلاسة، وبقائه خاصاً وآمناً بشكل افتراضي.

المتطلبات الأساسية (لنبقِ الأمور بسيطة وصحيحة)

• نظام Raspberry Pi OS 64-bit (يُفضل نسخة Bookworm)، مع صلاحية SSH و sudo.
• جهاز Raspberry Pi 4 أو 5 بذاكرة عشوائية (RAM) 4 جيجابايت كحد أدنى (8 جيجابايت أفضل لأداء أسلس)، ويُفضل بشدة استخدام SSD للتشغيل المستمر 24/7.
• Docker Engine + إضافة Docker Compose (سنقوم بتثبيتهما أدناه).
• مفتاح مزود ذكاء اصطناعي واحد: OPENAI_API_KEY أو ANTHROPIC_API_KEY.
• خطة للوصول الخاص: عبر الشبكة المحلية (LAN) فقط، أو VPN، أو نفق (Tunnel) - لا تعرض البوابة للإنترنت مباشرة.

الخطوة 1: تجهيز Raspberry Pi لتشغيل Docker بشكل دائم

bashCopy
sudo apt update
sudo apt -y full-upgrade
sudo reboot

من واقع تجربتي، هذا ما يمنع الكثير من أعطال الحاويات "العشوائية": النواة القديمة (Kernels)، عدم تطابق cgroups، والمكتبات القديمة، وكل تلك الفوضى. تحديثات Raspberry Pi OS تتضمن أيضاً إصلاحات للشبكة ونظام الملفات، وهي أمور مهمة جداً للأجهزة التي تعمل طوال الوقت.

بعد إعادة التشغيل، تأكد من أنك تعمل على نظام 64-بت:

bashCopy
uname -m
getconf LONG_BIT

إذا أظهر الأمر uname -m النتيجة aarch64 وكانت LONG_BIT هي 64، فأنت جاهز. إذا لم يكن الأمر كذلك، انتقل إلى Raspberry Pi OS 64-bit قبل المتابعة. الصور متعددة المعماريات (Multi-arch images) وإدارة الذاكرة أفضل بكثير في نظام 64-بت (وستوفر على نفسك وقتاً طويلاً لاحقاً).

خطوة اختيارية لكنها تستحق العناء: تقليل استهلاك بطاقة SD

bashCopy
sudo apt -y install smartmontools
lsblk

تشغيل OpenClaw على مدار الساعة يكتب الكثير من السجلات والبيانات. تتعامل أقراص SSD مع هذا الأمر بشكل أفضل بكثير من بطاقات SD. إذا كنت مضطراً لاستخدام SD، فاحرص على إبقاء السجلات صغيرة وقم بتدويرها (سنفعل ذلك لاحقاً عبر خيارات Docker logging).

الخطوة 2: تثبيت Docker و Docker Compose على Raspberry Pi OS

bashCopy
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
newgrp docker

يقوم سكربت get.docker.com بتثبيت نسخة Docker تتوافق عادةً بشكل جيد مع Raspberry Pi OS. إضافة المستخدم الخاص بك إلى مجموعة docker يعني أنك لن تضطر لكتابة sudo في كل مكان، مما يساعد أيضاً في تجنب مفاجآت الصلاحيات الغريبة عند استخدام الـ Bind Mounts.

ثبّت إضافة Compose والأدوات الأساسية:

bashCopy
sudo apt -y install docker-compose-plugin git jq
docker --version
docker compose version

إذا طبع الأمر docker compose version رقم إصدار، فهذا يعني أن لديك إضافة Compose الحديثة (وهذا ما تريده، وليس ملف بايثون docker-compose القديم).

الخطوة 3: إنشاء مجلد عمل نظيف لـ OpenClaw

bashCopy
mkdir -p ~/openclaw
cd ~/openclaw

لا شيء معقد هنا. الاحتفاظ بكل شيء في مجلد واحد يجعل التحديثات والنسخ الاحتياطي أمراً سهلاً. الهدف هو الحصول على حزمة قابلة لإعادة الإنتاج: ملف Compose، ملف .env، ومجلد بيانات دائم.

الخطوة 4: كتابة ملف Docker Compose آمن للـ Pi وقابل للتحديث

أنشئ ملف docker-compose.yml:

yamlCopy
services:
  openclaw:
    image: openclawai/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    
    # Default to LAN-only access. Change only if you have a VPN/tunnel/reverse proxy.
    ports:
      - "127.0.0.1:18789:18789"
    
    env_file:
      - .env
    
    volumes:
      - ./data:/var/lib/openclaw
      - ./logs:/var/log/openclaw
    
    # Keeps container logs from eating your SD/SSD over time
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    
    # Helps on small devices: prevents runaway memory from killing the Pi
    mem_limit: 1500m

يقوم إعداد Compose هذا بثلاثة أشياء تمنع -حسب ما رأيت- أكثر أعطال Raspberry Pi شيوعاً.

ربط المنفذ 18789 بـ 127.0.0.1 يبقي البوابة خاصة (لا تتجاوز هذه الخطوة). تعريضها للشبكة الخارجية (WAN) هو أسرع طريقة للتعرض للاختراق، وتحديثات الأمان لعام 2026 حدثت لسبب وجيه. استخدام الـ Bind Mounts للمسارين ./data و ./logs يضمن بقاء البيانات بعد إعادة بناء الحاوية وتحديث الصور. وتدوير السجلات (Log rotation) يمنع "الموت البطيء" لوحدة التخزين بسبب ملايين عمليات الكتابة الصغيرة.

ماذا لو كان اسم الصورة مختلفاً في وثائقك؟

تشير بعض الأدلة إلى أسماء صور Clawdbot/MoltBot القديمة. إذا فشل السحب، تحقق من وثائق نشر Docker الرسمية وقم بتحديث سطر image: وفقاً لذلك: Docker Deployment Guide - Clawdbot AI. قارن أيضاً مع نهج Compose الموضح هنا: Running OpenClaw in Docker.

الخطوة 5: إضافة ملف env مع الرموز ومفاتيح الذكاء الاصطناعي

أنشئ ملف .env:

bashCopy
cd ~/openclaw
nano .env

الصق وعدّل التالي:

bashCopy
## OpenClaw gateway settings
OPENCLAW_GATEWAY_PORT=18789

# Generate a strong token. Do not reuse passwords.
OPENCLAW_GATEWAY_TOKEN=[PASTE_LONG_RANDOM_TOKEN]

# Choose one provider (or both if supported by your build)
OPENAI_API_KEY=[YOUR_OPENAI_KEY]
ANTHROPIC_API_KEY=[YOUR_ANTHROPIC_KEY]

# Optional: keep the bot predictable on a small device
OPENCLAW_MAX_CONCURRENCY=2
OPENCLAW_LOG_LEVEL=info

مكان الرموز ومفاتيح API هو ملف .env، لأن ذلك يبقي الأسرار بعيدة عن ملف Compose ويجعل التحديثات أكثر أماناً. وعندما تقوم بنسخ احتياطي لملف docker-compose.yml، يمكنك ترك .env خارج النسخة (أو حفظه في مدير كلمات المرور).

قم بتوليد رمز قوي:

bashCopy
openssl rand -hex 32

الصق هذا الناتج في OPENCLAW_GATEWAY_TOKEN. بصراحة، الرمز العشوائي الطويل أهم مما يتوقعه الناس لأن البوابات تتعرض للمسح الآلي حتى على الشبكات المنزلية (نعم، حقاً).

الخطوة 6: تشغيل OpenClaw باستخدام Docker Compose

bashCopy
cd ~/openclaw
docker compose pull
docker compose up -d
docker compose ps

الأمر pull يفرض تنزيل صورة نظيفة لمعالجات ARM. الأمر up -d يبدأ التشغيل في الخلفية. الأمر ps يظهر ما إذا كانت الحاوية سليمة أو عالقة في حالة إعادة التشغيل.

تحقق من السجلات فوراً:

bashCopy
docker logs -n 200 openclaw

إذا كان OpenClaw يتطلب معالج إعداد أولي (Onboarding Wizard)، فستظهر السجلات عادةً الرابط الأول لفتحه، أو رموز الاقتران، أو المتغيرات البيئية المفقودة. قم بحل هذه الأمور قبل المتابعة، لأن عبارة "إنه يعمل لكن لا يفعل شيئاً" غالباً ما تعني مشكلة في الإعداد الأولي أو الرموز.

الخطوة 7: الوصول للبوابة بأمان (عبر الشبكة المحلية فقط افتراضياً)

من جهاز Raspberry Pi نفسه:

bashCopy
curl -sS http://127.0.0.1:18789/ | head

من جهاز آخر على شبكتك المحلية (LAN)، لديك خياران آمنان.

الخيار أ: إعادة توجيه منفذ SSH (الأسرع، ولا يتطلب تغييرات في الشبكة):

bashCopy
ssh -L 18789:127.0.0.1:18789 pi@[RASPBERRY_PI_IP]

ثم افتح هذا الرابط محلياً:

bashCopy
http://127.0.0.1:18789

الخيار ب: الربط بـ IP الشبكة المحلية فقط (لا يزال خاصاً، لكن يمكن الوصول إليه عبر الشبكة المحلية). غيّر ports: في ملف Compose إلى:

yamlCopy
ports:
  - "[RASPBERRY_PI_LAN_IP]:18789:18789"

عادةً ما يكون إعادة توجيه SSH هو الأقل عرضة للأخطاء لأنه لا يعرض الخدمة للشبكة الفرعية بالكامل. الربط بالشبكة المحلية (LAN bind) جيد إذا كانت الشبكة موثوقة ومجزأة (وتعرف ما هي الأجهزة الأخرى الموجودة على تلك الشبكة).

الخطوة 8: جعل التحديثات متوقعة (وقابلة للتراجع)

سير عمل التحديث:

bashCopy
cd ~/openclaw
docker compose pull
docker compose up -d
docker image prune -f

يقوم هذا بسحب أحدث صورة، وإعادة إنشاء الحاوية، وإزالة الصور القديمة لتوفير المساحة. ولأن الحالة محفوظة في ./data، فإن التحديثات لا تمسح إعداداتك أو سجلك.

للحصول على تحديث قابل للتراجع، قم بتثبيت إصدار محدد (Pinning) بدلاً من latest:

yamlCopy
image: openclawai/openclaw:2026.1.3

تثبيت الإصدار أمر ممل، وهذا بالضبط سبب نجاحه. على جهاز Raspberry Pi يعمل 24/7، التغييرات المفاجئة هي السبب الأول لتوقف الخدمة.

الخطوة 9: إضافة حماية أساسية للمضيف (Host) ذات تأثير حقيقي

ثبّت وفعّل جدار الحماية:

bashCopy
sudo apt -y install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable
sudo ufw status verbose

هذا يمنع حركة المرور الواردة باستثناء SSH. نظراً لأن OpenClaw مرتبط بـ localhost في Compose، فأنت بالفعل في وضع جيد، لكن جدار الحماية يظل مفيداً إذا قام شخص ما لاحقاً بتعديل ارتباطات المنافذ (أنت في المستقبل).

أضف Fail2ban للتعامل مع محاولات تخمين كلمات مرور SSH:

bashCopy
sudo apt -y install fail2ban
sudo systemctl enable --now fail2ban
sudo fail2ban-client status

تغطي هاتان الخطوتان أكثر طرق اختراق Pi المنزلية شيوعاً: SSH مكشوف بكلمات مرور ضعيفة. بالنسبة لأمن Docker وحواجز الحماية، تنطبق نفس المبادئ المذكورة في دليلنا Claude Code 2026 Best Practices: Guardrails & Tests: قيد مسارات الوصول أولاً، ثم أضف الأتمتة.

الخطوة 10: المهارات والإضافات دون تحويل الـ Pi إلى "مدفأة"

ابدأ بقائمة منتقاة حتى لا تثبت حزماً عشوائية بشكل أعمى:

• VoltAgent/awesome-openclaw-skills

القيد العملي في Raspberry Pi ليس "هل يمكنه التشغيل" بل "هل يمكنه التشغيل مع البقاء مستجيباً". المهارات التي تقوم بمسح صفحات الويب، أو تشغيل متصفحات بلا واجهة (Headless browsers)، أو إنشاء الكثير من العمليات الفرعية ستستنزف موارد الجهاز.

وإليك الفكرة: النمط الجيد هو إبقاء OpenClaw على الـ Pi، ولكن نقل الأدوات الثقيلة إلى جهاز آخر عبر SSH أو HTTP. اعتبر الـ Pi منسقاً دائماً للعمل، وليس وحدة المعالجة الرئيسية.

اختبار الإعداد الخاص بك

شغل هذه الاختبارات بالترتيب. فهي تكشف الإخفاقات الحقيقية: الـ Mounts الخاطئة، الرموز السيئة، ومشاكل الشبكة.

الاختبار 1: صحة الحاوية وإعادة التشغيل

bashCopy
docker compose ps
docker inspect -f '{{.State.Status}} {{.State.Restarting}}' openclaw

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

الاختبار 2: الاستمرارية عبر إعادة إنشاء الحاوية

bashCopy
cd ~/openclaw
docker compose down
docker compose up -d
ls -la ./data

إذا بقي المجلد ./data ممتلئاً، فلديك استمرارية حقيقية. إذا كان فارغاً أو مملوكاً لـ root بشكل غير متوقع، أصلح الصلاحيات. إصلاح شائع:

bashCopy
sudo chown -R $USER:$USER ~/openclaw/data ~/openclaw/logs

الاختبار 3: انكشاف المنفذ خاص

bashCopy
ss -lntp | grep 18789 || true

إذا رأيت 0.0.0.0:18789، فقد كشفته للعموم. أعده إلى 127.0.0.1:18789 إلا إذا كان لديك VPN أو مصادقة بروكسي عكسي صارمة.

الاختبار 4: قراءة مفتاح مزود الذكاء الاصطناعي

bashCopy
docker exec -it openclaw /bin/sh -lc 'env | egrep "OPENAI_API_KEY|ANTHROPIC_API_KEY|OPENCLAW_" | sed "s/=.*/=REDACTED/"'

إذا كانت المفاتيح مفقودة، فإن ملف .env لا يتم تحميله أو به مشاكل في التنسيق. الخطأ الأكثر شيوعاً هو وجود مسافات حول = أو نسخ علامات اقتباس ذكية (Smart quotes) من تطبيق ملاحظات (حدث معي سابقاً).

استكشاف الأخطاء وإصلاحها للمشاكل التي تحدث فعلياً على Raspberry Pi

"no matching manifest for linux/arm/v7"

bashCopy
uname -m
docker pull openclawai/openclaw:latest

إذا كان الـ Pi يعمل بنظام 32-بت (armv7l)، فإن العديد من الصور لن تدعمه. انتقل إلى Raspberry Pi OS 64-bit. إذا كنت بالفعل على 64-بت ولكن لا تزال تفشل، فقد لا تكون الصورة متعددة المعماريات. تأكد من وثائق Docker الرسمية: Docker Deployment Guide - Clawdbot AI.

الحاوية تبدأ، ثم تخرج فوراً

bashCopy
docker logs -n 300 openclaw
docker inspect openclaw --format '{{json.State}}' | jq

الخروج عند البدء عادة ما يكون بسبب أحد هذه الأمور: رمز بوابة مفقود، مفتاح مزود مفقود، أو مجلد مطلوب غير قابل للكتابة. أصلح .env أولاً، ثم تحقق من صلاحيات ./data.

"bind: address already in use" على المنفذ 18789

bashCopy
sudo ss -lntp | grep 18789
docker compose down

عملية أخرى تستخدم هذا المنفذ بالفعل، أو حاوية سابقة لا تزال تعمل. أوقف الحاوية القديمة. إذا كان يجب عليك تغيير المنافذ، فقم بتغيير كل من تعيين منفذ المضيف (Host port mapping) وأي عناوين URL للعميل.

يصبح الـ Pi بطيئاً أو غير مستجيب بعد تفعيل عدة مهارات

bashCopy
docker stats --no-stream
vcgencmd measure_temp

عندما يزداد ضغط الذاكرة (RAM)، سيبدأ Linux في استخدام الـ Swap وسيبدو كل شيء معطلاً. قلل التزامن (Concurrency) في .env، وحافظ على mem_limit، وأزل المهارات الثقيلة. إذا كنت بحاجة إلى أتمتة المتصفح، شغلها على جهاز منفصل واستدعها من الـ Pi.

مخاوف أمنية بشأن البوابة بعد القراءة عن حوادث 2026

اقرأ التوجيهات التي تركز على الحوادث: OpenClaw Complete Guide 2026. الخلاصة العملية بسيطة: ربط خاص (Private bind) بشكل افتراضي، رمز قوي دائماً، وتجنب أوضاع "بدون مصادقة" إذا رأيتها في الشروحات القديمة.

نهج "Docker أولاً" على Pi: لماذا تعتمد الفرق هذا النمط

يحظى Docker Compose بشعبية هنا لأنه يوفر عمليات نشر قابلة للتكرار مع مساحة تشغيلية صغيرة. هذا مهم على أجهزة الحافة (Edge devices) حيث يكون "الإصلاح المباشر" مؤلماً (وغالباً ما يحدث في أسوأ الأوقات).

إليك مقارنة بين المقايضات لعمليات النشر على Raspberry Pi:

أنماط الحاويات في الشركات الكبرى تنطبق بشكل مدهش على الـ Pi. أبلغت Netflix عن انخفاض بنسبة 50% في الحوادث المتعلقة بالنشر بعد نقل الخدمات إلى صور حاويات غير قابلة للتغيير (Immutable) مع خطوط أنابيب موحدة (مراجع Netflix TechBlog عبر عدة منشورات). وصفت Stripe كيف تقلل حدود العزل القوية وعمليات النشر القابلة للتكرار من انحراف "يعمل على جهازي" في أنظمة الإنتاج. نشرت Shopify دراسات حالة متعددة تظهر أن أدوات البناء والإصدار المتسقة تقلل وقت التراجع (Rollback) أثناء الحوادث.

تلك أمثلة لشركات ضخمة، لكن نفس الآليات تنطبق على Raspberry Pi: تبعيات فريدة (Snowflake) أقل، تراجع أوضح، وحفظ الحالة خارج الحاوية.

قائمة التحقق للنشر

ابدأ من هنا (خطوتك الأولى)

أنشئ ~/openclaw/docker-compose.yml مع 127.0.0.1:18789:18789 وتركيب دائم لـ ./data.

مكاسب سريعة (تأثير فوري)

• قم بتوليد وتعيين OPENCLAW_GATEWAY_TOKEN باستخدام openssl rand -hex 32، ثم أعد التشغيل باستخدام docker compose up -d.
• تأكد من أنك لم تعرض البوابة: شغل ss -lntp | grep 18789 وتحقق من أنها مرتبطة بـ 127.0.0.1.

تعمق أكثر (لمن يريد المزيد)

• ثبت وسم الصورة (مثال 2026.1.3) ووثق تسلسل أوامر التحديث في ملف RUNBOOK.md.
• أضف UFW + Fail2ban، ثم اختبر الوصول عن بعد من خلال إعادة توجيه منفذ SSH بدلاً من فتح المنافذ.

مصادر مفيدة

• Running OpenClaw in Docker - شرح Compose مع المجلدات وملاحظات الإعداد الأولي.
• Docker Deployment Guide - Clawdbot AI - المرجع الرسمي لنشر Docker و Compose.
• OpenClaw Complete Guide 2026 - التغييرات الأمنية والملاحظات التشغيلية من إصدارات 2026.
• OpenClaw Complete Guide (Formerly Moltbot/ClawdBot) - سياق إعادة التسمية، سير الإعداد، وملاحظات النظام البيئي.
• VoltAgent/awesome-openclaw-skills - دليل مهارات منتقى لاكتشاف إضافات أكثر أماناً.

أفكار ختامية

يمكن لـ Raspberry Pi تشغيل OpenClaw بموثوقية، ولكن فقط إذا بقيت البوابة خاصة، وكانت البيانات على تخزين دائم، وتم التعامل مع التحديثات كعملية قابلة للتكرار. Docker Compose هو أبسط طريقة للحصول على هذه الخصائص دون تحويل الـ Pi الخاص بك إلى "ندفة ثلج" هشة.

بمجرد استقرار الحزمة الأساسية، أضف المهارات ببطء وانقل العمل الثقيل إلى أجهزة أخرى بدلاً من إجبار الـ Pi على فعل كل شيء. لنكن واقعيين: الـ Pi الذي يحاول فعل كل شيء ينتهي به الأمر بعدم فعل أي شيء بشكل جيد.