feat(webuiapps): add local llama.cpp LLM support

Author: vmlinuzx

apps/webuiapps/src/components/ChatPanel/index.tsx

@@ -95,6 +95,10 @@ interface CharacterDisplayMessage extends DisplayMessage {
   toolCalls?: string[]; // collapsed tool call summaries
 }
 
+function hasUsableLLMConfig(config: LLMConfig | null | undefined): config is LLMConfig {
+  return !!config?.baseUrl.trim() && !!config.model.trim();
+}
+
 // ---------------------------------------------------------------------------
 // Tool definitions for character system
 // ---------------------------------------------------------------------------
@@ -649,7 +653,7 @@ const ChatPanel: React.FC<{
     while (actionQueueRef.current.length > 0) {
       const actionMsg = actionQueueRef.current.shift()!;
       const cfg = configRef.current;
-      if (!cfg?.apiKey) break;
+      if (!hasUsableLLMConfig(cfg)) break;
 
       const newHistory: ChatMessage[] = [
         ...chatHistoryRef.current,
@@ -672,7 +676,7 @@ const ChatPanel: React.FC<{
   useEffect(() => {
     const unsubscribe = onUserAction((event: unknown) => {
       const cfg = configRef.current;
-      if (!cfg?.apiKey) return;
+      if (!hasUsableLLMConfig(cfg)) return;
 
       const evt = event as {
         app_action?: {
@@ -704,7 +708,7 @@ const ChatPanel: React.FC<{
     async (overrideText?: string) => {
       const text = overrideText ?? input.trim();
       if (!text || loading) return;
-      if (!config?.apiKey) {
+      if (!hasUsableLLMConfig(config)) {
         setShowSettings(true);
         return;
       }
@@ -1102,9 +1106,9 @@ const ChatPanel: React.FC<{
           <div className={styles.messages} data-testid="chat-messages">
             {messages.length === 0 && (
               <div className={styles.emptyState}>
-                {config?.apiKey
+                {hasUsableLLMConfig(config)
                   ? `${character.character_name} is ready to chat...`
-                  : 'Click the gear icon to configure your LLM API key'}
+                  : 'Click the gear icon to configure your LLM connection'}
               </div>
             )}
             {messages.map((msg) => (
@@ -1287,6 +1291,7 @@ const SettingsModal: React.FC<{
             <option value="openai">OpenAI</option>
             <option value="anthropic">Anthropic</option>
             <option value="deepseek">DeepSeek</option>
+            <option value="llama.cpp">llama.cpp</option>
             <option value="minimax">MiniMax</option>
             <option value="z.ai">Z.ai</option>
             <option value="kimi">Kimi</option>
@@ -1301,7 +1306,7 @@ const SettingsModal: React.FC<{
             type="password"
             value={apiKey}
             onChange={(e) => setApiKey(e.target.value)}
-            placeholder="sk-..."
+            placeholder="Optional for local servers"
           />
         </div>
 

apps/webuiapps/src/lib/__tests__/llmClient.test.ts

@@ -36,6 +36,13 @@ const MOCK_ANTHROPIC_CONFIG: LLMConfig = {
   model: 'claude-opus-4-6',
 };
 
+const MOCK_LLAMACPP_CONFIG: LLMConfig = {
+  provider: 'llama.cpp',
+  apiKey: '',
+  baseUrl: 'http://athena:8081',
+  model: 'Qwen_Qwen3.5-35B-A3B',
+};
+
 const MOCK_MESSAGES: ChatMessage[] = [{ role: 'user', content: 'Hello' }];
 
 const MOCK_TOOLS: ToolDef[] = [
@@ -114,6 +121,13 @@ describe('getDefaultProviderConfig()', () => {
     expect(cfg.model).toBe('deepseek-chat');
   });
 
+  it('returns correct defaults for llama.cpp', () => {
+    const cfg = getDefaultProviderConfig('llama.cpp');
+    expect(cfg.provider).toBe('llama.cpp');
+    expect(cfg.baseUrl).toBe('http://localhost:8080');
+    expect(cfg.model).toBe('local-model');
+  });
+
   it('returns correct defaults for minimax', () => {
     const cfg = getDefaultProviderConfig('minimax');
     expect(cfg.provider).toBe('minimax');
@@ -422,6 +436,31 @@ describe('chat()', () => {
     });
   });
 
+  describe('llama.cpp provider (OpenAI-compatible)', () => {
+    it('routes to OpenAI path without requiring an API key', async () => {
+      const mockFetch = vi.fn().mockResolvedValueOnce(makeOpenAIResponse('Local response'));
+      globalThis.fetch = mockFetch;
+
+      const result = await chat(MOCK_MESSAGES, [], MOCK_LLAMACPP_CONFIG);
+
+      expect(result.content).toBe('Local response');
+      const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
+      expect(headers['Authorization']).toBeUndefined();
+      expect(headers['X-LLM-Target-URL']).toBe('http://athena:8081/v1/chat/completions');
+    });
+
+    it('strips Qwen-style think tags from assistant content', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(makeOpenAIResponse('<think>hidden reasoning</think>Hello there'));
+      globalThis.fetch = mockFetch;
+
+      const result = await chat(MOCK_MESSAGES, [], MOCK_LLAMACPP_CONFIG);
+
+      expect(result.content).toBe('Hello there');
+    });
+  });
+
   describe('Anthropic provider', () => {
     it('uses x-api-key and anthropic-version headers', async () => {
       const mockFetch = vi.fn().mockResolvedValueOnce(makeAnthropicResponse('Anthropic response'));

apps/webuiapps/src/lib/llmClient.ts

@@ -1,6 +1,6 @@
 /**
  * Minimal LLM API Client
- * Supports OpenAI / DeepSeek / Anthropic formats
+ * Supports OpenAI-compatible / Anthropic-compatible formats
  */
 
 import type { LLMConfig } from './llmModels';
@@ -88,6 +88,13 @@ interface LLMResponse {
   toolCalls: ToolCall[];
 }
 
+function stripThinkTags(content: string): string {
+  const withoutBlocks = content
+    .replace(/<think\b[^>]*>[\s\S]*?<\/think>/gi, '')
+    .replace(/<\/?think\b[^>]*>/gi, '');
+  return withoutBlocks === content ? content : withoutBlocks.trim();
+}
+
 function hasVersionSuffix(url: string): boolean {
   return /\/v\d+\/?$/.test(url);
 }
@@ -162,14 +169,17 @@ async function chatOpenAI(
     messageCount: messages.length,
     toolCount: tools.length,
   });
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-LLM-Target-URL': targetUrl,
+    ...parseCustomHeaders(config.customHeaders),
+  };
+  if (config.apiKey.trim()) {
+    headers.Authorization = `Bearer ${config.apiKey}`;
+  }
   const res = await fetch('/api/llm-proxy', {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${config.apiKey}`,
-      'X-LLM-Target-URL': targetUrl,
-      ...parseCustomHeaders(config.customHeaders),
-    },
+    headers,
     body: JSON.stringify(body),
   });
 
@@ -195,7 +205,7 @@ async function chatOpenAI(
     calledNames,
   );
   return {
-    content: choice?.content || '',
+    content: stripThinkTags(choice?.content || ''),
     toolCalls,
   };
 }
@@ -267,15 +277,18 @@ async function chatAnthropic(
     messageCount: anthropicMessages.length,
     toolCount: anthropicTools.length,
   });
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'anthropic-version': '2023-06-01',
+    'X-LLM-Target-URL': targetUrl,
+    ...parseCustomHeaders(config.customHeaders),
+  };
+  if (config.apiKey.trim()) {
+    headers['x-api-key'] = config.apiKey;
+  }
   const res = await fetch('/api/llm-proxy', {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'x-api-key': config.apiKey,
-      'anthropic-version': '2023-06-01',
-      'X-LLM-Target-URL': targetUrl,
-      ...parseCustomHeaders(config.customHeaders),
-    },
+    headers,
     body: JSON.stringify(body),
   });
 
@@ -314,5 +327,5 @@ async function chatAnthropic(
     'calledNames=',
     calledNames,
   );
-  return { content, toolCalls };
+  return { content: stripThinkTags(content), toolCalls };
 }

apps/webuiapps/src/lib/llmModels.ts

@@ -2,6 +2,7 @@ export type LLMProvider =
   | 'openai'
   | 'anthropic'
   | 'deepseek'
+  | 'llama.cpp'
   | 'minimax'
   | 'z.ai'
   | 'kimi'
@@ -77,6 +78,13 @@ export const LLM_PROVIDER_CONFIGS: Record<LLMProvider, ProviderModelConfig> = {
     ],
   },
 
+  'llama.cpp': {
+    displayName: 'llama.cpp',
+    baseUrl: 'http://localhost:8080',
+    defaultModel: 'local-model',
+    models: [],
+  },
+
   minimax: {
     displayName: 'MiniMax',
     baseUrl: 'https://api.minimax.io/anthropic/v1',