داکر

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

وقتی agents.defaults.sandbox فعال باشد، بک‌اند پیش‌فرض سندباکس از Docker استفاده می‌کند؛ اما سندباکس به‌طور پیش‌فرض غیرفعال است و نیازی ندارد خود Gateway در Docker اجرا شود. بک‌اندهای سندباکس SSH و OpenShell نیز در دسترس‌اند؛ به سندباکس‌سازی مراجعه کنید.

از چند کاربر میزبانی می‌کنید؟ برای مدل یک سلول به‌ازای هر مستأجر، به میزبانی چندمستأجری مراجعه کنید.

پیش‌نیازها

• Docker Desktop (یا Docker Engine) + Docker Compose v2
• حداقل 2 GB حافظهٔ RAM برای ساخت ایمیج (pnpm install ممکن است در میزبان‌های 1 GB با خروج 137 به‌دلیل OOM متوقف شود)
• فضای دیسک کافی برای ایمیج‌ها و گزارش‌ها
• در یک VPS/میزبان عمومی، سخت‌سازی امنیتی برای دسترسی شبکه، به‌ویژه زنجیرهٔ فایروال DOCKER-USER در Docker را بررسی کنید

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

جریان دستی

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -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

زمینهٔ Docker، .git را مستثنا می‌کند. همان‌طور که در بالا نشان داده شد، هویت منبع را به‌صورت آرگومان‌های ساخت ارسال کنید تا صفحهٔ «درباره» ایمیج، کامیت بررسی‌شده و یک برچسب زمانی ساخت را گزارش کند. scripts/docker/setup.sh هر دو مقدار را به‌طور خودکار تعیین و ارسال می‌کند.

ارتقای ایمیج‌های کانتینر

هنگامی که ایمیج OpenClaw را جایگزین می‌کنید اما همان وضعیت/پیکربندی متصل‌شده را نگه می‌دارید، Gateway جدید پیش از آماده‌شدن، مهاجرت‌های ارتقای ایمن برای راه‌اندازی و همگرایی Pluginها را اجرا می‌کند. ارتقاهای معمول ایمیج نباید به اجرای جداگانهٔ openclaw doctor --fix نیاز داشته باشند.

اگر راه‌اندازی نتواند این اصلاحات را با ایمنی کامل کند، Gateway به‌جای گزارش وضعیت سالم خارج می‌شود. با یک خط‌مشی راه‌اندازی مجدد، Docker، Podman یا Kubernetes ممکن است کانتینر Gateway را در حال راه‌اندازی مجدد نشان دهند. حجم وضعیت متصل‌شده را حفظ کنید، سپس همان ایمیج را یک‌بار با openclaw doctor --fix به‌عنوان فرمان کانتینر و با استفاده از همان اتصال‌های وضعیت/پیکربندی مورد استفادهٔ Gateway اجرا کنید:

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

پس از پایان کار doctor، کانتینر Gateway را با فرمان پیش‌فرضش دوباره راه‌اندازی کنید. در Kubernetes، همان فرمان را در یک Job یک‌بارمصرف یا پاد اشکال‌زدایی متصل به همان PVC اجرا کنید، سپس Deployment یا StatefulSet را دوباره راه‌اندازی کنید.

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

متغیرهای اختیاری پذیرفته‌شده توسط scripts/docker/setup.sh (و برای کانتینر Gateway، مستقیماً توسط docker-compose.yml):

ایمیج رسمی شامل Homebrew نیست. هنگام راه‌اندازی اولیه، OpenClaw نصب‌کننده‌های وابستگی Skills مختص brew را در یک کانتینر Linux بدون brew پنهان می‌کند؛ این وابستگی‌ها را از طریق یک ایمیج سفارشی فراهم کنید یا به‌صورت دستی نصب کنید. برای وابستگی‌های بسته‌بندی‌شدهٔ Debian از OPENCLAW_IMAGE_APT_PACKAGES و برای وابستگی‌های Python از OPENCLAW_IMAGE_PIP_PACKAGES استفاده کنید (python3 -m pip install --break-system-packages را هنگام ساخت اجرا می‌کند؛ بنابراین نسخه‌ها را سنجاق کنید و فقط از ایندکس‌هایی استفاده کنید که به آن‌ها اعتماد دارید).

