Ana içeriğe atla
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

1

Görüntüyü derleyin

Repo kökünden kurulum betiğini çalıştırın:
./scripts/docker/setup.sh
Bu, Gateway görüntüsünü yerel olarak derler. Bunun yerine önceden derlenmiş bir görüntü kullanmak için:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
Önceden derlenmiş görüntüler önce GitHub Container Registry üzerinde yayımlanır. GHCR; sürüm otomasyonu, sabitlenmiş dağıtımlar ve kaynak doğrulama kontrolleri için birincil kayıt deposudur. Aynı sürüm iş akışı, Docker Hub’ı tercih eden ana makineler için openclaw/openclaw adresinde resmi bir Docker Hub aynası da yayımlar:
export OPENCLAW_IMAGE="openclaw/openclaw:latest"
./scripts/docker/setup.sh
ghcr.io/openclaw/openclaw veya openclaw/openclaw kullanın. Topluluk Docker Hub aynalarından kaçının; çünkü OpenClaw bunların sürüm zamanlamasını, yeniden derlemelerini veya saklama politikasını kontrol etmez. Yaygın resmi etiketler: main, latest, <version> (örn. 2026.2.26) ve 2026.2.26-beta.1 gibi beta sürümleri. Beta etiketleri latest veya main etiketlerini taşımaz.
2

İnternete kapalı ortamda yeniden çalıştırma

Çevrimdışı ana makinelerde önce görüntüyü aktarın ve yükleyin:
docker load -i openclaw-image.tar
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh --offline
--offline, OPENCLAW_IMAGE değerinin yerelde zaten mevcut olduğunu doğrular, örtük Compose çekmelerini ve derlemelerini devre dışı bırakır, ardından .env eşitlemesi, izin düzeltmeleri, ilk kurulum, Gateway yapılandırma eşitlemesi ve Compose başlatma gibi normal kurulum akışını çalıştırır.OPENCLAW_SANDBOX=1 ise çevrimdışı kurulum ayrıca OPENCLAW_DOCKER_SOCKET arkasındaki daemon üzerinde yapılandırılmış varsayılan ve etkin ajan başına korumalı alan görüntülerini kontrol eder. Docker destekli tarayıcı görüntüleri güncel OpenClaw tarayıcı sözleşmesi etiketini de taşımalıdır. Gerekli bir görüntü eksik veya uyumsuz olduğunda kurulum, kullanılamaz bir korumalı alanla başarı bildirmek yerine korumalı alan yapılandırmasını değiştirmeden çıkar.
3

İlk kurulumu tamamlayın

Kurulum betiği ilk kurulumu otomatik olarak çalıştırır. Şunları yapar:
  • sağlayıcı API anahtarlarını ister
  • bir Gateway belirteci oluşturur ve bunu .env dosyasına yazar
  • auth-profile gizli anahtar dizinini oluşturur
  • Gateway’i Docker Compose ile başlatır
Kurulum sırasında, başlatma öncesi ilk kurulum ve yapılandırma yazma işlemleri doğrudan openclaw-gateway üzerinden çalışır. openclaw-cli, Gateway kapsayıcısı zaten var olduktan sonra çalıştırdığınız komutlar içindir.
4

Control UI'ı açın

Tarayıcınızda http://127.0.0.1:18789/ adresini açın ve yapılandırılmış paylaşılan gizli anahtarı Ayarlar’a yapıştırın. Kurulum betiği varsayılan olarak .env dosyasına bir belirteç yazar; kapsayıcı yapılandırmasını parola kimlik doğrulamasına geçirirseniz bunun yerine o parolayı kullanın.URL’ye tekrar mı ihtiyacınız var?
docker compose run --rm openclaw-cli dashboard --no-open
5

Kanalları yapılandırın (isteğe bağlı)

Mesajlaşma kanalları eklemek için CLI kapsayıcısını kullanın:
# 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>"
Dokümanlar: WhatsApp, Telegram, Discord

​
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-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
docker compose komutunu repo kökünden çalıştırın. OPENCLAW_EXTRA_MOUNTS veya OPENCLAW_HOME_VOLUME etkinleştirdiyseniz kurulum betiği docker-compose.extra.yml yazar; bunu standart override dosyalarından sonra dahil edin; örneğin iki override dosyası da mevcutsa -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.extra.yml kullanın.
openclaw-cli, openclaw-gateway ile aynı ağ ad alanını paylaştığı için başlatma sonrası bir araçtır. docker compose up -d openclaw-gateway komutundan önce ilk kurulumu ve kurulum zamanı yapılandırma yazma işlemlerini --no-deps --entrypoint node ile openclaw-gateway üzerinden çalıştırın.

​
Ortam değişkenleri

