Skip to main content
The OpenAI SDKs accept a custom baseURL and defaultHeaders in their constructors. Point the client at the Caveman gateway and every Chat Completions and Responses API call routes through it, with telemetry and optimization automatically applied.

Prerequisites

  • A Caveman Cloud account with a gateway URL (CAVE_GATEWAY_URL)
  • Your Cave API key (CAVE_API_KEY)
  • Your OpenAI provider key (OPENAI_API_KEY)

OpenAI SDK (TypeScript)

Replace {{app}} with your workload name or app slug. The /w/{{app}} segment attributes spend to the correct workload.

OpenAI SDK (Python)

OpenAI Agents SDK

The OpenAI Agents SDK requires an AsyncOpenAI client. Set it as the default once, and every agent and runner routes through the gateway automatically.
When your provider key is stored in Caveman Cloud, you can drop the x-cave-upstream-key header and pass CAVE_API_KEY in its place.

Labeling traffic

Add x-cave-agent or x-cave-workflow headers to identify different parts of your system in Traces. These labels do not grant access; they only tag requests for filtering and analysis.

Next steps