اگر Docker خطاهای ResourceExhausted یا cannot allocate memory را گزارش کرد، یا هنگام tsdown متوقف شد، محدودیت حافظهٔ سازندهٔ Docker را افزایش دهید یا با heapهای صریح کوچک‌تر دوباره تلاش کنید:

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

ایمیج‌های ساخته‌شده از منبع با Pluginهای منتخب

OPENCLAW_EXTENSIONS شناسه‌های مانیفست Plugin را از checkout منبع انتخاب می‌کند؛ نام‌های موجود دایرکتوری منبع نیز، در صورت متفاوت‌بودن، پذیرفته می‌شوند. فرایند ساخت Docker انتخاب را یک‌بار به دایرکتوری‌های منبع نگاشت می‌کند، وابستگی‌های production را نصب می‌کند و، وقتی Plugin انتخاب‌شده جداگانه با openclaw.build.bundledDist: false منتشر شده باشد، runtime آن را در dist همراه‌شده ریشه کامپایل می‌کند. این بسته‌بندی مختص Docker قرارداد artifact مربوط به npm یا ClawHub این Plugin را تغییر نمی‌دهد. شناسه‌های ناشناخته، نامعتبر یا مبهم باعث شکست ساخت image می‌شوند. شناسه‌های شناخته‌شده‌ای که فقط برای وابستگی/منبع هستند، staging فعلی منبع و وابستگی خود را بدون دریافت ورودی dist کامپایل‌شده در ریشه حفظ می‌کنند. یک Plugin انتخاب‌شده با ورودی‌های ساخت یکپارچه باید با موفقیت کامپایل شود؛ منبع و خروجی runtime مربوط به Pluginهای خارجی انتخاب‌نشده حذف می‌شوند.

برای نمونه، این فرمان‌ها imageهای مستقل و چندمعماریِ جداگانه‌ای از Gatewayهای FakeCo برای ClickClack، Slack و Microsoft Teams می‌سازند. ClawRouter از قبل بخشی از runtime ریشه OpenClaw است، بنابراین image مربوط به ClickClack فقط clickclack را انتخاب می‌کند. آرگومان صریحاً خالی مرورگر باعث می‌شود image پیش‌فرض فاقد Chromium بماند:

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

برای یک ساخت محلی native منفرد، از --platform linux/arm64 --load یا --platform linux/amd64 --load استفاده کنید. خروجی چندپلتفرمی و SBOM/provenance پیوست‌شده به یک registry یا خروجی دیگری از Buildx نیاز دارند که attestationها را حفظ کند. پس از push، مانیفست را بررسی کنید و به‌جای tag تغییرپذیر source-SHA، digest تغییرناپذیر را مستقر کنید:

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# استقرار: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

این imageها برای Gatewayهای مستقل مبتنی بر OCI و کاربران عمومی Docker هستند. Gatewayهای مدیریت‌شده با Crabhelm از آن‌ها استفاده نمی‌کنند: آن مسیر تحویل، یک archive مجزای appliance برای x86_64 می‌سازد که حاوی tarball مربوط به npm از OpenClaw است و digestهای Node، archive و مانیفست را ثابت می‌کند. آن appliance را مستقلاً از همان منبع نهایی‌شده OpenClaw بسازید.

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

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

ارسال OpenTelemetry از کانتینر Gateway به collector مربوط به OTLP شما خروجی است؛ به هیچ پورت منتشرشده Docker نیاز ندارد. برای گنجاندن exporter همراه‌شده در یک image ساخته‌شده به‌صورت محلی:

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

imageهای رسمی ازپیش‌ساخته‌شده از قبل diagnostics-otel را همراه دارند؛ فقط اگر آن را حذف کرده‌اید، خودتان clawhub:@openclaw/diagnostics-otel را نصب کنید. برای فعال‌کردن ارسال، Plugin مربوط به diagnostics-otel را در پیکربندی مجاز و فعال کنید، سپس diagnostics.otel.enabled=true را تنظیم کنید (نمونه کامل را در ارسال OpenTelemetry ببینید). هدرهای احراز هویت collector از طریق diagnostics.otel.headers ارائه می‌شوند، نه متغیرهای محیطی Docker.

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

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

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

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

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

curl -fsS http://127.0.0.1:18789/healthz   # زنده‌بودنcurl -fsS http://127.0.0.1:18789/readyz     # آمادگی

