OpenClaw 对接大语言模型 API 全配置指南
OpenClaw 作为开源 AI 智能体网关，核心能力是通过统一接口对接各类大语言模型 API，实现多模型灵活切换与统一调用。其配置核心围绕 baseUrl（API 基础地址）、apiKey（API 密钥）、模型 ID 三大参数展开，同时兼容 OpenAI 协议、原生协议等多种适配方式，支持国内外主流商业模型与开源模型接入。本文将系统梳理 OpenClaw 对接主流大模型的 API 配置规范、参数说明与实操示例，助力快速完成模型对接。
一、OpenClaw 模型配置核心参数解析
OpenClaw 模型配置主要通过 ~/.openclaw/openclaw.json 配置文件实现，核心配置块为 models.providers，每个模型提供商对应独立配置项，关键参数如下：
| 参数 | 类型 | 说明 | 配置要点 |
|---|---|---|---|
| baseUrl | string | API 服务基础地址 | 必须与模型官方接口一致，末尾禁止加斜杠，如 https://api.openai.com/v1 |
| apiKey | string | 模型平台 API 密钥 | 从对应平台控制台获取，建议通过环境变量 ${ENV_VAR} 引用，避免明文泄露 |
| api | string | 请求协议适配器 | 主流为 openai-completions（OpenAI 兼容协议），原生模型需指定对应协议（如 anthropic） |
| models | array | 模型列表 | 包含模型 ID、名称、上下文窗口等信息，id 为模型官方唯一标识 |
| id | string | 模型唯一 ID | 必须与模型平台提供的标识完全一致，如 gpt-4o、deepseek-chat |
| name | string | 模型自定义名称 | OpenClaw 内显示的模型别名，方便识别 |
| contextWindow | number | 上下文窗口大小 | 模型支持的最大 Token 长度，影响长文本处理能力 |
| maxTokens | number | 单次生成最大 Token | 限制模型单次响应长度，避免超额计费 |
二、主流大语言模型 API 对接配置（含 baseUrl、apiKey、模型 ID）
（一）国际主流模型
1. OpenAI（GPT 系列）
平台入口：https://platform.openai.com/ 核心配置：
"openai":{
"baseUrl":"https://api.openai.com/v1",
"apiKey":"${OPENAI_API_KEY}",
"api":"openai-completions",
"models":[
{
"id":"gpt-4o",
"name":"GPT-4o",
"contextWindow":128000,
"maxTokens":4096
},
{
"id":"gpt-3.5-turbo",
"name":"GPT-3.5 Turbo",
"contextWindow":16384,
"maxTokens":4096
}
]
}模型 ID 说明：gpt-4o（多模态旗舰）、gpt-4-turbo、gpt-3.5-turbo 等。
2. Anthropic（Claude 系列）
平台入口：https://console.anthropic.com/ 核心配置：
"anthropic":{
"baseUrl":"https://api.anthropic.com/v1",
"apiKey":"${ANTHROPIC_API_KEY}",
"api":"anthropic",
"models":[
{
"id":"claude-3-opus-20240229",
"name":"Claude Opus 4.6",
"contextWindow":200000,
"maxTokens":8192
},
{
"id":"claude-3-sonnet-20240229",
"name":"Claude Sonnet 4.6",
"contextWindow":200000,
"maxTokens":8192
}
]
}模型 ID 说明：claude-3-opus-20240229（旗舰）、claude-3-sonnet-20240229、claude-3-haiku-20240307。
3. Google（Gemini 系列）
平台入口：https://aistudio.google.com/ 核心配置：
"google":{
"baseUrl":"https://generativelanguage.googleapis.com/v1beta",
"apiKey":"${GOOGLE_API_KEY}",
"api":"google",
"models":[
{
"id":"gemini-1.5-pro",
"name":"Gemini 1.5 Pro",
"contextWindow":1000000,
"maxTokens":8192
}
]
}模型 ID 说明：gemini-1.5-pro、gemini-1.5-flash。
4. xAI（Grok 系列）
平台入口：https://x.ai/ 核心配置：
"xai":{
"baseUrl":"https://api.x.ai/v1",
"apiKey":"${XAI_API_KEY}",
"api":"openai-completions",
"models":[
{
"id":"grok-4.1",
"name":"Grok 4.1",
"contextWindow":128000,
"maxTokens":4096
}
]
}（二）国内主流模型
1. DeepSeek
平台入口：https://platform.deepseek.com/ 核心配置：
"deepseek":{
"baseUrl":"https://api.deepseek.com/v1",
"apiKey":"${DEEPSEEK_API_KEY}",
"api":"openai-completions",
"models":[
{
"id":"deepseek-chat",
"name":"DeepSeek Chat",
"contextWindow":128000,
"maxTokens":8192
},
{
"id":"deepseek-reasoner",
"name":"DeepSeek R1",
"contextWindow":128000,
"maxTokens":32768,
"reasoning":true
}
]
}模型 ID 说明：deepseek-chat（通用对话）、deepseek-reasoner（深度推理）。
2. 阿里云百炼（通义千问系列）
平台入口：https://www.aliyun.com/product/bailian 核心配置：
"bailian":{
"baseUrl":"https://dashscope.aliyuncs.com/api/v1",
"apiKey":"${BAILIAN_API_KEY}",
"apiSecret":"${BAILIAN_API_SECRET}",
"api":"openai-completions",
"models":[
{
"id":"qwen3.5-plus",
"name":"通义千问3.5 Plus",
"contextWindow":977000,
"maxTokens":8192
},
{
"id":"qwen3-coder-next",
"name":"通义千问3 Coder",
"contextWindow":256000,
"maxTokens":8192
}
]
}模型 ID 说明：qwen3.5-plus、qwen3-max、qwen3-coder-next。
3. 智谱 AI（GLM 系列）
平台入口：https://open.bigmodel.cn/ 核心配置：
"zhipu":{
"baseUrl":"https://open.bigmodel.cn/api/paas/v4",
"apiKey":"${ZHIPU_API_KEY}",
"api":"openai-completions",
"models":[
{
"id":"glm-4-plus",
"name":"GLM-4 Plus",
"contextWindow":128000,
"maxTokens":4096
},
{
"id":"glm-4-flash",
"name":"GLM-4 Flash",
"contextWindow":128000,
"maxTokens":4096
}
]
}4. Moonshot（Kimi 系列）
平台入口：https://platform.moonshot.cn/ 核心配置：
"moonshot":{
"baseUrl":"https://api.moonshot.cn/v1",
"apiKey":"${MOONSHOT_API_KEY}",
"api":"openai-completions",
"models":[
{
"id":"kimi-chat",
"name":"Kimi Chat",
"contextWindow":200000,
"maxTokens":4096
},
{
"id":"kimi-coding",
"name":"Kimi Coding",
"contextWindow":256000,
"maxTokens":4096
}
]
}5. 百度文心一言
平台入口：https://console.bce.baidu.com/qianfan/ 核心配置：
"ernie":{
"baseUrl":"https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat",
"apiKey":"${ERNIE_API_KEY}",
"secretKey":"${ERNIE_SECRET_KEY}",
"api":"ernie",
"models":[
{
"id":"ernie-3.5-turbo",
"name":"文心一言3.5 Turbo",
"contextWindow":128000,
"maxTokens":4096
}
]
}三、OpenClaw 模型对接实操步骤
1. 获取 API 密钥
登录对应模型平台，完成实名认证后，在「API 密钥」或「开发者中心」创建新密钥，妥善保存（仅展示一次，丢失需重新创建）。
2. 配置环境变量（推荐）
将 API 密钥存入系统环境变量，避免配置文件明文泄露：
# Linux/Mac
echo "export OPENAI_API_KEY='你的密钥'">>~/.bashrc
source ~/.bashrc
# Windows（PowerShell）
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY","你的密钥","User")3. 编辑 OpenClaw 配置文件
打开 ~/.openclaw/openclaw.json，在 models.providers 中添加对应模型配置，示例如下：
{
"models":{
"mode":"merge",
"providers":{
"openai":{/*OpenAI配置*/},
"deepseek":{/*DeepSeek配置*/}
},
"defaults":{
"model":{
"primary":"deepseek/deepseek-chat"//设置默认模型
}
}
}
}4. 重启 OpenClaw 服务
配置修改后，执行命令重启网关使配置生效：
openclaw gateway restart
5. 验证配置
发送测试消息，若模型正常响应，说明对接成功；可通过 openclaw models list 查看已配置模型列表。
四、常见问题与避坑指南
baseUrl 错误：末尾加斜杠、协议错误（http/https）、地址过时，需严格核对官方文档。 模型 ID 不匹配：使用自定义名称而非官方 ID，导致调用失败，需复制平台提供的完整模型标识。 apiKey 泄露：明文写入配置文件，建议通过环境变量引用，或使用 OpenClaw 内置的密钥管理功能。 协议适配器错误：非 OpenAI 兼容模型使用 openai-completions，需指定原生协议（如 anthropic、ernie）。 Token 超额：未设置 maxTokens 或上下文窗口过大，导致高额计费，需根据需求合理配置。
五、总结
OpenClaw 凭借灵活的配置架构，实现了对国内外主流大语言模型的统一对接，核心在于准确配置 baseUrl、apiKey、模型 ID 三大参数，并选择适配的协议类型。通过本文提供的配置示例与实操步骤，可快速完成多模型接入，结合 OpenClaw 的智能体能力，实现复杂任务的自动化处理。后续可进一步探索 OpenClaw 的模型切换、负载均衡、多模型协作等高级功能，最大化发挥大模型的价值。
