Docker

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• Có: bạn muốn một môi trường Gateway biệt 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 có sẵn. 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 Gia cố bảo mật cho việc phơi bày mạng, đặc biệt là chính sách firewall 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

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

​

Khả năng quan sát

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

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

​

Kiểm tra sức khỏe

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

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

​

LAN so với vòng lặp cục bộ

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

​

Provider cục bộ trên host

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

​

Bonjour / mDNS

​

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

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

​

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

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

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

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-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?

​

Sandbox tác tử

• Sandboxing — tài liệu tham khảo đầy đủ về sandbox
• OpenShell — truy cập shell tương tác vào container sandbox
• Multi-Agent Sandbox and Tools — ghi đè theo tác tử

​

Bật nhanh

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

scripts/sandbox-setup.sh

​

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 — lựa chọn thay thế Podman cho Docker
• ClawDock — thiết lập cộng đồng Docker Compose
• Cập nhật — giữ OpenClaw luôn được cập nhật
• Cấu hình — cấu hình gateway sau khi cài đặt