mirror of https://github.com/openclaw/openclaw.git synced 2026-02-15 22:59:29 +00:00

Files

Daniel Olshansky 31f616d45b feat: ClawDock - shell docker helpers for OpenClaw development (#12817 )

Discussion: https://github.com/openclaw/openclaw/discussions/13528

## Checklist

- [x] **Mark as AI-assisted in the PR title or description** - Implemented by 🤖, reviewed by 👨‍💻 
- [x] **Note the degree of testing** - fully tested and I use it myself
- [x] **Include prompts or session logs if possible (super helpful!)** - I can try doing a "resume" on a few sessions, but don't think it'll provide value. Lmk if this is a blocker.
- [x] **Confirm you understand what the code does** - It's simple :)

## Summary of changes

- **ClawDock** - Shell helpers replace verbose `docker-compose` commands with simple `clawdock-*` shortcuts
- **Zero-config setup** - First run auto-detects the OpenClaw project directory from common paths and saves the config for future use
- **No extra dependencies** - Just bash
- **Built-in auth & device pairing helpers** - `clawdock-fix-token`, `clawdock-dashboard`, etc to handle gateay setup, streamline web UI, etc...
- **Updated Docker docs** - Installation docs now include the optional ClawDock helper setup for users who want simplified container management

## Example Usage

```bash
$ clawdock-help

🦞 ClawDock - Docker Helpers for OpenClaw

⚡ Basic Operations
  clawdock-start       Start the gateway
  clawdock-stop        Stop the gateway
  clawdock-restart     Restart the gateway
  clawdock-status      Check container status
  clawdock-logs        View live logs (follows)

🐚 Container Access
  clawdock-shell       Shell into container (openclaw alias ready)
  clawdock-cli         Run CLI commands (e.g., clawdock-cli status)
  clawdock-exec <cmd>  Execute command in gateway container

🌐 Web UI & Devices
  clawdock-dashboard   Open web UI in browser (auto-guides you)
  clawdock-devices     List device pairings (auto-guides you)
  clawdock-approve <id> Approve device pairing (with examples)

⚙️  Setup & Configuration
  clawdock-fix-token   Configure gateway token (run once)

🔧 Maintenance
  clawdock-rebuild     Rebuild Docker image
  clawdock-clean       ⚠️  Remove containers & volumes (nuclear)

🛠️  Utilities
  clawdock-health      Run health check
  clawdock-token       Show gateway auth token
  clawdock-cd          Jump to openclaw project directory
  clawdock-config      Open config directory (~/.openclaw)
  clawdock-workspace   Open workspace directory

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 First Time Setup
  1. clawdock-start          # Start the gateway
  2. clawdock-fix-token      # Configure token
  3. clawdock-dashboard      # Open web UI
  4. clawdock-devices        # If pairing needed
  5. clawdock-approve <id>   # Approve pairing

💬 WhatsApp Setup
  clawdock-shell
    > openclaw channels login --channel whatsapp
    > openclaw status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 All commands guide you through next steps!
📚 Docs: https://docs.openclaw.ai
```\n\nCo-authored-by: Gustavo Madeira Santana <gumadeiras@gmail.com>

2026-02-10 16:04:41 -05:00

5.4 KiB

Raw Blame History

ClawDock

Stop typing docker-compose commands. Just type clawdock-start.

Inspired by Simon Willison's Running OpenClaw in Docker.

Quickstart
Available Commands
Common Workflows
Requirements

Quickstart

Install:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

See what you get:

clawdock-help

On first command, ClawDock auto-detects your OpenClaw directory:

Checks common paths (~/openclaw, ~/workspace/openclaw, etc.)
If found, asks you to confirm
Saves to ~/.clawdock/config

First time setup:

clawdock-start

clawdock-fix-token

clawdock-dashboard

If you see "pairing required":

clawdock-devices

And approve the request for the specific device:

clawdock-approve <request-id>

Available Commands

Basic Operations

Command	Description
`clawdock-start`	Start the gateway
`clawdock-stop`	Stop the gateway
`clawdock-restart`	Restart the gateway
`clawdock-status`	Check container status
`clawdock-logs`	View live logs (follows output)

Container Access

Command	Description
`clawdock-shell`	Interactive shell inside the gateway container
`clawdock-cli <command>`	Run OpenClaw CLI commands
`clawdock-exec <command>`	Execute arbitrary commands in the container

Web UI & Devices

Command	Description
`clawdock-dashboard`	Open web UI in browser with authentication
`clawdock-devices`	List device pairing requests
`clawdock-approve <id>`	Approve a device pairing request

Setup & Configuration

Command	Description
`clawdock-fix-token`	Configure gateway authentication token (run once)

Maintenance

Command	Description
`clawdock-rebuild`	Rebuild the Docker image
`clawdock-clean`	Remove all containers and volumes (destructive!)

Utilities

Command	Description
`clawdock-health`	Run gateway health check
`clawdock-token`	Display the gateway authentication token
`clawdock-cd`	Jump to the OpenClaw project directory
`clawdock-config`	Open the OpenClaw config directory
`clawdock-workspace`	Open the workspace directory
`clawdock-help`	Show all available commands with examples

Common Workflows

Check Status and Logs

Restart the gateway:

clawdock-restart

Check container status:

clawdock-status

View live logs:

clawdock-logs

Set Up WhatsApp Bot

Shell into the container:

clawdock-shell

Inside the container, login to WhatsApp:

openclaw channels login --channel whatsapp --verbose

Scan the QR code with WhatsApp on your phone.

Verify connection:

openclaw status

Troubleshooting Device Pairing

Check for pending pairing requests:

clawdock-devices

Copy the Request ID from the "Pending" table, then approve:

clawdock-approve <request-id>

Then refresh your browser.

Fix Token Mismatch Issues

If you see "gateway token mismatch" errors:

clawdock-fix-token

This will:

Read the token from your .env file
Configure it in the OpenClaw config
Restart the gateway
Verify the configuration

Permission Denied

Ensure Docker is running and you have permission:

docker ps

Requirements

Docker and Docker Compose installed
Bash or Zsh shell
OpenClaw project (from docker-setup.sh)

Development

Test with fresh config (mimics first-time install):

unset CLAWDOCK_DIR && rm -f ~/.clawdock/config && source scripts/shell-helpers/clawdock-helpers.sh

Then run any command to trigger auto-detect:

clawdock-start

5.4 KiB Raw Blame History