From 3596ccf82804e214c31d6bc8e6eb2265f8f36b1d Mon Sep 17 00:00:00 2001
From: Xubin Ren <52506698+Re-bin@users.noreply.github.com>
Date: Thu, 25 Jun 2026 16:35:55 +0800
Subject: [PATCH] docs: explain custom provider thinking style

---
 docs/configuration.md | 23 +++++++++++++++++++++++
 docs/providers.md     |  2 ++
 2 files changed, 25 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index 3b4730fc..e00dff6e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -985,6 +985,29 @@ Some OpenAI-compatible gateways expose request-body extensions such as vLLM guid
 }
 ```
 
+If a custom OpenAI-compatible endpoint exposes a provider-specific thinking toggle, set `thinkingStyle` so nanobot can translate `reasoningEffort` into the right request body. Supported styles are `thinking_type` (`{"thinking":{"type":"enabled"}}`), `enable_thinking` (`{"enable_thinking": true}`), and `reasoning_split` (`{"reasoning_split": true}`):
+
+```json
+{
+  "providers": {
+    "companyProxy": {
+      "apiKey": "${COMPANY_PROXY_API_KEY}",
+      "apiBase": "https://api.your-provider.com/v1",
+      "thinkingStyle": "enable_thinking"
+    }
+  },
+  "modelPresets": {
+    "company": {
+      "provider": "companyProxy",
+      "model": "served-model-name",
+      "reasoningEffort": "high"
+    }
+  }
+}
+```
+
+Leave `thinkingStyle` unset unless the endpoint explicitly documents one of those wire formats. `extraBody` is still applied last, so advanced users can override the generated value.
+
 </details>
 
 <a id="local-providers"></a>
diff --git a/docs/providers.md b/docs/providers.md
index 41b78849..697173fb 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -293,6 +293,8 @@ If you have more than one custom OpenAI-compatible endpoint, give each endpoint
 
 Custom provider keys are treated as direct OpenAI-compatible providers. `apiBase` is required because nanobot cannot know the endpoint URL. `apiKey` is optional for local servers or private proxies that do not require one. Choose a name that does not conflict with a built-in provider name or alias, such as `openai`, `openai-codex`, `github-copilot`, or `lm-studio`. Do not set `apiType` on custom provider keys; `apiType` is only for `providers.openai`.
 
+If your custom endpoint documents a nonstandard thinking toggle, set `providers.<name>.thinkingStyle` to `thinking_type`, `enable_thinking`, or `reasoning_split`; nanobot then maps `reasoningEffort` onto that provider-specific request body. Leave it unset for ordinary OpenAI-compatible endpoints.
+
 This named custom provider path is not for Anthropic-compatible endpoints. For Anthropic-compatible proxies, use `providers.anthropic.apiBase` and set the preset provider to `anthropic`.
 
 ### Ollama