OpenClaw Docker 浏览器与插件配置完整教程
# OpenClaw Docker 浏览器与插件配置完整教程
## 概述
本教程记录了在 Docker 环境中为 OpenClaw 配置浏览器功能和自定义插件（mcp-newsnow）的完整过程。
**配置目标：**
– ✅ 启用浏览器自动化功能（Chromium + Playwright）
– ✅ 集成自定义插件 mcp-newsnow（新闻聚合服务）
– ✅ 持久化 Playwright 浏览器缓存（避免重复下载）
**最终效果：**
– 浏览器功能：支持打开网页、截图、快照、点击、输入等操作
– mcp-newsnow 插件：提供 14 个新闻源的搜索 API
– 容器状态：健康运行，所有功能正常
—
## 前置条件
### 环境要求
– Docker 和 Docker Compose 已安装
– OpenClaw 源码目录：`/media/george/AI/openclaw`
– 配置目录：`/home/george/.openclaw`
– 磁盘空间：至少 1GB 可用（镜像 300MB + volume 300MB）
### 文件结构
“`
/media/george/AI/openclaw/
├── docker-compose.yml # Docker Compose 配置
├── Dockerfile # 主镜像构建文件
├── extensions/ # 内置插件目录
│ ├── feishu/
│ ├── acpx/
│ └── mcp-newsnow/ # 新增插件
└── .env # 环境变量
/home/george/.openclaw/
├── openclaw.json # OpenClaw 主配置
├── extensions/ # 用户插件目录（已清空）
└── workspace/ # 工作区
“`
—
## 第一步：修改 docker-compose.yml
### 1.1 添加 Playwright 缓存持久化
编辑 `/media/george/AI/openclaw/docker-compose.yml`：
“`yaml
services:
openclaw-gateway:
image: openclaw:local
container_name: Geo_Clawbot
privileged: true
environment:
HOME: /home/node
TERM: xterm-256color
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
[API_KEY]: ${[API_KEY]:-}
CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
volumes:
– ${OPENCLAW_CONFIG_DIR}:[工作区路径]
– ${OPENCLAW_WORKSPACE_DIR}:[工作区路径]/workspace
– /media/george/AI/my_share_folder:/home/node/share:rw
– ./docker-entrypoint.sh:/docker-entrypoint.sh:ro
# 新增：持久化 Playwright 浏览器缓存
– openclaw-playwright-cache:/home/node/.cache/ms-playwright
ports:
– “${OPENCLAW_GATEWAY_PORT:-18789}:18789”
– “${OPENCLAW_BRIDGE_PORT:-18790}:18790”
init: true
restart: unless-stopped
entrypoint: [“/bin/sh”, “/docker-entrypoint.sh”]
healthcheck:
test:
[
“CMD”,
“node”,
“-e”,
“fetch(‘http://127.0.0.1:18789/healthz’).then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))”,
]
interval: 30s
timeout: 5s
retries: 5
start_period: 20s
networks:
– openclaw_default
– shared_network
networks:
openclaw_default:
driver: bridge
shared_network:
external: true
# 新增：定义 Playwright 缓存 volume
volumes:
openclaw-playwright-cache:
driver: local
“`
**关键变更：**
– 第 19 行：添加 Playwright 缓存 volume 挂载
– 第 76-78 行：定义 named volume
—
## 第二步：添加自定义插件到镜像
### 2.1 复制插件到源码目录
“`bash
# 将插件从用户目录复制到源码 extensions 目录
cp -r /home/george/.openclaw/extensions/mcp-newsnow /media/george/AI/openclaw/extensions/
# 验证插件文件
ls -la /media/george/AI/openclaw/extensions/mcp-newsnow/
“`
**预期输出：**
“`
total 40
drwxr-xr-x 2 george george 4096 Mar 10 20:59 .
drwxrwxr-x 43 george george 4096 Mar 10 14:47 ..
-rw-r–r– 1 george george 4836 Mar 10 20:59 fetch-priority-news.js
-rw-r–r– 1 george george 1957 Mar 10 20:59 full-text-fetcher.js
-rw-r–r– 1 george george 8294 Mar 10 20:59 index.ts
-rw-r–r– 1 george george 723 Mar 10 20:59 openclaw.plugin.json
-rw-r–r– 1 george george 217 Mar 10 20:59 package.json
“`
### 2.2 验证插件清单
“`bash
cat /media/george/AI/openclaw/extensions/mcp-newsnow/openclaw.plugin.json
“`
**必需字段：**
“`json
{
“id”: “mcp-newsnow”,
“name”: “MCP NewsNow Client”,
“version”: “1.0.0”,
“configSchema”: {
“type”: “object”,
“additionalProperties”: false,
“properties”: {}
}
}
“`
**重要提示：**
– `id` 必须与目录名一致
– `configSchema` 必须存在（即使为空对象）
– `entry` 字段指向插件入口文件（支持 `.ts` 和 `.js`）
—
## 第三步：重新构建 Docker 镜像
### 3.1 构建命令
“`bash
cd /media/george/AI/openclaw
# 构建镜像（添加浏览器支持）
docker build –build-arg OPENCLAW_INSTALL_BROWSER=1 -t openclaw:local .
“`
**构建参数说明：**
– `OPENCLAW_INSTALL_BROWSER=1`：安装 Chromium + Playwright（约 300MB）
– 构建时间：约 5-10 分钟（取决于网络速度）
### 3.2 构建过程关键步骤
“`
# 安装 Xvfb（虚拟帧缓冲）
RUN apt-get install -y xvfb
# 安装 Playwright 浏览器
RUN PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright \
node /app/node_modules/playwright-core/cli.js install –with-deps chromium
# 下载内容：
– Chrome for Testing 145.0.7632.6 (167.3 MB)
– FFmpeg (2.3 MB)
– Chrome Headless Shell (约 100 MB)
“`
### 3.3 验证镜像构建成功
“`bash
# 检查镜像大小
docker images openclaw:local
# 检查插件是否包含在镜像中
docker run –rm openclaw:local ls -la /app/extensions/mcp-newsnow/
# 检查 Playwright 浏览器
docker run –rm openclaw:local ls -la /home/node/.cache/ms-playwright/
“`
—
## 第四步：更新 OpenClaw 配置
### 4.1 浏览器配置
编辑 `/home/george/.openclaw/openclaw.json`，添加浏览器配置：
“`json
{
“browser”: {
“enabled”: true,
“executablePath”: “/home/node/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome”,
“noSandbox”: true,
“headless”: true,
“defaultProfile”: “openclaw”,
“ssrfPolicy”: {
“dangerouslyAllowPrivateNetwork”: true
},
“profiles”: {
“openclaw”: {
“cdpPort”: 18800,
“color”: “#FF4500”
}
}
}
}
“`
**关键配置说明：**
| 参数 | 值 | 说明 |
|——|—–|——|
| `executablePath` | Playwright Chrome 路径 | 必须指向实际安装位置 |
| `noSandbox` | `true` | **容器环境必须禁用沙箱** |
| `headless` | `true` | **无 GUI 环境必须使用无头模式** |
| `cdpPort` | `18800` | Chrome DevTools Protocol 端口 |
### 4.2 插件配置
“`json
{
“plugins”: {
“enabled”: true,
“entries”: {
“feishu”: {
“enabled”: true
},
“acpx”: {
“enabled”: true
},
“mcp-newsnow”: {
“enabled”: true
}
}
}
}
“`
**配置说明：**
– `plugins.enabled`：全局插件开关
– `plugins.entries`：每个插件的启用状态
– 内置插件（`/app/extensions/`）会自动发现，无需额外配置路径
### 4.3 完整配置示例
“`json
{
“meta”: {
“lastTouchedVersion”: “2026.3.8”,
“lastTouchedAt”: “2026-03-10T07:11:21.627Z”
},
“gateway”: {
“port”: 18789,
“mode”: “local”,
“bind”: “loopback”,
“auth”: {
“mode”: “token”,
“token”: “your-token-here”
}
},
“browser”: {
“enabled”: true,
“executablePath”: “/home/node/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome”,
“noSandbox”: true,
“headless”: true,
“defaultProfile”: “openclaw”,
“profiles”: {
“openclaw”: {
“cdpPort”: 18800,
“color”: “#FF4500”
}
}
},
“plugins”: {
“enabled”: true,
“entries”: {
“feishu”: { “enabled”: true },
“acpx”: { “enabled”: true },
“mcp-newsnow”: { “enabled”: true }
}
}
}
“`
—
## 第五步：启动容器并验证
### 5.1 启动容器
“`bash
cd /media/george/AI/openclaw
# 停止旧容器（如果存在）
docker compose down
# 启动新容器
docker compose up -d
# 查看启动日志
docker compose logs -f openclaw-gateway
“`
### 5.2 等待容器健康
“`bash
# 查看容器状态（等待 STATUS 变为 healthy）
docker compose ps
# 预期输出：
# NAME STATUS
# Geo_Clawbot Up (healthy)
“`
**健康检查时间线：**
– 0-20 秒：容器启动
– 20-40 秒：健康检查开始
– 40-60 秒：状态变为 healthy
—
## 第六步：验证浏览器功能
### 6.1 检查浏览器状态
“`bash
docker compose exec openclaw-gateway openclaw browser status
“`
**预期输出：**
“`
profile: openclaw
enabled: true
running: false
cdpPort: 18800
cdpUrl: http://127.0.0.1:18800
browser: unknown
detectedBrowser: custom
detectedPath: ~/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome
profileColor: #FF4500
“`
### 6.2 启动浏览器
“`bash
docker compose exec openclaw-gateway openclaw browser start
“`
**预期输出：**
“`
🦞 browser [openclaw] running: true
“`
### 6.3 测试打开网页
“`bash
docker compose exec openclaw-gateway openclaw browser open https://example.com
“`
**预期输出：**
“`
opened: https://example.com/
id: [API_KEY]
“`
### 6.4 测试页面快照
“`bash
docker compose exec openclaw-gateway openclaw browser snapshot
“`
**预期输出：**
“`
– generic [ref=e2]:
– heading “Example Domain” [level=1] [ref=e3]
– paragraph [ref=e4]: This domain is for use in documentation examples…
– paragraph [ref=e5]:
– link “Learn more” [ref=e6] [cursor=pointer]:
– /url: https://iana.org/domains/example
“`
### 6.5 测试截图功能
“`bash
docker compose exec openclaw-gateway openclaw browser screenshot
“`
**预期输出：**
“`
MEDIA:~/.openclaw/media/browser/[API_KEY].png
“`
### 6.6 停止浏览器
“`bash
docker compose exec openclaw-gateway openclaw browser stop
“`
—
## 第七步：验证 mcp-newsnow 插件
### 7.1 检查插件状态
“`bash
docker compose exec openclaw-gateway openclaw doctor | grep -A 20 “Plugins”
“`
**预期输出：**
“`
◇ Plugins ──────╮
│ │
│ Loaded: 8 │
│ Disabled: 31 │
│ Errors: 0 │
│ │
├────────────────╯
“`
### 7.2 测试健康检查端点
“`bash
docker compose exec openclaw-gateway curl -s http://127.0.0.1:18799/health | jq ‘.’
“`
**预期输出：**
“`json
{
“status”: “ok”,
“service”: “mcp-newsnow-v2”,
“newsnow”: “http://newsnow:4444”,
“sources”: [
“cls”, “wallstreetcn”, “xueqiu”, “gelonghui”, “jin10”,
“mktnews”, “fastbull”, “36kr”, “ithome”, “v2ex”,
“zhihu”, “toutiao”, “weibo”, “douyin”
],
“timestamp”: “2026-03-10T13:25:59.411Z”
}
“`
### 7.3 测试搜索功能
“`bash
docker compose exec openclaw-gateway curl -s “http://127.0.0.1:18799/search?q=AI&limit=3” | jq ‘.’
“`
**预期输出：**
“`json
{
“success”: true,
“query”: “AI”,
“count”: 2,
“articles”: [
{
“title”: “何小鹏：2026 年将会是 AI 走向物理世界的元年”,
“url”: “https://www.ithome.com/0/927/717.htm”,
“source”: “ithome”,
“publishedAt”: “2026-03-10T13:26:21.814Z”
}
]
}
“`
—
## 故障排除
### 问题 1：容器无法启动，报错 “plugin manifest not found”
**原因：** 插件清单文件缺失或路径错误
**解决方案：**
“`bash
# 1. 检查插件清单是否存在
ls -la /media/george/AI/openclaw/extensions/mcp-newsnow/openclaw.plugin.json
# 2. 验证清单内容
cat /media/george/AI/openclaw/extensions/mcp-newsnow/openclaw.plugin.json | jq ‘.id’
# 3. 重新构建镜像
docker build –build-arg OPENCLAW_INSTALL_BROWSER=1 -t openclaw:local .
“`
### 问题 2：浏览器启动失败，报错 “No supported browser found”
**原因：** 浏览器可执行文件路径未配置
**解决方案：**
“`bash
# 1. 查找 Chrome 实际路径
docker compose exec openclaw-gateway find /home/node/.cache/ms-playwright -name “chrome”
# 2. 更新配置文件
cat /home/george/.openclaw/openclaw.json | jq ‘.browser.executablePath = “/home/node/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome”‘ > /tmp/config.json && mv /tmp/config.json /home/george/.openclaw/openclaw.json
# 3. 重启容器
docker compose restart openclaw-gateway
“`
### 问题 3：浏览器启动失败，报错 “Missing X server or $DISPLAY”
**原因：** 容器环境缺少 GUI 支持
**解决方案：**
“`bash
# 添加无头模式和禁用沙箱配置
cat /home/george/.openclaw/openclaw.json | jq ‘.browser.noSandbox = true | .browser.headless = true’ > /tmp/config.json && mv /tmp/config.json /home/george/.openclaw/openclaw.json
# 重启容器
docker compose restart openclaw-gateway
“`
### 问题 4：插件重复加载警告
**原因：** 插件同时存在于镜像和用户目录
**解决方案：**
“`bash
# 删除用户目录中的重复插件
rm -rf /home/george/.openclaw/extensions/mcp-newsnow
# 重启容器
docker compose restart openclaw-gateway
“`
### 问题 5：Playwright 浏览器未安装
**原因：** 镜像构建时未添加 `OPENCLAW_INSTALL_BROWSER=1` 参数
**解决方案：**
“`bash
# 重新构建镜像
docker build –build-arg OPENCLAW_INSTALL_BROWSER=1 -t openclaw:local .
# 重启容器
docker compose down && docker compose up -d
“`
—
## 配置文件完整示例
### docker-compose.yml
“`yaml
services:
openclaw-gateway:
image: openclaw:local
container_name: Geo_Clawbot
privileged: true
environment:
HOME: /home/node
TERM: xterm-256color
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
volumes:
– ${OPENCLAW_CONFIG_DIR}:[工作区路径]
– ${OPENCLAW_WORKSPACE_DIR}:[工作区路径]/workspace
– openclaw-playwright-cache:/home/node/.cache/ms-playwright
ports:
– “18789:18789”
– “18790:18790”
init: true
restart: unless-stopped
healthcheck:
test: [“CMD”, “node”, “-e”, “fetch(‘http://127.0.0.1:18789/healthz’).then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))”]
interval: 30s
timeout: 5s
retries: 5
start_period: 20s
volumes:
openclaw-playwright-cache:
driver: local
“`
### openclaw.json（浏览器部分）
“`json
{
“browser”: {
“enabled”: true,
“executablePath”: “/home/node/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome”,
“noSandbox”: true,
“headless”: true,
“defaultProfile”: “openclaw”,
“ssrfPolicy”: {
“dangerouslyAllowPrivateNetwork”: true
},
“profiles”: {
“openclaw”: {
“cdpPort”: 18800,
“color”: “#FF4500”
}
}
}
}
“`
### openclaw.json（插件部分）
“`json
{
“plugins”: {
“enabled”: true,
“entries”: {
“feishu”: { “enabled”: true },
“acpx”: { “enabled”: true },
“mcp-newsnow”: { “enabled”: true }
}
}
}
“`
—
## 常用命令速查
### 容器管理
“`bash
# 启动容器
docker compose up -d
# 停止容器
docker compose down
# 重启容器
docker compose restart openclaw-gateway
# 查看日志
docker compose logs -f openclaw-gateway
# 查看容器状态
docker compose ps
“`
### 浏览器操作
“`bash
# 查看状态
docker compose exec openclaw-gateway openclaw browser status
# 启动浏览器
docker compose exec openclaw-gateway openclaw browser start
# 打开网页
docker compose exec openclaw-gateway openclaw browser open https://example.com
# 页面快照
docker compose exec openclaw-gateway openclaw browser snapshot
# 截图
docker compose exec openclaw-gateway openclaw browser screenshot
# 停止浏览器
docker compose exec openclaw-gateway openclaw browser stop
“`
### 插件管理
“`bash
# 检查插件状态
docker compose exec openclaw-gateway openclaw doctor | grep -A 20 “Plugins”
# 测试 mcp-newsnow 健康检查
docker compose exec openclaw-gateway curl -s http://127.0.0.1:18799/health | jq ‘.’
# 测试搜索功能
docker compose exec openclaw-gateway curl -s “http://127.0.0.1:18799/search?q=AI&limit=5” | jq ‘.’
“`
—
## 总结
### 配置要点
1. **浏览器功能**
– 必须在镜像构建时安装 Playwright（`OPENCLAW_INSTALL_BROWSER=1`）
– 容器环境必须设置 `noSandbox: true` 和 `headless: true`
– 使用 volume 持久化浏览器缓存，避免重复下载
2. **自定义插件**
– 将插件放入源码 `extensions/` 目录，构建到镜像中
– 插件清单 `openclaw.plugin.json` 必须包含 `id` 和 `configSchema`
– 在配置文件中启用插件：`plugins.entries.
3. **Docker 配置**
– 使用 named volume 持久化数据
– 设置合理的健康检查间隔
– 使用 `privileged: true` 确保浏览器权限
### 资源占用
– **镜像大小**：约 1.2GB（基础镜像 + 浏览器 + 插件）
– **Playwright 浏览器**：约 300MB
– **运行时内存**：约 500MB-1GB（取决于浏览器使用情况）
### 下一步
– 配置 Agent 使用浏览器工具进行自动化任务
– 集成 mcp-newsnow API 到 Agent 工作流
– 监控容器资源使用情况，优化配置
—
**文档版本：** 1.0
**最后更新：** 2026-03-10
**作者：** 小智 – 技术专家
**适用版本：** OpenClaw 2026.3.8+
