Docker

Docker اختياري اختياري. استخدمه فقط إذا كنت تريد Gateway ضمن حاوية أو تريد التحقق من مسار Docker.

هل Docker مناسب لي؟

• نعم: تريد بيئة Gateway معزولة وقابلة للرمي، أو تريد تشغيل OpenClaw على مضيف بدون تثبيتات محلية.
• لا: تعمل على جهازك وتريد فقط أسرع حلقة تطوير. استخدم مسار التثبيت العادي بدلا من ذلك.
• ملاحظة العزل: يستخدم محرك العزل الافتراضي Docker عند تفعيل العزل، لكن العزل معطل افتراضيا ولا يتطلب تشغيل Gateway الكامل داخل Docker. تتوفر أيضا محركات عزل SSH وOpenShell. راجع العزل.

المتطلبات الأساسية

• Docker Desktop (أو Docker Engine) + Docker Compose v2
• ذاكرة RAM لا تقل عن 2 GB لبناء الصورة (pnpm install قد ينهيه النظام بسبب نفاد الذاكرة على مضيفات 1 GB مع الخروج 137)
• مساحة قرص كافية للصور والسجلات
• إذا كنت تشغل على VPS/مضيف عام، راجع تقوية الأمان للتعرض الشبكي، خصوصا سياسة جدار حماية Docker DOCKER-USER.

Gateway ضمن حاوية

./scripts/docker/setup.sh

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

المسار اليدوي

إذا كنت تفضل تشغيل كل خطوة بنفسك بدلا من استخدام سكربت الإعداد:

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

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

يقبل سكربت الإعداد متغيرات البيئة الاختيارية هذه:

لا تتضمن صورة Docker الرسمية Homebrew. أثناء التهيئة الأولية، يخفي OpenClaw مثبتات اعتماديات Skills الخاصة بـ brew فقط عندما يعمل داخل حاوية Linux بدون brew؛ يجب توفير تلك الاعتماديات عبر صورة مخصصة أو تثبيتها يدويا. للاعتماديات المتاحة من حزم Debian، استخدم OPENCLAW_IMAGE_APT_PACKAGES أثناء بناء الصورة. لا يزال الاسم القديم OPENCLAW_DOCKER_APT_PACKAGES مقبولا. لاعتماديات Python، استخدم OPENCLAW_IMAGE_PIP_PACKAGES. يشغل هذا python3 -m pip install --break-system-packages أثناء بناء الصورة، لذلك ثبت إصدارات الحزم واستخدم فهارس حزم تثق بها فقط. تضبط عمليات بناء المصدر OPENCLAW_DOCKER_BUILD_NODE_OPTIONS افتراضيا على --max-old-space-size=8192 وتترك OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB غير مضبوطة كي يستطيع مغلف tsdown احترام حدود ذاكرة الحاوية. كما تضبط افتراضيا OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 لأن صور التشغيل تحذف ملفات التصريحات بعد البناء. إذا أبلغ Docker عن ResourceExhausted، أو cannot allocate memory، أو توقف أثناء tsdown، فزد حد ذاكرة باني Docker أو أعد المحاولة بكومات صريحة أصغر، مثلا OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

يمكن للمشرفين اختبار مصدر Plugin مضمن مقابل صورة معبأة عن طريق تحميل دليل مصدر Plugin واحد فوق مسار مصدره المعبأ، مثلا OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. يتجاوز دليل المصدر المحمل هذا حزمة /app/dist/extensions/synology-chat المترجمة المطابقة لمعرف Plugin نفسه.

قابلية المراقبة

يكون تصدير OpenTelemetry خارجا من حاوية Gateway إلى جامع OTLP الخاص بك. لا يتطلب منفذ Docker منشورا. إذا بنيت الصورة محليا وتريد أن يكون مصدر OpenTelemetry المضمن متاحا داخل الصورة، فأدرج اعتماديات التشغيل الخاصة به:

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

