Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

scripts/clawdock/README.md

@@ -0,0 +1,366 @@
+# 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)
+- [Configuration \& Secrets](#configuration--secrets)
+  - [Docker Files](#docker-files)
+  - [Config Files](#config-files)
+  - [Initial Setup](#initial-setup)
+  - [How It Works in Docker](#how-it-works-in-docker)
+  - [Env Precedence](#env-precedence)
+- [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)
+- [Development](#development)
+
+## Quickstart
+
+**Install:**
+
+```bash
+mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
+```
+
+```bash
+echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
+```
+
+Canonical docs page: https://docs.openclaw.ai/install/clawdock
+
+If you previously installed ClawDock from `scripts/shell-helpers/clawdock-helpers.sh`, rerun the install command above. The old raw GitHub path has been removed.
+
+**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-update`  | Pull latest, rebuild image, and restart (one command) |
+| `clawdock-rebuild` | Rebuild the Docker image only                         |
+| `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-show-config` | Print config files with redacted values   |
+| `clawdock-workspace`   | Open the workspace directory              |
+| `clawdock-help`        | Show all available commands with examples |
+
+## Configuration & Secrets
+
+The Docker setup uses three config files on the host. The container never stores secrets — everything is bind-mounted from local files.
+
+### Docker Files
+
+| File                          | Purpose                                                                        |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `Dockerfile`                  | Builds the `openclaw:local` image (Node 22, pnpm, non-root `node` user)        |
+| `docker-compose.yml`          | Defines `openclaw-gateway` and `openclaw-cli` services, bind-mounts, ports     |
+| `docker-compose.override.yml` | Standard Docker Compose overrides — auto-loaded by ClawDock helpers if present |
+| `docker-compose.extra.yml`    | Additional overrides — loaded after the standard override if present           |
+| `scripts/docker/setup.sh`     | First-time setup — builds image, creates `.env` from `.env.example`            |
+| `.env.example`                | Template for `<project>/.env` with all supported vars and docs                 |
+
+### Config Files
+
+| File                        | Purpose                                          | Examples                                                                                                |
+| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `<project>/.env`            | **Docker infra** — image, ports, gateway token   | `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_IMAGE`, `OPENCLAW_GATEWAY_PORT`, `OPENCLAW_AUTH_PROFILE_SECRET_DIR` |
+| `~/.openclaw/.env`          | **Secrets** — API keys and bot tokens            | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TELEGRAM_BOT_TOKEN`                                             |
+| `~/.openclaw/openclaw.json` | **Behavior config** — models, channels, policies | Model selection, WhatsApp allowlists, agent settings                                                    |
+
+**Do NOT** put API keys or bot tokens in `openclaw.json`. Use `~/.openclaw/.env` for all secrets.
+
+### Initial Setup
+
+`./scripts/docker/setup.sh` handles first-time Docker configuration:
+
+- Builds the `openclaw:local` image from `Dockerfile`
+- Creates `<project>/.env` from `.env.example` with a generated gateway token
+- Creates the auth-profile secret key directory
+- Sets up `~/.openclaw` directories if they don't exist
+
+```bash
+./scripts/docker/setup.sh
+```
+
+After setup, add your API keys:
+
+```bash
+vim ~/.openclaw/.env
+```
+
+See `.env.example` for all supported keys.
+
+The `Dockerfile` supports optional build args:
+
+- `OPENCLAW_IMAGE_APT_PACKAGES` — extra apt packages to install (e.g. `ffmpeg`); also accepts legacy `OPENCLAW_DOCKER_APT_PACKAGES`
+- `OPENCLAW_IMAGE_PIP_PACKAGES` — extra Python packages to install (e.g. `requests==2.32.5`); pin versions and use only package indexes you trust
+- `OPENCLAW_INSTALL_BROWSER=1` — pre-install Chromium for browser automation (adds ~300MB, but skips the 60-90s Playwright install on each container start)
+
+### How It Works in Docker
+
+`docker-compose.yml` bind-mounts both config and workspace from the host:
+
+```yaml
+volumes:
+  - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
+  - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
+  - ${OPENCLAW_AUTH_PROFILE_SECRET_DIR}:/home/node/.config/openclaw
+```
+
+This means:
+
+- `~/.openclaw/.env` is available inside the container at `/home/node/.openclaw/.env` — OpenClaw loads it automatically as the global env fallback
+- `~/.openclaw/openclaw.json` is available at `/home/node/.openclaw/openclaw.json` — the gateway watches it and hot-reloads most changes
+- `~/.openclaw-auth-profile-secrets` is available at `/home/node/.config/openclaw` — OpenClaw stores the auth-profile encryption key there
+- Downloadable external plugin packages and install records live under the mounted OpenClaw home
+- Bundled OpenClaw channel plugins, such as Discord when present in the image,
+  should normally load from the image-matched bundled copy. Avoid installing
+  pinned `@openclaw/*` channel packages into the mounted home unless you
+  deliberately want an external npm override.
+- No need to add API keys to `docker-compose.yml` or configure anything inside the container
+- Keys survive `clawdock-update`, `clawdock-rebuild`, and `clawdock-clean` because they live on the host
+
+The project `.env` feeds Docker Compose directly (gateway token, image name, ports). The `~/.openclaw/.env` feeds the OpenClaw process inside the container.
+
+### Example `~/.openclaw/.env`
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+TELEGRAM_BOT_TOKEN=123456:ABCDEF...
+```
+
+### Example `<project>/.env`
+
+```bash
+OPENCLAW_CONFIG_DIR=/Users/you/.openclaw
+OPENCLAW_WORKSPACE_DIR=/Users/you/.openclaw/workspace
+OPENCLAW_GATEWAY_PORT=18789
+OPENCLAW_BRIDGE_PORT=18790
+OPENCLAW_GATEWAY_BIND=lan
+OPENCLAW_GATEWAY_TOKEN=<generated-by-docker-setup>
+OPENCLAW_AUTH_PROFILE_SECRET_DIR=/Users/you/.openclaw-auth-profile-secrets
+OPENCLAW_IMAGE=openclaw:local
+```
+
+### Env Precedence
+
+OpenClaw loads env vars in this order (highest wins, never overrides existing):
+
+1. **Process environment** — `docker-compose.yml` `environment:` block (gateway token, session keys)
+2. **`.env` in CWD** — project root `.env` (Docker infra vars)
+3. **`~/.openclaw/.env`** — global secrets (API keys, bot tokens)
+4. **`openclaw.json` `env` block** — inline vars, applied only if still missing
+5. **Shell env import** — optional login-shell scrape (`OPENCLAW_LOAD_SHELL_ENV=1`)
+
+## Common Workflows
+
+### Update OpenClaw
+
+> **Important:** `openclaw update` does not work inside Docker.
+> The container runs as a non-root user with a source-built image, so `npm i -g` fails with EACCES.
+> Use `clawdock-update` instead — it pulls, rebuilds, and restarts from the host.
+
+```bash
+clawdock-update
+```
+
+This runs `git pull` → `docker compose build` → `docker compose down/up` in one step.
+
+If you only want to rebuild without pulling:
+
+```bash
+clawdock-rebuild && clawdock-stop && clawdock-start
+```
+
+### 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 (run `scripts/docker/setup.sh`)
+
+## Development
+
+**Test with fresh config (mimics first-time install):**
+
+```bash
+unset CLAWDOCK_DIR && rm -f ~/.clawdock/config && source scripts/clawdock/clawdock-helpers.sh
+```
+
+Then run any command to trigger auto-detect:
+
+```bash
+clawdock-start
+```

scripts/clawdock/clawdock-helpers.sh

@@ -0,0 +1,537 @@
+#!/usr/bin/env bash
+# ClawDock - Docker helpers for OpenClaw
+# Inspired by Simon Willison's "Running OpenClaw in Docker"
+# https://til.simonwillison.net/llms/openclaw-docker
+#
+# Installation:
+#   mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
+#   echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc
+#
+# Usage:
+#   clawdock-help    # Show all available commands
+
+# =============================================================================
+# 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'
+
+# Styled command output (green + bold)
+_clr_cmd() {
+  echo -e "${_CLR_GREEN}${_CLR_BOLD}$1${_CLR_RESET}"
+}
+
+# Inline command for use in sentences
+_cmd() {
+  echo "${_CLR_GREEN}${_CLR_BOLD}$1${_CLR_RESET}"
+}
+
+# =============================================================================
+# Config
+# =============================================================================
+CLAWDOCK_CONFIG="${HOME}/.clawdock/config"
+
+# 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"
+)
+
+_clawdock_filter_warnings() {
+  grep -v "^WARN\|^time="
+}
+
+_clawdock_trim_quotes() {
+  local value="$1"
+  value="${value#\"}"
+  value="${value%\"}"
+  printf "%s" "$value"
+}
+
+_clawdock_mask_value() {
+  local value="$1"
+  local length=${#value}
+  if (( length == 0 )); then
+    printf "%s" "<empty>"
+    return 0
+  fi
+  if (( length == 1 )); then
+    printf "%s" "<redacted:1 char>"
+    return 0
+  fi
+  printf "%s" "<redacted:${length} chars>"
+}
+
+_clawdock_browser_url_for_gateway_url() {
+  local url="$1"
+  case "$url" in
+    http://127.0.0.1:18789*|http://localhost:18789*|https://127.0.0.1:18789*|https://localhost:18789*) ;;
+    *)
+      printf "%s" "$url"
+      return 0
+      ;;
+  esac
+
+  local published published_port
+  published=$(_clawdock_compose port openclaw-gateway 18789 2>/dev/null | head -n 1 | tr -d '\r')
+  published_port="${published##*:}"
+  if [[ ! "$published_port" =~ ^[0-9]+$ ]]; then
+    printf "%s" "$url"
+    return 0
+  fi
+
+  printf "%s" "${url/:18789/:${published_port}}"
+}
+
+_clawdock_read_config_dir() {
+  if [[ ! -f "$CLAWDOCK_CONFIG" ]]; then
+    return 1
+  fi
+  local raw
+  raw=$(sed -n 's/^CLAWDOCK_DIR=//p' "$CLAWDOCK_CONFIG" | head -n 1)
+  if [[ -z "$raw" ]]; then
+    return 1
+  fi
+  _clawdock_trim_quotes "$raw"
+}
+
+# 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
+
+  # Try loading from config
+  local config_dir
+  config_dir=$(_clawdock_read_config_dir)
+  if [[ -n "$config_dir" && -f "${config_dir}/docker-compose.yml" ]]; then
+    CLAWDOCK_DIR="$config_dir"
+    return 0
+  fi
+
+  # 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 && ./scripts/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
+  echo "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
+  local compose_args=(-f "${CLAWDOCK_DIR}/docker-compose.yml")
+  if [[ -f "${CLAWDOCK_DIR}/docker-compose.override.yml" ]]; then
+    compose_args+=(-f "${CLAWDOCK_DIR}/docker-compose.override.yml")
+  fi
+  if [[ -f "${CLAWDOCK_DIR}/docker-compose.extra.yml" ]]; then
+    compose_args+=(-f "${CLAWDOCK_DIR}/docker-compose.extra.yml")
+  fi
+  command docker compose "${compose_args[@]}" "$@"
+}
+
+_clawdock_read_env_token() {
+  _clawdock_ensure_dir || return 1
+  if [[ ! -f "${CLAWDOCK_DIR}/.env" ]]; then
+    return 1
+  fi
+  local raw
+  raw=$(sed -n 's/^OPENCLAW_GATEWAY_TOKEN=//p' "${CLAWDOCK_DIR}/.env" | head -n 1)
+  if [[ -z "$raw" ]]; then
+    return 1
+  fi
+  _clawdock_trim_quotes "$raw"
+}
+
+# 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-show-config() {
+  _clawdock_ensure_dir >/dev/null 2>&1 || true
+  local config_dir="${HOME}/.openclaw"
+  echo -e "${_CLR_BOLD}Config directory:${_CLR_RESET} ${_CLR_CYAN}${config_dir}${_CLR_RESET}"
+  echo ""
+
+  # Show openclaw.json
+  if [[ -f "${config_dir}/openclaw.json" ]]; then
+    echo -e "${_CLR_BOLD}${config_dir}/openclaw.json${_CLR_RESET}"
+    echo -e "${_CLR_DIM}$(cat "${config_dir}/openclaw.json")${_CLR_RESET}"
+  else
+    echo -e "${_CLR_YELLOW}No openclaw.json found${_CLR_RESET}"
+  fi
+  echo ""
+
+  # Show .env (mask secret values)
+  if [[ -f "${config_dir}/.env" ]]; then
+    echo -e "${_CLR_BOLD}${config_dir}/.env${_CLR_RESET}"
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      if [[ "$line" =~ ^[[:space:]]*# ]] || [[ -z "$line" ]]; then
+        echo -e "${_CLR_DIM}${line}${_CLR_RESET}"
+      elif [[ "$line" == *=* ]]; then
+        local key="${line%%=*}"
+        local val="${line#*=}"
+        echo -e "${_CLR_CYAN}${key}${_CLR_RESET}=${_CLR_DIM}$(_clawdock_mask_value "$val")${_CLR_RESET}"
+      else
+        echo -e "${_CLR_DIM}${line}${_CLR_RESET}"
+      fi
+    done < "${config_dir}/.env"
+  else
+    echo -e "${_CLR_YELLOW}No .env found${_CLR_RESET}"
+  fi
+  echo ""
+
+  # Show project .env if available
+  if [[ -n "$CLAWDOCK_DIR" && -f "${CLAWDOCK_DIR}/.env" ]]; then
+    echo -e "${_CLR_BOLD}${CLAWDOCK_DIR}/.env${_CLR_RESET}"
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      if [[ "$line" =~ ^[[:space:]]*# ]] || [[ -z "$line" ]]; then
+        echo -e "${_CLR_DIM}${line}${_CLR_RESET}"
+      elif [[ "$line" == *=* ]]; then
+        local key="${line%%=*}"
+        local val="${line#*=}"
+        echo -e "${_CLR_CYAN}${key}${_CLR_RESET}=${_CLR_DIM}$(_clawdock_mask_value "$val")${_CLR_RESET}"
+      else
+        echo -e "${_CLR_DIM}${line}${_CLR_RESET}"
+      fi
+    done < "${CLAWDOCK_DIR}/.env"
+  fi
+  echo ""
+}
+
+clawdock-workspace() {
+  cd ~/.openclaw/workspace
+}
+
+# Container Access
+clawdock-shell() {
+  _clawdock_compose exec openclaw-gateway \
+    bash -c 'echo "alias openclaw=\"./openclaw.mjs\"" > /tmp/.bashrc_openclaw && bash --rcfile /tmp/.bashrc_openclaw'
+}
+
+clawdock-exec() {
+  _clawdock_compose exec openclaw-gateway "$@"
+}
+
+clawdock-cli() {
+  _clawdock_compose run --rm openclaw-cli "$@"
+}
+
+# Maintenance
+clawdock-update() {
+  _clawdock_ensure_dir || return 1
+
+  echo "🔄 Updating OpenClaw..."
+
+  echo ""
+  echo "📥 Pulling latest source..."
+  git -C "${CLAWDOCK_DIR}" pull || { echo "❌ git pull failed"; return 1; }
+
+  echo ""
+  echo "🔨 Rebuilding Docker image (this may take a few minutes)..."
+  _clawdock_compose build openclaw-gateway || { echo "❌ Build failed"; return 1; }
+
+  echo ""
+  echo "♻️  Recreating container with new image..."
+  _clawdock_compose down 2>&1 | _clawdock_filter_warnings
+  _clawdock_compose up -d openclaw-gateway 2>&1 | _clawdock_filter_warnings
+
+  echo ""
+  echo "⏳ Waiting for gateway to start..."
+  sleep 5
+
+  echo "✅ Update complete!"
+  echo -e "   Verify: $(_cmd clawdock-cli status)"
+}
+
+clawdock-rebuild() {
+  _clawdock_compose build openclaw-gateway
+}
+
+clawdock-clean() {
+  _clawdock_compose down -v --remove-orphans
+}
+
+# Health check
+clawdock-health() {
+  _clawdock_ensure_dir || return 1
+  local token
+  token=$(_clawdock_read_env_token)
+  if [[ -z "$token" ]]; then
+    echo "❌ Error: Could not find gateway token"
+    echo "   Check: ${CLAWDOCK_DIR}/.env"
+    return 1
+  fi
+  _clawdock_compose exec -e "OPENCLAW_GATEWAY_TOKEN=$token" openclaw-gateway \
+    node dist/index.js health
+}
+
+# Show gateway token
+clawdock-token() {
+  _clawdock_read_env_token
+}
+
+# Fix token configuration (run this once after setup)
+clawdock-fix-token() {
+  _clawdock_ensure_dir || return 1
+
+  echo "🔧 Configuring gateway token..."
+  local token
+  token=$(clawdock-token)
+  if [[ -z "$token" ]]; then
+    echo "❌ Error: Could not find gateway token"
+    echo "   Check: ${CLAWDOCK_DIR}/.env"
+    return 1
+  fi
+
+  echo "📝 Setting token: ${token:0:20}..."
+
+  _clawdock_compose exec -e "TOKEN=$token" openclaw-gateway \
+    bash -c './openclaw.mjs config set gateway.remote.token "$TOKEN" && ./openclaw.mjs config set gateway.auth.token "$TOKEN"' 2>&1 | _clawdock_filter_warnings
+
+  echo "🔍 Verifying token was saved..."
+  local saved_token
+  saved_token=$(_clawdock_compose exec openclaw-gateway \
+    bash -c "./openclaw.mjs config get gateway.remote.token 2>/dev/null" 2>&1 | _clawdock_filter_warnings | tr -d '\r\n' | head -c 64)
+
+  if [[ "$saved_token" == "$token" ]]; then
+    echo "✅ Token saved correctly!"
+  else
+    echo "⚠️  Token mismatch detected"
+    echo "   Expected: ${token:0:20}..."
+    echo "   Got: ${saved_token:0:20}..."
+  fi
+
+  echo "🔄 Restarting gateway..."
+  _clawdock_compose restart openclaw-gateway 2>&1 | _clawdock_filter_warnings
+
+  echo "⏳ Waiting for gateway to start..."
+  sleep 5
+
+  echo "✅ Configuration complete!"
+  echo -e "   Try: $(_cmd clawdock-devices)"
+}
+
+# Open dashboard in browser
+clawdock-dashboard() {
+  _clawdock_ensure_dir || return 1
+
+  echo "🦞 Getting dashboard URL..."
+  local output exit_status url
+  output=$(_clawdock_compose run --rm --no-deps openclaw-cli dashboard --no-open 2>&1)
+  exit_status=$?
+  url=$(printf "%s\n" "$output" | _clawdock_filter_warnings | grep -o 'http[s]\?://[^[:space:]]*' | head -n 1)
+  if [[ $exit_status -ne 0 ]]; then
+    echo "❌ Failed to get dashboard URL"
+    echo -e "   Try restarting: $(_cmd clawdock-restart)"
+    return 1
+  fi
+
+  if [[ -n "$url" ]]; then
+    url=$(_clawdock_browser_url_for_gateway_url "$url")
+    echo -e "✅ Opening: ${_CLR_CYAN}${url}${_CLR_RESET}"
+    open "$url" 2>/dev/null || xdg-open "$url" 2>/dev/null || echo -e "   Please open manually: ${_CLR_CYAN}${url}${_CLR_RESET}"
+    echo ""
+    echo -e "${_CLR_CYAN}💡 If you see ${_CLR_RED}'pairing required'${_CLR_CYAN} error:${_CLR_RESET}"
+    echo -e "   1. Run: $(_cmd clawdock-devices)"
+    echo "   2. Copy the Request ID from the Pending table"
+    echo -e "   3. Run: $(_cmd 'clawdock-approve <request-id>')"
+  else
+    echo "❌ Failed to get dashboard URL"
+    echo -e "   Try restarting: $(_cmd clawdock-restart)"
+  fi
+}
+
+# List device pairings
+clawdock-devices() {
+  _clawdock_ensure_dir || return 1
+
+  echo "🔍 Checking device pairings..."
+  local output exit_status
+  output=$(_clawdock_compose exec openclaw-gateway node dist/index.js devices list 2>&1)
+  exit_status=$?
+  printf "%s\n" "$output" | _clawdock_filter_warnings
+  if [ $exit_status -ne 0 ]; then
+    echo ""
+    echo -e "${_CLR_CYAN}💡 If you see token errors above:${_CLR_RESET}"
+    echo -e "   1. Verify token is set: $(_cmd clawdock-token)"
+    echo -e "   2. Try fixing the token automatically: $(_cmd clawdock-fix-token)"
+    echo "   3. If you still see errors, try manual config inside container:"
+    echo -e "      $(_cmd clawdock-shell)"
+    echo -e "      $(_cmd 'openclaw config get gateway.remote.token')"
+    return 1
+  fi
+
+  echo ""
+  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 -e "❌ Usage: $(_cmd 'clawdock-approve <request-id>')"
+    echo ""
+    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 -e "   3. Run: $(_cmd 'clawdock-approve <that-request-id>')"
+    echo ""
+    echo "Example:"
+    echo -e "   $(_cmd 'clawdock-approve 6f9db1bd-a1cc-4d3f-b643-2c195262464e')"
+    return 1
+  fi
+
+  echo "✅ Approving device: $1"
+  _clawdock_compose exec openclaw-gateway \
+    node dist/index.js devices approve "$1" 2>&1 | _clawdock_filter_warnings
+
+  echo ""
+  echo "✅ Device approved! Refresh your browser."
+}
+
+# Show all available clawdock helper commands
+clawdock-help() {
+  echo -e "\n${_CLR_BOLD}${_CLR_CYAN}🦞 ClawDock - Docker Helpers for OpenClaw${_CLR_RESET}\n"
+
+  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 "${_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 "${_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 "${_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 "${_CLR_BOLD}${_CLR_MAGENTA}🔧 Maintenance${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-update)      ${_CLR_DIM}Pull, rebuild, and restart ${_CLR_CYAN}(one-command update)${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-rebuild)     ${_CLR_DIM}Rebuild Docker image only${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-clean)       ${_CLR_RED}⚠️  Remove containers & volumes (nuclear)${_CLR_RESET}"
+  echo ""
+
+  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-show-config) ${_CLR_DIM}Print config files with redacted values${_CLR_RESET}"
+  echo -e "  $(_cmd clawdock-workspace)   ${_CLR_DIM}Open workspace directory${_CLR_RESET}"
+  echo ""
+
+  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 "${_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 "${_CLR_BOLD}${_CLR_CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${_CLR_RESET}"
+  echo ""
+
+  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 ""
+}