Ubuntu 桌面系统 + OpenClaw

git clone https://cnb.cool/fuliai/openclaw_desktop_docker
cd openclaw_desktop_docker
docker compose up -d

启动后打开浏览器：

http://localhost:3000
或
https://<你的IP>:3001

• 启动前请先检查 .env 文件。
• 请在 .env 中查看并修改登录密码。
• 请docker compose 启动前更换密码。

• 容器内真正的持久化目录是 /config。
• OpenClaw 工作区真实目录是 /config/workspace。
• 容器内的 /workspace 是一个兼容用软链接，指向 /config/workspace。
• 因此你看到 /config/workspace 和 /workspace 同时存在是正常的，不是两份数据。
• 只有 /config 下的内容会在重启、更新镜像后继续保留。

• OpenClaw 默认工作区会指向 /workspace。
• 由于 /workspace 实际链接到 /config/workspace，所以工作结果仍然会持久化到 /config 中。
• 如果你想直接查看真实落盘位置，请看 /config/workspace。

• 当前仓库这份镜像源码默认会打包 openclaw@2026.5.12。
• 当前仓库默认会同时预装以下微信相关 npm 包：
  • @tencent-weixin/openclaw-weixin-cli@2.1.4
  • @tencent-weixin/openclaw-weixin@2.4.3
• 当前仓库默认还会预装 OpenClaw OS（工作区 UI）插件：
  • @openuidev/openclaw-os-plugin@0.1.4

• compose.yaml 默认拉取的是已发布镜像 docker.cnb.cool/fuliai/openclaw_desktop_docker/openclaw-desktop:latest。
• 因此如果你直接执行 docker compose up -d 使用预构建镜像，最终版本以你实际拉到的镜像内容为准。
• 如果你是按当前仓库源码自行构建镜像，则默认会使用上面这组版本。
• 如需确认当前容器内真实版本，请进入容器或 Webtop 终端执行：

openclaw --version

• 如需自定义 OpenClaw 或微信插件版本，可在构建镜像时覆盖 OPENCLAW_NPM_SPEC、WEIXIN_VERSION、WEIXIN_CLI_VERSION、OPENCLAW_OS_VERSION，但建议优先保持当前默认组合，避免插件兼容性问题。

当镜像有更新时，在项目目录执行：

docker compose pull
docker compose up -d

更新不影响原有的保存在 /config 目录下的文件。只有在这个目录内的内容才能持久化！

如要锁定到具体版本号，把 compose.yaml 里 image: ...:latest 改成例如 image: ...:2026.5.12，再 docker compose pull && docker compose up -d。

如需清理无用旧镜像，可执行：

docker image prune -f

• 镜像内已经预装 @tencent-weixin/openclaw-weixin-cli 和 @tencent-weixin/openclaw-weixin。
• 容器启动时会从镜像内本地路径 /usr/lib/node_modules/@tencent-weixin/openclaw-weixin 执行 openclaw plugins install -l，不是依赖远程再次拉取插件包。
• 启动脚本还会自动把 openclaw-weixin 写入 OpenClaw 的插件配置并启用，方便首次启动后直接扫码登录。
• Webtop 桌面会自动生成一个快捷方式：微信扫码登录。
• 双击这个图标后，会自动打开终端并执行扫码登录命令。
• 如果你更习惯命令行，也可以手动运行：

openclaw channels login --channel openclaw-weixin

• 扫码成功后，登录状态会保存在 /config/.openclaw 中。

如需确认当前容器里的 OpenClaw 版本和微信 channel 插件是否已经正常加载，请使用：

openclaw --version
openclaw plugins list

• 看到 openclaw-weixin 处于 loaded 即表示微信 channel 插件已经被 OpenClaw 成功加载。
• 如果你是旧 /config 数据升级上来的，建议再检查一下插件配置：

openclaw config get plugins.allow
openclaw config get plugins.entries.openclaw-weixin.enabled

• 如果没有看到 openclaw-weixin 为 loaded，可在容器内执行下面命令重新安装并重载：

openclaw plugins install -l /usr/lib/node_modules/@tencent-weixin/openclaw-weixin
openclaw config set plugins.allow '["openclaw-weixin"]'
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart
openclaw plugins list

• 上面使用的是本地路径安装方式，适合这个镜像里已经预装好的微信插件，不需要再猜测远程包名或额外手动下载。

• 镜像内已经预装 @openuidev/openclaw-os-plugin，由 OpenClaw gateway 直接挂载，无需额外的 Next.js 进程或端口。
• 容器启动时会从镜像内本地路径 /usr/lib/node_modules/@openuidev/openclaw-os-plugin 执行 openclaw plugins install -l，并把 openclaw-os-plugin 加进 plugins.allow 并设置 enabled: true。
• 启动完成后访问工作区 UI：

http://localhost:18789/plugins/openclawos          # 本机浏览器或 Webtop 内
http://<你的服务器IP>:18789/plugins/openclawos     # 远程访问，需先做下面"公网/远程访问与安全"一节

• 如需获取已预鉴权的 URL，可在容器内执行：

openclaw os url

• 如果你是旧 /config 数据升级上来的，或者插件没有按预期加载，可以在容器内执行：

