fix(status): correct pinned model clear hint (#93231)

hxy91819 · clawsweeper[bot] · web-flow · commit 3ce3ed668d92 · 2026-06-15T10:15:54.000Z
Summary: - This PR changes pinned-session `/status` guidance, model-selection docs, and status tests to recommend `/model default` instead of `/model <configured>` or `/reset` for clearing a session model pin. - PR surface: Source 0, Tests 0, Docs +4. Total +4 across 7 files. - Reproducibility: yes. from source inspection. Current main and v2026.6.6 emit the old `/reset` hint, while `/model default` clears persisted model overrides and `/reset` intentionally preserves user-selected overrides. Automerge notes: - PR branch already contained follow-up commit before automerge: docs: align model clear hint docs - PR branch already contained follow-up commit before automerge: fix(status): correct pinned model clear hint Validation: - ClawSweeper review passed for head 1181624. - Required merge gates passed before the squash merge. Prepared head SHA: 1181624 Review: #93231 (comment) Co-authored-by: masonxhuang <masonxhuang@tencent.com> Co-authored-by: Mason Huang <masonxhuang@tencent.com> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: hxy91819 Co-authored-by: hxy91819 <8814856+hxy91819@users.noreply.github.com>
diff --git a/docs/cli/status.md b/docs/cli/status.md
@@ -26,7 +26,7 @@ Notes:
 - When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
 - `/status` includes compact Gateway process uptime and host system uptime.
 - Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
-- When a session is pinned to a model that differs from the configured primary, status prints both values, the reason (`session override`), and the clear hint (`/model <configured-default>` or `/reset`). The configured primary applies to new or unpinned sessions; existing pinned sessions keep their session selection until cleared.
+- When a session is pinned to a model that differs from the configured primary, status prints both values, the reason (`session override`), and the clear hint (`/model default`). The configured primary applies to new or unpinned sessions; existing pinned sessions keep their session selection until cleared.
 - For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
 - Output includes per-agent session stores when multiple agents are configured.
 - Overview includes Gateway + node host service install/runtime status when available.
diff --git a/docs/concepts/models.md b/docs/concepts/models.md
@@ -61,7 +61,7 @@ The same `provider/model` can mean different things depending on where it came f
 - Configured defaults (`agents.defaults.model.primary` and agent-specific primaries) are the normal starting point and use `agents.defaults.model.fallbacks`.
 - Auto fallback selections are temporary recovery state. They are stored with `modelOverrideSource: "auto"` so later turns can keep using the fallback chain without probing a known-bad primary every time; OpenClaw periodically probes the original primary again, clears the auto selection when it recovers, and announces fallback/recovery transitions once per state change.
 - User session selections are exact. `/model`, the model picker, `session_status(model=...)`, and `sessions.patch` store `modelOverrideSource: "user"`; if that selected provider/model is unreachable, OpenClaw fails visibly instead of falling through to another configured model.
-- Changing `agents.defaults.model.primary` does not rewrite existing session selections. If status says `This session is pinned to X; config primary Y will apply to new/unpinned sessions.`, switch the current session with `/model Y` or clear stale session state with `/reset`.
+- Changing `agents.defaults.model.primary` does not rewrite existing session selections. If status says `This session is pinned to X; config primary Y will apply to new/unpinned sessions.`, clear the current session selection with `/model default` so it inherits the configured primary again.
 - Cron `--model` / payload `model` is a per-job primary. It still uses configured fallbacks unless the job supplies explicit payload `fallbacks` (use `fallbacks: []` for a strict cron run).
 - CLI default-model and allowlist pickers respect `models.mode: "replace"` by listing explicit `models.providers.*.models` instead of loading the full built-in catalog.
 - The Control UI model picker asks the Gateway for its configured model view: `agents.defaults.models` when present, including provider-wide `provider/*` entries, otherwise explicit `models.providers.*.models` plus providers with usable auth. The full built-in catalog is reserved for explicit browse views such as `models.list` with `view: "all"` or `openclaw models list --all`.
@@ -188,6 +188,7 @@ You can switch models for the current session without restarting:
 /model list
 /model 3
 /model openai/gpt-5.4
+/model default
 /model status
 ```
 
@@ -205,6 +206,7 @@ You can switch models for the current session without restarting:
     - If the agent is idle, the next run uses the new model right away.
     - If a run is already active, OpenClaw marks a live switch as pending and only restarts into the new model at a clean retry point.
     - If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn.
+    - `/model default` clears the session selection and returns the session to the configured default model.
     - A user-selected `/model` ref is strict for that session: if the selected provider/model is unreachable, the reply fails visibly instead of silently answering from `agents.defaults.model.fallbacks`. This is different from configured defaults and cron job primaries, which can still use fallback chains.
     - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
 
diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md
@@ -185,7 +185,8 @@ plugins.
       dashboard session, except when `session.dmScope: "main"` is configured
       and the current parent is the agent's main session — in that case `/new`
       resets the main session in place. Typed `/reset` still runs the Gateway's
-      in-place reset.
+      in-place reset. Use `/model default` when you want to clear a pinned
+      session model selection.
     </Note>
 
   </Accordion>
@@ -358,6 +359,7 @@ use the Control UI Tools panel or config surfaces.
 /model 3           # select by number from picker
 /model openai/gpt-5.4
 /model opus@anthropic:default
+/model default     # clear the session model selection
 /model status      # detailed view with endpoint and API mode
 ```
 
diff --git a/src/auto-reply/status.test.ts b/src/auto-reply/status.test.ts
@@ -1719,7 +1719,7 @@ describe("buildStatusMessage", () => {
     expect(normalized).toContain(
       "This session is pinned to deepseek/deepseek-v4-flash; config primary zhipu/glm-4.5-air will apply to new/unpinned sessions.",
     );
-    expect(normalized).toContain("Clear with: /model zhipu/glm-4.5-air or /reset");
+    expect(normalized).toContain("Clear with: /model default");
     expect(normalized).toContain(
       "Docs: https://docs.openclaw.ai/concepts/models#selection-source-and-fallback-behavior",
     );
diff --git a/src/commands/status.command-sections.test.ts b/src/commands/status.command-sections.test.ts
@@ -167,7 +167,7 @@ describe("status.command-sections", () => {
       "  Configured default: zhipu/glm-4.5-air",
       "  Session selected: deepseek/deepseek-v4-flash",
       "  Reason: session override",
-      "  Clear with: /model zhipu/glm-4.5-air or /reset",
+      "  Clear with: /model default",
       "  Docs: https://docs.openclaw.ai/concepts/models#selection-source-and-fallback-behavior",
     ]);
   });
diff --git a/src/commands/status.command-sections.ts b/src/commands/status.command-sections.ts
@@ -396,7 +396,7 @@ export function buildStatusModelSelectionLines(params: {
       `  Configured default: ${configured}`,
       `  Session selected: ${selected}`,
       `  Reason: ${sess.modelSelectionReason ?? "session override"}`,
-      `  Clear with: /model ${configured} or /reset`,
+      "  Clear with: /model default",
       "  Docs: https://docs.openclaw.ai/concepts/models#selection-source-and-fallback-behavior",
     );
   }
diff --git a/src/status/status-message.ts b/src/status/status-message.ts
@@ -996,7 +996,7 @@ export function buildStatusMessage(args: StatusArgs): string {
         `📌 Session selected: ${selectedModelLabel}${selectedAuthLabel}${modelNote}`,
         "⚠️ Reason: session override",
         `⚠️ This session is pinned to ${selectedModelLabel}; config primary ${configuredDefaultModelLabel} will apply to new/unpinned sessions.`,
-        `↩️ Clear with: /model ${configuredDefaultModelLabel} or /reset`,
+        "↩️ Clear with: /model default",
         "📖 Docs: https://docs.openclaw.ai/concepts/models#selection-source-and-fallback-behavior",
       ]
     : [`🧠 Model: ${selectedModelLabel}${selectedAuthLabel}${modelNote}`];

Original file line number	Diff line number	Diff line change
`@@ -396,7 +396,7 @@ export function buildStatusModelSelectionLines(params: {`
`396`	`396`	` Configured default: ${configured}`,
`397`	`397`	` Session selected: ${selected}`,
`398`	`398`	` Reason: ${sess.modelSelectionReason ?? "session override"}`,
`399`		- ` Clear with: /model ${configured} or /reset`,
	`399`	`+ " Clear with: /model default",`
`400`	`400`	`" Docs: https://docs.openclaw.ai/concepts/models#selection-source-and-fallback-behavior",`
`401`	`401`	`);`
`402`	`402`	`}`
Original file line number	Diff line number	Diff line change
`@@ -996,7 +996,7 @@ export function buildStatusMessage(args: StatusArgs): string {`
`996`	`996`	`📌 Session selected: ${selectedModelLabel}${selectedAuthLabel}${modelNote}`,
`997`	`997`	`"⚠️ Reason: session override",`
`998`	`998`	`⚠️ This session is pinned to ${selectedModelLabel}; config primary ${configuredDefaultModelLabel} will apply to new/unpinned sessions.`,
`999`		- `↩️ Clear with: /model ${configuredDefaultModelLabel} or /reset`,
	`999`	`+ "↩️ Clear with: /model default",`
`1000`	`1000`	`"📖 Docs: https://docs.openclaw.ai/concepts/models#selection-source-and-fallback-behavior",`
`1001`	`1001`	`]`
`1002`	`1002`	: [`🧠 Model: ${selectedModelLabel}${selectedAuthLabel}${modelNote}`];