diff --git a/.env.example b/.env.example
index 6acb2258..4b9d24e8 100644
--- a/.env.example
+++ b/.env.example
@@ -28,3 +28,20 @@ JWT_SECRET=
 # CORS 白名单（逗号分隔，如 https://mateclaw.example.com,https://admin.example.com）。
 # 若留空，服务器会允许所有 origin 并在启动日志里 WARN。生产部署务必设置。
 MATECLAW_CORS_ALLOWED_ORIGINS=
+
+# ==================== 浏览器工具（可选） ====================
+#
+# Docker 镜像已经把 Chromium 打进去了，默认零配置可用。
+# 只有在下述场景才需要 override：
+#
+# 1) 把浏览器独立部署成 sidecar 容器，通过 CDP 连接：
+#    MATECLAW_BROWSER_CDP_URL=http://chrome-sidecar:9222
+#
+# 2) 指定非 Playwright 打包的浏览器（例如宿主机上已装的 Chrome）：
+#    MATECLAW_BROWSER_CHROME_PATH=/usr/bin/google-chrome-stable
+#
+# 3) 强制使用 Playwright channel（chrome / msedge / chrome-beta …）：
+#    MATECLAW_BROWSER_CHANNEL=chrome
+MATECLAW_BROWSER_CDP_URL=
+MATECLAW_BROWSER_CHROME_PATH=
+MATECLAW_BROWSER_CHANNEL=
diff --git a/docker-compose.yml b/docker-compose.yml
index 59310964..9bd2b24f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -73,6 +73,16 @@ services:
       MATECLAW_CORS_ALLOWED_ORIGINS: ${MATECLAW_CORS_ALLOWED_ORIGINS:-}
       # SearXNG: tell the app where to reach the sidecar container
       SEARXNG_BASE_URL: ${SEARXNG_BASE_URL:-http://searxng:8080}
+      # Browser automation: the runtime image (mcr.microsoft.com/playwright:*)
+      # bakes Chromium + system libs + fonts in, so the tool works out of the box.
+      # Override these if you want to attach to an external Chrome (CDP sidecar):
+      MATECLAW_BROWSER_CDP_URL: ${MATECLAW_BROWSER_CDP_URL:-}
+      MATECLAW_BROWSER_CHROME_PATH: ${MATECLAW_BROWSER_CHROME_PATH:-}
+      MATECLAW_BROWSER_CHANNEL: ${MATECLAW_BROWSER_CHANNEL:-}
+    # Chromium needs a real /dev/shm. Docker defaults to 64MB which causes
+    # SIGBUS / "Target page closed" errors under load. 2GB is the usual
+    # recommendation for Playwright / headless chrome.
+    shm_size: 2gb
     ports:
       - "18080:18088"   # host:container — app listens on 18088 inside the container
     volumes:
diff --git a/mateclaw-server/Dockerfile b/mateclaw-server/Dockerfile
index c7c865b7..e3220acb 100644
--- a/mateclaw-server/Dockerfile
+++ b/mateclaw-server/Dockerfile
@@ -42,8 +42,36 @@ COPY --from=frontend-builder /static ./src/main/resources/static
 RUN mvn package -DskipTests -q
 
 # Stage 3 — Runtime
-FROM eclipse-temurin:21-jre-alpine
+#
+# Uses Microsoft's official Playwright image (Ubuntu Noble, glibc) with all three
+# browsers (Chromium / Firefox / WebKit) and every system library Chromium needs
+# pre-installed. This avoids the `playwright install` step and the Alpine/musl
+# incompatibility that blocks browser_use on minimal images.
+#
+# We pin to the exact Playwright version declared in pom.xml (1.52.0). If you
+# bump the Java dependency, bump this tag in lockstep — Microsoft rebuilds each
+# tag with the matching driver, so mismatched versions cause the java driver to
+# re-download browsers at runtime (defeating the whole point of this image).
+FROM mcr.microsoft.com/playwright:v1.52.0-noble
 WORKDIR /app
+
+# JDK 21 is NOT part of the base image (it ships Node for the JS driver).
+# Install openjdk-21 explicitly and add CJK fonts so Chinese pages render
+# correctly in screenshots and snapshots.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        openjdk-21-jre-headless \
+        fonts-noto-cjk \
+        fonts-noto-color-emoji \
+        tzdata \
+    && rm -rf /var/lib/apt/lists/*
+
+# Tell Playwright Java where Microsoft's image stored the browsers.
+# BrowserLauncher's BUNDLED strategy will then succeed without extra config.
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright \
+    TZ=Asia/Shanghai \
+    JAVA_TOOL_OPTIONS="-Duser.timezone=Asia/Shanghai"
+
 COPY --from=builder /build/target/*.jar app.jar
 EXPOSE 18088
 ENTRYPOINT ["java", "-jar", "-Dspring.profiles.active=mysql", "app.jar"]