docs: refresh backup and migration storage refs

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

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/<agentId>/agent/auth-profiles.json` (model auth profiles: OAuth + API keys)
+- `~/.openclaw/credentials/` (channel/provider state plus legacy OAuth import data)
 - `~/.openclaw/agents/<agentId>/sessions/` (session transcripts + metadata)
 - `~/.openclaw/skills/` (managed skills)
 

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:

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-<profile>/` or a path set via `OPENCLAW_STATE_D
   </Accordion>
 
   <Accordion title="Copying only openclaw.json">
-    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/<agentId>/agent/auth-profiles.json`, and channel/provider state still
+    lives under `credentials/`. Always migrate the **entire** state directory.
   </Accordion>
 
   <Accordion title="Permissions and ownership">
@@ -95,7 +96,8 @@ Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_D
   </Accordion>
 
   <Accordion title="Secrets in backups">
-    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.
   </Accordion>
 </AccordionGroup>

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/<agentId>/agent/auth-profiles.json`
   - Sessions: `~/.openclaw/agents/<agentId>/sessions/`
   - Logs: `/tmp/openclaw/`