Docker

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

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

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

# پیش‌نیازها

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

# 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>"

# جریان دستی

اگر ترجیح می‌دهید به‌جای استفاده از اسکریپت 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-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

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

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

نگه‌دارندگان می‌توانند منبع 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 override می‌کند.

# Observability

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

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

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

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

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

# Health checkها

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

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

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

snapshot عمیق سلامت با authentication:

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 (پیش‌فرض): browser میزبان و CLI میزبان می‌توانند به پورت منتشرشده Gateway دسترسی داشته باشند.
• loopback: فقط processهای داخل فضای نام شبکه container می‌توانند مستقیماً به Gateway دسترسی داشته باشند.

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

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

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

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

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

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

# Bonjour / mDNS

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

برای میزبان‌های Docker از URL منتشرشده Gateway، Tailscale، یا wide-area DNS-SD استفاده کنید. OPENCLAW_DISABLE_BONJOUR=0 را فقط زمانی تنظیم کنید که با host networking، macvlan، یا شبکه دیگری اجرا می‌کنید که می‌دانید multicast مربوط به mDNS در آن کار می‌کند.

برای نکات مشکل‌ساز و عیب‌یابی، کشف Bonjour را ببینید.

# Storage و persistence

Docker Compose مقدار OPENCLAW_CONFIG_DIR را به /home/node/.openclaw و OPENCLAW_WORKSPACE_DIR را به /home/node/.openclaw/workspace به‌صورت bind-mount متصل می‌کند، بنابراین آن مسیرها پس از جایگزینی container باقی می‌مانند. وقتی هرکدام از این متغیرها تنظیم نشده باشد، فایل همراه docker-compose.yml به ${HOME}/.openclaw (و ${HOME}/.openclaw/workspace برای mount فضای کاری) fallback می‌کند، یا وقتی خود HOME نیز وجود نداشته باشد به /tmp/.openclaw fallback می‌کند. این کار مانع از آن می‌شود که docker compose up در محیط‌های bare یک مشخصه volume با source خالی صادر کند.

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

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

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

برای جزئیات کامل persistence در deploymentهای 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 را از مسیر خام قدیمی‌تر 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 اجرا می‌کنید؟

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

# سندباکس عامل

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

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

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

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

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

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

image پیش‌فرض سندباکس را بسازید (از checkout سورس):

scripts/sandbox-setup.sh

برای نصب‌های npm بدون checkout سورس، فرمان‌های inline مربوط به docker build را در سندباکس‌سازی § imageها و راه‌اندازی ببینید.

# عیب‌یابی

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