تشغيل OpenClaw على Raspberry Pi باستخدام Docker: الدليل العملي

معظم الأدلة والشروحات تجعل هذا الأمر معقداً أكثر من اللازم. لقد قمت بإعداد هذا النظام عدة مرات، وإليك نهج Raspberry Pi العملي والمنطقي: تشغيل OpenClaw (Clawbot) داخل Docker مع تخزين دائم (Persistent Storage)، وتقليل التعرض للشبكة افتراضياً، وتحديثات يمكنك تكرارها دون مفاجآت. إذا كنت تريد وكيلاً ذكياً (Agent) يعمل على مدار الساعة طوال أيام الأسبوع دون العبث بجهازك الأساسي، فهذا هو المسار الأنظف عادةً.

أسرع إعداد فعال (Docker Compose على Raspberry Pi)

yamlCopy
## docker-compose.yml
services:
  openclaw:
    image: ghcr.io/[UPSTREAM_OR_COMMUNITY]/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "127.0.0.1:18789:18789"
    environment:
      - TZ=UTC
      - OPENCLAW_PORT=18789
      - OPENCLAW_DATA_DIR=/data
    volumes:
      - openclaw-data:/data
      - /etc/localtime:/etc/localtime:ro
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

volumes:
  openclaw-data:

يتعامل ملف Compose هذا بهدوء مع ثلاثة أمور "واقعية" تتجاهلها معظم الشروحات:

• يربط البوابة (Gateway) بـ 127.0.0.1 بحيث لا تكون مكشوفة لشبكتك المحلية (LAN) أو الإنترنت بشكل افتراضي، وهو بالضبط ما تريده في البداية.
• يستخدم وحدة تخزين مسماة (Named Volume) openclaw-data لضمان بقاء حالة الإعداد، وتكوين المهارات، والرموز (Tokens) حتى بعد إعادة التشغيل.
• يقوم بتدوير السجلات (Log Rotation) لتجنب تلف بطاقة SD بسبب سجلات JSON غير المحدودة (نعم، لقد رأيت ذلك يحدث).

قم بتشغيله:

bashCopy
docker compose up -d
docker compose logs -f openclaw

إذا بدأت الحاوية (Container) واستمرت في العمل، فأنت جاهز لمرحلة الإعداد وربط القنوات.

المتطلبات الأساسية التي تهمك فعلاً على Raspberry Pi

bashCopy
## Raspberry Pi OS (Debian) quick prep
sudo apt-get update
sudo apt-get install -y ca-certificates curl git

# Docker Engine install (official script)
curl -fsSL https://get.docker.com | sudo sh

# Allow your user to run docker without sudo
sudo usermod -aG docker $USER
newgrp docker

# Docker Compose v2 is included with modern Docker packages
docker version
docker compose version

الحد الأدنى من العتاد لتجنب المشاكل (إليك الأمر بوضوح: يمكنك استخدام مواصفات أقل، لكنك ستشعر بتأثير ذلك):

• Raspberry Pi 4 أو 5.
• ذاكرة 4GB RAM كحد أدنى للوكيل والمهارات. ذاكرة 8GB تجعل الأداء أسلس بشكل ملحوظ بمجرد تشغيل أكثر من شيء في وقت واحد.
• قرص SSD جيد (USB 3) أكثر أماناً من بطاقة microSD للكتابة المستمرة على مدار الساعة.

لماذا يهم هذا؟ تميل الوكلاء من نوع OpenClaw إلى كتابة الحالة (State)، وتخزين المطالبات مؤقتاً، وتسجيل استدعاءات الأدوات. بطاقات SD يمكن أن تتلف -وتتلف فعلاً- مبكراً تحت ضغط الكتابة المستمر.

مسار التثبيت أ: استخدام نص إعداد Docker الخاص بالمستودع (الأكثر قابلية للتكرار)

bashCopy
git clone [REPO_URL]
cd [REPO_DIR]

# Common pattern in guides: a helper script
chmod +x docker-setup.sh
./docker-setup.sh

