# What Is the Purpose of the Registry and Runtime Metadata in OpenClaude Integrations?

> Discover how OpenClaude integrations use registry and runtime metadata. Learn about static blueprints and dynamic capabilities for configuration validation and adaptive behavior.

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

---

**The registry stores static provider blueprints while runtime metadata tracks dynamic capabilities, together enabling OpenClaude to validate configurations at build time and adapt behavior during execution.**

The Gitlawb/openclaude repository separates provider definitions from live session data to support a modular, extensible integration architecture. Understanding how the **Integration Registry** and **runtime metadata** interact clarifies how the CLI discovers providers, validates models, and selects features like vision or tool support without hard-coding provider-specific logic.

## The Static Integration Registry

The registry serves as the compile-time source of truth for all supported AI providers, models, and integration tools.

### Registry Structure in src/utils/registry.ts

Located at [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts), the registry imports Zod schemas from [`src/integrations/types.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/types.ts) to enforce type safety across provider descriptors. Each entry maps a provider name to its static configuration, including environment variable names for authentication, default API endpoints, and base capability flags. This structure allows OpenClaude to import provider definitions by name rather than embedding URLs or secrets directly in command logic.

According to the source analysis, the registry holds these descriptors as immutable objects that the CLI consults during initialization to validate that a requested provider exists and that all required secrets are present in the environment.

### Type Safety and Provider Secrets

The [`src/utils/providerSecrets.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerSecrets.ts) file leverages the registry to resolve provider-specific environment variables. By referencing the registry’s static mappings, the secrets utility can prompt users for missing credentials without knowing the specific provider’s auth scheme ahead of time. This decoupling demonstrates how the registry abstracts provider implementation details from the core CLI workflow.

## Runtime Metadata and Dynamic Discovery

While the registry defines what *could* exist, runtime metadata captures what *actually* exists in the current execution context.

### Capturing Live Capabilities

When OpenClaude initializes a provider session, it populates runtime metadata structures with data fetched from the provider’s API. This includes the list of currently available models, per-model token limits, and dynamic capability flags such as `vision` or `toolUse`. The [`src/utils/providerProfiles.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfiles.ts) module caches this per-session information, ensuring that subsequent calls within the same process reuse the discovered state without redundant network requests.

### Runtime Metadata Retrieval Functions

The [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts) file exports `getProviderRuntimeMetadata()`, an async function that accepts a provider name string and returns a metadata object. This function bridges the static registry entry with live API calls, enriching the base descriptor with real-time capacity information. For example, calling `await getProviderRuntimeMetadata('openai')` returns an object containing the `tokenLimit` and a `capabilities` array indicating whether image inputs or function calling are supported at that moment.

## Source Code Implementation Patterns

OpenClaude consumes these two layers through specific utility functions that insulate business logic from provider-specific internals.

### Listing Registered Providers

To enumerate all available integrations without hard-coding provider names, the CLI calls `getAllProviders()` from [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts). This function returns an array of strings representing every provider defined in the static catalog, enabling UI auto-completion and configuration validation.

```typescript
import { getAllProviders } from '../utils/registry.js';

const providers = getAllProviders();
// Returns: ['openai', 'gemini', 'ollama', ...]
console.log('Installed providers:', providers);

```

### Selecting Models Based on Runtime Constraints

When routing a request that requires tool support, OpenClaude queries the runtime metadata to identify which models actually advertise the `toolUse` capability. The `pickModelWithToolSupport()` helper (exposed from [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts)) filters the static model list against live capability flags returned by `getProviderRuntimeMetadata()`, ensuring the CLI never attempts to invoke tools on an incompatible endpoint.

```typescript
import { pickModelWithToolSupport } from '../utils/registry.js';

const model = await pickModelWithToolSupport('openai');
console.log('Selected model for tool use:', model);

```

## Summary

- The **Integration Registry** in [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts) provides a type-safe, static catalog of providers and their configurations using Zod schemas defined in [`src/integrations/types.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/types.ts).
- **Runtime metadata** captures dynamic, per-session information such as available models, token limits, and capability flags (vision, tool use) via `getProviderRuntimeMetadata()`.
- The registry enables compile-time validation and secret mapping through [`src/utils/providerSecrets.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerSecrets.ts), while runtime metadata enables adaptive behavior selection through [`src/utils/providerProfiles.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfiles.ts).
- Together, these layers allow OpenClaude to remain provider-agnostic, building provider interfaces from static descriptors and adjusting execution strategies based on live API responses.

## Frequently Asked Questions

### What is the difference between the registry and runtime metadata in OpenClaude?

The registry contains static definitions—provider names, required environment variables, and default endpoints—stored in [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts). Runtime metadata represents dynamic data discovered at session start, such as which models are currently online and their specific token limits.

### Where does OpenClaude store provider type definitions?

The TypeScript interfaces and Zod schemas that enforce registry entries are defined in [`src/integrations/types.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/types.ts) and consumed throughout the codebase, including [`src/utils/providerSecrets.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerSecrets.ts) and [`src/utils/registry.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/registry.ts).

### How does OpenClaude detect if a provider supports vision or tool use?

During initialization, `getProviderRuntimeMetadata()` queries the provider’s API and populates a capabilities array. The CLI checks this array for strings like `vision` or `toolUse` before enabling corresponding features in the UI or routing engine.

### Can runtime metadata change between OpenClaude sessions?

Yes, runtime metadata is session-specific. If a provider adds a new model or updates token limits between CLI invocations, the next call to `getProviderRuntimeMetadata()` reflects those changes immediately without requiring a code update or registry modification.