# Canonical Telem setup guide for coding agents

This file is generated from `docs-verify/snippets/` — the same files the install-verification suite (`docs-verify/`) runs unmodified. Do not hand-edit; run `node scripts/build-agents-md.mjs`.

## Which surface do I use?

| If you're...              | Install as        |
| -------------------------- | ------------------ |
| Using OpenClaw              | Plugin              |
| Using opencode               | Plugin              |
| Using pi                     | Package             |
| A generic MCP client          | `telem-mcp`         |
| Writing Python code            | SDK                 |
| Calling the API directly (no SDK) | HTTP (`curl`)    |
| Using a Claude Code skill       | Repo skill (private repo today) |

## OpenClaw

```bash
openclaw plugins install npm:@telem/openclaw-plugin
echo "TELEM_API_KEY=${TELEM_API_KEY}" >> ~/.openclaw/.env
openclaw gateway restart
```

- Requires OpenClaw >= 2026.7.1.
- Gateway restart required after install.

## opencode

```bash
opencode plugin @telem/opencode-plugin --global
export TELEM_API_KEY=...   # your key
```

- One command writes `opencode.jsonc` and materializes the package.

## pi

```bash
pi install npm:@telem/pi-telem
export TELEM_API_KEY=...   # your key
```

- The `npm:` prefix is required.

## MCP

```bash
pip install "telem-sdk[mcp]"
```

```bash
claude mcp add telem -e TELEM_API_KEY=your-telem-api-key -- telem-mcp
```

- MCP entry point is `telem-mcp`.
- `claude-mcp-add.sh` is the verified `claude mcp add` form for wiring the server into Claude Code.
- `TELEM_API_KEY` (and optional `TELEM_BASE_URL`) are read from the environment.
- `telem-sdk` is not yet published to PyPI — coming soon.

## SDK

```bash
pip install telem-sdk
```

```python
from telem import Telem

client = Telem()  # reads TELEM_API_KEY / TELEM_BASE_URL from env
response = client.search("when was the International Space Station launched")
print(response.results[0].title)
```

- `TELEM_API_KEY` (and optional `TELEM_BASE_URL`) are read from the environment.
- `telem-sdk` is not yet published to PyPI — coming soon.

## HTTP

```bash
# TELEM_API_KEY is optional: some Telem deployments run open and accept
# unauthenticated requests, so the Authorization header is only added when a
# key is actually set (an empty "Bearer " header would make an otherwise-open
# deployment reject the request).
auth_header=()
if [ -n "${TELEM_API_KEY:-}" ]; then
  auth_header=(-H "Authorization: Bearer $TELEM_API_KEY")
fi

curl -s -X POST "$TELEM_BASE_URL/v1/interactions" \
  "${auth_header[@]}" \
  -H "Content-Type: application/json" \
  -d '{"user_input": {"query": "when was the International Space Station launched"}, "postprocessor_names": [], "metadata": {}}'
```

- The only endpoint needed for a single search call is `POST /v1/interactions`.
- `TELEM_API_KEY` is optional — omit the `Authorization` header entirely for open deployments.

## Skill

```bash
pip install telem-sdk
mkdir -p ~/.claude/skills
TELEM_REPO="${TELEM_REPO:-.}"
cp -r "$TELEM_REPO/skills/telem-search" ~/.claude/skills/telem-search
```

- `TELEM_API_KEY` (and optional `TELEM_BASE_URL`) are read from the environment.
- `telem-sdk` is not yet published to PyPI — coming soon.
- Skill source: https://github.com/TelemAI/TelemSDK/tree/main/skills/telem-search (private repo today — request access).