تأتي العديد من أدلة ونسخ OpenClaw مع نص إعداد (Script) يقوم بسحب/بناء الصور، وكتابة ملف .env، وتشغيل Compose. من واقع خبرتي، يميل هذا أيضاً إلى التوافق مع افتراضات المطورين الأصليين (مثل إصدار Node.js الذي يتوقعونه داخل الحاوية)، مما يوفر عليك مشاكل توافق Node.js 22+ على مستوى النظام المضيف.

إذا طلب النص تحديد المنافذ، أنصحك بإبقاء البوابة على 18789 إلا إذا كان لديك شيء آخر يعمل هناك. للحصول على تدفق إعداد Docker كامل (مفاتيح API + قائمة المهارات)، راجع شرح الإعداد على YouTube: https://www.youtube.com/watch?v=-aeR1cQktdM

مسار التثبيت ب: البناء محلياً على Pi (عندما تتأخر الصور الجاهزة)

bashCopy
git clone [REPO_URL]
cd [REPO_DIR]

# Typical Docker build flow
docker build -t openclaw:pi .

# Run with a persistent data directory
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 127.0.0.1:18789:18789 \
  -e OPENCLAW_DATA_DIR=/data \
  -v openclaw-data:/data \
  openclaw:pi

يساعد البناء المحلي في الحالات التالية:

• الصورة الأصلية متوفرة لـ amd64 فقط وأنت بحاجة لـ arm64.
• المشروع يتغير بسرعة وتتأخر وسوم السجل (Registry Tags) عن التحديث.
• تحتاج إلى تعديل (Patch) إحدى التبعيات لتتوافق مع ARM (يحدث هذا أحياناً).

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

الإعداد داخل الحاوية (معالج بدون تخمين)

bashCopy
# Open a shell in the running container
docker exec -it openclaw sh

تتم خطوات الإعداد الشائعة داخل الحاوية:

• إضافة مفاتيح مزود LLM (مثل OpenAI، Anthropic، إلخ).
• تعيين النموذج الافتراضي.
• تفعيل قنوات مثل Telegram أو Discord.
• تأكيد مكان تخزين البيانات (توجيهها إلى /data).

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

bashCopy
## Example pattern: start wizard or open dashboard
openclaw wizard
openclaw gateway --port 18789

إذا لم ترَ هذه الأوامر، تحقق من مساعدة الحاوية (في الواقع: تحقق من أسماء متعددة، لأن النسخ المعدلة تحب تغيير أسماء الملفات التنفيذية):

bashCopy
openclaw --help || clawbot --help || ls -la

المفهوم الأساسي: يجب أن يكتب الإعداد حالته داخل وحدة التخزين المثبتة (/data). إذا قمت بالإعداد بدون وحدة تخزين دائمة، فستقوم بإعادة الإعداد بالكامل بعد كل عملية إعادة بناء.

ربط Telegram الذي يحافظ على الأمان (تدفق الموافقة)

bashCopy
## Example approve command pattern found in Docker walkthroughs
docker compose run --rm openclaw-cli pairing approve telegram [CODE]

يحظى Telegram بشعبية لأنه منخفض التأخير (Low-latency) ويناسب تماماً طبيعة "الوكيل الذي يعمل في الخلفية". خطوة الموافقة على الربط موجودة لسبب وجيه: فهي تمنع الحسابات العشوائية من التحكم في وكيلك إذا عثروا على البوت الخاص بك بالصدفة.

القواعد التشغيلية لتقليل المخاطر (هذه هي القواعد المملة التي تنقذك لاحقاً):

• حافظ على ربط البوابة بـ 127.0.0.1.
• اكشف فقط عن وكيل عكسي (Reverse Proxy) مع مصادقة إذا كنت تحتاج حقاً إلى وصول عن بعد.
• قم بتغيير رموز البوت (Tokens) إذا قمت بلصقها في السجلات أو لقطات الشاشة.

تتضمن ملاحظات Simon Willison تدفق الربط والوصول إلى لوحة التحكم: https://til.simonwillison.net/llms/openclaw-docker

كشف البوابة بأمان (LAN فقط، Tailscale، أو وكيل عكسي)

الخيار 1: الكشف للشبكة المحلية فقط (لا يزال غير "آمن افتراضياً")

