{"id":48085732,"url":"https://github.com/ddong8/openclaw-kasmvnc","last_synced_at":"2026-04-04T15:16:52.404Z","repository":{"id":338285778,"uuid":"1157358804","full_name":"ddong8/openclaw-kasmvnc","owner":"ddong8","description":"One-click deployment for OpenClaw + KasmVNC. Browser-based remote desktop with full container lifecycle management.","archived":false,"fork":false,"pushed_at":"2026-03-25T06:04:21.000Z","size":2130,"stargazers_count":35,"open_issues_count":0,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T15:47:49.333Z","etag":null,"topics":["agent","ai","ai-agent","cloud","container","desktop","docker","docker-in-docker","gpu","kasmvnc","linux","openclaw","remote-desktop","vnc","wechat","xfce"],"latest_commit_sha":null,"homepage":"https://claw.ihasy.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddong8.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T18:18:34.000Z","updated_at":"2026-03-25T06:04:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ddong8/openclaw-kasmvnc","commit_stats":null,"previous_names":["ddong8/openclaw_kasmvnc","ddong8/openclaw-kasmvnc"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ddong8/openclaw-kasmvnc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fopenclaw-kasmvnc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fopenclaw-kasmvnc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fopenclaw-kasmvnc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fopenclaw-kasmvnc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddong8","download_url":"https://codeload.github.com/ddong8/openclaw-kasmvnc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fopenclaw-kasmvnc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-agent","cloud","container","desktop","docker","docker-in-docker","gpu","kasmvnc","linux","openclaw","remote-desktop","vnc","wechat","xfce"],"created_at":"2026-04-04T15:16:51.815Z","updated_at":"2026-04-04T15:16:52.398Z","avatar_url":"https://github.com/ddong8.png","language":"Shell","funding_links":[],"categories":["云部署方案"],"sub_categories":["上下文管理"],"readme":"# openclaw-kasmvnc\n\n🌐 English version: [README.md](README.md)\n\n一键部署 OpenClaw + KasmVNC（支持 Windows / macOS / Linux）。\n\n![OpenClaw 桌面环境](docs/screenshot-desktop.jpg)\n\n## 核心优势\n\n### 🔧 容器内完整生命周期管理\n\n**解决官方 Docker 方案的核心痛点：**\n\n官方 OpenClaw Docker 部署方案中，Gateway 运行在宿主机上，容器内无 systemd，导致：\n- ❌ 无法在容器内执行 `openclaw gateway restart`\n- ❌ 无法在容器内执行 `npm install -g openclaw@latest` 热更新\n- ❌ 配置变更后需要手动重启容器\n\n**本项目通过 systemctl shim 完美解决：**\n- ✅ 容器内支持 `openclaw gateway restart` 重启网关\n- ✅ 容器内支持 `upgrade` 命令热更新 OpenClaw（无需重建镜像）\n- ✅ 完整的 `install / upgrade / restart / uninstall` 生命周期管理\n\n### 👁️ 可视化桌面环境\n\n**解决云厂商一键部署方案的可见性问题：**\n\n各大云厂商提供的 OpenClaw 一键部署方案通常只有命令行界面，无法：\n- ❌ 实时查看 OpenClaw 操作浏览器的过程\n- ❌ 观察 Agent 执行任务的可视化反馈\n- ❌ 调试桌面应用相关问题\n\n**本项目提供完整桌面环境：**\n- ✅ 浏览器直连 XFCE 桌面（KasmVNC）\n- ✅ 实时观察 OpenClaw 操作 Chromium 浏览器\n- ✅ 支持中文输入法（Fcitx5 + Rime Ice 雾凇拼音）\n- ✅ 完整的 Linux 桌面体验\n\n## 快速上手\n\n### 方式一：Docker 镜像（推荐）\n\n```bash\ndocker run -d \\\n  --name openclaw-kasmvnc \\\n  --privileged \\\n  --shm-size=2g \\\n  -p 18789:18789 \\\n  -p 8443:8444 \\\n  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \\\n  -e OPENCLAW_KASMVNC_PASSWORD=your-password-here \\\n  -v ~/openclaw-data:/home/node \\\n  ddong8/openclaw-kasmvnc:latest\n```\n\n**数据持久化：** 挂载 `~/openclaw-data:/home/node` 可持久化所有用户数据，包括 OpenClaw 配置、VS Code 设置、Git 凭证和桌面文件。\n\n\u003e 📖 详细文档：[DOCKER.md](DOCKER.md)\n\n### 方式二：一键脚本\n\nWindows:\n```powershell\nirm https://raw.githubusercontent.com/ddong8/openclaw-kasmvnc/main/openclaw-kasmvnc-zh.ps1 | iex\n```\n\nmacOS / Linux:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ddong8/openclaw-kasmvnc/main/openclaw-kasmvnc-zh.sh | bash -s -- install\n```\n\n### 访问服务\n\n| 服务 | 地址 | 凭证 |\n|------|------|------|\n| WebChat | `http://127.0.0.1:18789/chat?session=main` | `OPENCLAW_GATEWAY_TOKEN` |\n| KasmVNC 桌面 | `https://127.0.0.1:8443` | 用户名 `node`，密码 `OPENCLAW_KASMVNC_PASSWORD` |\n\n\u003e 首次安装会自动生成并输出 Token 和密码，请妥善保存。\n\n## 其他特性\n\n- **环境隔离** — OpenClaw、桌面环境、依赖都在容器内，不污染主机系统\n- **一键部署** — 通过脚本和 Compose 一键安装/升级/重启，换机器也可快速复现\n- **跨平台一致** — Windows、macOS、Linux 使用同一套容器行为，排障路径统一\n- **Docker-in-Docker** — 容器内内置 dockerd，OpenClaw 可直接创建和管理子容器\n- **GPU 自动检测** — 安装时自动识别宿主机 NVIDIA GPU，有则启用 `nvidia` runtime\n- **大规模部署** — 标准化容器方案使大规模部署龙虾成为可能\n\n## 前置条件\n\n- Docker（含 Docker Compose v2）\n- Windows: PowerShell 5+ / 7+\n- macOS/Linux: Bash\n\n## 常用命令\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows (PowerShell)\u003c/b\u003e\u003c/summary\u003e\n\n```powershell\n# 安装\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command install\n\n# 卸载（仅停服务）\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command uninstall\n\n# 卸载并删除安装目录\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command uninstall -Purge\n\n# 重启\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command restart\n\n# 升级\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command upgrade\n\n# 状态 / 日志\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command status\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command logs -Tail 200\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS / Linux (Bash)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nchmod +x ./openclaw-kasmvnc-zh.sh\n\n./openclaw-kasmvnc-zh.sh install              # 安装\n./openclaw-kasmvnc-zh.sh uninstall            # 卸载（仅停服务）\n./openclaw-kasmvnc-zh.sh uninstall --purge    # 卸载并删除安装目录\n./openclaw-kasmvnc-zh.sh restart              # 重启\n./openclaw-kasmvnc-zh.sh upgrade              # 升级\n./openclaw-kasmvnc-zh.sh status               # 状态\n./openclaw-kasmvnc-zh.sh logs --tail 200      # 日志\n```\n\n\u003c/details\u003e\n\n## 可选参数\n\n| 参数 | Windows (PS1) | macOS/Linux (sh) | 默认值 |\n|------|---------------|-------------------|--------|\n| 安装目录 | `-InstallDir` | `--install-dir` | `$HOME/openclaw-kasmvnc` |\n| 网关端口 | `-GatewayPort` | `--gateway-port` | `18789` |\n| VNC HTTPS 端口 | `-HttpsPort` | `--https-port` | `8443` |\n| 网关 Token | `-GatewayToken` | `--gateway-token` | 自动生成 |\n| VNC 密码 | `-KasmPassword` | `--kasm-password` | 自动生成 |\n| 系统代理 | `-Proxy` | `--proxy` | 无 |\n| 禁用 Docker-in-Docker | `-NoDinD` | `--no-dind` | 否 |\n| 日志行数 | `-Tail` | `--tail` | `200` |\n| 禁用构建缓存 | `-NoCache` | `--no-cache` | 否 |\n| 清除安装目录 | `-Purge` | `--purge` | 否 |\n\n\u003e 脚本默认通过 npm 获取 `latest` 版本的 OpenClaw。升级时直接运行 `upgrade` 即可。\n\n\u003cdetails\u003e\n\u003csummary\u003e自定义安装示例\u003c/summary\u003e\n\n```powershell\n# Windows\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 `\n  -Command install `\n  -InstallDir \"D:\\openclaw-deploy\" `\n  -GatewayPort \"18789\" `\n  -HttpsPort \"8443\"\n```\n\n```bash\n# macOS/Linux\n./openclaw-kasmvnc-zh.sh install \\\n  --install-dir \"$HOME/openclaw-deploy\" \\\n  --gateway-port 18789 \\\n  --https-port 8443\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e使用系统代理\u003c/summary\u003e\n\n安装时指定 `--proxy`，容器内所有 HTTP/HTTPS 请求都会走代理：\n\n```bash\n# Linux/macOS\n./openclaw-kasmvnc-zh.sh install --proxy http://192.168.1.131:10808\n\n# Windows\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command install -Proxy \"http://192.168.1.131:10808\"\n```\n\n安装后也可编辑 `.env` 开关代理，修改后执行 `restart` 生效：\n```env\nOPENCLAW_HTTP_PROXY=http://192.168.1.131:10808\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e禁用 Docker-in-Docker（更安全）\u003c/summary\u003e\n\n默认情况下，容器会安装 Docker CE 并以 privileged 模式运行，以支持 Docker-in-Docker。如果你不需要 OpenClaw 管理子容器，可以禁用 DinD 以提高安全性：\n\n```bash\n# Linux/macOS\n./openclaw-kasmvnc-zh.sh install --no-dind\n\n# Windows\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command install -NoDinD\n```\n\n启用 `--no-dind` 后：\n- 容器内不会安装 Docker CE\n- 容器不需要 `privileged: true` 权限（更安全）\n- OpenClaw 无法创建或管理子容器\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e选择 KasmVNC 版本\u003c/summary\u003e\n\n默认使用 KasmVNC **1.3.0**，可通过环境变量切换：\n\n```bash\n# Linux/macOS\nOPENCLAW_KASMVNC_VERSION=1.4.0 ./openclaw-kasmvnc-zh.sh install\n\n# Windows\n$env:OPENCLAW_KASMVNC_VERSION=\"1.4.0\"\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command install\n```\n\n\u003c/details\u003e\n\n## 项目结构\n\n- `openclaw-kasmvnc-zh.sh` — macOS/Linux 管理脚本（中文版，含国内镜像加速）\n- `openclaw-kasmvnc-zh.ps1` — Windows 管理脚本（中文版，含国内镜像加速）\n- `openclaw-kasmvnc.sh` — macOS/Linux 管理脚本（国际版）\n- `openclaw-kasmvnc.ps1` — Windows 管理脚本（国际版）\n\n脚本运行后在安装目录下生成：\n```\n\u003c安装目录\u003e/\n├── .env                              # 环境变量配置（token、密码、端口等）\n├── .openclaw/                        # OpenClaw 持久化配置和工作区（挂载到容器内）\n├── docker-compose.yml                # Compose 服务定义\n├── Dockerfile.kasmvnc                # 镜像构建指令（node:22 + KasmVNC + XFCE + Fcitx5）\n└── scripts/docker/\n    ├── kasmvnc-startup.sh            # 容器入口脚本（启动 VNC → 桌面 → 输入法 → 网关）\n    └── systemctl-shim.sh             # systemctl 模拟（将 systemd 调用转为进程信号）\n```\n\n## 内置优化\n\n- **中文环境预配置** — `TZ=Asia/Shanghai`、`LANG=zh_CN.UTF-8`，预装中文字体（Noto CJK）和 Fcitx5 + Rime（雾凇拼音）输入法，本地输入法默认启用\n- **网关无损重启** — gateway 重启期间 VNC 桌面会话保持连接不中断\n- **X11 状态清理** — 入口脚本自动清理残留的 X11 锁文件和 VNC 进程，避免容器重启后黑屏\n- **systemctl shim** — 容器内无 systemd，通过 shim 使 `openclaw gateway restart/stop/start` 等命令正常工作\n- **剪贴板安全** — 移除 KasmVNC 默认的 `chromium/x-web-custom-data` MIME 类型，`pkill -f chromium` 不会误杀 VNC\n\n\u003cdetails\u003e\n\u003csummary\u003e在容器内管理 Gateway\u003c/summary\u003e\n\n在 VNC 桌面的终端里，可以直接使用标准的 OpenClaw 命令：\n\n```bash\nopenclaw gateway restart          # 重启（加载最新代码）\nopenclaw gateway stop             # 停止\nopenclaw gateway status --probe   # 查看状态\n```\n\n\u003e 这些命令通过内置的 systemctl shim 实现，无需真正的 systemd。\n\n\u003c/details\u003e\n\n## 预装工具\n\n桌面环境预装了以下开发工具：\n\n- **Chromium** - 浏览器（桌面图标）\n- **Visual Studio Code** - 代码编辑器（桌面图标）\n- **vim** - 终端文本编辑器\n- **Git** - 版本控制工具\n- **Node.js 22** - JavaScript 运行时\n- **npm** - 包管理器\n- **Docker CE** - 容器引擎（仅 DinD 版本）\n\n桌面图标位于 `/home/node/Desktop`，双击即可启动应用。\n\n## 修改配置后如何生效\n\n常见配置位置：`\u003c安装目录\u003e/.env`、`\u003c安装目录\u003e/.openclaw/openclaw.json`\n\n1. 修改配置文件\n2. 执行 `restart`\n3. 用 `status` 和 `logs --tail 200` 验证\n\n\u003e 如果修改的是镜像配置（如 Dockerfile、系统依赖），需执行 `upgrade` 而非 `restart`。\n\n## 已知问题\n\n### 执行 `openclaw update` 时 VNC 短暂闪断\n\n`npm install` 解压依赖时 CPU/IO 占用极高，可能导致 KasmVNC WebSocket 心跳超时。这是资源抢占引起的假死，完成后自动恢复。建议在宿主机资源充裕时执行 `upgrade`。\n\n## 常见问题（FAQ）\n\n### 1. 构建失败或需要清除缓存\n\n如果安装过程中遇到构建错误，可以使用 `--no-cache` 参数禁用 Docker 构建缓存：\n\n```bash\n# macOS/Linux\n./openclaw-kasmvnc-zh.sh install --no-cache\n\n# Windows\npowershell -ExecutionPolicy Bypass -File .\\openclaw-kasmvnc-zh.ps1 -Command install -NoCache\n```\n\n### 2. 端口被占用\n\n安装时改端口：Windows `-GatewayPort 28789 -HttpsPort 9443`，macOS/Linux `--gateway-port 28789 --https-port 9443`，然后重新 `install`。\n\n### 3. KasmVNC 提示 HTTPS 证书不安全\n\n默认使用容器自签名证书，属于正常现象。在浏览器选择继续访问，或自行配置反向代理（Nginx/Caddy）。\n\n### 4. Fcitx5 默认未激活中文\n\n旧卷配置冲突导致。处理：\n1. 宿主机执行 `upgrade`\n2. VNC 终端执行 `rm -rf ~/.config/fcitx5 ~/.local/share/fcitx5/rime/default.custom.yaml ~/.config/autostart/fcitx5.desktop`\n3. 桌面菜单 → Log Out → 刷新页面重新进入\n\n### 5. 进入桌面后黑屏\n\n依次尝试：`restart` → `status` → `logs --tail 200` → `upgrade`。\n\n### 6. 容器反复重启\n\n常见原因：`.env` 缺参数、目录权限异常、端口冲突。重新 `install` 或更换端口。\n\n### 7. macOS 上 `chown: Operation not permitted`\n\nmacOS M 系列部分挂载路径会出现此提示，容器运行正常则可安全忽略。\n\n### 8. 为什么用 Chromium 而不是 Chrome？\n\n1. **多架构兼容** — Google 未提供 ARM64 Chrome，Chromium 是唯一同时适配 x86_64 和 arm64 的方案\n2. **版权合规** — Chrome 含闭源插件（DRM 等），不适合打包到公有镜像\n3. **依赖纯净** — `apt install` 的 Chromium 与系统库无缝兼容，无需第三方源\n\n### 9. 升级后中文输入法不是默认首选\n\n旧版配置持久化导致。VNC 终端执行后断开重连：\n```bash\nrm -rf ~/.config/fcitx5 ~/.local/share/fcitx5/rime/default.custom.yaml ~/.config/dconf\n```\n\n### 10. 日志太多\n\n用 `logs --tail 200` 看最近日志，`logs --tail 50` 快速定位报错。\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=ddong8/openclaw-kasmvnc\u0026type=Date)](https://star-history.com/#ddong8/openclaw-kasmvnc\u0026Date)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddong8%2Fopenclaw-kasmvnc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddong8%2Fopenclaw-kasmvnc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddong8%2Fopenclaw-kasmvnc/lists"}