Billing Attribution Plugin

This OpenClaw plugin reports runtime attribution events to relay so billing logs can be reconciled with agent, message, session, and tool context.

It is observation-only:

• It does not modify OpenClaw source code.
• It does not rewrite prompts, tool calls, or model responses.
• It does not calculate or settle tokens.
• It does not upload full prompts, image data, files, secrets, or full search queries.

Configuration

{
  "enabled": true,
  "endpoint": "http://openclaw-gateway:8080/v1/api/attribution/events",
  "emitWebSearch": true,
  "emitImageInput": false,
  "emitHeartbeat": false,
  "sampleLog": false,
  "timeoutMs": 1500
}

emitWebSearch uses the current pod's search relay token from plugins.entries.<search>.config.webSearch.apiKey only when that search entry points at the gateway relay. It does not use provider API keys.

emitImageInput and emitHeartbeat are disabled by default. Relay-side usage classification remains the source of truth for image and heartbeat billing.

Environment fallbacks are also supported:

• BILLING_ATTRIBUTION_ENABLED
• BILLING_ATTRIBUTION_ENDPOINT
• BILLING_ATTRIBUTION_SAMPLE_LOG
• BILLING_ATTRIBUTION_TIMEOUT_MS

The endpoint is protected by the normal relay bearer token middleware. Web search attribution intentionally reports with the same search relay token that the search request uses, so relay can match events by token, query hash, and time window.

Events

The first version listens to:

• before_tool_call

For tool calls, the plugin sends tool_name, tool_call_id, agent, conversation, session, run, message, query_hash, and a short query_preview.

Relay remains the source of truth for usage, quota, and wallet settlement. These events are only evidence used to connect relay usage logs to OpenClaw runtime context when there is exactly one safe match.