Claude Code

Before you begin

• Install the OpenLLM CLI. See Install.
• Install Claude Code so that claude is on your PATH. If it is missing, openllm claude prints the official installer, https://claude.ai/install.sh.
• Have at least one model available. See Providers.

If no API key is saved yet, the first run asks you to paste your sk-llm-… key and saves it to ~/.openllm/.env.

Set up with openllm claude

openllm claude

Every argument after claude goes to Claude Code unchanged, so openllm claude --resume behaves like claude --resume. OpenLLM's own flags go before the client name: -d, --new, and --attach [id].

At launch, OpenLLM picks a gateway: your local daemon at http://127.0.0.1:8787 if it answers, otherwise https://www.openllm.sh. It then starts the real claude binary with this session-only setup:

• Temporary files in ~/.openllm/run/claude/<pid>/, passed with --settings and --mcp-config. They are deleted when Claude Code exits.
• Environment: ANTHROPIC_BASE_URL points at the gateway. ANTHROPIC_DEFAULT_OPUS_MODEL=ultra, ANTHROPIC_DEFAULT_SONNET_MODEL=plus, and ANTHROPIC_DEFAULT_HAIKU_MODEL=lite. Your key reaches Claude Code through an apiKeyHelper script that reads it from the environment, so the key is never written to disk.
• Removed for the session: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and CLAUDE_CODE_OAUTH_TOKEN, so only one credential is active.
• Settings layered on yours: default model ultra, a status line with the directory and context use, and memory hooks that recall before each prompt and save after each turn. Your claude.ai connectors are turned off in these sessions.
• MCP: the openllm server (openllm mcp). See MCP server.

Your ~/.claude directory, login, history, and projects are untouched.

Interactive sessions run in a background session host. When you run openllm claude without arguments and a Claude Code session is already running on this machine, OpenLLM offers to attach to it. To always start fresh, run openllm --new claude. To list sessions, run openllm sessions list.

Set up without the CLI

openllm claude is the recommended path. To run Claude Code against OpenLLM without the OpenLLM CLI, set these variables in the shell that starts claude:

export ANTHROPIC_BASE_URL="https://www.openllm.sh"
export ANTHROPIC_AUTH_TOKEN="sk-llm-YOUR_KEY"
export ANTHROPIC_DEFAULT_OPUS_MODEL="ultra"
export ANTHROPIC_DEFAULT_SONNET_MODEL="plus"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="lite"
claude --model ultra

• Leave /v1 off ANTHROPIC_BASE_URL. Claude Code adds /v1/messages itself.
• ANTHROPIC_AUTH_TOKEN sends your key as Authorization: Bearer, and ANTHROPIC_API_KEY sends it as x-api-key. OpenLLM accepts either. Set only one of them.
• If you are also signed in to claude.ai, Claude Code can warn that two credentials are set. openllm claude avoids this by removing the other credentials for the session.
• To use the daemon on the same machine, set ANTHROPIC_BASE_URL="http://127.0.0.1:8787". See Use the local daemon.

A manual setup doesn't get the memory hooks, the status line, or the openllm MCP server. To add the MCP server yourself, see MCP server.

Choose models

Claude Code's three model slots map to OpenLLM aliases:

To pin a specific model, pass its id: openllm claude --model <provider/model>, or use /model inside a session. Get ids from GET /v1/models. To change what ultra, plus, and lite resolve to, edit the chains in Configuration. See Routing and fallback.

To turn off automatic memory, set MEMORY_AUTO_RECALL=0 or MEMORY_AUTO_SAVE=0. See Memory.

Who pays for a request

The model that serves the request decides. A Claude subscription hop runs on your own Claude login through the daemon on one of your devices. An API-key hop bills your provider account. Included openllm/ models count against your plan's allowance. See Providers and Plans and limits.

Check that it works

openllm claude -p "Reply with OK"

The reply prints to your terminal. Open Overview in the app: the request appears with the model that served it.

Common problems

For anything else, see Troubleshooting.

Remove it

There is nothing to uninstall. Exit Claude Code and run claude directly to use it without OpenLLM. Temporary files are deleted on exit; files left by a crashed launch are cleaned up on the next launch.

Last updated on