Skip to content
Telem

Authentication

Telem authenticates with a bearer token (TELEM_API_KEY) and points at a deployment with a base URL (TELEM_BASE_URL). Every surface reads both from the environment; the SDK also takes them as constructor arguments and OpenClaw’s plugin config as apiKey/baseUrl, both above the environment. OpenCode and Pi keep credentials env-only, out of their config files.

TELEM_API_KEY

Section titled “TELEM_API_KEY”

Set it and every request carries an Authorization: Bearer <key> header. Issue one in the Telem console under API keys in your project; keys are project-scoped and carry per-service grants, so a key reaches only that project’s services.

The hosted deployment (https://router.telem.ai) requires a key — an unauthenticated request gets 401 {"detail": "Missing API key"}. Unset, the client sends no Authorization header rather than raising, so a self-hosted deployment configured to run open works without one.

TELEM_BASE_URL

Section titled “TELEM_BASE_URL”

Defaults to the hosted deployment, https://router.telem.ai. Set it (or pass base_url in code) to reach a staging or self-hosted deployment. That default is the SDK’s and the plugins’ — a raw curl has none and must export the variable, or the request fails with curl: (3) URL rejected.

Resolution order

Section titled “Resolution order”

Both settings resolve the same way, first match wins:

  1. Explicit argument — Telem(api_key=..., base_url=...) in code, or the equivalent per-surface config value (e.g. an OpenClaw plugin config entry).
  2. Environment variable — TELEM_API_KEY / TELEM_BASE_URL.
  3. Credentials file — ~/.telem/credentials.json, written by the npm wizard (npm create @telemai) and relocatable with TELEM_CONFIG_DIR. Read by the Python SDK and everything that rides it and by the JavaScript SDK on Node 20.16+; the TypeScript harness plugins stop at the environment. The one-line curl installer instead exports TELEM_API_KEY from ~/.telem/env (mode 0600) via your shell profile, so a key installed that way arrives at step 2, not step 3.
  4. Default — none for TELEM_API_KEY (unset means no auth header at all); https://router.telem.ai for TELEM_BASE_URL.

Except on OpenClaw, whose host config carries apiKey and baseUrl, credentials are never .telem/telem.json keys — that file carries options.

Keeping your key safe

Section titled “Keeping your key safe”
  • Set it as an environment variable, or in a .env-style file kept outside version control — ~/.openclaw/.env for OpenClaw, your shell profile for local SDK use.
  • Prefer the environment over plaintext config wherever a surface supports both.