From 7f1254861528cbae6908f59c785d15ba2228eb65 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 9 Jan 2026 01:59:22 +0100
Subject: [PATCH] docs: explain model allowlist errors

---
 docs/concepts/models.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/concepts/models.md b/docs/concepts/models.md
index eee79d6ac..67e786211 100644
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@@ -33,6 +33,37 @@ Related:
 Model refs are normalized to lowercase. Provider aliases like `z.ai/*` normalize
 to `zai/*`.
 
+## “Model is not allowed” (and why replies stop)
+
+If `agent.models` is set, it becomes the **allowlist** for `/model` and for
+session overrides. When a user selects a model that isn’t in that allowlist,
+Clawdbot returns:
+
+```
+Model "provider/model" is not allowed. Use /model to list available models.
+```
+
+This happens **before** a normal reply is generated, so the message can feel
+like it “didn’t respond.” The fix is to either:
+
+- Add the model to `agent.models`, or
+- Clear the allowlist (remove `agent.models`), or
+- Pick a model from `/model list`.
+
+Example allowlist config:
+
+```json5
+{
+  agent: {
+    model: { primary: "anthropic/claude-sonnet-4-5" },
+    models: {
+      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
+      "anthropic/claude-opus-4-5": { alias: "Opus" }
+    }
+  }
+}
+```
+
 ## CLI commands
 
 ```bash