# How Gateway Routing Works in OpenClaude Based on transportConfig.kind

> Understand how OpenClaude gateway routing works by inspecting transportConfig.kind. Direct traffic to OpenAI-compatible gateways or local providers with this guide.

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

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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:

```typescript
// 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}`);
}

```

```typescript
// 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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerValidation.ts))
- **Test coverage** in [`src/integrations/gateways/opencode.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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.