# How OpenClaude Derives Runtime Metadata for LLM Requests: Environment-to-Request Pipeline

> Discover how OpenClaude derives runtime metadata for LLM requests. Learn about the four-step pipeline that aggregates environment variables, routing, catalog entries, and provider settings.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: internals
- Published: 2026-09-02

---

**OpenClaude derives runtime metadata for LLM requests through a deterministic four-step pipeline that aggregates environment variables, resolves routing configurations, merges catalog entries, and infers provider-specific OpenAI-shim settings to produce a complete `OpenAIShimRuntimeContext` object.**

OpenClaude implements a sophisticated configuration resolution system to standardize interactions with diverse LLM providers. When preparing an API call, the framework must derive comprehensive runtime metadata for LLM requests that captures routing logic, model capabilities, and transport-specific overrides. This process centers on [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts), which orchestrates environment detection, route resolution, and configuration merging to ensure every request carries the correct parameters.

## The Four-Step Derivation Pipeline

The runtime metadata derivation follows a strict logical sequence defined in [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts), transforming raw environment inputs into structured execution context.

### Step 1: Gathering Environment Information

The pipeline begins with `resolveOpenAIShimRuntimeContext`, which reads the current process environment (or an optional `processEnv` override) to capture critical variables such as `OPENAI_BASE_URL` and `OPENAI_MODEL`. This function establishes the baseline configuration by detecting any explicit user overrides before proceeding to route resolution.

### Step 2: Resolving the Active Route

Once environment variables are captured, the system determines which provider route to use through `resolveActiveRouteIdFromEnv`. This function inspects `OPENAI_ROUTE_ID`, `OPENAI_PROFILE`, and provider-specific environment variables to locate the appropriate route.

If a `baseUrl` parameter is supplied, `resolveRouteIdFromBaseUrl` can force route selection to match that endpoint, while `preferBaseUrlRoute` implements precedence logic that prioritizes explicit base URLs over profile-based configurations.

### Step 3: Pulling Catalog and Descriptor Data

With a finalized `routeId`, the resolver pulls three critical data structures from the integration registry:

- **RouteDescriptor** via `getRouteDescriptor`: Contains static transport configuration including default OpenAI-shim settings.
- **ModelCatalogEntry** via `getCatalogEntryForModel`: Matches the model name against the catalog, resolving aliases and provider-mapped identifiers.
- **ModelDescriptor** via `getModelDescriptorForCatalogEntry`: Provides provider-specific context window sizes and maximum output token limits.

### Step 4: Assembling the Final Runtime Metadata

The final assembly phase merges three layers of OpenAI-shim configuration using `mergeOpenAIShimConfig`:

1. **Base configuration** from the route descriptor (`descriptor?.transportConfig.openaiShim`).
2. **Catalog overrides** from the entry (`catalogEntry?.transportOverrides?.openaiShim`).
3. **Inferred configuration** via `inferRemoteModelOpenAIShimConfig`, which applies heuristics based on model strings (e.g., `glm-5.2`, `deepseek`, `kimi`) to set fields like `preserveReasoningContent`, `maxTokensField`, and `removeBodyFields`.

After merging, `resolveRouteOpenAIShimConfig` sanitizes attribution headers (such as those for the `aimlapi` partner) and returns a complete `OpenAIShimRuntimeContext` object containing the resolved `routeId`, `descriptor`, `catalogEntry`, and the fully merged `openaiShimConfig`.

## From Metadata to Request Limits

The derived runtime metadata feeds directly into model limit resolution through `resolveModelRuntimeLimits` in [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts). This function extracts concrete `contextWindow` and `maxOutputTokens` values from the `ModelDescriptor`, falling back to the **catalog entry** limits if the descriptor lacks specifications, and finally defaulting to global constants like `CLAUDE_CODE_MAX_OUTPUT_TOKENS` for Claude models or permissive upper bounds for unknown providers.

