OpenClaw + KasmVNC:一个能＂看见＂ AI Agent 操作浏览器的容器方案

用 AI Agent 自动操作浏览器，你怎么调试？

官方方案的问题：

• • 容器内无法重启网关：openclaw gateway restart 执行不了
• • 只能看命令行输出：Agent 在浏览器里干什么，你看不到
• • 配置变更要重建镜像：改个配置就得重新打包部署

有没有想过，一个容器方案能：支持完整生命周期管理、提供可视化桌面、实时观察 Agent 操作？

今天分享一个开源项目——openclaw-kasmvnc，它解决了这些问题。

它是什么？

openclaw-kasmvnc 是一个 一键部署 OpenClaw + KasmVNC 的容器化解决方案。

核心定位：

• • 容器内完整生命周期管理：install/upgrade/restart/uninstall 全支持
• • 可视化桌面环境：浏览器直连 XFCE 桌面，实时观察 Agent 操作
• • 中文环境预配置：时区、语言、输入法开箱即用

项目基本信息：

这个项目有意思的点：解决了官方 OpenClaw Docker 方案的核心痛点——看不见 Agent 在干什么。

为什么需要这个方案？

OpenClaw 是什么？一个 AI Agent 工具，能自动操作浏览器完成任务。

部署 OpenClaw 有两个主流方案：

方案一：官方 Docker 镜像

问题：

方案二：云厂商一键部署

问题：

openclaw-kasmvnc 的做法

解决两个核心问题：

问题一：容器内生命周期管理 → systemctl shim（模拟 systemd）问题二：可视化桌面 → KasmVNC（浏览器直连桌面）

结果：

• • 容器内能执行 restart/upgrade：通过 shim 脚本实现
• • 能看到 Agent 操作浏览器：VNC 桌面直连，实时观察
• • 完整开发环境：VS Code、Chromium、Git、Node.js 全预装

核心功能详解

1. 容器内完整生命周期管理

这是项目的核心技术创新——systemctl shim。

问题背景：

官方 OpenClaw 容器 → 无 systemd → systemctl 命令失败 → 无法管理服务

openclaw-kasmvnc 的做法：

# systemctl shim 脚本systemctl restart openclaw-gateway# → shim 捕获命令 → 查找网关 PID → 发送信号 → 重启进程

shim 脚本核心逻辑：

# 查找网关进程 PIDfind_gateway_pid() {    pgrep -f "openclaw gateway"}# 重启网关restart_gateway() {    pid=$(find_gateway_pid)    kill -TERM $pid      # 发送终止信号    wait_gateway_stop    # 等待进程退出    start_gateway        # 启动新进程    wait_gateway_ready   # 等待就绪}

支持的生命周期命令：

这些命令都能在容器内执行，不需要重建镜像。

2. 可视化桌面环境

这是项目的差异化功能——KasmVNC 桌面。

传统方案：

Agent 操作浏览器 → 你只能看命令行日志 → 不知道具体发生了什么

openclaw-kasmvnc 的做法：

Agent 操作浏览器 → VNC 桌面实时显示 → 你能看到每一步操作

技术实现：

• • KasmVNC：高性能 VNC 服务器，支持浏览器直连
• • XFCE4 桌面：完整 Linux 桌面环境
• • Chromium 浏览器：Agent 操作的目标浏览器

访问方式：

浏览器打开 https://127.0.0.1:8443 → 输入密码 → 看到完整桌面Agent 启动后 → 桌面上的 Chromium 自动打开 → 实时观察操作

这对调试非常有帮助——Agent 卡住了，你能看到它在哪个页面、做了什么操作。

3. 网关无损重启

这是项目的技术亮点——Gateway 重启不中断 VNC 会话。

问题：

重启 Gateway → 容器内进程全部重启 → VNC 桌面断开 → 需要重新连接

openclaw-kasmvnc 的做法：

重启 Gateway → 只重启网关进程 → VNC 桌面保持连接 → 不中断会话

原理：

