From 7cb9e95a537c7bc7ff52498c676b97fe7d3611b5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 9 Jan 2026 14:17:49 +0000
Subject: [PATCH] docs: document auth profile selection

---
 docs/gateway/authentication.md | 18 ++++++++++++++++++
 docs/start/faq.md              | 31 +++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md
index b4a1449fb..8c6b4d705 100644
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@@ -67,6 +67,24 @@ clawdbot models status
 clawdbot doctor
 ```
 
+## Controlling which credential is used
+
+### Per-session (chat command)
+
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:claude-cli`, `anthropic:default`). Use `/model status` to see candidates + which one is next.
+
+### Per-agent (CLI override)
+
+Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
+
+```bash
+clawdbot models auth order get --provider anthropic
+clawdbot models auth order set --provider anthropic anthropic:claude-cli
+clawdbot models auth order clear --provider anthropic
+```
+
+Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+
 ## How sync works
 
 1. **Claude Code** stores credentials in `~/.claude/.credentials.json` (or
diff --git a/docs/start/faq.md b/docs/start/faq.md
index 14b7db395..3d3c25ebd 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -280,6 +280,15 @@ Use the `/model` command as a standalone message:
 
 You can list available models with `/model`, `/model list`, or `/model status`.
 
+You can also force a specific auth profile for the provider (per session):
+
+```
+/model opus@anthropic:claude-cli
+/model opus@anthropic:default
+```
+
+Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.
+
 ### Why do I see “Model … is not allowed” and then no reply?
 
 If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any
@@ -413,6 +422,28 @@ Clawdbot uses provider‑prefixed IDs like:
 
 Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.<provider>`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.
 
+You can also set a **per-agent** order override (stored in that agent’s `auth-profiles.json`) via the CLI:
+
+```bash
+# Defaults to the configured default agent (omit --agent)
+clawdbot models auth order get --provider anthropic
+
+# Lock rotation to a single profile (only try this one)
+clawdbot models auth order set --provider anthropic anthropic:claude-cli
+
+# Or set an explicit order (fallback within provider)
+clawdbot models auth order set --provider anthropic anthropic:claude-cli anthropic:default
+
+# Clear override (fall back to config auth.order / round-robin)
+clawdbot models auth order clear --provider anthropic
+```
+
+To target a specific agent:
+
+```bash
+clawdbot models auth order set --provider anthropic --agent main anthropic:claude-cli
+```
+
 ### OAuth vs API key: what’s the difference?
 
 Clawdbot supports both: