Refined Custom Preset

Fully customizable Claude Code API preset that allows granular control over model routing, token limits, and endpoint configuration.

When to Use This Setting

Apply this setting when you need to:

• Connect Claude Code to a custom API endpoint such as a self-hosted proxy or third-party gateway
• Override default model parameters including temperature, max tokens, and system prompts at the API level
• Create a reusable API configuration that can be shared across team members via version control

Consider alternatives when:

• Standard Anthropic, Bedrock, or Vertex configurations already meet your API routing needs
• You require only model selection changes without custom endpoint routing

Quick Start

Configuration

Copy
name: refined-custom-preset
type: setting
category: api

Example Application

Copy
claude setting:apply refined-custom-preset

Example Output

Setting applied successfully. Configuration changes:
- ANTHROPIC_BASE_URL: custom endpoint configured
- ANTHROPIC_MODEL: custom model set
- Token limits: adjusted per configuration

Core Concepts

Custom API Routing Overview

Aspect	Details
Endpoint	Any OpenAI-compatible or Anthropic API
Authentication	API key, bearer token, or custom header
Model Override	Full model ID customization
Rate Limiting	Configurable per-endpoint thresholds
Fallback	Optional secondary endpoint on failure

Custom Preset Architecture

┌──────────────┐     ┌──────────────────┐
│  Claude Code │     │  Custom Endpoint  │
│              │────>│  ┌────────────┐   │
│  Settings:   │     │  │ Auth Layer │   │
│  - base_url  │     │  └─────┬──────┘   │
│  - model     │     │  ┌─────┴──────┐   │
│  - tokens    │     │  │ Model Route│   │
│              │     │  └─────┬──────┘   │
└──────────────┘     │  ┌─────┴──────┐   │
                     │  │ Response   │   │
                     │  └────────────┘   │
                     └──────────────────┘

Configuration

Parameter	Type	Default	Description
ANTHROPIC_BASE_URL	string	api.anthropic.com	Custom API endpoint URL
ANTHROPIC_AUTH_TOKEN	string	none	Authentication token for custom endpoint
ANTHROPIC_MODEL	string	claude-sonnet-4-5	Primary model identifier for requests
ANTHROPIC_SMALL_FAST_MODEL	string	claude-3-5-haiku	Secondary model for fast operations
MAX_OUTPUT_TOKENS	string	16384	Maximum tokens per response from endpoint

Best Practices

1. Validate Endpoint Compatibility - Before applying the preset, send a test request to your custom endpoint using curl to confirm it accepts the Anthropic message format. Incompatible endpoints will cause silent failures or malformed responses.

2. Use Environment Variable References - Store sensitive values like API keys as environment variable references rather than hardcoded strings. This prevents credentials from being committed to version control when sharing preset files.

3. Configure Sensible Token Limits - Set max output tokens based on your endpoint's capabilities and your billing constraints. Custom endpoints may have different token limits than the standard Anthropic API, and exceeding them causes truncated responses.

4. Implement Health Checks - Add a lightweight health check script that runs before each session to verify the custom endpoint is reachable. This provides clear error messages instead of cryptic timeout failures during coding sessions.

5. Document Model Mappings - When your custom endpoint uses different model identifiers than Anthropic's standard naming, maintain a mapping document. This helps team members understand which underlying model they are using and its capability differences.

Common Issues

1. Authentication format mismatch - Custom endpoints may expect different auth header formats (Bearer vs x-api-key). Check your endpoint documentation and adjust the ANTHROPIC_AUTH_TOKEN format accordingly.

2. Streaming not supported - Some proxy endpoints do not support server-sent events for streaming. If responses appear to hang, check whether your endpoint supports streaming and disable it if necessary.

3. Model ID not recognized - Custom endpoints may use different model naming conventions. Verify the exact model identifier string your endpoint expects and update ANTHROPIC_MODEL to match precisely.