From c67c4a9eb39a500ac5601780856f2558983b4904 Mon Sep 17 00:00:00 2001
From: dj-oyu <68707227+dj-oyu@users.noreply.github.com>
Date: Fri, 20 Feb 2026 15:07:51 +0900
Subject: [PATCH] docs: add model fallback docs and update config example

Add cross-provider model_fallbacks section to README.md and README.ja.md.
Update config.example.json with provider, model_fallbacks, and
task_reminder_interval fields.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.ja.md               | 30 ++++++++++++++++++++++++++++++
 README.md                  | 30 ++++++++++++++++++++++++++++++
 config/config.example.json |  5 ++++-
 3 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/README.ja.md b/README.ja.md
index ff1838b79..24b58f983 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -621,6 +621,36 @@ HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
 - `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化
 - `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔変更
 
+### モデルフォールバック
+
+`model_fallbacks` はプライマリモデルがリトライ可能なエラー（レート制限、サーバーエラー等）を返した時に起動するフォールバックチェーンです。**異なるプロバイダー**をターゲットにでき、プロバイダーは初回使用時に遅延生成・キャッシュされます。
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "provider": "vllm",
+      "model": "MiniMax-M1-80k",
+      "model_fallbacks": ["openai/gpt-4o", "anthropic/claude-sonnet-4-5-20250929"]
+    }
+  },
+  "providers": {
+    "vllm": {
+      "api_key": "minimax-key",
+      "api_base": "https://api.minimax.io/v1"
+    },
+    "openai": {
+      "auth_method": "oauth"
+    },
+    "anthropic": {
+      "api_key": "sk-ant-xxx"
+    }
+  }
+}
+```
+
+フォーマットは `provider/model`。`/` がない場合はプライマリプロバイダーが使われます（同一プロバイダー内フォールバック）。失敗したプロバイダーはクールダウン期間に入り、連続タイムアウトを防ぎます。
+
 ### 基本設定
 
 1.  **設定ファイルの作成:**
diff --git a/README.md b/README.md
index c292bcd25..abfbe4aae 100644
--- a/README.md
+++ b/README.md
@@ -689,6 +689,36 @@ PicoClaw routes providers by protocol family:
 
 This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
 
+### Model Fallbacks
+
+`model_fallbacks` defines a fallback chain that activates when the primary model returns a retriable error (rate limit, server error, etc.). Fallbacks can target **different providers** — the provider is lazily created and cached on first use.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "provider": "vllm",
+      "model": "MiniMax-M1-80k",
+      "model_fallbacks": ["openai/gpt-4o", "anthropic/claude-sonnet-4-5-20250929"]
+    }
+  },
+  "providers": {
+    "vllm": {
+      "api_key": "minimax-key",
+      "api_base": "https://api.minimax.io/v1"
+    },
+    "openai": {
+      "auth_method": "oauth"
+    },
+    "anthropic": {
+      "api_key": "sk-ant-xxx"
+    }
+  }
+}
+```
+
+The format is `provider/model`. If no `/` is present, the primary provider is assumed (same-provider fallback). Failed providers enter a cooldown period to avoid repeated timeouts.
+
 <details>
 <summary><b>Zhipu</b></summary>
 
diff --git a/config/config.example.json b/config/config.example.json
index 37c2bcd81..118da242d 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -3,10 +3,13 @@
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
       "restrict_to_workspace": true,
+      "provider": "zhipu",
       "model": "glm-4.7",
+      "model_fallbacks": ["openai/gpt-4o"],
       "max_tokens": 8192,
       "temperature": 0.7,
-      "max_tool_iterations": 20
+      "max_tool_iterations": 20,
+      "task_reminder_interval": 5
     }
   },
   "channels": {