When multiple team members share an OpenClaw instance, one power user can burn through the entire API budget, leaving nothing for others. Per-user budgets let you set daily and monthly token limits for each user, track usage individually, and gracefully handle over-limit scenarios without disrupting the team.
Why This Is Hard to Do Yourself
These are the common pitfalls that trip people up.
Shared budget chaos
One user runs expensive automations and uses 80% of the monthly budget in week one. Rest of team is throttled.
No user identification
Default OpenClaw doesn't track which user made which request. All usage looks the same.
Fair allocation
How do you fairly distribute token budgets? Equal per person? By role? By project?
Handling over-limit users
User hits their limit mid-task. Do you hard-stop them? Warn them? Let them continue at reduced priority?
Step-by-Step Guide
Enable user identification
Tag each request with user ID.
# In config/auth.yaml:
authentication:
enabled: true
method: jwt # or "api_key", "oauth"
# Require auth for all requests:
require_auth: true
# Extract user_id from token:
user_id_claim: "sub" # JWT claim containing user ID
# Or for simple setups without auth:
# In config/users.yaml:
user_identification:
method: api_key
users:
- id: user_alice
api_key: ak_alice_...
- id: user_bob
api_key: ak_bob_...Warning: Per-user budgets require user identification. If your OpenClaw instance has no auth, you must add it first or use API keys to identify users.
Create per-user budget config
Define limits for each user.
# In config/budgets.yaml:
per_user_budgets:
enabled: true
default_limits:
daily_tokens: 50000 # 50k tokens/day default
monthly_tokens: 1000000 # 1M tokens/month
user_overrides:
user_alice:
daily_tokens: 100000 # Power user gets more
monthly_tokens: 2000000
user_bob:
daily_tokens: 25000 # Occasional user gets less
monthly_tokens: 500000
# Budget allocation by role:
role_limits:
admin: 200000 # daily
developer: 100000
viewer: 10000Set daily and monthly limits per user
Configure time-based resets.
# In config/budgets.yaml (continued):
per_user_budgets:
reset_schedule:
daily_reset_time: "00:00" # Midnight UTC
monthly_reset_day: 1 # 1st of month
timezone: "UTC"
# Rollover unused tokens?
rollover:
enabled: false # No rollover (use it or lose it)
# enabled: true # Unused tokens carry to next period
# max_rollover_tokens: 100000
# Warn users approaching limit:
warnings:
- at_percent: 75
message: "You've used 75% of your daily token budget"
- at_percent: 90
message: "You've used 90% of your daily budget. Limit will be enforced at 100%"Configure warning messages
Notify users before hard limits.
# In config/budgets.yaml (continued):
per_user_budgets:
on_approaching_limit:
action: warn
message_template: |
You've used {percent_used}% of your {period} token budget.
Remaining: {tokens_remaining} tokens
Resets: {reset_time}
# Show budget status in responses:
include_budget_in_response: true
budget_footer: |
---
Your usage: {tokens_used}/{tokens_limit} tokens ({percent_used}%)
Resets: {reset_time}Set up admin dashboard
View all users' token usage.
# Admin endpoint to view all user budgets:
# GET /api/admin/budgets
# Expected response:
{
"users": [
{
"user_id": "user_alice",
"daily_used": 45000,
"daily_limit": 100000,
"daily_remaining": 55000,
"monthly_used": 890000,
"monthly_limit": 2000000,
"status": "ok"
},
{
"user_id": "user_bob",
"daily_used": 25000,
"daily_limit": 25000,
"daily_remaining": 0,
"monthly_used": 520000,
"monthly_limit": 500000,
"status": "over_limit"
}
]
}
# Create admin dashboard:
# admin-dashboard.html with real-time budget displayHandle over-limit users
Decide what happens when budget is exceeded.
# In config/budgets.yaml (continued):
per_user_budgets:
on_limit_exceeded:
action: soft_limit # Options: "soft_limit", "hard_stop", "reduced_priority"
# Soft limit: warn but allow continuation
soft_limit:
message: |
You've exceeded your daily token budget.
Continued usage will be flagged for review.
notify_admin: true
# Hard stop: reject new requests
hard_stop:
message: |
You've reached your daily token limit.
Your budget resets at {reset_time}.
status_code: 429 # Too Many Requests
# Reduced priority: route to cheaper models
reduced_priority:
force_model: anthropic/claude-3-haiku
message: "Over budget. Routing to Haiku."Warning: Hard stops can frustrate users mid-task. Consider soft limits with admin review or reduced priority routing instead.
Need Custom Per-User Budget Logic?
Basic per-user budgets are straightforward, but enterprise setups need role-based limits, department budgets, project-based allocation, and custom enforcement logic. Our experts design and implement token budget systems tailored to your team structure.
Get matched with a specialist who can help.
Sign Up for Expert Help →