Openskill Claw Image

Languages: English | 中文

Evolution note: Openskill Claw Image is the successor to the original ClawManager OpenClaw Image. It inherits the same foundation while providing a more powerful and feature-rich Agent image, and remains fully compatible with ClawManager.

This guide helps you build an OpenClaw base image for the ClawManager control plane, with automated config injection (API Key, Base URL, etc.) and persistent directory layout for multi-tenant scenarios.

The image now also includes an OpenClaw Agent service inside the container. It auto-registers to ClawManager, sends heartbeats, polls commands, manages the OpenClaw process, and exposes a local Gin-based health endpoint.

This project provides two Dockerfiles for different scenarios:

Dockerfile	Base image	Best for	Typical resources
Dockerfile.ubuntu-xfce	lscr.io/linuxserver/webtop:ubuntu-xfce	Desktop skill agent: provides a full browser-accessible desktop (noVCE). Ideal for skills that require GUI interaction.	Larger image; always pass --shm-size="1gb" at runtime.
Dockerfile.alpine-openbox	lscr.io/linuxserver/webtop:alpine-openbox	Server-side skill agent: lightweight Alpine + Openbox stack. Significantly smaller image and faster startup. Best when no complex desktop interaction is needed.	Lower footprint; still recommend sufficient shared memory.

Choose the Dockerfile that matches your use case for a one-shot build. If you need to install components manually inside the WebTop desktop and then docker commit, see Advanced: manual flow below.

Project overview

In ClawManager batch scenarios, per-container manual setup does not scale. This project addresses:

• Pre-installed runtime: Node.js and the latest OpenClaw CLI, ready to use.
• Config sync: custom-cont-init.d so new containers can restore templates from /defaults on start.
• Dynamic injection: Environment variables update openclaw.json without editing files in the desktop session.

---

Quick start (recommended)

The image is based on lscr.io/linuxserver/webtop:ubuntu-xfce. The Dockerfile installs Node.js and global OpenClaw, seeds /defaults/.openclaw, and installs scripts/99-openclaw-sync under /custom-cont-init.d/ (runs on each container start, not during docker build). Runtime config lives under /config/.openclaw, not ~/.openclaw. Look for [OpenClaw] lines in the container logs after startup.

Build

Bash

# Desktop skill agent (default)
docker build -f Dockerfile.ubuntu-xfce -t openclaw:local .

# Server-side skill agent (lightweight)
docker build -f Dockerfile.alpine-openbox -t openclaw:local .

Run

Set shared memory: always pass --shm-size="1gb" (at least 1GB) when running WebTop, or the browser/desktop stack may crash or behave oddly.

Bash

docker run -d \
  --name=webtop-openclaw \
  --shm-size="1gb" \
  --restart unless-stopped \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e CLAWMANAGER_LLM_BASE_URL=https://your-gateway/v1 \
  -e CLAWMANAGER_LLM_API_KEY=your-sk-key \
  -e CLAWMANAGER_LLM_MODEL=gpt-4o \
  -p 3000:3000 \
  -p 3001:3001 \
  openclaw:local

Adjust ports and placeholders as needed.

---

Environment variables

Set these in ClawManager or docker run to inject into openclaw.json:

Variable	Config path	Purpose
CLAWMANAGER_LLM_BASE_URL	models.providers.auto.baseUrl	Gateway or upstream base URL
CLAWMANAGER_LLM_API_KEY	apiKey	Model API key
CLAWMANAGER_LLM_MODEL	primary / agents.defaults.models	Model id replacement;auto/ handling matches the sed logic in 99-openclaw-sync
CLAWMANAGER_OPENCLAW_CHANNELS_JSON	channels (merge)	JSON object with one or more channel keys (feishu, slack, …); shallow-merge into channels; invalid JSON aborts startup
CLAWMANAGER_CHANNEL_FEISHU_ENABLED	channels.feishu.enabled	true / false to enable Feishu channel
CLAWMANAGER_CHANNEL_FEISHU_APP_ID	channels.feishu.appId	Feishu self-built app ID (cli_xxx)
CLAWMANAGER_CHANNEL_FEISHU_APP_SECRET	channels.feishu.appSecret	Feishu self-built app secret
CLAWMANAGER_CHANNEL_WECOM_ENABLED	channels.wecom.enabled	true / false to enable WeCom channel
CLAWMANAGER_CHANNEL_WECOM_BOT_ID	channels.wecom.botId	WeCom bot ID
CLAWMANAGER_CHANNEL_WECOM_SECRET	channels.wecom.secret	WeCom bot secret
CLAWMANAGER_CHANNEL_DINGTALK_ENABLED	channels.dingtalk-connector.enabled	true / false to enable DingTalk channel
CLAWMANAGER_CHANNEL_DINGTALK_CLIENT_ID / CLAWMANAGER_CHANNEL_DINGTALK_APP_KEY	channels.dingtalk-connector.clientId	DingTalk AppKey (Client ID)
CLAWMANAGER_CHANNEL_DINGTALK_CLIENT_SECRET / CLAWMANAGER_CHANNEL_DINGTALK_APP_SECRET	channels.dingtalk-connector.clientSecret	DingTalk AppSecret (Client Secret)
CLAWMANAGER_GATEWAY_BIND	gateway.bind	Bind address for openclaw gateway. Set to 0.0.0.0 to allow access from host via -p 18789:18789. Default is loopback.
OPENCLAW_AGENT_INSTANCE_ID	agent bootstrap	Required. Unique instance id used during /api/v1/agent/register
OPENCLAW_AGENT_BOOTSTRAP_TOKEN	agent bootstrap	Required. Bootstrap token for agent registration
OPENCLAW_AGENT_CONTROL_PLANE_BASE_URL	agent bootstrap	Required. ClawManager base URL
OPENCLAW_AGENT_INITIAL_CONFIG_REVISION_ID	agent bootstrap	Optional initial revision id
OPENCLAW_AGENT_OPENCLAW_COMMAND	process management	Optional. Defaults to openclaw gateway

