SDKs & frameworks

Any OpenAI- or Anthropic-based SDK routes through Anyray via its base URL. This page also owns what every integration shares: base URLs, client keys, attribution.

Base URLs and headers

Two dialects, two base-URL shapes. Mixing them up is the usual 404.

Dialect	Base URL	The client appends
OpenAI-compatible	http://<gateway>:8787/v1	/chat/completions
Anthropic-native	http://<gateway>:8787 (no /v1)	/v1/messages

Pass your gateway key as the SDK's API key; the real provider key stays server-side. A bare placeholder is rejected when the gateway requires verified users. x-anyray-provider names the upstream provider and is optional once a default provider or routing config is set server-side. Attribution rides x-anyray-metadata, a JSON header: {"user":"alice","team":"platform","tool":"batch-job"}. On a verified key, user and team come from the key itself (a key with no team clears a header-supplied one); tool is always read from the header. Set identity by minting the key against the right user, not by editing the header. The one exception is an agent key with delegated attribution on: it takes user, and team when sent, from the header (validated as an id, else the agent's own name) and keeps the agent's name on the row as agent.

Client keys

Every integration authenticates with the same x-anyray-api-key credential. There are two kinds (ark_svc_ is an ark_ key on the wire):

	Personal key (ark_…)	Agent key (ark_svc_…)
Minted at	Users page, by enrolling a person (or anyray-connect --enroll)	Users page → Agents → Add agent
Attributed to	That person, and their team	The agent name you set at mint time (letters, digits, dot, colon, hyphen, underscore; up to 64 characters)
Use it for	A developer's own machine	A container, a CI job, an unattended service
Expiry	Sliding: renewed on use, so an active developer never hits a mid-session 401	Whatever you set, as a hard limit
Billed seat	Yes, counts as an active seat	No, excluded from the seat count automatically
Extras	Follows the person's team for team-scoped routing	Optional monthly USD budget cap

The agent name becomes the attributed user id in spend, so name the deployment (openclaw-prod, not agent1), and give each deployment its own key: a shared key files all spend under one identity and makes revocation all-or-nothing. The raw key is shown exactly once and never re-fetchable, and in an env var it is a bearer credential, so it belongs in the secret store. Rotating is a new key plus a restart.

Per-SDK setup

OpenAI-compatible clients

The OpenAI SDKs, LangChain's ChatOpenAI, the Vercel AI SDK, and LlamaIndex, on /v1.

Anthropic-native clients

The Anthropic SDKs and LangChain's ChatAnthropic, on the bare origin.

Close the retrieval loop in an agent SDK

When the optimizer elides bulk it leaves a ctx_… handle the model must be able to read back. The opt-in, from the one-line MCP entry to declaring the tool yourself: Retrieval reference.

Coding tools & shell

For coding tools (Claude Code, Cursor, Codex) and a shell/SDK environment, let anyray-connect write the base URL and enroll a per-user key for you, so one command points your tools at the gateway. See also the Cursor integration.