Kurulum betiği şu isteğe bağlı ortam değişkenlerini kabul eder:
DeğişkenAmaç
OPENCLAW_IMAGEYerelde derlemek yerine uzak bir görüntü kullanır
OPENCLAW_IMAGE_APT_PACKAGESDerleme sırasında ek apt paketleri kurar (boşlukla ayrılmış)
OPENCLAW_IMAGE_PIP_PACKAGESDerleme sırasında ek Python paketleri kurar (boşlukla ayrılmış)
OPENCLAW_EXTENSIONSDerleme zamanında Plugin bağımlılıklarını önceden kurar (boşlukla ayrılmış adlar)
OPENCLAW_DOCKER_BUILD_NODE_OPTIONSYerel kaynak derlemesi Node seçeneklerini geçersiz kılar
OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MBYerel kaynak derlemesi tsdown yığınını MB cinsinden geçersiz kılar
OPENCLAW_DOCKER_BUILD_SKIP_DTSYalnızca çalışma zamanı yerel görüntü derlemelerinde bildirim çıktısını atlar
OPENCLAW_EXTRA_MOUNTSEk ana makine bind bağlamaları (virgülle ayrılmış source:target[:opts])
OPENCLAW_HOME_VOLUME/home/node dizinini adlandırılmış bir Docker volume içinde kalıcı yapar
OPENCLAW_SANDBOXKorumalı alan önyüklemesine katılır (1, true, yes, on)
OPENCLAW_SKIP_ONBOARDINGEtkileşimli ilk kurulum adımını atlar (1, true, yes, on)
OPENCLAW_DOCKER_SOCKETDocker socket yolunu geçersiz kılar
OPENCLAW_DISABLE_BONJOURBonjour/mDNS duyurusunu devre dışı bırakır (Docker için varsayılan 1)
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYSPaketlenmiş Plugin kaynak bind-mount overlay’lerini devre dışı bırakır
OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry dışa aktarımı için paylaşılan OTLP/HTTP toplayıcı uç noktası
OTEL_EXPORTER_OTLP_*_ENDPOINTİzler, metrikler veya günlükler için sinyale özgü OTLP uç noktaları
OTEL_EXPORTER_OTLP_PROTOCOLOTLP protokolünü geçersiz kılar. Bugün yalnızca http/protobuf desteklenir
OTEL_SERVICE_NAMEOpenTelemetry kaynakları için kullanılan hizmet adı
OTEL_SEMCONV_STABILITY_OPT_INEn son deneysel GenAI semantik özniteliklerine katılır
OPENCLAW_OTEL_PRELOADEDBir OpenTelemetry SDK zaten önceden yüklenmişse ikinci bir SDK başlatmayı atlar
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   # liveness
curl -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.
gateway.bind içinde bağlama modu değerlerini kullanın (lan / loopback / custom / tailnet / auto); 0.0.0.0 veya 127.0.0.1 gibi ana makine takma adlarını kullanmayın.

​
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:
SağlayıcıAna makine varsayılan URL’siDocker kurulum URL’si
LM Studiohttp://127.0.0.1:1234http://host.docker.internal:1234
Ollamahttp://127.0.0.1:11434http://host.docker.internal:11434
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.0
OLLAMA_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
. ./.env
set +a
export 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 login
docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --text
docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  openclaw-cli models auth login \
  --provider anthropic --method cli --set-default
docker 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.
Paylaşımlı üretim otomasyonu veya öngörülebilir Anthropic faturalaması için Anthropic API anahtarı yolunu tercih edin. Claude CLI yeniden kullanımı Claude Code’un yüklü sürümünü, hesap oturumunu, faturalamasını ve güncelleme davranışını izler.

