Docker

Docker isteğe bağlıdır. Yalnızca kapsayıcılı bir Gateway istiyorsanız veya Docker akışını doğrulamak istiyorsanız kullanın.

Docker benim için uygun mu?

• Evet: yalıtılmış, tek kullanımlık bir Gateway ortamı istiyorsunuz veya OpenClaw'u yerel kurulumlar olmadan bir ana makinede çalıştırmak istiyorsunuz.
• Hayır: kendi makinenizde çalışıyorsunuz ve yalnızca en hızlı geliştirme döngüsünü istiyorsunuz. Bunun yerine normal kurulum akışını kullanın.
• Korumalı alan notu: varsayılan korumalı alan arka ucu, korumalı alan etkinleştirildiğinde Docker kullanır; ancak korumalı alan varsayılan olarak kapalıdır ve tam Gateway'in Docker içinde çalışmasını gerektirmez. SSH ve OpenShell korumalı alan arka uçları da kullanılabilir. Bkz. Korumalı alan.

Ön koşullar

• Docker Desktop (veya Docker Engine) + Docker Compose v2
• Görüntü derlemesi için en az 2 GB RAM (pnpm install, 1 GB ana makinelerde 137 çıkışıyla OOM nedeniyle sonlandırılabilir)
• Görüntüler ve günlükler için yeterli disk alanı
• Bir VPS/genel ana makinede çalıştırıyorsanız, Ağ erişimine açma için güvenlik sıkılaştırması bölümünü, özellikle Docker DOCKER-USER güvenlik duvarı politikasını inceleyin.

Kapsayıcılı 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>"

Manuel akış

Kurulum betiğini kullanmak yerine her adımı kendiniz çalıştırmayı tercih ederseniz:

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

Ortam değişkenleri

Kurulum betiği şu isteğe bağlı ortam değişkenlerini kabul eder:

Resmi Docker görüntüsü Homebrew içermez. İlk kurulum sırasında OpenClaw, brew olmadan bir Linux kapsayıcısında çalıştığında yalnızca brew ile kullanılabilen skill bağımlılığı kurucularını gizler; bu bağımlılıklar özel bir görüntüyle sağlanmalı veya manuel olarak kurulmalıdır. Debian paketlerinden edinilebilen bağımlılıklar için görüntü derlemesi sırasında OPENCLAW_IMAGE_APT_PACKAGES kullanın. Eski OPENCLAW_DOCKER_APT_PACKAGES adı hâlâ kabul edilir. Python bağımlılıkları için OPENCLAW_IMAGE_PIP_PACKAGES kullanın. Bu, görüntü derlemesi sırasında python3 -m pip install --break-system-packages çalıştırır; bu nedenle paket sürümlerini sabitleyin ve yalnızca güvendiğiniz paket indekslerini kullanın. Kaynak derlemeleri varsayılan olarak OPENCLAW_DOCKER_BUILD_NODE_OPTIONS değerini --max-old-space-size=8192 yapar ve tsdown sarmalayıcısının kapsayıcı bellek sınırlarına uyabilmesi için OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB değerini ayarlanmamış bırakır. Ayrıca çalışma zamanı görüntüleri derlemeden sonra bildirim dosyalarını budadığı için OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 varsayılanını kullanırlar. Docker ResourceExhausted, cannot allocate memory bildirirse veya tsdown sırasında işlemi durdurursa, Docker derleyici bellek sınırını artırın ya da daha küçük açık yığınlarla yeniden deneyin; örneğin OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Bakımcılar, bir Plugin kaynak dizinini paketlenmiş kaynak yolunun üzerine bağlayarak paketlenmiş bir görüntüye karşı paketlenmiş Plugin kaynağını test edebilir; örneğin OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Bu bağlanmış kaynak dizini, aynı Plugin kimliği için eşleşen derlenmiş /app/dist/extensions/synology-chat paketini geçersiz kılar.

Gözlemlenebilirlik

