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#

Ensure the following prerequisites are met before configuring Claude:

• An organization exists and at least one Active provider is configured.
• 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>"
     }
   }
   

   

3. Configure the values:

   

   Note

   Replace the /v1 suffix with /anthropic in the Base URL.

   • ANTHROPIC_BASE_URL

     • In OptScale AI Chat, select the provider and model you want to connect. Open Connect this model to external tools → OPENAI-COMPATIBLE and copy the Base URL value.
     • Replace the /v1 suffix with /anthropic.
     • Paste the resulting value into ANTHROPIC_BASE_URL.

     Example:

     https://my.optscale.ai/llm_proxy/.../v1
     

     ↓

     https://my.optscale.ai/llm_proxy/.../anthropic
     

   • ANTHROPIC_AUTH_TOKEN

     • In OptScale AI Chat, copy the API key value.
     • Paste the copied value into ANTHROPIC_AUTH_TOKEN.

   • ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_OPUS_MODEL

     • In OptScale AI Chat, copy the Model name value.
     • Paste the copied value into the variable corresponding to the Claude Code tier.

At least one of the model variables must be configured. If multiple variables are configured, Claude Code uses the corresponding model for each tier.

For example:

• 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

The following example configures only the Haiku tier:

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

4. Save the file.

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

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

Connect Claude Desktop#

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

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

   

3. In Connection, select Gateway from the provider dropdown.

   

4. Enter the gateway connection values:

   

   • Base URL:

     • In OptScale AI Chat, select the provider and model you want to connect. Open 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/.../v1
       

       ↓

       https://my.optscale.ai/llm_proxy/.../anthropic
       

     • Paste the resulting value into Gateway base URL.

   • API key:

     • In the Connect this model to external tools → OPENAI-COMPATIBLE dialog in OptScale AI Chat, copy the API key value.

       

     • Paste the copied value into Gateway API key.

5. Configure models in Connection → Models:

   • Enable Model discovery if you want Claude Desktop to auto-populate the model picker from the gateway.

     

   • Add one or more models manually in Model list. Fill in Model ID and Display name:

     

     • Model ID — In OptScale AI Chat, copy the Model name value.

       

     • Display name — Enter a descriptive label for the model. For example, Claude Sonnet via OptScale AI.

6. Click Apply Changes. When prompted, click Save & Restart to relaunch Claude Desktop with the new configuration.

   

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

Verify the connection#

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

Claude setup notes#

• Use providers and models allowed for the user.

• Prefer models that support tool execution when using Claude tools.

See also#

• Get connection values from Chat — Shared Base URL, API key, and model values.
• External Tools — Overview and shared limitations.
• Connect Cursor — Point Cursor IDE at the gateway.
• Core Services — Traces — Verify requests after connecting.