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

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

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

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

يمكن للمشرفين اختبار مصدر 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"

LAN مقابل 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 لـ Linux Docker Engine. يوفر 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.

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 ‏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 أشجار تبعيات Plugins المضمّنة.

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

النقاط الأكثر تسببًا في نمو القرص: راقب media/، وملفات JSONL الخاصة بالجلسات، وcron/runs/*.jsonl، وجذور حِزم Plugin المثبتة، وسجلات الملفات الدوّارة ضمن /tmp/openclaw/.

مساعدات Shell (اختيارية)

لتسهيل إدارة 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 لخطوات نشر 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 بعد التثبيت