OpenTelemetry dışa aktarımı Gateway kapsayıcısından OTLP toplayıcınıza giden yöndedir. Yayımlanmış bir Docker portu gerektirmez. Görüntüyü yerelde derliyorsanız ve paketlenmiş OpenTelemetry dışa aktarıcısının görüntü içinde kullanılabilir olmasını istiyorsanız çalışma zamanı bağımlılıklarını dahil edin:

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

Paketlenmiş Docker kurulumlarında dışa aktarımı etkinleştirmeden önce resmi @openclaw/diagnostics-otel Plugin'ini ClawHub'dan kurun. Özel kaynak derlemeli görüntüler yerel Plugin kaynağını OPENCLAW_EXTENSIONS=diagnostics-otel ile hâlâ dahil edebilir. Dışa aktarımı etkinleştirmek için yapılandırmada diagnostics-otel Plugin'ine izin verin ve etkinleştirin, ardından diagnostics.otel.enabled=true ayarlayın veya OpenTelemetry dışa aktarımı bölümündeki yapılandırma örneğini kullanın. Toplayıcı kimlik doğrulama başlıkları Docker ortam değişkenleriyle değil, diagnostics.otel.headers üzerinden yapılandırılır.

Prometheus metrikleri zaten yayımlanmış Gateway portunu kullanır. clawhub:@openclaw/diagnostics-prometheus kurun, diagnostics-prometheus Plugin'ini etkinleştirin, ardından scrape edin:

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

Rota Gateway kimlik doğrulamasıyla korunur. Ayrı bir genel /metrics portu veya kimlik doğrulamasız reverse-proxy yolu açmayın. Bkz. Prometheus metrikleri.

Sağlık kontrolleri

Kapsayıcı probe uç noktaları (kimlik doğrulama gerekmez):

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

Docker görüntüsü, /healthz adresine ping atan yerleşik bir HEALTHCHECK içerir. Kontroller başarısız olmaya devam ederse Docker kapsayıcıyı unhealthy olarak işaretler ve orkestrasyon sistemleri onu yeniden başlatabilir veya değiştirebilir.

Kimliği doğrulanmış derin sağlık anlık görüntüsü:

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

LAN ile loopback

scripts/docker/setup.sh varsayılan olarak OPENCLAW_GATEWAY_BIND=lan kullanır; böylece http://127.0.0.1:18789 adresine ana makineden erişim Docker bağlantı noktası yayımlama ile çalışır.

• lan (varsayılan): ana makine tarayıcısı ve ana makine CLI yayımlanan gateway bağlantı noktasına erişebilir.
• loopback: yalnızca kapsayıcı ağ ad alanı içindeki süreçler gateway'e doğrudan erişebilir.

Ana Makine Yerel Sağlayıcıları

OpenClaw Docker içinde çalıştığında, kapsayıcı içindeki 127.0.0.1 ana makineniz değil, kapsayıcının kendisidir. Ana makinede çalışan yapay zeka sağlayıcıları için host.docker.internal kullanın:

Paketli Docker kurulumu, bu ana makine URL'lerini LM Studio ve Ollama ilk kurulum varsayılanları olarak kullanır ve docker-compose.yml, Linux Docker Engine için host.docker.internal adını Docker'ın ana makine ağ geçidine eşler. Docker Desktop, macOS ve Windows üzerinde aynı ana makine adını zaten sağlar.

Ana makine hizmetleri ayrıca Docker'dan erişilebilen bir adreste dinlemelidir:

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

Kendi Compose dosyanızı veya docker run komutunuzu kullanıyorsanız, aynı ana makine eşlemesini kendiniz ekleyin; örneğin --add-host=host.docker.internal:host-gateway.

Docker içinde Claude CLI arka ucu

Resmi OpenClaw Docker görüntüsü Claude Code'u önceden yüklemez. Claude Code'u OpenClaw'u çalıştıran kapsayıcı kullanıcısının içinde yükleyip oturum açın, ardından görüntü yükseltmeleri ikili dosyayı veya Claude kimlik doğrulama durumunu silmesin diye bu kapsayıcı home dizinini kalıcı hale getirin.

Yeni Docker kurulumları için, kurulumu çalıştırmadan önce kalıcı bir /home/node birimini etkinleştirin:

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