yamlCopy
# docker-compose.yml snippet
ports:
  - "192.168.1.50:18789:18789"

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

الخيار 2: استخدام Tailscale (وصول خاص عن بعد)

bashCopy
## Install Tailscale on the Pi (official docs recommended)
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

ثم اترك Compose على 127.0.0.1 وادخل إليه عبر Tailscale. مما رأيته، هذا هو أبسط نهج "عن بعد ولكن خاص" لأنك لست مضطراً لفتح منافذ في الراوتر.

الخيار 3: وكيل عكسي مع مصادقة أساسية (عند الحاجة للوصول عبر المتصفح)

nginxCopy
# /etc/nginx/sites-available/openclaw.conf
server {
    listen 443 ssl;
    server_name [YOUR_DOMAIN];

    location / {
        auth_basic "Restricted";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

إذا قمت بكشف OpenClaw عبر Nginx، أضف TLS والمصادقة. فكر أيضاً في قوائم السماح لعناوين IP - إنه عمل إضافي، لكنه يستحق العناء.

وحدات التخزين الدائمة بالطريقة الصحيحة (الحالة، المهارات، والتراجع الآمن)

bashCopy
## See where Docker stored your named volume
docker volume inspect openclaw-data

# Backup the entire volume to a tarball
docker run --rm \
  -v openclaw-data:/data \
  -v "$PWD":/backup \
  alpine sh -c "cd /data && tar -czf /backup/openclaw-data.tgz ."

النسخ الاحتياطي لوحدات التخزين هو الفرق بين "إعادة البناء في دقيقتين" و"إعادة الإعداد لمدة ساعة". كما أنها تجعل الترقيات أقل توتراً لأنه يمكنك التراجع بسرعة.

نمط عملي للتراجع (Rollback):

bashCopy
# Stop the service
docker compose down

# Restore volume from backup
docker run --rm \
  -v openclaw-data:/data \
  -v "$PWD":/backup \
  alpine sh -c "rm -rf /data/* && tar -xzf /backup/openclaw-data.tgz -C /data"

# Start again
docker compose up -d

تحسين أداء Raspberry Pi الذي يغفل عنه الكثيرون

bashCopy
## Check memory pressure and swap usage
free -h
vmstat 1

# Check container CPU and memory live
docker stats

ثلاثة تغييرات تهم استقرار Pi (إذا كنت ستفعل القليل فقط، فافعل هذه):

• استخدم SSD لـ /var/lib/docker ووحدات التخزين. Docker يكتب كثيراً.
• حافظ على تدوير السجلات مفعلاً. تسجيل JSON الافتراضي ينمو بلا حدود.
• حدد التزامن (Concurrency). إذا كان OpenClaw يسمح لك بوضع حد أقصى لتشغيل الأدوات المتوازي، فافعل ذلك.

إذا بدأ Pi في استخدام الذاكرة البديلة (Swap) أثناء تشغيل الوكيل، فسترتفع أزمنة الاستجابة (Latency). ستلاحظ ذلك كبطء في تنفيذ المهارات وانتهاء مهلة الاتصال في مكالمات الويب.

سير عمل المهارات: التثبيت، الاختبار، وتقييد نطاق التأثير

bashCopy
# Example pattern: list skills and enable one
openclaw skills list
openclaw skills enable [SKILL_NAME]

# Run a single skill test (dry run if supported)
openclaw skills run [SKILL_NAME] --dry-run

المهارات هي المكان الذي يصبح فيه OpenClaw مفيداً ومحفوفاً بالمخاطر في آن واحد. المهارة التي يمكنها كتابة الملفات، أو استدعاء Webhooks، أو الوصول إلى جسر أتمتة المنزل تحتاج إلى حدود - وإلا فأنت تمنحها مفاتيح منزلك حرفياً.

ثلاثة قيود تعمل بشكل جيد في Docker:

1. قم بتركيب (Mount) مجلد عمل مخصص، وليس مجلد المنزل (Home) بالكامل.
2. استخدم تركيبات للقراءة فقط (Read-only) للبيانات المرجعية.
3. استخدم متغيرات البيئة بأسلوب القائمة البيضاء (Allowlist) للأسرار.

مثال: تركيب مجلد عمل فقط:

yamlCopy
## docker-compose.yml snippet
volumes:
  - openclaw-data:/data
  - /home/pi/openclaw-workspace:/workspace

environment:
  - OPENCLAW_WORKSPACE=/workspace

للحصول على قائمة منسقة من مهارات المجتمع، استخدم مجموعة GitHub هذه: https://github.com/VoltAgent/awesome-openclaw-skills

ملاحظة داخلية: إذا كنت لا تزال تقرر ما إذا كان الوكيل يستحق التشغيل على مدار الساعة، راجع Clawdbot AI Agent: What It Is & Why It Matters.

مشاكل شائعة على Pi (وحلول فعالة)

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

bashCopy
docker compose ps
docker compose logs --tail=200 openclaw

الحلول التي تنطبق عادةً:

• نقص في متغيرات البيئة المطلوبة (مفتاح LLM غير مضبوط).
• دليل البيانات غير قابل للكتابة (مشكلة في أذونات تركيب وحدة التخزين).
• صورة بمعمارية خاطئة (سحب amd64 على arm64).

إذا كان عدم تطابق في المعمارية، تأكد من ذلك:

bashCopy
uname -m
docker image inspect [IMAGE] --format '{{.Architecture}}'

البوابة تعمل محلياً ولكن ليس من جهاز آخر

bashCopy
# Check what address it is bound to
ss -lntp | grep 18789

إذا كانت مرتبطة بـ 127.0.0.1، فلن تقبل حركة مرور الشبكة المحلية. هذا مقصود للأمان. إذا كنت بحاجة إلى وصول LAN، اربطها بـ IP محلي كما هو موضح سابقاً.

اختفاء الحالة بعد التحديثات

bashCopy
docker compose down
docker volume ls | grep openclaw

يحدث هذا عادة عندما:

• قمت بالإعداد قبل إضافة وحدات التخزين (خطأ سهل الوقوع فيه).
• استخدمت تركيبات ربط (Bind Mounts) تشير إلى مسار تغير لاحقاً.
• قام نص برمجي بإعادة إنشاء اسم مشروع Compose واسم وحدة التخزين.

الحل القياسي: استخدم وحدات تخزين مسماة وحافظ على استقرار اسم مشروع Compose. وبالتأكيد، احتفظ بنسخة احتياطية مضغوطة من وحدة التخزين.

بوت Telegram يقترن لكن لا يفعل شيئاً

bashCopy
# Look for channel handler errors
docker compose logs --tail=300 openclaw | grep -i telegram

الأسباب الشائعة:

• لم تتم الموافقة على الاقتران (لم يتم تشغيل pairing approve telegram [CODE]).
• رمز البوت (Token) خاطئ.
• تمت إضافة البوت إلى مجموعة لكنه يفتقر إلى الصلاحيات.

إذا كنت بحاجة إلى أساس آمن لـ Pi قبل البدء بـ Telegram والمهارات، راجع OpenClaw (Clawdbot) on Raspberry Pi: Safe Setup Guide.

استراتيجية الترقية: وسوم مستقرة، حاوية كناري، وتراجع سريع

bashCopy
## Pull latest image and restart
docker compose pull
docker compose up -d

# Confirm version and health
docker compose logs --tail=100 openclaw
docker exec -it openclaw sh -c "openclaw --version || clawbot --version"

نمط أكثر أماناً من استخدام "latest" (وبصراحة، هذا ما سأفعله إذا كان وقت التشغيل مهماً):

• تشغيل openclaw-stable مثبت على وسم (Tag) معروف.
• تشغيل openclaw-canary على أحدث وسم لمدة يوم.
• ترقية النسخة المستقرة إلى الكناري بعد أن تنجو من أعباء العمل الحقيقية.

مثال لخدمة الكناري:

yamlCopy
services:
  openclaw-stable:
    image: ghcr.io/[UPSTREAM_OR_COMMUNITY]/openclaw:[PINNED_TAG]
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - openclaw-stable-data:/data

  openclaw-canary:
    image: ghcr.io/[UPSTREAM_OR_COMMUNITY]/openclaw:latest
    ports:
      - "127.0.0.1:28789:18789"
    volumes:
      - openclaw-canary-data:/data

volumes:
  openclaw-stable-data:
  openclaw-canary-data:

هذا يعزل الحالة أيضاً. إذا أفسدت نسخة الكناري التكوين، تظل النسخة المستقرة نظيفة.

Docker مقابل التثبيت الأصلي على Pi (جدول القرار)

عادةً ما يكون Docker هو الحل الوسط: مستقر بما يكفي لمهام الوكيل طويلة الأمد، ولكنه لا يزال سهل إعادة البناء.

نقاط مرجعية من العالم الحقيقي (نتائج قابلة للقياس)

حققت Netflix انخفاضاً بنسبة 50% في تكاليف التخزين من خلال الانتقال إلى AV1 لتشفير الفيديو، مما يوضح كيف يمكن للأتمتة وتصميم النظام الدقيق تقليل النفقات التشغيلية على نطاق واسع. قللت Spotify وقت بناء CI بنسبة 40% من خلال تحسين سير عمل البناء والتخزين المؤقت، وهو مثال ملموس على كيف تتفوق خطوط الأنابيب القابلة للتكرار على الإعدادات العشوائية. خفضت Stripe زمن استجابة API (p99) بنسبة 40% في أجزاء من بنيتها التحتية من خلال تحسين الأداء، وهو تذكير بضرورة قياس زمن الاستجابة الأقصى عندما يكون Pi تحت ضغط الذاكرة.

هذه الأمثلة ليست خاصة بـ OpenClaw، لكن المبدأ واحد: الأتمتة المستقرة تأتي من القابلية للتكرار، والقياس، والتغيير المنضبط.

خطوات عملية

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

أنشئ docker-compose.yml مع 127.0.0.1:18789:18789 ووحدة تخزين مسماة، ثم شغل:

bashCopy
docker compose up -d
docker compose logs -f openclaw

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

• أضف تدوير سجلات Docker (max-size=10m, max-file=5) وتأكد من توقف السجلات عن النمو بلا حدود.
• انسخ وحدة التخزين المسماة احتياطياً إلى openclaw-data.tgz وخزنها خارج Pi.

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

• أضف حاوية كناري على المنفذ 28789 وشغلها لمدة 24 ساعة قبل ترقية النسخة المستقرة.
• أضف وصولاً خاصاً عن بعد عبر Tailscale مع الحفاظ على البوابة مرتبطة بـ 127.0.0.1.

مصادر مفيدة

• Running OpenClaw in Docker (Simon Willison) - تدفق Docker عملي، الوصول للوحة التحكم، وربط Telegram.
• OpenClaw Complete Guide (2026) - خطوات المعالج، ملاحظات الأمان، وتفاصيل إعداد القنوات.
• Awesome OpenClaw Skills (GitHub) - قائمة مهارات منسقة لسير عمل الأتمتة.
• How To Install and Setup OpenClaw With Docker (YouTube) - شرح مرئي لإعداد Docker والمهارات.
• Full OpenClaw Setup Tutorial (YouTube) - أنماط التشغيل على مدار الساعة وتكوين القنوات.

الأفكار الرئيسية

• يُعد Raspberry Pi 4/5 مع Docker Compose مضيفاً عملياً يعمل دائماً لـ OpenClaw عندما تريد العزل وإعادة البناء القابلة للتكرار.
• اربط البوابة بـ 127.0.0.1، واستخدم وحدات تخزين دائمة، وقم بتدوير السجلات. هذه الخيارات الثلاثة تمنع معظم مشاكل Pi الغريبة.
• تعامل مع ربط القنوات (Telegram/Discord) كطبقة تحكم في الوصول: وافق على عمليات الاقتران، وقم بتدوير الرموز، وتجنب التعرض العام.
• استخدم حاوية كناري ونسخاً احتياطية لوحدات التخزين لجعل الترقيات عملية مملة (بالمعنى الجيد)، وقابلة للعكس، وسريعة.