Finalizing PR

2026-04-03 03:03:24 -04:00 · 2026-02-09 16:23:03 -05:00
parent 3715b9671c
commit 1c2e989838
3 changed files with 321 additions and 209 deletions
--- a/scripts/shell-helpers/README.md
+++ b/scripts/shell-helpers/README.md
@@ -6,23 +6,30 @@ Inspired by Simon Willison's [Running OpenClaw in Docker](https://til.simonwilli

 - [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)
- [Troubleshooting](#troubleshooting)
+  - [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)
- [Contributing](#contributing)

 ## Quickstart

-**Try it out:**
+**Install:**

 ```bash
-source <(curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh)
+mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
 ```

-**Make it permanent:**
-
 ```bash
-echo 'source <(curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh)' >> ~/.zshrc
+echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
 ```

 **See what you get:**
@@ -31,6 +38,11 @@ echo 'source <(curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main
 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
@@ -51,6 +63,8 @@ If you see "pairing required":
 clawdock-devices
 ```

+And approve the request for the specific device:
+
 ```bash
 clawdock-approve <request-id>
 ```
@@ -59,58 +73,64 @@ clawdock-approve <request-id>

 ### 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) |
+| 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 |
+| 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 |
+| 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 |
-|---------|-------------|
+| 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!) |
+| 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 |
+| 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
@@ -123,20 +143,6 @@ clawdock-status
 clawdock-logs
 ```

-### Restart After Configuration Changes
-
-**Restart the gateway:**
-
-```bash
-clawdock-restart
-```
-
-**Watch the logs:**
-
-```bash
-clawdock-logs
-```
-
 ### Set Up WhatsApp Bot

 **Shell into the container:**
@@ -170,7 +176,7 @@ clawdock-devices
 **Copy the Request ID from the "Pending" table, then approve:**

 ```bash
-clawdock-approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e
+clawdock-approve <request-id>
 ```

 Then refresh your browser.
@@ -184,31 +190,12 @@ 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

-## Troubleshooting
-
-### Commands Not Found
-
-**Source the helpers file:**
-
-```bash
-source <(curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh)
-```
-
-Add this line to your `~/.zshrc` or `~/.bashrc` for persistence.
-
-### Token Mismatch Errors
-
-**Run the token fixer:**
-
-```bash
-clawdock-fix-token
-```
-
 ### Permission Denied

 **Ensure Docker is running and you have permission:**
@@ -217,31 +204,22 @@ clawdock-fix-token
 docker ps
 ```

-### Container Not Starting
-
-**Check the logs:**
-
-```bash
-clawdock-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
+## Development

-Found a bug or want to add a new helper? Contributions welcome!
+**Test with fresh config (mimics first-time install):**

-1. Test your changes locally
-2. Ensure helpers work in both bash and zsh
-3. Follow the naming convention (`clawdock-*`)
-4. Add documentation for new commands
-5. Submit a pull request
+```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
+```
--- a/scripts/shell-helpers/clawdock-helpers.sh
+++ b/scripts/shell-helpers/clawdock-helpers.sh
@@ -4,71 +4,193 @@
 # https://til.simonwillison.net/llms/openclaw-docker
 #
 # Installation:
-#   source <(curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh)
+#   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
 #
 # Usage:
 #   clawdock-help    # Show all available commands

-# OpenClaw project directory (auto-detect or set manually)
-CLAWDOCK_DIR="${CLAWDOCK_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+# =============================================================================
+# Colors
+# =============================================================================
+_CLR_RESET='\033[0m'
+_CLR_BOLD='\033[1m'
+_CLR_DIM='\033[2m'
+_CLR_GREEN='\033[0;32m'
+_CLR_YELLOW='\033[1;33m'
+_CLR_BLUE='\033[0;34m'
+_CLR_MAGENTA='\033[0;35m'
+_CLR_CYAN='\033[0;36m'
+_CLR_RED='\033[0;31m'

-# Start openclaw gateway
-alias clawdock-start="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml up -d openclaw-gateway"
+# Styled command output (green + bold)
+_clr_cmd() {
+  echo -e "${_CLR_GREEN}${_CLR_BOLD}$1${_CLR_RESET}"
+}

-# Stop openclaw gateway
-alias clawdock-stop="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml down"
+# Inline command for use in sentences
+_cmd() {
+  echo "${_CLR_GREEN}${_CLR_BOLD}$1${_CLR_RESET}"
+}

-# Restart openclaw gateway
-alias clawdock-restart="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml restart openclaw-gateway"
+# =============================================================================
+# Config
+# =============================================================================
+CLAWDOCK_CONFIG="${HOME}/.clawdock/config"

-# View openclaw logs
-alias clawdock-logs="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml logs -f openclaw-gateway"
+# Common paths to check for OpenClaw
+CLAWDOCK_COMMON_PATHS=(
+  "${HOME}/openclaw"
+  "${HOME}/workspace/openclaw"
+  "${HOME}/projects/openclaw"
+  "${HOME}/dev/openclaw"
+  "${HOME}/code/openclaw"
+  "${HOME}/src/openclaw"
+)

-# Check openclaw status
-alias clawdock-status="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml ps"
+# Ensure CLAWDOCK_DIR is set and valid
+_clawdock_ensure_dir() {
+  # Already set and valid?
+  if [[ -n "$CLAWDOCK_DIR" && -f "${CLAWDOCK_DIR}/docker-compose.yml" ]]; then
+    return 0
+  fi

-# Open openclaw directory
-alias clawdock-cd="cd ${CLAWDOCK_DIR}"
+  # Try loading from config
+  if [[ -f "$CLAWDOCK_CONFIG" ]]; then
+    source "$CLAWDOCK_CONFIG"
+    if [[ -n "$CLAWDOCK_DIR" && -f "${CLAWDOCK_DIR}/docker-compose.yml" ]]; then
+      return 0
+    fi
+  fi

-# Shell into openclaw container (with openclaw alias pre-configured)
+  # Auto-detect from common paths
+  local found_path=""
+  for path in "${CLAWDOCK_COMMON_PATHS[@]}"; do
+    if [[ -f "${path}/docker-compose.yml" ]]; then
+      found_path="$path"
+      break
+    fi
+  done
+
+  if [[ -n "$found_path" ]]; then
+    echo ""
+    echo "🦞 Found OpenClaw at: $found_path"
+    echo -n "   Use this location? [Y/n] "
+    read -r response
+    if [[ "$response" =~ ^[Nn] ]]; then
+      echo ""
+      echo "Set CLAWDOCK_DIR manually:"
+      echo "  export CLAWDOCK_DIR=/path/to/openclaw"
+      return 1
+    fi
+    CLAWDOCK_DIR="$found_path"
+  else
+    echo ""
+    echo "❌ OpenClaw not found in common locations."
+    echo ""
+    echo "Clone it first:"
+    echo ""
+    echo "  git clone https://github.com/openclaw/openclaw.git ~/openclaw"
+    echo "  cd ~/openclaw && ./docker-setup.sh"
+    echo ""
+    echo "Or set CLAWDOCK_DIR if it's elsewhere:"
+    echo ""
+    echo "  export CLAWDOCK_DIR=/path/to/openclaw"
+    echo ""
+    return 1
+  fi
+
+  # Save to config
+  if [[ ! -d "${HOME}/.clawdock" ]]; then
+    /bin/mkdir -p "${HOME}/.clawdock"
+  fi
+  print "CLAWDOCK_DIR=\"$CLAWDOCK_DIR\"" > "$CLAWDOCK_CONFIG"
+  echo "✅ Saved to $CLAWDOCK_CONFIG"
+  echo ""
+  return 0
+}
+
+# Wrapper to run docker compose commands
+_clawdock_compose() {
+  _clawdock_ensure_dir || return 1
+  command docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" "$@"
+}
+
+# Basic Operations
+clawdock-start() {
+  _clawdock_compose up -d openclaw-gateway
+}
+
+clawdock-stop() {
+  _clawdock_compose down
+}
+
+clawdock-restart() {
+  _clawdock_compose restart openclaw-gateway
+}
+
+clawdock-logs() {
+  _clawdock_compose logs -f openclaw-gateway
+}
+
+clawdock-status() {
+  _clawdock_compose ps
+}
+
+# Navigation
+clawdock-cd() {
+  _clawdock_ensure_dir || return 1
+  cd "${CLAWDOCK_DIR}"
+}
+
+clawdock-config() {
+  cd ~/.openclaw
+}
+
+clawdock-workspace() {
+  cd ~/.openclaw/workspace
+}
+
+# Container Access
 clawdock-shell() {
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway \
+  _clawdock_compose exec openclaw-gateway \
    bash -c 'echo "alias openclaw=\"./openclaw.mjs\"" > /tmp/.bashrc_openclaw && bash --rcfile /tmp/.bashrc_openclaw'
 }

-# Rebuild openclaw Docker image
-alias clawdock-rebuild="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml build openclaw-gateway"
+clawdock-exec() {
+  _clawdock_compose exec openclaw-gateway "$@"
+}

-# Open config directory
-alias clawdock-config="cd ~/.openclaw"
+clawdock-cli() {
+  _clawdock_compose run --rm openclaw-cli "$@"
+}

-# Open workspace directory
-alias clawdock-workspace="cd ~/.openclaw/workspace"
+# Maintenance
+clawdock-rebuild() {
+  _clawdock_compose build openclaw-gateway
+}

-# Clean up containers and volumes (nuclear option)
-alias clawdock-clean="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml down -v --remove-orphans"
+clawdock-clean() {
+  _clawdock_compose down -v --remove-orphans
+}

 # Health check
 clawdock-health() {
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway \
+  _clawdock_ensure_dir || return 1
+  _clawdock_compose exec openclaw-gateway \
    node dist/index.js health --token "$(grep OPENCLAW_GATEWAY_TOKEN ${CLAWDOCK_DIR}/.env | cut -d'=' -f2)"
 }

 # Show gateway token
 clawdock-token() {
+  _clawdock_ensure_dir || return 1
  grep OPENCLAW_GATEWAY_TOKEN "${CLAWDOCK_DIR}/.env" | cut -d'=' -f2
 }

-# Execute command in container
-clawdock-exec() {
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway "$@"
-}
-
-# Run interactive CLI commands (dedicated CLI container)
-alias clawdock-cli="docker compose -f ${CLAWDOCK_DIR}/docker-compose.yml run --rm openclaw-cli"
-
 # Fix token configuration (run this once after setup)
 clawdock-fix-token() {
+  _clawdock_ensure_dir || return 1
+
  echo "🔧 Configuring gateway token..."
  local token=$(clawdock-token)
  if [[ -z "$token" ]]; then
@@ -79,12 +201,11 @@ clawdock-fix-token() {

  echo "📝 Setting token: ${token:0:20}..."

-  # Set both tokens directly (simpler approach)
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway \
+  _clawdock_compose exec openclaw-gateway \
    bash -c "./openclaw.mjs config set gateway.remote.token '$token' && ./openclaw.mjs config set gateway.auth.token '$token'" 2>&1 | grep -v "^WARN\|^time="

  echo "🔍 Verifying token was saved..."
-  local saved_token=$(docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway \
+  local saved_token=$(_clawdock_compose exec openclaw-gateway \
    bash -c "./openclaw.mjs config get gateway.remote.token 2>/dev/null" 2>&1 | grep -v "^WARN\|^time=" | tr -d '\r\n' | head -c 64)

  if [[ "$saved_token" == "$token" ]]; then
@@ -96,73 +217,79 @@ clawdock-fix-token() {
  fi

  echo "🔄 Restarting gateway..."
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" restart openclaw-gateway 2>&1 | grep -v "^WARN\|^time="
+  _clawdock_compose restart openclaw-gateway 2>&1 | grep -v "^WARN\|^time="

  echo "⏳ Waiting for gateway to start..."
  sleep 5

  echo "✅ Configuration complete!"
-  echo "   Try: clawdock-devices"
+  echo -e "   Try: $(_cmd clawdock-devices)"
 }

 # Open dashboard in browser
 clawdock-dashboard() {
+  _clawdock_ensure_dir || return 1
+
  echo "🦞 Getting dashboard URL..."
-  local url=$(docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" run --rm openclaw-cli dashboard --no-open 2>&1 | grep -v "^WARN\|^time=" | grep -o 'http[s]\?://[^[:space:]]*')
+  local url=$(_clawdock_compose run --rm openclaw-cli dashboard --no-open 2>&1 | grep -v "^WARN\|^time=" | grep -o 'http[s]\?://[^[:space:]]*')

  if [[ -n "$url" ]]; then
    echo "✅ Opening: $url"
    open "$url" 2>/dev/null || xdg-open "$url" 2>/dev/null || echo "   Please open manually: $url"
    echo ""
-    echo "💡 If you see 'pairing required' error:"
-    echo "   1. Run: clawdock-devices"
+    echo -e "${_CLR_CYAN}💡 If you see 'pairing required' error:${_CLR_RESET}"
+    echo -e "   1. Run: $(_cmd clawdock-devices)"
    echo "   2. Copy the Request ID from the Pending table"
-    echo "   3. Run: clawdock-approve <request-id>"
+    echo -e "   3. Run: $(_cmd 'clawdock-approve <request-id>')"
  else
    echo "❌ Failed to get dashboard URL"
-    echo "   Try restarting: clawdock-restart"
+    echo -e "   Try restarting: $(_cmd clawdock-restart)"
  fi
 }

 # List device pairings
 clawdock-devices() {
+  _clawdock_ensure_dir || return 1
+
  echo "🔍 Checking device pairings..."
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway \
+  _clawdock_compose exec openclaw-gateway \
    node dist/index.js devices list 2>&1 | grep -v "^WARN\|^time="

  local exit_code=$?
  if [ $exit_code -ne 0 ]; then
    echo ""
-    echo "💡 If you see token errors above:"
-    echo "   1. Verify token is set: clawdock-token"
+    echo -e "${_CLR_CYAN}💡 If you see token errors above:${_CLR_RESET}"
+    echo -e "   1. Verify token is set: $(_cmd clawdock-token)"
    echo "   2. Try manual config inside container:"
-    echo "      clawdock-shell"
-    echo "      openclaw config get gateway.remote.token"
+    echo -e "      $(_cmd clawdock-shell)"
+    echo -e "      $(_cmd 'openclaw config get gateway.remote.token')"
    return 1
  fi

  echo ""
-  echo "💡 To approve a pairing request:"
-  echo "   clawdock-approve <request-id>"
+  echo -e "${_CLR_CYAN}💡 To approve a pairing request:${_CLR_RESET}"
+  echo -e "   $(_cmd 'clawdock-approve <request-id>')"
 }

 # Approve device pairing request
 clawdock-approve() {
+  _clawdock_ensure_dir || return 1
+
  if [[ -z "$1" ]]; then
-    echo "❌ Usage: clawdock-approve <request-id>"
+    echo -e "❌ Usage: $(_cmd 'clawdock-approve <request-id>')"
    echo ""
-    echo "💡 How to approve a device:"
-    echo "   1. Run: clawdock-devices"
+    echo -e "${_CLR_CYAN}💡 How to approve a device:${_CLR_RESET}"
+    echo -e "   1. Run: $(_cmd clawdock-devices)"
    echo "   2. Find the Request ID in the Pending table (long UUID)"
-    echo "   3. Run: clawdock-approve <that-request-id>"
+    echo -e "   3. Run: $(_cmd 'clawdock-approve <that-request-id>')"
    echo ""
    echo "Example:"
-    echo "   clawdock-approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e"
+    echo -e "   $(_cmd 'clawdock-approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e')"
    return 1
  fi

  echo "✅ Approving device: $1"
-  docker compose -f "${CLAWDOCK_DIR}/docker-compose.yml" exec openclaw-gateway \
+  _clawdock_compose exec openclaw-gateway \
    node dist/index.js devices approve "$1" 2>&1 | grep -v "^WARN\|^time="

  echo ""
@@ -171,85 +298,74 @@ clawdock-approve() {

 # Show all available clawdock helper commands
 clawdock-help() {
-  # Colors
-  local CYAN='\033[0;36m'
-  local BOLD='\033[1m'
-  local GREEN='\033[0;32m'
-  local YELLOW='\033[1;33m'
-  local BLUE='\033[0;34m'
-  local MAGENTA='\033[0;35m'
-  local RED='\033[0;31m'
-  local RESET='\033[0m'
-  local DIM='\033[2m'
+  echo -e "\n${_CLR_BOLD}${_CLR_CYAN}🦞 ClawDock - Docker Helpers for OpenClaw${_CLR_RESET}\n"

-  echo -e "\n${BOLD}${CYAN}🦞 ClawDock - Docker Helpers for OpenClaw${RESET}\n"
-
-  echo -e "${BOLD}${MAGENTA}⚡ Basic Operations${RESET}"
-  echo -e "  ${BOLD}clawdock-start${RESET}       ${DIM}Start the gateway${RESET}"
-  echo -e "  ${BOLD}clawdock-stop${RESET}        ${DIM}Stop the gateway${RESET}"
-  echo -e "  ${BOLD}clawdock-restart${RESET}     ${DIM}Restart the gateway${RESET}"
-  echo -e "  ${BOLD}clawdock-status${RESET}      ${DIM}Check container status${RESET}"
-  echo -e "  ${BOLD}clawdock-logs${RESET}        ${DIM}View live logs (follows)${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_MAGENTA}⚡ Basic Operations${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-start)       ${_CLR_DIM}Start the gateway${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-stop)        ${_CLR_DIM}Stop the gateway${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-restart)     ${_CLR_DIM}Restart the gateway${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-status)      ${_CLR_DIM}Check container status${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-logs)        ${_CLR_DIM}View live logs (follows)${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${MAGENTA}🐚 Container Access${RESET}"
-  echo -e "  ${BOLD}clawdock-shell${RESET}       ${DIM}Shell into container (openclaw alias ready)${RESET}"
-  echo -e "  ${BOLD}clawdock-cli${RESET}         ${DIM}Run CLI commands (e.g., clawdock-cli status)${RESET}"
-  echo -e "  ${BOLD}clawdock-exec${RESET} ${CYAN}<cmd>${RESET}  ${DIM}Execute command in gateway container${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_MAGENTA}🐚 Container Access${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-shell)       ${_CLR_DIM}Shell into container (openclaw alias ready)${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-cli)         ${_CLR_DIM}Run CLI commands (e.g., clawdock-cli status)${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-exec) ${_CLR_CYAN}<cmd>${_CLR_RESET}  ${_CLR_DIM}Execute command in gateway container${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${MAGENTA}🌐 Web UI & Devices${RESET}"
-  echo -e "  ${BOLD}clawdock-dashboard${RESET}   ${DIM}Open web UI in browser ${YELLOW}(auto-guides you)${RESET}"
-  echo -e "  ${BOLD}clawdock-devices${RESET}     ${DIM}List device pairings ${YELLOW}(auto-guides you)${RESET}"
-  echo -e "  ${BOLD}clawdock-approve${RESET} ${CYAN}<id>${RESET} ${DIM}Approve device pairing ${YELLOW}(with examples)${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_MAGENTA}🌐 Web UI & Devices${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-dashboard)   ${_CLR_DIM}Open web UI in browser ${_CLR_CYAN}(auto-guides you)${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-devices)     ${_CLR_DIM}List device pairings ${_CLR_CYAN}(auto-guides you)${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-approve) ${_CLR_CYAN}<id>${_CLR_RESET} ${_CLR_DIM}Approve device pairing ${_CLR_CYAN}(with examples)${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${MAGENTA}⚙️  Setup & Configuration${RESET}"
-  echo -e "  ${BOLD}clawdock-fix-token${RESET}   ${DIM}Configure gateway token ${YELLOW}(run once)${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_MAGENTA}⚙️  Setup & Configuration${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-fix-token)   ${_CLR_DIM}Configure gateway token ${_CLR_CYAN}(run once)${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${MAGENTA}🔧 Maintenance${RESET}"
-  echo -e "  ${BOLD}clawdock-rebuild${RESET}     ${DIM}Rebuild Docker image${RESET}"
-  echo -e "  ${BOLD}clawdock-clean${RESET}       ${RED}⚠️  Remove containers & volumes (nuclear)${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_MAGENTA}🔧 Maintenance${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-rebuild)     ${_CLR_DIM}Rebuild Docker image${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-clean)       ${_CLR_RED}⚠️  Remove containers & volumes (nuclear)${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${MAGENTA}🛠️  Utilities${RESET}"
-  echo -e "  ${BOLD}clawdock-health${RESET}      ${DIM}Run health check${RESET}"
-  echo -e "  ${BOLD}clawdock-token${RESET}       ${DIM}Show gateway auth token${RESET}"
-  echo -e "  ${BOLD}clawdock-cd${RESET}          ${DIM}Jump to openclaw project directory${RESET}"
-  echo -e "  ${BOLD}clawdock-config${RESET}      ${DIM}Open config directory (~/.openclaw)${RESET}"
-  echo -e "  ${BOLD}clawdock-workspace${RESET}   ${DIM}Open workspace directory${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_MAGENTA}🛠️  Utilities${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-health)      ${_CLR_DIM}Run health check${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-token)       ${_CLR_DIM}Show gateway auth token${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-cd)          ${_CLR_DIM}Jump to openclaw project directory${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-config)      ${_CLR_DIM}Open config directory (~/.openclaw)${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-workspace)   ${_CLR_DIM}Open workspace directory${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
-  echo -e "${BOLD}${GREEN}🚀 First Time Setup${RESET}"
-  echo -e "${CYAN}  1.${RESET} ${GREEN}clawdock-start${RESET}          ${DIM}# Start the gateway${RESET}"
-  echo -e "${CYAN}  2.${RESET} ${GREEN}clawdock-fix-token${RESET}      ${DIM}# Configure token${RESET}"
-  echo -e "${CYAN}  3.${RESET} ${GREEN}clawdock-dashboard${RESET}      ${DIM}# Open web UI${RESET}"
-  echo -e "${CYAN}  4.${RESET} ${GREEN}clawdock-devices${RESET}        ${DIM}# If pairing needed${RESET}"
-  echo -e "${CYAN}  5.${RESET} ${GREEN}clawdock-approve${RESET} ${CYAN}<id>${RESET}   ${DIM}# Approve pairing${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${_CLR_RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_GREEN}🚀 First Time Setup${_CLR_RESET}"
+  echo -e "${_CLR_CYAN}  1.${_CLR_RESET} $(_cmd clawdock-start)          ${_CLR_DIM}# Start the gateway${_CLR_RESET}"
+  echo -e "${_CLR_CYAN}  2.${_CLR_RESET} $(_cmd clawdock-fix-token)      ${_CLR_DIM}# Configure token${_CLR_RESET}"
+  echo -e "${_CLR_CYAN}  3.${_CLR_RESET} $(_cmd clawdock-dashboard)      ${_CLR_DIM}# Open web UI${_CLR_RESET}"
+  echo -e "${_CLR_CYAN}  4.${_CLR_RESET} $(_cmd clawdock-devices)        ${_CLR_DIM}# If pairing needed${_CLR_RESET}"
+  echo -e "${_CLR_CYAN}  5.${_CLR_RESET} $(_cmd clawdock-approve) ${_CLR_CYAN}<id>${_CLR_RESET}   ${_CLR_DIM}# Approve pairing${_CLR_RESET}"
  echo ""

-  echo -e "${BOLD}${GREEN}💬 WhatsApp Setup${RESET}"
-  echo -e "  ${GREEN}clawdock-shell${RESET}"
-  echo -e "    ${BLUE}>${RESET} ${GREEN}openclaw channels login --channel whatsapp${RESET}"
-  echo -e "    ${BLUE}>${RESET} ${GREEN}openclaw status${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_GREEN}💬 WhatsApp Setup${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-shell)"
+  echo -e "    ${_CLR_BLUE}>${_CLR_RESET} $(_cmd 'openclaw channels login --channel whatsapp')"
+  echo -e "    ${_CLR_BLUE}>${_CLR_RESET} $(_cmd 'openclaw status')"
  echo ""

-  echo -e "${BOLD}${GREEN}📝 Quick Examples${RESET}"
-  echo -e "  ${GREEN}clawdock-start${RESET} && ${GREEN}clawdock-logs${RESET}"
-  echo -e "  ${GREEN}clawdock-dashboard${RESET}"
-  echo -e "  ${GREEN}clawdock-devices${RESET}"
-  echo -e "  ${GREEN}clawdock-cli${RESET} ${CYAN}channels login${RESET}"
-  echo -e "${BOLD}${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  echo -e "${_CLR_BOLD}${_CLR_CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${_CLR_RESET}"
  echo ""

-  echo -e "${YELLOW}💡 All commands guide you through next steps!${RESET}"
-  echo -e "${BLUE}📚 Docs: ${RESET}${CYAN}https://docs.openclaw.ai${RESET}"
+  echo -e "${_CLR_CYAN}💡 All commands guide you through next steps!${_CLR_RESET}"
+  echo -e "${_CLR_BLUE}📚 Docs: ${_CLR_RESET}${_CLR_CYAN}https://docs.openclaw.ai${_CLR_RESET}"
  echo ""
 }

 # Export functions so they're available in subshells
-export -f clawdock-shell clawdock-health clawdock-token clawdock-exec
-export -f clawdock-fix-token clawdock-dashboard clawdock-devices
-export -f clawdock-approve clawdock-help
+export -f _cmd _clawdock_ensure_dir _clawdock_compose
+export -f clawdock-start clawdock-stop clawdock-restart clawdock-logs clawdock-status
+export -f clawdock-cd clawdock-config clawdock-workspace
+export -f clawdock-shell clawdock-exec clawdock-cli
+export -f clawdock-rebuild clawdock-clean
+export -f clawdock-health clawdock-token clawdock-fix-token
+export -f clawdock-dashboard clawdock-devices clawdock-approve
+export -f clawdock-help