山波之家

还有砂糖和布丁
  • By - george
  • Posted on
  • Posted in 学习

OpenClaw Docker 浏览器与插件配置完整教程

# OpenClaw Docker 浏览器与插件配置完整教程

## 概述

本教程记录了在 Docker 环境中为 OpenClaw 配置浏览器功能和自定义插件（mcp-newsnow）的完整过程。

**配置目标：**
– ✅ 启用浏览器自动化功能（Chromium + Playwright）
– ✅ 集成自定义插件 mcp-newsnow（新闻聚合服务）
– ✅ 持久化 Playwright 浏览器缓存（避免重复下载）

**最终效果：**
– 浏览器功能：支持打开网页、截图、快照、点击、输入等操作
– mcp-newsnow 插件：提供 14 个新闻源的搜索 API
– 容器状态：健康运行，所有功能正常

—

## 前置条件

### 环境要求
– Docker 和 Docker Compose 已安装
– OpenClaw 源码目录：`/[openclaw-path]`
– 配置目录：`/[config-path]`
– 磁盘空间：至少 1GB 可用（镜像 300MB + volume 300MB）

### 文件结构

/[openclaw-path]/
├── docker-compose.yml          # Docker Compose 配置
├── Dockerfile                  # 主镜像构建文件
├── extensions/                 # 内置插件目录
│   ├── feishu/
│   ├── acpx/
│   └── mcp-newsnow/           # 新增插件
└── .env                        # 环境变量

/[config-path]/
├── openclaw.json               # OpenClaw 主配置
├── extensions/                 # 用户插件目录（已清空）
└── workspace/                  # 工作区

—

## 第一步：修改 docker-compose.yml

### 1.1 添加 Playwright 缓存持久化

编辑 `/[openclaw-path]/docker-compose.yml`：

