openclaw-exhausted-models 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+## openclaw-exhausted-models 插件
+
+**openclaw-exhausted-models** 是一个用于 OpenClaw 的模型熔断 / 备用模型插件，用来在对话过程中自动记住「因为额度耗尽、错误频发等原因不可用」的模型列表，并在之后的请求中优先改用备用模型；同时可以按每天固定时间点自动清空这份「超限模型列表」，如果你使用魔搭等免费但有限额的模型时可以使用这个插件。
+
+### 工作原理
+
+- **模型顺序来源**
+  - 主模型：`openclaw.json` 中 `agents.defaults.model.primary`
+  - 备用模型列表：`openclaw.json` 中 `agents.defaults.model.fallbacks`（按顺序依次尝试）
+  - 插件内部会把它们组成一个有序列表：
+    1. 主模型（primary）
+    2. 所有备用模型（fallbacks）
+
+- **选择模型**
+  - 每次触发 `before_model_resolve` 时：
+    - 从上述有序列表中，找到第一个 **不在超限集合** 里的模型；
+    - 若找到，则将其拆分成 `provider/model`，返回给 OpenClaw 作为本次会话使用的模型；
+    - 若所有模型都在超限集合中，则抛出错误，提示所有配置模型均不可用。
+
+- **标记超限模型**
+  - 每次模型被选中时，会按 `sessionId` 记住本次使用的 `provider/model`；
+  - 当触发 `agent_end` 事件且 `success === false`（本次对话失败）时：
+    - 将本会话所用的模型加入「超限集合」，之后的请求将自动跳过该模型，优先尝试下一个备用模型。
+
+- **按日重置超限集合**
+  - 插件会根据配置的时区和「每日重置时间」，判断是否需要清空超限集合；
+  - 在到达指定时间之后的任意一次请求中：
+    - 将清空所有已标记为超限的模型；
+    - 标记当天已经完成过清空，避免同一天重复清空。
+
+### 安装与启用
+
+1. 安装 npm 包：
+   - `npm install openclaw-exhausted-models`
+2. 在你的 OpenClaw 配置中（例如 `~/.openclaw/openclaw.json`），添加扩展：
+   ```json
+   {
+     "openclaw": {
+       "extensions": ["openclaw-exhausted-models"]
+     }
+   }
+   ```
+
+### 在 openclaw.json 中的配置
+
+在你的 `~/.openclaw/openclaw.json`（或工作区 `.openclaw/openclaw.json`）中，至少需要配置默认模型和插件条目，大致结构如下：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "anthropic/claude-sonnet-4-20250514",
+        "fallbacks": [
+          "openai/gpt-4.1-mini",
+          "openai/gpt-4.1",
+          "deepseek/deepseek-chat"
+        ]
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "openclaw-exhausted-models": {
+        "config": {
+          "resetHour": 8,
+          "resetMinute": 0,
+          "timezone": "Asia/Shanghai"
+        }
+      }
+    }
+  }
+}
+```
+
+#### 配置项说明（`plugins.entries["openclaw-exhausted-models"].config`）
+
+- **`resetHour`**（可选，默认 `8`）  
+  每天清空「超限模型列表」的小时数（24 小时制）。
+
+- **`resetMinute`**（可选，默认 `0`）  
+  每天清空「超限模型列表」的分钟数。
+
+- **`timezone`**（可选，默认自动探测本机时区，失败时为 `UTC`）  
+  用于计算每日重置时刻的时区字符串，例如：`"Asia/Shanghai"`、`"America/Los_Angeles"`。
+
+### 使用建议
+
+- **合理设置模型顺序**：把最常用、额度相对充足的模型放在 `primary`，把更廉价或更保守的模型放在 `fallbacks` 中的后面。
+- **结合额度监控/告警**：当插件因为所有模型都被标记为超限而报错时，通常意味着所有模型的配额都已用尽，需要手动扩容或调整配置。
+- **多工作区支持**：插件会尝试根据当前 `workspaceDir` 寻找对应的 `.openclaw` 目录，这样不同项目可以有各自独立的模型和插件配置。
+

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Exhausted Models Plugin
+ * 超限模型列表：当模型因额度/错误不可用时加入内存列表，次日指定时间清空。
+ *
+ * 模型顺序取自 openclaw.json 的：
+ *   agents.defaults.model.primary   → 主模型
+ *   agents.defaults.model.fallbacks → 备用模型列表（按顺序）
+ *
+ * 标识格式："provider/model"（如 "anthropic/claude-sonnet-4-20250514"）
+ */
+export default function register(api: {
+    on: (name: string, handler: (...args: unknown[]) => unknown, opts?: {
+        priority?: number;
+    }) => void;
+}): void;

package/dist/index.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Exhausted Models Plugin
+ * 超限模型列表：当模型因额度/错误不可用时加入内存列表，次日指定时间清空。
+ *
+ * 模型顺序取自 openclaw.json 的：
+ *   agents.defaults.model.primary   → 主模型
+ *   agents.defaults.model.fallbacks → 备用模型列表（按顺序）
+ *
+ * 标识格式："provider/model"（如 "anthropic/claude-sonnet-4-20250514"）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = register;
+const DEFAULT_CONFIG = {
+    resetHour: 8,
+    resetMinute: 0,
+    // 若未配置 timezone，将自动使用当前设备时区
+    timezone: "",
+};
+let config = { ...DEFAULT_CONFIG };
+let orderedModels = [];
+// 内存中的超限集合
+const exhaustedSet = new Set();
+// 已执行清空的日期（"YYYY-MM-DD"），防止同一天重复清空
+let lastResetDate = "";
+// sessionId -> 本次 run 选中的模型（agent_end 时加入超限列表）
+const sessionModelMap = new Map();
+function loadConfig(openclawDir) {
+    // @ts-ignore
+    const { existsSync, readFileSync } = require("fs");
+    // @ts-ignore
+    const { join } = require("path");
+    const configPath = join(openclawDir, "openclaw.json");
+    if (!existsSync(configPath))
+        return;
+    try {
+        const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+        const pluginEntry = cfg?.plugins?.entries?.["openclaw-exhausted-models"];
+        if (pluginEntry?.config) {
+            config = { ...DEFAULT_CONFIG, ...pluginEntry.config };
+        }
+        const modelCfg = cfg?.agents?.defaults?.model;
+        if (modelCfg?.primary) {
+            const list = [modelCfg.primary];
+            if (Array.isArray(modelCfg.fallbacks)) {
+                for (const f of modelCfg.fallbacks) {
+                    if (typeof f === "string" && f)
+                        list.push(f);
+                }
+            }
+            orderedModels = list;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+function getOpenClawDir(workspaceDir) {
+    // @ts-ignore
+    const { join } = require("path");
+    if (workspaceDir?.includes(".openclaw")) {
+        const idx = workspaceDir.indexOf(".openclaw");
+        return join(workspaceDir.slice(0, idx), ".openclaw");
+    }
+    // @ts-ignore
+    const home = (typeof process !== "undefined" ? process.env?.HOME : undefined) || "/home/node";
+    return join(home, ".openclaw");
+}
+function todayString(tz) {
+    const now = new Date(new Date().toLocaleString("en-US", { timeZone: tz }));
+    return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+}
+function getTz() {
+    if (config.timezone && typeof config.timezone === "string")
+        return config.timezone;
+    try {
+        const detected = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (detected)
+            return detected;
+    }
+    catch {
+        // ignore
+    }
+    return "UTC";
+}
+function checkAndReset() {
+    const tz = getTz();
+    const today = todayString(tz);
+    if (lastResetDate === today)
+        return;
+    const now = new Date(new Date().toLocaleString("en-US", { timeZone: tz }));
+    const hour = now.getHours();
+    const minute = now.getMinutes();
+    const rh = config.resetHour ?? 8;
+    const rm = config.resetMinute ?? 0;
+    if (hour > rh || (hour === rh && minute >= rm)) {
+        exhaustedSet.clear();
+        lastResetDate = today;
+    }
+}
+function getFirstAvailable() {
+    if (!orderedModels.length)
+        return null;
+    const available = orderedModels.find((m) => !exhaustedSet.has(m));
+    return available ?? null;
+}
+function parseModelRef(ref) {
+    const slash = ref.indexOf("/");
+    if (slash < 1)
+        return null;
+    return { provider: ref.slice(0, slash), model: ref.slice(slash + 1) };
+}
+function register(api) {
+    api.on("before_model_resolve", (event, ctx) => {
+        const typedCtx = ctx;
+        loadConfig(getOpenClawDir(typedCtx.workspaceDir));
+        if (!orderedModels.length)
+            return;
+        checkAndReset();
+        const ref = getFirstAvailable();
+        if (!ref) {
+            throw new Error("Exhausted Models plugin: all configured models are marked exhausted; please update quotas or wait until the daily reset time.");
+        }
+        if (typedCtx.sessionId)
+            sessionModelMap.set(typedCtx.sessionId, ref);
+        const parsed = parseModelRef(ref);
+        if (!parsed)
+            return;
+        return { providerOverride: parsed.provider, modelOverride: parsed.model };
+    }, { priority: 100 });
+    api.on("agent_end", (event, ctx) => {
+        const typedEvent = event;
+        const typedCtx = ctx;
+        if (typedEvent.success !== false)
+            return;
+        const ref = typedCtx.sessionId ? sessionModelMap.get(typedCtx.sessionId) : undefined;
+        if (ref) {
+            exhaustedSet.add(ref);
+            sessionModelMap.delete(typedCtx.sessionId);
+        }
+    }, { priority: 0 });
+}

package/index.ts

@@ -0,0 +1,166 @@
+/**
+ * Exhausted Models Plugin
+ * 超限模型列表：当模型因额度/错误不可用时加入内存列表，次日指定时间清空。
+ *
+ * 模型顺序取自 openclaw.json 的：
+ *   agents.defaults.model.primary   → 主模型
+ *   agents.defaults.model.fallbacks → 备用模型列表（按顺序）
+ *
+ * 标识格式："provider/model"（如 "anthropic/claude-sonnet-4-20250514"）
+ */
+
+const DEFAULT_CONFIG = {
+  resetHour: 8,
+  resetMinute: 0,
+  // 若未配置 timezone，将自动使用当前设备时区
+  timezone: "",
+};
+
+type ResolvedConfig = {
+  resetHour: number;
+  resetMinute: number;
+  timezone: string;
+};
+
+// 模型优先级列表，格式 "provider/model"
+type ModelRef = string;
+
+let config: ResolvedConfig = { ...DEFAULT_CONFIG };
+let orderedModels: ModelRef[] = [];
+
+// 内存中的超限集合
+const exhaustedSet = new Set<ModelRef>();
+
+// 已执行清空的日期（"YYYY-MM-DD"），防止同一天重复清空
+let lastResetDate = "";
+
+// sessionId -> 本次 run 选中的模型（agent_end 时加入超限列表）
+const sessionModelMap = new Map<string, ModelRef>();
+
+function loadConfig(openclawDir: string): void {
+  // @ts-ignore
+  const { existsSync, readFileSync } = require("fs");
+  // @ts-ignore
+  const { join } = require("path");
+  const configPath = join(openclawDir, "openclaw.json");
+  if (!existsSync(configPath)) return;
+  try {
+    const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+
+    const pluginEntry = cfg?.plugins?.entries?.["openclaw-exhausted-models"];
+    if (pluginEntry?.config) {
+      config = { ...DEFAULT_CONFIG, ...(pluginEntry.config as object) };
+    }
+
+    const modelCfg = cfg?.agents?.defaults?.model;
+    if (modelCfg?.primary) {
+      const list: ModelRef[] = [modelCfg.primary];
+      if (Array.isArray(modelCfg.fallbacks)) {
+        for (const f of modelCfg.fallbacks) {
+          if (typeof f === "string" && f) list.push(f);
+        }
+      }
+      orderedModels = list;
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+function getOpenClawDir(workspaceDir?: string): string {
+  // @ts-ignore
+  const { join } = require("path");
+  if (workspaceDir?.includes(".openclaw")) {
+    const idx = workspaceDir.indexOf(".openclaw");
+    return join(workspaceDir.slice(0, idx), ".openclaw");
+  }
+  // @ts-ignore
+  const home: string = (typeof process !== "undefined" ? process.env?.HOME : undefined) || "/home/node";
+  return join(home, ".openclaw");
+}
+
+function todayString(tz: string): string {
+  const now = new Date(new Date().toLocaleString("en-US", { timeZone: tz }));
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+}
+
+function getTz(): string {
+  if (config.timezone && typeof config.timezone === "string") return config.timezone;
+  try {
+    const detected = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (detected) return detected;
+  } catch {
+    // ignore
+  }
+  return "UTC";
+}
+
+function checkAndReset(): void {
+  const tz = getTz();
+  const today = todayString(tz);
+  if (lastResetDate === today) return;
+  const now = new Date(new Date().toLocaleString("en-US", { timeZone: tz }));
+  const hour = now.getHours();
+  const minute = now.getMinutes();
+  const rh = config.resetHour ?? 8;
+  const rm = config.resetMinute ?? 0;
+  if (hour > rh || (hour === rh && minute >= rm)) {
+    exhaustedSet.clear();
+    lastResetDate = today;
+  }
+}
+
+function getFirstAvailable(): ModelRef | null {
+  if (!orderedModels.length) return null;
+  const available = orderedModels.find((m) => !exhaustedSet.has(m));
+  return available ?? null;
+}
+
+function parseModelRef(ref: ModelRef): { provider: string; model: string } | null {
+  const slash = ref.indexOf("/");
+  if (slash < 1) return null;
+  return { provider: ref.slice(0, slash), model: ref.slice(slash + 1) };
+}
+
+export default function register(api: {
+  on: (name: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }) => void;
+}) {
+  api.on(
+    "before_model_resolve",
+    (event: unknown, ctx: unknown) => {
+      const typedCtx = ctx as { sessionId?: string; workspaceDir?: string };
+      loadConfig(getOpenClawDir(typedCtx.workspaceDir));
+      if (!orderedModels.length) return;
+
+      checkAndReset();
+
+      const ref = getFirstAvailable();
+      if (!ref) {
+        throw new Error(
+          "Exhausted Models plugin: all configured models are marked exhausted; please update quotas or wait until the daily reset time."
+        );
+      }
+      if (typedCtx.sessionId) sessionModelMap.set(typedCtx.sessionId, ref);
+
+      const parsed = parseModelRef(ref);
+      if (!parsed) return;
+      return { providerOverride: parsed.provider, modelOverride: parsed.model };
+    },
+    { priority: 100 }
+  );
+
+  api.on(
+    "agent_end",
+    (event: unknown, ctx: unknown) => {
+      const typedEvent = event as { success?: boolean; error?: string };
+      const typedCtx = ctx as { sessionId?: string };
+      if (typedEvent.success !== false) return;
+      const ref = typedCtx.sessionId ? sessionModelMap.get(typedCtx.sessionId) : undefined;
+      if (ref) {
+        exhaustedSet.add(ref);
+        sessionModelMap.delete(typedCtx.sessionId!);
+      }
+    },
+    { priority: 0 }
+  );
+}

package/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "openclaw-exhausted-models",
+  "name": "Exhausted Models",
+  "description": "超限模型列表：自动跳过因额度/错误不可用的模型，按 agents.defaults.model 中的主模型与备用模型顺序切换，次日指定时间清空",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "resetHour": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 23,
+        "description": "每日清空的小时（0-23），默认 8"
+      },
+      "resetMinute": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 59,
+        "description": "每日清空的分钟，默认 0"
+      },
+      "timezone": {
+        "type": "string",
+        "description": "时区（IANA 格式），默认 Asia/Shanghai"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "openclaw-exhausted-models",
+  "version": "1.0.0",
+  "devDependencies": {
+    "@types/node": "*",
+    "typescript": "^5.9.3"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "openclaw": {
+    "extensions": ["openclaw-exhausted-models"]
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "declaration": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["index.ts"]
+}