Docker

Docker เป็น ตัวเลือก ใช้เฉพาะเมื่อคุณต้องการ Gateway แบบคอนเทนเนอร์ หรือต้องการตรวจสอบความถูกต้องของขั้นตอน Docker

Docker เหมาะกับฉันหรือไม่?

• ใช่: คุณต้องการสภาพแวดล้อม Gateway ที่แยกออกมาและทิ้งได้ หรือต้องการรัน OpenClaw บนโฮสต์ที่ไม่มีการติดตั้งภายในเครื่อง
• ไม่: คุณกำลังรันบนเครื่องของคุณเองและต้องการเพียงรอบการพัฒนาที่เร็วที่สุด ให้ใช้ขั้นตอนการติดตั้งปกติแทน
• หมายเหตุเรื่อง sandboxing: แบ็กเอนด์ sandbox เริ่มต้นใช้ Docker เมื่อเปิดใช้ sandboxing แต่ sandboxing จะปิดไว้โดยค่าเริ่มต้น และ ไม่ ต้องให้ Gateway ทั้งหมดรันใน Docker นอกจากนี้ยังมีแบ็กเอนด์ sandbox แบบ SSH และ OpenShell ดู Sandboxing

ข้อกำหนดเบื้องต้น

• Docker Desktop (หรือ Docker Engine) + Docker Compose v2
• RAM อย่างน้อย 2 GB สำหรับการ build image (pnpm install อาจถูก OOM-killed บนโฮสต์ 1 GB พร้อมรหัสออก 137)
• พื้นที่ดิสก์เพียงพอสำหรับ image และ log
• หากรันบน VPS/โฮสต์สาธารณะ ให้ทบทวน การเพิ่มความปลอดภัยสำหรับการเปิดให้เข้าถึงผ่านเครือข่าย, โดยเฉพาะนโยบายไฟร์วอลล์ DOCKER-USER ของ Docker

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 # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

ขั้นตอนแบบ Manual

หากคุณต้องการรันแต่ละขั้นตอนเองแทนการใช้สคริปต์ตั้งค่า:

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

ตัวแปรสภาพแวดล้อม

สคริปต์ตั้งค่ารองรับตัวแปรสภาพแวดล้อมแบบไม่บังคับเหล่านี้:

ผู้ดูแลสามารถทดสอบ source ของ Plugin ที่ bundled กับ image แบบแพ็กเกจได้โดย mount ไดเรกทอรี source ของ Plugin หนึ่งรายการทับพาธ source แบบแพ็กเกจของมัน เช่น OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro ไดเรกทอรี source ที่ mount นั้นจะแทนที่ bundle ที่คอมไพล์แล้วที่ตรงกัน /app/dist/extensions/synology-chat สำหรับ plugin id เดียวกัน

Observability

การส่งออก OpenTelemetry เป็นการเชื่อมต่อขาออกจากคอนเทนเนอร์ Gateway ไปยัง OTLP collector ของคุณ ไม่จำเป็นต้องมีพอร์ต Docker ที่เผยแพร่ หากคุณ build image ในเครื่องและต้องการให้ exporter ของ OpenTelemetry ที่ bundled พร้อมใช้งานภายใน image ให้รวม runtime dependencies ของมัน:

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

ติดตั้ง Plugin @openclaw/diagnostics-otel อย่างเป็นทางการจาก ClawHub ใน การติดตั้ง Docker แบบแพ็กเกจก่อนเปิดใช้การส่งออก image ที่ build จาก source เอง ยังสามารถรวม source ของ Plugin ภายในเครื่องด้วย OPENCLAW_EXTENSIONS=diagnostics-otel ได้ หากต้องการเปิดใช้การส่งออก ให้ allow และเปิดใช้ Plugin diagnostics-otel ใน config จากนั้นตั้งค่า diagnostics.otel.enabled=true หรือใช้ตัวอย่าง config ใน การส่งออก OpenTelemetry ส่วนหัวสำหรับการยืนยันตัวตนของ collector กำหนดค่าผ่าน diagnostics.otel.headers ไม่ใช่ผ่านตัวแปรสภาพแวดล้อม Docker

metrics ของ Prometheus ใช้พอร์ต Gateway ที่เผยแพร่อยู่แล้ว ติดตั้ง clawhub:@openclaw/diagnostics-prometheus, เปิดใช้ Plugin diagnostics-prometheus แล้วจึง scrape:

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

route นี้ได้รับการป้องกันด้วยการยืนยันตัวตนของ Gateway อย่าเปิดเผยพอร์ต /metrics สาธารณะแยกต่างหาก หรือพาธ reverse-proxy ที่ไม่ต้องยืนยันตัวตน ดู metrics ของ Prometheus

Health checks

