SDK

Configuration reference

On this page

Environment variables

Variable	Used by	Description
`OPEXIA_API_KEY`	SDK, CLI	Workspace API key
`OPEXIA_TRANSPORT`	SDK	`collector` or `direct`; the `transport=` argument wins
`OPEXIA_INGEST_URL`	TS bootstrap	Ingest base URL
`OPEXIA_PROJECT_ID`	TS bootstrap	Project name → `service.name`
`OPEXIA_ORG_ID` / `OPEXIA_WORKSPACE_ID`	your own bootstrap	Passed into `init()`
`CREWAI_DISABLE_TELEMETRY`	CrewAI adapter	Set to `true` before importing CrewAI
`PXCORE_MODEL`	pxcore	Active model for calibration gating

OPEXIA_ORG_ID and OPEXIA_WORKSPACE_ID are read by your bootstrap code, not by init() itself — init() takes them as explicit arguments.

Path	Purpose
`.opexia-wal/spans.jsonl`	Write-ahead log; replayed on next `init()`
`.opexia/shipcheck.yml`	Ship Check policy
`.opexia/agentmap.lock`	Committed agent-topology lockfile from `opexia audit`

Add .opexia-wal/ to .gitignore. Commit .opexia/agentmap.lock — its whole value is being diffable in review.

Symptom	Cause	Fix
`init()` raises at startup	Bad collector endpoint or WAL path	Fix the config, or set `fail_open=True`
No spans, no errors	Protobuf OTLP	Use the http/json exporter; collectors need `encoding: json`
`202` on ingest but no traces	Spans dead-lettering	Check the four rules and ingestion health
A whole span vanishes	Nested object in `opexia.decision` / `opexia.sources`	`json.dumps` them — they are JSON strings
A whole span vanishes	Undocumented `opexia.*` key	The schema is `extra="forbid"`; remove it
Prompts page has thousands of one-call rows	`query_text` joined without role boundaries	Use `renderPrompt()` / the `role:\ncontent` join
`PermissionError` (WinError 32) on Windows	WAL renamed with an open handle	Fixed in current versions — upgrade `opexia-trace`
Spans lost on exit	Process died before the batch flushed	Call `force_flush()` before exit
No `end_user` data on the dashboard	`opexia.end_user` never set	Pass `end_user=` or call `record_end_user()`
Empty engine panels, traces present	Engine off, or no LLM credential	Check engine settings and LLM credentials
No prompt/completion text stored	`capture_text` is off (the default)	See capture text