OpenClaw 自定义 Provider 开发

🎯 为什么需要自定义 Provider？

世界上有一种需求，叫「我要用自己的模型」。OpenAI、Anthropic 很好，但企业有私有模型、本地有 Ollama、特殊场景需要定制 API。

"周二下午4点，公司要求接入内部微调的 GLM 模型。OpenClaw 默认不支持。那一刻我知道，需要学会写自定义 Provider。"

自定义 Provider 让你能够：

• 🏢 接入企业私有模型 - 公司内部微调模型、私有化部署
• 🖥️ 本地 LLM - Ollama、LM Studio、vLLM 本地运行
• 🔌 OpenAI 兼容 API - 任何兼容 OpenAI API 的服务
• 🛡️ 统一认证管理 - v2026.5.22 改进认证状态预热
• 🎛️ 细粒度控制 - 自定义重试、超时、fallback 策略

🚀 快速开始

1. 最简单的 Provider（OpenAI 兼容）

// ~/.openclaw/config.json
{
  "providers": {
    "my-custom-api": {
      "type": "openai-compatible",
      "baseUrl": "https://my-api.example.com/v1",
      "apiKey": "sk-your-key",
      "models": ["my-model-1", "my-model-2"]
    }
  },
  "agents": {
    "main": {
      "provider": "my-custom-api",
      "model": "my-model-1"
    }
  }
}

2. 接入 Ollama 本地模型

// Ollama 是 OpenAI 兼容的，配置更简单
{
  "providers": {
    "ollama-local": {
      "type": "openai-compatible",
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama", // Ollama 不需要真实 key
      "models": ["llama3.1", "mistral", "codellama"]
    }
  }
}

// 验证
openclaw models list --provider ollama-local

// 使用
openclaw agent --provider ollama-local "帮我写个Python脚本"

3. 使用 Plugin SDK 开发高级 Provider

// src/my-provider-plugin.ts
import { Plugin, LLMProvider } from '@openclaw/plugin-sdk';

export class MyProviderPlugin implements Plugin, LLMProvider {
  name = 'my-provider';
  version = '1.0.0';
  
  // Provider 元数据
  getProviderInfo() {
    return {
      id: 'my-provider',
      name: 'My Custom Provider',
      type: 'custom',
      supportsStreaming: true,
      supportsTools: true
    };
  }
  
  // 列出可用模型
  async listModels(): Promise<Model[]> {
    return [
      { id: 'my-model-1', contextWindow: 128000 },
      { id: 'my-model-2', contextWindow: 256000 }
    ];
  }
  
  // 执行 completion
  async complete(request: CompletionRequest): Promise<CompletionResponse> {
    // 实现你的 API 调用逻辑
    const response = await fetch('https://my-api.com/v1/chat/completions', {
      method: 'POST',
      headers: { 
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: request.model,
        messages: request.messages,
        stream: request.stream
      })
    });
    
    return await response.json();
  }
}

export default function createPlugin(config: any) {
  return new MyProviderPlugin(config);
}

💻 v2026.5.22 新特性：认证状态预热

v2026.5.22 带来了 Provider 认证状态的预热机制，模型列表查询性能提升 4000x：

认证状态预热配置

{
  "providers": {
    "my-provider": {
      "type": "custom",
      "preWarmAuth": true,  // 启用预热（默认true）
      "preWarmTimeoutMs": 30000,
      "reuseAuthState": true  // 跨模块复用认证状态
    }
  },
  "gateway": {
    "performance": {
      "preWarmModels": true,
      "reuseProviderAuth": true  // 预热 Provider 认证
    }
  }
}

// 效果：
// 首次 /models 调用：~20s（预热）
// 后续 /models 调用：~5ms（缓存命中）
// 性能提升：~4000x

处理认证失败和重试

// v2026.5.22 改进了认证失败处理
{
  "providers": {
    "my-provider": {
      "auth": {
        "retry": {
          "maxAttempts": 3,
          "backoff": "exponential",
          "initialDelayMs": 1000
        },
        "failover": {
          "enabled": true,
          "fallbackProvider": "openai"  // 认证失败切换到备用
        }
      }
    }
  }
}

🔧 实战：接入企业私有模型

场景：公司微调的 GLM 模型

// 1. 配置企业 GLM Provider
{
  "providers": {
    "company-glm": {
      "type": "openai-compatible",
      "baseUrl": "https://ai.company.com/v1",
      "apiKey": "${COMPANY_AI_KEY}",  // 从环境变量读取
      "models": ["glm-4-plus", "glm-4-air", "glm-4-flash"],
      "headers": {
        "X-Company-ID": "${COMPANY_ID}",
        "X-Project-ID": "miaoquai"
      },
      "timeoutMs": 60000
    }
  },
  "agents": {
    "company-bot": {
      "provider": "company-glm",
      "model": "glm-4-plus",
      "systemPrompt": "你是妙趣AI的企业助手..."
    }
  }
}

// 2. 设置环境变量
export COMPANY_AI_KEY="your-company-key"
export COMPANY_ID="miaoquai-001"

// 3. 测试
openclaw agent --agent company-bot "分析这份财报的要点"

高级：自定义模型 catalog

// 如果你的模型不在 /models 返回中，可以手动定义
{
  "providers": {
    "my-provider": {
      "catalog": {
        "static": [
          {
            "id": "my-model-1",
            "name": "My Model 1",
            "contextWindow": 128000,
            "inputCostPer1k": 0.01,
            "outputCostPer1k": 0.03
          },
          {
            "id": "my-model-2",
            "name": "My Model 2",
            "contextWindow": 256000,
            "supportsTools": true,
            "supportsVision": true
          }
        ]
      }
    }
  }
}

📊 Provider 配置详解

🎓 高级话题

1. 多模型路由（Model Router）

// 根据任务类型自动选择模型
{
  "providers": {
    "router": {
      "type": "model-router",
      "rules": [
        {
          "match": { "task": "code" },
          "provider": "ollama-local",
          "model": "codellama"
        },
        {
          "match": { "task": "chat" },
          "provider": "openai",
          "model": "gpt-4o"
        },
        {
          "match": { "contextWindow": ">128000" },
          "provider": "anthropic",
          "model": "claude-3-opus"
        }
      ],
      "default": {
        "provider": "openai",
        "model": "gpt-4o-mini"
      }
    }
  }
}

2. 成本追踪

// 为自定义 Provider 添加成本追踪
{
  "providers": {
    "my-provider": {
      "costTracking": {
        "enabled": true,
        "inputCostPer1k": 0.01,
        "outputCostPer1k": 0.03,
        "reportTo": "prometheus"  // 或 "logs"
      }
    }
  }
}

// 查看成本
openclaw usage --provider my-provider --last 7d

3. 与嵌入 Provider 集成

// v2026.5.22 新增通用嵌入提供商 API
{
  "embeddingProviders": {
    "my-embeddings": {
      "provider": "custom",
      "baseUrl": "https://my-embeddings.com",
      "apiKey": "${EMBEDDING_KEY}",
      "dimensions": 1536
    }
  },
  "memory": {
    "provider": "lancedb",
    "config": {
      "embeddingProvider": "my-embeddings"
    }
  }
}

🔧 故障排查

📚 相关资源

• OpenClaw Plugin SDK 开发
• OpenClaw Ollama 本地部署
• OpenClaw 模型路由
• OpenClaw Gateway 性能优化
• 官方自定义 Provider 文档