diff --git a/docs/cli/backup.md b/docs/cli/backup.md index a39b0fefac6..6cfa9294703 100644 --- a/docs/cli/backup.md +++ b/docs/cli/backup.md @@ -8,7 +8,7 @@ title: "backup" # `openclaw backup` -Create a local backup archive for OpenClaw state, config, credentials, sessions, and optionally workspaces. +Create a local backup archive for OpenClaw state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces. ```bash openclaw backup create @@ -37,12 +37,19 @@ openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz - The state directory returned by OpenClaw's local state resolver, usually `~/.openclaw` - The active config file path -- The OAuth / credentials directory +- The resolved `credentials/` directory when it exists outside the state directory - Workspace directories discovered from the current config, unless you pass `--no-include-workspace` -If you use `--only-config`, OpenClaw skips state, credentials, and workspace discovery and archives only the active config file path. +Model auth profiles are already part of the state directory under +`agents//agent/auth-profiles.json`, so they are normally covered by the +state backup entry. -OpenClaw canonicalizes paths before building the archive. If config, credentials, or a workspace already live inside the state directory, they are not duplicated as separate top-level backup sources. Missing paths are skipped. +If you use `--only-config`, OpenClaw skips state, credentials-directory, and workspace discovery and archives only the active config file path. + +OpenClaw canonicalizes paths before building the archive. If config, the +credentials directory, or a workspace already live inside the state directory, +they are not duplicated as separate top-level backup sources. Missing paths are +skipped. The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset. @@ -56,7 +63,8 @@ If you still want a partial backup in that situation, rerun: openclaw backup create --no-include-workspace ``` -That keeps state, config, and credentials in scope while skipping workspace discovery entirely. +That keeps state, config, and the external credentials directory in scope while +skipping workspace discovery entirely. If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery. diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md index f8f6b9e4562..82c18626fa9 100644 --- a/docs/concepts/agent-workspace.md +++ b/docs/concepts/agent-workspace.md @@ -130,7 +130,8 @@ files. These live under `~/.openclaw/` and should NOT be committed to the workspace repo: - `~/.openclaw/openclaw.json` (config) -- `~/.openclaw/credentials/` (OAuth tokens, API keys) +- `~/.openclaw/agents//agent/auth-profiles.json` (model auth profiles: OAuth + API keys) +- `~/.openclaw/credentials/` (channel/provider state plus legacy OAuth import data) - `~/.openclaw/agents//sessions/` (session transcripts + metadata) - `~/.openclaw/skills/` (managed skills) diff --git a/docs/help/faq.md b/docs/help/faq.md index 35f37a29372..fb2b1a4d2a2 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1266,7 +1266,7 @@ for usage/billing and raise limits as needed. - **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md` (or legacy fallback `memory.md` when `MEMORY.md` is absent), `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`. - - **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs, + - **State dir (`~/.openclaw`)**: config, channel/provider state, auth profiles, sessions, logs, and shared skills (`~/.openclaw/skills`). Default workspace is `~/.openclaw/workspace`, configurable via: diff --git a/docs/install/migrating.md b/docs/install/migrating.md index 6656c97b339..f5a8408c34f 100644 --- a/docs/install/migrating.md +++ b/docs/install/migrating.md @@ -15,7 +15,7 @@ This guide moves an OpenClaw gateway to a new machine without redoing onboarding When you copy the **state directory** (`~/.openclaw/` by default) and your **workspace**, you preserve: - **Config** -- `openclaw.json` and all gateway settings -- **Auth** -- API keys, OAuth tokens, credential profiles +- **Auth** -- per-agent `auth-profiles.json` (API keys + OAuth), plus any channel/provider state under `credentials/` - **Sessions** -- conversation history and agent state - **Channel state** -- WhatsApp login, Telegram session, etc. - **Workspace files** -- `MEMORY.md`, `USER.md`, skills, and prompts @@ -80,8 +80,9 @@ Custom profiles use `~/.openclaw-/` or a path set via `OPENCLAW_STATE_D - The config file alone is not enough. Credentials live under `credentials/`, and agent - state lives under `agents/`. Always migrate the **entire** state directory. + The config file alone is not enough. Model auth profiles live under + `agents//agent/auth-profiles.json`, and channel/provider state still + lives under `credentials/`. Always migrate the **entire** state directory. @@ -95,7 +96,8 @@ Custom profiles use `~/.openclaw-/` or a path set via `OPENCLAW_STATE_D - The state directory contains API keys, OAuth tokens, and channel credentials. + The state directory contains auth profiles, channel credentials, and other + provider state. Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure. diff --git a/docs/start/setup.md b/docs/start/setup.md index 98e3d875178..b9af09b4aaf 100644 --- a/docs/start/setup.md +++ b/docs/start/setup.md @@ -117,7 +117,8 @@ openclaw health - **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port. - **Where state lives:** - - Credentials: `~/.openclaw/credentials/` + - Channel/provider state: `~/.openclaw/credentials/` + - Model auth profiles: `~/.openclaw/agents//agent/auth-profiles.json` - Sessions: `~/.openclaw/agents//sessions/` - Logs: `/tmp/openclaw/`