Connect Claude#

Connect Claude Code or Claude Desktop to OptScale AI so agent sessions use your organization's governed model catalog through the Anthropic-compatible gateway endpoint.

Works on Windows, Linux, and macOS.

In Chat, copy connection values from Get connection values from Chat (Connect this model to external tools → OPENAI-COMPATIBLE) before you configure Claude. For shared model naming rules and limitations, see External Tools overview.

Prerequisites#

Complete the following before configuring Claude (same baseline as Connect OpenCode):

An organization and at least one Active provider exist.
Allowed providers are assigned for the user connecting Claude to OptScale AI.
The cluster exposes a valid TLS certificate (HTTPS is required for the gateway Base URL).
When using Claude tools, select models that support tool execution.

Connect Claude Code#

1. Open or create the Claude Code user settings file:

For Windows: %USERPROFILE%\.claude\settings.json
For macOS and Linux: ~/.claude/settings.json

2. Add or update the env block:

{
  "env": {
    "ANTHROPIC_BASE_URL": "<Base URL>",
    "ANTHROPIC_AUTH_TOKEN": "<API key>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<haiku_model_name>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<sonnet_model_name>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<opus_model_name>"
  }
}

ANTHROPIC_BASE_URL — copy the Base URL value from OptScale AI Chat → Connect this model to external tools → OPENAI-COMPATIBLE and replace the /v1 suffix with /anthropic.

For example:

https://my.optscale.ai/llm_proxy/00000000-0000-0000-0000-000000000000/v1

↓

https://my.optscale.ai/llm_proxy/00000000-0000-0000-0000-000000000000/anthropic
ANTHROPIC_AUTH_TOKEN — copy the API key value from OptScale AI Chat → Connect this model to external tools → OPENAI-COMPATIBLE.
ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_OPUS_MODEL define the default models used for each Claude Code tier. At least one of these variables must be specified. Copy Model name value from OptScale AI Chat → Connect this model to external tools → OPENAI-COMPATIBLE.

If multiple variables are configured, Claude Code uses the corresponding model for each tier.

Examples:

ANTHROPIC_DEFAULT_HAIKU_MODEL: anthropic/claude-haiku-4-5
ANTHROPIC_DEFAULT_SONNET_MODEL: anthropic/claude-sonnet-4-6
ANTHROPIC_DEFAULT_OPUS_MODEL: anthropic/claude-opus-4-6

Example: The following configuration maps the Claude Code Haiku tier to the anthropic/claude-haiku-4-5 model. The Sonnet and Opus tiers are not configured.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://my.optscale.ai/llm_proxy/00000000-0000-0000-0000-000000000000/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-bf-...",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5"
  }
}

3. Run claude /logout, restart Claude Code, and then run /models. Confirm that the configured models appear in the list.

4. Send a test prompt and verify that the model responds without authentication errors.

Connect Claude Desktop#

1. Open Claude Desktop, enable Developer Mode: Help → Troubleshooting → Enable Developer Mode

2. Open the third-party inference settings: Developer → Configure Third-Party Inference

3. Enter the gateway connection values. In Connection → Gateway fill in:

Gateway Base URL: OptScale AI Chat → Connect this model to external tools → OPENAI-COMPATIBLE → copy the Base URL value and replace the /v1 suffix with /anthropic.

Example:

https://my.optscale.ai/llm_proxy/00000000-0000-0000-0000-000000000000/v1

↓

https://my.optscale.ai/llm_proxy/00000000-0000-0000-0000-000000000000/anthropic
Gateway API Key: OptScale AI Chat → Connect this model to external tools → OPENAI-COMPATIBLE → copy the API key value.

4. Add one or more models. In Connection → Models:

Model ID: OptScale AI Chat → Connect this model to external tools → OPENAI-COMPATIBLE → copy the Model name value.
Display Name: Enter a descriptive label for the model. For example, Claude Sonnet via OptScale AI.

5. Click Apply Changes. Claude Desktop restarts automatically.

6. Confirm that you are signed in to the Gateway account and that the configured models appear in the model selector.

Verify the connection#

Send a test prompt from Claude Code or Claude Desktop.
Confirm the model responds without authentication errors.
Check Traces in the OptScale AI Admin UI for the corresponding request.

Claude setup notes#

Note

Claude Code and Claude Desktop use a single Anthropic-compatible base URL and API key configuration at a time. When OptScale AI is configured as the endpoint, requests no longer go directly to Anthropic's public API.

Use providers and models allowed for the user.
Prefer models that support tool execution when using Claude tools.

After connecting Claude, you may want to:

Review shared connection values in Get connection values from Chat.
Read the broader External Tools overview.
Configure another client with Connect Cursor or Connect OpenCode.
Check setup requirements in First Steps.
Manage user access in Core Services — AI Access.
Monitor requests in Core Services — Traces.
Review Chat controls in Interface Overview.