@paso4/cloudflare-unified-billing

OpenClaw provider plugin for Cloudflare AI Gateway with full model catalog (150+ models) and unified billing support.

Features

• Full Model Catalog: 150+ models from Google Gemini, Anthropic Claude, OpenAI, xAI Grok, DeepSeek, Alibaba Qwen, MiniMax, Moonshot Kimi, Workers AI frontier models, and more
• Multi-API Support: Native wire protocol for each model family
• Unified Billing Mode: Optional openai-completions compatibility layer
• Capabilities: Web search, web fetch, and image generation through the same gateway
• Auto Discovery: Installed in ~/.openclaw/plugins/, auto-discovered by gateway

Installation

Install through ClawHub:

openclaw plugins install clawhub:@paso4/cloudflare-unified-billing
openclaw plugins inspect cloudflare-unified-billing --runtime --json

Building from source

bun install
bun run --cwd plugins/provider/cloudflare-unified-billing build
openclaw plugins install "$PWD/plugins/provider/cloudflare-unified-billing" --force --accept-capabilities

bun run build bundles src/ into dist/ with openclaw marked external (--external openclaw). openclaw is a peerDependency resolved by the host runtime — never bundle it into dist/. Keep the --external openclaw flag when modifying the build script.

Configuration

Environment Variables

Onboard

The plugin uses providerAuthAliases to map cloudflare-unified-billing → cloudflare-ai-gateway.
Auth profiles created via the bundled cloudflare-ai-gateway provider are automatically discovered.

Recommended: Use bundled provider's auth choice (has CLI flags for account-id/gateway-id):

openclaw onboard --non-interactive \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-api-key $API_KEY \
  --cloudflare-ai-gateway-account-id $ACCOUNT_ID \
  --cloudflare-ai-gateway-gateway-id $GATEWAY_ID

The plugin will discover this profile and provide the extended model catalog.

Alternative: Use plugin's auth choice (account-id/gateway-id from env vars only, no CLI flags):

export CF_AI_GATEWAY_ACCOUNT_ID=$ACCOUNT_ID
export CF_AI_GATEWAY_GATEWAY_ID=$GATEWAY_ID
openclaw onboard --auth-choice cloudflare-unified-billing-api-key
# API key read from CLOUDFLARE_AI_GATEWAY_API_KEY env var

Model Selection

Models are referenced with the cloudflare-unified-billing/ prefix:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "cloudflare-unified-billing/anthropic/claude-sonnet-4-6",
        "fallbacks": ["cloudflare-unified-billing/openai/gpt-4o"]
      }
    }
  }
}

Unified Billing Mode

All requests use the Cloudflare AI Gateway REST API (OpenAI-compatible):

• Base URL: https://api.cloudflare.com/client/v4/accounts/{account}/ai/v1
• Auth: Authorization: Bearer <CLOUDFLARE_API_TOKEN>
• Gateway routing: cf-aig-gateway-id: <gateway-id> header (requests route through the configured gateway; if the gateway has unified-billing credits, third-party models are billed to the account)
• All models use openai-completions API
• Per-model API differences are stripped

This is useful when you want Cloudflare to handle billing aggregation across all providers.

Note: The legacy gateway.ai.cloudflare.com/v1/{account}/{gateway}/compat endpoint is deprecated for single-model calls. Third-party unified billing is served through the REST API above. The configured gateway must have unified-billing credits (or BYOK provider keys) for third-party models; the account's default gateway typically has them.

User Insights via custom domain

The AI Gateway User Insights dashboard attributes spend to individual identities. Without an identity, all traffic is grouped under one anonymous user. To attribute spend per user, either tag requests with custom metadata or put an Access-protected custom domain in front of the gateway.

Custom domains are not served by the Cloudflare REST API (api.cloudflare.com), so the plugin switches to the AI Gateway endpoint when CF_AI_GATEWAY_CUSTOM_DOMAIN is set:

• Base URL: https://<custom-domain>/compat
• With Access: cf-access-token: <CF_ACCESS_TOKEN> (AI Gateway records the verified Access subject as cf.user_id)
• Without Access: Authorization: Bearer <CLOUDFLARE_API_TOKEN>

# 1. Create a custom domain on the gateway and put it behind Cloudflare Access.
# 2. Point the plugin at it:
export CF_AI_GATEWAY_CUSTOM_DOMAIN=ai.example.com

# 3a. Per-user attribution — a user Access JWT from cloudflared:
export CF_ACCESS_TOKEN="$(cloudflared access login https://ai.example.com)"

# 3b. Or headless service-token auth (no cf.user_id; stays anonymous):
export CF_ACCESS_CLIENT_ID=...
export CF_ACCESS_CLIENT_SECRET=...

Because every request from a tenant's agent carries the Access identity, User Insights groups spend per user without the client application passing user IDs. Service-token requests authenticate successfully but do not receive cf.user_id.

Available Models

Models are referenced with the cloudflare-unified-billing/ prefix followed by the Cloudflare REST model id, e.g. cloudflare-unified-billing/anthropic/claude-opus-5. The tables below list the model id (the part after the plugin prefix).

The catalog tracks the Cloudflare AI model catalog. xAI models use the xai/ REST prefix (the native grok/ prefix only applies to the gateway.ai.cloudflare.com endpoint, which this plugin does not use).

Google Gemini (google)

⚠️ Known Limitation: Gemini models through Cloudflare's unified billing have degraded tool calling performance due to a Google API requirement. Gemini requires thought_signature in function calls for optimal performance, but the OpenAI compat format doesn't support this field. For full tool calling support with Gemini models, use the direct Google provider (google or google-gemini-cli) instead.

See Google's thought_signature documentation for details.

Anthropic Claude

OpenAI

xAI (xai)

Other providers

The catalog also includes DeepSeek (deepseek/deepseek-v4-pro), Alibaba Qwen (alibaba/qwen3.8-max, qwen3.7-max, qwen3.7-plus, qwen3.5-397b-a17b, qwen3-max), Moonshot (moonshotai/kimi-k3, moonshotai/kimi-k2.6, moonshotai/kimi-k2.7-code), MiniMax (minimax/m3, minimax/m2.7), Google Gemma 4 (google/gemma-4-26b-a4b-it), Worker AI frontier models (workers-ai/@cf/zai-org/glm-5.2, workers-ai/@cf/moonshotai/kimi-k2.6, workers-ai/@cf/moonshotai/kimi-k2.7-code, workers-ai/@cf/deepseek-ai/deepseek-v4-pro-0813), plus the Groq, Mistral, Cohere, Perplexity, Cerebras, Baseten, and Parallel families. See src/models.ts for the full list and pricing.

Cloudflare API Token Permissions

This plugin requires the following credentials:

The AI credential must be a real account-level Cloudflare credential with the AI Gateway and Workers AI permissions required by the selected REST models. Requests are authenticated with Authorization: Bearer <CLOUDFLARE_API_TOKEN> against api.cloudflare.com; the cf-aig-gateway-id header routes them through the configured gateway for unified billing and logging.

Development

bun run test                       # unit tests
bun run typecheck
bun run build
cp .dev.vars.example .dev.vars     # fill in credentials
PLUGIN_LIVE_TESTS=true bun run test:integration   # live, paid calls

License

Source-available under the Paso4 Open Plugin License. See LICENSE.