Docker

Docker اختیاری است. فقط زمانی از آن استفاده کنید که یک Gateway کانتینری می‌خواهید یا می‌خواهید جریان Docker را اعتبارسنجی کنید.

آیا Docker برای من مناسب است؟

• بله: یک محیط Gateway ایزوله و موقت می‌خواهید یا می‌خواهید OpenClaw را روی میزبانی بدون نصب‌های محلی اجرا کنید.
• خیر: روی دستگاه خودتان اجرا می‌کنید و فقط سریع‌ترین چرخه توسعه را می‌خواهید. به‌جای آن از جریان نصب معمولی استفاده کنید.
• نکته سندباکس: backend پیش‌فرض سندباکس وقتی سندباکس فعال باشد از Docker استفاده می‌کند، اما سندباکس به‌طور پیش‌فرض خاموش است و برای اجرای کامل Gateway در Docker نیازی ندارد. backendهای سندباکس SSH و OpenShell نیز در دسترس‌اند. سندباکس را ببینید.

پیش‌نیازها

• Docker Desktop (یا Docker Engine) + Docker Compose v2
• دست‌کم ۲ گیگابایت RAM برای ساخت image (pnpm install ممکن است روی میزبان‌های ۱ گیگابایتی با خروج ۱۳۷ به‌دلیل کمبود حافظه کشته شود)
• فضای دیسک کافی برای imageها و logها
• اگر روی یک VPS/میزبان عمومی اجرا می‌کنید، به‌ویژه سیاست firewall مربوط به 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 بسته‌بندی‌شده را در برابر یک image بسته‌بندی‌شده آزمایش کنند؛ برای نمونه با mount کردن یک directory سورس Plugin روی مسیر سورس بسته‌بندی‌شده آن، OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. آن directory سورس mountشده، bundle کامپایل‌شده مطابق /app/dist/extensions/synology-chat را برای همان شناسه Plugin بازنویسی می‌کند.

مشاهده‌پذیری

export مربوط به OpenTelemetry از کانتینر Gateway به‌سمت collector مربوط به OTLP شما خروجی است. به port منتشرشده Docker نیاز ندارد. اگر image را به‌صورت محلی می‌سازید و می‌خواهید exporter بسته‌بندی‌شده OpenTelemetry داخل image در دسترس باشد، dependencyهای runtime آن را اضافه کنید:

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

در نصب‌های Docker بسته‌بندی‌شده، Plugin رسمی @openclaw/diagnostics-otel را پیش از فعال کردن export از ClawHub نصب کنید. imageهای سفارشی ساخته‌شده از سورس همچنان می‌توانند سورس Plugin محلی را با OPENCLAW_EXTENSIONS=diagnostics-otel اضافه کنند. برای فعال کردن export، Plugin diagnostics-otel را در config مجاز و فعال کنید، سپس diagnostics.otel.enabled=true را تنظیم کنید یا از نمونه config در export OpenTelemetry استفاده کنید. headerهای احراز هویت collector از طریق diagnostics.otel.headers پیکربندی می‌شوند، نه از طریق متغیرهای محیطی Docker.

metricهای Prometheus از port ازقبل‌منتشرشده Gateway استفاده می‌کنند. clawhub:@openclaw/diagnostics-prometheus را نصب کنید، Plugin diagnostics-prometheus را فعال کنید، سپس scrape کنید:

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

این route با احراز هویت Gateway محافظت می‌شود. یک port عمومی جداگانه /metrics یا مسیر reverse-proxy بدون احراز هویت expose نکنید. metricهای Prometheus را ببینید.

بررسی‌های سلامت

endpointهای probe کانتینر (بدون نیاز به احراز هویت):

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

image مربوط به Docker شامل یک HEALTHCHECK داخلی است که /healthz را ping می‌کند. اگر checkها همچنان شکست بخورند، Docker کانتینر را به‌عنوان unhealthy علامت‌گذاری می‌کند و سیستم‌های orchestration می‌توانند آن را restart یا جایگزین کنند.

snapshot سلامت عمیق احرازشده:

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 با انتشار port در Docker کار کند.

• lan (پیش‌فرض): مرورگر میزبان و CLI میزبان می‌توانند به port منتشرشده Gateway برسند.
• loopback: فقط processهای داخل namespace شبکه کانتینر می‌توانند مستقیماً به Gateway برسند.

ارائه‌دهندگان محلی میزبان

وقتی OpenClaw در Docker اجرا می‌شود، 127.0.0.1 داخل کانتینر خود کانتینر است، نه دستگاه میزبان شما. برای ارائه‌دهندگان AI که روی میزبان اجرا می‌شوند از host.docker.internal استفاده کنید:

راه‌اندازی Docker بسته‌بندی‌شده از این URLهای میزبان به‌عنوان پیش‌فرض‌های onboarding برای LM Studio و Ollama استفاده می‌کند، و docker-compose.yml، host.docker.internal را برای Docker Engine روی Linux به gateway میزبان Docker نگاشت می‌کند. Docker Desktop همین hostname را از قبل روی macOS و Windows فراهم می‌کند.

serviceهای میزبان نیز باید روی نشانی‌ای listen کنند که از Docker قابل دسترسی باشد:

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

