roqueribeiro1988/roqueos-openclaw repository overview
RoqueOS OpenClaw
🦞 AI Agent Container with Visual Desktop
OpenClaw-powered automation with Ubuntu + XFCE + VNC
🖥️ Supported Platforms
| Architecture | Devices |
|---|---|
| linux/amd64 | PCs, servers, cloud VMs |
| linux/arm64 | Raspberry Pi 4/5, Mac M1/M2/M3/M4, AWS Graviton |
Docker will automatically pull the correct image for your architecture.
🌟 What is RoqueOS OpenClaw?
RoqueOS OpenClaw is a specialized Docker container that provides an AI-powered automation environment for RoqueOS. It combines:
- OpenClaw - AI agent framework for visual automation
- Ubuntu 22.04 - Stable Linux base
- XFCE Desktop - Lightweight graphical environment
- VNC/noVNC - Remote desktop access via browser
- Chromium - Web browser with OpenClaw extension
This container enables AI agents to interact with a visual desktop, browse the web, and execute complex automation tasks - all accessible through RoqueOS's Agent app.
⚠️ Note: This image is designed to work with RoqueOS Server. The server manages container lifecycle and provides the integration layer.
✨ Features
🤖 OpenClaw AI Agent
- Pre-installed OpenClaw CLI and gateway
- Visual automation capabilities
- Support for Anthropic (Claude) and OpenAI (GPT-4)
- Browser extension for web interaction
- RoqueOS skill for system integration
🖥️ Full Desktop Environment
- XFCE4 lightweight desktop
- Dark theme (Adwaita-dark)
- Desktop shortcuts for quick access
- File manager (Thunar)
- Terminal emulator
🌐 Remote Access
- VNC server (TigerVNC) on port 5901
- noVNC web client on port 6080
- No password required (secured by network)
- Configurable resolution (default: 1920x1080)
🔗 RoqueOS Integration
roqueosCLI for server communication- Shared folder support (
/shared) - Environment variables for API credentials
- Automatic gateway startup when configured
🚀 How It Works
┌─────────────────────────────────────────────────────────────┐
│ RoqueOS Frontend │
│ (https://roqueos.com.br) │
│ Agent App │
└─────────────────────────────────────────────────────────────┘
│
│ WebSocket + REST
▼
┌─────────────────────────────────────────────────────────────┐
│ RoqueOS Server │
│ (roqueribeiro1988/roqueos-server) │
│ /agent endpoints │
└─────────────────────────────────────────────────────────────┘
│
│ Docker API
▼
┌─────────────────────────────────────────────────────────────┐
│ RoqueOS OpenClaw │
│ (roqueribeiro1988/roqueos-openclaw) │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ XFCE Desktop │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │OpenClaw │ │Chromium │ │Terminal │ │ │
│ │ │ Gateway │ │+Extension│ │ │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ VNC/noVNC │
└─────────────────────────────────────────────────────────────┘
- User opens Agent app in RoqueOS
- RoqueOS Server creates/manages OpenClaw container
- noVNC streams desktop to the browser
- OpenClaw gateway handles AI agent communication
- Agent executes tasks visually on the desktop
📦 Quick Start
Option 1: Standalone (for testing)
docker run -d \
--name roqueos-openclaw \
-p 5901:5901 \
-p 6080:6080 \
-v openclaw-data:/data/openclaw \
-v openclaw-config:/home/agent/.openclaw \
--shm-size=1gb \
roqueribeiro1988/roqueos-openclaw:latest
Access the desktop at: http://localhost:6080
Option 2: With RoqueOS Server (recommended)
The container is automatically managed by RoqueOS Server when you use the Agent app. No manual setup required.
Option 3: Docker Compose
version: '3.8'
services:
roqueos-openclaw:
image: roqueribeiro1988/roqueos-openclaw:latest
container_name: roqueos-openclaw
restart: unless-stopped
ports:
- "5901:5901" # VNC
- "6080:6080" # noVNC
- "18789:18789" # OpenClaw Gateway
environment:
- VNC_RESOLUTION=1920x1080
- VNC_COL_DEPTH=24
- ROQUEOS_SERVER_URL=http://host.docker.internal:27021
volumes:
- openclaw-data:/data/openclaw
- openclaw-config:/home/agent/.openclaw
- shared-files:/shared
shm_size: "1gb"
extra_hosts:
- "host.docker.internal:host-gateway"
volumes:
openclaw-data:
openclaw-config:
shared-files:
🔧 First-Time Setup
After starting the container, you need to configure OpenClaw with your AI provider API key:
Step 1: Access the Desktop
Open your browser and navigate to:
http://localhost:6080
Step 2: Open Terminal
Double-click the Terminal icon on the desktop.
Step 3: Run Setup
roqueclaw-setup
This will guide you through configuring your API key (Anthropic or OpenAI).
Step 4: Start Gateway
After setup, start the OpenClaw gateway:
roqueclaw-gateway
The gateway will be available at http://localhost:18789.
💡 Tip: If OpenClaw is already configured, the gateway starts automatically when the container boots.
⚙️ Environment Variables
| Variable | Default | Description |
|---|---|---|
VNC_RESOLUTION | 1920x1080 | Desktop resolution |
VNC_COL_DEPTH | 24 | Color depth (bits) |
VNC_PORT | 5901 | VNC server port |
NOVNC_PORT | 6080 | noVNC web client port |
ROQUEOS_SERVER_URL | http://host.docker.internal:27021 | RoqueOS Server URL |
ROQUEOS_API_KEY | (empty) | API Key for RoqueOS Server |
ROQUEOS_API_SECRET | (empty) | API Secret for RoqueOS Server |
ROQUEOS_SESSION_ID | (empty) | Agent session ID |
ROQUEOS_USER_ID | (empty) | User ID for the session |
🔌 Exposed Ports
| Port | Service | Description |
|---|---|---|
5901 | VNC | Direct VNC connection |
6080 | noVNC | Web-based VNC client |
18789 | OpenClaw Gateway | AI agent API (when running) |
💾 Volumes
| Volume | Container Path | Description |
|---|---|---|
| OpenClaw Data | /data/openclaw | Persistent agent data |
| OpenClaw Config | /home/agent/.openclaw | Configuration and API keys |
| Shared Files | /shared | Shared folder with RoqueOS |
🛠️ Pre-installed Software
Desktop Environment
| Component | Version |
|---|---|
| Ubuntu | 22.04 LTS |
| XFCE | 4.16 |
| TigerVNC | Latest |
| noVNC | Latest |
Development Tools
| Tool | Description |
|---|---|
| Node.js | 20.x |
| Yarn | Latest |
| Python 3 | System default |
| Git | Version control |
| Chromium | Web browser |
Utilities
| Tool | Description |
|---|---|
| curl, wget | HTTP clients |
| vim, nano | Text editors |
| htop | Process monitor |
| jq | JSON processor |
OpenClaw
| Component | Description |
|---|---|
| OpenClaw CLI | openclaw command |
| Browser Extension | Auto-loaded in Chromium |
| RoqueOS Skill | Pre-installed integration |
📋 Desktop Shortcuts
The desktop includes these shortcuts for quick access:
| Shortcut | Description |
|---|---|
| OpenClaw Terminal | Opens terminal with OpenClaw help |
| OpenClaw Dashboard | Starts gateway and opens dashboard |
| Chromium Browser | Web browser with OpenClaw extension |
| Shared Files | Opens shared folder in file manager |
| Terminal | Standard terminal emulator |
🔧 CLI Commands
RoqueClaw Commands
| Command | Description |
|---|---|
roqueclaw-setup | Configure OpenClaw API key |
roqueclaw-gateway | Start OpenClaw gateway |
roqueos | Communicate with RoqueOS Server |
OpenClaw Commands
| Command | Description |
|---|---|
openclaw | OpenClaw CLI |
openclaw onboard | Configure API key |
openclaw gateway | Start gateway server |
openclaw --help | Show all commands |
🔧 Troubleshooting
Desktop not loading?
# Check container logs
docker logs roqueos-openclaw
# Verify VNC is running
docker exec roqueos-openclaw nc -z localhost 5901
# Restart VNC manually
docker exec -u agent roqueos-openclaw vncserver -kill :1
docker exec -u agent roqueos-openclaw vncserver :1 -geometry 1920x1080 -depth 24 -SecurityTypes None
OpenClaw not configured?
# Access container shell
docker exec -it -u agent roqueos-openclaw bash
# Run setup
roqueclaw-setup
Chromium not starting?
# Test Chromium manually
docker exec -u agent roqueos-openclaw chromium-wrapper --version
# Check if shm_size is set (required for Chromium)
# Restart container with --shm-size=1gb
Gateway not starting?
# Check if OpenClaw is configured
docker exec -u agent roqueos-openclaw cat ~/.openclaw/config.json
# View gateway logs
docker exec roqueos-openclaw cat /tmp/openclaw-gateway.log
# Start manually
docker exec -it -u agent roqueos-openclaw roqueclaw-gateway
Connection refused to RoqueOS Server?
# Verify ROQUEOS_SERVER_URL is correct
docker exec roqueos-openclaw cat /home/agent/.roqueos-env
# Test connection
docker exec roqueos-openclaw curl -s http://host.docker.internal:27021/health
🏗️ Building Custom Image
If you need additional software or customizations:
FROM roqueribeiro1988/roqueos-openclaw:latest
# Install additional packages
USER root
RUN apt-get update && apt-get install -y \
your-package-here \
&& rm -rf /var/lib/apt/lists/*
# Add custom configuration
USER agent
COPY your-config /home/agent/.config/
📦 Related Images
| Image | Description | Link |
|---|---|---|
roqueribeiro1988/roqueos-server | Main RoqueOS Server | Docker Hub |
roqueribeiro1988/roqueos-server-ubuntu | Ubuntu container for terminal | Docker Hub |
roqueribeiro1988/roqueos-openclaw | OpenClaw agent (this image) | Docker Hub |
🔗 Links
- RoqueOS Frontend: https://roqueos.com.br
- RoqueOS Server: Docker Hub
- OpenClaw: https://openclaw.ai
- App Catalog: github.com/roqueribeiro/roqueos-containers-list
📄 License
MIT License - Copyright (c) 2024 Roque Ribeiro
Made with ❤️ by Roque Ribeiro
Tag summary
Content type
Image
Digest
sha256:c9654c356…
Size
912 MB
Last updated
2 months ago
docker pull roqueribeiro1988/roqueos-openclaw