OpenClaw 自定义模型 Provider：接入 LiteLLM 代理和私有模型

2026-03-23 · 5 分钟模型接入

什么时候需要自定义 Provider？

以下场景需要手动配置 Provider：

使用 LiteLLM 等代理统一管理多个模型
使用 LM Studio 本地运行模型
接入企业内部的私有模型 API
使用 OpenClaw 尚未内置的模型服务

配置方式

在 openclaw.json 的 models.providers 中添加自定义 Provider：

LiteLLM 代理

{
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "custom-proxy/llama-3.1-8b"
      }
    }
  }
}

LM Studio 本地模型

{
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.5-gs32",
            name: "MiniMax M2.5 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "lmstudio/minimax-m2.5-gs32"
      }
    }
  }
}

Provider 参数说明

参数	说明
`baseUrl`	API 端点地址
`apiKey`	认证密钥，支持 `${ENV_VAR}` 引用环境变量
`api`	请求适配器类型，常用 `openai-completions`、`openai-responses`、`anthropic-messages`
`auth`	认证策略，如 `api-key`
`authHeader`	是否在请求头中发送认证信息
`headers`	自定义请求头
`models`	该 Provider 提供的模型目录

模型定义参数

参数	说明
`id`	模型标识符
`name`	显示名称
`api`	请求适配器（可覆盖 Provider 级别设置）
`reasoning`	是否支持推理/思考模式
`input`	输入类型列表，如 `["text"]`、`["text", "image"]`
`cost`	token 费用（用于成本追踪）
`contextWindow`	上下文窗口大小（token 数）
`maxTokens`	最大输出 token 数

模型目录模式

models.mode 控制自定义 Provider 与内置 Provider 的合并方式：

merge（默认）：自定义 Provider 与内置 Provider 合并共存
replace：自定义 Provider 完全替换内置目录

{
  models: {
    mode: "merge"  // 推荐，保留内置 Provider
  }
}

模型引用格式

配置完成后，通过 provider-id/model-id 格式引用模型：

{
  agents: {
    defaults: {
      model: {
        primary: "custom-proxy/llama-3.1-8b",
        fallbacks: ["lmstudio/minimax-m2.5-gs32"]
      }
    }
  }
}