​
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.sh
echo '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
Özel soket yolu (ör. rootless Docker):
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
Betik docker.sock dosyasını yalnızca sandbox ön koşulları geçtikten sonra bağlar. Sandbox kurulumu tamamlanamazsa betik agents.defaults.sandbox.mode değerini off olarak sıfırlar. OpenClaw sandbox’ı etkin olduğu sürece Codex kod modu turları yine Codex workspace-write ile sınırlıdır; ana makine Docker soketini agent sandbox kapsayıcılarına bağlamayın.
Compose sözde TTY ayırmasını -T ile devre dışı bırakın:
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
openclaw-cli, CLI komutlarının 127.0.0.1 üzerinden gateway’e erişebilmesi için network_mode: "service:openclaw-gateway" kullanır. Bunu paylaşımlı bir güven sınırı olarak ele alın. Compose yapılandırması hem openclaw-gateway hem de openclaw-cli üzerinde NET_RAW/NET_ADMIN özelliklerini kaldırır ve no-new-privileges etkinleştirir.
Bazı Docker Desktop kurulumları, NET_RAW kaldırıldıktan sonra paylaşımlı ağdaki openclaw-cli yan kapsayıcısından DNS sorgularında başarısız olur; bu da openclaw plugins install gibi npm destekli komutlar sırasında EAI_AGAIN olarak görünür. Normal gateway çalışması için varsayılan sıkılaştırılmış compose dosyasını koruyun. Aşağıdaki yerel override, Docker’ın varsayılan yeteneklerini geri yükleyerek CLI kapsayıcısının güvenlik duruşunu gevşetir; bu yüzden bunu varsayılan Compose çağrınız olarak değil, yalnızca paket kayıt defteri erişimi gerektiren tek seferlik CLI komutu için kullanın:
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>
Zaten uzun süre çalışan bir openclaw-cli kapsayıcısı oluşturduysanız, onu aynı override ile yeniden oluşturun. docker compose exec ve docker exec, önceden oluşturulmuş bir kapsayıcıda Linux yeteneklerini değiştiremez.
Görüntü node olarak çalışır (uid 1000). /home/node/.openclaw üzerinde izin hataları görürseniz, ana makine bind mount’larınızın uid 1000’e ait olduğundan emin olun:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
Aynı uyumsuzluk, şu tür bir plugin uyarısı olarak da görünebilir: blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) ve ardından plugin present but blocked. Bu, süreç uid’si ile bağlanan plugin dizini sahibinin uyuşmadığı anlamına gelir. Kapsayıcıyı varsayılan uid 1000 olarak çalıştırmayı ve bind mount sahipliğini düzeltmeyi tercih edin. Yalnızca OpenClaw’u uzun vadede kasıtlı olarak root olarak çalıştırıyorsanız /path/to/openclaw-config/npm dizinini root:root olarak chown yapın.
Dockerfile’ınızı bağımlılık katmanları önbelleğe alınacak şekilde sıralayın. Bu, lockfile’lar değişmediği sürece pnpm install komutunun yeniden çalıştırılmasını önler:
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"]
Varsayılan image güvenliği önceler ve root olmayan node olarak çalışır. Daha kapsamlı özelliklere sahip bir container için:
  1. /home/node dizinini kalıcı yapın: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. Sistem bağımlılıklarını imaja gömün: export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq"
  3. Python bağımlılıklarını imaja gömün: export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0"
  4. Playwright Chromium’u imaja gömün: export OPENCLAW_INSTALL_BROWSER=1
  5. Veya Playwright tarayıcılarını kalıcı bir volume içine kurun: 
    docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
  6. Tarayıcı indirmelerini kalıcı yapın: OPENCLAW_HOME_VOLUME veya OPENCLAW_EXTRA_MOUNTS kullanın. OpenClaw, Linux’ta Docker image’ın Playwright tarafından yönetilen Chromium’unu otomatik algılar.
Sihirbazda OpenAI Codex OAuth’u seçerseniz bir tarayıcı URL’si açılır. Docker veya headless kurulumlarda, ulaştığınız tam yönlendirme URL’sini kopyalayın ve kimlik doğrulamayı tamamlamak için sihirbaza geri yapıştırın.
Ana Docker runtime image’ı node:24-bookworm-slim kullanır ve uzun süre çalışan container’larda zombi süreçlerin temizlenmesini ve sinyallerin doğru işlenmesini sağlamak için entrypoint init süreci (PID 1) olarak tini içerir. org.opencontainers.image.base.name, org.opencontainers.image.source ve diğerleri dahil OCI temel image anotasyonlarını yayımlar. Node temel özeti Dependabot Docker temel image PR’leriyle yenilenir; release build’leri bir dağıtım yükseltme katmanı çalıştırmaz. Bkz. OCI image anotasyonları.

​
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.:

​
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

Korumalı alan image’ını scripts/sandbox-setup.sh (kaynak çalışma kopyası) ile veya Korumalı alan § Image’lar ve kurulum bölümündeki satır içi docker build komutuyla (npm kurulumu) oluşturun ya da agents.defaults.sandbox.docker.image değerini özel image’ınıza ayarlayın. Container’lar ihtiyaç halinde oturum başına otomatik oluşturulur.
docker.user değerini mount edilmiş çalışma alanınızın sahipliğiyle eşleşen bir UID:GID olarak ayarlayın veya çalışma alanı klasörünün sahipliğini değiştirin.
OpenClaw komutları sh -lc (login shell) ile çalıştırır; bu da /etc/profile dosyasını kaynak olarak kullanır ve PATH’i sıfırlayabilir. Özel araç yollarınızı başa eklemek için docker.env.PATH ayarlayın veya Dockerfile’ınızda /etc/profile.d/ altına bir script ekleyin.
VM için en az 2 GB RAM gerekir. Daha büyük bir makine sınıfı kullanın ve tekrar deneyin.
Yeni bir dashboard bağlantısı alın ve tarayıcı cihazını onaylayın:
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>
Daha fazla ayrıntı: Dashboard, Cihazlar.
Gateway modunu ve bind değerini sıfırlayın:
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