Docker

Docker là tùy chọn. Chỉ dùng nếu bạn muốn một gateway được container hóa hoặc muốn xác thực luồng Docker.

# Docker có phù hợp với tôi không?

• Có: bạn muốn một môi trường gateway cô lập, dùng xong bỏ, hoặc muốn chạy OpenClaw trên một host không có cài đặt cục bộ.
• Không: bạn đang chạy trên máy của mình và chỉ muốn vòng lặp phát triển nhanh nhất. Thay vào đó hãy dùng luồng cài đặt thông thường.
• Lưu ý về sandboxing: backend sandbox mặc định dùng Docker khi sandboxing được bật, nhưng sandboxing mặc định tắt và không yêu cầu toàn bộ gateway chạy trong Docker. Các backend sandbox SSH và OpenShell cũng khả dụng. Xem Sandboxing.

# Điều kiện tiên quyết

• Docker Desktop (hoặc Docker Engine) + Docker Compose v2
• Ít nhất 2 GB RAM để build image (pnpm install có thể bị OOM-killed trên host 1 GB với mã thoát 137)
• Đủ dung lượng đĩa cho image và log
• Nếu chạy trên VPS/host công khai, hãy xem lại Tăng cường bảo mật khi phơi bày mạng, đặc biệt là chính sách tường lửa Docker DOCKER-USER.

# Gateway được container hóa

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

# Luồng thủ công

Nếu bạn muốn tự chạy từng bước thay vì dùng script thiết lập:

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

# Biến môi trường

Script thiết lập chấp nhận các biến môi trường tùy chọn này:

Maintainer có thể kiểm thử mã nguồn Plugin được đóng gói với image đã đóng gói bằng cách mount một thư mục mã nguồn Plugin lên đường dẫn mã nguồn đã đóng gói của nó, ví dụ OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Thư mục mã nguồn được mount đó ghi đè bundle đã biên dịch tương ứng /app/dist/extensions/synology-chat cho cùng id Plugin.

# Khả năng quan sát

Xuất OpenTelemetry là outbound từ container Gateway tới collector OTLP của bạn. Nó không yêu cầu publish port Docker. Nếu bạn build image cục bộ và muốn exporter OpenTelemetry được đóng gói có sẵn bên trong image, hãy bao gồm các phụ thuộc runtime của nó:

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

Cài Plugin chính thức @openclaw/diagnostics-otel từ ClawHub trong các bản cài Docker đã đóng gói trước khi bật xuất. Các image được build từ mã nguồn tùy chỉnh vẫn có thể bao gồm mã nguồn Plugin cục bộ bằng OPENCLAW_EXTENSIONS=diagnostics-otel. Để bật xuất, hãy cho phép và bật Plugin diagnostics-otel trong config, rồi đặt diagnostics.otel.enabled=true hoặc dùng ví dụ config trong xuất OpenTelemetry . Header xác thực collector được cấu hình qua diagnostics.otel.headers, không qua biến môi trường Docker.

Metric Prometheus dùng port Gateway đã được publish sẵn. Cài clawhub:@openclaw/diagnostics-prometheus, bật Plugin diagnostics-prometheus, rồi scrape:

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

Route này được bảo vệ bằng xác thực Gateway. Không phơi bày port /metrics công khai riêng hoặc đường dẫn reverse-proxy không xác thực. Xem Metric Prometheus.

# Kiểm tra sức khỏe

Endpoint probe container (không cần xác thực):

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

Image Docker bao gồm HEALTHCHECK tích hợp ping /healthz. Nếu các lần kiểm tra tiếp tục thất bại, Docker đánh dấu container là unhealthy và hệ thống điều phối có thể khởi động lại hoặc thay thế nó.

Ảnh chụp nhanh sức khỏe sâu có xác thực:

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

# LAN so với loopback

scripts/docker/setup.sh mặc định OPENCLAW_GATEWAY_BIND=lan để truy cập host tới http://127.0.0.1:18789 hoạt động với việc publish port Docker.

• lan (mặc định): trình duyệt host và CLI host có thể truy cập port gateway đã publish.
• loopback: chỉ các tiến trình bên trong namespace mạng container mới có thể truy cập trực tiếp gateway.

# Provider cục bộ trên host

Khi OpenClaw chạy trong Docker, 127.0.0.1 bên trong container là chính container, không phải máy host của bạn. Dùng host.docker.internal cho các provider AI chạy trên host:

Thiết lập Docker được đóng gói dùng các URL host đó làm mặc định onboarding cho LM Studio và Ollama, và docker-compose.yml ánh xạ host.docker.internal tới host gateway của Docker cho Docker Engine trên Linux. Docker Desktop đã cung cấp cùng hostname trên macOS và Windows.

Các dịch vụ host cũng phải lắng nghe trên một địa chỉ mà Docker có thể truy cập:

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

Nếu bạn dùng file Compose hoặc lệnh docker run riêng, hãy tự thêm cùng ánh xạ host, ví dụ --add-host=host.docker.internal:host-gateway.

# Bonjour / mDNS

