一、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>。