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...

Security Scan

The skill is an instruction-only guide for adding model providers to OpenClaw and its requested actions and guidance are coherent with that purpose.

Purpose & Capability

Name/description match the content: the skill is purely an instruction guide for configuring OpenClaw model providers. It does not request unrelated binaries, credentials, or config paths beyond the OpenClaw configuration it documents.

Instruction Scope

SKILL.md stays on-topic: collects provider name, baseUrl, API key, model ID and shows how to generate/merge the configuration, edit ~/.openclaw/openclaw.json, validate and test models. It mentions reading/writing the OpenClaw config and environment variables, which is expected for this task and is explicitly scoped.

Install Mechanism

No install spec or code is provided (instruction-only), so nothing is downloaded or written by the skill itself. This minimizes install-time risk.

Credentials

The skill asks the user to supply API keys for the provider being added and recommends storing them in environment variables. It does not declare or require any platform-level secrets or unrelated credentials. Asking users to set provider API keys is proportionate to the stated purpose.

Persistence & Privilege

No special persistence or elevated privileges are requested. Flags are default (always:false, user-invocable:true). The instructions only modify the user's OpenClaw config when the user performs the steps.

Assessment

This skill is a how-to for adding model providers to OpenClaw and appears internally consistent. Before following it: 1) Only use provider base URLs you trust (do not point to unknown or shortened links). 2) Prefer environment variables (not hardcoding keys into config files) and rotate keys if you test with high-privilege credentials. 3) Backup ~/.openclaw/openclaw.json (the guide already recommends this). 4) When testing a third‑party provider, limit the API key's permissions or use a test key to avoid unexpected charges or data leakage. If you need higher assurance, verify the referenced OpenClaw docs URL and run config validation/test commands locally rather than pasting secrets into chat or public places.

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. 验证配置