Skill: ksbbs/openclaw-model-provider (version 1.0.0)

--- 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：生成配置 根据用户提供的信息，生成完整的配置片段。 **自定义提供商完整配置示例：** ```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 } } } } } } ``` ## 参考资源 - [OpenClaw 官方文档 - 模型提供商](https://docs.openclaw.ai/zh-CN/concepts/model-providers) - [OpenClaw 配置参考](references/openclaw-config-reference.md) ## 使用示例 **用户说**："我想添加硅基流动的 DeepSeek-R1" **执行流程**： 1. 确认是自定义提供商（非内置） 2. 收集信息： - 名称：`siliconflow` - 地址：`https://api.siliconflow.cn/v1` - API Key：用户提供的 key - 模型：`deepseek-ai/DeepSeek-R1` 3. 生成配置并指导用户应用 4. 验证配置

path: references/openclaw-config-reference.md
content: # OpenClaw 模型提供商配置参考

## 完整配置结构

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "provider/model-id"
      },
      "models": {
        "provider/model-id": {
          "params": {
            "temperature": 0.7,
            "maxTokens": 4096,
            "fastMode": false,
            "transport": "auto"
          }
        }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "provider-name": {
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "${ENV_VAR}",
        "api": "openai-completions",
        "models": [
          {
            "id": "model-id",
            "name": "Display Name",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "env": {
    "ENV_VAR": "actual-api-key"
  }
}
```

## API 类型说明

| API 类型 | 说明 | 适用场景 |
|---------|------|----------|
| `openai-completions` | OpenAI 兼容接口 | 大多数第三方代理、OpenRouter、本地模型 |
| `anthropic-messages` | Anthropic 兼容接口 | Claude API、部分兼容代理 |

## 字段详解

### models.providers.{provider}

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `baseUrl` | string | 是 | API 基础地址，以 /v1 结尾 |
| `apiKey` | string | 是 | API 密钥，建议使用 `${ENV_VAR}` 格式引用环境变量 |
| `api` | string | 是 | API 类型，`openai-completions` 或 `anthropic-messages` |
| `models` | array | 是 | 该提供商下的模型列表 |

### models.providers.{provider}.models[]{}

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | 是 | 模型 ID，用于 API 调用 |
| `name` | string | 否 | 显示名称 |
| `api` | string | 否 | 覆盖 provider 级别的 API 类型 |
| `reasoning` | boolean | 否 | 是否支持推理/thinking 模式 |
| `input` | array | 否 | 支持的输入类型，如 `["text", "image"]` |
| `contextWindow` | number | 否 | 上下文窗口大小（tokens） |
| `maxTokens` | number | 否 | 最大输出 token 数 |
| `cost` | object | 否 | 价格信息 |

### agents.defaults.model

| 字段 | 类型 | 说明 |
|------|------|------|
| `primary` | string | 默认主模型，格式 `provider/model-id` |

### agents.defaults.models.{model-ref}

| 字段 | 类型 | 说明 |
|------|------|------|
| `params` | object | 该模型的默认参数 |
| `params.temperature` | number | 温度参数 |
| `params.maxTokens` | number | 最大 token 数 |
| `params.fastMode` | boolean | 快速模式（部分提供商支持） |
| `params.transport` | string | 传输方式：`sse`, `websocket`, `auto` |

## 环境变量优先级

OpenClaw 支持多种方式设置 API Key，优先级从高到低：

1. `OPENCLAW_LIVE_{PROVIDER}_KEY` - 最高优先级，单个覆盖
2. `{PROVIDER}_API_KEYS` - 逗号分隔的密钥列表，支持轮换
3. `{PROVIDER}_API_KEY` - 主密钥
4. `{PROVIDER}_API_KEY_1`, `{PROVIDER}_API_KEY_2`... - 编号列表
5. 配置文件中 `env` 字段定义的值

## 常见错误

### 1. JSON 语法错误
```bash
# 使用 jq 验证
jq '.' ~/.openclaw/openclaw.json
```

### 2. API Key 未找到
- 确认环境变量已正确导出
- 检查变量名拼写
- 确认 OpenClaw 进程能访问该环境变量

### 3. 模型不存在
- 运行 `openclaw models list` 确认模型已加载
- 检查 `models.providers` 配置是否正确合并
- 确认 `mode` 设置为 `merge` 而非 `replace`

### 4. 连接失败
- 检查 `baseUrl` 是否正确
- 确认网络可以访问该地址
- 检查 API Key 是否有调用权限

## 内置提供商列表

以下提供商无需 `models.providers` 配置，直接设置 API Key 即可：

- `openai` - OPENAI_API_KEY
- `anthropic` - ANTHROPIC_API_KEY
- `moonshot` - MOONSHOT_API_KEY
- `zai` - ZAI_API_KEY
- `google` - GEMINI_API_KEY
- `openrouter` - OPENROUTER_API_KEY
- `groq` - GROQ_API_KEY
- `together` - TOGETHER_API_KEY
- 等...


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)