每日备份 2026-06-10 12:57:13

2026-06-10 12:57:14 +08:00
1 parent fda2ccb8c2
commit 3d2e638c6a
@@ -0,0 +1,421 @@
+# 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*