# OpenClaw 模型配置语法规格及配置示例

## 目录
1. [模型配置概述](#模型配置概述)
2. [配置文件结构](#配置文件结构)
3. [模型提供者配置](#模型提供者配置)
4. [模型别名配置](#模型别名配置)
5. [会话模型配置](#会话模型配置)
6. [配置示例](#配置示例)
7. [常用命令](#常用命令)

## 模型配置概述

OpenClaw 支持多种AI模型，包括：
- OpenAI兼容API模型 (DeepSeek, Qwen等)
- Ollama本地模型
- Anthropic Claude模型
- Google Gemini模型
- 其他兼容OpenAI API的模型

## 配置文件结构

OpenClaw 使用JSON格式的配置文件，主要配置文件位于：
- `/root/.openclaw/openclaw.json` - 主配置文件
- `/root/.openclaw/agents/main/agent/models.json` - 模型提供者配置文件
- `/root/.openclaw/agents/main/agent/config.json` - 代理配置

## 模型提供者配置

### 基本语法
```json
{
  "models": {
    "providers": {
      "provider_name": {
        "baseUrl": "API基础URL",
        "apiKey": "API密钥",
        "api": "API类型",
        "models": [
          {
            "id": "模型ID",
            "name": "模型显示名称",
            "reasoning": true/false,
            "input": ["text", "image"],
            "cost": {
              "input": 每token价格,
              "output": 每token价格,
              "cacheRead": 缓存读取价格,
              "cacheWrite": 缓存写入价格
            },
            "contextWindow": 上下文窗口大小,
            "maxTokens": 最大输出token数
          }
        ]
      }
    }
  }
}
```

### 参数说明
- `provider_name`: 提供者标识符 (如: deepseek, ollama, openai等)
- `baseUrl`: API基础URL地址
- `apiKey`: API密钥 (本地模型可使用占位符)
- `api`: API类型，通常为 "openai-completions"
- `id`: 模型唯一标识符
- `name`: 模型显示名称
- `reasoning`: 是否支持推理模式
- `input`: 支持的输入类型数组
- `contextWindow`: 上下文窗口大小 (token数)
- `maxTokens`: 最大输出token数

## 模型别名配置

### 基本语法
```json
{
  "agents": {
    "defaults": {
      "models": {
        "provider/model_id": {
          "alias": "显示别名"
        }
      }
    }
  }
}
```

### 参数说明
- `provider/model_id`: 完整的模型标识符 (提供者/模型ID)
- `alias`: 用户友好的显示名称

## 会话模型配置

### 基本语法
```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "主模型标识符",
        "fallbacks": ["备用模型1", "备用模型2"]
      }
    }
  }
}
```

### 参数说明
- `primary`: 主模型标识符 (格式: provider/model_id)
- `fallbacks`: 备用模型数组，在主模型不可用时使用

## 配置示例

### 示例1: DeepSeek模型配置
```json
{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-your-api-key-here",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "deepseek-chat",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 32768,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallbacks": ["deepseek/deepseek-chat"]
      },
      "models": {
        "deepseek/deepseek-chat": {
          "alias": "DeepSeek"
        }
      }
    }
  }
}
```

### 示例2: Ollama本地模型配置
```json
{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [
          {
            "id": "llama3:latest",
            "name": "llama3:latest",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 8192,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/llama3:latest",
        "fallbacks": ["deepseek/deepseek-chat"]
      },
      "models": {
        "ollama/llama3:latest": {
          "alias": "本地Llama3"
        },
        "deepseek/deepseek-chat": {
          "alias": "DeepSeek云端"
        }
      }
    }
  }
}
```

### 示例3: 多模型提供者配置
```json
{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-openai-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      },
      "anthropic": {
        "baseUrl": "https://api.anthropic.com/v1",
        "apiKey": "sk-ant-api-key",
        "api": "anthropic",
        "models": [
          {
            "id": "claude-3-5-sonnet-20241022",
            "name": "Claude 3.5 Sonnet",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      },
      "google": {
        "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
        "apiKey": "google-api-key",
        "api": "google",
        "models": [
          {
            "id": "gemini-1.5-pro",
            "name": "Gemini 1.5 Pro",
            "reasoning": true,
            "input": ["text", "image", "audio", "video"],
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4o",
        "fallbacks": ["anthropic/claude-3-5-sonnet-20241022", "google/gemini-1.5-pro"]
      },
      "models": {
        "openai/gpt-4o": {
          "alias": "GPT-4o"
        },
        "anthropic/claude-3-5-sonnet-20241022": {
          "alias": "Claude 3.5"
        },
        "google/gemini-1.5-pro": {
          "alias": "Gemini Pro"
        }
      }
    }
  }
}
```

### 示例4: 当前系统实际配置 (参考)
```json
{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "sk-9df28699a75146efae67c44e0a3d57a8",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "deepseek-chat",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 32768,
            "maxTokens": 8192
          }
        ]
      },
      "ollama": {
        "baseUrl": "http://192.168.0.66:11434/v1",
        "apiKey": "local-no-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "llama3:latest",
            "name": "llama3:latest",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 8192,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallbacks": ["deepseek/deepseek-chat"]
      },
      "models": {
        "ollama/llama3:latest": {
          "alias": "Local Win10 Llama3"
        },
        "deepseek/deepseek-chat": {
          "alias": "DeepSeek"
        }
      }
    }
  }
}
```

## 常用命令

### 1. 查看当前模型配置
```bash
openclaw status
```

### 2. 查看详细配置
```bash
cat /root/.openclaw/openclaw.json | jq '.models'
```

### 3. 修改模型配置
```bash
# 使用openclaw configure命令
openclaw configure models.providers.deepseek.apiKey "新的API密钥"

# 或直接编辑配置文件
nano /root/.openclaw/openclaw.json
```

### 4. 重启网关应用配置
```bash
openclaw gateway restart
```

### 5. 切换会话模型
在聊天界面中使用命令：
```
/model deepseek/deepseek-chat
```

或使用别名：
```
/model DeepSeek
```

### 6. 查看可用模型列表
```bash
openclaw models list
```

## 注意事项

1. **API密钥安全**: 确保API密钥安全存储，不要泄露
2. **配置验证**: 修改配置后使用 `openclaw status` 验证配置
3. **网关重启**: 修改模型配置后需要重启网关服务
4. **网络连接**: 确保模型API服务器可访问
5. **费用监控**: 注意API使用费用，特别是商业API
6. **本地模型**: Ollama等本地模型需要确保服务运行正常

## 故障排除

### 1. 模型不可用
- 检查API密钥是否正确
- 验证网络连接
- 确认模型提供者服务状态

### 2. 配置错误
- 检查JSON格式是否正确
- 验证配置路径和权限
- 查看网关日志: `openclaw logs --follow`

### 3. 性能问题
- 调整上下文窗口大小
- 启用/禁用推理模式
- 考虑使用本地模型减少延迟

---

*文档创建时间: 2026-02-02 10:48 GMT+8*
*基于当前系统配置: /root/.openclaw/openclaw.json*
*OpenClaw版本: 2026.1.30*