Skip to main content
Running an agent you didn’t write, like OpenClaw or Hermes Agent? You don’t need the Belvedir SDK. The ingest endpoint is a standard OTLP/HTTP trace receiver:
  • Endpoint: https://platform.belvedir.ai/api/v1/traces
  • Auth: your bv_live_... key in an x-api-key header (or as a Bearer token)
  • Wire formats: http/protobuf and http/json, gzip accepted
  • Content: spans that follow the OpenTelemetry GenAI conventions (gen_ai.input.messages / gen_ai.output.messages) show up as full conversations
  • Sessions: read from a session.id or gen_ai.conversation.id span attribute. Send the header x-belvedir-session-from: trace to treat every trace that contains an LLM call as its own session when the exporter doesn’t stamp one (traces with no LLM call are not turned into sessions)
Only traces are ingested. There are no metrics or logs endpoints, so turn those signals off or point them elsewhere.

​
OpenClaw

Install our openclaw-belvedir plugin. It has zero dependencies (plain JavaScript on Node built-ins, nothing for a security scanner to flag) and, unlike OpenClaw’s stock OTel exporter, it stamps OpenClaw’s real session identity on every span: a multi-turn conversation becomes one Belvedir session instead of one session per turn, and OpenClaw’s single-span housekeeping traces are skipped.
In ~/.openclaw/openclaw.json, then restart the Gateway (openclaw gateway restart):
hooks.allowConversationAccess is OpenClaw’s consent gate for message content: without it the plugin still runs but only structure and timing arrive, and nothing can be segmented into tasks. Set BELVEDIR_PRIVACY_MODE=true (or config.privacyMode) to send usage and structure only. To confirm the wiring without spending model tokens, the plugin ships a simulator that fires the exact hook sequence of a real two-turn session and prints the session id to look for on the Data pages. Run it from a checkout of the plugin repo:

​
Hermes Agent

Install our hermes-belvedir plugin. It has zero Python dependencies: nothing to pip install, no dependency tree for a security scanner to flag, and few enough lines to review before enabling, as Hermes’ security policy asks. It stamps session.id on every span, so multi-turn Hermes sessions become Belvedir sessions as-is.
That’s the whole setup. Each turn appears within seconds: the conversation the model saw, its replies, tool calls with results, and token usage per request. Full prompts and responses are captured by default; set BELVEDIR_PRIVACY_MODE=true to send usage and structure only. Both plugins are configured environment-first (the variables are listed under Plugin variables), with an optional config.json next to the installed plugin. To confirm the wiring without running the agent, the plugin ships a simulator that fires the exact hook sequence of a real two-turn session:

​
Any other OpenTelemetry SDK

The stock OTLP/HTTP trace exporter works with environment variables alone. Add the session header if your agent doesn’t set session.id:
Traffic is attributed to the API key in the header like SDK traffic, so you can filter by it on the Data pages. Tasks appear once a session goes quiet; see How it works.