​

Docker (اختياري)

​

هل Docker مناسب لي؟

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

• Gateway مُحَوْسَب بالحاويات (OpenClaw كامل داخل Docker)
• Sandbox وكيل لكل جلسة (Gateway على المضيف + أدوات وكيل معزولة بـ Docker)

​

المتطلبات

• Docker Desktop (أو Docker Engine) + Docker Compose v2
• مساحة قرص كافية للصور + السجلات

​

Gateway مُحَوْسَب بالحاويات (Docker Compose)

​

البدء السريع (موصى به)

./docker-setup.sh

• يبني صورة الـ Gateway
• تشغيل معالج أونبواردينغ
• يطبع تلميحات إعداد الموفّرين الاختيارية
• يبدأ الـ Gateway عبر Docker Compose
• يولّد رمز Gateway ويكتبه إلى .env

• OPENCLAW_DOCKER_APT_PACKAGES — تثبيت حِزَم apt إضافية أثناء البناء
• OPENCLAW_EXTRA_MOUNTS — إضافة ربطات bind إضافية من المضيف
• OPENCLAW_HOME_VOLUME — الإبقاء على /home/node في وحدة تخزين مُسماة

• افتح http://127.0.0.1:18789/ في المتصفح.
• الصق الرمز في واجهة التحكم (الإعدادات → الرمز).
• هل تحتاج إلى عنوان URL مرة أخرى؟ هل تحتاج إلى عنوان URL مرة أخرى؟ هل تحتاج العنوان مرة أخرى؟ شغّل docker compose run --rm openclaw-cli dashboard --no-open.

• ~/.openclaw/
• ~/.openclaw/workspace

​

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

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

​

