📦 new (provider): add Ollama provider plugin with model pairing and catalog

Author: warengonzaga

README.md

@@ -53,6 +53,7 @@ Tiny Claw is inspired by personal AI companions from science fiction like **Cods
 - **Own personality.** Ships with a personality (Heartware system) that's uniquely its own.
 - **Native, not wrapped.** Every component is built from scratch with zero dependency on external AI frameworks.
 - **Easy to start.** Uses Ollama Cloud with two built-in models — kimi-k2.5:cloud (default) and gpt-oss:120b-cloud. Choose your model during setup and switch anytime via conversation.
+- **Flexible Ollama support.** Add the Ollama provider plugin for local Ollama or extra cloud models without duplicating the built-in starter models, while reusing the Ollama API key already stored during setup.
 - **Cost-conscious.** Smart routing tiers queries across your installed providers. Cheap models handle simple stuff, powerful models only fire when needed.
 
 ## ✨ Features

bun.lock

@@ -22,6 +22,8 @@ export type { ConfigManagerConfig, ConfigManagerInterface } from '@tinyclaw/type
  * stored in secrets-engine (never the actual secret).
  */
 const ProviderEntrySchema = z.object({
+  providerId: z.string().optional(),
+  mode: z.enum(['local', 'cloud']).optional(),
   model: z.string().optional(),
   baseUrl: z.string().url().optional(),
   apiKeyRef: z.string().optional(),
@@ -61,7 +63,7 @@ export const TinyClawConfigSchema = z
         starterBrain: ProviderEntrySchema.optional(),
         primary: ProviderEntrySchema.optional(),
       })
-      .passthrough()
+      .catchall(ProviderEntrySchema)
       .optional(),
 
     /** Channel configurations (telegram, discord, slack, etc.) */

packages/config/src/types.ts

@@ -61,10 +61,16 @@ describe('TinyClawConfigSchema — valid data', () => {
           baseUrl: 'http://localhost:11434',
         },
         primary: {
+          providerId: 'openai',
           model: 'gpt-4',
           baseUrl: 'https://api.openai.com/v1',
           apiKeyRef: 'provider.openai.apiKey',
         },
+        ollama: {
+          mode: 'local',
+          model: 'llama3.2:3b',
+          baseUrl: 'http://127.0.0.1:11434',
+        },
       },
       channels: {
         telegram: { enabled: true, tokenRef: 'channel.telegram.token' },
@@ -116,6 +122,25 @@ describe('TinyClawConfigSchema — valid data', () => {
     });
     expect(result.success).toBe(true);
   });
