From f0ea46877689b106591d5ebf938c94056ade3caa Mon Sep 17 00:00:00 2001
From: "openclaw-docs-sync[bot]"
 <openclaw-docs-sync[bot]@users.noreply.github.com>
Date: Tue, 28 Apr 2026 05:56:30 +0000
Subject: [PATCH] chore(sync): mirror docs from
 openclaw/openclaw@b5371bfd636d5b6f00e857af2fbf644944199a2f

---
 .openclaw-sync/source.json              |  4 ++--
 docs/gateway/authentication.md          | 17 +++++++++++++++++
 docs/gateway/configuration-reference.md |  1 +
 docs/providers/ollama.md                |  3 +++
 4 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 30f28e173..bce252abf 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "439771732240be06bd3b4aa8accf735e84ddbc85",
-  "syncedAt": "2026-04-28T05:51:55.430Z"
+  "sha": "b5371bfd636d5b6f00e857af2fbf644944199a2f",
+  "syncedAt": "2026-04-28T05:54:57.449Z"
 }
diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md
index dac0dd0dd..25c725b1b 100644
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@@ -93,6 +93,23 @@ Manual token entry (any provider; writes `auth-profiles.json` + updates config):
 openclaw models auth paste-token --provider openrouter
 ```
 
+`auth-profiles.json` stores credentials only. The canonical shape is:
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "openrouter:default": {
+      "type": "api_key",
+      "provider": "openrouter",
+      "key": "OPENROUTER_API_KEY"
+    }
+  }
+}
+```
+
+OpenClaw expects the canonical `version` + `profiles` shape at runtime. If an older install still has a flat file such as `{ "openrouter": { "apiKey": "..." } }`, run `openclaw doctor --fix` to rewrite it as an `openrouter:default` API-key profile; doctor keeps a `.legacy-flat.*.bak` copy beside the original. Endpoint details such as `baseUrl`, `api`, model ids, headers, and timeouts belong under `models.providers.<id>` in `openclaw.json` or `models.json`, not in `auth-profiles.json`.
+
 Auth profile refs are also supported for static credentials:
 
 - `api_key` credentials can use `keyRef: { source, provider, id }`
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index ded910bb3..e0a0269ea 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -800,6 +800,7 @@ Notes:
 
 - Per-agent profiles are stored at `<agentDir>/auth-profiles.json`.
 - `auth-profiles.json` supports value-level refs (`keyRef` for `api_key`, `tokenRef` for `token`) for static credential modes.
+- Legacy flat `auth-profiles.json` maps such as `{ "provider": { "apiKey": "..." } }` are not a runtime format; `openclaw doctor --fix` rewrites them to canonical `provider:default` API-key profiles with a `.legacy-flat.*.bak` backup.
 - OAuth-mode profiles (`auth.profiles.<id>.mode = "oauth"`) do not support SecretRef-backed auth-profile credentials.
 - Static runtime credentials come from in-memory resolved snapshots; legacy static `auth.json` entries are scrubbed when discovered.
 - Legacy OAuth imports from `~/.openclaw/credentials/oauth.json`.
diff --git a/docs/providers/ollama.md b/docs/providers/ollama.md
index 3ee76cadd..c144eada5 100644
--- a/docs/providers/ollama.md
+++ b/docs/providers/ollama.md
@@ -27,6 +27,9 @@ Ollama provider config uses `baseUrl` as the canonical key. OpenClaw also accept
   <Accordion title="Custom provider ids">
     Custom provider ids that set `api: "ollama"` follow the same rules. For example, an `ollama-remote` provider that points at a private LAN Ollama host can use `apiKey: "ollama-local"` and sub-agents will resolve that marker through the Ollama provider hook instead of treating it as a missing credential. Memory search can also set `agents.defaults.memorySearch.provider` to that custom provider id so embeddings use the matching Ollama endpoint.
   </Accordion>
+  <Accordion title="Auth profiles">
+    `auth-profiles.json` stores the credential for a provider id. Put endpoint settings (`baseUrl`, `api`, model ids, headers, timeouts) in `models.providers.<id>`. Older flat auth-profile files such as `{ "ollama-windows": { "apiKey": "ollama-local" } }` are not a runtime format; run `openclaw doctor --fix` to rewrite them to the canonical `ollama-windows:default` API-key profile with a backup. `baseUrl` in that file is compatibility noise and should be moved to provider config.
+  </Accordion>
   <Accordion title="Memory embedding scope">
     When Ollama is used for memory embeddings, bearer auth is scoped to the host where it was declared: