openclaw/scripts/shell-helpers

OpenClaw Shell Helpers

User-friendly shell commands for managing OpenClaw Docker containers. These helpers make it easy to start, stop, configure, and interact with OpenClaw without memorizing complex docker-compose commands.

Features

✨ Simple Commands - Intuitive names like openclaw-start, openclaw-stop, openclaw-dashboard 🎨 Beautiful Output - Colorful, emoji-rich terminal output with clear guidance 🔧 Auto-Configuration - Helpers guide you through setup and troubleshooting 🚀 Fast Onboarding - Get started with OpenClaw in minutes 📖 Self-Documenting - Run openclaw-help anytime to see available commands

Quick Start

Installation

Add to your shell configuration file (~/.zshrc or ~/.bashrc):

# Add this line to your ~/.zshrc or ~/.bashrc
source /path/to/openclaw/scripts/shell-helpers/openclaw-helpers.sh

Then reload your shell:

source ~/.zshrc  # or source ~/.bashrc

First Time Setup

# 1. Start the gateway
openclaw-start

# 2. Configure authentication token
openclaw-fix-token

# 3. Open the web dashboard
openclaw-dashboard

# 4. If you see "pairing required", approve devices
openclaw-devices
openclaw-approve <request-id>

# 5. Set up WhatsApp (optional)
openclaw-shell
  > openclaw channels login --channel whatsapp

Available Commands

Basic Operations

• openclaw-start - Start the OpenClaw gateway
• openclaw-stop - Stop the gateway
• openclaw-restart - Restart the gateway
• openclaw-status - Check container status
• openclaw-logs - View live logs (follows output)

Container Access

• openclaw-shell - Interactive shell inside the gateway container
• openclaw-cli <command> - Run OpenClaw CLI commands
• openclaw-exec <command> - Execute arbitrary commands in the container

Web UI & Devices

• openclaw-dashboard - Open web UI in browser with authentication
• openclaw-devices - List device pairing requests
• openclaw-approve <id> - Approve a device pairing request

Setup & Configuration

• openclaw-fix-token - Configure gateway authentication token (run once after setup)

Maintenance

• openclaw-rebuild - Rebuild the Docker image
• openclaw-clean - ⚠️ Remove all containers and volumes (destructive!)

Utilities

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

Common Workflows

Check Status and Logs

openclaw-status
openclaw-logs

Restart After Configuration Changes

openclaw-restart
openclaw-logs

Access the Dashboard

openclaw-dashboard

The dashboard will open automatically with the correct authentication token.

Set Up WhatsApp Bot

# 1. Shell into the container
openclaw-shell

# 2. Inside the container, login to WhatsApp
openclaw channels login --channel whatsapp --verbose

# 3. Scan the QR code with WhatsApp on your phone
# 4. Verify connection
openclaw status

Troubleshooting Device Pairing

# 1. Check for pending pairing requests
openclaw-devices

# 2. Copy the Request ID from the "Pending" table
# 3. Approve the request
openclaw-approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e

# 4. Refresh your browser

Fix Token Mismatch Issues

If you see "gateway token mismatch" errors:

openclaw-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

Troubleshooting

Commands Not Found

Make sure you've sourced the helpers file:

source /path/to/openclaw/scripts/shell-helpers/openclaw-helpers.sh

Add it to your ~/.zshrc or ~/.bashrc for persistence.

Token Mismatch Errors

Run openclaw-fix-token to automatically configure the authentication token.

Permission Denied

Ensure Docker is running and you have permission to use it:

docker ps

Container Not Starting

Check the logs:

openclaw-logs

Common issues:

• Port 18789 or 18790 already in use
• Missing environment variables in .env
• Docker daemon not running

Requirements

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

Contributing

Found a bug or want to add a new helper? Contributions are welcome!

1. Test your changes locally
2. Ensure helpers work in both bash and zsh
3. Follow the existing naming convention (openclaw-*)
4. Add documentation for new commands
5. Submit a pull request

License

Same as the OpenClaw project.

Support

• 📚 OpenClaw Documentation
• 💬 Community Discussions
• 🐛 Report Issues