Rerank

The bundled rerank plugin turns any reranker behind a /rerank endpoint into a Decision model. It ships with OpenClaw and is enabled by default; it does nothing until you configure an endpoint.

A reranker answers one question: how relevant is this document to this query? That is the shape of many Decision questions, such as the Knowledge recall gate asking "would this page help answer the message?". If you already run a reranker, it works as a Decision model with no extra plugin.

Supported servers

Any server that speaks the common /rerank API:

OpenClaw posts to <baseUrl>/rerank with model, query, and the documents. Most servers read the documents from documents; TEI reads texts. When an endpoint rejects the first form, OpenClaw retries once with texts and remembers the working form for that endpoint.

Responses may use the Cohere shape (results[].relevance_score), Voyage's data[], or TEI's bare array of { index, score }. Scores must be relevance probabilities from 0 to 1. Cohere, Jina and Voyage return them, as does TEI with raw_scores off; check the score setting of other servers. A response with any score outside that range is rejected as invalid-response: rescaling a batch from its own values would move one page's score with its neighbours, so serve raw-logit models (for example llama.cpp's --reranking) behind a sigmoid.

Configure

List the endpoint and the model under models.providers.rerank, then select it as the Decision model:

{  models: {    providers: {      rerank: {        baseUrl: "http://127.0.0.1:8000/v1",        models: [          { id: "Alibaba-NLP/gte-reranker-modernbert-base", name: "GTE reranker ModernBERT" },        ],      },    },  },  agents: {    defaults: { decisionModel: "rerank/Alibaba-NLP/gte-reranker-modernbert-base" },  },}

Any reranker your server hosts works; Alibaba-NLP/gte-reranker-modernbert-base is the recommended model for the Knowledge recall gate (see below).

• The model id is sent as model in each request. Use the name your server expects.
• A self-hosted server needs no credential. For a hosted API, set models.providers.rerank.apiKey (a SecretRef is recommended) or the RERANK_API_KEY environment variable. OpenClaw sends it as Authorization: Bearer <key>.
• Private and LAN addresses are allowed because you authored the endpoint. Set models.providers.rerank.request.allowPrivateNetwork: false to refuse them.
• The plugin declares the model as Decision-only; it is never offered as a chat model.

The plugin serves one provider entry, rerank, so it points at one server. List every model that server hosts under models.providers.rerank.models. Other provider IDs (for example rerank-home) are not handled by this plugin.

What a reranker can answer

The plugin maps Decision questions onto rerank calls. Questions in one request that share a query go to the server in one call.

• Choice probabilities are independent relevance scores, not a distribution that sums to 1.
• score, tags, and box questions and image state are not supported; a request containing one returns unsupported-input without a server call.
• JSON state is sent as its JSON text.

Relevance is not the same as reasoning. A reranker is a good fit for "does this text match that one" judgments and a poor fit for rubric scoring or multi-step logic. Use a native Decision provider for those.

Recall gate example

The Knowledge recall gate asks one boolean question per candidate page. By default the candidates come from keyword search, the state is the bare user message, and each question carries the page title and its best passages, so every question maps onto one (query, document) pair in a single rerank call. The recommended model is Alibaba-NLP/gte-reranker-modernbert-base; the gate's defaults were measured with it:

{  models: {    providers: {      rerank: {        baseUrl: "http://127.0.0.1:8080",        models: [          { id: "Alibaba-NLP/gte-reranker-modernbert-base", name: "GTE reranker ModernBERT" },        ],      },    },  },  agents: {    defaults: { decisionModel: "rerank/Alibaba-NLP/gte-reranker-modernbert-base" },  },  plugins: {    entries: { knowledge: { config: { recallGate: { mode: "shadow" } } } },  },}

Reranker scores are not calibrated probabilities, and each model scores on its own scale. With a different model, run the gate in shadow mode first and tune highThreshold against its logged scores before switching to live.

Privacy

Every evaluation sends the state text and the question documents to the configured endpoint. Use a local server for private conversations.