github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-19 03:37:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: document secrets refs runtime and migration

Browse Source
This commit is contained in:
joshavant
2026-02-24 16:26:51 -06:00
committed by Peter Steinberger
parent cb119874dc
commit c0a3801086
19 changed files with 187 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/help/environment.md
View File

@@ -74,6 +74,15 @@ You can reference env vars directly in config string values using `${VAR_NAME}`
See [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details.
## Secret refs vs `${ENV}` strings
OpenClaw supports two env-driven patterns:
- `${VAR}` string substitution in config values.
- SecretRef objects (`{ source: "env", id: "VAR" }`) for fields that support secrets references.
Both resolve from process env at activation time. SecretRef details are documented in [Secrets Management](/gateway/secrets).
## Path-related env vars
| Variable | Purpose |

24
docs/help/faq.md
View File

@@ -1291,16 +1291,18 @@ Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory
Everything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`):
| Path | Purpose |
| --------------------------------------------------------------- | ------------------------------------------------------------ |
| `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) |
| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json` | Session metadata (per agent) |
| Path | Purpose |
| --------------------------------------------------------------- | ----------------------------------------------------------------- |
| `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) |
| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth, API keys, and optional `keyRef`/`tokenRef`) |
| `$OPENCLAW_STATE_DIR/secrets.enc.json` | Optional encrypted file-backed secret payload (`sops`) |
| `$OPENCLAW_STATE_DIR/backups/secrets-migrate/` | Optional migration rollback backups + manifests |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) |
| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json` | Session metadata (per agent) |
Legacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`).
@@ -1338,7 +1340,7 @@ Put your **agent workspace** in a **private** git repo and back it up somewhere
private (for example GitHub private). This captures memory + AGENTS/SOUL/USER
files, and lets you restore the assistant's "mind" later.
Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens).
Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens, encrypted secrets payloads, or migration backups).
If you need a full restore, back up both the workspace and the state directory
separately (see the migration question above).