OpenClaw Model Provider

---

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：收集必要信息

询问用户提供： 1. 提供商名称（如 my-openai-proxy） 2. API 基础地址（如 https://api.xxx.com/v1） 3. API 密钥 4. 模型 ID（如 gpt-4, kimi-k2.5） 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 --verbose

API 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
          }
        }
      }
    }
  }
}

参考资源

OpenClaw 官方文档 - 模型提供商

OpenClaw 配置参考

使用示例

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

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