Public-Mirror/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-13 10:59:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 20

docs(docker): document auth profile key mount

Browse source
This commit is contained in:
Ayaan Zaidi 2026-05-12 16:15:20 +05:30
parent c3e3146639
commit c025291df7
4 changed files with 25 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.env.example
View file

@ -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

1
docs/install/docker-vm-runtime.md
View file

@ -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 |

19
docs/install/docker.md
View file

@ -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/<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.

14
scripts/clawdock/README.md
View file

@ -151,11 +151,11 @@ The Docker setup uses three config files on the host. The container never stores
### Config Files
| File | Purpose | Examples |
| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| `<project>/.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 |
| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `<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.
@ -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
```