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 สำหรับการสร้างอิมเมจ (pnpm install อาจถูก OOM-killed บนโฮสต์ 1 GB พร้อมรหัสออก 137)
• พื้นที่ดิสก์เพียงพอสำหรับอิมเมจและบันทึก
• หากรันบน VPS/โฮสต์สาธารณะ ให้ตรวจทาน การเสริมความปลอดภัยสำหรับการเปิดเผยบนเครือข่าย, โดยเฉพาะนโยบายไฟร์วอลล์ Docker DOCKER-USER

Gateway แบบคอนเทนเนอร์

./scripts/docker/setup.sh

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

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

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

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

อิมเมจ Docker อย่างเป็นทางการไม่ได้มาพร้อม Homebrew ระหว่าง onboarding OpenClaw จะซ่อนตัวติดตั้ง dependencies ของ skill ที่มีเฉพาะ brew เมื่อรันในคอนเทนเนอร์ Linux ที่ไม่มี brew; dependencies เหล่านั้นต้องจัดเตรียมโดยอิมเมจ custom หรือ ติดตั้งด้วยตนเอง สำหรับ dependencies ที่มีจากแพ็กเกจ Debian ให้ใช้ OPENCLAW_IMAGE_APT_PACKAGES ระหว่างการสร้างอิมเมจ ชื่อ legacy OPENCLAW_DOCKER_APT_PACKAGES ยังรองรับอยู่ สำหรับ dependencies ของ Python ให้ใช้ OPENCLAW_IMAGE_PIP_PACKAGES คำสั่งนี้รัน python3 -m pip install --break-system-packages ระหว่างการสร้างอิมเมจ ดังนั้นให้ pin เวอร์ชันแพ็กเกจและใช้เฉพาะดัชนีแพ็กเกจที่คุณเชื่อถือ

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

Observability

การ export OpenTelemetry เป็นขาออกจากคอนเทนเนอร์ Gateway ไปยังตัวรวบรวม OTLP ของคุณ ไม่จำเป็นต้องมีพอร์ต Docker ที่เผยแพร่ หากคุณสร้างอิมเมจในเครื่อง และต้องการให้ตัว export OpenTelemetry ที่ bundled พร้อมใช้งานภายในอิมเมจ ให้รวม 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 แบบแพ็กเกจก่อนเปิดใช้การ export อิมเมจ custom ที่สร้างจากซอร์สยังสามารถ รวมซอร์ส plugin ในเครื่องด้วย OPENCLAW_EXTENSIONS=diagnostics-otel ได้ หากต้องการเปิดใช้การ export ให้อนุญาตและเปิดใช้ Plugin diagnostics-otel ใน config จากนั้นตั้งค่า diagnostics.otel.enabled=true หรือใช้ตัวอย่าง config ใน การ export OpenTelemetry ส่วนหัว auth ของตัวรวบรวมกำหนดค่าผ่าน diagnostics.otel.headers ไม่ใช่ผ่านตัวแปรสภาพแวดล้อม Docker

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

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

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

Health checks

endpoint ตรวจสอบคอนเทนเนอร์ (ไม่ต้องมี auth):

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

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

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

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: เฉพาะกระบวนการภายใน namespace เครือข่ายของคอนเทนเนอร์เท่านั้นที่เข้าถึง Gateway ได้โดยตรง

Providers ในเครื่องของโฮสต์

เมื่อ 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 บนที่อยู่ที่ 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.

แบ็กเอนด์ Claude CLI ใน Docker

อิมเมจ Docker อย่างเป็นทางการของ OpenClaw ไม่ได้ติดตั้ง Claude Code ไว้ล่วงหน้า ให้ติดตั้งและ เข้าสู่ระบบ Claude Code ภายในผู้ใช้ของคอนเทนเนอร์ที่รัน OpenClaw จากนั้นคงอยู่ home ของคอนเทนเนอร์นั้นไว้ เพื่อไม่ให้การอัปเกรดอิมเมจลบไบนารีหรือสถานะการยืนยันตัวตน Claude

สำหรับการติดตั้ง Docker ใหม่ ให้เปิดใช้ volume /home/node แบบคงอยู่ก่อนรัน setup:

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

สำหรับการติดตั้ง Docker ที่มีอยู่แล้ว ให้หยุด stack ก่อน แล้วโหลดค่า Docker .env ปัจจุบันอีกครั้งก่อนรัน setup ซ้ำ สคริปต์ setup ไม่ได้อ่าน .env เอง แต่จะเขียน .env ใหม่จาก shell ปัจจุบันและค่าเริ่มต้น สำหรับ .env ที่สร้างขึ้น ให้รัน:

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

