الانتقال إلى المحتوى الرئيسي
شغّل OpenClaw Gateway داخل حاوية Podman بلا جذر، تُدار بواسطة مستخدمك الحالي غير الجذري. النموذج المقصود هو:
  • يشغّل Podman حاوية Gateway.
  • يكون openclaw CLI على المضيف هو مستوى التحكم.
  • تكون الحالة الدائمة على المضيف تحت ~/.openclaw افتراضيًا.
  • تستخدم الإدارة اليومية openclaw --container <name> ... بدلًا من sudo -u openclaw أو podman exec أو مستخدم خدمة منفصل.

​
المتطلبات المسبقة

  • Podman في وضع بلا جذر
  • OpenClaw CLI مثبّت على المضيف
  • اختياري: systemd --user إذا كنت تريد تشغيلًا تلقائيًا مُدارًا بواسطة Quadlet
  • اختياري: sudo فقط إذا كنت تريد loginctl enable-linger "$(whoami)" لاستمرارية التشغيل بعد الإقلاع على مضيف بلا شاشة

​
البدء السريع

1

One-time setup

من جذر المستودع، شغّل ./scripts/podman/setup.sh.
2

Start the Gateway container

ابدأ الحاوية باستخدام ./scripts/run-openclaw-podman.sh launch.
3

Run onboarding inside the container

شغّل ./scripts/run-openclaw-podman.sh launch setup، ثم افتح http://127.0.0.1:18789/.
4

Manage the running container from the host CLI

اضبط OPENCLAW_CONTAINER=openclaw، ثم استخدم أوامر openclaw العادية من المضيف.
تفاصيل الإعداد:
  • يبني ./scripts/podman/setup.sh الصورة openclaw:local في مخزن Podman بلا جذر لديك افتراضيًا، أو يستخدم OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE إذا ضبطت أحدهما.
  • ينشئ ~/.openclaw/openclaw.json مع gateway.mode: "local" إذا كان مفقودًا.
  • ينشئ ~/.openclaw/.env مع OPENCLAW_GATEWAY_TOKEN إذا كان مفقودًا.
  • بالنسبة لعمليات التشغيل اليدوية، يقرأ المساعد قائمة سماح صغيرة فقط من المفاتيح المتعلقة بـ Podman من ~/.openclaw/.env ويمرر متغيرات بيئة تشغيل صريحة إلى الحاوية؛ ولا يمرر ملف البيئة كاملًا إلى Podman.
إعداد مُدار بواسطة Quadlet: 
./scripts/podman/setup.sh --quadlet
Quadlet خيار خاص بـ Linux فقط لأنه يعتمد على خدمات مستخدم systemd. يمكنك أيضًا ضبط OPENCLAW_PODMAN_QUADLET=1. متغيرات بيئة اختيارية للبناء/الإعداد:
  • OPENCLAW_IMAGE أو OPENCLAW_PODMAN_IMAGE — استخدم صورة موجودة/مجلوبة بدلًا من بناء openclaw:local
  • OPENCLAW_IMAGE_APT_PACKAGES — ثبّت حزم apt إضافية أثناء بناء الصورة (يقبل أيضًا OPENCLAW_DOCKER_APT_PACKAGES القديم)
  • OPENCLAW_IMAGE_PIP_PACKAGES — ثبّت حزم Python إضافية أثناء بناء الصورة؛ ثبّت الإصدارات واستخدم فقط فهارس الحزم التي تثق بها
  • OPENCLAW_EXTENSIONS — ثبّت اعتماديات Plugin مسبقًا وقت البناء
  • OPENCLAW_INSTALL_BROWSER — ثبّت Chromium و Xvfb مسبقًا لأتمتة المتصفح (اضبطه على 1 للتفعيل)
