feat: add litellm provider

CHANGELOG.md

@@ -5,6 +5,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Added
+- **LiteLLM support for AI features.** Point webclaw at your own LiteLLM setup to use many different models for extraction and summarization through a single connection. Enable it by setting `LITELLM_API_KEY`; existing model choices are unaffected.
+
 ## [0.6.22] - 2026-08-30
 
 ### Added

README.md

@@ -371,6 +371,9 @@ webclaw/
 | `ANTHROPIC_BASE_URL` | Anthropic-compatible base URL |
 | `ORCAROUTER_API_KEY` | OrcaRouter LLM provider key |
 | `ORCAROUTER_BASE_URL` | OrcaRouter base URL (defaults to https://api.orcarouter.ai/v1) |
+| `LITELLM_API_KEY` | LiteLLM proxy key (OpenAI-compatible gateway) |
+| `LITELLM_BASE_URL` | LiteLLM proxy base URL (defaults to http://localhost:4000/v1) |
+| `LITELLM_MODEL` | LiteLLM default model (defaults to gpt-4o-mini) |
 | `WEBCLAW_PROXY` | Single proxy URL |
 | `WEBCLAW_PROXY_FILE` | Proxy pool file |
 

crates/webclaw-cli/src/main.rs

@@ -339,7 +339,7 @@ struct Cli {
     #[arg(long, num_args = 0..=1, default_missing_value = "3")]
     summarize: Option<usize>,
 
-    /// Force a specific LLM provider (ollama, openai, atlascloud, anthropic, orcarouter)
+    /// Force a specific LLM provider (ollama, openai, atlascloud, anthropic, orcarouter, litellm)
     #[arg(long, env = "WEBCLAW_LLM_PROVIDER")]
     llm_provider: Option<String>,
 
@@ -2284,15 +2284,24 @@ async fn build_llm_provider(cli: &Cli) -> Result<Box<dyn LlmProvider>, String> {
                 .ok_or("ANTHROPIC_API_KEY not set")?;
                 Ok(Box::new(provider))
             }
+            "litellm" => {
+                let provider = webclaw_llm::providers::litellm::LiteLlmProvider::new(
+                    None,
+                    cli.llm_base_url.clone(),
+                    cli.llm_model.clone(),
+                )
+                .ok_or("LITELLM_API_KEY not set")?;
+                Ok(Box::new(provider))
+            }
             other => Err(format!(
-                "unknown LLM provider: {other} (use ollama, openai, atlascloud, anthropic, or orcarouter)"
+                "unknown LLM provider: {other} (use ollama, openai, atlascloud, anthropic, orcarouter, or litellm)"
             )),
         }
     } else {
         let chain = webclaw_llm::ProviderChain::default().await;
         if chain.is_empty() {
             return Err(
-                "no LLM providers available -- start Ollama or set OPENAI_API_KEY / ANTHROPIC_API_KEY / ORCAROUTER_API_KEY"
+                "no LLM providers available -- start Ollama or set OPENAI_API_KEY / ANTHROPIC_API_KEY / ORCAROUTER_API_KEY / LITELLM_API_KEY"
                     .into(),
             );
         }

crates/webclaw-llm/src/chain.rs

@@ -8,22 +8,25 @@ use crate::error::LlmError;
 use crate::provider::{CompletionRequest, LlmProvider};
 use crate::providers::{
     anthropic::AnthropicProvider, atlascloud::AtlasCloudProvider, gemini::GeminiProvider,
-    ollama::OllamaProvider, openai::OpenAiProvider, orcarouter::OrcaRouterProvider,
+    litellm::LiteLlmProvider, ollama::OllamaProvider, openai::OpenAiProvider,
+    orcarouter::OrcaRouterProvider,
 };
 
 pub struct ProviderChain {
     providers: Vec<Box<dyn LlmProvider>>,
 }
 
 impl ProviderChain {
-    /// Build the default chain: Ollama -> OpenAI -> Gemini -> Anthropic -> Atlas Cloud -> OrcaRouter.
+    /// Build the default chain: Ollama -> OpenAI -> Gemini -> Anthropic -> Atlas Cloud -> OrcaRouter -> LiteLLM.
     /// Ollama is always added (availability checked at call time).
     /// Cloud providers are only added if their API keys are configured.
     /// Gemini sits ahead of Anthropic so Google Cloud credits are preferred,
     /// with Anthropic as the last-resort fallback. Atlas Cloud is opt-in and
     /// added last (only when `ATLASCLOUD_API_KEY` is set), so it never preempts
-    /// an already-configured provider. OrcaRouter is also opt-in and added last,
-    /// only when `ORCAROUTER_API_KEY` is set.
+    /// an already-configured provider. OrcaRouter and LiteLLM are also opt-in
+    /// and added last, only when `ORCAROUTER_API_KEY` / `LITELLM_API_KEY` is
+    /// set. A LiteLLM proxy is OpenAI-compatible, so it reaches 100+ upstream
+    /// providers through one endpoint.
     pub async fn default() -> Self {
         Self::build_default(true).await
     }
@@ -73,6 +76,11 @@ impl ProviderChain {
             providers.push(Box::new(orcarouter));
         }
 
+        if let Some(litellm) = LiteLlmProvider::new(None, None, None) {
+            debug!("litellm configured, adding to chain");
+            providers.push(Box::new(litellm));
+        }
+
         Self { providers }
     }
 

crates/webclaw-llm/src/providers/litellm.rs

@@ -0,0 +1,84 @@
+/// LiteLLM provider — OpenAI-compatible chat completions against a LiteLLM proxy.
+///
+/// A LiteLLM proxy speaks the OpenAI wire format, so this provider reuses the
+/// `OpenAiProvider` transport unchanged. Pointing it at a LiteLLM gateway lets
+/// webclaw reach 100+ upstream providers (OpenAI, Anthropic, Bedrock, Vertex
+/// AI, Azure, and more) through a single endpoint with centralized keys.
+use async_trait::async_trait;
+
+use crate::error::LlmError;
+use crate::provider::{CompletionRequest, LlmProvider};
+
+use super::openai::OpenAiProvider;
+
+pub struct LiteLlmProvider {
+    inner: OpenAiProvider,
+}
+
+impl LiteLlmProvider {
+    /// Returns `None` if no LiteLLM API key is available (param or env).
+    pub fn new(
+        key_override: Option<String>,
+        base_url: Option<String>,
+        model: Option<String>,
+    ) -> Option<Self> {
+        let key = super::load_api_key(key_override, "LITELLM_API_KEY")?;
+        let base_url = base_url
+            .or_else(|| std::env::var("LITELLM_BASE_URL").ok())
+            .unwrap_or_else(|| "http://localhost:4000/v1".into());
+        let model = model
+            .or_else(|| std::env::var("LITELLM_MODEL").ok())
+            .unwrap_or_else(|| "gpt-4o-mini".into());
+        let inner = OpenAiProvider::new(Some(key), Some(base_url), Some(model))?;
+        Some(Self { inner })
+    }
+
+    pub fn default_model(&self) -> &str {
+        self.inner.default_model()
+    }
+}
+
+#[async_trait]
+impl LlmProvider for LiteLlmProvider {
+    async fn complete(&self, request: &CompletionRequest) -> Result<String, LlmError> {
+        self.inner.complete(request).await
+    }
+
+    async fn is_available(&self) -> bool {
+        self.inner.is_available().await
+    }
+
+    fn name(&self) -> &str {
+        "litellm"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn empty_key_returns_none() {
+        assert!(LiteLlmProvider::new(Some(String::new()), None, None).is_none());
+    }
+
+    #[test]
+    #[ignore = "reads LITELLM_MODEL from the process env; run with --test-threads=1"]
+    fn explicit_key_constructs_with_litellm_defaults() {
+        let provider =
+            LiteLlmProvider::new(Some("test-key".into()), None, None).expect("should construct");
+        assert_eq!(provider.name(), "litellm");
+        assert_eq!(provider.default_model(), "gpt-4o-mini");
+    }
+
+    #[test]
+    fn explicit_model_override() {
+        let provider = LiteLlmProvider::new(
+            Some("test-key".into()),
+            Some("http://proxy.example.com:4000/v1".into()),
+            Some("claude-sonnet-4-6".into()),
+        )
+        .expect("should construct");
+        assert_eq!(provider.default_model(), "claude-sonnet-4-6");
+    }
+}

crates/webclaw-llm/src/providers/mod.rs

@@ -1,6 +1,7 @@
 pub mod anthropic;
 pub mod atlascloud;
 pub mod gemini;
+pub mod litellm;
 pub mod ollama;
 pub mod openai;
 pub mod orcarouter;

env.example

@@ -23,6 +23,11 @@ OLLAMA_MODEL=qwen3:8b
 # ORCAROUTER_BASE_URL — defaults to https://api.orcarouter.ai/v1
 # ORCAROUTER_MODEL    — defaults to orcarouter/auto
 
+# LiteLLM proxy (optional OpenAI-compatible gateway to 100+ providers)
+# LITELLM_API_KEY  — set your LiteLLM proxy key
+# LITELLM_BASE_URL — defaults to http://localhost:4000/v1
+# LITELLM_MODEL    — defaults to gpt-4o-mini
+
 # --- Proxy ---
 
 # Single proxy