The Narrow Waist: Metadata, Routing, and Transport
OpenClaude's central architecture question is simple to state: when a user selects a model, how does the system know what that choice means and how to send it a request? This chapter follows OpenClaude from provider description to active route to wire protocol. The practical result is a vocabulary readers can use to tell whether a change is a harmless model selection, a route change, or a transport change that may alter the entire interaction.
The chain from intent to wire protocol
The word “provider” is too broad to describe what happens inside OpenClaude. A vendor is the service that owns a model API or serves its own models. A gateway is an endpoint that hosts, proxies, or aggregates models behind its own contract. A model is a particular generation engine. A route is the selectable integration surface that joins an endpoint, a model catalog, setup rules, and a transport. Transport is the request-and-response protocol used to communicate with that route.
These terms form a chain rather than a set of competing labels. A gateway may expose a model from another vendor. A route may expose only some of the models available from that vendor. The same model family may have different API names, context limits, authentication rules, or reasoning controls on different routes. OpenClaude needs to preserve those relationships long enough to construct the right request.
The repository's integration architecture does this through typed descriptors. A descriptor is metadata about an integration, not the integration's request executor. It can state a route's label, default endpoint, default model, authentication mode, credential variables, catalog, discovery policy, capabilities, validation hints, and transport configuration. The distinction matters because describing a route and executing a request answer different questions:
- Metadata: What is this route, what does it offer, and what does it say it supports?
- Routing: Which route is active for the user's preset, profile, environment, or base URL?
- Transport: How must this request be shaped and sent to the active endpoint?
Suppose a user selects a model through a saved profile. The profile supplies user intent: use this endpoint, credential, and model. Route resolution maps that profile to a known route when possible. The route descriptor supplies defaults and catalog information. Runtime metadata combines the route, the selected catalog entry, and any verified model-specific settings. Only then does transport code decide how to serialize messages, tools, images, reasoning information, and authentication.
This is a narrow waist because many higher-level actions pass through a small set of stable decisions. The user can think in terms of a coding task and a chosen model. The lower layers still need to know whether the route is local, OpenAI-compatible, Anthropic-native, Gemini-native, Bedrock, Vertex, or an Anthropic-compatible proxy. The narrow waist keeps the agent workflow from reimplementing every provider's catalog and environment rules, while allowing transport code to respect the real API contract.
The route's transport kind is the decisive field for that purpose. OpenClaude's integration documentation explicitly treats transportConfig.kind as the routing contract. A route marked openai-compatible enters a different execution family from one marked bedrock or vertex. By contrast, a gateway's category—such as local, hosted, or aggregating—is descriptive grouping metadata. It can help organize a picker or explain a route to a contributor, but it must not decide which runtime path receives the request.
This distinction prevents a subtle but consequential error. An aggregating gateway can still speak the OpenAI-compatible protocol, while a hosted route can use a dedicated native SDK. “Hosted” says where the service runs or how it is grouped. It does not say how messages and tools must be serialized. If category were used as the execution selector, two routes with the same presentation label could be sent through incompatible request logic.
The architecture is also loader-owned. Normal descriptor files define typed data through helper functions; generated artifacts and the integration loader make those descriptors available to registry consumers. The loader can defer evaluation until registry information is needed. This arrangement is less important as a file organization rule than as an ownership rule: route definitions describe the integration, while registration and runtime lookup remain centralized. New integration metadata therefore has one intended home instead of a separate provider switch in every consumer.
That centralization does not mean the compatibility layer disappears. OpenClaude still supports environment variables, saved profiles, legacy provider names, and older callers. The architecture documentation describes those bridges as temporary or transitional surfaces around a more precise descriptor model. They are evidence that public configuration contracts often outlive the internal representation, not evidence that the descriptor boundary is unnecessary.
Why the catalog belongs to the route
A global list of model names looks convenient, but it cannot answer the questions a coding agent needs answered. Is the model offered by this endpoint? What API name should be sent? Does this route expose tool calling, reasoning, or vision? What context window and output limit apply here? Is the model available only during a time-limited launch? A route-owned catalog keeps those facts attached to the endpoint that can actually serve the request.
OpenClaude supports static, dynamic, and hybrid catalogs. A static catalog is useful when a vendor publishes a stable, curated set of models whose capabilities and limits can be recorded in advance. A dynamic catalog discovers models from an endpoint. A hybrid catalog keeps curated entries for stable labels and model metadata while refreshing the available set from the route. The choice is not merely a user-interface preference; it expresses how much the route's reality changes outside the client release cycle.
OpenRouter and Gitlawb Opengateway illustrate why this matters. Their public model-list endpoints can provide discovery without requiring an inference credential, while actual chat requests still require authentication. A discovered list can therefore improve the model picker without proving that a request will succeed for the current account. The OpenRouter mapping also filters out non-text-oriented routes and records signals such as tool or reasoning support when the public payload provides them. OpenGateway maps public model entries, preserves route-facing names, and can apply route-specific transport metadata to selected entries.
Ollama shows a different form of route ownership. Its route is local and can discover models from the local service, but readiness is also a concern: the server must be running and a model must be loaded. The catalog describes what the service exposes; a readiness probe tests whether the local route can actually participate. A cloud gateway can be reachable yet deny inference because of credentials or quota. A local route can have a model installed in theory yet fail because the server is unavailable. Discovery and readiness are related, but they are not the same fact.
The catalog also carries identity that cannot safely be inferred from a familiar name. A route may expose an API alias that differs from the shared model identity. The descriptor model allows a catalog entry to point to shared model metadata while retaining the route's own API name. This lets OpenClaude reuse family-level information without pretending that route availability is global. In the other direction, the absence of a catalog entry does not establish that a provider cannot serve a model; it may indicate only that discovery or curation has not recorded it. The runtime must distinguish “not known here” from “not supported.”
Context and output limits follow the same logic. A provider may advertise one value for a model, while a gateway or deployment imposes another. OpenClaude can use catalog values, discovery values, and explicit overrides, but its documentation warns that a gateway's advertised context can be wrong or flat across models. The client keeps the advertised value unless the user supplies a more authoritative exact override, because budgeting above an endpoint's real limit can turn early compaction into a mid-session request failure. This is a useful example of a system choosing a conservative operational assumption rather than pretending to know the external truth.
Time can matter as well. The descriptor schema supports an availability deadline for entries that are known to disappear after a launch or promotional window. That client-side guard keeps the picker from offering an entry the gateway is expected to reject after the deadline. It does not make the provider's clock or server-side policy reliable; it only lets the client avoid one known stale choice.
The abstraction stops at protocol differences
Once metadata and catalogs have selected a route, transport code has to honor the external contract. OpenClaude's OpenAI-compatible shim provides the broadest example. The rest of the application can use an Anthropic-shaped client boundary, while the shim converts messages and tools into OpenAI-compatible requests and converts streamed responses back into Anthropic-style stream events. Tool schemas may need normalization. Image blocks may need a route-specific representation. Reasoning content may need to be preserved or omitted. Token fields, headers, body fields, and API paths can differ by route or model.
This is interoperability, not magic. A route can accept the general OpenAI-compatible shape while rejecting a field that another gateway accepts. One model family may require reasoning content when its assistant message is echoed back; another endpoint may reject that same field. An endpoint may support chat completions but not a Responses-style request, or it may require the latter for a particular model. These details belong below the agent loop because they are request-contract facts, but they must remain visible in route metadata so the shim does not guess from a model name alone.
The repository documents several intentional exceptions. GitHub can be a dual-mode route: Claude models may use Anthropic-native message behavior while Copilot or GitHub Models traffic follows OpenAI- or Codex-style behavior. Mistral has dedicated environment selection and request shaping. Azure OpenAI and Bankr use distinct authentication or header contracts. Gemini has provider-specific credential handling and thought-signature behavior. DeepSeek and Moonshot/Kimi require route-specific handling for reasoning content and token fields. Bedrock, Vertex, and Foundry use dedicated Anthropic-family SDK and authentication flows rather than the generic OpenAI-compatible transport.
The important architectural lesson is not that exceptions are unfortunate leftovers. Some are compatibility bridges that may shrink as public configuration changes. Others are durable protocol differences created by external services. The integration documentation tells contributors to distinguish those cases before moving behavior. Removing a branch because it looks repetitive can be a regression if the external API contract is genuinely different.
The same principle governs native web search and conversation recovery. Native web search is valid only on particular Anthropic-family and Codex paths, not on every route that can generate text. Thinking blocks may need to be preserved for native transports but stripped when an OpenAI-compatible route cannot accept them. A common upper-layer feature name therefore does not imply a common lower-layer operation.
OpenClaude's design is strongest when it tells the truth about this stopping point. Descriptors can centralize labels, defaults, catalogs, validation, and capability flags. Routing can map user configuration to an active route. Runtime metadata can combine route and model facts. Transport can then execute the real contract. None of those layers can make an endpoint support a feature it does not implement.
That boundary changes how to read a provider addition. The work is not complete when a new URL appears in a menu. The route also needs an identity, credential policy, model catalog or discovery strategy, validation behavior, transport configuration, and any exceptions required by the API. Recent project changes emphasize live model lists, hybrid gateways, cost and context controls, and provider-specific fixes alongside new integrations. The growing challenge is coherence across the matrix, not merely breadth.
The conclusion is a practical rule for users and contributors alike: ask three questions in order. What does this route claim to be and offer? How did OpenClaude resolve it from the current configuration? Which transport contract will actually carry the request? If those answers are clear, portability can be controlled. If they are collapsed into a model name or a marketing category, a failure will be difficult to diagnose and a successful request may still conceal a capability mismatch.