Provider runtime hooks and catalogs

​

Provider runtime hooks

• Manifest metadata for cheap pre-runtime lookup: setup.providers[].envVars, providerAuthAliases, providerAuthChoices, and channelConfigs.
• Config-time hooks: catalog plus applyConfigDefaults.
• Runtime hooks: 40+ optional hooks covering auth, model resolution, stream wrapping, thinking levels, replay policy, and usage endpoints. See Hook order and usage.

​

Hook order and usage

• Model references apply manifest-declared model-ID normalization once before normalizeModelId dispatch. The matched provider hook can refine that prepared model ID; an empty result keeps it unchanged. OpenClaw does not try other providers’ normalization hooks or reapply manifest rules afterward. Reference parsing reads the selected runtime registry without activating plugins. Executable normalization requires a prepared runtime owner; reads without one use static manifest policies only. A directly registered provider owns its ID; compatibility aliases match only when no literal provider exists, preserving alias-only routes and explicit API-owner eligibility.
• normalizeTransport tries the matched provider first. Only if that does not change api or baseUrl and the provider has no models.providers.<id> entry does it try other transport hooks, stopping at the first change.
• normalizeConfig uses the owning bundled provider’s lightweight policy surface first. If that surface has no normalizeConfig hook, OpenClaw may call the matched runtime owner, provided runtime loading is allowed and, when a config is supplied, that owner has explicit plugin activation. It never scans other providers’ hooks or falls through after the owning hook returns no change. Config assembly passes allowRuntimePluginLoad: false, so it uses bundled policy without loading provider runtime.

​

Provider example

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Built-in examples

​

Provider catalogs

• { provider } for one provider entry
• { providers } for multiple provider entries

• simple: plain API-key or env-driven providers
• profile: providers that appear when auth profiles exist
• paired: providers that synthesize multiple related provider entries
• late: last pass, after other implicit providers

• discovery still works as a legacy alias, but emits a deprecation warning
• if both catalog and discovery are registered, OpenClaw uses catalog and emits a warning
• augmentModelCatalog is deprecated; bundled providers should publish supplemental rows through registerModelCatalogProvider