Mạng bridge Docker thường không chuyển tiếp multicast Bonjour/mDNS (224.0.0.251:5353) một cách tin cậy. Vì vậy thiết lập Compose được đóng gói mặc định OPENCLAW_DISABLE_BONJOUR=1 để Gateway không crash-loop hoặc liên tục khởi động lại việc quảng bá khi bridge làm rơi lưu lượng multicast.

Dùng URL Gateway đã publish, Tailscale hoặc DNS-SD diện rộng cho các host Docker. Chỉ đặt OPENCLAW_DISABLE_BONJOUR=0 khi chạy với host networking, macvlan, hoặc một mạng khác mà multicast mDNS được biết là hoạt động.

Để biết các điểm dễ vướng và cách khắc phục sự cố, xem khám phá Bonjour.

# Lưu trữ và duy trì dữ liệu

Docker Compose bind-mount OPENCLAW_CONFIG_DIR tới /home/node/.openclaw và OPENCLAW_WORKSPACE_DIR tới /home/node/.openclaw/workspace, nên các đường dẫn đó vẫn tồn tại sau khi thay thế container. Khi một trong hai biến chưa được đặt, docker-compose.yml được đóng gói fallback về ${HOME}/.openclaw (và ${HOME}/.openclaw/workspace cho workspace mount), hoặc /tmp/.openclaw khi chính HOME cũng bị thiếu. Điều đó giúp docker compose up không phát ra volume spec có source rỗng trên môi trường tối giản.

Thư mục config được mount đó là nơi OpenClaw lưu:

• openclaw.json cho config hành vi
• agents/<agentId>/agent/auth-profiles.json cho xác thực OAuth/API-key provider đã lưu
• .env cho các secret runtime dựa trên env như OPENCLAW_GATEWAY_TOKEN

Các Plugin tải về đã cài đặt lưu trạng thái package của chúng dưới OpenClaw home được mount, nên bản ghi cài đặt Plugin và package root vẫn tồn tại sau khi thay thế container. Khởi động Gateway không tạo cây phụ thuộc bundled-plugin.

Để biết đầy đủ chi tiết về tính duy trì dữ liệu trên các triển khai VM, xem Docker VM Runtime - Những gì được duy trì ở đâu.

Điểm nóng tăng dung lượng đĩa: theo dõi media/, các tệp JSONL phiên, cron/runs/*.jsonl, thư mục gốc của gói Plugin đã cài đặt, và nhật ký tệp xoay vòng trong /tmp/openclaw/.

# Trình trợ giúp shell (tùy chọn)

Để quản lý Docker hằng ngày dễ hơn, hãy cài đặt ClawDock:

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

Nếu bạn đã cài đặt ClawDock từ đường dẫn thô scripts/shell-helpers/clawdock-helpers.sh cũ hơn, hãy chạy lại lệnh cài đặt ở trên để tệp trợ giúp cục bộ của bạn theo dõi vị trí mới.

Sau đó dùng clawdock-start, clawdock-stop, clawdock-dashboard, v.v. Chạy clawdock-help để xem tất cả lệnh. Xem ClawDock để biết hướng dẫn đầy đủ về trình trợ giúp.

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

# Chạy trên VPS?

Xem Hetzner (Docker VPS) và Docker VM Runtime để biết các bước triển khai VM dùng chung, bao gồm đóng gói nhị phân, duy trì dữ liệu, và cập nhật.

# Sandbox tác nhân

Khi agents.defaults.sandbox được bật với backend Docker, gateway chạy thực thi công cụ của tác nhân (shell, đọc/ghi tệp, v.v.) bên trong các container Docker cô lập trong khi chính gateway vẫn ở trên máy chủ. Điều này cung cấp một bức tường cứng quanh các phiên tác nhân không đáng tin cậy hoặc đa khách thuê mà không cần container hóa toàn bộ gateway.

Phạm vi sandbox có thể theo từng tác nhân (mặc định), theo từng phiên, hoặc dùng chung. Mỗi phạm vi có workspace riêng được gắn tại /workspace. Bạn cũng có thể cấu hình chính sách công cụ cho phép/từ chối, cô lập mạng, giới hạn tài nguyên, và container trình duyệt.

Để xem cấu hình đầy đủ, image, ghi chú bảo mật, và hồ sơ đa tác nhân, hãy xem:

• Sandboxing -- tham chiếu sandbox đầy đủ
• OpenShell -- truy cập shell tương tác vào container sandbox
• Multi-Agent Sandbox and Tools -- ghi đè theo từng tác nhân

# Bật nhanh

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

Dựng image sandbox mặc định (từ bản checkout mã nguồn):

scripts/sandbox-setup.sh

Đối với cài đặt npm không có bản checkout mã nguồn, xem Sandboxing § Image và thiết lập để biết các lệnh docker build nội tuyến.

# Khắc phục sự cố

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

# Liên quan

• Tổng quan cài đặt — tất cả phương thức cài đặt
• Podman — phương án Podman thay thế Docker
• ClawDock — thiết lập cộng đồng Docker Compose
• Cập nhật — giữ OpenClaw luôn cập nhật
• Cấu hình — cấu hình gateway sau khi cài đặt