OpenClaw Model Provider

Help users add custom model providers to OpenClaw. Use when the user wants to add a new AI model provider (like custom OpenAI-compatible APIs, local LLMs, or third-party services) to their OpenClaw configuration. Handles configuration of models.providers, agents.defaults.model, environment variables, and validation.

ksbbs@ksbbs

Install

openclaw skills install @ksbbs/openclaw-model-provider

OpenClaw 自定义模型提供商配置

帮助用户在 OpenClaw 中添加和配置自定义模型提供商。

快速开始

判断用户的配置类型：

类型 A：内置提供商（只需一处配置）

OpenClaw 已内置支持，只需设置 API Key 和默认模型：

openai, anthropic, moonshot, zai, google, deepseek
配置位置：agents.defaults.model.primary
API Key：通过环境变量或 env 字段设置

类型 B：自定义提供商（需要两处配置）

文档未内置支持的模型或自建代理：

配置位置 1：models.providers - 定义提供商信息
配置位置 2：agents.defaults.model - 设置默认使用

配置流程

步骤 1：收集必要信息

询问用户提供：

提供商名称（如 my-openai-proxy）
API 基础地址（如 https://api.xxx.com/v1）
API 密钥
模型 ID（如 gpt-4, kimi-k2.5）
接口类型：
- openai-completions - OpenAI 兼容接口（大多数情况）
- anthropic-messages - Anthropic 兼容接口

步骤 2：生成配置

根据用户提供的信息，生成完整的配置片段。

自定义提供商完整配置示例：

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "提供商名称/模型ID"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "提供商名称": {
        "baseUrl": "https://api.xxx.com/v1",
        "apiKey": "${ENV_VAR_NAME}",
        "api": "openai-completions",
        "models": [
          {
            "id": "模型ID",
            "name": "显示名称",
            "contextWindow": 128000,
            "maxTokens": 4096,
            "reasoning": false,
            "input": ["text", "image"]
          }
        ]
      }
    }
  }
}

步骤 3：应用配置

指导用户将配置合并到 ~/.openclaw/openclaw.json：

bash

# 1. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 2. 编辑配置
openclaw config edit
# 或直接修改文件
nano ~/.openclaw/openclaw.json

步骤 4：验证配置

bash

# 检查配置格式
openclaw config validate

# 查看可用模型列表
openclaw models list

# 测试模型
openclaw models test 提供商名称/模型ID

环境变量设置

推荐将 API Key 放在环境变量中，而非硬编码到配置文件：

方式 1：shell 配置文件

bash

# ~/.bashrc 或 ~/.zshrc
export PROVIDER_API_KEY="sk-xxxxx"

方式 2：OpenClaw 配置中的 env 字段

json

{
  "env": {
    "PROVIDER_API_KEY": "sk-xxxxx"
  }
}

方式 3：.env 文件（如果 OpenClaw 支持）

常见提供商模板

OpenAI 兼容代理

json

{
  "models": {
    "providers": {
      "custom-openai": {
        "baseUrl": "https://api.openai-proxy.com/v1",
        "apiKey": "${OPENAI_PROXY_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4",
            "name": "GPT-4",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom-openai/gpt-4"
      }
    }
  }
}

本地 Ollama

json

{
  "models": {
    "providers": {
      "ollama-local": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [
          {
            "id": "llama3.3",
            "name": "Llama 3.3",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

Moonshot AI (Kimi)

json

{
  "models": {
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.ai/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

故障排查

配置验证失败

bash

# 检查 JSON 语法
openclaw config validate

# 查看详细错误
openclaw config validate --verbose

模型不可用

bash

# 确认模型列表中包含目标模型
openclaw models list | grep 提供商名称

# 测试连接
openclaw models test 提供商名称/模型ID --verbose

API Key 无效

检查环境变量是否正确设置：echo $PROVIDER_API_KEY
确认 OpenClaw 能读取环境变量
检查 API Key 是否有调用权限和余额

高级配置

多密钥轮换

支持配置多个 API Key 实现自动故障转移：

json

{
  "env": {
    "PROVIDER_API_KEY_1": "sk-xxx1",
    "PROVIDER_API_KEY_2": "sk-xxx2",
    "PROVIDER_API_KEY_3": "sk-xxx3"
  }
}

或在 shell 中：

bash

export PROVIDER_API_KEYS="sk-xxx1,sk-xxx2,sk-xxx3"

模型参数覆盖

为特定模型设置默认参数：

json

{
  "agents": {
    "defaults": {
      "models": {
        "提供商名称/模型ID": {
          "params": {
            "temperature": 0.7,
            "maxTokens": 2048,
            "fastMode": true
          }
        }
      }
    }
  }
}

参考资源

使用示例

用户说："我想添加硅基流动的 DeepSeek-R1"

执行流程：

确认是自定义提供商（非内置）
收集信息：
- 名称：siliconflow
- 地址：https://api.siliconflow.cn/v1
- API Key：用户提供的 key
- 模型：deepseek-ai/DeepSeek-R1
生成配置并指导用户应用
验证配置