From 6e502584ef81edb6c4e0d95ee57cbb11f2ddb9f4 Mon Sep 17 00:00:00 2001
From: "openclaw-docs-sync[bot]"
 <openclaw-docs-sync[bot]@users.noreply.github.com>
Date: Sat, 25 Apr 2026 09:48:45 +0000
Subject: [PATCH] chore(sync): mirror docs from
 openclaw/openclaw@815e9b493c7122cf931db86a687f853f0f7923fe

---
 .openclaw-sync/source.json |  4 ++--
 docs/cli/models.md         | 29 +++++++++++++++++++++++++++++
 docs/concepts/models.md    | 17 +++++++++++------
 3 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 528070a72..1eafbf87c 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "da2c61fe6e02a67f7cbb0d040a9b2b3ac806ba15",
-  "syncedAt": "2026-04-25T09:47:11.960Z"
+  "sha": "815e9b493c7122cf931db86a687f853f0f7923fe",
+  "syncedAt": "2026-04-25T09:47:22.286Z"
 }
diff --git a/docs/cli/models.md b/docs/cli/models.md
index 1fd734a50..71a46a8c0 100644
--- a/docs/cli/models.md
+++ b/docs/cli/models.md
@@ -66,6 +66,35 @@ Notes:
   stale removed-provider default.
 - `models status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets.
 
+### `models scan`
+
+`models scan` reads OpenRouter's public `:free` catalog and ranks candidates for
+fallback use. The catalog itself is public, so metadata-only scans do not need
+an OpenRouter key.
+
+By default OpenClaw tries to probe tool and image support with live model calls.
+If no OpenRouter key is configured, the command falls back to metadata-only
+output and explains that `:free` models still require `OPENROUTER_API_KEY` for
+probes and inference.
+
+Options:
+
+- `--no-probe` (metadata only; no config/secrets lookup)
+- `--min-params <b>`
+- `--max-age-days <days>`
+- `--provider <name>`
+- `--max-candidates <n>`
+- `--timeout <ms>` (catalog request and per-probe timeout)
+- `--concurrency <n>`
+- `--yes`
+- `--no-input`
+- `--set-default`
+- `--set-image`
+- `--json`
+
+`--set-default` and `--set-image` require live probes; metadata-only scan
+results are informational and are not applied to config.
+
 ### `models status`
 
 Options:
diff --git a/docs/concepts/models.md b/docs/concepts/models.md
index d70dad3a4..123f13f9e 100644
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@@ -242,8 +242,11 @@ Key flags:
 - `--set-default`: set `agents.defaults.model.primary` to the first selection
 - `--set-image`: set `agents.defaults.imageModel.primary` to the first image selection
 
-Probing requires an OpenRouter API key (from auth profiles or
-`OPENROUTER_API_KEY`). Without a key, use `--no-probe` to list candidates only.
+The OpenRouter `/models` catalog is public, so metadata-only scans can list
+free candidates without a key. Probing and inference still require an
+OpenRouter API key (from auth profiles or `OPENROUTER_API_KEY`). If no key is
+available, `openclaw models scan` falls back to metadata-only output and leaves
+config unchanged. Use `--no-probe` to request metadata-only mode explicitly.
 
 Scan results are ranked by:
 
@@ -255,12 +258,14 @@ Scan results are ranked by:
 Input
 
 - OpenRouter `/models` list (filter `:free`)
-- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment))
+- Live probes require OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment))
 - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
-- Probe controls: `--timeout`, `--concurrency`
+- Request/probe controls: `--timeout`, `--concurrency`
 
-When run in a TTY, you can select fallbacks interactively. In non‑interactive
-mode, pass `--yes` to accept defaults.
+When live probes run in a TTY, you can select fallbacks interactively. In
+non‑interactive mode, pass `--yes` to accept defaults. Metadata-only results are
+informational; `--set-default` and `--set-image` require live probes so
+OpenClaw does not configure an unusable keyless OpenRouter model.
 
 ## Models registry (`models.json`)