openclaw plugins install -l /usr/lib/node_modules/@openuidev/openclaw-os-plugin
openclaw config set plugins.allow '["openclaw-weixin", "openclaw-os-plugin"]'
openclaw config set plugins.entries.openclaw-os-plugin.enabled true
openclaw gateway restart
openclaw plugins list

• 看到 openclaw-os-plugin 处于 loaded 即表示工作区 UI 已经被 OpenClaw 成功加载。

从这一版开始，镜像默认让 OpenClaw gateway 在容器内绑定 lan 模式（listen 0.0.0.0:18789），配合 compose.yaml 把 18789:18789 发布出来，所以容器一启动，gateway 在宿主机的所有网卡上都可达，包括公网 IP。http://<你的服务器IP>:18789/plugins/openclawos 这种远程访问因此可以直接打开。

之前版本默认绑 loopback，gateway 只听 127.0.0.1，端口 publish 出去也连不上——是这个老行为反了过来。

部署到公网服务器（或任何不完全可信的网络）前，务必先做下面两件事，否则等于裸奔：

1. 替换 OPENCLAW_GATEWAY_TOKEN——.env 里默认是占位串 change-this-to-a-long-random-string，gateway 不绑 loopback 时这个 token 就是唯一的访问凭证。生成强随机值：

   openssl rand -hex 32
   

   写回 .env 后必须 docker compose down && docker compose up -d，容器才会读到新 token。仅 restart 不会重读 env。

2. 替换 WEBTOP_PASSWORD——同一个 .env 里的 Webtop 登录密码，决定 3000/3001 桌面的访问权限，同样不能留默认值。

进一步收紧的建议：

• 公网部署最好不要把 18789 直接 publish 到 0.0.0.0。改用 nginx/Caddy 反代加 TLS + IP 白名单或 Basic Auth，对外只暴露 443。
• 局域网部署可接受默认 publish，但仍必须换 token。
• 完全不需要远程访问 gateway 的场景，把 compose.yaml 里 "18789:18789" 改成 "127.0.0.1:18789:18789"（或直接删掉），让 18789 只在宿主机本地可达。容器内访问、Webtop 内浏览器访问都不受影响。

• 如果 openclaw gateway status 里出现 unauthorized: gateway token mismatch，通常不是 gateway 没启动，而是 CLI 与 gateway 使用了不同 token。
• 当前镜像启动脚本会在容器启动时把 gateway.auth.token 和 gateway.remote.token 同步成同一个值。
• 如果你使用的是旧 /config 数据，或者手动改过配置，可以在容器内执行下面命令重新对齐：

echo "$OPENCLAW_GATEWAY_TOKEN"
openclaw config get gateway.auth.token
openclaw config get gateway.remote.token

NEW_TOKEN="${OPENCLAW_GATEWAY_TOKEN:-$(openssl rand -hex 24)}"
openclaw config set gateway.auth.token "$NEW_TOKEN"
openclaw config set gateway.remote.token "$NEW_TOKEN"
openclaw gateway restart
openclaw gateway status

• 如果你在 Compose 里传了 OPENCLAW_GATEWAY_TOKEN，它应与上面两个配置值保持一致。

• compose.yaml 里写了 security_opt: - no-new-privileges:false 之后，必须重建容器，这个改动才会真正作用到运行中的容器。
• 建议执行：

docker compose down
docker compose up -d

• 然后在宿主机检查运行态配置：

docker inspect openclaw-webtop --format '{{json .HostConfig.SecurityOpt}}'

• 看到 ["no-new-privileges:false"] 后，再进容器里测试：

sudo -i

本仓库父项目里有几个脚本辅助升级与发布（终端用户不需要关心）：

# 1. 看 npm 上有没有新版本可用（默认 dry-run）
bash openclaw-version-check.sh

# 2. 接受升级，写回父项目里的 Dockerfile 与 README 版本号
bash openclaw-version-check.sh --apply

# 3. 本地 build → 隔离容器验证 → 推 :latest 与 :<openclaw版本号> 双 tag
bash push-openclaw-desktop.sh

# 4. 同步本目录到 cnb.cool（已有脚本）
bash sync-desktop.sh sync

openclaw-version-check.sh 会按 @tencent-weixin/openclaw-weixin 在 npm 上发布的 compat-host-gte<min>-lt<max> dist-tag 自动挑兼容版本，避免盲目跟随 latest 造成插件与 host 不匹配。

push-openclaw-desktop.sh 默认从 registry 拉取 openclaw-base:latest 作为构建起点，所以日常的 OpenClaw 版本升级不需要重建 base 层。

镜像分两层：

• openclaw/openclaw-base/ —— 基础镜像：系统包、Node/Bun/Go/Rust、启动脚本、autostart 项、openclaw.json 模板等。改动很少。
• openclaw/openclaw-webtop/（本目录） —— 应用层：FROM openclaw-base + npm install -g openclaw + 微信插件。每次 OpenClaw 发版都改。

只有 base 层的内容（Dockerfile、openclaw-base/files/*）有改动时，才需要重建并推送 base：

bash push-openclaw-base.sh
bash push-openclaw-desktop.sh

如需在本地从头构建（不推送）：

bash push-openclaw-base.sh --no-push
bash push-openclaw-desktop.sh --base-image local/openclaw-base:latest --no-push --skip-verify

点击扫码加群