Mevcut bir Docker kurulumu için önce yığını durdurun ve kurulumu yeniden çalıştırmadan önce geçerli Docker .env değerlerini yeniden yükleyin. Kurulum betiği .env dosyasını kendi başına okumaz; .env dosyasını geçerli kabuktan ve varsayılanlardan yeniden yazar. Oluşturulan .env için şunu çalıştırın:

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

.env dosyanız kabuğunuzun kaynak olarak yükleyemeyeceği değerler içeriyorsa, önce dayandığınız mevcut değerleri elle yeniden dışa aktarın; örneğin OPENCLAW_IMAGE, bağlantı noktaları, bağlama modu, özel yollar, OPENCLAW_EXTRA_MOUNTS, sandbox ve ilk kurulumu atlama ayarları. Oluşturulan overlay, home birimini hem openclaw-gateway hem de openclaw-cli için bağlar.

Kalan komutları oluşturulan Compose overlay'i ile çalıştırın; böylece her iki hizmet de kalıcı home dizinini bağlar. Kurulumunuz ayrıca docker-compose.override.yml kullanıyorsa, onu docker-compose.extra.yml dosyasından önce dahil edin.

Claude Code'u bu kalıcı home dizinine yükleyin:

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'

Yerel yükleyici claude ikili dosyasını /home/node/.local/bin/claude altına yazar. OpenClaw'a bu kapsayıcı yolunu kullanmasını söyleyin:

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

Aynı kalıcı kapsayıcı home dizini içinden oturum açın ve doğrulayın:

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

Bundan sonra, paketli claude-cli arka ucunu kullanabilirsiniz:

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, yerel Claude Code kurulumunu /home/node/.local/bin ve /home/node/.local/share/claude altında, ayrıca Claude Code ayarlarını ve kimlik doğrulama durumunu /home/node/.claude ve /home/node/.claude.json altında kalıcı hale getirir. Yalnızca /home/node/.openclaw dizinini kalıcı hale getirmek, Claude CLI yeniden kullanımı için yeterli değildir. Home birimi yerine OPENCLAW_EXTRA_MOUNTS kullanıyorsanız, bu Claude yollarının tamamını her iki Docker hizmetine bağlayın.

Bonjour / mDNS

Docker bridge ağı genellikle Bonjour/mDNS multicast (224.0.0.251:5353) trafiğini güvenilir şekilde iletmez. Bu nedenle paketli Compose kurulumu varsayılan olarak OPENCLAW_DISABLE_BONJOUR=1 kullanır; böylece bridge multicast trafiğini düşürdüğünde Gateway crash-loop'a girmez veya reklam yayınlamayı tekrar tekrar yeniden başlatmaz.

Docker ana makineleri için yayımlanan Gateway URL'sini, Tailscale'i veya geniş alan DNS-SD kullanın. OPENCLAW_DISABLE_BONJOUR=0 değerini yalnızca host networking, macvlan veya mDNS multicast'in çalıştığı bilinen başka bir ağla çalışırken ayarlayın.

Dikkat edilmesi gereken noktalar ve sorun giderme için Bonjour keşfi bölümüne bakın.

Depolama ve kalıcılık

Docker Compose, OPENCLAW_CONFIG_DIR değerini /home/node/.openclaw konumuna, OPENCLAW_WORKSPACE_DIR değerini /home/node/.openclaw/workspace konumuna ve OPENCLAW_AUTH_PROFILE_SECRET_DIR değerini /home/node/.config/openclaw konumuna bind-mount yapar; böylece bu yollar kapsayıcı değişiminden sonra da korunur. Herhangi bir değişken ayarlanmamışsa, paketli docker-compose.yml ${HOME} altına, HOME değerinin kendisi de eksikse /tmp altına geri döner. Bu, yalın ortamlarda docker compose up komutunun boş kaynaklı bir birim belirtimi yaymasını engeller.

Bu bağlanan yapılandırma dizini, OpenClaw'un şunları tuttuğu yerdir:

