mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-16 23:29:32 +00:00
31f616d45b
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>
227 lines
5.4 KiB
Markdown
227 lines
5.4 KiB
Markdown
# ClawDock <!-- omit in toc -->
|
|
|
|
Stop typing `docker-compose` commands. Just type `clawdock-start`.
|
|
|
|
Inspired by Simon Willison's [Running OpenClaw in Docker](https://til.simonwillison.net/llms/openclaw-docker).
|
|
|
|
- [Quickstart](#quickstart)
|
|
- [Available Commands](#available-commands)
|
|
- [Basic Operations](#basic-operations)
|
|
- [Container Access](#container-access)
|
|
- [Web UI \& Devices](#web-ui--devices)
|
|
- [Setup \& Configuration](#setup--configuration)
|
|
- [Maintenance](#maintenance)
|
|
- [Utilities](#utilities)
|
|
- [Common Workflows](#common-workflows)
|
|
- [Check Status and Logs](#check-status-and-logs)
|
|
- [Set Up WhatsApp Bot](#set-up-whatsapp-bot)
|
|
- [Troubleshooting Device Pairing](#troubleshooting-device-pairing)
|
|
- [Fix Token Mismatch Issues](#fix-token-mismatch-issues)
|
|
- [Permission Denied](#permission-denied)
|
|
- [Requirements](#requirements)
|
|
|
|
## Quickstart
|
|
|
|
**Install:**
|
|
|
|
```bash
|
|
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
|
|
```
|
|
|
|
```bash
|
|
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
|
|
```
|
|
|
|
**See what you get:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
clawdock-start
|
|
```
|
|
|
|
```bash
|
|
clawdock-fix-token
|
|
```
|
|
|
|
```bash
|
|
clawdock-dashboard
|
|
```
|
|
|
|
If you see "pairing required":
|
|
|
|
```bash
|
|
clawdock-devices
|
|
```
|
|
|
|
And approve the request for the specific device:
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
clawdock-restart
|
|
```
|
|
|
|
**Check container status:**
|
|
|
|
```bash
|
|
clawdock-status
|
|
```
|
|
|
|
**View live logs:**
|
|
|
|
```bash
|
|
clawdock-logs
|
|
```
|
|
|
|
### Set Up WhatsApp Bot
|
|
|
|
**Shell into the container:**
|
|
|
|
```bash
|
|
clawdock-shell
|
|
```
|
|
|
|
**Inside the container, login to WhatsApp:**
|
|
|
|
```bash
|
|
openclaw channels login --channel whatsapp --verbose
|
|
```
|
|
|
|
Scan the QR code with WhatsApp on your phone.
|
|
|
|
**Verify connection:**
|
|
|
|
```bash
|
|
openclaw status
|
|
```
|
|
|
|
### Troubleshooting Device Pairing
|
|
|
|
**Check for pending pairing requests:**
|
|
|
|
```bash
|
|
clawdock-devices
|
|
```
|
|
|
|
**Copy the Request ID from the "Pending" table, then approve:**
|
|
|
|
```bash
|
|
clawdock-approve <request-id>
|
|
```
|
|
|
|
Then refresh your browser.
|
|
|
|
### Fix Token Mismatch Issues
|
|
|
|
If you see "gateway token mismatch" errors:
|
|
|
|
```bash
|
|
clawdock-fix-token
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Read the token from your `.env` file
|
|
2. Configure it in the OpenClaw config
|
|
3. Restart the gateway
|
|
4. Verify the configuration
|
|
|
|
### Permission Denied
|
|
|
|
**Ensure Docker is running and you have permission:**
|
|
|
|
```bash
|
|
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):**
|
|
|
|
```bash
|
|
unset CLAWDOCK_DIR && rm -f ~/.clawdock/config && source scripts/shell-helpers/clawdock-helpers.sh
|
|
```
|
|
|
|
Then run any command to trigger auto-detect:
|
|
|
|
```bash
|
|
clawdock-start
|
|
```
|