The lifecycle
Every tenant moves through the same five stages. You'll touch most of them via the CLI; the control-plane HTTP API exposes the same surface for automation.
1. Create
openclaw tenants create acme \
--quota.tokens-per-day 5_000_000 \
--quota.cost-per-day-usd 50
# output:
# ✓ tenant created · /tenants/acme
# ✓ token (copy now — shown once):
# tk_acme_9F2A4D7E8B1C3F65A2D9E7B0FA1C4E63
# ✓ quota: 5,000,000 tokens/day, $50/dayThe plaintext token appears once. The gateway only stores its SHA-256 hash; recovery is impossible if you lose it. Rotate instead.
2. Use
The tenant token authenticates every request — JSON-RPC, the OpenAI-compatible HTTP API, channel inbound webhooks, terminal sessions.
curl https://gateway.example.com/v1/chat/completions \
-H "Authorization: Bearer tk_acme_9F2A...4E63" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4-7",
"messages": [{"role": "user", "content": "Hello"}]
}'3. Rotate
openclaw tenants token rotate acme
# ✓ old token hash removed from keystore
# ✓ new token (copy now): tk_acme_4F8D...A1B2
# ✓ any requests with the old token will now 4014. Backup / restore
Tenants are tar-zstd'd to any S3-compatible store. Use this before every migration, schema change, or "we're not sure what just happened" moment.
# snapshot
openclaw tenants backup acme \
--to s3://openclawmu-backups/acme/$(date +%F).tar.zst
# restore (on the same or different gateway)
openclaw tenants restore \
--from s3://openclawmu-backups/acme/2026-06-01.tar.zst \
--as acme-staging # optional rename5. Delete
openclaw tenants delete acme --confirm
# ✓ session store wiped
# ✓ memory wiped
# ✓ sandbox roots wiped
# ✓ token hash removed from keystore
# ✓ tenant entry removed
# (audit log kept for compliance retention)Token shape
Tokens are tk_<tenant_id>_<32 hex chars>.
The tenant ID prefix makes operator log lines self-explanatory —
you can grep the gateway logs for tk_acme_ and see
exactly that tenant's traffic without leaking the token's secret half.
The secret half is 32 hex chars = 128 bits of entropy, sourced from
crypto.randomBytes. The SHA-256 hash stored at rest is
64 hex chars; storing the hash means a gateway-disk compromise does
not leak live tokens.
Control-plane HTTP API
Everything the CLI does is also reachable via the control-plane HTTP API for automation. The admin key authenticates these calls; it lives in the gateway config and is never in a tenant overlay.
# list all tenants
curl -H "X-Admin-Key: $OPENCLAWMU_ADMIN_KEY" \
https://gateway.example.com/v1/tenants
# get usage for a tenant
curl -H "X-Admin-Key: $OPENCLAWMU_ADMIN_KEY" \
https://gateway.example.com/v1/tenants/acme/usage?period=current-monthQuotas & suspension
Quotas can be set at creation or updated later. When a tenant exceeds
its quota, subsequent requests return a 429 with
Retry-After set to the next reset boundary. Quotas
apply to tokens consumed, cost (USD), and request rate independently.
openclaw tenants quota update acme \
--tokens-per-day 10_000_000 \
--cost-per-day-usd 100 \
--rpm 60
# suspend without deleting (token still in keystore but all requests 403)
openclaw tenants suspend acme --reason "billing-overdue"
openclaw tenants resume acme