ثبت Plugin الرسمي @openclaw/diagnostics-otel من ClawHub في تثبيتات Docker المعبأة قبل تفعيل التصدير. لا تزال الصور المخصصة المبنية من المصدر قادرة على تضمين مصدر Plugin المحلي باستخدام OPENCLAW_EXTENSIONS=diagnostics-otel. لتفعيل التصدير، اسمح بـ Plugin diagnostics-otel وفعله في الإعدادات، ثم اضبط diagnostics.otel.enabled=true أو استخدم مثال الإعداد في تصدير OpenTelemetry . تضبط ترويسات مصادقة الجامع عبر diagnostics.otel.headers، وليس عبر متغيرات بيئة Docker.

تستخدم مقاييس Prometheus منفذ Gateway المنشور بالفعل. ثبت clawhub:@openclaw/diagnostics-prometheus، وفعل Plugin diagnostics-prometheus، ثم اجمع المقاييس:

http://<gateway-host>:18789/api/diagnostics/prometheus

المسار محمي بمصادقة Gateway. لا تعرض منفذ /metrics عام منفصل أو مسار وكيل عكسي غير مصادق. راجع مقاييس Prometheus.

فحوصات الصحة

نقاط نهاية فحص الحاوية (لا تتطلب مصادقة):

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

تتضمن صورة Docker فحصًا مدمجًا باسم HEALTHCHECK يرسل طلبًا إلى /healthz. إذا استمرت الفحوصات في الفشل، يضع Docker علامة unhealthy على الحاوية ويمكن لأنظمة التنسيق إعادة تشغيلها أو استبدالها.

لقطة صحة عميقة موثقة:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

الشبكة المحلية مقابل loopback

يضبط scripts/docker/setup.sh القيمة الافتراضية OPENCLAW_GATEWAY_BIND=lan بحيث يعمل وصول المضيف إلى http://127.0.0.1:18789 مع نشر منافذ Docker.

• lan (الافتراضي): يمكن لمتصفح المضيف وCLI المضيف الوصول إلى منفذ Gateway المنشور.
• loopback: لا يمكن الوصول إلى Gateway مباشرة إلا من العمليات داخل مساحة أسماء شبكة الحاوية.

الموفرون المحليون على المضيف

عند تشغيل OpenClaw داخل Docker، يكون 127.0.0.1 داخل الحاوية هو الحاوية نفسها، وليس جهازك المضيف. استخدم host.docker.internal لموفري الذكاء الاصطناعي الذين يعملون على المضيف:

يستخدم إعداد Docker المضمّن عناوين URL هذه للمضيف كافتراضات الإعداد الأولي لـ LM Studio وOllama، ويعيّن docker-compose.yml الاسم host.docker.internal إلى Gateway المضيف في Docker لمحرك Docker على Linux. يوفر Docker Desktop بالفعل اسم المضيف نفسه على macOS وWindows.

يجب أن تستمع خدمات المضيف أيضًا على عنوان يمكن الوصول إليه من Docker:

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

إذا كنت تستخدم ملف Compose خاصًا بك أو أمر docker run، فأضف تعيين المضيف نفسه بنفسك، على سبيل المثال --add-host=host.docker.internal:host-gateway.

خلفية Claude CLI في Docker

لا تثبّت صورة OpenClaw الرسمية لـ Docker أداة Claude Code مسبقًا. ثبّت Claude Code وسجّل الدخول إليها داخل مستخدم الحاوية الذي يشغّل OpenClaw، ثم احتفظ بمجلد المنزل الخاص بتلك الحاوية حتى لا تمحو ترقيات الصورة الملف الثنائي أو حالة مصادقة Claude.

لتثبيتات Docker الجديدة، فعّل مجلدًا دائمًا لـ /home/node قبل تشغيل الإعداد:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

لتثبيت Docker موجود، أوقف الحزمة أولًا وأعد تحميل قيم Docker الحالية من .env قبل إعادة تشغيل الإعداد. لا يقرأ سكربت الإعداد .env من تلقاء نفسه؛ بل يعيد كتابة .env من الصدفة الحالية والافتراضات. بالنسبة إلى ملف .env المُنشأ، شغّل:

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

