Tools
Model Refresh
By OpenClaw plugin: live /models discovery, /models-refresh command, admin RPC for OpenAI-compatible providers
Install
openclaw plugins install openclaw-model-refreshREADME
# OpenClaw Model Refresh 🔄
Language: [English](./README.md) | [简体中文](./docs/README.zh.md)
[](https://github.com/GuoShuang233/openclaw-model-refresh/actions/workflows/ci.yml)
An OpenClaw plugin that keeps your configured OpenAI-compatible model catalogs fresh: live discovery of each provider's `/v1/models`, automatic refresh of model lists, a dedicated `/models-refresh` chat command, and an admin RPC method.
## Features
- **Live model discovery**: pulls the OpenAI-compatible `/v1/models` endpoint per provider, with a TTL cache (default 60s) and bounded concurrency
- **Auto refresh**: model-list reads (e.g. `/models`) go through a live catalog that calls the providers; stale entries are re-fetched automatically, and on failure the last cache is kept with a warning
- **Model solidification**: refresh results are written back to the agent's `models.json` and synced into the OpenClaw config; models that disappear upstream are pruned from the allowlist
- **`/models-refresh` command**: trigger a refresh from chat and get per-provider model counts and source (`live` / `cache` / `fallback`)
- **`openclaw-model-refresh.refresh` gateway method**: `openclaw gateway call openclaw-model-refresh.refresh --params '{"force":true}'` for scripts and cron jobs
- **Default-model drift protection**: if the current default model is removed upstream, the plugin auto-switches to a surviving model from the same provider and reports it
## Installation
Requires Node.js ≥ 22.12 and OpenClaw ≥ 2026.7.1.
```bash
openclaw plugins install openclaw-model-refresh
```
From the git source:
```bash
openclaw plugins install git+https://github.com/GuoShuang233/openclaw-model-refresh.git
```
Restart the OpenClaw gateway after installing. The plugin activates automatically on gateway startup.
## Configuration
The plugin reuses `models.providers` from your main OpenClaw config — no extra provider setup. Optional plugin-level settings live under `plugins.entries.openclaw-model-refresh.config`:
| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `ttlMs` | integer | 60000 | Model-list cache TTL (ms), ≥ 1000 |
| `timeoutMs` | integer | 5000 | Timeout for a single `/v1/models` request (ms) |
| `maxConcurrency` | integer | 4 | Max concurrent provider fetches, 1–16 |
Provider `baseUrl` / `apiKey` are read from the main OpenClaw config; `apiKey` is only used in request headers and never appears in output.
## Usage
- Send `/models-refresh` in chat: force a refresh immediately and see the result
- `openclaw models` and other model-list reads: zero overhead while the cache is fresh, automatic background refresh when stale
- Call the RPC directly from scripts or cron:
```bash
openclaw gateway call openclaw-model-refresh.refresh --params '{"force":true}'
```
## Development
```bash
# Build dist/ (the npm publish artifact)
npm run build
# Tests (self-contained, uses tsx for the TypeScript sources)
npm test
# Structure check
npm run check
# Optional: run a real discovery pass against a local OpenClaw config
node --import tsx scripts/provider-smoke.mjs [path/to/openclaw.json]
```
The build uses esbuild; if it is not installed locally, it borrows from a sibling `../openclaw/node_modules`.
## Architecture
```
openclaw main config models.providers
│
▼
discovery.ts ── GET {baseUrl}/models (TTL 60s, concurrency cap)
│
├── refresh-service.ts ── merge live/cache/fallback, solidify models.json + config
├── catalog.ts ──────── liveCatalog provider (registerModelCatalogProvider)
└── index.ts ────────── /models-refresh command + gateway method
```
- `catalog.ts` hooks the unified model catalog via the official `registerModelCatalogProvider`; reads call discovery live (60s TTL), so `/models` and friends need no changes
- `refresh-service.ts` owns refresh, solidification, and allowlist convergence; it auto-drifts and reports when the default model is removed
- No runtime third-party dependencies — only `openclaw/plugin-sdk/plugin-entry` and Node built-ins
## License
MIT
tools
Comments
Sign in to leave a comment