ปลายทาง probe ของคอนเทนเนอร์ (ไม่ต้องยืนยันตัวตน):

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

Docker image มี HEALTHCHECK ในตัวที่จะ ping /healthz หากการตรวจสอบยังล้มเหลว Docker จะทำเครื่องหมายคอนเทนเนอร์เป็น unhealthy และ ระบบ orchestration สามารถรีสตาร์ตหรือแทนที่ได้

สแนปช็อตสุขภาพเชิงลึกที่ยืนยันตัวตนแล้ว:

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

LAN เทียบกับ loopback

scripts/docker/setup.sh ตั้งค่าเริ่มต้น OPENCLAW_GATEWAY_BIND=lan เพื่อให้การเข้าถึงของโฮสต์ไปยัง http://127.0.0.1:18789 ทำงานได้กับการเผยแพร่พอร์ตของ Docker

• lan (ค่าเริ่มต้น): เบราว์เซอร์ของโฮสต์และ CLI ของโฮสต์สามารถเข้าถึงพอร์ต Gateway ที่เผยแพร่ได้
• loopback: เฉพาะ process ภายใน network namespace ของคอนเทนเนอร์เท่านั้นที่เข้าถึง Gateway ได้โดยตรง

Provider ภายในเครื่องของโฮสต์

เมื่อ OpenClaw รันใน Docker, 127.0.0.1 ภายในคอนเทนเนอร์คือคอนเทนเนอร์ เอง ไม่ใช่เครื่องโฮสต์ของคุณ ใช้ host.docker.internal สำหรับ provider AI ที่ รันบนโฮสต์:

การตั้งค่า Docker ที่ bundled ใช้ URL ของโฮสต์เหล่านั้นเป็นค่าเริ่มต้นของ onboarding สำหรับ LM Studio และ Ollama และ docker-compose.yml จะ map host.docker.internal ไปยัง Gateway ของโฮสต์ Docker สำหรับ Linux Docker Engine ส่วน Docker Desktop มี hostname เดียวกันนี้อยู่แล้วบน macOS และ Windows

บริการของโฮสต์ต้อง listen บน address ที่ Docker เข้าถึงได้ด้วย:

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

หากคุณใช้ไฟล์ Compose ของคุณเองหรือคำสั่ง docker run ให้เพิ่ม host mapping เดียวกันเอง เช่น --add-host=host.docker.internal:host-gateway

Bonjour / mDNS

โดยปกติ Docker bridge networking จะไม่ forward multicast ของ Bonjour/mDNS (224.0.0.251:5353) ได้อย่างน่าเชื่อถือ ดังนั้นการตั้งค่า Compose ที่ bundled จึงตั้งค่าเริ่มต้น OPENCLAW_DISABLE_BONJOUR=1 เพื่อไม่ให้ Gateway crash-loop หรือ รีสตาร์ตการโฆษณาซ้ำ ๆ เมื่อ bridge ทิ้ง traffic multicast

ใช้ URL ของ Gateway ที่เผยแพร่, Tailscale หรือ wide-area DNS-SD สำหรับโฮสต์ Docker ตั้งค่า OPENCLAW_DISABLE_BONJOUR=0 เฉพาะเมื่อรันด้วย host networking, macvlan หรือเครือข่ายอื่นที่ทราบว่า mDNS multicast ทำงานได้

สำหรับข้อควรระวังและการแก้ไขปัญหา ดู การค้นพบ Bonjour

พื้นที่จัดเก็บและการคงอยู่ของข้อมูล

Docker Compose จะ bind-mount OPENCLAW_CONFIG_DIR ไปยัง /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR ไปยัง /home/node/.openclaw/workspace และ OPENCLAW_AUTH_PROFILE_SECRET_DIR ไปยัง /home/node/.config/openclaw เพื่อให้พาธเหล่านั้น คงอยู่หลังการแทนที่คอนเทนเนอร์ เมื่อไม่ได้ตั้งค่าตัวแปรใด ๆ docker-compose.yml ที่ bundled จะ fallback ไปใต้ ${HOME} หรือ /tmp เมื่อ HOME เองก็หายไปด้วย ซึ่งช่วยป้องกันไม่ให้ docker compose up ปล่อย volume spec ที่มี source ว่าง บนสภาพแวดล้อมเปล่า

ไดเรกทอรี config ที่ mount นั้นคือที่ที่ OpenClaw เก็บ:

• openclaw.json สำหรับ config พฤติกรรม
• agents/<agentId>/agent/auth-profiles.json สำหรับ auth ของ provider OAuth/API-key ที่จัดเก็บไว้
• .env สำหรับความลับ runtime ที่หนุนด้วย env เช่น OPENCLAW_GATEWAY_TOKEN

