From c025291df7c4fdf9a6c39c696d4b2de10f053ee6 Mon Sep 17 00:00:00 2001 From: Ayaan Zaidi Date: Tue, 12 May 2026 16:15:20 +0530 Subject: [PATCH] docs(docker): document auth profile key mount --- .env.example | 3 +++ docs/install/docker-vm-runtime.md | 1 + docs/install/docker.md | 19 ++++++++++++------- scripts/clawdock/README.md | 14 +++++++++----- 4 files changed, 25 insertions(+), 12 deletions(-) diff --git a/.env.example b/.env.example index a643b98ddf9..7c400c907e0 100644 --- a/.env.example +++ b/.env.example @@ -28,6 +28,9 @@ OPENCLAW_GATEWAY_TOKEN= # OPENCLAW_STATE_DIR=~/.openclaw # OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json # OPENCLAW_HOME=~ +# Docker setup stores auth profile encryption key material outside the mounted +# OpenClaw state dir and mounts this host directory into the container. +# OPENCLAW_AUTH_PROFILE_SECRET_DIR=/absolute/path/to/.openclaw-auth-profile-secrets # Allowlist of extra directories that `$include` directives in openclaw.json may # resolve files from. Path-list separated (':' on POSIX, ';' on Windows). Each diff --git a/docs/install/docker-vm-runtime.md b/docs/install/docker-vm-runtime.md index 43e1bc2ac07..b2be276049f 100644 --- a/docs/install/docker-vm-runtime.md +++ b/docs/install/docker-vm-runtime.md @@ -126,6 +126,7 @@ All long-lived state must survive restarts, rebuilds, and reboots. | ------------------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------- | | Gateway config | `/home/node/.openclaw/` | Host volume mount | Includes `openclaw.json`, `.env` | | Model auth profiles | `/home/node/.openclaw/agents/` | Host volume mount | `agents//agent/auth-profiles.json` (OAuth, API keys) | +| Auth profile key | `/home/node/.config/openclaw/` | Host volume mount | Local encryption key for OAuth auth profile token material | | Skill configs | `/home/node/.openclaw/skills/` | Host volume mount | Skill-level state | | Agent workspace | `/home/node/.openclaw/workspace/` | Host volume mount | Code and agent artifacts | | WhatsApp session | `/home/node/.openclaw/` | Host volume mount | Preserves QR login | diff --git a/docs/install/docker.md b/docs/install/docker.md index 7c4fe539b1a..a613cc7087b 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -51,6 +51,7 @@ Docker is **optional**. Use it only if you want a containerized gateway or to va - prompt for provider API keys - generate a gateway token and write it to `.env` + - create the auth-profile secret key directory - start the gateway via Docker Compose During setup, pre-start onboarding and config writes run through @@ -257,13 +258,13 @@ For gotchas and troubleshooting, see [Bonjour discovery](/gateway/bonjour). ### Storage and persistence -Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw` and -`OPENCLAW_WORKSPACE_DIR` to `/home/node/.openclaw/workspace`, so those paths -survive container replacement. When either variable is unset, the bundled -`docker-compose.yml` falls back to `${HOME}/.openclaw` (and -`${HOME}/.openclaw/workspace` for the workspace mount), or `/tmp/.openclaw` -when `HOME` itself is also missing. That keeps `docker compose up` from -emitting an empty-source volume spec on bare environments. +Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw`, +`OPENCLAW_WORKSPACE_DIR` to `/home/node/.openclaw/workspace`, and +`OPENCLAW_AUTH_PROFILE_SECRET_DIR` to `/home/node/.config/openclaw`, so those +paths survive container replacement. When any variable is unset, the bundled +`docker-compose.yml` falls back under `${HOME}`, or `/tmp` when `HOME` itself is +also missing. That keeps `docker compose up` from emitting an empty-source +volume spec on bare environments. That mounted config directory is where OpenClaw keeps: @@ -271,6 +272,10 @@ That mounted config directory is where OpenClaw keeps: - `agents//agent/auth-profiles.json` for stored provider OAuth/API-key auth - `.env` for env-backed runtime secrets such as `OPENCLAW_GATEWAY_TOKEN` +The auth-profile secret key directory stores the local encryption key used for +OAuth-backed auth profile token material. Keep it with your Docker host state, +but separate from `OPENCLAW_CONFIG_DIR`. + Installed downloadable plugins store their package state under the mounted OpenClaw home, so plugin install records and package roots survive container replacement. Gateway startup does not generate bundled-plugin dependency trees. diff --git a/scripts/clawdock/README.md b/scripts/clawdock/README.md index a09c6a503d0..db77621e784 100644 --- a/scripts/clawdock/README.md +++ b/scripts/clawdock/README.md @@ -151,11 +151,11 @@ The Docker setup uses three config files on the host. The container never stores ### 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 | +| File | Purpose | Examples | +| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `/.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. @@ -165,6 +165,7 @@ The Docker setup uses three config files on the host. The container never stores - Builds the `openclaw:local` image from `Dockerfile` - Creates `/.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 @@ -192,12 +193,14 @@ The `Dockerfile` supports two optional build args: 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 plugin packages and install records live under the mounted OpenClaw home - 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 @@ -221,6 +224,7 @@ OPENCLAW_GATEWAY_PORT=18789 OPENCLAW_BRIDGE_PORT=18790 OPENCLAW_GATEWAY_BIND=lan OPENCLAW_GATEWAY_TOKEN= +OPENCLAW_AUTH_PROFILE_SECRET_DIR=/Users/you/.openclaw-auth-profile-secrets OPENCLAW_IMAGE=openclaw:local ```