自定义 AI 供应商集成

供应商接口规范

OpenClaw 通过统一的 LLMProvider 接口抽象了所有 AI 模型的接入方式。开发者只需要实现该接口，即可无缝接入任意大语言模型供应商。核心接口定义如下：

interface LLMProvider {
  /** 供应商唯一标识 */
  readonly id: string;

  /** 供应商显示名称 */
  readonly name: string;

  /** 支持的模型列表 */
  readonly models: ModelInfo[];

  /** 发送聊天补全请求 */
  chat(options: ChatOptions): Promise<ChatResponse>;

  /** 流式聊天补全 */
  chatStream(options: ChatOptions): AsyncIterable<ChatChunk>;

  /** 嵌入向量生成 */
  embed(texts: string[]): Promise<EmbeddingResponse>;

  /** 模型计费信息 */
  pricing?: PricingInfo;
}

interface ChatOptions {
  model: string;
  messages: Message[];
  temperature?: number;
  maxTokens?: number;
  topP?: number;
  stop?: string[];
  stream?: boolean;
}

interface ModelInfo {
  id: string;
  name: string;
  contextWindow: number;
  maxOutput: number;
  pricing: {
    input: number;    // 每百万 token 输入价格
    output: number;   // 每百万 token 输出价格
  };
}

主流供应商集成

OpenClaw 原生支持以下主流 AI 供应商，每种供应商都提供了完善的接入配置和参数调优能力。

OpenAI 作为业界标杆，支持 GPT-4o、GPT-4o-mini、o3 等全系列模型，适合需要强大通用能力和工具调用功能的场景。配置时只需设置 API Key 和基础地址即可。如果希望使用 Azure OpenAI，只需将 baseURL 修改为 Azure 部署端点。

Anthropic 旗下的 Claude 系列模型在长文本理解和代码生成方面表现卓越，特别适合需要处理大量上下文的企业级应用。Claude 支持高达 200K 的上下文窗口，并且提供了独特的 extendedThinking 模式。接入配置如下：

import { defineConfig } from 'openclaw';

export default defineConfig({
  model: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-20250514',
    apiKey: process.env.ANTHROPIC_API_KEY,
    maxTokens: 8192,
    parameters: {
      thinking: {
        type: 'enabled',
        budgetTokens: 4096,
      },
    },
  },
});

国内供应商接入配置

针对国内开发者，OpenClaw 提供了完善的本土供应商适配。以下是一些主流国内供应商的接入示例：

import { defineConfig } from 'openclaw';

// MiniMax 配置
const minimaxConfig = {
  provider: 'minimax',
  model: 'abab6.5s',
  apiKey: process.env.MINIMAX_API_KEY,
  baseURL: 'https://api.minimax.chat/v1',
};

// 火山引擎（豆包模型）配置
const volcConfig = {
  provider: 'volcengine',
  model: 'doubao-pro-32k',
  apiKey: process.env.VOLC_ACCESS_KEY,
  baseURL: 'https://ark.cn-beijing.volces.com/api/v3',
  parameters: {
    temperature: 0.8,
    topP: 0.9,
  },
};

// DeepSeek 配置
const deepseekConfig = {
  provider: 'deepseek',
  model: 'deepseek-chat',
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: 'https://api.deepseek.com/v1',
  parameters: {
    temperature: 0.7,
    maxTokens: 4096,
  },
};

// Moonshot（月之暗面）配置
const moonshotConfig = {
  provider: 'moonshot',
  model: 'moonshot-v1-32k',
  apiKey: process.env.MOONSHOT_API_KEY,
  baseURL: 'https://api.moonshot.cn/v1',
};

接入国内供应商时有几个关键注意事项：首先，需要确保服务器位于境内或使用合法的跨境网络方案；其次，国内供应商一般采用先充值后使用的方式，建议设置月度预算上限；最后，注意不同供应商对 API 调用频率的限制差异。

多模型路由策略

OpenClaw 内置了智能路由引擎，可以根据请求特征动态选择最合适的模型。以下是几种实用的路由策略：

• 基于成本的优先级路由：优先使用低成本模型处理简单请求，仅在复杂场景下回退到高端模型。例如，日常问答使用 DeepSeek Chat，代码生成切换至 Claude Sonnet。
• 基于内容类型的路由：根据用户输入的语言、领域或意图路由到专长模型。英文技术问题优先路由到 GPT-4o，中文文学创作路由到 MiniMax。
• 基于负载的均衡路由：当同一模型配置了多个 API Key 时，按权重或最少连接数进行负载分配。
• 故障转移路由：当主模型返回错误或超时后，自动切换到备用模型，确保服务不中断。

自定义模型包装器开发

如果官方尚未支持你需要的供应商，可以通过自定义包装器快速接入。以下是一个自定义供应商的完整示例：

import {
  BaseProvider,
  ChatOptions,
  ChatResponse,
  ProviderCapability,
} from 'openclaw/providers';

interface CustomConfig {
  apiKey: string;
  baseURL: string;
  model: string;
}

export class CustomProvider extends BaseProvider {
  private config: CustomConfig;

  constructor(config: CustomConfig) {
    super();
    this.config = config;
    this.capabilities = {
      streaming: true,
      functionCalling: true,
      vision: false,
      embedding: false,
    };
  }

  async chat(options: ChatOptions): Promise<ChatResponse> {
    const response = await fetch(`${this.config.baseURL}/chat/completions`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.config.apiKey}`,
      },
      body: JSON.stringify({
        model: this.config.model,
        messages: options.messages,
        temperature: options.temperature ?? 0.7,
        max_tokens: options.maxTokens ?? 2048,
      }),
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    return {
      id: data.id,
      content: data.choices[0].message.content,
      usage: {
        promptTokens: data.usage.prompt_tokens,
        completionTokens: data.usage.completion_tokens,
      },
      model: data.model,
    };
  }

  async *chatStream(options: ChatOptions): AsyncIterable<ChatChunk> {
    const response = await fetch(`${this.config.baseURL}/chat/completions`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.config.apiKey}`,
      },
      body: JSON.stringify({
        model: this.config.model,
        messages: options.messages,
        stream: true,
      }),
    });

    const reader = response.body!.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      // 解析 SSE 格式数据并 yield
      for (const line of chunk.split('\n')) {
        if (line.startsWith('data: ')) {
          const json = JSON.parse(line.slice(6));
          yield { content: json.choices[0]?.delta?.content ?? '' };
        }
      }
    }
  }
}

供应商价格与能力对比表

综合来看，选择合适的供应商需要权衡成本、性能和合规性。对于国内用户，DeepSeek 和火山引擎在性价比上具有明显优势；而对于需要强推理能力的复杂场景，Claude Sonnet 4 仍然是首选。建议在生产环境中配置至少两家供应商以实现故障转移，确保服务的持续可用。