Docker

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

# Docker เหมาะกับฉันไหม?

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

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

• Docker Desktop (หรือ Docker Engine) + Docker Compose v2
• RAM อย่างน้อย 2 GB สำหรับการสร้างอิมเมจ (pnpm install อาจถูกหยุดเพราะหน่วยความจำไม่พอบนโฮสต์ 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 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>"

# โฟลว์แบบแมนนวล

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

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

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

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

ผู้ดูแลสามารถทดสอบซอร์สของ 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 สำหรับ id ของ Plugin เดียวกัน

# การสังเกตการณ์

การ export OpenTelemetry เป็นขาออกจากคอนเทนเนอร์ Gateway ไปยังตัวรวบรวม OTLP ของคุณ โดยไม่ต้องใช้พอร์ต Docker ที่เผยแพร่ไว้ หากคุณสร้างอิมเมจในเครื่อง และต้องการให้ exporter OpenTelemetry แบบ bundled พร้อมใช้งานในอิมเมจ ให้รวม dependency รันไทม์ของมันด้วย:

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 อิมเมจที่สร้างจากซอร์สแบบกำหนดเอง ยังคงรวมซอร์ส Plugin ในเครื่องได้ด้วย OPENCLAW_EXTENSIONS=diagnostics-otel หากต้องการเปิดใช้การ export ให้ allow และ enable Plugin diagnostics-otel ในคอนฟิก จากนั้นตั้ง diagnostics.otel.enabled=true หรือใช้ตัวอย่างคอนฟิกใน การ export OpenTelemetry ตั้งค่าส่วนหัวสำหรับการยืนยันตัวตนของตัวรวบรวมผ่าน diagnostics.otel.headers ไม่ใช่ผ่านตัวแปรสภาพแวดล้อมของ Docker

เมตริก Prometheus ใช้พอร์ต Gateway ที่เผยแพร่ไว้แล้ว ติดตั้ง clawhub:@openclaw/diagnostics-prometheus เปิดใช้ Plugin diagnostics-prometheus จากนั้น scrape:

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

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

# การตรวจสอบสุขภาพ

endpoint สำหรับ probe คอนเทนเนอร์ (ไม่ต้องใช้การยืนยันตัวตน):

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

อิมเมจ Docker มี 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: เฉพาะโปรเซสภายใน 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 มี ชื่อโฮสต์เดียวกันให้ใช้อยู่แล้วบน macOS และ Windows

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

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

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

# Bonjour / mDNS

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

ใช้ URL Gateway ที่เผยแพร่ไว้, Tailscale หรือ DNS-SD แบบ wide-area สำหรับโฮสต์ 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 ดังนั้นพาธเหล่านั้น จะอยู่รอดหลังการแทนที่คอนเทนเนอร์ เมื่อไม่ได้ตั้งค่าตัวแปรใดตัวแปรหนึ่ง docker-compose.yml แบบ bundled จะ fallback ไปที่ ${HOME}/.openclaw (และ ${HOME}/.openclaw/workspace สำหรับ workspace mount) หรือ /tmp/.openclaw เมื่อ HOME เองก็หายไปด้วย วิธีนี้ทำให้ docker compose up ไม่ส่งออก volume spec ที่มี source ว่างเปล่าในสภาพแวดล้อมเปล่า

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

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

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

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

จุดที่ดิสก์โตเร็ว: เฝ้าดู media/, ไฟล์ JSONL ของเซสชัน, cron/runs/*.jsonl, รากแพ็กเกจ 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.sh
echo '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=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"]

# รันบน VPS?

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

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

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

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

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

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

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

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

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

scripts/sandbox-setup.sh

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

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

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

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

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