- Updated: March 18, 2026
- 4 min read
Customizing OpenClaw Rating API Edge OPA Token‑Bucket Policies for Tiered Plans on UBOS Hosting
# Introduction
Developers building SaaS platforms often need fine‑grained rate‑limiting that matches the pricing tiers they sell. The **OpenClaw Rating API** combined with **Edge OPA (Open Policy Agent)** token‑bucket policies gives you a powerful, declarative way to enforce those limits at the edge. In this article we’ll walk through customizing the built‑in token‑bucket templates for tiered customer plans, show you how to integrate the solution with **UBOS** hosting, and sprinkle in a timely nod to the current hype around self‑hosted AI agents.
—
## 1. Understanding the Default Token‑Bucket Templates
OpenClaw ships with two starter OPA policies:
1. **basic‑bucket.rego** – a single bucket shared by all users (good for a free‑tier trial).
2. **tiered‑bucket.rego** – a map of buckets keyed by `plan_id` (perfect for paid tiers).
Both policies use the same `allow` rule structure:
rego
allow {
not over_limit
}
over_limit {
bucket := data.ratelimit.buckets[input.plan_id]
bucket.tokens < 1
}
The `data.ratelimit.buckets` object is populated by the Rating API at request time.
—
## 2. Extending the Templates for Your Own Tier Structure
Assume you have three plans:
– **Starter** – 100 req/min
– **Growth** – 1 000 req/min
– **Enterprise** – 10 000 req/min
Create a new file **custom‑tiered‑bucket.rego** and replace the bucket definition with a richer schema:
rego
package openclaw.ratelimit
default bucket = {"capacity": 0, "refill_rate": 0}
bucket[plan] = {
"capacity": capacity,
"refill_rate": refill_rate,
"tokens": tokens
} {
plan := input.plan_id
capacity := tier[plan].capacity
refill_rate := tier[plan].refill_rate
tokens := data.ratelimit.state[plan].tokens
}
tier := {
"starter": {"capacity": 100, "refill_rate": 100},
"growth": {"capacity": 1000, "refill_rate": 1000},
"enterprise": {"capacity": 10000,"refill_rate": 10000}
}
allow {
not over_limit
}
over_limit {
b := bucket[input.plan_id]
b.tokens < 1
}
*What changed?*
– **Explicit tier map** – makes it easy to add new plans without touching the policy logic.
– **Separate `capacity` and `refill_rate`** – you can now implement burst‑able limits (e.g., 2× capacity for the first minute).
Deploy the policy to your Edge OPA instance (UBOS provides a one‑click “Upload OPA Policy” button in the **Edge Services** dashboard).
—
## 3. Wiring the Policy into the OpenClaw Rating API
1. **Create a Rating API key** in the UBOS console → *OpenClaw → API Keys*.
2. **Configure the “Policy URL”** field to point at the OPA endpoint you just uploaded (e.g., `https://edge-opa.your‑domain.ubos.tech/v1/data/openclaw/ratelimit`).
3. **Add a webhook** that pushes the current bucket state back to UBOS every 30 seconds – UBOS supplies a pre‑built script `sync‑bucket‑state.sh` that you can drop into the *Scripts* tab.
Now every request that hits the Rating API will be evaluated against your custom token‑bucket policy, and the bucket counters are persisted automatically by UBOS.
—
## 4. Deploying the Whole Stack on UBOS Hosting
UBOS makes the deployment of edge‑aware micro‑services painless:
1. **Create a new Application** → select *Docker* → use the official `openclaw/rating-api:latest` image.
2. **Add a second Service** → *OPA* → mount the `custom‑tiered‑bucket.rego` file as `/policy/custom.rego`.
3. **Link the services** – in the *Networking* tab, set the Rating API’s `OPA_ENDPOINT` env var to the internal DNS name of the OPA service (`http://opa:8181`).
4. **Enable TLS** – UBOS automatically provisions Let’s Encrypt certs for the domain you assign (e.g., `api.your‑domain.ubos.tech`).
5. **Deploy** – click *Deploy* and UBOS will spin up the containers on a geographically‑close edge node.
### 4.1. Verify the Setup
bash
curl -H "x-api-key: $YOUR_KEY" \
-d '{"plan_id":"growth","user_id":"12345"}' \
https://api.your-domain.ubos.tech/rate
You should receive a JSON response with a `remaining` field that reflects the bucket state for the *growth* tier.
—
## 5. Adding Context – Self‑Hosted AI Agents are the New Frontier
The AI community is buzzing about **self‑hosted agents** that run locally or at the edge, promising privacy and lower latency. By combining OpenClaw’s token‑bucket throttling with UBOS’s edge hosting, you can expose your own AI‑driven micro‑services (e.g., a locally‑hosted LLM inference endpoint) while protecting them from abuse. The same rate‑limit policy you just built can be reused for any AI‑powered endpoint, giving you a unified control plane for both traditional SaaS APIs and the emerging wave of self‑hosted AI agents.
—
## 6. Publish Your Article
If you found this guide helpful, consider sharing it with the UBOS community. For more details on hosting OpenClaw on UBOS, check out our dedicated page: https://ubos.tech/host-openclaw/.
Happy coding!
—
*Author: UBOS Team*
*Featured Image: https://ubos.tech/images/openclaw-rating-api.jpg*