Docker

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

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

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

پیش‌نیازها

• Docker Desktop (یا Docker Engine) + Docker Compose v2
• حداقل ۲ GB RAM برای ساخت image (pnpm install ممکن است روی میزبان‌های ۱ GB با کد خروج ۱۳۷ به‌دلیل OOM کشته شود)
• فضای دیسک کافی برای imageها و لاگ‌ها
• اگر روی 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>"

جریان دستی

اگر ترجیح می‌دهید هر مرحله را خودتان به‌جای استفاده از اسکریپت setup اجرا کنید:

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

متغیرهای محیطی

اسکریپت setup این متغیرهای محیطی اختیاری را می‌پذیرد:

image رسمی Docker، Homebrew را همراه خود ندارد. هنگام onboarding، OpenClaw نصب‌کننده‌های وابستگی skill فقط مخصوص brew را وقتی در یک کانتینر Linux بدون brew اجرا می‌شود پنهان می‌کند؛ این وابستگی‌ها باید از طریق یک image سفارشی فراهم شوند یا به‌صورت دستی نصب شوند. برای وابستگی‌هایی که از بسته‌های Debian در دسترس‌اند، هنگام build image از OPENCLAW_IMAGE_APT_PACKAGES استفاده کنید. نام قدیمی OPENCLAW_DOCKER_APT_PACKAGES هنوز پذیرفته می‌شود. برای وابستگی‌های Python، از OPENCLAW_IMAGE_PIP_PACKAGES استفاده کنید. این کار هنگام build image python3 -m pip install --break-system-packages را اجرا می‌کند، بنابراین نسخه‌های package را pin کنید و فقط از indexهای package که به آن‌ها اعتماد دارید استفاده کنید. source buildها مقدار پیش‌فرض OPENCLAW_DOCKER_BUILD_NODE_OPTIONS را --max-old-space-size=8192 قرار می‌دهند و OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB را unset می‌گذارند تا wrapper مربوط به tsdown بتواند محدودیت‌های حافظه کانتینر را رعایت کند. همچنین به‌طور پیش‌فرض OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 را تنظیم می‌کنند، زیرا imageهای runtime پس از build، فایل‌های declaration را prune می‌کنند. اگر Docker خطاهای ResourceExhausted، cannot allocate memory گزارش کرد یا هنگام tsdown متوقف شد، محدودیت حافظه builder در Docker را افزایش دهید یا با heapهای صریح کوچک‌تر دوباره تلاش کنید، برای مثال OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

نگه‌دارندگان می‌توانند منبع Plugin bundled را در برابر یک image بسته‌بندی‌شده با mount کردن یک دایرکتوری منبع Plugin روی مسیر منبع بسته‌بندی‌شده آن آزمایش کنند، برای مثال OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. آن دایرکتوری منبع mount‌شده، bundle کامپایل‌شده متناظر /app/dist/extensions/synology-chat را برای همان شناسه Plugin بازنویسی می‌کند.

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

export مربوط به OpenTelemetry از کانتینر Gateway به collector مبتنی بر OTLP شما خروجی است. این کار به پورت Docker منتشرشده نیاز ندارد. اگر image را به‌صورت محلی می‌سازید و می‌خواهید exporter bundled مربوط به OpenTelemetry داخل image در دسترس باشد، وابستگی‌های 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

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

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

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

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

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

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

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

تصویر Docker شامل یک HEALTHCHECK داخلی است که /healthz را ping می‌کند. اگر بررسی‌ها همچنان شکست بخورند، 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های میزبان به‌عنوان پیش‌فرض‌های onboarding برای LM Studio و Ollama استفاده می‌کند، و docker-compose.yml، host.docker.internal را برای Docker Engine روی Linux به Gateway میزبان Docker نگاشت می‌کند. Docker Desktop از قبل همین hostname را روی 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

تصویر رسمی Docker برای OpenClaw، Claude Code را از پیش نصب نمی‌کند. Claude Code را داخل کاربر کانتینری که OpenClaw را اجرا می‌کند نصب کنید و وارد شوید، سپس home همان کانتینر را پایدار کنید تا ارتقاهای تصویر، binary یا وضعیت احراز هویت Claude را پاک نکنند.