اگر از file مربوط به Compose یا command مربوط به docker run خودتان استفاده می‌کنید، همان نگاشت میزبان را خودتان اضافه کنید؛ برای مثال --add-host=host.docker.internal:host-gateway.

Bonjour / mDNS

شبکه bridge در Docker معمولاً multicast مربوط به Bonjour/mDNS (224.0.0.251:5353) را قابل‌اعتماد forward نمی‌کند. بنابراین راه‌اندازی Compose بسته‌بندی‌شده به‌طور پیش‌فرض OPENCLAW_DISABLE_BONJOUR=1 را تنظیم می‌کند تا Gateway هنگام drop شدن ترافیک multicast توسط bridge دچار crash-loop نشود یا تبلیغ را پیوسته restart نکند.

برای میزبان‌های Docker از URL منتشرشده Gateway، Tailscale، یا DNS-SD گسترده‌ناحیه استفاده کنید. OPENCLAW_DISABLE_BONJOUR=0 را فقط زمانی تنظیم کنید که با شبکه host، macvlan، یا شبکه دیگری اجرا می‌کنید که در آن مشخص است multicast مربوط به 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 به‌صورت bind-mount متصل می‌کند، بنابراین این مسیرها پس از جایگزینی کانتینر باقی می‌مانند. وقتی هر متغیری تنظیم نشده باشد، docker-compose.yml بسته‌بندی‌شده زیر ${HOME} fallback می‌کند، یا اگر خود HOME هم موجود نباشد به /tmp fallback می‌کند. این کار مانع می‌شود docker compose up در محیط‌های bare یک volume spec با source خالی emit کند.

آن directory پیکربندی mountشده جایی است که OpenClaw این موارد را نگه می‌دارد:

• openclaw.json برای config رفتار
• agents/<agentId>/agent/auth-profiles.json برای احراز هویت OAuth/API-key ذخیره‌شده ارائه‌دهنده
• .env برای secretهای runtime مبتنی بر env مانند OPENCLAW_GATEWAY_TOKEN

directory کلید secret مربوط به auth-profile کلید encryption محلی استفاده‌شده برای token material پروفایل auth مبتنی بر OAuth را ذخیره می‌کند. آن را همراه با state میزبان Docker خود نگه دارید، اما جدا از OPENCLAW_CONFIG_DIR.

Pluginهای قابل‌دانلودِ نصب‌شده، وضعیت بستهٔ خود را زیر خانهٔ mounted OpenClaw ذخیره می‌کنند؛ بنابراین رکوردهای نصب Plugin و ریشه‌های بسته پس از جایگزینی container نیز باقی می‌مانند. راه‌اندازی Gateway، درخت‌های وابستگیِ Pluginهای بسته‌بندی‌شده را تولید نمی‌کند.

برای جزئیات کامل پایداری در استقرارهای VM، ببینید: زمان اجرای Docker VM - چه چیزی کجا پایدار می‌ماند.

نقاط داغ رشد دیسک: media/، فایل‌های JSONL نشست، cron/runs/*.jsonl، ریشه‌های بستهٔ Plugin نصب‌شده، و file logهای چرخشی زیر /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 را از مسیر raw قدیمی‌تر scripts/shell-helpers/clawdock-helpers.sh نصب کرده‌اید، دستور نصب بالا را دوباره اجرا کنید تا فایل helper محلی شما مکان جدید را دنبال کند.

سپس از clawdock-start، clawdock-stop، clawdock-dashboard و غیره استفاده کنید. برای همهٔ فرمان‌ها clawdock-help را اجرا کنید. برای راهنمای کامل helper، 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 اجرا می‌کنید؟

برای مراحل مشترک استقرار VM، از جمله قرار دادن binary در image، پایداری، و به‌روزرسانی‌ها، ببینید: Hetzner (Docker VPS) و زمان اجرای Docker VM.

sandbox عامل

وقتی agents.defaults.sandbox با backend مربوط به Docker فعال باشد، Gateway اجرای ابزارهای عامل (shell، خواندن/نوشتن فایل و غیره) را داخل containerهای Docker ایزوله اجرا می‌کند، در حالی که خود Gateway روی میزبان باقی می‌ماند. این کار یک دیوار سخت دور نشست‌های عامل نامطمئن یا چندمستاجری ایجاد می‌کند، بدون اینکه کل Gateway را containerize کند.

دامنهٔ sandbox می‌تواند برای هر عامل (پیش‌فرض)، برای هر نشست، یا مشترک باشد. هر دامنه workspace خودش را دارد که در /workspace mount می‌شود. همچنین می‌توانید سیاست‌های allow/deny ابزار، ایزوله‌سازی شبکه، محدودیت‌های منبع، و containerهای مرورگر را پیکربندی کنید.

برای پیکربندی کامل، imageها، نکات امنیتی، و profileهای چندعاملی، ببینید:

• Sandboxing -- مرجع کامل sandbox
• OpenShell -- دسترسی shell تعاملی به containerهای sandbox
• Sandbox و ابزارهای چندعاملی -- overrideهای هر عامل

فعال‌سازی سریع

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

ساخت image پیش‌فرض sandbox (از یک source checkout):

scripts/sandbox-setup.sh

برای نصب‌های npm بدون source checkout، فرمان‌های inline docker build را در Sandboxing § imageها و setup ببینید.

عیب‌یابی

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 پس از نصب