Claude API Added in 0.9.18

The Claude API provider runs Claude chats on an API key from the Claude Console instead of your Claude subscription. The agent is the same: Claude Code on the relay's machine, with the same tools, modes, question cards, sub-agents, steering and background tasks. Only the bill changes. Turns are billed to the Console organisation the key belongs to.

Claude API sits beside your subscription, not in its place. You can start a chat on the key, start one on the subscription, and move a Claude chat from one to the other between turns, keeping its session. An optional monthly cap stops spending on the key once this relay's estimate reaches it. The table of all providers is on Providers at a glance.

The API key #

You need an API key from the Claude Console (API keys on platform.claude.com). Create it inside a workspace; see Limits. Open Settings → Providers → Claude API, the sub-tab after Claude.

The line under the fields says where you are:

Then start a conversation as usual: in New Chat, pick Claude API. See Starting a conversation. A Claude API chat carries a gold Claude API label, and the composer's lock note reads 🔒 Session locked to Claude API models.

Which keys are taken #

• A Console API key, a key that starts with sk-ant-, of 8 to 512 characters without spaces.
• Claude login and session tokens, and Admin keys, are refused when you save, with a message that names what was pasted, for example This is an Anthropic Admin API key (it manages an organisation and cannot run models), not an API key. A key of another vendor gets This does not look like a Claude API key. No message quotes the key.
• Whether Anthropic accepts the key shows when the relay asks for its models (see Models). A refused key stays saved, and the status line says why.

Saving, changing and removing the key #

• Saving a different key clears the key's model list and stops the Claude API workers that are running, including one in the middle of a turn, so change the key between turns. The next message starts them with the new key.
• Removing the key is refused while any Claude API chat has sent a message or has one queued: Cannot remove the Claude API key while N Claude API conversation(s) still exist. Switch Claude API off for new conversations instead. It is refused too while a worker still runs on the key.
• Removing the key, or switching Claude API off, moves Claude API chats that have not sent a message yet back to Copilot. A chat on the key that has started keeps its billing toggle, so you can move it to the subscription; its turns on the key do not run while Claude API is off.

Switching a chat between subscription and key #

A Claude chat, on either billing, has a toggle under the lock note: Subscription | API key. It shows while Claude API is on with a saved key. A chat that is on the key keeps it after Claude API is switched off, so it can move back.

• From the next turn. A running turn finishes on the billing it started on. Messages already queued run on the new one.
• The session stays. The relay restarts the chat's Claude Code between turns and resumes the same session. It waits for the running turn, an open question, a compaction or background tasks, and the toggle says which, for example Moves to the API key after the running turn.
• The first turn on the key costs more. It has no prompt cache. The toggle says so: The first turn on the API key has no prompt cache and costs more.
• The transcript notes each switch, for example 💳 Billing: this chat runs on the Claude API key from the next turn., with (switched by an agent) or (switched at the usage limit) where that applies.
• When a side cannot be chosen, its button is greyed and its tooltip says why. The switch is refused when Claude API has no key or is off, when this month's cap is reached (the toggle then says This month's Claude API cap is reached: the chat stays on the subscription.), when Claude is switched off for a move back to the subscription (CLAUDE_NOT_CONFIGURED), or when the chat's model is not on the other side's model list.
• A page that is behind. A message sent from a page that still showed the old billing is not sent on the new one: its text goes back into the draft.

Nothing else switches a chat. There are three ways to do it: the toggle, the usage-limit banner, and an agent's send:

• At the usage limit. When a subscription chat is paused at the Claude usage limit, the banner offers Switch this chat to API key if the chat may move. The paused turn then carries on on the key at once. At the cap the banner says No switch to the API key: this month's Claude API cap is reached.
• By an agent. relay_tool's send takes provider (claude or claude-api) for a Claude session and switches it together with the message. The approval card then says Switches billing to API key.