HEALTHCHECK داخلی image، /healthz را ping می‌کند؛ شکست‌های تکراری کانتینر را unhealthy علامت‌گذاری می‌کنند تا orchestratorها بتوانند آن را راه‌اندازی مجدد یا جایگزین کنند.

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 روی میزبان با انتشار پورت Docker کار کند.

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

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

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

راه‌اندازی همراه‌شده از آن URLها به‌عنوان پیش‌فرض‌های onboarding برای LM Studio/Ollama استفاده می‌کند و docker-compose.yml، مقدار host.docker.internal را در Docker Engine روی Linux به Gateway میزبان نگاشت می‌کند (Docker Desktop همین alias را در 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.

backend مربوط به Claude CLI در Docker

image رسمی، Claude Code را از پیش نصب نمی‌کند. آن را در کاربر node کانتینر نصب کنید و وارد حساب شوید، سپس home کانتینر را ماندگار کنید تا ارتقای image فایل اجرایی یا وضعیت احراز هویت را پاک نکند.

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

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

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

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، ردکردن onboarding). overlay تولیدشده، volume مربوط به home را برای هر دو openclaw-gateway و openclaw-cli mount می‌کند؛ فرمان‌های باقی‌مانده را با همان overlay اجرا کنید (و اگر از docker-compose.override.yml استفاده می‌کنید، ابتدا آن را نیز اضافه کنید):

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، claude را در /home/node/.local/bin/claude می‌نویسد. image مربوط به OpenClaw شامل /home/node/.local/bin در PATH است، بنابراین Plugin همراه‌شده Anthropic بدون بازنویسی پیکربندی adapter آن را resolve می‌کند.

با همان 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

سپس از backend همراه‌شده 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 "از Docker Claude CLI سلام کن"

OPENCLAW_HOME_VOLUME نصب native را در /home/node/.local/bin و /home/node/.local/share/claude، و همچنین تنظیمات/احراز هویت Claude Code را در /home/node/.claude و /home/node/.claude.json ماندگار می‌کند. ماندگارکردن فقط /home/node/.openclaw کافی نیست؛ اگر به‌جای volume مربوط به home از OPENCLAW_EXTRA_MOUNTS استفاده می‌کنید، همه آن مسیرهای Claude را در هر دو سرویس mount کنید.

Bonjour / mDNS

شبکه‌سازی bridge در Docker معمولاً multicast مربوط به Bonjour/mDNS (224.0.0.251:5353) را به‌طور قابل‌اعتماد forward نمی‌کند. وقتی OPENCLAW_DISABLE_BONJOUR تنظیم نشده باشد، Plugin همراه‌شده Bonjour پس از تشخیص اجرا در کانتینر، تبلیغ LAN را به‌طور خودکار غیرفعال می‌کند تا برای multicastای که bridge کنار می‌گذارد وارد چرخه crash و retry نشود. برای غیرفعال‌کردن اجباری آن، مستقل از تشخیص، OPENCLAW_DISABLE_BONJOUR=1 را تنظیم کنید؛ یا برای فعال‌کردن اجباری آن 0 را تنظیم کنید (فقط در شبکه‌سازی میزبان، macvlan یا شبکه دیگری که کارکرد multicast مربوط به mDNS در آن تأیید شده است).

در غیر این صورت برای میزبان‌های Docker از URL منتشرشده Gateway،‏ Tailscale یا DNS-SD گسترده استفاده کنید. برای نکات ظریف و عیب‌یابی، کشف 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، تا docker compose up هرگز در محیط‌های خام یک مشخصه volume با منبع خالی تولید نکند.

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

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

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

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

برای جزئیات کامل ماندگاری VM،‏ runtime ماشین مجازی Docker ــ چه چیزی کجا ماندگار می‌شود را ببینید.

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

ابزارهای کمکی shell (اختیاری)

برای کوتاه‌ترشدن فرمان‌های روزمره، 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

اگر از مسیر قدیمی‌تر scripts/shell-helpers/clawdock-helpers.sh نصب کرده‌اید، فرمان بالا را دوباره اجرا کنید تا ابزار کمکی محلی شما مسیر فعلی را دنبال کند. سپس از clawdock-start،‏ clawdock-stop،‏ clawdock-dashboard و موارد دیگر استفاده کنید (برای فهرست کامل clawdock-help را اجرا کنید).

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

سندباکس عامل

وقتی 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      },    },  },}

ایمیج پیش‌فرض سندباکس را بسازید (از یک 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 پس از نصب