docs(docker): document auth profile key mount

.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

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/<agentId>/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                                            |

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
+Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw`,
-`OPENCLAW_WORKSPACE_DIR` to `/home/node/.openclaw/workspace`, so those paths
+`OPENCLAW_WORKSPACE_DIR` to `/home/node/.openclaw/workspace`, and
-survive container replacement. When either variable is unset, the bundled
+`OPENCLAW_AUTH_PROFILE_SECRET_DIR` to `/home/node/.config/openclaw`, so those
-`docker-compose.yml` falls back to `${HOME}/.openclaw` (and
+paths survive container replacement. When any variable is unset, the bundled
-`${HOME}/.openclaw/workspace` for the workspace mount), or `/tmp/.openclaw`
+`docker-compose.yml` falls back under `${HOME}`, or `/tmp` when `HOME` itself is
-when `HOME` itself is also missing. That keeps `docker compose up` from
+also missing. That keeps `docker compose up` from emitting an empty-source
-emitting an empty-source volume spec on bare environments.
+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/<agentId>/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.

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                                                            |
+| File                        | Purpose                                          | Examples                                                                                                |
-| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
+| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `<project>/.env`            | **Docker infra** — image, ports, gateway token   | `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_IMAGE`, `OPENCLAW_GATEWAY_PORT` |
+| `<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/.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                |
+| `~/.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 `<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
@@ -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=<generated-by-docker-setup>
+OPENCLAW_AUTH_PROFILE_SECRET_DIR=/Users/you/.openclaw-auth-profile-secrets
 OPENCLAW_IMAGE=openclaw:local
 ```