Core Concepts

Understanding the Green module's data model and methodology.

Carbon Traces

A carbon trace is an atomic record of environmental impact for a single API request.

Each trace captures:

Field Description
traceId Unique identifier
runId Links to agent run
timestamp When the request occurred
provider API provider (anthropic, openai, etc.)
model Model identifier
inputTokens Tokens sent to the model
outputTokens Tokens generated by the model
cacheReadTokens Tokens read from cache
inputCo2Grams CO₂ from processing input
outputCo2Grams CO₂ from generating output
cacheCo2Grams CO₂ from cache reads
totalCo2Grams Sum of all CO₂
waterMl Estimated water usage
confidence Data quality indicator (0.0–1.0)

GHG Protocol Fields

For standards compliance, traces also include:

Field Description
scope Always 3 (Scope 3 emissions)
category Always 1 (Purchased Goods and Services)
calculationMethod How the estimate was derived
dataQualityScore GHG Protocol quality indicator (1–5)

Carbon Factors

A carbon factor defines the emissions per unit of activity for a specific provider/model combination.

type CarbonFactor = {
  provider: string;
  model: string;
  inputCo2PerMillionTokens: number;   // gCO₂eq
  outputCo2PerMillionTokens: number;  // gCO₂eq
  cacheReadCo2PerMillionTokens: number;
  waterMlPerMillionTokens: number;
  confidence: number;                  // 0.0–1.0
  source: "measured" | "research" | "estimated" | "fallback";
};

Output vs Input Ratio

Output tokens are ~3x more carbon-intensive than input tokens because: - Generation requires iterative forward passes - Each token requires full model computation - Input tokens can be parallelized more efficiently

Confidence Scoring

Every estimate carries a confidence score (0.0–1.0) indicating data quality:

Score Label Description
≥0.7 High Based on published provider data
≥0.5 Medium Academic research + extrapolation
≥0.3 Low Estimated from similar models
<0.3 Very Low Fallback estimate

Data Quality Score (GHG Protocol)

For GHG Protocol compliance, confidence maps to a 1–5 data quality score:

Confidence DQS Description
≥0.8 1 Primary data from suppliers
≥0.6 2 Published secondary data
≥0.4 3 Average secondary data
≥0.2 4 Estimated data
<0.2 5 Highly uncertain

Calculation Methods

The GHG Protocol defines four calculation methods for Scope 3:

Method Description When Used
Supplier-specific Data from the actual supplier Provider publishes emissions
Hybrid Mix of supplier + secondary data Partial provider data available
Average-data Industry averages Using academic research
Spend-based Emissions per $ spent Last resort

OpenClaw primarily uses average-data (academic research) with hybrid when providers publish partial data.

Intensity Metrics

For TCFD reporting, emissions are normalized to activity:

Metric Unit Description
Per Million Tokens gCO₂eq/1M tokens Efficiency metric
Per API Call gCO₂eq/call Usage metric

These allow comparison across: - Different time periods - Different providers/models - Industry benchmarks

Uncertainty Bounds

For ISO 14064 compliance, confidence converts to uncertainty ranges:

Confidence Uncertainty Range
≥0.7 ±15%
≥0.5 ±30%
≥0.3 ±50%
<0.3 ±100%

Example: 100g CO₂ at 60% confidence → 70g to 130g

Scope 3 Category 1

All AI inference emissions fall under Scope 3, Category 1: Purchased Goods and Services.

  • Scope 1: Direct emissions (your company's facilities)
  • Scope 2: Indirect from purchased energy (your electricity)
  • Scope 3: All other indirect (supply chain, products)
  • Category 1: Purchased goods and services (API calls)

Next Steps