+
+  test('accepts provider mode and providerId fields', () => {
+    const result = TinyClawConfigSchema.safeParse({
+      providers: {
+        primary: {
+          providerId: 'ollama',
+          model: 'llama3.2:3b',
+        },
+        ollama: {
+          mode: 'cloud',
+          model: 'qwen3:32b',
+          baseUrl: 'https://ollama.com',
+          apiKeyRef: 'provider.ollama.apiKey',
+        },
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
 });
 
 // -----------------------------------------------------------------------
@@ -173,4 +198,14 @@ describe('TinyClawConfigSchema — invalid data', () => {
     });
     expect(result.success).toBe(false);
   });
+
+  test('rejects invalid provider mode', () => {
+    const result = TinyClawConfigSchema.safeParse({
+      providers: {
+        ollama: { mode: 'edge' },
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
 });

packages/config/tests/types.test.ts

@@ -646,7 +646,10 @@ export interface ChannelPlugin extends PluginMeta {
 export interface ProviderPlugin extends PluginMeta {
   readonly type: 'provider';
   /** Create and return an initialized Provider instance. */
-  createProvider(secrets: SecretsManagerInterface): Promise<Provider>;
+  createProvider(
+    secrets: SecretsManagerInterface,
+    configManager: ConfigManagerInterface,
+  ): Promise<Provider>;
   /** Optional pairing tools for conversational setup (API key, model config). */
   getPairingTools?(secrets: SecretsManagerInterface, configManager: ConfigManagerInterface): Tool[];
 }

packages/types/src/index.ts

@@ -20,7 +20,7 @@ The startup flow is:
 1. CLI loads plugin IDs from the `plugins.enabled` config array.
 2. Plugin modules are imported dynamically by package name.
 3. Pairing tools from provider (and channel) plugins are merged into the agent tool list.
-4. For each enabled provider plugin, Tiny Claw calls `plugin.createProvider(secrets)` to obtain a `Provider` instance.
+4. For each enabled provider plugin, Tiny Claw calls `plugin.createProvider(secrets, configManager)` to obtain a `Provider` instance.
 5. The routing system maps query complexity tiers (simple, moderate, complex, reasoning) to provider IDs.
 6. At query time, the router selects the appropriate provider based on the tier mapping.
 
@@ -31,7 +31,10 @@ Provider plugins must default-export an object that satisfies `ProviderPlugin` f
 ```ts
 export interface ProviderPlugin extends PluginMeta {
   readonly type: 'provider';
-  createProvider(secrets: SecretsManagerInterface): Promise<Provider>;
+  createProvider(
+    secrets: SecretsManagerInterface,
+    configManager: ConfigManagerInterface,
+  ): Promise<Provider>;
   getPairingTools?(
     secrets: SecretsManagerInterface,
     configManager: ConfigManagerInterface,
@@ -59,7 +62,7 @@ Required fields on the plugin:
 | `description` | Short summary |
 | `type` | Must be `'provider'` |
 | `version` | SemVer string |
-| `createProvider(secrets)` | Factory that returns a `Provider` instance |
+| `createProvider(secrets, configManager)` | Factory that returns a `Provider` instance |
 
 Optional field:
 
@@ -130,8 +133,15 @@ const plugin: ProviderPlugin = {
   type: 'provider',
   version: '0.1.0',
 
-  async createProvider(secrets: SecretsManagerInterface) {
-    return createMyProvider({ secrets });
+  async createProvider(
+    secrets: SecretsManagerInterface,
+    configManager: ConfigManagerInterface,
+  ) {
+    return createMyProvider({
+      secrets,
+      model: configManager.get<string>('providers.<name>.model') ?? undefined,
+      baseUrl: configManager.get<string>('providers.<name>.baseUrl') ?? undefined,
+    });
   },
 
   getPairingTools(
@@ -294,6 +304,7 @@ configManager.set('routing.tierMapping.reasoning', '<name>');
 | Plugin | Path | Description |
 |--------|------|-------------|
 | **OpenAI** | `plugins/provider/plugin-provider-openai/` | OpenAI GPT models via raw fetch (no SDK) |
+| **Ollama** | `plugins/provider/plugin-provider-ollama/` | Local Ollama and custom Ollama Cloud models |
 
 Key files in the OpenAI plugin:
 

plugins/provider/README.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- add Ollama provider plugin with local and custom cloud model support
+- add conversational model listing and switching tools for the Ollama plugin

plugins/provider/plugin-provider-ollama/CHANGELOG.md

@@ -0,0 +1,28 @@
+# @tinyclaw/plugin-provider-ollama
+
+Ollama provider plugin for Tiny Claw. It supports both local Ollama instances and custom Ollama Cloud models while keeping the built-in starter models reserved for the built-in provider.
+
+## What It Adds
+
+- Local Ollama support with a configurable base URL
+- Ollama Cloud support for custom cloud models
+- Conversational pairing, model listing, and model switching tools
+- Filtering of built-in cloud starter models from the plugin's cloud model list
+
+## Conversational Tools
+
+- `ollama_pair` - pair local or cloud Ollama
+- `ollama_model_list` - show supported Ollama models for the current mode
+- `ollama_model_set` - switch the configured Ollama model or mode
+- `ollama_unpair` - disable the plugin and restore built-in routing
+
+## Notes
+
+- Cloud mode reuses the existing `provider.ollama.apiKey` from the built-in setup by default
+- You only need to pass `apiKey` if you want to replace that stored Ollama key
+- Cloud model listing excludes the built-in starter models
+- Use `tinyclaw_restart` after pairing or switching models
+
+## License
+
+GPLv3

plugins/provider/plugin-provider-ollama/README.md

@@ -0,0 +1,39 @@
+{
+  "name": "@tinyclaw/plugin-provider-ollama",
+  "version": "2.0.0",
+  "description": "Ollama provider plugin for Tiny Claw",
+  "license": "GPL-3.0",
+  "author": "Waren Gonzaga",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warengonzaga/tinyclaw.git",
+    "directory": "plugins/provider/plugin-provider-ollama"
+  },
+  "homepage": "https://github.com/warengonzaga/tinyclaw/tree/main/plugins/provider/plugin-provider-ollama#readme",
+  "bugs": {
+    "url": "https://github.com/warengonzaga/tinyclaw/issues"
+  },
+  "keywords": [
+    "tinyclaw",
+    "plugin",
+    "provider",
+    "ollama"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tinyclaw/core": "workspace:*",
+    "@tinyclaw/logger": "workspace:*",
+    "@tinyclaw/types": "workspace:*"
+  }
+}

plugins/provider/plugin-provider-ollama/package.json

@@ -0,0 +1,79 @@
+import { BUILTIN_MODEL_TAGS, DEFAULT_BASE_URL } from '@tinyclaw/core';
+import { buildProviderKeyName } from '@tinyclaw/types';
+
+export const OLLAMA_PLUGIN_ID = '@tinyclaw/plugin-provider-ollama';
+export const OLLAMA_PROVIDER_ID = 'ollama';
+export const OLLAMA_SECRET_KEY = buildProviderKeyName(OLLAMA_PROVIDER_ID);
+export const OLLAMA_MODEL_CONFIG_KEY = 'providers.ollama.model';
+export const OLLAMA_BASE_URL_CONFIG_KEY = 'providers.ollama.baseUrl';
+export const OLLAMA_MODE_CONFIG_KEY = 'providers.ollama.mode';
+export const OLLAMA_API_KEY_REF_CONFIG_KEY = 'providers.ollama.apiKeyRef';
+export const OLLAMA_LOCAL_BASE_URL = 'http://127.0.0.1:11434';
+export const OLLAMA_LOCAL_FALLBACK_MODEL = 'llama3.2:3b';
+export const OLLAMA_CLOUD_FALLBACK_MODEL = 'qwen3:32b';
+
+export type OllamaProviderMode = 'local' | 'cloud';
+
+interface OllamaTagItem {
+  name?: string;
+  model?: string;
+}
+
+interface OllamaTagsResponse {
+  models?: OllamaTagItem[];
+}
+
+export function normalizeOllamaMode(mode: string | null | undefined): OllamaProviderMode {
+  return mode === 'cloud' ? 'cloud' : 'local';
+}
+
+export function getDefaultBaseUrl(mode: OllamaProviderMode): string {
+  return mode === 'cloud' ? DEFAULT_BASE_URL : OLLAMA_LOCAL_BASE_URL;
+}
+
+export function getFallbackModel(mode: OllamaProviderMode): string {
+  return mode === 'cloud' ? OLLAMA_CLOUD_FALLBACK_MODEL : OLLAMA_LOCAL_FALLBACK_MODEL;
+}
+
+export function shouldFilterBuiltinModel(mode: OllamaProviderMode, model: string): boolean {
+  return mode === 'cloud' && (BUILTIN_MODEL_TAGS as readonly string[]).includes(model);
+}
+
+export function sortModels(models: string[]): string[] {
+  return [...new Set(models)].sort((left, right) => left.localeCompare(right));
+}
+
+export async function fetchOllamaModels(config: {
+  baseUrl: string;
+  mode: OllamaProviderMode;
+  apiKey?: string | null;
+}): Promise<string[]> {
+  const headers: Record<string, string> = {};
+  if (config.apiKey) {
+    headers.Authorization = `Bearer ${config.apiKey}`;
+  }
+
+  const response = await fetch(`${config.baseUrl}/api/tags`, { headers });
+  if (!response.ok) {
+    throw new Error(`Ollama model listing failed with HTTP ${response.status}`);
+  }
+
+  const data = (await response.json()) as OllamaTagsResponse;
+  const models = (data.models ?? [])
+    .map((entry) => entry.name ?? entry.model ?? '')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .filter((entry) => !shouldFilterBuiltinModel(config.mode, entry));
+
+  return sortModels(models);
+}
+
+export function formatModelList(models: string[], currentModel?: string): string {
+  if (models.length === 0) {
+    return 'No supported models were found.';
+  }
+
+  return models
+    .map((model) => (model === currentModel ? `• ${model} [current]` : `• ${model}`))
+    .join('\n');
+}