# What Is the Authoritative Routing Contract for Gateway Descriptors in OpenClaude?

> Understand the authoritative routing contract for gateway descriptors in OpenClaude. Discover the GatewayDescriptor interface and its essential routes array for mapping endpoints to handlers.

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

---

**The authoritative routing contract for gateway descriptors in OpenClaude is defined by the `GatewayDescriptor` interface located in [`src/integrations/gateways/gitlawb-opengateway.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/gitlawb-opengateway.ts), which mandates the structure every gateway must implement—including the critical `routes` array that maps API endpoints to handler functions.**

In the **Gitlawb/openclaude** repository, the gateway system provides a pluggable architecture for connecting to different model providers. The **authoritative routing contract for gateway descriptors** establishes the single source of truth that governs how these gateways describe their capabilities to the core router. This contract ensures that any gateway added to the system conforms to a predictable structure, enabling seamless integration and routing of model-provider calls.

## Location and Definition of the Routing Contract

The definitive routing contract resides in [`src/integrations/gateways/gitlawb-opengateway.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/gitlawb-opengateway.ts). This file exports the `GatewayDescriptor` type, which serves as the immutable schema for gateway registration. The contract specifies six primary properties that define a gateway's identity and routing capabilities.

### Core Properties of GatewayDescriptor

Every gateway descriptor must supply the following properties to satisfy the contract:

- **`id`**: A unique string identifier used internally for gateway lookup and differentiation.
- **`name`**: Human-readable label displayed in CLI help outputs and user interfaces.
- **`description`**: Optional string providing context about the gateway's purpose or scope.
- **`routes`**: An array of `GatewayRoute` objects representing the **authoritative routing table**. This mandatory property declares every API endpoint the gateway implements.
- **`default`**: Optional boolean flagging the gateway as the fallback when no specific gateway is requested.
- **`configSchema`**: Optional JSON schema object validating custom configuration parameters specific to the gateway.

## The GatewayRoute Structure

Individual routes within the `routes` array follow the `GatewayRoute` type defined in the same file. Each route entry functions as a binding between an HTTP endpoint and its implementation logic.

### Required Route Properties

The contract mandates four critical properties for each route:

- **`path`**: The URL path pattern (e.g., `"/v1/chat/completions"`) that the gateway exposes.
- **`method`**: The HTTP verb restricted to `"GET"`, `"POST"`, `"PUT"`, or `"DELETE"`.
- **`handler`**: An async function receiving a `GatewayRequest` and returning a `Promise<GatewayResponse>`. This function contains the concrete logic for processing model-provider calls.
- **`auth`**: Optional authentication configuration specifying requirements such as API keys or OAuth tokens.

## Contract Enforcement During Registration

The `registerGateway` function in [`src/utils/model/modelOptions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/modelOptions.ts) enforces this contract at runtime. When loading a gateway, the function validates the supplied descriptor against the `GatewayDescriptor` interface, ensuring all required properties—particularly the `routes` array—are present and correctly typed.

Upon successful validation, the router constructs an internal lookup map keyed by the combination of `path` and `method`. All subsequent model-provider requests matching registered routes dispatch to the corresponding `handler` implementation. This validation prevents mismatched or outdated gateway definitions from entering the system.

## Implementing a Compliant Gateway

Developers create compliant gateways by importing the `GatewayDescriptor` type and exporting an object satisfying the contract. The following example demonstrates a complete gateway definition with a single chat completions route.

```typescript
// src/gateways/my-custom-gateway.ts
import { GatewayDescriptor } from '@/integrations/gateways/gitlawb-opengateway';

export const myGateway: GatewayDescriptor = {
  id: 'my-gateway',
  name: 'My Custom Gateway',
  description: 'Forwards requests to a private LLM server.',
  default: true,
  routes: [
    {
      path: '/v1/chat/completions',
      method: 'POST',
      handler: async (req) => {
        const response = await fetch('https://private-llm.local/v1/chat/completions', {
          method: 'POST',
          headers: req.headers,
          body: JSON.stringify(req.body),
        });
        return response.json();
      },
      auth: { type: 'apiKey', header: 'Authorization' },
    },
  ],
};

```

Registration occurs through the core utility:

```typescript
// Registration within the core system
import { registerGateway } from '@/utils/model/modelOptions';
import { myGateway } from '@/gateways/my-custom-gateway';

registerGateway(myGateway);

```

## Summary

- The **authoritative routing contract** is codified in [`src/integrations/gateways/gitlawb-opengateway.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/gitlawb-opengateway.ts) via the `GatewayDescriptor` interface.
- The contract mandates specific properties including `id`, `name`, and the critical `routes` array.
- Each route must specify `path`, `method`, and a `handler` function conforming to the `GatewayRoute` type.
- The `registerGateway` function in [`src/utils/model/modelOptions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/modelOptions.ts) validates all descriptors against this contract before adding them to the router.
- This architecture ensures a single source of truth for gateway capabilities across the entire OpenClaude ecosystem.

## Frequently Asked Questions

### Where is the authoritative routing contract defined in OpenClaude?

The contract is defined in [`src/integrations/gateways/gitlawb-opengateway.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/gitlawb-opengateway.ts). This file contains the TypeScript interfaces for `GatewayDescriptor` and `GatewayRoute`, establishing the mandatory structure that every gateway must implement to integrate with the OpenClaude router.

### What properties are required in a GatewayDescriptor?

A compliant `GatewayDescriptor` must include `id` (unique identifier), `name` (display name), and `routes` (array of route definitions). Optional properties include `description`, `default` (fallback flag), and `configSchema` (validation schema for custom configuration).

### How does OpenClaude validate gateway descriptors against the routing contract?

The `registerGateway` function in [`src/utils/model/modelOptions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/modelOptions.ts) performs runtime validation. It checks that the supplied object matches the `GatewayDescriptor` interface structure, verifies the presence of required properties, and ensures all routes conform to the `GatewayRoute` specification before registering the gateway with the internal router.

### Can a gateway define multiple routes in OpenClaude?

Yes. The `routes` property accepts an array of `GatewayRoute` objects, allowing a single gateway to expose multiple endpoints. Each route must define a unique combination of `path` and `method`, with its own `handler` function to process requests for that specific endpoint.