Containers
Docker
Docker isteğe bağlıdır. Yalıtılmış, geçici bir gateway ortamı veya yerel kurulumların bulunmadığı bir ana makine için kullanın. Zaten kendi makinenizde geliştirme yapıyorsanız bunun yerine normal kurulum akışını kullanın.
Varsayılan sandbox arka ucu, agents.defaults.sandbox etkinleştirildiğinde Docker kullanır; ancak sandbox varsayılan olarak kapalıdır ve gateway'in kendisinin Docker'da çalışmasını gerektirmez. SSH ve OpenShell sandbox arka uçları da kullanılabilir; bkz. Sandbox Kullanımı.
Birden çok kullanıcıyı mı barındırıyorsunuz? Kiracı başına bir hücre modeli için bkz. Çok kiracılı barındırma.
Ön Koşullar
- Docker Desktop (veya Docker Engine) + Docker Compose v2
- İmaj derlemesi için en az 2 GB RAM (
pnpm install, 1 GB kapasiteli ana makinelerde 137 çıkış koduyla yetersiz bellek nedeniyle sonlandırılabilir) - İmajlar ve günlükler için yeterli disk alanı
- Bir VPS veya genel ana makinede, özellikle Docker
DOCKER-USERgüvenlik duvarı zinciri olmak üzere ağa açılmaya yönelik güvenlik sağlamlaştırmasını inceleyin
Kapsayıcılaştırılmış gateway
İmajı derleyin
Depo kökünden:
./scripts/docker/setup.shBu, gateway imajını yerel olarak openclaw:local adıyla derler. Bunun yerine önceden derlenmiş bir imaj kullanmak için:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.shÖnceden derlenmiş imajlar ilk olarak GitHub Container Registry üzerinde yayımlanır. GHCR; sürüm otomasyonu, sabitlenmiş dağıtımlar ve kaynak doğrulama denetimleri için birincil kayıt defteridir. Aynı sürüm, openclaw/openclaw adresinde bir Docker Hub yansısı da yayımlar:
export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.shghcr.io/openclaw/openclaw veya openclaw/openclaw kullanın ve OpenClaw'ın sürüm zamanlamasını ya da saklama politikasını paylaşmayan resmî olmayan yansılardan kaçının. Sürüme özgü etiketler, 2026.2.26 gibi sürümleri ve 2026.2.26-beta.1 gibi ön sürümleri içerir. Kararlı sürümler latest ve main etiketlerini ilerletir; ay sonu Gateway sürümleri yalnızca extended-stable etiketini ilerletir. Varyantlar arasında slim, main-slim, extended-stable-slim, latest-browser, main-browser ve extended-stable-browser bulunur. Varsayılan imajlar codex ve diagnostics-otel pluginlerini içerir. Ayrıca Chromium'un imaja önceden eklendiği bir -browser varyantı da sunulur; bu varyant, ilk çalıştırmada Playwright kurulumu gerektirmeden sandbox tarayıcı aracını kullanmak için yararlıdır.
İnternet bağlantısı olmadan yeniden çalıştırın
Çevrimdışı ana makinelerde önce imajı aktarın ve yükleyin:
docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline--offline, OPENCLAW_IMAGE öğesinin yerel olarak zaten bulunduğunu doğrular, örtük Compose çekme/derleme işlemlerini devre dışı bırakır ve ardından normal akışı çalıştırır: .env eşitlemesi, izin düzeltmeleri, ilk katılım, gateway yapılandırma eşitlemesi ve Compose başlatma.
OPENCLAW_SANDBOX=1 ise çevrimdışı kurulum, tarayıcı sözleşmesi etiketi de dahil olmak üzere OPENCLAW_DOCKER_SOCKET arkasındaki daemon üzerinde yapılandırılmış varsayılan ve aracı başına sandbox imajlarını da denetler. Gerekli bir imaj eksik veya eskiyse kurulum, hatalı bir başarı bildirmek yerine sandbox yapılandırmasını değiştirmeden çıkar.
İlk katılımı tamamlayın
Kurulum betiği ilk katılımı otomatik olarak çalıştırır:
- sağlayıcı API anahtarlarını ister
- bir gateway belirteci oluşturur ve bunu
.envkonumuna yazar - kimlik doğrulama profili gizli anahtar dizinini oluşturur
- gateway'i Docker Compose aracılığıyla başlatır
Başlatma öncesi ilk katılım ve yapılandırma yazma işlemleri, openclaw-cli gateway'in ağ ad alanını paylaştığı ve yalnızca gateway kapsayıcısı mevcut olduktan sonra çalıştığı için doğrudan openclaw-gateway üzerinden (--no-deps --entrypoint node ile) yürütülür.
Kontrol Arayüzünü açın
http://127.0.0.1:18789/ adresini açın ve .env konumuna yazılan belirteci Ayarlar'a yapıştırın. Kapsayıcıyı parola kimlik doğrulamasına geçirdiyseniz bunun yerine o parolayı kullanın.
URL yeniden mi gerekiyor?
docker compose run --rm openclaw-cli dashboard --no-openKanalları yapılandırın (isteğe bağlı)
# 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ış
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-gatewayDocker bağlamı .git öğesini hariç tutar. İmajın Hakkında ekranının kullanıma alınan commit'i ve tek bir derleme zaman damgasını bildirmesi için kaynak kimliğini yukarıda gösterildiği gibi derleme bağımsız değişkenleri olarak iletin. scripts/docker/setup.sh her iki değeri de otomatik olarak çözümler ve iletir.
Kapsayıcı imajlarını yükseltme
OpenClaw imajını değiştirip aynı bağlı durum/yapılandırmayı koruduğunuzda yeni gateway, hazır duruma geçmeden önce başlangıçta güvenli yükseltme geçişlerini ve plugin yakınsamasını çalıştırır. Rutin imaj yükseltmeleri ayrı bir openclaw doctor --fix çalıştırması gerektirmemelidir.
Başlangıç bu onarımları güvenli biçimde tamamlayamazsa gateway sağlıklı olduğunu bildirmek yerine çıkar. Bir yeniden başlatma politikası kullanıldığında Docker, Podman veya Kubernetes gateway kapsayıcısının yeniden başlatıldığını gösterebilir. Bağlı durum birimini koruyun, ardından aynı imajı gateway'in kullandığı durum/yapılandırma bağlamalarıyla birlikte bir kez openclaw doctor --fix kapsayıcı komutuyla çalıştırın:
docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixDoctor tamamlandıktan sonra gateway kapsayıcısını varsayılan komutuyla yeniden başlatın. Kubernetes'te aynı komutu, aynı PVC'nin bağlandığı tek seferlik bir Job veya hata ayıklama pod'unda çalıştırın ve ardından Deployment ya da StatefulSet'i yeniden başlatın.
Ortam değişkenleri
scripts/docker/setup.sh tarafından (ve gateway kapsayıcısı için doğrudan docker-compose.yml tarafından) kabul edilen isteğe bağlı değişkenler:
| Değişken | Amaç |
|---|---|
OPENCLAW_IMAGE |
Yerel olarak derlemek yerine uzak bir imaj kullanır |
OPENCLAW_IMAGE_APT_PACKAGES |
Derleme sırasında ek apt paketleri kurar (boşlukla ayrılmış). Eski diğer ad: OPENCLAW_DOCKER_APT_PACKAGES |
OPENCLAW_IMAGE_PIP_PACKAGES |
Derleme sırasında ek Python paketleri kurar (boşlukla ayrılmış) |
OPENCLAW_EXTENSIONS |
Desteklenen seçili pluginleri derler/paketler ve çalışma zamanı bağımlılıklarını kurar (virgülle veya boşlukla ayrılmış kimlikler) |
OPENCLAW_DOCKER_BUILD_NODE_OPTIONS |
Yerel kaynak derlemesi Node seçeneklerini geçersiz kılar (varsayılan --max-old-space-size=8192) |
OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB |
Yerel kaynak derlemesi tsdown yığınını MB cinsinden geçersiz kılar |
OPENCLAW_DOCKER_BUILD_SKIP_DTS |
Yalnızca çalışma zamanına yönelik yerel imaj derlemelerinde bildirim çıktısını atlar (varsayılan 1) |
OPENCLAW_INSTALL_BROWSER |
Derleme sırasında Chromium + Xvfb'yi imaja ekler |
OPENCLAW_EXTRA_MOUNTS |
Ek ana makine bağlama noktaları (virgülle ayrılmış source:target[:opts]) |
OPENCLAW_HOME_VOLUME |
/home/node öğesini adlandırılmış bir Docker biriminde kalıcı tutar |
OPENCLAW_SANDBOX |
Sandbox önyüklemesini etkinleştirir (1, true, yes, on) |
OPENCLAW_SKIP_ONBOARDING |
Etkileşimli ilk katılım adımını atlar (1, true, yes, on) |
OPENCLAW_DOCKER_SOCKET |
Docker soketi yolunu geçersiz kılar |
OPENCLAW_DISABLE_BONJOUR |
Bonjour/mDNS duyurusunu açmaya (0) veya kapatmaya (1) zorlar; bkz. Bonjour / mDNS |
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS |
Paketlenmiş plugin kaynak bağlama katmanlarını devre dışı bırakır |
OTEL_EXPORTER_OTLP_ENDPOINT |
OpenTelemetry 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_PROTOCOL |
OTLP protokolü geçersiz kılması. Günümüzde yalnızca http/protobuf desteklenmektedir |
OTEL_SERVICE_NAME |
OpenTelemetry kaynakları için kullanılan hizmet adı |
OTEL_SEMCONV_STABILITY_OPT_IN |
En son deneysel GenAI anlamsal özniteliklerini etkinleştirir |
OPENCLAW_OTEL_PRELOADED |
Önceden yüklenmiş bir OpenTelemetry SDK olduğunda ikinci bir SDK'nın başlatılmasını atlar |
Resmî imaj Homebrew içermez. OpenClaw, ilk katılım sırasında brew bulunmayan bir Linux kapsayıcısında yalnızca brew ile çalışan skill bağımlılığı yükleyicilerini gizler; bu bağımlılıkları özel bir imaj aracılığıyla sağlayın veya manuel olarak kurun. Debian paketli bağımlılıklar için OPENCLAW_IMAGE_APT_PACKAGES, Python bağımlılıkları için OPENCLAW_IMAGE_PIP_PACKAGES kullanın (derleme sırasında python3 -m pip install --break-system-packages çalıştırılır; bu nedenle sürümleri sabitleyin ve yalnızca güvendiğiniz dizinleri kullanın).
Docker, ResourceExhausted veya cannot allocate memory bildirirse ya da tsdown sırasında işlemi durdurursa Docker derleyicisinin bellek sınırını artırın veya daha küçük açık yığınlarla yeniden deneyin:
OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096Seçili pluginleri içeren kaynaktan derlenmiş imajlar
OPENCLAW_EXTENSIONS kaynak çalışma kopyasından plugin bildirim kimliklerini seçer;
farklı olduklarında mevcut kaynak dizini adları da kabul edilir. Docker
derlemesi, seçimi bir kez kaynak dizinlerine çözümler, üretim
bağımlılıklarını yükler ve seçilen bir plugin openclaw.build.bundledDist: false ile
ayrı olarak yayımlandığında çalışma zamanını kök paketlenmiş dist içine
derler. Yalnızca Docker'a özgü bu paketleme, plugin'in npm veya ClawHub
yapıt sözleşmesini değiştirmez. Bilinmeyen, geçersiz veya belirsiz kimlikler
imaj derlemesinin başarısız olmasına neden olur. Bilinen bağımlılık/yalnızca
kaynak kimlikleri, derlenmiş bir kök dist girdisi kazanmadan mevcut kaynak ve
bağımlılık hazırlama düzenlerini korur. Birleşik derleme girdileri olan seçilmiş
bir plugin başarıyla derlenmelidir; seçilmemiş harici plugin kaynağı ve çalışma
zamanı çıktısı ayıklanır.
Örneğin bu komutlar ClickClack, Slack ve Microsoft Teams için ayrı, çok
mimarili, bağımsız FakeCo gateway imajları derler. ClawRouter zaten kök
OpenClaw çalışma zamanının bir parçasıdır; bu nedenle ClickClack imajı yalnızca
clickclack öğesini seçer. Açıkça belirtilen boş tarayıcı argümanı,
varsayılan imajı Chromium içermeyecek şekilde tutar:
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 msteamsTek bir yerel yerel derleme için --platform linux/arm64 --load veya
--platform linux/amd64 --load kullanın. Çok platformlu çıktı ve ekli SBOM/kaynak
bilgisi, doğrulamaları koruyan bir kayıt defteri veya başka bir Buildx çıktısı
gerektirir. Gönderdikten sonra bildirimi inceleyin ve değişebilir kaynak-SHA
etiketi yerine değişmez özeti dağıtın:
docker buildx imagetools inspect \ "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Dağıt: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>Bu imajlar, bağımsız OCI tabanlı gateway'ler ve genel Docker kullanıcıları içindir. Crabhelm tarafından yönetilen gateway'ler bunları kullanmaz: bu teslimat yolu, bir OpenClaw npm tar arşivi içeren ayrı bir x86_64 cihaz arşivi derler ve Node, arşiv ve bildirim özetlerini sabitler. Bu cihazı, aynı birleştirilmiş OpenClaw kaynağından bağımsız olarak derleyin.
Paketlenmiş bir imaja karşı paketlenmiş plugin kaynağını test etmek için bir plugin kaynak dizinini paketlenmiş kaynak yolunun üzerine bağlayın; örneğin OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Bu, aynı plugin kimliğine ait eşleşen derlenmiş /app/dist/extensions/synology-chat paketini geçersiz kılar.
Gözlemlenebilirlik
OpenTelemetry dışa aktarımı, Gateway konteynerinden OTLP toplayıcınıza giden yöndedir; yayımlanmış bir Docker bağlantı noktası gerektirmez. Paketlenmiş dışa aktarıcıyı yerel olarak derlenen bir imaja dahil etmek için:
export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.shResmî önceden derlenmiş imajlar zaten diagnostics-otel öğesini paketler; yalnızca kaldırdıysanız clawhub:@openclaw/diagnostics-otel öğesini kendiniz yükleyin. Dışa aktarımı etkinleştirmek için yapılandırmada diagnostics-otel plugin'ine izin verip onu etkinleştirin, ardından diagnostics.otel.enabled=true değerini ayarlayın (tam örnek için OpenTelemetry dışa aktarımı bölümüne bakın). Toplayıcı kimlik doğrulama başlıkları Docker ortam değişkenleri üzerinden değil, diagnostics.otel.headers üzerinden geçer.
Prometheus metrikleri, zaten yayımlanmış Gateway bağlantı noktasını yeniden kullanır. clawhub:@openclaw/diagnostics-prometheus öğesini yükleyin, diagnostics-prometheus plugin'ini etkinleştirin, ardından şu adresi tarayın:
http://<gateway-host>:18789/api/diagnostics/prometheusRota Gateway kimlik doğrulamasıyla korunur; ayrı bir genel /metrics bağlantı noktası veya kimliği doğrulanmamış ters proxy yolu açığa çıkarmayın. Prometheus metrikleri bölümüne bakın.
Sistem durumu denetimleri
Konteyner yoklama uç noktaları (kimlik doğrulama gerekmez):
curl -fsS http://127.0.0.1:18789/healthz # canlılıkcurl -fsS http://127.0.0.1:18789/readyz # hazır olmaİmajın yerleşik HEALTHCHECK öğesi /healthz öğesine ping gönderir; tekrarlanan hatalar konteyneri unhealthy olarak işaretler, böylece düzenleyiciler onu yeniden başlatabilir veya değiştirebilir.
Kimliği doğrulanmış ayrıntılı sistem durumu anlık görüntüsü:
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"LAN ve geri döngü karşılaştırması
scripts/docker/setup.sh, Docker bağlantı noktası yayımlamayla ana makinedeki http://127.0.0.1:18789 çalışacak şekilde varsayılan olarak OPENCLAW_GATEWAY_BIND=lan kullanır.
lan(varsayılan): ana makine tarayıcısı ve ana makine CLI'ı yayımlanmış gateway bağlantı noktasına erişebilir.loopback: yalnızca konteyner ağ ad alanındaki işlemler gateway'e doğrudan erişebilir.
Ana makinedeki yerel sağlayıcılar
Konteyner içinde 127.0.0.1, ana makineyi değil konteynerin kendisini belirtir. Ana makinede çalışan sağlayıcılar için host.docker.internal kullanın:
| Sağlayıcı | Ana makine varsayılan URL'si | Docker kurulum URL'si |
|---|---|---|
| LM Studio | http://127.0.0.1:1234 |
http://host.docker.internal:1234 |
| Ollama | http://127.0.0.1:11434 |
http://host.docker.internal:11434 |
Paketlenmiş kurulum, bu URL'leri LM Studio/Ollama ilk katılım varsayılanları olarak kullanır ve docker-compose.yml, Linux Docker Engine üzerinde host.docker.internal öğesini ana makine gateway'ine eşler (Docker Desktop, macOS/Windows üzerinde aynı takma adı sağlar). Ana makine hizmetleri Docker'ın erişebileceği bir adresi dinlemelidir:
lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serveKendi Compose dosyanızı veya docker run mı kullanıyorsunuz? Aynı eşlemeyi kendiniz ekleyin; örneğin --add-host=host.docker.internal:host-gateway.
Docker'da Claude CLI arka ucu
Resmî imaj Claude Code'u önceden yüklemez. Konteynerin node kullanıcısı içinde yükleyip oturum açın, ardından imaj yükseltmelerinin ikili dosyayı veya kimlik doğrulama durumunu silmemesi için bu konteyner ana dizinini kalıcı hâle getirin.
Yeni bir kurulum 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.shMevcut bir kurulum için önce yığını durdurun ve güncel .env değerlerini yeniden yükleyin; kurulum betiği .env dosyasını her zaman mevcut kabuktan ve varsayılanlardan yeniden yazar, dosyayı kendi başına okumaz:
set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh.env kabuğunuzun kaynak olarak yükleyemediği değerler içeriyorsa önce dayandığınız değerleri (OPENCLAW_IMAGE, bağlantı noktaları, bağlama modu, özel yollar, OPENCLAW_EXTRA_MOUNTS, korumalı alan, ilk katılımı atlama) elle yeniden dışa aktarın. Oluşturulan katman, hem openclaw-gateway hem de openclaw-cli için ana dizin birimini bağlar; kalan komutları bu katmanla (kullanıyorsanız önce docker-compose.override.yml ile) çalıştırın:
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 öğesini /home/node/.local/bin/claude konumuna yazar.
OpenClaw imajı, PATH üzerinde /home/node/.local/bin öğesini içerir; böylece paketlenmiş
Anthropic plugin'i bir bağdaştırıcı yapılandırması geçersiz kılması olmadan onu çözümler.
Aynı kalıcı ana dizinden 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 anthropicArdından paketlenmiş claude-cli arka ucunu kullanın:
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'dan merhaba de"OPENCLAW_HOME_VOLUME, /home/node/.local/bin ve /home/node/.local/share/claude altındaki yerel kurulumu; ayrıca /home/node/.claude ve /home/node/.claude.json altındaki Claude Code ayarlarını/kimlik doğrulamasını kalıcı hâle getirir. Yalnızca /home/node/.openclaw öğesini kalıcı hâle getirmek yeterli değildir; bir ana dizin birimi yerine OPENCLAW_EXTRA_MOUNTS kullanıyorsanız bu Claude yollarının tümünü her iki hizmete de bağlayın.
Bonjour / mDNS
Docker köprü ağı genellikle Bonjour/mDNS çok noktaya yayınını (224.0.0.251:5353) güvenilir biçimde iletmez. OPENCLAW_DISABLE_BONJOUR ayarlanmamışsa paketlenmiş Bonjour plugin'i bir konteynerde çalıştığını algıladığında LAN duyurusunu otomatik olarak devre dışı bırakır; böylece köprünün düşürdüğü çok noktaya yayını yeniden denemek için çökme döngüsüne girmez. Algılamadan bağımsız olarak zorla kapatmak için OPENCLAW_DISABLE_BONJOUR=1, zorla açmak için ise 0 ayarlayın (yalnızca ana makine ağı, macvlan veya mDNS çok noktaya yayınının çalıştığı bilinen başka bir ağda).
Aksi durumda Docker ana makineleri için yayımlanmış Gateway URL'sini, Tailscale'i veya geniş alan DNS-SD'yi kullanın. Önemli 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 öğesini /home/node/.openclaw konumuna, OPENCLAW_WORKSPACE_DIR öğesini /home/node/.openclaw/workspace konumuna ve OPENCLAW_AUTH_PROFILE_SECRET_DIR öğesini /home/node/.config/openclaw konumuna bağlayarak bu yolların konteyner değişiminden sonra da korunmasını sağlar. Bir değişken ayarlanmamışsa docker-compose.yml, ${HOME} altına veya HOME öğesinin kendisi yoksa /tmp altına geri döner; böylece docker compose up yalın ortamlarda hiçbir zaman kaynağı boş bir birim belirtimi üretmez.
Bağlanan bu yapılandırma dizini şunları içerir:
openclaw.json: davranış yapılandırmasıagents/<agentId>/agent/auth-profiles.json: depolanan sağlayıcı OAuth/API anahtarı kimlik doğrulaması.env:OPENCLAW_GATEWAY_TOKENgibi ortam tabanlı çalışma zamanı gizli bilgileri
Kimlik doğrulama profili gizli bilgi dizini, OAuth tabanlı kimlik doğrulama profili belirteç malzemesine ait yerel şifreleme anahtarını depolar. Bunu Docker ana makine durumunuzla birlikte, ancak OPENCLAW_CONFIG_DIR öğesinden ayrı tutun.
Yüklenen indirilebilir plugin'ler paket durumunu bağlanan OpenClaw ana dizini altında depolar; böylece yükleme kayıtları ve paket kökleri konteyner değişiminden sonra da korunur. Gateway başlatılması, paketlenmiş plugin bağımlılık ağaçlarını yeniden oluşturmaz.
Tam sanal makine kalıcılığı ayrıntıları için Docker VM Çalışma Zamanı - Nerede neler kalıcıdır bölümüne bakın.
Disk büyümesinin yoğunlaştığı noktalar: media/, aracı başına SQLite veritabanları, eski oturum JSONL dökümleri, paylaşılan SQLite durum veritabanı, yüklü plugin paket kökleri ve /tmp/openclaw/ altındaki dönüşümlü dosya günlükleri.
Kabuk yardımcıları (isteğe bağlı)
Günlük komutları kısaltmak 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 ~/.zshrcEski scripts/shell-helpers/clawdock-helpers.sh yolundan yüklediyseniz yerel yardımcınızın güncel konumu izlemesi için yukarıdaki komutu yeniden çalıştırın. Ardından clawdock-start, clawdock-stop, clawdock-dashboard vb. kullanın (tam liste için clawdock-help çalıştırın).
Docker gateway için agent sandbox'ını etkinleştirme
export OPENCLAW_SANDBOX=1./scripts/docker/setup.shÖzel soket yolu (ör. köksüz Docker):
export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.shBetik, docker.sock öğesini yalnızca sandbox ön koşulları başarıyla tamamlandıktan sonra bağlar. Sandbox kurulumu tamamlanamazsa agents.defaults.sandbox.mode değerini off olarak sıfırlar. OpenClaw sandbox'ının etkin olduğu dönüşlerde Codex kod modu devre dışı bırakılır (bkz. Sandbox Kullanımı § Docker arka ucu); ana makinenin Docker soketini hiçbir zaman agent sandbox kapsayıcılarına bağlamayın.
Otomasyon / CI (etkileşimsiz)
Compose sözde TTY tahsisini -T ile devre dışı bırakın:
docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --jsonPaylaşılan ağ güvenliği notu
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şılan bir güven sınırı olarak değerlendirin. Compose yapılandırması hem openclaw-gateway hem de openclaw-cli üzerinde NET_RAW/NET_ADMIN yeteneklerini kaldırır ve no-new-privileges özelliğini etkinleştirir.
openclaw-cli içindeki Docker Desktop DNS hataları
Bazı Docker Desktop kurulumlarında NET_RAW kaldırıldıktan sonra paylaşılan ağdaki openclaw-cli yardımcı kapsayıcısından yapılan DNS sorguları başarısız olur; bu durum openclaw plugins install gibi npm destekli komutlar sırasında EAI_AGAIN olarak görünür. Normal kullanım için varsayılan, güçlendirilmiş Compose dosyasını kullanmaya devam edin. Aşağıdaki geçersiz kılma, yalnızca openclaw-cli kapsayıcısının varsayılan yeteneklerini geri yükler — bunu varsayılan çağrınız olarak değil, kayıt defteri erişimi gerektiren tek seferlik komut 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>Uzun süre çalışan bir openclaw-cli kapsayıcısı zaten oluşturduysanız aynı geçersiz kılmayla yeniden oluşturun — docker compose exec/docker exec, önceden oluşturulmuş bir kapsayıcının Linux yeteneklerini değiştiremez.
İzinler ve EACCES
İmaj node (uid 1000) olarak çalışır. /home/node/.openclaw üzerinde izin hataları görürseniz ana makinenizdeki bağlama noktalarının uid 1000'e ait olduğundan emin olun:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceAynı uyuşmazlık, blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) ve ardından plugin present but blocked olarak da görünebilir — işlem uid'si ile bağlanan Plugin dizininin sahibi uyuşmuyordur. Varsayılan uid 1000 ile çalıştırmayı ve bağlama noktası sahipliğini düzeltmeyi tercih edin. Yalnızca OpenClaw'ı uzun vadede kasıtlı olarak root kullanıcısıyla çalıştırıyorsanız /path/to/openclaw-config/npm öğesinin sahipliğini root:root olarak değiştirin.
Daha hızlı yeniden derlemeler
Dockerfile'ınızı bağımlılık katmanları önbelleğe alınacak şekilde sıralayarak kilit dosyaları değişmediği sürece pnpm install komutunun yeniden çalıştırılmasını önleyin:
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"]İleri düzey kullanıcılar için kapsayıcı seçenekleri
Varsayılan imaj güvenliğe öncelik verir ve root olmayan node olarak çalışır. Daha kapsamlı özelliklere sahip bir kapsayıcı için:
/home/nodeöğesini kalıcılaştırın:export OPENCLAW_HOME_VOLUME="openclaw_home"- Sistem bağımlılıklarını imaja dahil edin:
export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq" - Python bağımlılıklarını imaja dahil edin:
export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0" - Playwright Chromium'u imaja dahil edin:
export OPENCLAW_INSTALL_BROWSER=1veya resmi-browserimaj etiketini kullanın - Ya da Playwright tarayıcılarını kalıcı bir birime yükleyin:
bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium - Tarayıcı indirmelerini kalıcılaştırın:
OPENCLAW_HOME_VOLUMEveyaOPENCLAW_EXTRA_MOUNTSkullanın. OpenClaw, Linux'ta imajın Playwright tarafından yönetilen Chromium'unu otomatik olarak algılar.
OpenAI Codex OAuth (başsız Docker)
Sihirbazda OpenAI Codex OAuth'u seçerseniz bir tarayıcı URL'si açılır. Docker veya başsız kurulumlarda ulaştığınız yönlendirme URL'sinin tamamını kopyalayıp kimlik doğrulamayı tamamlamak için yeniden sihirbaza yapıştırın.
Temel imaj meta verileri
Çalışma zamanı imajı node:24-bookworm-slim kullanır ve zombi işlemlerin temizlenmesiyle uzun süre çalışan kapsayıcılarda sinyallerin doğru biçimde işlenmesi için tini öğesini PID 1 olarak çalıştırır. org.opencontainers.image.base.name ve org.opencontainers.image.source dahil olmak üzere OCI temel imaj ek açıklamalarını yayımlar. Dependabot, sabitlenmiş Node temel imaj özetini yeniler; sürüm derlemeleri ayrı bir dağıtım yükseltme katmanı çalıştırmaz. Bkz. OCI imaj ek açıklamaları.
Bir VPS üzerinde mi çalıştırıyorsunuz?
İkili dosyaların imaja dahil edilmesi, kalıcılık ve güncellemeler dahil olmak üzere paylaşılan sanal makine dağıtım adımları için Hetzner (Docker VPS) ve Docker VM Çalışma Zamanı sayfalarına bakın.
Agent sandbox'ı
agents.defaults.sandbox Docker arka ucuyla etkinleştirildiğinde gateway; agent araçlarının yürütülmesini (kabuk, dosya okuma/yazma vb.) yalıtılmış Docker kapsayıcılarında gerçekleştirirken gateway'in kendisi ana makinede kalır — tüm gateway'i kapsayıcıya almadan güvenilmeyen veya birden fazla kiracılı agent oturumlarının etrafında katı bir duvar oluşturur.
Sandbox kapsamı agent başına (varsayılan), oturum başına veya paylaşılan olabilir; her kapsam /workspace konumuna bağlanan kendi çalışma alanını alır. Ayrıca araç izin/ret ilkelerini, ağ yalıtımını, kaynak sınırlarını ve tarayıcı kapsayıcılarını yapılandırabilirsiniz.
Tam yapılandırma, imajlar, güvenlik notları ve çoklu agent profilleri için:
- Sandbox Kullanımı -- eksiksiz sandbox başvurusu
- OpenShell -- sandbox kapsayıcılarına etkileşimli kabuk erişimi
- Çoklu Agent Sandbox'ı ve Araçları -- agent başına geçersiz kılmalar
Hızlı etkinleştirme
{ agents: { defaults: { sandbox: { mode: "non-main", // kapalı | ana olmayan | tümü scope: "agent", // oturum | agent | paylaşılan }, }, },}Varsayılan sandbox imajını derleyin (kaynak kod deposu kopyasından):
scripts/sandbox-setup.shKaynak kod deposu kopyası olmadan yapılan npm kurulumları için satır içi docker build komutlarıyla ilgili olarak Sandbox Kullanımı § İmajlar ve kurulum bölümüne bakın.
Sorun giderme
İmaj eksik veya sandbox kapsayıcısı başlamıyor
Sandbox imajını scripts/sandbox-setup.sh ile (kaynak kod deposu kopyası) ya da Sandbox Kullanımı § İmajlar ve kurulum bölümündeki satır içi docker build komutuyla (npm kurulumu) derleyin veya agents.defaults.sandbox.docker.image değerini özel imajınıza ayarlayın. Kapsayıcılar, gerektiğinde her oturum için otomatik olarak oluşturulur.
Sandbox'taki izin hataları
docker.user değerini bağlanan ç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.
Özel araçlar sandbox'ta bulunamıyor
OpenClaw komutları sh -lc (oturum açma kabuğu) ile çalıştırır; bu kabuk /etc/profile dosyasını yükler ve PATH'i sıfırlayabilir. Özel araç yollarınızı başa eklemek için docker.env.PATH değerini ayarlayın veya Dockerfile'ınızda /etc/profile.d/ altına bir betik ekleyin.
İmaj derlemesi sırasında OOM nedeniyle sonlandırıldı (çıkış 137)
Sanal makine en az 2 GB RAM gerektirir. Daha büyük bir makine sınıfı kullanıp yeniden deneyin.
Control UI'da yetkisiz veya eşleştirme gerekiyor
Yeni bir pano bağlantısı alın ve tarayıcı cihazını onaylayın:
docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>Gateway hedefi ws://172.x.x.x gösteriyor veya Docker CLI'dan eşleştirme hataları alınıyor
Gateway modunu ve bağlama ayarını 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
- Kuruluma Genel Bakış — tüm kurulum yöntemleri
- Podman — Docker'a Podman alternatifi
- ClawDock — topluluk tarafından sağlanan Docker Compose kurulumu
- Güncelleme — OpenClaw'ı güncel tutma
- Yapılandırma — kurulum sonrasında gateway yapılandırması