بدء الحاوية: 
./scripts/run-openclaw-podman.sh launch
يبدأ السكربت الحاوية بمعرّف المستخدم/المجموعة الحاليين لديك باستخدام --userns=keep-id ويربط حالة OpenClaw لديك داخل الحاوية. الإعداد الأولي: 
./scripts/run-openclaw-podman.sh launch setup
ثم افتح http://127.0.0.1:18789/ واستخدم الرمز من ~/.openclaw/.env. مصادقة النموذج في Podman:
  • استخدم المصادقة المُدارة بواسطة OpenClaw أثناء الإعداد: مفاتيح Anthropic API لـ Anthropic، أو مصادقة OpenAI Codex عبر OAuth في المتصفح/رمز الجهاز لـ OpenAI المدعوم بـ Codex.
  • لا يربط مشغّل Podman مجلدات بيانات اعتماد CLI على المضيف مثل ~/.claude أو ~/.codex داخل حاوية الإعداد أو Gateway.
  • تسجيلات دخول CLI الموجودة على المضيف هي مسارات تسهيل على المضيف نفسه. بالنسبة لتثبيتات الحاويات، أبقِ مصادقة المزوّد في حالة ~/.openclaw المربوطة التي يديرها الإعداد.
افتراضي CLI على المضيف: 
export OPENCLAW_CONTAINER=openclaw
بعد ذلك، ستُشغَّل أوامر مثل هذه داخل تلك الحاوية تلقائيًا: 
openclaw dashboard --no-open
openclaw gateway status --deep   # includes extra service scan
openclaw doctor
openclaw channels login
على macOS، قد تجعل آلة Podman المتصفح يبدو غير محلي بالنسبة إلى Gateway. إذا أبلغت Control UI عن أخطاء مصادقة الجهاز بعد التشغيل، فاستخدم إرشادات Tailscale في Podman و Tailscale.

​
Podman و Tailscale

للوصول عبر HTTPS أو متصفح بعيد، اتبع وثائق Tailscale الرئيسية. ملاحظة خاصة بـ Podman:
  • أبقِ مضيف نشر Podman على 127.0.0.1.
  • فضّل tailscale serve المُدار من المضيف على openclaw gateway --tailscale serve.
  • على macOS، إذا كان سياق مصادقة جهاز المتصفح المحلي غير موثوق، فاستخدم وصول Tailscale بدلًا من حلول الأنفاق المحلية المخصصة.
راجع:

​
Systemd (Quadlet، اختياري)

إذا شغّلت ./scripts/podman/setup.sh --quadlet، يثبّت الإعداد ملف Quadlet في: 
~/.config/containers/systemd/openclaw.container
أوامر مفيدة:
  • بدء: systemctl --user start openclaw.service
  • إيقاف: systemctl --user stop openclaw.service
  • الحالة: systemctl --user status openclaw.service
  • السجلات: journalctl --user -u openclaw.service -f
بعد تعديل ملف Quadlet: 
systemctl --user daemon-reload
systemctl --user restart openclaw.service
لاستمرارية التشغيل بعد الإقلاع على مضيفات SSH/بلا شاشة، فعّل الإبقاء لمستخدمك الحالي: 
sudo loginctl enable-linger "$(whoami)"

​
الإعدادات والبيئة والتخزين

  • دليل الإعدادات: ~/.openclaw
  • دليل مساحة العمل: ~/.openclaw/workspace
  • ملف الرمز: ~/.openclaw/.env
  • مساعد التشغيل: ./scripts/run-openclaw-podman.sh
يربط سكربت التشغيل و Quadlet حالة المضيف داخل الحاوية:
  • OPENCLAW_CONFIG_DIR -> /home/node/.openclaw
  • OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace
افتراضيًا، هذه أدلة مضيف وليست حالة حاوية مجهولة، لذلك تبقى openclaw.json، وملف auth-profiles.json لكل وكيل، وحالة القنوات/المزوّدين، والجلسات، ومساحة العمل بعد استبدال الحاوية. كما يجهّز إعداد Podman gateway.controlUi.allowedOrigins لـ 127.0.0.1 و localhost على منفذ Gateway المنشور لكي تعمل لوحة المعلومات المحلية مع ربط الحاوية غير المعتمد على loopback. متغيرات بيئة مفيدة للمشغّل اليدوي:
  • OPENCLAW_PODMAN_CONTAINER — اسم الحاوية (openclaw افتراضيًا)
  • OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE — الصورة المراد تشغيلها
  • OPENCLAW_PODMAN_GATEWAY_HOST_PORT — منفذ المضيف المعين إلى منفذ الحاوية 18789
  • OPENCLAW_PODMAN_BRIDGE_HOST_PORT — منفذ المضيف المعين إلى منفذ الحاوية 18790
  • OPENCLAW_PODMAN_PUBLISH_HOST — واجهة المضيف للمنافذ المنشورة؛ الافتراضي هو 127.0.0.1
  • OPENCLAW_GATEWAY_BIND — وضع ربط Gateway داخل الحاوية؛ الافتراضي هو lan
  • OPENCLAW_PODMAN_USERNS — keep-id (الافتراضي)، أو auto، أو host
