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

The authoritative routing contract for gateway descriptors in OpenClaude is defined by the GatewayDescriptor interface located in 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. 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 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.

// 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:

// 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 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 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. 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 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.

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