المسار اليدوي (compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

​

رمز واجهة التحكم + الاقتران (Docker)

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>

​

ربطات إضافية (اختياري)

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

• يجب مشاركة المسارات مع Docker Desktop على macOS/Windows.
• إذا عدّلت OPENCLAW_EXTRA_MOUNTS، فأعد تشغيل docker-setup.sh لإعادة توليد ملف compose الإضافي.
• يتم توليد docker-compose.extra.yml. لا تعدّله يدويًا.

​

الإبقاء على دليل المنزل الكامل للحاوية (اختياري)

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

• إذا غيّرت OPENCLAW_HOME_VOLUME، فأعد تشغيل docker-setup.sh لإعادة توليد ملف compose الإضافي.
• تستمر وحدة التخزين المُسماة حتى تُزال باستخدام docker volume rm <name>.

​

تثبيت حِزَم apt إضافية (اختياري)

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

• يقبل هذا قائمة أسماء حِزَم apt مفصولة بمسافات.
• إذا غيّرت OPENCLAW_DOCKER_APT_PACKAGES، فأعد تشغيل docker-setup.sh لإعادة بناء الصورة.

​

حاوية متقدمة/كاملة الميزات (اختياري)

• عدم تثبيت حِزَم النظام أثناء التشغيل
• عدم وجود Homebrew افتراضيًا
• عدم تضمين متصفحات Chromium/Playwright

1. الإبقاء على /home/node بحيث تبقى تنزيلات المتصفح ومخابئ الأدوات:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

2. خبز تبعيات النظام داخل الصورة (قابل للتكرار + دائم):

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

3. تثبيت متصفحات Playwright دون npx (يتجنب تعارضات تجاوز npm):

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

4. الإبقاء على تنزيلات متصفح Playwright:

• اضبط PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright في docker-compose.yml.
• تأكّد من بقاء /home/node عبر OPENCLAW_HOME_VOLUME، أو اربط /home/node/.cache/ms-playwright عبر OPENCLAW_EXTRA_MOUNTS.

​

الأذونات + EACCES

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

​

إعادة بناء أسرع (موصى به)

FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
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"]

​

إعداد القنوات (اختياري)

docker compose run --rm openclaw-cli channels login

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

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

​

OAuth لـ OpenAI Codex (Docker دون واجهة)

​

فحص الصحة

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

​

اختبار دخان E2E (Docker)

scripts/e2e/onboard-docker.sh

​

اختبار دخان لاستيراد QR (Docker)

pnpm test:docker:qr

​

ملاحظات

• ربط Gateway الافتراضي هو lan لاستخدام الحاويات.
• يستخدم CMD في Dockerfile ‏--allow-unconfigured؛ سيبدأ التكوين المُثبّت مع gateway.mode وليس local. غيّر CMD لفرض الحارس.
• حاوية Gateway هي مصدر الحقيقة للجلسات (~/.openclaw/agents/<agentId>/sessions/).

​

Sandbox الوكيل (Gateway على المضيف + أدوات Docker)

​

ما الذي يفعله

• النطاق: "agent" افتراضيًا (حاوية واحدة + مساحة عمل لكل وكيل)
• النطاق: "session" للعزل لكل جلسة
• مجلد مساحة عمل لكل نطاق مُثبت عند /workspace
• وصول اختياري لمساحة عمل الوكيل (agents.defaults.sandbox.workspaceAccess)
• سياسة أدوات سماح/منع (المنع له الأسبقية)
• تُنسخ الوسائط الواردة إلى مساحة عمل الـ sandbox النشطة (media/inbound/*) ليتمكنـت الأدوات من قراءتها (ومع workspaceAccess: "rw"، تهبط في مساحة عمل الوكيل)

​

ملفات تعريف sandbox لكل وكيل (متعدد الوكلاء)

• وصول كامل (وكيل شخصي)
• أدوات للقراءة فقط + مساحة عمل للقراءة فقط (وكيل عائلة/عمل)
• بدون أدوات نظام ملفات/قشرة (وكيل عام)

​

السلوك الافتراضي

• الصورة: openclaw-sandbox:bookworm-slim
• حاوية واحدة لكل وكيل
• وصول مساحة عمل الوكيل: workspaceAccess: "none" (افتراضي) يستخدم ~/.openclaw/sandboxes
  • يحافظ "ro" على مساحة عمل الـ sandbox عند /workspace ويربط مساحة عمل الوكيل للقراءة فقط عند /agent (يعطّل write/edit/apply_patch)
  • يربط "rw" مساحة عمل الوكيل قراءة/كتابة عند /workspace
• التنظيف التلقائي: خمول > 24 ساعة أو العمر > 7 أيام
• الشبكة: none افتراضيًا (اشترك صراحة إذا احتجت الخروج)
• السماح الافتراضي: exec، process، read، write، edit، sessions_list، sessions_history، sessions_send، sessions_spawn، session_status
• المنع الافتراضي: browser، canvas، nodes، cron، discord، gateway

​

تمكين sandboxing

• القيمة الافتراضية لـ docker.network هي "none" (لا خروج).
• يمنع readOnlyRoot: true تثبيت الحِزَم.
• يجب أن يكون user مستخدم root من أجل apt-get (احذف user أو اضبط user: "0:0"). يعيد OpenClaw إنشاء الحاويات تلقائيًا عند تغيّر setupCommand (أو إعدادات docker) ما لم تكن الحاوية مستخدمة مؤخرًا (خلال ~5 دقائق). تسجّل الحاويات الساخنة تحذيرًا مع أمر openclaw sandbox recreate ... الدقيق.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

​

بناء صورة sandbox الافتراضية

scripts/sandbox-setup.sh

​

صورة sandbox مشتركة (اختياري)

scripts/sandbox-common-setup.sh

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

​

صورة متصفح sandbox

scripts/sandbox-browser-setup.sh

• الرأسي (Xvfb) يقلل من حجب البوت مقابل بلا رأس.
• يمكن استخدام الوضع دون واجهة عبر ضبط agents.defaults.sandbox.browser.headless=true.
• لا حاجة لبيئة سطح مكتب كاملة (GNOME)؛ يوفر Xvfb العرض.

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

• عنوان تحكم متصفح sandbox (لأداة browser)
• عنوان noVNC (إن كان مُمكّنًا و headless=false)

​

صورة sandbox مخصّصة

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

​

سياسة الأدوات (سماح/منع)

• deny يتغلب على allow.
• إذا كان allow فارغًا: تتوفر جميع الأدوات (باستثناء المنع).
• إذا كان allow غير فارغ: تتوفر فقط الأدوات ضمن allow (مع طرح المنع).

​

استراتيجية التنظيف

• prune.idleHours: إزالة الحاويات غير المستخدمة خلال X ساعات (0 = تعطيل)
• prune.maxAgeDays: إزالة الحاويات الأقدم من X أيام (0 = تعطيل)

• الاحتفاظ بالجلسات النشطة مع تحديد العمر: idleHours: 24، maxAgeDays: 7
• عدم التنظيف مطلقًا: idleHours: 0، maxAgeDays: 0

​

ملاحظات أمنية

• الجدار الصلب ينطبق فقط على الأدوات (exec/read/write/edit/apply_patch).
• أدوات المضيف فقط مثل browser/camera/canvas محظورة افتراضيًا.
• السماح بـ browser داخل sandbox يكسر العزل (يعمل المتصفح على المضيف).

​

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

• الصورة مفقودة: ابنِها باستخدام scripts/sandbox-setup.sh أو اضبط agents.defaults.sandbox.docker.image.
• الحاوية لا تعمل: ستُنشأ تلقائيًا لكل جلسة عند الطلب.
• أخطاء أذونات داخل sandbox: اضبط docker.user إلى UID:GID يطابق ملكية مساحة العمل المُثبتة (أو غيّر ملكية مجلد مساحة العمل).
• لم تُعثر على أدوات مخصّصة: يشغّل OpenClaw الأوامر باستخدام sh -lc (قشرة تسجيل دخول)، والتي تُصدِر /etc/profile وقد تعيد ضبط PATH. اضبط docker.env.PATH لإضافة مسارات أدواتك المخصّصة (مثل /custom/bin:/usr/local/share/npm-global/bin)، أو أضِف سكربتًا تحت /etc/profile.d/ في Dockerfile الخاص بك.