Docker

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

# Docker benim için doğru mu?

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

# Ön koşullar

• Docker Desktop (veya Docker Engine) + Docker Compose v2
• İmaj derlemesi için en az 2 GB RAM (pnpm install, 1 GB ana makinelerde çıkış 137 ile OOM nedeniyle sonlandırılabilir)
• İmajlar ve günlükler için yeterli disk alanı
• Bir VPS/genel ana makinede çalıştırıyorsanız, Ağ erişimi için güvenlik sağlamlaştırması bölümünü, özellikle Docker DOCKER-USER güvenlik duvarı ilkesini gözden geçirin.

# Konteynerleştirilmiş Gateway

./scripts/docker/setup.sh

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

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

# 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

# Ortam değişkenleri

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

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

# Gözlemlenebilirlik

OpenTelemetry dışa aktarımı, Gateway konteynerinden OTLP collector'ınıza doğru çıkış yönündedir. Yayımlanmış bir Docker portu gerektirmez. İmajı yerel olarak derliyorsanız ve paketlenmiş OpenTelemetry exporter'ın imaj 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 imajlar yerel Plugin kaynağını yine OPENCLAW_EXTENSIONS=diagnostics-otel ile dahil edebilir. Dışa aktarımı etkinleştirmek için, yapılandırmada diagnostics-otel Plugin'ine izin verip etkinleştirin, ardından diagnostics.otel.enabled=true ayarlayın veya OpenTelemetry dışa aktarımı içindeki yapılandırma örneğini kullanın. Collector 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 denetimleri

Konteyner 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 imajı, /healthz ping atan yerleşik bir HEALTHCHECK içerir. Denetimler başarısız olmaya devam ederse Docker konteyneri unhealthy olarak işaretler ve orkestrasyon sistemleri onu yeniden başlatabilir veya değiştirebilir.

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

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

# LAN ve loopback

scripts/docker/setup.sh, Docker port yayımlamasıyla ana makine erişiminin http://127.0.0.1:18789 üzerinden çalışması için varsayılan olarak OPENCLAW_GATEWAY_BIND=lan kullanır.

• lan (varsayılan): ana makine tarayıcısı ve ana makine CLI'ı yayımlanmış Gateway portuna erişebilir.
• loopback: yalnızca konteyner 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, konteyner içindeki 127.0.0.1 ana makineniz değil, konteynerin kendisidir. Ana makinede çalışan AI sağlayıcıları için host.docker.internal kullanın:

Paketlenmiş Docker kurulumu, bu ana makine URL'lerini LM Studio ve Ollama onboarding varsayılanları olarak kullanır ve docker-compose.yml, Linux Docker Engine için host.docker.internal adını Docker'ın ana makine Gateway'ine eşler. Docker Desktop, macOS ve Windows'ta aynı ana makine adını zaten sağlar.

Ana makine hizmetleri Docker'dan erişilebilir bir adreste de 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.

# Bonjour / mDNS

Docker bridge ağı genellikle Bonjour/mDNS multicast'i (224.0.0.251:5353) güvenilir biçimde iletmez. Bu nedenle paketlenmiş Compose kurulumu varsayılan olarak OPENCLAW_DISABLE_BONJOUR=1 kullanır; böylece bridge multicast trafiğini düşürdüğünde Gateway çökme döngüsüne girmez veya duyuruyu tekrar tekrar yeniden başlatmaz.

Docker ana makineleri için yayımlanmış Gateway URL'sini, Tailscale'i veya wide-area DNS-SD'yi kullanın. OPENCLAW_DISABLE_BONJOUR=0 ayarını yalnızca host networking, macvlan veya mDNS multicast'in çalıştığı bilinen başka bir ağla çalıştırırken kullanın.

Dikkat edilmesi gerekenler ve sorun giderme için bkz. Bonjour keşfi.

# Depolama ve kalıcılık

Docker Compose, OPENCLAW_CONFIG_DIR değerini /home/node/.openclaw yoluna ve OPENCLAW_WORKSPACE_DIR değerini /home/node/.openclaw/workspace yoluna bind-mount eder; bu nedenle bu yollar konteyner değişiminden sonra korunur. Değişkenlerden biri ayarlanmamışsa, paketlenmiş docker-compose.yml, ${HOME}/.openclaw değerine (ve workspace bağlama noktası için ${HOME}/.openclaw/workspace değerine) veya HOME da eksikse /tmp/.openclaw değerine geri döner. Bu, yalın ortamlarda docker compose up komutunun boş kaynaklı bir volume belirtimi yaymasını önler.

OpenClaw, şu öğeleri bu bağlanmış yapılandırma dizininde tutar:

• davranış yapılandırması için openclaw.json
• depolanmış 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ı sırları için .env

Kurulan indirilebilir Plugin'ler paket durumlarını bağlanmış OpenClaw home altında depolar; bu nedenle Plugin kurulum kayıtları ve paket kökleri konteyner değişiminden sonra korunur. Gateway başlatma, paketlenmiş Plugin bağımlılık ağaçları oluşturmaz.

VM dağıtımlarında tam kalıcılık ayrıntıları için bkz. Docker VM Çalışma Zamanı - Nerede ne kalıcı olur.

Disk büyümesi sıcak noktaları: /tmp/openclaw/ altındaki media/, oturum JSONL dosyaları, cron/runs/*.jsonl, kurulu Plugin paket kökleri ve 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 kurun:

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 ham yolundan kurduysanız, yerel yardımcı dosyanızın yeni konumu izlemesi için yukarıdaki kurulum komutunu yeniden çalıştırın.

Ardından clawdock-start, clawdock-stop, clawdock-dashboard vb. 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=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# Bir VPS üzerinde mi çalıştırıyorsunuz?

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

# Agent sandbox

agents.defaults.sandbox, Docker backend ile etkinleştirildiğinde gateway, agent araç yürütmeyi (kabuk, dosya okuma/yazma vb.) yalıtılmış Docker konteynerleri içinde çalıştırırken gateway'in kendisi host üzerinde kalır. Bu, tüm gateway'i konteynerleştirmeden güvenilmeyen veya çok kiracılı agent oturumlarının etrafına sert bir sınır koyar.

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 izin ver/reddet araç politikalarını, ağ yalıtımını, kaynak sınırlarını ve tarayıcı konteynerlerini yapılandırabilirsiniz.

Tam yapılandırma, imajlar, güvenlik notları ve çoklu agent profilleri için bkz.:

• Sandboxing -- eksiksiz sandbox başvurusu
• OpenShell -- sandbox konteynerlerine etkileşimli kabuk erişimi
• Multi-Agent Sandbox and Tools -- agent 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 sandbox imajını derleyin (bir kaynak checkout'undan):

scripts/sandbox-setup.sh

Kaynak checkout'u olmayan npm kurulumları için satır içi docker build komutları amacıyla Sandboxing § İmajlar ve kurulum bölümüne bakın.

# Sorun giderme

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

# İ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ı