In [`src/utils/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/context.ts), the `buildRequestContext` function orchestrates this integration:

```typescript
// src/utils/context.ts (excerpt)
import { resolveOpenAIShimRuntimeContext } from '../integrations/runtimeMetadata.js';
import { resolveModelRuntimeLimits } from '../integrations/runtimeMetadata.js';

export async function buildRequestContext(opts) {
  const shimCtx = resolveOpenAIShimRuntimeContext(opts);
  const limits   = await resolveModelRuntimeLimits(shimCtx.catalogEntry);
  // …use shimCtx.openaiShimConfig + limits to shape the payload
}

```

## Practical Implementation Examples

### Manual Resolution for a Gemini Model

```typescript
// Example 1 – Manually resolve a runtime context for a Gemini model
import { resolveOpenAIShimRuntimeContext } from '@/integrations/runtimeMetadata.js';

const ctx = resolveOpenAIShimRuntimeContext({
  baseUrl: 'https://generativelanguage.googleapis.com',
  model:   'gemini-1.5-pro',
  treatAsLocal: false,
});

console.log(ctx.routeId);               // “gemini”
console.log(ctx.catalogEntry?.id);       // “gemini-1.5-pro”
console.log(ctx.openaiShimConfig);      // merged shim config for Gemini

```

### Using Context During Request Preparation

```typescript
// Example 2 – Using the context while sending a request
import { buildRequestContext } from '@/utils/context.js';
import { requestExecutor } from '@/services/api/openaiShim/requestExecutor.js';

const requestOpts = {
  baseUrl: process.env.OPENAI_BASE_URL,
  model:   process.env.OPENAI_MODEL,
};

const ctx = await buildRequestContext(requestOpts);
const response = await requestExecutor({
  url: `${ctx.openaiShimConfig.baseUrl}/v1/chat/completions`,
  body: {
    model: ctx.openaiShimConfig.model ?? requestOpts.model,
    max_tokens: ctx.openaiShimConfig.maxTokensField
      ? ctx.openaiShimConfig.maxTokensField
      : undefined,
    // …other fields are taken from ctx.openaiShimConfig
  },
});

```

### Inspecting Derived Limits Directly

```typescript
// Example 3 – Inspecting the derived limits directly
import { resolveModelRuntimeLimits } from '@/integrations/runtimeMetadata.js';

const limits = await resolveModelRuntimeLimits(
  // Provide a catalog entry (or null) to get concrete limits
  {
    modelDescriptorId: 'gemini-1.5-pro',
    // …
  },
);
console.log(limits.contextWindow);   // e.g. 8192
console.log(limits.maxOutputTokens); // e.g. 2048

```

## Summary

- OpenClaude derives runtime metadata for LLM requests through a deterministic pipeline defined in [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts).
- The process follows four steps: environment gathering, route resolution, catalog data retrieval, and multi-layer configuration merging.
- **Route descriptors** provide base transport settings, while **model catalog entries** supply overrides and capability limits.
- The `inferRemoteModelOpenAIShimConfig` heuristic automatically configures provider-specific fields based on model name patterns.
- Final metadata consumption occurs in [`src/utils/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/context.ts), which combines shim configuration with resolved model limits to shape API payloads.
- Unit tests in [`src/integrations/runtimeMetadata.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.test.ts) and [`src/integrations/runtimeMetadata.modelLimits.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.modelLimits.test.ts) verify correct merging, inference, and fallback behaviors.

## Frequently Asked Questions

### What is the entry point for deriving runtime metadata in OpenClaude?

The primary entry point is `resolveOpenAIShimRuntimeContext` in [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts). This function accepts an optional environment override and returns a complete `OpenAIShimRuntimeContext` object containing the resolved route, catalog entry, and merged OpenAI-shim configuration.

### How does OpenClaude handle conflicting route configurations between environment variables and base URLs?

When both a profile (via `OPENAI_PROFILE`) and a `baseUrl` are present, the `preferBaseUrlRoute` logic prioritizes the explicit base URL over profile-based routing. The `resolveRouteIdFromBaseUrl` function can force route selection to match the provided endpoint URL, ensuring direct API endpoints take precedence over configured profiles.

### Where are model-specific token limits defined in the runtime metadata pipeline?

Token limits originate from the `ModelDescriptor` retrieved via `getModelDescriptorForCatalogEntry` in [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts). If the descriptor lacks explicit values, `resolveModelRuntimeLimits` falls back to the `ModelCatalogEntry` specifications, then to global defaults like `CLAUDE_CODE_MAX_OUTPUT_TOKENS` for Claude models or permissive upper bounds for unknown providers.

### How does the system infer configuration for unknown or remote models?

The `inferRemoteModelOpenAIShimConfig` function in [`src/integrations/runtimeMetadata.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/runtimeMetadata.ts) analyzes model name strings (such as `deepseek`, `kimi`, or `moonshot`) to automatically apply provider-specific settings. This heuristic determines fields like `preserveReasoningContent`, `maxTokensField`, and `removeBodyFields` without requiring explicit catalog entries for every possible model variant.