Docker

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

# هل Docker مناسب لي؟

• نعم: تريد بيئة Gateway معزولة وقابلة للتخلص منها، أو تشغيل OpenClaw على مضيف بدون تثبيتات محلية.
• لا: تعمل على جهازك الخاص وتريد فقط أسرع حلقة تطوير. استخدم سير التثبيت العادي بدلا من ذلك.
• ملاحظة العزل: يستخدم خلفية العزل الافتراضية Docker عند تفعيل العزل، لكن العزل معطل افتراضيا ولا يتطلب not تشغيل 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

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker 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-daemon
docker 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   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

تتضمن صورة Docker HEALTHCHECK مدمجا يرسل ping إلى /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.0
OLLAMA_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، لذلك تبقى هذه المسارات بعد استبدال الحاوية. عندما لا يكون أي من المتغيرين معينا، يعود docker-compose.yml المجمع إلى ${HOME}/.openclaw (و ${HOME}/.openclaw/workspace لتركيب مساحة العمل)، أو /tmp/.openclaw عندما يكون HOME نفسه مفقودا أيضا. يمنع ذلك docker compose up من إصدار مواصفة مجلد ذات مصدر فارغ في البيئات المجردة.

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

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

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

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

مواضع نمو القرص الساخنة: راقب media/، وملفات JSONL للجلسات، وcron/runs/*.jsonl، وجذور حزم 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.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

إذا كنت قد ثبّتت ClawDock من مسار raw الأقدم 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=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# التشغيل على VPS؟

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

# عزل الوكيل

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

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

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

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

# تفعيل سريع

{
  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-open
docker compose run --rm openclaw-cli devices list
docker 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 بعد التثبيت