services:
  openclaw-gateway:
    image: openclaw:local
    container_name: [container-name]
    privileged: true
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      [YOUR_API_KEY]: ${[YOUR_API_KEY]:-}
      [SESSION_KEY]:-}
      [SESSION_KEY]:-}
      [COOKIE]: ${[COOKIE]:-}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:[工作区路径]
      - ${OPENCLAW_WORKSPACE_DIR}:[工作区路径]/workspace
      - /[shared-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 复制插件到源码目录

# 将插件从用户目录复制到源码 extensions 目录
cp -r /[config-path]/extensions/mcp-newsnow /[openclaw-path]/extensions/

# 验证插件文件
ls -la /[openclaw-path]/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 验证插件清单

cat /[openclaw-path]/extensions/mcp-newsnow/openclaw.plugin.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 构建命令

cd /[openclaw-path]

# 构建镜像（添加浏览器支持）
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 验证镜像构建成功

# 检查镜像大小
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 浏览器配置

编辑 `/[config-path]/openclaw.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 插件配置

{
  "plugins": {
    "enabled": true,
    "entries": {
      "feishu": {
        "enabled": true
      },
      "acpx": {
        "enabled": true
      },
      "mcp-newsnow": {
        "enabled": true
      }
    }
  }
}

**配置说明：**
– `plugins.enabled`：全局插件开关
– `plugins.entries`：每个插件的启用状态
– 内置插件（`/app/extensions/`）会自动发现，无需额外配置路径

### 4.3 完整配置示例

{
  "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 启动容器

cd /[openclaw-path]

# 停止旧容器（如果存在）
docker compose down

# 启动新容器
docker compose up -d

# 查看启动日志
docker compose logs -f openclaw-gateway

### 5.2 等待容器健康

# 查看容器状态（等待 STATUS 变为 healthy）
docker compose ps

# 预期输出：
# NAME          STATUS
# [container-name]   Up (healthy)

**健康检查时间线：**
– 0-20 秒：容器启动
– 20-40 秒：健康检查开始
– 40-60 秒：状态变为 healthy

—

## 第六步：验证浏览器功能

### 6.1 检查浏览器状态

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 启动浏览器

docker compose exec openclaw-gateway openclaw browser start

**预期输出：**

🦞 browser [openclaw] running: true

### 6.3 测试打开网页

docker compose exec openclaw-gateway openclaw browser open https://example.com

**预期输出：**

opened: https://example.com/
id: [YOUR_API_KEY]

### 6.4 测试页面快照

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 测试截图功能

docker compose exec openclaw-gateway openclaw browser screenshot

**预期输出：**

MEDIA:~/.openclaw/media/browser/[YOUR_API_KEY].png

### 6.6 停止浏览器

docker compose exec openclaw-gateway openclaw browser stop

—

## 第七步：验证 mcp-newsnow 插件

### 7.1 检查插件状态

docker compose exec openclaw-gateway openclaw doctor | grep -A 20 "Plugins"

**预期输出：**

◇  Plugins ──────╮
│                │
│  Loaded: 8     │
│  Disabled: 31  │
│  Errors: 0     │
│                │
├────────────────╯

### 7.2 测试健康检查端点

docker compose exec openclaw-gateway curl -s http://127.0.0.1:18799/health | jq '.'

**预期输出：**

{
  "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 测试搜索功能

docker compose exec openclaw-gateway curl -s "http://127.0.0.1:18799/search?q=AI&limit=3" | jq '.'

**预期输出：**

{
  "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”

**原因：** 插件清单文件缺失或路径错误

**解决方案：**

# 1. 检查插件清单是否存在
ls -la /[openclaw-path]/extensions/mcp-newsnow/openclaw.plugin.json

# 2. 验证清单内容
cat /[openclaw-path]/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”

**原因：** 浏览器可执行文件路径未配置

**解决方案：**

# 1. 查找 Chrome 实际路径
docker compose exec openclaw-gateway find /home/node/.cache/ms-playwright -name "chrome"

# 2. 更新配置文件
cat /[config-path]/openclaw.json | jq '.browser.executablePath = "/home/node/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome"' > /tmp/config.json && mv /tmp/config.json /[config-path]/openclaw.json

# 3. 重启容器
docker compose restart openclaw-gateway

### 问题 3：浏览器启动失败，报错 “Missing X server or $DISPLAY”

**原因：** 容器环境缺少 GUI 支持

**解决方案：**

# 添加无头模式和禁用沙箱配置
cat /[config-path]/openclaw.json | jq '.browser.noSandbox = true | .browser.headless = true' > /tmp/config.json && mv /tmp/config.json /[config-path]/openclaw.json

# 重启容器
docker compose restart openclaw-gateway

### 问题 4：插件重复加载警告

**原因：** 插件同时存在于镜像和用户目录

**解决方案：**

# 删除用户目录中的重复插件
rm -rf /[config-path]/extensions/mcp-newsnow

# 重启容器
docker compose restart openclaw-gateway

### 问题 5：Playwright 浏览器未安装

**原因：** 镜像构建时未添加 `OPENCLAW_INSTALL_BROWSER=1` 参数

**解决方案：**

# 重新构建镜像
docker build --build-arg OPENCLAW_INSTALL_BROWSER=1 -t openclaw:local .

# 重启容器
docker compose down && docker compose up -d

—

## 配置文件完整示例

### docker-compose.yml

services:
  openclaw-gateway:
    image: openclaw:local
    container_name: [container-name]
    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（浏览器部分）

{
  "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（插件部分）

{
  "plugins": {
    "enabled": true,
    "entries": {
      "feishu": { "enabled": true },
      "acpx": { "enabled": true },
      "mcp-newsnow": { "enabled": true }
    }
  }
}

—

## 常用命令速查

### 容器管理

# 启动容器
docker compose up -d

# 停止容器
docker compose down

# 重启容器
docker compose restart openclaw-gateway

# 查看日志
docker compose logs -f openclaw-gateway

# 查看容器状态
docker compose ps

### 浏览器操作

# 查看状态
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

### 插件管理

# 检查插件状态
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..enabled: true`

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+

Previous Article
Next Article

发表回复

Your email address will not be published. Required fields are marked *.

*
*

george 的头像

关于本站

这里是一个我们展示和记录生活的地方

联系我们

  • 地址
    中国，北京，一个小河边

空闲时间
星期一—五：19:00–21:00
星期六—日：9:00–21:00

京公网安备11010802046182号
京ICP备2025139524号