برای نصب‌های جدید Docker، پیش از اجرای setup یک volume پایدار برای /home/node فعال کنید:

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

برای نصب Docker موجود، ابتدا stack را متوقف کنید و پیش از اجرای دوباره setup، مقادیر فعلی Docker .env را دوباره بارگذاری کنید. اسکریپت setup خودش .env را نمی‌خواند؛ بلکه .env را از shell فعلی و پیش‌فرض‌ها بازنویسی می‌کند. برای .env تولیدشده، اجرا کنید:

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

اگر .env شما مقادیری دارد که shell نمی‌تواند source کند، ابتدا مقادیر موجودی را که به آن‌ها تکیه دارید به‌صورت دستی دوباره export کنید، مانند OPENCLAW_IMAGE، پورت‌ها، حالت bind، مسیرهای سفارشی، OPENCLAW_EXTRA_MOUNTS، sandbox، و تنظیمات skip-onboarding. overlay تولیدشده، volume مربوط به home را برای هر دو سرویس openclaw-gateway و openclaw-cli mount می‌کند.

فرمان‌های باقی‌مانده را با overlay تولیدشده Compose اجرا کنید تا هر دو سرویس home پایدار را mount کنند. اگر راه‌اندازی شما از docker-compose.override.yml هم استفاده می‌کند، آن را پیش از docker-compose.extra.yml وارد کنید.

Claude Code را در همان home پایدار نصب کنید:

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'

نصب‌کننده native، binary مربوط به 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

از داخل همان home پایدار کانتینر وارد شوید و بررسی کنید:

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 نصب native مربوط به 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 کافی نیست. اگر به‌جای volume مربوط به home از OPENCLAW_EXTRA_MOUNTS استفاده می‌کنید، همه این مسیرهای Claude را در هر دو سرویس Docker mount کنید.

Bonjour / mDNS

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

برای میزبان‌های Docker از URL منتشرشده Gateway، Tailscale، یا wide-area DNS-SD استفاده کنید. OPENCLAW_DISABLE_BONJOUR=0 را فقط وقتی تنظیم کنید که با host networking، 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}، یا وقتی خود HOME هم موجود نباشد به /tmp fallback می‌کند. این کار مانع می‌شود docker compose up در محیط‌های bare، مشخصات volume با source خالی منتشر کند.

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

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

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

Pluginهای قابل دانلود نصب‌شده، وضعیت package خود را زیر home نصب‌شده OpenClaw ذخیره می‌کنند، بنابراین سوابق نصب Plugin و ریشه‌های package پس از جایگزینی کانتینر باقی می‌مانند. راه‌اندازی Gateway درخت‌های dependency مربوط به bundled-plugin را تولید نمی‌کند.

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

نقاط داغ رشد دیسک: media/، فایل‌های JSONL نشست، پایگاه‌داده SQLite وضعیت مشترک، ریشه‌های package مربوط به Plugin نصب‌شده، و logهای فایل چرخشی زیر /tmp/openclaw/ را زیر نظر بگیرید.

helperهای 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، ماندگاری، و به‌روزرسانی‌ها، Hetzner (Docker VPS) و زمان اجرای Docker VM را ببینید.

سندباکس عامل

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

دامنه سندباکس می‌تواند برای هر عامل (پیش‌فرض)، برای هر نشست، یا مشترک باشد. هر دامنه workspace مخصوص خود را دریافت می‌کند که در /workspace mount می‌شود. همچنین می‌توانید سیاست‌های مجاز/غیرمجاز ابزار، جداسازی شبکه، محدودیت‌های منابع، و کانتینرهای مرورگر را پیکربندی کنید.

برای پیکربندی کامل، تصاویر، نکات امنیتی، و پروفایل‌های چندعاملی، ببینید:

• سندباکس‌سازی -- مرجع کامل سندباکس
• OpenShell -- دسترسی shell تعاملی به کانتینرهای سندباکس
• سندباکس و ابزارهای چندعاملی -- بازنویسی‌های هر عامل

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

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

تصویر پیش‌فرض سندباکس را بسازید (از یک checkout منبع):

scripts/sandbox-setup.sh

برای نصب‌های npm بدون checkout منبع، برای دستورهای درون‌خطی 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 پس از نصب