ไดเรกทอรีคีย์ลับของ auth-profile เก็บคีย์เข้ารหัสภายในเครื่องที่ใช้สำหรับ ข้อมูลโทเค็นของ auth profile ที่หนุนด้วย OAuth เก็บไว้กับสถานะโฮสต์ Docker ของคุณ แต่แยกออกจาก OPENCLAW_CONFIG_DIR

Plugin ที่ดาวน์โหลดมาติดตั้งจะเก็บสถานะแพ็กเกจไว้ใต้ OpenClaw home ที่เมานต์ไว้ ดังนั้นระเบียนการติดตั้ง Plugin และรากแพ็กเกจจึงคงอยู่รอดจากการเปลี่ยนคอนเทนเนอร์ การเริ่มต้น Gateway จะไม่สร้างแผนผัง dependency ของ Plugin ที่บันเดิลมา

สำหรับรายละเอียดการคงอยู่แบบเต็มในการปรับใช้ VM ดู Docker VM Runtime - สิ่งใดคงอยู่ที่ใด

จุดที่ดิสก์เติบโตเร็ว: เฝ้าดู media/, ไฟล์ JSONL ของเซสชัน, cron/runs/*.jsonl, รากแพ็กเกจของ Plugin ที่ติดตั้งแล้ว และ rolling file logs ใต้ /tmp/openclaw/

ตัวช่วย Shell (ไม่บังคับ)

เพื่อให้จัดการ Docker ในแต่ละวันได้ง่ายขึ้น ให้ติดตั้ง ClawDock:

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 ~/.zshrc

หากคุณติดตั้ง ClawDock จากพาธ raw เก่า scripts/shell-helpers/clawdock-helpers.sh ให้รันคำสั่งติดตั้งด้านบนอีกครั้ง เพื่อให้ไฟล์ตัวช่วยในเครื่องของคุณติดตามตำแหน่งใหม่

จากนั้นใช้ clawdock-start, clawdock-stop, clawdock-dashboard ฯลฯ รัน clawdock-help เพื่อดูคำสั่งทั้งหมด ดู ClawDock สำหรับคู่มือตัวช่วยฉบับเต็ม

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probedocker 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-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"]

กำลังรันบน VPS ใช่ไหม?

ดู Hetzner (Docker VPS) และ Docker VM Runtime สำหรับขั้นตอนการปรับใช้ VM ร่วมกัน รวมถึงการฝังไบนารี การคงอยู่ และการอัปเดต

Agent sandbox

เมื่อเปิดใช้งาน agents.defaults.sandbox ด้วย backend ของ Docker, gateway จะรันการดำเนินการเครื่องมือของ agent (shell, การอ่าน/เขียนไฟล์ ฯลฯ) ภายในคอนเทนเนอร์ Docker ที่แยกอยู่ ขณะที่ gateway เองยังอยู่บนโฮสต์ วิธีนี้ให้กำแพงแข็งแรง รอบเซสชัน agent ที่ไม่ไว้วางใจหรือมีผู้เช่าหลายราย โดยไม่ต้องทำให้ gateway ทั้งหมด เป็นคอนเทนเนอร์

ขอบเขต sandbox สามารถเป็นต่อ agent (ค่าเริ่มต้น), ต่อเซสชัน หรือใช้ร่วมกัน แต่ละขอบเขต จะมี workspace ของตัวเองเมานต์ที่ /workspace คุณยังสามารถกำหนดค่า นโยบาย allow/deny ของเครื่องมือ การแยกเครือข่าย ขีดจำกัดทรัพยากร และคอนเทนเนอร์เบราว์เซอร์ได้

สำหรับคอนฟิกทั้งหมด images, หมายเหตุความปลอดภัย และโปรไฟล์ multi-agent ดู:

• Sandboxing -- เอกสารอ้างอิง sandbox ฉบับสมบูรณ์
• OpenShell -- การเข้าถึง shell แบบโต้ตอบไปยังคอนเทนเนอร์ sandbox
• Multi-Agent Sandbox and Tools -- override ต่อ agent

เปิดใช้งานแบบเร็ว

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

สร้าง sandbox image เริ่มต้น (จาก source checkout):

scripts/sandbox-setup.sh

สำหรับการติดตั้งผ่าน npm โดยไม่มี source checkout ดู Sandboxing § Images and setup สำหรับคำสั่ง docker build แบบ inline

การแก้ไขปัญหา

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker 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

ที่เกี่ยวข้อง

• ภาพรวมการติดตั้ง — วิธีติดตั้งทั้งหมด
• Podman — ทางเลือก Podman แทน Docker
• ClawDock — การตั้งค่า Docker Compose ของชุมชน
• การอัปเดต — การทำให้ OpenClaw ทันสมัยอยู่เสมอ
• Configuration — คอนฟิก gateway หลังการติดตั้ง