- name
- openclaw-model-provider
- description
- 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.
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：生成配置
根据用户提供的信息，生成完整的配置片段。
自定义提供商完整配置示例：
{
"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：
# 1. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# 2. 编辑配置
openclaw config edit
# 或直接修改文件
nano ~/.openclaw/openclaw.json步骤 4：验证配置
# 检查配置格式
openclaw config validate
# 查看可用模型列表
openclaw models list
# 测试模型
openclaw models test 提供商名称/模型ID环境变量设置
推荐将 API Key 放在环境变量中，而非硬编码到配置文件：
方式 1：shell 配置文件
# ~/.bashrc 或 ~/.zshrc
export PROVIDER_API_KEY="sk-xxxxx"方式 2：OpenClaw 配置中的 env 字段
{
"env": {
"PROVIDER_API_KEY": "sk-xxxxx"
}
}方式 3：.env 文件（如果 OpenClaw 支持）
常见提供商模板
OpenAI 兼容代理
{
"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
{
"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)
{
"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
}
]
}
}
}
}故障排查
配置验证失败
# 检查 JSON 语法
openclaw config validate
# 查看详细错误
openclaw config validate --verbose模型不可用
# 确认模型列表中包含目标模型
openclaw models list | grep 提供商名称
# 测试连接
openclaw models test 提供商名称/模型ID --verboseAPI Key 无效
- 检查环境变量是否正确设置：
echo $PROVIDER_API_KEY - 确认 OpenClaw 能读取环境变量
- 检查 API Key 是否有调用权限和余额
高级配置
多密钥轮换
支持配置多个 API Key 实现自动故障转移：
{
"env": {
"PROVIDER_API_KEY_1": "sk-xxx1",
"PROVIDER_API_KEY_2": "sk-xxx2",
"PROVIDER_API_KEY_3": "sk-xxx3"
}
}或在 shell 中：
export PROVIDER_API_KEYS="sk-xxx1,sk-xxx2,sk-xxx3"模型参数覆盖
为特定模型设置默认参数：
{
"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
- 生成配置并指导用户应用
- 验证配置