إذا كان ملف .env يحتوي على قيم لا يمكن لصدفتك تحميلها كمصدر، فأعد تصدير القيم الحالية التي تعتمد عليها يدويًا أولًا، مثل OPENCLAW_IMAGE، والمنافذ، ووضع الربط، والمسارات المخصصة، وOPENCLAW_EXTRA_MOUNTS، وsandbox، وإعدادات تخطي الإعداد الأولي. يركّب التراكب المُنشأ مجلد المنزل لكل من openclaw-gateway و openclaw-cli.

شغّل الأوامر المتبقية باستخدام تراكب Compose المُنشأ حتى يركّب كلا الخدمتين مجلد المنزل الدائم. إذا كان إعدادك يستخدم أيضًا docker-compose.override.yml، فأدرجه قبل docker-compose.extra.yml.

ثبّت Claude Code في ذلك المنزل الدائم:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

يكتب المثبّت الأصلي الملف الثنائي claude تحت /home/node/.local/bin/claude. أخبر OpenClaw باستخدام ذلك المسار داخل الحاوية:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

سجّل الدخول وتحقق من داخل منزل الحاوية الدائم نفسه:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

بعد ذلك، يمكنك استخدام خلفية claude-cli المضمّنة:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

يحافظ OPENCLAW_HOME_VOLUME على تثبيت Claude Code الأصلي تحت /home/node/.local/bin و/home/node/.local/share/claude، إضافة إلى إعدادات Claude Code وحالة المصادقة تحت /home/node/.claude و/home/node/.claude.json. الحفاظ على /home/node/.openclaw فقط لا يكفي لإعادة استخدام Claude CLI. إذا استخدمت OPENCLAW_EXTRA_MOUNTS بدلًا من مجلد المنزل، فركّب كل مسارات Claude هذه داخل خدمتي Docker معًا.

Bonjour / mDNS

عادةً لا تمرّر شبكة Docker الجسرية بث Bonjour/mDNS المتعدد (224.0.0.251:5353) بشكل موثوق. لذلك يضبط إعداد Compose المضمّن القيمة الافتراضية OPENCLAW_DISABLE_BONJOUR=1 حتى لا يدخل Gateway في حلقة تعطل أو يعيد تشغيل الإعلان مرارًا عندما تُسقط الشبكة الجسرية حركة البث المتعدد.

استخدم عنوان URL المنشور لـ Gateway أو Tailscale أو DNS-SD واسع النطاق لمضيفي Docker. اضبط OPENCLAW_DISABLE_BONJOUR=0 فقط عند التشغيل باستخدام شبكة المضيف أو macvlan أو شبكة أخرى يُعرف أن بث mDNS المتعدد يعمل عليها.

للملاحظات واستكشاف الأخطاء وإصلاحها، راجع اكتشاف Bonjour.

التخزين والاستمرارية

يركّب Docker Compose عبر bind mount كلًا من OPENCLAW_CONFIG_DIR إلى /home/node/.openclaw، وOPENCLAW_WORKSPACE_DIR إلى /home/node/.openclaw/workspace، و OPENCLAW_AUTH_PROFILE_SECRET_DIR إلى /home/node/.config/openclaw، بحيث تبقى هذه المسارات بعد استبدال الحاوية. عندما لا تُعيّن أي متغيرات، يعود docker-compose.yml المضمّن إلى مسارات تحت ${HOME}، أو إلى /tmp عندما يكون HOME نفسه مفقودًا أيضًا. يمنع ذلك docker compose up من إصدار مواصفة مجلد ذات مصدر فارغ في البيئات المجردة.

دليل الإعداد المركّب هذا هو المكان الذي يحتفظ فيه OpenClaw بما يلي:

