Exhausted Models

Name: Exhausted Models
Rating: 3.5 (1 reviews)
Author: jianjunx

By jianjunx 👁 4 views ▲ 0 votes

openclaw plugins, openclaw-exhausted-models

GitHub

Install

npm install openclaw-exhausted-models`

Configuration Example

{
     "openclaw": {
       "extensions": ["openclaw-exhausted-models"]
     }
   }

README

## 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`（本次对话失败）时：
    - 将本会话所用的模型加入「超限集合」，之后的请求将自动跳过该模型，优先尝试下一个备用模型。

- **按日重置超限集合**
  - 插件会根据配置的时区和「每日重置时间」，判断是否需要清空超限集合；
  - 在到达指定时间之后的任意一次请求中：
    - 将清空所有已标记为超限的模型；
    - 标记当天已经完成过清空，避免同一天重复清空。

### 安装与启用

#### 方式一：通过 npm 安装

1. 安装 npm 包：
   - `npm install openclaw-exhausted-models`
2. 在你的 OpenClaw 配置中（例如 `~/.openclaw/openclaw.json`），添加扩展：
   ```json
   {
     "openclaw": {
       "extensions": ["openclaw-exhausted-models"]
     }
   }
   ```

#### 方式二：通过 openclaw CLI 安装

如果你已经安装了 `openclaw` 命令行工具，可以直接在终端中运行：

```bash
openclaw plugins install openclaw-exhausted-models
```

安装成功后，通常会自动将插件写入 `openclaw.extensions`；如果没有自动写入，可以参考上面的方式一手动在 `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` 目录，这样不同项目可以有各自独立的模型和插件配置。

tools