• • Gateway 是独立进程，和 VNC 服务分离
• • shim 脚本只管理 Gateway 进程，不影响 VNC
• • X11 显示服务器持续运行，桌面会话保持

好处：你不用在调试过程中反复重连桌面。

4. 中文环境预配置

这是项目的贴心设计——开箱即用的中文环境。

预配置内容：

你在桌面上能直接输入中文，不需要额外配置。

5. Docker-in-Docker（可选）

这是项目的高级功能——容器内内置 dockerd。

为什么需要？

• • Agent 需要调用 Docker 命令
• • 容器内执行 docker run 需要有 dockerd

实现：

# docker-compose.ymlservices:  openclaw-kasmvnc:    privileged: true    volumes:      - /var/run/docker.sock:/var/run/docker.sock

或者用内置 DinD 模式：

# 镜像标签ddong8/openclaw-kasmvnc:latest          # 有 DinDddong8/openclaw-kasmvnc:latest-no-dind  # 无 DinD（更安全）

6. GPU 自动检测

如果你的机器有 NVIDIA GPU，容器会自动识别：

# 启动时自动检测docker run --gpus all ...

Agent 可以利用 GPU 加速某些操作（比如图像处理）。

7. 预装开发工具

桌面环境预装了完整开发工具：

基本上一个完整开发环境，不需要额外安装。

8. 4 种镜像变体

项目提供 4 种镜像，适应不同需求：

国内用户推荐 latest，国外用户推荐 latest-intl。

技术架构

如果你关心技术细节，openclaw-kasmvnc 的架构设计值得看。

技术栈总览

项目目录结构

<安装目录>/├── .env                    # 环境变量配置├── .openclaw/              # OpenClaw 持久化配置和工作区├── docker-compose.yml      # Compose 服务定义├── Dockerfile.kasmvnc      # 镜像构建指令└── scripts/docker/    ├── kasmvnc-startup.sh  # 容器入口脚本    └── systemctl-shim.sh   # systemctl 模拟脚本

容器入口脚本

kasmvnc-startup.sh 是容器启动的核心：

# 启动流程示意1. 清理 X11 残留锁文件2. 启动 KasmVNC 服务3. 启动 XFCE 桌面4. 启动 Fcitx5 输入法5. 启动 OpenClaw Gateway6. 等待网关就绪

为什么要清理 X11 残留？

容器重启 → X11 锁文件残留 → 新会话启动失败 → 黑屏清理锁文件 → 正常启动 → 不会黑屏

systemctl shim 详细原理

核心函数：

# 查找网关进程 PIDfind_gateway_pid() {    pgrep -f "openclaw gateway" || echo ""}# 解析版本号resolve_openclaw_version() {    node -e "console.log(require('openclaw/package.json').version)"}# 等待网关就绪wait_gateway_ready() {    for i in {1..30}; do        if curl -s http://localhost:18789/health > /dev/null; then            return 0        fi        sleep 1    done    return 1}

这些函数实现了 systemd 的核心功能，但不需要 systemd 进程。

剪贴板安全优化

KasmVNC 的剪贴板有安全隐患：

默认 MIME 类型 → 可能误杀 VNC 进程 → 桌面崩溃移除 MIME 类型 → 只传输纯文本 → 安全稳定

项目移除了默认 MIME 类型，防止剪贴板操作导致桌面崩溃。

seccomp 兼容处理

旧版 Docker 有个问题：

close_range 系统调用 → seccomp 阻止 → 容器启动失败添加 seccomp 配置 → 允许调用 → 正常启动

项目在启动脚本中添加了兼容处理，适配旧版 Docker。

如何部署？

方式一：一键脚本（推荐）

Windows：

irm https://raw.githubusercontent.com/ddong8/openclaw-kasmvnc/main/openclaw-kasmvnc-zh.ps1 | iex

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/ddong8/openclaw-kasmvnc/main/openclaw-kasmvnc-zh.sh | bash -s -- install

脚本会自动：

• • 下载镜像
• • 创建配置文件
• • 启动服务

方式二：Docker 命令

