How Gateway Routing Works in OpenClaude Based on transportConfig.kind

OpenClaude routes requests to appropriate backends by inspecting the transportConfig.kind field in route descriptors, directing traffic to either OpenAI-compatible gateways or local providers based on this configuration value.

The Gitlawb/openclaude repository implements a dynamic routing system that determines request handling through transport metadata. By analyzing the transportConfig.kind property stored in route descriptors, the application decides whether to forward requests to external gateways or execute them against local models.

Understanding transportConfig.kind in Route Metadata

The core routing intelligence resides in src/integrations/routeMetadata.ts, which serves as the central registry for route descriptors and transport configurations.

Route Descriptor Structure

Each route descriptor retrieved via getRouteDescriptor(routeId) contains a nested transportConfig object. This configuration houses the kind field that categorizes the transport mechanism for that specific route. The system uses this field as the primary discriminator for routing decisions.

Supported Transport Kinds

The router recognizes two primary values for transportConfig.kind:

• 'openai-compatible' – Indicates the route targets an external OpenAI-compatible gateway (e.g., Opengateway or ApiSmart)
• 'local' – Indicates the route handles requests via a locally-hosted model or process

Any other value triggers fallback handling or rejection, depending on higher-level validation logic.

The Gateway Routing Decision Flow

The routing process follows a three-step validation pattern implemented in src/integrations/routeMetadata.ts.

Step 1: Retrieve the Route Descriptor

When processing a request, the system first obtains the active route's complete descriptor using getRouteDescriptor(routeId). This descriptor encapsulates all transport configuration details required for routing decisions.

Step 2: Check transportConfig.kind

At lines 1093-1094 in src/integrations/routeMetadata.ts, a predicate evaluates whether transportConfig.kind equals 'openai-compatible' or 'local'. This boolean check determines if the route qualifies for gateway-compatible handling paths. Only routes matching these kinds proceed through the gateway routing pipeline.

Step 3: Expose Kind to Downstream Callers

The helper function getRouteTransportKind(routeId) extracts and returns the kind value (or null if undefined) at line 1476. This abstraction allows other modules to make routing decisions without directly accessing the descriptor structure.

Provider Validation and Gateway Construction

Beyond initial routing, transportConfig.kind enforces validation constraints and construction requirements across the codebase.

Validating Gateway-Specific Overrides

In src/utils/providerValidation.ts (line 527), the validateProvider function ensures that gateway-specific overrides are applied exclusively to routes where transportConfig.kind === 'openai-compatible'. This validation prevents incompatible provider configurations from receiving OpenAI-specific transformations that would cause runtime errors.

Gateway Construction Verification

Test suites in src/integrations/gateways/opencode.test.ts (lines 79-163) assert that constructed gateway instances maintain the 'openai-compatible' kind. These tests verify that the routing contract remains intact during gateway instantiation, catching configuration mismatches at build time rather than during request processing.

Practical Implementation Examples

The following patterns demonstrate how to implement gateway routing logic using the OpenClaude metadata utilities:

// Resolve the transport kind for the active route
import { getRouteTransportKind } from '../integrations/routeMetadata';

const routeId = 'gitlawb-opengateway';
const kind = getRouteTransportKind(routeId);

if (kind === 'openai-compatible') {
  // Forward to the OpenAI-compatible gateway implementation
  await forwardToGateway(request);
} else if (kind === 'local') {
  // Run the request against a locally-hosted model
  await runLocalModel(request);
} else {
  // Fallback or error handling
  throw new Error(`Unsupported transport kind: ${kind}`);
}

// Provider validation that only allows gateway overrides for compatible kinds
import { validateProvider } from '../utils/providerValidation';
import { getRouteDescriptor } from '../integrations/routeMetadata';

function ensureGatewayOverrides(routeId: string) {
  const descriptor = getRouteDescriptor(routeId);
  if (descriptor.transportConfig.kind !== 'openai-compatible') {
    throw new Error(
      `Gateway overrides are only allowed for OpenAI-compatible transports (found ${descriptor.transportConfig.kind})`,
    );
  }
  // Continue with validation…
}

Summary

• Route descriptors in src/integrations/routeMetadata.ts store transport configuration metadata that drives routing decisions
• transportConfig.kind accepts 'openai-compatible' or 'local' values, with the predicate at lines 1093-1094 determining gateway eligibility
• getRouteTransportKind(routeId) provides a safe accessor for the kind value (line 1476), abstracting descriptor internals
• Provider validation enforces that gateway-specific overrides only apply to 'openai-compatible' routes (line 527 in src/utils/providerValidation.ts)
• Test coverage in src/integrations/gateways/opencode.test.ts verifies that gateways maintain the correct transport kind during construction

Frequently Asked Questions

What values can transportConfig.kind take in OpenClaude?

According to the source code in src/integrations/routeMetadata.ts, the routing logic explicitly recognizes 'openai-compatible' and 'local' as valid values for transportConfig.kind. The predicate at lines 1093-1094 checks for these specific strings to determine gateway compatibility. Other values trigger fallback handling or validation errors depending on the specific caller.

How does OpenClaude handle unsupported transport kinds?

When transportConfig.kind contains any value other than 'openai-compatible' or 'local', the routing system redirects the request to fallback provider logic or raises validation errors. The getRouteTransportKind helper returns null for undefined kinds, allowing callers to implement custom error handling or default behaviors as shown in the implementation examples.

Where is the gateway routing logic implemented?

The primary gateway routing logic resides in src/integrations/routeMetadata.ts, specifically within the getRouteDescriptor function and the kind-checking predicate at lines 1093-1094. Secondary validation occurs in src/utils/providerValidation.ts (line 527), which ensures gateway-specific overrides only apply to compatible transport configurations.

Why does provider validation check transportConfig.kind?

The provider validation system inspects transportConfig.kind to prevent incompatible routes from receiving OpenAI-specific transformations. As implemented in src/utils/providerValidation.ts at line 527, this check ensures that gateway overrides—such as header modifications or endpoint remapping—only apply to routes explicitly configured as 'openai-compatible', maintaining type safety and preventing runtime misconfigurations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}