Skip to content

Commit 5adc438

Browse files
obviyusobviyus
committed
docs(docker): document auth profile key mount
1 parent e68b943 commit 5adc438

4 files changed

Lines changed: 25 additions & 12 deletions

File tree

‎.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@ OPENCLAW_GATEWAY_TOKEN=
2828
# OPENCLAW_STATE_DIR=~/.openclaw
2929
# OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
3030
# OPENCLAW_HOME=~
31+
# Docker setup stores auth profile encryption key material outside the mounted
32+
# OpenClaw state dir and mounts this host directory into the container.
33+
# OPENCLAW_AUTH_PROFILE_SECRET_DIR=/absolute/path/to/.openclaw-auth-profile-secrets
3134

3235
# Allowlist of extra directories that `$include` directives in openclaw.json may
3336
# resolve files from. Path-list separated (':' on POSIX, ';' on Windows). Each

‎docs/install/docker-vm-runtime.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ All long-lived state must survive restarts, rebuilds, and reboots.
126126
| ------------------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------- |
127127
| Gateway config | `/home/node/.openclaw/` | Host volume mount | Includes `openclaw.json`, `.env` |
128128
| Model auth profiles | `/home/node/.openclaw/agents/` | Host volume mount | `agents/<agentId>/agent/auth-profiles.json` (OAuth, API keys) |
129+
| Auth profile key | `/home/node/.config/openclaw/` | Host volume mount | Local encryption key for OAuth auth profile token material |
129130
| Skill configs | `/home/node/.openclaw/skills/` | Host volume mount | Skill-level state |
130131
| Agent workspace | `/home/node/.openclaw/workspace/` | Host volume mount | Code and agent artifacts |
131132
| WhatsApp session | `/home/node/.openclaw/` | Host volume mount | Preserves QR login |

‎docs/install/docker.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Docker is **optional**. Use it only if you want a containerized gateway or to va
5151

5252
- prompt for provider API keys
5353
- generate a gateway token and write it to `.env`
54+
- create the auth-profile secret key directory
5455
- start the gateway via Docker Compose
5556

5657
During setup, pre-start onboarding and config writes run through
@@ -257,20 +258,24 @@ For gotchas and troubleshooting, see [Bonjour discovery](/gateway/bonjour).
257258

258259
### Storage and persistence
259260

260-
Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw` and
261-
`OPENCLAW_WORKSPACE_DIR` to `/home/node/.openclaw/workspace`, so those paths
262-
survive container replacement. When either variable is unset, the bundled
263-
`docker-compose.yml` falls back to `${HOME}/.openclaw` (and
264-
`${HOME}/.openclaw/workspace` for the workspace mount), or `/tmp/.openclaw`
265-
when `HOME` itself is also missing. That keeps `docker compose up` from
266-
emitting an empty-source volume spec on bare environments.
261+
Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw`,
262+
`OPENCLAW_WORKSPACE_DIR` to `/home/node/.openclaw/workspace`, and
263+
`OPENCLAW_AUTH_PROFILE_SECRET_DIR` to `/home/node/.config/openclaw`, so those
264+
paths survive container replacement. When any variable is unset, the bundled
265+
`docker-compose.yml` falls back under `${HOME}`, or `/tmp` when `HOME` itself is
266+
also missing. That keeps `docker compose up` from emitting an empty-source
267+
volume spec on bare environments.
267268

268269
That mounted config directory is where OpenClaw keeps:
269270

270271
- `openclaw.json` for behavior config
271272
- `agents/<agentId>/agent/auth-profiles.json` for stored provider OAuth/API-key auth
272273
- `.env` for env-backed runtime secrets such as `OPENCLAW_GATEWAY_TOKEN`
273274

275+
The auth-profile secret key directory stores the local encryption key used for
276+
OAuth-backed auth profile token material. Keep it with your Docker host state,
277+
but separate from `OPENCLAW_CONFIG_DIR`.
278+
274279
Installed downloadable plugins store their package state under the mounted
275280
OpenClaw home, so plugin install records and package roots survive container
276281
replacement. Gateway startup does not generate bundled-plugin dependency trees.

‎scripts/clawdock/README.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -151,11 +151,11 @@ The Docker setup uses three config files on the host. The container never stores
151151

152152
### Config Files
153153

154-
| File | Purpose | Examples |
155-
| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
156-
| `<project>/.env` | **Docker infra** — image, ports, gateway token | `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_IMAGE`, `OPENCLAW_GATEWAY_PORT` |
157-
| `~/.openclaw/.env` | **Secrets** — API keys and bot tokens | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TELEGRAM_BOT_TOKEN` |
158-
| `~/.openclaw/openclaw.json` | **Behavior config** — models, channels, policies | Model selection, WhatsApp allowlists, agent settings |
154+
| File | Purpose | Examples |
155+
| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
156+
| `<project>/.env` | **Docker infra** — image, ports, gateway token | `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_IMAGE`, `OPENCLAW_GATEWAY_PORT`, `OPENCLAW_AUTH_PROFILE_SECRET_DIR` |
157+
| `~/.openclaw/.env` | **Secrets** — API keys and bot tokens | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TELEGRAM_BOT_TOKEN` |
158+
| `~/.openclaw/openclaw.json` | **Behavior config** — models, channels, policies | Model selection, WhatsApp allowlists, agent settings |
159159

160160
**Do NOT** put API keys or bot tokens in `openclaw.json`. Use `~/.openclaw/.env` for all secrets.
161161

@@ -165,6 +165,7 @@ The Docker setup uses three config files on the host. The container never stores
165165

166166
- Builds the `openclaw:local` image from `Dockerfile`
167167
- Creates `<project>/.env` from `.env.example` with a generated gateway token
168+
- Creates the auth-profile secret key directory
168169
- Sets up `~/.openclaw` directories if they don't exist
169170

170171
```bash
@@ -192,12 +193,14 @@ The `Dockerfile` supports two optional build args:
192193
volumes:
193194
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
194195
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
196+
- ${OPENCLAW_AUTH_PROFILE_SECRET_DIR}:/home/node/.config/openclaw
195197
```
196198
197199
This means:
198200
199201
- `~/.openclaw/.env` is available inside the container at `/home/node/.openclaw/.env` — OpenClaw loads it automatically as the global env fallback
200202
- `~/.openclaw/openclaw.json` is available at `/home/node/.openclaw/openclaw.json` — the gateway watches it and hot-reloads most changes
203+
- `~/.openclaw-auth-profile-secrets` is available at `/home/node/.config/openclaw` — OpenClaw stores the auth-profile encryption key there
201204
- Downloadable plugin packages and install records live under the mounted OpenClaw home
202205
- No need to add API keys to `docker-compose.yml` or configure anything inside the container
203206
- Keys survive `clawdock-update`, `clawdock-rebuild`, and `clawdock-clean` because they live on the host
@@ -221,6 +224,7 @@ OPENCLAW_GATEWAY_PORT=18789
221224
OPENCLAW_BRIDGE_PORT=18790
222225
OPENCLAW_GATEWAY_BIND=lan
223226
OPENCLAW_GATEWAY_TOKEN=<generated-by-docker-setup>
227+
OPENCLAW_AUTH_PROFILE_SECRET_DIR=/Users/you/.openclaw-auth-profile-secrets
224228
OPENCLAW_IMAGE=openclaw:local
225229
```
226230

0 commit comments

Comments
 (0)