• davranış yapılandırması için openclaw.json
• saklanan sağlayıcı OAuth/API anahtarı kimlik doğrulaması için agents/<agentId>/agent/auth-profiles.json
• OPENCLAW_GATEWAY_TOKEN gibi env destekli çalışma zamanı gizli değerleri için .env

Kimlik doğrulama profili gizli anahtar dizini, OAuth destekli kimlik doğrulama profili token malzemesi için kullanılan yerel şifreleme anahtarını saklar. Bunu Docker ana makine durumunuzla birlikte, ancak OPENCLAW_CONFIG_DIR dizininden ayrı tutun.

Yüklenen indirilebilir plugin'ler paket durumlarını bağlanan OpenClaw home dizini altında saklar; böylece plugin yükleme kayıtları ve paket kökleri kapsayıcı değişiminden sonra korunur. Gateway başlangıcı paketli plugin bağımlılık ağaçları oluşturmaz.

VM dağıtımlarında kalıcılık ayrıntılarının tamamı için Docker VM Çalışma Zamanı - Nerede ne kalıcıdır bölümüne bakın.

Disk büyümesi sıcak noktaları: media/, oturum JSONL dosyaları, paylaşılan SQLite durum veritabanı, yüklü plugin paket kökleri ve /tmp/openclaw/ altındaki dönen dosya günlüklerini izleyin.

Kabuk yardımcıları (isteğe bağlı)

Günlük Docker yönetimini kolaylaştırmak için ClawDock yükleyin:

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'u eski scripts/shell-helpers/clawdock-helpers.sh raw yolundan yüklediyseniz, yerel yardımcı dosyanızın yeni konumu izlemesi için yukarıdaki yükleme komutunu yeniden çalıştırın.

Ardından clawdock-start, clawdock-stop, clawdock-dashboard vb. komutları kullanın. Tüm komutlar için clawdock-help çalıştırın. Tam yardımcı kılavuzu için ClawDock bölümüne bakın.

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 üzerinde çalıştırıyor musunuz?

İkiliyi imaja gömme, kalıcılık ve güncellemeler dahil paylaşımlı VM dağıtım adımları için Hetzner (Docker VPS) ve Docker VM Runtime sayfalarına bakın.

Ajan korumalı alanı

agents.defaults.sandbox Docker backend ile etkinleştirildiğinde Gateway, ajan araç yürütmesini (shell, dosya okuma/yazma vb.) yalıtılmış Docker container'ları içinde çalıştırırken Gateway'in kendisi host üzerinde kalır. Bu, Gateway'in tamamını container içine almadan güvenilmeyen veya çok kiracılı ajan oturumlarının etrafında sağlam bir duvar sağlar.

Korumalı alan kapsamı ajan başına (varsayılan), oturum başına veya paylaşımlı olabilir. Her kapsam kendi çalışma alanını /workspace konumuna mount edilmiş olarak alır. Ayrıca izin verme/reddetme araç ilkelerini, ağ yalıtımını, kaynak sınırlarını ve tarayıcı container'larını yapılandırabilirsiniz.

Tam yapılandırma, image'lar, güvenlik notları ve çok ajanlı profiller için bkz.:

• Korumalı alan -- eksiksiz korumalı alan referansı
• OpenShell -- korumalı alan container'larına etkileşimli shell erişimi
• Çok Ajanlı Korumalı Alan ve Araçlar -- ajan başına geçersiz kılmalar

Hızlı etkinleştirme

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

Varsayılan korumalı alan image'ını oluşturun (bir kaynak çalışma kopyasından):

scripts/sandbox-setup.sh

Kaynak çalışma kopyası olmadan npm kurulumları için satır içi docker build komutları hakkında Korumalı alan § Image'lar ve kurulum bölümüne bakın.

Sorun giderme

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

İlgili

• Kurulum Genel Bakışı — tüm kurulum yöntemleri
• Podman — Docker'a Podman alternatifi
• ClawDock — Docker Compose topluluk kurulumu
• Güncelleme — OpenClaw'ı güncel tutma
• Yapılandırma — kurulumdan sonra Gateway yapılandırması