There is no setting per folder for the billing: each chat has its own, chosen in New Chat and changed with the toggle. What a folder sets, its commit attribution, applies on both billings.

The monthly cap #

Monthly cap in US dollars (optional) limits what this relay spends on the key in a calendar month, by its own estimate. Amounts above 0, up to 1,000,000, with at most two decimals; leave it empty for no cap.

Once this month's estimate reaches the cap:

• A new turn on the key does not run. The chat gets a note that ends with Error code: relay.claude-api-cap-reached. and the buttons Claude API settings (it opens the tab at the cap field) and Switch to subscription.
• A switch to the key is refused, from the toggle, the usage-limit banner or an agent.
• New Chat refuses a Claude API chat. The dialog stays open with the reason, Claude API settings, and Start on subscription, which starts the same chat on Claude instead (offered while Claude is on). On a phone the dialog scrolls to it.
• Agents are refused too. An agent's send to a session on the key, and its create_session for a Claude API chat, are refused: the relay answers 409 CLAUDE_API_CAP_REACHED, and nothing is queued or created.
• A turn Claude Code starts by itself on the key, when a background task reports back, gets the note, and the chat's background tasks are stopped, since each report would start another such turn. Its first request may already be billed. The note comes once per chat until the cap clears, a Claude API setting is saved, or a turn of the chat runs on the key again.

A turn that is already running finishes. A turn's cost is booked when it ends, so turns that were running can take the month past the cap. The cap counts only the part of the estimate that has a price (see Limits). While a cap is set and the spend cannot be read, the cap counts as reached. The month is the relay's: it starts over at midnight on the 1st in the relay's time zone. Spend limits set in the Console apply on top.

The same note and buttons come when Claude API has no key (relay.claude-api-not-configured) or is switched off: the turn does not run. New Chat refuses a Claude API chat then too, with CLAUDE_API_NOT_CONFIGURED.

The usage card #

📊 Check Usage has a Claude API tab while a key is saved, also with Claude API switched off, so the month's spend stays in view. It shows what this relay's turns on the key are estimated to have cost:

The bar changes colour at 50 % and 75 % of the cap and turns red at 90 %, as every bar does; see Reading a card. The card links to Console billing and Console limits.

Where the figures come from. They are Claude Code's own estimate from its price table, for the turns on the saved key on this relay, so sub-agents, compaction and web search are in them. OAR keeps no price table of its own. Days and the month follow the relay's clock and time zone. Turns paid from the API credit that comes with a Max or Team plan are counted too; OAR cannot see that credit, nor the Console balance. The Console's billing page has the real figures and the balance.

Tokens without a price. A model Claude Code has no price for shows no price known instead of an amount, never $0. A total that leaves such tokens out reads (estimate incomplete).

An agent can read the same card with relay_tool's usage action.

Models #

The relay asks Anthropic which models the key may use (GET /v1/models) when you save a key, when you switch Claude API on again, and on Refresh models (on the tab, or Refresh in 🤗 Select Models). A request gives up after 10 seconds.

• Until the first answer the tab offers the Claude tab's models, with the note Not listed by Anthropic yet: these are the Claude tab's models until the key's list is read.
• A failed request keeps the list the relay had; Refresh models says Claude API model discovery failed. The stored models were kept: ….
• Long context. A model with a window of 1M tokens or more, or one whose 1M variant the Claude tab lists, also gets its [1m] variant, offered in the Context window dropdown as on Claude.
• Which ones show. 🤗 Select Models → Claude API chooses which models the composer offers. The Default model is always offered.
• Per message. A chat can change its model between turns, as on Claude.

Reasoning effort #

The effort picker works as on Claude. The levels come from Anthropic's model list: none and the levels the model reports, plus Ultracode on a model that has xhigh. A model that reports no effort support offers only none. Before the key's list is read, a model has the Claude tab's levels for it. The 🧠 dialog has the same Thinking controls as on Claude.