• openclaw.json لإعداد السلوك
• agents/<agentId>/agent/auth-profiles.json لمصادقة OAuth/API-key المخزنة الخاصة بالموفر
• .env لأسرار وقت التشغيل المدعومة بالبيئة مثل OPENCLAW_GATEWAY_TOKEN

يخزن دليل مفتاح سر ملف تعريف المصادقة مفتاح التشفير المحلي المستخدم لمواد رموز ملف تعريف المصادقة المدعومة بـ OAuth. احتفظ به مع حالة مضيف Docker لديك، لكن منفصلًا عن OPENCLAW_CONFIG_DIR.

تخزن plugins القابلة للتنزيل والمثبّتة حالة حزمها تحت منزل OpenClaw المركّب، لذلك تبقى سجلات تثبيت Plugin وجذور الحزم بعد استبدال الحاوية. لا ينشئ بدء تشغيل Gateway أشجار تبعيات bundled-plugin.

للحصول على تفاصيل الاستمرارية الكاملة في عمليات نشر VM، راجع وقت تشغيل Docker VM - ما الذي يستمر وأين.

مناطق نمو القرص الساخنة: راقب media/، وملفات JSONL للجلسات، وقاعدة بيانات حالة SQLite المشتركة، وجذور حزم Plugin المثبّتة، وسجلات الملفات الدوّارة تحت /tmp/openclaw/.

مساعدات الصدفة (اختيارية)

لإدارة Docker اليومية بسهولة أكبر، ثبّت ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

إذا ثبّت ClawDock من المسار الخام الأقدم scripts/shell-helpers/clawdock-helpers.sh، فأعد تشغيل أمر التثبيت أعلاه حتى يتتبع ملف المساعد المحلي الموقع الجديد.

ثم استخدم clawdock-start وclawdock-stop وclawdock-dashboard وما إلى ذلك. شغّل clawdock-help لكل الأوامر. راجع ClawDock للاطلاع على دليل المساعد الكامل.

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

هل تشغله على VPS؟

راجع Hetzner (Docker VPS) و Docker VM Runtime للاطلاع على خطوات النشر المشتركة على VM بما يشمل تضمين الثنائيات، والاستمرارية، والتحديثات.

بيئة عزل الوكيل

عند تمكين agents.defaults.sandbox مع واجهة Docker الخلفية، يشغل Gateway تنفيذ أدوات الوكيل (shell، وقراءة/كتابة الملفات، وما إلى ذلك) داخل حاويات Docker معزولة بينما يبقى Gateway نفسه على المضيف. يمنحك هذا حاجزا صلبا حول جلسات الوكلاء غير الموثوقة أو متعددة المستأجرين من دون وضع Gateway كله داخل حاوية.

يمكن أن يكون نطاق بيئة العزل لكل وكيل (الافتراضي)، أو لكل جلسة، أو مشتركا. يحصل كل نطاق على مساحة عمل خاصة به مثبتة في /workspace. يمكنك أيضا تكوين سياسات السماح/المنع للأدوات، وعزل الشبكة، وحدود الموارد، وحاويات المتصفح.

للاطلاع على التكوين الكامل، والصور، وملاحظات الأمان، وملفات تعريف الوكلاء المتعددين، راجع:

• العزل -- مرجع العزل الكامل
• OpenShell -- وصول shell تفاعلي إلى حاويات العزل
• بيئة عزل وأدوات الوكلاء المتعددين -- تجاوزات لكل وكيل

التمكين السريع

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

ابن صورة العزل الافتراضية (من نسخة مصدرية محلية):

scripts/sandbox-setup.sh

لتثبيتات npm من دون نسخة مصدرية محلية، راجع العزل § الصور والإعداد لأوامر docker build المضمنة.

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

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

ذو صلة

• نظرة عامة على التثبيت — جميع طرق التثبيت
• Podman — بديل Podman لـ Docker
• ClawDock — إعداد Docker Compose من المجتمع
• التحديث — إبقاء OpenClaw محدثا
• التكوين — تكوين Gateway بعد التثبيت