หาก .env ของคุณมีค่าที่ shell ของคุณ source ไม่ได้ ให้ re-export ค่าที่มีอยู่ซึ่งคุณต้องพึ่งพาด้วยตนเองก่อน เช่น OPENCLAW_IMAGE, พอร์ต, โหมด bind, พาธที่กำหนดเอง, OPENCLAW_EXTRA_MOUNTS, sandbox และการตั้งค่า skip-onboarding overlay ที่สร้างขึ้นจะ mount home volume สำหรับทั้ง openclaw-gateway และ openclaw-cli

รันคำสั่งที่เหลือด้วย Compose overlay ที่สร้างขึ้น เพื่อให้ทั้งสองบริการ mount home ที่คงอยู่ หาก setup ของคุณใช้ docker-compose.override.yml ด้วย ให้รวมไว้ก่อน docker-compose.extra.yml

ติดตั้ง Claude Code ใน home ที่คงอยู่นั้น:

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'

ตัวติดตั้ง native จะเขียนไบนารี claude ไว้ใต้ /home/node/.local/bin/claude แจ้งให้ OpenClaw ใช้พาธคอนเทนเนอร์นั้น:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

เข้าสู่ระบบและตรวจสอบจากภายใน home ของคอนเทนเนอร์แบบคงอยู่เดียวกัน:

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 anthropic

หลังจากนั้น คุณสามารถใช้แบ็กเอนด์ claude-cli ที่มาพร้อมชุดได้:

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 "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME ทำให้การติดตั้ง Claude Code แบบ native คงอยู่ใต้ /home/node/.local/bin และ /home/node/.local/share/claude รวมถึงการตั้งค่า Claude Code และสถานะการยืนยันตัวตนใต้ /home/node/.claude และ /home/node/.claude.json การคงอยู่เฉพาะ /home/node/.openclaw ไม่เพียงพอสำหรับการใช้ Claude CLI ซ้ำ หาก คุณใช้ OPENCLAW_EXTRA_MOUNTS แทน home volume ให้ mount พาธ Claude ทั้งหมดเหล่านั้น เข้าไปในทั้งสองบริการ Docker

Bonjour / mDNS

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

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

สำหรับข้อควรระวังและการแก้ปัญหา ดู การค้นพบ 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 ที่มาพร้อมชุดจะ fallback ไปใต้ ${HOME} หรือ /tmp เมื่อ HOME เองก็ ไม่มีอยู่เช่นกัน ซึ่งช่วยป้องกันไม่ให้ docker compose up ส่งออก spec ของ volume ที่มี source ว่างในสภาพแวดล้อมเปล่า

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

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

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

Plugin ที่ดาวน์โหลดได้ซึ่งติดตั้งแล้วจะเก็บสถานะ package ของตนไว้ใต้ home ของ OpenClaw ที่ mount ไว้ ดังนั้น record การติดตั้ง Plugin และ root ของ package จะคงอยู่หลังการแทนที่คอนเทนเนอร์ การเริ่มต้น Gateway ไม่ได้สร้าง dependency tree ของ bundled-plugin

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

จุดที่ดิสก์มีแนวโน้มโตเร็ว: เฝ้าดู media/, ไฟล์ JSONL ของเซสชัน, ฐานข้อมูลสถานะ SQLite แบบใช้ร่วมกัน, รากแพ็กเกจ Plugin ที่ติดตั้งแล้ว และล็อกไฟล์แบบหมุนเวียนภายใต้ /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 สำหรับขั้นตอนการปรับใช้ VM ร่วม รวมถึงการอบไบนารี การคงอยู่ของข้อมูล และการอัปเดต

แซนด์บ็อกซ์ของเอเจนต์

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

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

สำหรับการกำหนดค่าฉบับเต็ม อิมเมจ หมายเหตุด้านความปลอดภัย และโปรไฟล์หลายเอเจนต์ ดู:

• แซนด์บ็อกซ์ -- เอกสารอ้างอิงแซนด์บ็อกซ์ฉบับครบถ้วน
• OpenShell -- การเข้าถึง shell แบบโต้ตอบไปยังคอนเทนเนอร์แซนด์บ็อกซ์
• แซนด์บ็อกซ์และเครื่องมือหลายเอเจนต์ -- การกำหนดทับรายเอเจนต์

เปิดใช้อย่างรวดเร็ว

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

สร้างอิมเมจแซนด์บ็อกซ์เริ่มต้น (จาก source checkout):

scripts/sandbox-setup.sh

สำหรับการติดตั้ง npm ที่ไม่มี source checkout โปรดดู แซนด์บ็อกซ์ § อิมเมจและการตั้งค่า สำหรับคำสั่ง 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 เป็นเวอร์ชันล่าสุดอยู่เสมอ
• การกำหนดค่า — การกำหนดค่า gateway หลังติดตั้ง