The agent default config is stored at /etc/openclaw-agent/config.yaml, seeded from /defaults/openclaw-agent/config.yaml, and the local health/debug server listens on :18080 by default.

---

GitHub Actions and GHCR (optional)

The workflow .github/workflows/docker-ghcr.yml builds Dockerfile.ubuntu-xfce on push to the default branch (main / master) or on v* tags, and pushes to GitHub Container Registry so you do not need a local docker build for releases.

Short checklist

1. Push the repo to GitHub and confirm Build and push to GHCR succeeds under Actions.
2. Find the package under Packages; the image is usually ghcr.io/<user>/<repo>.
3. For private packages, run docker login ghcr.io first; set the package to Public if you want anonymous docker pull.

Bash

docker pull ghcr.io/<github_user>/<repo>:latest

docker run -d \
  --name=webtop-openclaw \
  --shm-size="1gb" \
  --restart unless-stopped \
  -e PUID=1000 -e PGID=1000 -e TZ=Asia/Shanghai \
  -e CLAWMANAGER_LLM_BASE_URL=https://your-gateway/v1 \
  -e CLAWMANAGER_LLM_API_KEY=your-sk-key \
  -e CLAWMANAGER_LLM_MODEL=gpt-4o \
  -e CLAWMANAGER_OPENCLAW_CHANNELS_JSON='{"feishu":{"enabled":true,"accounts":{"main":{"appId":"cli_xxx","appSecret":"your-secret"}}}}' \
  -p 3000:3000 -p 3001:3001 \
  ghcr.io/<github_user>/<repo>:latest

Pushing tags like v1.0.0 also publishes semver tags per the workflow metadata rules.

---

Advanced: manual flow (docker commit)

Use this when you must install extra tooling inside WebTop before saving an image. It is an alternative to Dockerfile.ubuntu-xfce / Dockerfile.alpine-openbox.

Install software

Open https://<IP>:3001, then in a terminal:

Bash

curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs

npm config set registry https://registry.npmmirror.com
sudo npm install -g openclaw@latest

Init script and cleanup

1. Seed defaults: cp -rp /config/.openclaw /defaults/.
2. Install hook: place an executable 99-openclaw-sync under /custom-cont-init.d/ (you can start from scripts/99-openclaw-sync in this repo) to copy from /defaults to /config and apply env-based edits.
3. Clean before image save: rm -rf /config/.openclaw. If this step is skipped, new containers may not run first-boot init as expected.

Save image

Bash

docker commit webtop-running openclaw:v1.0

---

Notes

• Line endings: 99-openclaw-sync must use LF. On Windows, convert line endings or rely on the sed step in Dockerfile.ubuntu-xfce / Dockerfile.alpine-openbox to strip \r. Rebuild the image after editing the script.
• Permissions: the script runs chown -R abc:abc so the default user can read/write persisted config.
• Docker Compose: point image at your built tag, or use build with dockerfile: Dockerfile.ubuntu-xfce or dockerfile: Dockerfile.alpine-openbox. Do not rely on the stock webtop image alone; it will not include this repo’s templates and init script.
• Standalone WebTop: if you do not use ClawManager batch features, you can skip the ClawManager-specific steps in the advanced flow.

---

Links

• ClawManager - The friendliest way to manage Al agents