docker run -d \  --name openclaw-kasmvnc \  --privileged \  --shm-size=2g \  -p 18789:18789 \  -p 8443:8444 \  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \  -e OPENCLAW_KASMVNC_PASSWORD=your-password-here \  -v ~/openclaw-data:/home/node \  ddong8/openclaw-kasmvnc:latest

参数说明：

方式三：Docker Compose

services:  openclaw-kasmvnc:    image: ddong8/openclaw-kasmvnc:latest    privileged: true    shm_size: 2g    ports:      - "18789:18789"      - "8443:8444"    environment:      - OPENCLAW_GATEWAY_TOKEN=your-token      - OPENCLAW_KASMVNC_PASSWORD=your-password    volumes:      - ~/openclaw-data:/home/node

docker compose up -d

访问服务

常用命令

# macOS/Linux./openclaw-kasmvnc-zh.sh install     # 安装./openclaw-kasmvnc-zh.sh uninstall   # 卸载./openclaw-kasmvnc-zh.sh restart     # 重启./openclaw-kasmvnc-zh.sh upgrade     # 升级./openclaw-kasmvnc-zh.sh status      # 状态./openclaw-kasmvnc-zh.sh logs --tail 200  # 日志# Windowspowershell -ExecutionPolicy Bypass -File .\openclaw-kasmvnc-zh.ps1 -Command install

环境变量配置

可选参数

与其他方案对比

核心差异：openclaw-kasmvnc 是唯一支持可视化桌面 + 完整生命周期管理的方案。

适用场景

我觉得 openclaw-kasmvnc 适合这些场景：

不适合的场景：如果你只是简单用 OpenClaw，不需要调试 Agent 操作过程，官方 Docker 镜像就够用。但如果你想深入了解 Agent 在浏览器里做了什么，openclaw-kasmvnc 很有价值。

我的看法

我觉得 openclaw-kasmvnc 有几个亮点：

1. 1. systemctl shim 是真正的技术创新：在无 systemd 的容器中实现完整服务管理，这个设计很巧妙。解决了官方方案的核心痛点。
2. 2. 可视化桌面是差异化功能：能看到 Agent 操作浏览器的过程，这对调试非常有帮助。传统方案只能看日志，不知道具体发生了什么。
3. 3. 网关无损重启设计合理：Gateway 重启不中断 VNC 会话，调试过程中不用反复重连。
4. 4. 中文环境预配置贴心：输入法、字体、镜像都预配置好了，开箱即用。国内用户不需要额外折腾。
5. 5. 预装完整开发工具：VS Code、Git、Node.js、Docker CE……一个容器搞定开发环境。
6. 6. 镜像变体灵活：国内版/国际版、有 DinD/无 DinD，适应不同需求。

但也有一些考虑：

• • privileged 权限较高：DinD 需要完全权限，安全场景可能不适用
• • 镜像体积较大：预装了完整桌面和开发工具，体积比精简镜像大
• • 依赖 KasmVNC 服务：VNC 服务稳定性影响整体体验

总的来说，如果你用 OpenClaw Agent，需要调试 Agent 操作浏览器的过程，openclaw-kasmvnc 是目前最好的方案。可视化桌面让你”看见” Agent 在干什么，这是传统方案做不到的。

总结

openclaw-kasmvnc 的核心价值：一键部署 OpenClaw + KasmVNC，容器内完整生命周期管理，可视化桌面实时观察 Agent 操作。

技术创新：systemctl shim（无 systemd 实现服务管理），网关无损重启，X11 状态自动清理，剪贴板安全优化。

差异化：唯一支持可视化桌面 + 完整生命周期管理的方案，能看到 Agent 操作浏览器的每一步。

预配置：中文环境（输入法、字体、镜像）、开发工具（VS Code、Git、Node.js）、GPU 自动检测。

项目地址：https://github.com/ddong8/openclaw-kasmvnc

一句话总结：用 OpenClaw Agent 又想看见它在浏览器里干什么？试试 openclaw-kasmvnc，浏览器直连桌面，实时观察。