OpenClaude

OpenClaude supports multiple model providers. You can configure them using the /provider command inside the CLI.

• OpenAI: Recommended for the easiest cloud setup if you have an OpenAI API key.
• Ollama: Best for running models locally without depending on a cloud API. Requires Ollama to be installed and running.
• Codex: Use this if you already use the Codex CLI or have Codex/ChatGPT authentication configured.
• Other supported providers: DeepSeek, Gemini.

The OpenClaude integration system is divided into three distinct layers to maintain separation of concerns:

1. Metadata (Descriptors): Files that declare labels, defaults, catalogs, setup requirements, validation hints, and request-shaping metadata. This is where you define what a route is.
2. Routing: Helpers that map user configuration, presets, and environment state onto the active descriptor route.
3. Transport: Runtime execution code that performs the actual request using a specific transport family. This is where you define how a request is executed against an external API.

When making changes, determine if the change affects the route definition (Metadata) or the execution logic (Transport).

When modeling a new route, choose the descriptor type based on the nature of the endpoint to ensure correct routing and behavior:

• VendorDescriptor: Use when the route is the canonical direct vendor API.
• GatewayDescriptor: Use when the route hosts, proxies, or aggregates models behind its own endpoint contract.
• AnthropicProxyDescriptor: Use when the route accepts Anthropic-native traffic through its own Anthropic-style environment contract.
• ModelDescriptor: Use for shared model metadata (what a model is), not for defining route availability (where a model is offered).

// Use define* helpers from src/integrations/define.ts
// and default-export the descriptor.

// Example conceptual usage:
export default defineVendorDescriptor({
  // ... descriptor config
});

For gateways and custom routes, the transportConfig.kind field is the authoritative routing contract used by the runtime to select the correct transport family.

Do not use the category field for routing decisions. The category field is purely descriptive metadata used for grouping or display (e.g., local, hosted, aggregating).

Common values for transportConfig.kind include:

• 'openai-compatible'
• 'local'
• 'anthropic-proxy'
• 'bedrock'
• 'vertex'

To indicate that a model is capable of reasoning or 'thinking', use the following metadata:

• classification: ['reasoning']
• capabilities.supportsReasoning: true

Warning: Adding these fields does not automatically enable /effort request mutation. You must verify the model's exact control surface (accepted/rejected levels and thinking-disable formats) for the specific route before adding this metadata.

When looking up model information, the system follows this precedence order:

1. Route-owned catalog metadata: The primary source for what a specific route offers.
2. Shared model-descriptor enrichment: Metadata pulled from a shared descriptor when a catalog entry references a modelDescriptorId.
3. Global shared model descriptors: Found in src/integrations/models/ (used for legacy or custom OpenAI-compatible names).
4. User overrides:
   • Environment variables: CLAUDE_CODE_OPENAI_CONTEXT_WINDOWS and CLAUDE_CODE_OPENAI_MAX_OUTPUT_TOKENS.
   • settings.json: The modelLimits map.

Control how frequently discovered models are refreshed using discoveryCacheTtl and discoveryRefreshMode.

Discovery Cache TTL (discoveryCacheTtl)

Use human-readable strings:

• 30m: For fast-changing catalogs.
• 1h: For moderately active hosted routes.
• 1d: For stable hosted or local routes with low churn.

Discovery Refresh Mode (discoveryRefreshMode)

• manual: For flaky or rate-limited providers; refresh only on demand.
• on-open: The picker always attempts a fresh list when opened.
• background-if-stale: The standard choice for hosted gateways; cached models appear immediately while refreshing in the background.
• startup: For fast local routes where probing at startup is cheap and useful.

OpenClaude manages reasoning (thinking) capabilities on a per-model basis. To enable control over reasoning effort via the /effort command, you must provide a reasoning object in the model's metadata.

Key Concepts:

• capabilities.supportsReasoning: A boolean flag indicating the model is capable of reasoning. This does not automatically enable request mutation (like changing effort levels).
• reasoning: The control surface that defines how OpenClaude interacts with the model's reasoning parameters.

Metadata Schema:

reasoning: {
  mode: 'levels' | 'toggle' | 'always-on'
  levels?: ReasoningEffortLevel[] // e.g., ['high', 'xhigh']
  defaultLevel?: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
  wireFormat?: 'reasoning_effort' | 'deepseek_compatible' | 'zai_compatible' | 'none'
  disableFormat?: 'thinking_type_disabled'
}

The transportConfig.kind field on a route descriptor is the authoritative selector for the transport family. If you need to determine how a route executes requests or if the underlying protocol differs, inspect transportConfig.kind.

Common transport examples include:

• Anthropic-native
• Anthropic-proxy
• OpenAI-compatible
• local
• Gemini-native
• Bedrock
• Vertex

Note that an Anthropic Proxy is a specific descriptor type for third-party endpoints that accept Anthropic-native requests through a non-Anthropic endpoint/auth contract, and is distinct from an OpenAI-compatible gateway.