يقرأ المشغّل اليدوي ~/.openclaw/.env قبل تثبيت افتراضيات الحاوية/الصورة، لذلك يمكنك حفظ هذه القيم هناك. إذا استخدمت OPENCLAW_CONFIG_DIR أو OPENCLAW_WORKSPACE_DIR غير افتراضي، فاضبط المتغيرات نفسها لكل من أوامر ./scripts/podman/setup.sh وأوامر ./scripts/run-openclaw-podman.sh launch اللاحقة. لا يحفظ المشغّل المحلي في المستودع تجاوزات المسارات المخصصة عبر جلسات shell. ملاحظة Quadlet:
  • تحافظ خدمة Quadlet المُولّدة عمدًا على شكل افتراضي ثابت ومُحصّن: منافذ منشورة على 127.0.0.1، و --bind lan داخل الحاوية، ومساحة أسماء مستخدم keep-id.
  • تثبّت OPENCLAW_NO_RESPAWN=1، و Restart=on-failure، و TimeoutStartSec=300.
  • تنشر كلًا من 127.0.0.1:18789:18789 (Gateway) و 127.0.0.1:18790:18790 (الجسر).
  • تقرأ ~/.openclaw/.env كملف EnvironmentFile وقت التشغيل لقيم مثل OPENCLAW_GATEWAY_TOKEN، لكنها لا تستهلك قائمة السماح الخاصة بتجاوزات Podman للمشغّل اليدوي.
  • إذا كنت تحتاج إلى منافذ نشر مخصصة، أو مضيف نشر، أو أعلام أخرى لتشغيل الحاوية، فاستخدم المشغّل اليدوي أو عدّل ~/.config/containers/systemd/openclaw.container مباشرة، ثم أعد تحميل الخدمة وأعد تشغيلها.

​
أوامر مفيدة

  • سجلات الحاوية: podman logs -f openclaw
  • إيقاف الحاوية: podman stop openclaw
  • إزالة الحاوية: podman rm -f openclaw
  • فتح عنوان URL للوحة المعلومات من CLI على المضيف: openclaw dashboard --no-open
  • الصحة/الحالة عبر CLI على المضيف: openclaw gateway status --deep (فحص RPC + فحص خدمة إضافي)

​
استكشاف الأخطاء وإصلاحها

  • رفض الإذن (EACCES) على الإعدادات أو مساحة العمل: تعمل الحاوية باستخدام --userns=keep-id و --user <your uid>:<your gid> افتراضيًا. تأكد من أن مسارات الإعدادات/مساحة العمل على المضيف مملوكة لمستخدمك الحالي.
  • بدء Gateway محظور (gateway.mode=local مفقود): تأكد من وجود ~/.openclaw/openclaw.json وأنه يضبط gateway.mode="local". ينشئ scripts/podman/setup.sh هذا إذا كان مفقودًا.
  • أوامر CLI داخل الحاوية تستهدف وجهة خاطئة: استخدم openclaw --container <name> ... صراحة، أو صدّر OPENCLAW_CONTAINER=<name> في shell لديك.
  • فشل openclaw update مع --container: هذا متوقع. أعد بناء/جلب الصورة، ثم أعد تشغيل الحاوية أو خدمة Quadlet.
  • خدمة Quadlet لا تبدأ: شغّل systemctl --user daemon-reload، ثم systemctl --user start openclaw.service. على الأنظمة بلا شاشة قد تحتاج أيضًا إلى sudo loginctl enable-linger "$(whoami)".
  • SELinux يحظر ربط التحميلات: اترك سلوك التحميل الافتراضي كما هو؛ يضيف المشغّل :Z تلقائيًا على Linux عندما يكون SELinux في وضع الفرض أو السماح.

​
ذو صلة