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. 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: ${ENVVARNAME},
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 PROVIDERAPIKEY=sk-xxxxx

方式 2：OpenClaw 配置中的 env 字段
json
{
env: {
PROVIDERAPIKEY: sk-xxxxx
}
}

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

常见提供商模板

OpenAI 兼容代理

json
{
models: {
providers: {
custom-openai: {
baseUrl: https://api.openai-proxy.com/v1,
apiKey: ${OPENAIPROXYKEY},
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: ${MOONSHOTAPIKEY},
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 $PROVIDERAPIKEY
• 确认 OpenClaw 能读取环境变量
• 检查 API Key 是否有调用权限和余额

高级配置

多密钥轮换

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

json
{
env: {
PROVIDERAPIKEY_1: sk-xxx1,
PROVIDERAPIKEY_2: sk-xxx2,
PROVIDERAPIKEY_3: sk-xxx3
}
}

或在 shell 中：
bash
export PROVIDERAPIKEYS=sk-xxx1,sk-xxx2,sk-xxx3

模型参数覆盖

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

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

参考资源

• - OpenClaw 官方文档 - 模型提供商
• OpenClaw 配置参考

使用示例

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

执行流程：

1. 1. 确认是自定义提供商（非内置）
2. 收集信息：

- 名称：siliconflow
- 地址：https://api.siliconflow.cn/v1
- API Key：用户提供的 key
- 模型：deepseek-ai/DeepSeek-R1

1. 3. 生成配置并指导用户应用
2. 验证配置