Shared with Claude #

Commit attribution, the background command limit, the effort levels and the compaction window are the Claude tab's, so a switch changes only who pays:

• Commit attribution, with a folder's choice from the 🧠 dialog;
• the background command limit;
• the auto-compact window.

One Claude configuration folder. Claude API chats use the same Claude Code folder as subscription chats (~/.claude, or CLAUDE_CONFIG_DIR): the same skills, plugins, MCP servers and transcripts. That is what lets a chat keep its session when it switches. Settings in that folder or the chat folder's .claude/ cannot reroute the key: the relay pins Anthropic's address and the key over them.

Not on the key. Claude's plan meters and the usage-limit pause do not apply: a turn Anthropic refuses fails with a note. Claude API chats run with all hooks and the status line off; see Security.

Everywhere else, read Claude. Where other pages describe what Claude chats do, such as sub-agents, background tasks, compaction, the plan board, question cards or the send button during a turn, a Claude API chat does the same.

Limits #

• A key outside a workspace gets HTTP 400. Anthropic answers a key that is not tied to a workspace with HTTP 400, and the tab says API key saved, but Anthropic refused it: …. Create the key inside a workspace in the Claude Console and save that one. Naming the workspace in OAR is planned.
• Models without a price. A model Claude Code has no price for, currently Claude Haiku 5.5, shows no price known on the card. Its tokens are left out of the estimate and of the cap.
• The estimate is this relay's. Other use of the key is not in it; the Console has every request.
• No balance. OAR does not read the Console balance or the plan's API credit.
• No base URL. The key goes to https://api.anthropic.com only. There is no setting for another endpoint.
• The agent can read the key. See Security.

Error codes #

A failed Claude API reply ends with Error code: relay.<code>. and, for some codes, buttons that go straight to the fix:

Claude API settings opens Settings → Providers → Claude API. Add funds and Console billing open the Console's billing page, Console limits its limits page. Switch to subscription moves the chat to your subscription from its next turn; send the message again.

The relay's own refusals have codes too:

Troubleshooting #

Security #

Where the key is kept. The key is stored in the relay's database on the relay's machine and never sent to a browser: the tab only says that one is saved. The relay uses it itself for one request, the model list, and sends it to https://api.anthropic.com and nowhere else. It reaches only the workers of Claude API chats, where sessions run under tmux through a file only the relay's user can read. Inside the worker it reaches Claude Code in its environment and in settings handed over on its standard input, never on its command line, which other users of the machine can read. A key in the relay's own environment (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN) reaches no chat.

What the agent can see. The agent's own commands can read the key from their environment, as with any key a CLI holds. The relay replaces the key with [redacted] in everything a worker posts and in the worker's log, from the moment it is saved, as for DeepSeek. That keeps it out of what OAR stores and shows; it is no barrier against the agent.

The credential is checked, and one model request can go first. A Claude API chat shares the Claude Code folder where your Claude login lives. The relay pins the saved key above any credential in that folder's or the chat folder's settings, and when Claude Code's start report names another source for its key, the relay stops the turn at once (relay.claude-api-key-source). Claude Code does not wait for that check: it sends its first model request some 50 to 90 ms after the report, so one model request may already have gone out on the other credential, for example your Claude login, before the stop lands. The check limits a wrong credential to that one model request; it does not prevent it. The same check runs the other way in a chat on your subscription; see Claude.

No hooks. Claude Code in a Claude API chat starts with all hooks off: neither your own (~/.claude) nor the chat folder's (.claude/settings.json, settings.local.json) nor a plugin's run, and no status line command does. They would run as the relay's user with the key in their environment. The setting is on Claude Code's command line, so a settings file cannot turn them back on. Hooks in managed settings, the machine administrator's, still run. Chats on your subscription keep their hooks and status line.

What goes to Anthropic. Everything the agent reads and writes during a turn, as in a subscription chat.

More on Security.