diff --git a/CHANGELOG.md b/CHANGELOG.md index a6e77708a66..f16cd1b70ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -222,6 +222,7 @@ Docs: https://docs.openclaw.ai - CLI/status: detect node-only hosts in `openclaw status` and `openclaw status --all`, show the configured remote gateway target instead of a false local `ECONNREFUSED`, and suppress contradictory local-gateway diagnosis output. - Gateway/SQLite transient handling: keep unhandled `SQLITE_CANTOPEN`, `SQLITE_BUSY`, `SQLITE_LOCKED`, and `SQLITE_IOERR` failures non-fatal in the global rejection handler so macOS LaunchAgent restarts do not enter a crash-throttle loop. (#57018) - Control UI/gateway: reconnect the browser client when gateway event sequence gaps are detected, so stale non-chat state recovers automatically instead of only telling the user to refresh. (#23912) thanks @Olshansk. +- ClawDock/docs: move the helper scripts to `scripts/clawdock`, publish ClawDock as a first-class docs page on the docs site, and document reinstalling local helper copies from the new raw GitHub path. (#23912) thanks @Olshansk. ## 2026.3.24 diff --git a/docs/docs.json b/docs/docs.json index aa4f160cc3e..8d3edb416ab 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -924,6 +924,7 @@ "pages": [ "install/ansible", "install/bun", + "install/clawdock", "install/docker", "install/nix", "install/podman" diff --git a/docs/install/clawdock.md b/docs/install/clawdock.md new file mode 100644 index 00000000000..10bed182f11 --- /dev/null +++ b/docs/install/clawdock.md @@ -0,0 +1,105 @@ +--- +summary: "ClawDock shell helpers for Docker-based OpenClaw installs" +read_when: + - You run OpenClaw with Docker often and want shorter day-to-day commands + - You want a helper layer for dashboard, logs, token setup, and pairing flows +title: "ClawDock" +--- + +# ClawDock + +ClawDock is a small shell-helper layer for Docker-based OpenClaw installs. + +It gives you short commands like `clawdock-start`, `clawdock-dashboard`, and `clawdock-fix-token` instead of longer `docker compose ...` invocations. + +If you have not set up Docker yet, start with [Docker](/install/docker). + +## Install + +Use the canonical helper path: + +```bash +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 && source ~/.zshrc +``` + +If you previously installed ClawDock from `scripts/shell-helpers/clawdock-helpers.sh`, reinstall from the new `scripts/clawdock/clawdock-helpers.sh` path. The old raw GitHub path was removed. + +## What you get + +### 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` | Follow gateway logs | + +### Container access + +| Command | Description | +| ------------------------- | --------------------------------------------- | +| `clawdock-shell` | Open a shell inside the gateway container | +| `clawdock-cli ` | Run OpenClaw CLI commands in Docker | +| `clawdock-exec ` | Execute an arbitrary command in the container | + +### Web UI and pairing + +| Command | Description | +| ----------------------- | ---------------------------- | +| `clawdock-dashboard` | Open the Control UI URL | +| `clawdock-devices` | List pending device pairings | +| `clawdock-approve ` | Approve a pairing request | + +### Setup and maintenance + +| Command | Description | +| -------------------- | ------------------------------------------------ | +| `clawdock-fix-token` | Configure the gateway token inside the container | +| `clawdock-update` | Pull, rebuild, and restart | +| `clawdock-rebuild` | Rebuild the Docker image only | +| `clawdock-clean` | Remove containers and volumes | + +### Utilities + +| Command | Description | +| ---------------------- | --------------------------------------- | +| `clawdock-health` | Run a gateway health check | +| `clawdock-token` | Print the gateway token | +| `clawdock-cd` | Jump to the OpenClaw project directory | +| `clawdock-config` | Open `~/.openclaw` | +| `clawdock-show-config` | Print config files with redacted values | +| `clawdock-workspace` | Open the workspace directory | + +## First-time flow + +```bash +clawdock-start +clawdock-fix-token +clawdock-dashboard +``` + +If the browser says pairing is required: + +```bash +clawdock-devices +clawdock-approve +``` + +## Config and secrets + +ClawDock works with the same Docker config split described in [Docker](/install/docker): + +- `/.env` for Docker-specific values like image name, ports, and the gateway token +- `~/.openclaw/.env` for provider keys and bot tokens +- `~/.openclaw/openclaw.json` for behavior config + +Use `clawdock-show-config` when you want to inspect those files quickly. It redacts `.env` values in its printed output. + +## Related pages + +- [Docker](/install/docker) +- [Docker VM Runtime](/install/docker-vm-runtime) +- [Updating](/install/updating) diff --git a/docs/install/docker.md b/docs/install/docker.md index 0aea7350ce4..fc7f0bde144 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -187,13 +187,15 @@ and rolling file logs under `/tmp/openclaw/`. For easier day-to-day Docker management, install `ClawDock`: ```bash -mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh +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 && source ~/.zshrc ``` +If you installed ClawDock from the older `scripts/shell-helpers/clawdock-helpers.sh` raw path, rerun the install command above so your local helper file tracks the new location. + Then use `clawdock-start`, `clawdock-stop`, `clawdock-dashboard`, etc. Run `clawdock-help` for all commands. -See the [`ClawDock` Helper README](https://github.com/openclaw/openclaw/blob/main/scripts/shell-helpers/README.md). +See [ClawDock](/install/clawdock) for the full helper guide. diff --git a/scripts/clawdock/README.md b/scripts/clawdock/README.md new file mode 100644 index 00000000000..67430a24690 --- /dev/null +++ b/scripts/clawdock/README.md @@ -0,0 +1,355 @@ +# ClawDock + +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 +``` + +## 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 ` | Run OpenClaw CLI commands | +| `clawdock-exec ` | 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 ` | 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-setup.sh` | First-time setup — builds image, creates `.env` from `.env.example` | +| `.env.example` | Template for `/.env` with all supported vars and docs | +| `docker-compose.extra.yml` | Optional overrides — auto-loaded by ClawDock helpers if present | + +### Config Files + +| File | Purpose | Examples | +| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- | +| `/.env` | **Docker infra** — image, ports, gateway token | `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_IMAGE`, `OPENCLAW_GATEWAY_PORT` | +| `~/.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 + +`./docker-setup.sh` (in the project root) handles first-time Docker configuration: + +- Builds the `openclaw:local` image from `Dockerfile` +- Creates `/.env` from `.env.example` with a generated gateway token +- Sets up `~/.openclaw` directories if they don't exist + +```bash +./docker-setup.sh +``` + +After setup, add your API keys: + +```bash +vim ~/.openclaw/.env +``` + +See `.env.example` for all supported keys. + +The `Dockerfile` supports two optional build args: + +- `OPENCLAW_DOCKER_APT_PACKAGES` — extra apt packages to install (e.g. `ffmpeg`) +- `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 +``` + +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 +- 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 `/.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= +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 +``` + +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 +``` diff --git a/scripts/shell-helpers/clawdock-helpers.sh b/scripts/clawdock/clawdock-helpers.sh similarity index 78% rename from scripts/shell-helpers/clawdock-helpers.sh rename to scripts/clawdock/clawdock-helpers.sh index 6351aa97f0c..31d77d3139b 100755 --- a/scripts/shell-helpers/clawdock-helpers.sh +++ b/scripts/clawdock/clawdock-helpers.sh @@ -4,7 +4,7 @@ # https://til.simonwillison.net/llms/openclaw-docker # # Installation: -# mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh +# 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: @@ -59,6 +59,20 @@ _clawdock_trim_quotes() { printf "%s" "$value" } +_clawdock_mask_value() { + local value="$1" + local length=${#value} + if (( length == 0 )); then + printf "%s" "" + return 0 + fi + if (( length == 1 )); then + printf "%s" "" + return 0 + fi + printf "%s" "" +} + _clawdock_read_config_dir() { if [[ ! -f "$CLAWDOCK_CONFIG" ]]; then return 1 @@ -187,6 +201,58 @@ 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 } @@ -206,6 +272,32 @@ clawdock-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 } @@ -290,10 +382,10 @@ clawdock-dashboard() { fi if [[ -n "$url" ]]; then - echo "✅ Opening: $url" - open "$url" 2>/dev/null || xdg-open "$url" 2>/dev/null || echo " Please open manually: $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 'pairing required' error:${_CLR_RESET}" + 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 ')" @@ -316,7 +408,8 @@ clawdock-devices() { echo "" 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 -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 @@ -381,7 +474,8 @@ clawdock-help() { echo "" 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-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 "" @@ -390,6 +484,7 @@ clawdock-help() { 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 "" diff --git a/scripts/shell-helpers/README.md b/scripts/shell-helpers/README.md deleted file mode 100644 index b789048a975..00000000000 --- a/scripts/shell-helpers/README.md +++ /dev/null @@ -1,226 +0,0 @@ -# ClawDock - -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 -``` - -## 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 ` | Run OpenClaw CLI commands | -| `clawdock-exec ` | 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 ` | 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 -``` - -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/shell-helpers/clawdock-helpers.sh -``` - -Then run any command to trigger auto-detect: - -```bash -clawdock-start -```