一、OpenClaw 是什么
OpenClaw是一个开源的多通道 AI 网关（Multi-channel AI Gateway），核心定位是：
将大语言模型（LLM）能力接入多种通讯渠道（IM、语音、平台），同时提供 Agent 运行时、工具系统、记忆系统和插件体系，让 AI 不只是聊天机器人，而是可以主动执行任务的数字助手。
1.1 核心能力矩阵
| 能力维度 | 说明 |
|---|---|
| 多渠道接入 | 同时接入 Telegram、飞书、Discord、微信、企业微信、WhatsApp、Line、Signal 等 20+ 消息平台 |
| Agent 运行时 | 内置完整的 Agent 执行引擎，支持多 Agent 并发、工具调用、子任务分解 |
| 工具系统（Skills） | 可插拔的技能体系，通过 SKILL.md 定义工作流，扩展 Agent 能力边界 |
| 记忆系统 | 多级记忆架构：短期会话 → 每日日志 → 长期记忆（LanceDB 向量库） |
| 大模型路由 | 支持多个模型提供方，可配置默认模型、按场景路由、降级策略 |
| 插件体系 | 支持第三方扩展，可开发自定义 Channel 插件、Provider 插件 |
| 浏览器自动化 | 内置 CDP 协议浏览器控制，可操控真实浏览器完成网页任务 |
| 定时/周期任务 | 内置 Crontab 引擎，支持定时提醒、定期检查、延迟任务 |
1.2 架构概览
code复制
┌─────────────────────────────────────────────────────┐ │ OpenClaw Gateway │ │ │ │ ┌─────────┐ ┌──────────┐ ┌───────────────────┐ │ │ │ Channel │ │ Agent │ │ Tools / Skills │ │ │ │Plugins │ │ Runtime │ │ │ │ │ │(20+平台)│ │ │ │ • Web Search │ │ │ └────┬────┘ └─────┬────┘ │ • Browser Control │ │ │ │ │ │ • File I/O │ │ │ │ ┌──────┴─────┐ │ • Cron / Remind │ │ │ │ │ LLM Router│ │ • 200+ Skills │ │ │ │ │ + Memory │ │ from SkillHub │ │ │ │ └───────────┘ └────────────────────┘ │ └───────┼──────────────────────────────────────────────┘ │ ┌────▼───────────────┐ │ Model Providers │ │ • OpenAI / Azure │ │ • Claude (Anthropic)│ │ • Gemini / DeepSeek│ │ • 腾讯混元 / 百度 │ │ • 本地 Ollama / LM Studio │ │ • 自定义 OpenAI-compat API│ └────────────────────┘二、大模型接入方式
OpenClaw 支持三类大模型接入路径，下面逐一说明。
2.1 方式一：OpenAI 兼容 API（最通用）
适用于：所有提供 OpenAI 兼容接口的模型服务，包括：
- OpenAI 官方（GPT-4o、GPT-4o-mini 等）
- Azure OpenAI Service
- 硅基流动 / Fireworks AI / Together AI 等第三方聚合平台
- 几乎所有国产大模型 API（腾讯混元、百度文心、字节豆包、DeepSeek 等）
配置方法：
在openclaw.json的providers节点下添加：
json复制
{ "providers": { "my-openai": { "baseUrl": "https://api.example.com/v1", "apiKey": "sk-xxxxxxxxxxxxxxxx", "api": "openai-compat", "models": [ { "id": "gpt-4o", "name": "GPT-4o", "input": ["text", "image"], "reasoning": true }, { "id": "deepseek-chat", "name": "DeepSeek V3", "input": ["text"] } ] } } }关键参数说明：
baseUrl：API 端点，需包含/v1路径apiKey：访问密钥api：接口类型，写"openai-compat"即兼容 OpenAI 格式models[].id：实际调用的模型 ID（与 baseUrl 对应服务中的模型名一致）models[].reasoning：是否启用思维链推理（需要模型支持）
2.2 方式二：直接 Provider 插件（最深度）
OpenClaw 为部分主流模型提供了原生 Provider 插件，支持更好的功能特性（如 thinking 预算、流式输出、工具调用优化）。
已内置支持的 Provider：
| Provider | 说明 |
|---|---|
claude | Anthropic Claude 系列（支持 native tools、thinking） |
google-gemini | Google Gemini 系列 |
openai | OpenAI 官方（带 function calling 优化） |
qclaw | QClaw 自有路由（当前主配置方式） |
lmstudio | 本地 LM Studio（Ollama 类本地推理） |
ollama | 本地 Ollama |
配置示例（Anthropic Claude）：
json复制
{ "providers": { "claude": { "apiKey": "${ANTHROPIC_API_KEY}", "models": [ { "id": "claude-sonnet-4-7-20250611", "name": "Claude Sonnet 4", "input": ["text", "image"], "reasoning": true, "thinkingBudgetTokens": 16000 } ] } } }配置示例（本地 LM Studio）：
json复制
{ "providers": { "lmstudio": { "baseUrl": "http://localhost:1234/v1", "apiKey": "lm-studio", "api": "openai-compat", "models": [ { "id": "local-model", "name": "Qwen2.5-7B", "input": ["text"] } ] } } }2.3 方式三：MCP（Model Context Protocol）扩展接入
OpenClaw 支持通过 MCP 协议接入外部 AI 工具/数据源（不是 LLM 本身，而是 LLM 可以调用的工具生态）：
json复制
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\17616\\Documents"] }, "fetch": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"] } } }三、模型路由与 Agent 绑定
3.1 设置默认模型
在 Agent 配置中指定model.primary：
json复制
{ "agents": { "defaults": { "model": { "primary": "qclaw/modelroute" } } } }3.2 多模型路由策略
OpenClaw 支持按场景自动选择模型，通过models配置中的label标签匹配：
json复制
{ "agents": { "defaults": { "model": { "primary": "qclaw/modelroute", "routing": { "code": "claude/claude-sonnet-4-7-20250611", "creative": "qclaw/pool-kimi-k2.7-code-highspeed", "fast": "qclaw/modelroute" } } } } }3.3 环境变量注入敏感信息
推荐将 API Key 等敏感信息放在环境变量中，避免明文写入配置文件：
json复制
{ "providers": { "claude": { "apiKey": "${ANTHROPIC_API_KEY}" } } }在系统环境变量中设置：
powershell复制
# Windows PowerShell $env:ANTHROPIC_API_KEY = "sk-ant-xxxxx"四、实战配置清单
快速接入国产模型（以腾讯混元为例）
json复制
{ "providers": { "hunyuan": { "baseUrl": "https://hunyuan.cloud.tencent.com/hunyuan-api/v1", "apiKey": "${HUNYUAN_API_KEY}", "api": "openai-compat", "models": [ { "id": "hunyuan-pro", "name": "混元 Pro", "input": ["text"] } ] } } }快速接入 DeepSeek
json复制
{ "providers": { "deepseek": { "baseUrl": "https://api.deepseek.com/v1", "apiKey": "${DEEPSEEK_API_KEY}", "api": "openai-compat", "models": [ { "id": "deepseek-chat", "name": "DeepSeek V3", "input": ["text"] }, { "id": "deepseek-reasoner", "name": "DeepSeek R1（推理）", "input": ["text"], "reasoning": true } ] } } }接入本地 Ollama
json复制
{ "providers": { "ollama-local": { "baseUrl": "http://localhost:11434/v1", "apiKey": "ollama", "api": "openai-compat", "models": [ { "id": "qwen2.5:7b", "name": "Qwen 2.5 7B（本地）", "input": ["text"] } ] } } }注意：Ollama 默认模型名称格式为
model:tag，需要与ollama list输出一致。
五、完整 openclaw.json 参考结构
json复制
{ "version": 2, "agents": { "defaults": { "model": { "primary": "qclaw/modelroute" }, "workspace": "C:\\Users\\<用户名>\\.qclaw\\workspace", "maxConcurrent": 3, "timeoutSeconds": 72000, "heartbeat": { "isolatedSession": true, "lightContext": true, "model": "qclaw/modelroute" } }, "list": [ { "id": "main", "default": true, "name": "QClaw", "reasoningDefault": "stream", "skills": ["find-skills", "online-search", "xbrowser", "qclaw-cron-skill"], "identity": { "name": "QClaw" } } ] }, "providers": { "qclaw": { "baseUrl": "${QCLAW_LLM_BASE_URL}", "apiKey": "${QCLAW_LLM_API_KEY}", "api": "openai-compat", "models": [ { "id": "modelroute", "name": "modelroute", "input": ["text", "image"], "reasoning": true } ] }, "claude": { "apiKey": "${ANTHROPIC_API_KEY}", "models": [ { "id": "claude-sonnet-4-7-20250611", "name": "Claude Sonnet 4", "input": ["text", "image"], "reasoning": true, "thinkingBudgetTokens": 16000 } ] }, "deepseek": { "baseUrl": "https://api.deepseek.com/v1", "apiKey": "${DEEPSEEK_API_KEY}", "api": "openai-compat", "models": [ { "id": "deepseek-chat", "name": "DeepSeek V3", "input": ["text"] }, { "id": "deepseek-reasoner", "name": "DeepSeek R1", "input": ["text"], "reasoning": true } ] } }, "tools": { "web": { "search": { "enabled": true } }, "alsoAllow": ["sessions_spawn", "skillhub_install"] }, "browser": { "enabled": true, "defaultProfile": "openclaw" }, "gateway": { "port": 60802, "mode": "local", "bind": "loopback" } }六、常见问题
Q1：配置修改后需要重启吗？
是的，通过
openclaw gateway restart重启网关使配置生效。
Q2：多个 Provider 同时可用时，Agent 使用哪个模型？
按
agents.defaults.model.primary指定的值决定，也可以通过routing按场景分流。
Q3：API Key 不想写在配置里怎么办？
使用
${环境变量名}语法引用，OpenClaw 启动时自动从~/.qclaw/qclaw.env或系统环境变量读取。
Q4：本地模型（Ollama/LM Studio）接入慢或超时？
检查 localhost 是否可访问，确认模型已加载（LM Studio 左下角需显示 “Model loaded”），Ollama 需提前运行
ollama run <model>。
