OpenClaw 完整搭建指南：从零开始打造你的 AI 助手

Ne0inhk

— 9 min read
OpenClaw 完整搭建指南：从零开始打造你的 AI 助手

OpenClaw 完整搭建指南：从零开始打造你的 AI 助手

本文基于实际部署经验，详细介绍 OpenClaw 的安装、配置 GitHub Copilot / Qwen 模型、接入钉钉、解决常见问题，以及搭建本地模型的完整流程。
在这里插入图片描述

目录

  1. 什么是 OpenClaw
  2. 环境准备与安装
  3. 配置模型提供商
  4. 接入钉钉机器人
  5. 钉钉插件常见问题与解决方案
  6. 日常使用技巧
  7. 搭建本地模型（llama.cpp）
  8. 总结与资源

一、什么是 OpenClaw

OpenClaw 是一个开源的 AI 助手框架，可以：

  • 🤖 接入多种大模型（Claude、GPT、Qwen、本地模型等）
  • 💬 连接多个消息平台（钉钉、Telegram、Discord、微信等）
  • 🛠️ 执行文件操作、Shell 命令、浏览器自动化
  • ⏰ 设置定时任务和提醒
  • 🧠 拥有持久记忆能力

简单说，它让你拥有一个 7x24 小时在线的 AI 助手，可以通过任何聊天软件与它对话。

项目地址： https://github.com/openclaw/openclaw
官方文档： https://docs.openclaw.ai

二、环境准备与安装

1. 系统要求

  • 操作系统： macOS、Linux 或 Windows（需要 WSL2）
  • Node.js： >= 22.x
  • 网络： 能访问 GitHub（配置模型时需要）

2. 安装 Node.js（如果没有）

Windows WSL / Ubuntu：

curl -fsSL https://deb.nodesource.com/setup_22.x |sudo -E bash - sudoaptinstall -y nodejs

macOS：

brew install node@22

验证安装：

node -v # 应显示 v22.x.xnpm -v

3. 安装 OpenClaw

推荐方式（一键安装）：

Linux / macOS：

curl -fsSL https://openclaw.ai/install.sh |bash

Windows PowerShell：

iwr-useb https://openclaw.ai/install.ps1 |iex

手动安装：

npminstall -g openclaw@latest openclaw onboard --install-daemon

4. 运行引导程序

安装完成后会自动运行引导程序，如果跳过了，可以手动执行：

openclaw onboard --install-daemon

引导程序会帮你：

  • 选择运行模式（本地/云端）
  • 配置默认模型
  • 设置 Gateway 端口
  • 安装守护进程

5. 验证安装

openclaw status # 查看服务状态 openclaw doctor # 诊断问题 openclaw health # 健康检查

三、配置模型提供商

OpenClaw 支持多种模型提供商，这里介绍最常用的两种：

方案一：GitHub Copilot（推荐）

如果你有 GitHub Copilot 订阅（包括学生包），可以直接使用：

openclaw models auth login-github-copilot

执行后会显示一个链接和验证码：

  1. 在浏览器中打开链接
  2. 输入验证码
  3. 授权 GitHub 应用
  4. 等待终端显示成功

设置默认模型：

openclaw models set github-copilot/claude-opus-4.5 # 或者使用 GPT-4o openclaw models set github-copilot/gpt-4o

可用模型列表：

  • github-copilot/claude-opus-4.5 — Claude Opus（最强）
  • github-copilot/claude-sonnet-4 — Claude Sonnet（均衡）
  • github-copilot/gpt-4o — GPT-4o
  • github-copilot/gpt-4.1 — GPT-4 Turbo

方案二：Qwen（通义千问，免费）

Qwen 提供免费的 OAuth 登录，每天 2000 次请求：

1. 启用插件：

openclaw plugins enable qwen-portal-auth openclaw gateway restart

2. 登录认证：

openclaw models auth login --provider qwen-portal --set-default

按提示在浏览器中完成登录。

3. 设置默认模型：

openclaw models set qwen-portal/coder-model

可用模型：

  • qwen-portal/coder-model — Qwen Coder（代码增强）
  • qwen-portal/vision-model — Qwen Vision（支持图片）

方案三：其他提供商

OpenClaw 还支持：

  • OpenAI — 需要 API Key
  • Anthropic — 直接使用 Claude API
  • Ollama — 本地模型
  • OpenRouter — 模型聚合平台

详见官方文档：https://docs.openclaw.ai/providers

四、接入钉钉机器人

1. 创建钉钉应用

  1. 打开钉钉开放平台：https://open.dingtalk.com
  2. 进入「应用开发」→「企业内部开发」→「创建应用」
  3. 填写应用名称和描述
  4. 进入应用详情，获取：
    • Client ID（AppKey）
    • Client Secret（AppSecret）

2. 配置应用权限

在应用的「权限管理」中，申请以下权限：

  • qyapi_chat_manage — 群会话管理
  • qyapi_robot_sendmsg — 机器人发送消息
  • contact_user_mobile_read — 读取用户手机号（可选）

3. 配置消息接收地址

在「开发配置」→「事件与回调」中：

  • 消息接收模式： HTTP
  • 消息接收地址：https://你的域名/webhook/dingtalk
⚠️ 钉钉要求 HTTPS，本地开发可以用 ngrok 或 Cloudflare Tunnel

4. 安装钉钉插件

openclaw plugins install clawdbot-dingtalk openclaw plugins enable clawdbot-dingtalk

5. 配置 OpenClaw

编辑配置文件 ~/.openclaw/openclaw.json：

{"channels":{"dingtalk":{"enabled":true,"clientId":"你的Client ID","clientSecret":"你的Client Secret","dmPolicy":"pairing"}},"plugins":{"entries":{"clawdbot-dingtalk":{"enabled":true}}}}

或者使用命令行配置：

openclaw config set channels.dingtalk.enabled true openclaw config set channels.dingtalk.clientId "你的Client ID" openclaw config set channels.dingtalk.clientSecret "你的Client Secret"

6. 重启服务

openclaw gateway restart

7. 测试连接

在钉钉中 @机器人 或私聊机器人，发送消息测试。

五、钉钉插件常见问题与解决方案

问题 1：消息发送失败，提示 “Unknown target”

原因： 钉钉 API 需要 userId 或 conversationId，而不是用户名。

解决方案：

  1. 先让用户给机器人发一条消息
  2. 从消息中获取 userId
  3. 使用 userId 发送消息

代码层面的修复：

// 错误：使用用户名 message.send({to:"maple",message:"hello"})// 正确：使用 userId 或 conversationId message.send({to:"user123456",message:"hello"})

问题 2：Webhook 签名验证失败

原因： 钉钉的签名验证机制要求时间戳在有效范围内。

解决方案：

  1. 确保服务器时间准确：sudo ntpdate pool.ntp.org
  2. 检查 Client Secret 是否正确
  3. 确认使用 HTTPS

问题 3：消息接收延迟或丢失

原因：

  • 服务器响应超时
  • 网络不稳定
  • Gateway 未正常运行

解决方案：

# 检查服务状态 openclaw status openclaw health # 查看日志 openclaw logs -f # 重启服务 openclaw gateway restart

问题 4：无法接收群消息

原因： 未将机器人添加到群聊。

解决方案：

  1. 在钉钉群设置中添加「自定义机器人」
  2. 选择你创建的应用
  3. 确认机器人出现在群成员列表中

问题 5：Rate Limit 错误

原因： 钉钉 API 调用频率限制。

解决方案：

  • 企业内部应用：20次/秒
  • 减少不必要的 API 调用
  • 使用消息合并发送

调试技巧

查看详细日志：

openclaw logs -f --level debug

测试 Webhook 连通性：

curl -X POST https://你的域名/webhook/dingtalk \ -H "Content-Type: application/json"\ -d '{"test": true}'

检查插件状态：

openclaw plugins list

六、日常使用技巧

1. 常用命令

# 查看状态 openclaw status # 打开 Web 控制台 openclaw dashboard # 查看日志 openclaw logs -f # 重启服务 openclaw gateway restart # 切换模型 openclaw models set github-copilot/gpt-4o # 查看当前模型 openclaw models current

2. 聊天中的斜杠命令

在聊天中可以使用：

  • /status — 查看会话状态
  • /model <模型名> — 切换模型
  • /clear — 清空对话历史
  • /help — 查看帮助

3. 设置提醒

在聊天中直接说：

“20分钟后提醒我开会”
“每天早上9点提醒我查看邮件”

OpenClaw 会自动创建 cron 任务。

4. 文件操作

在聊天中可以让 AI 帮你：

  • 读取/写入文件
  • 执行 Shell 命令
  • 搜索文件内容
  • 操作数据库

5. 多模型切换

# 创建模型别名 openclaw config set agents.defaults.models.qwen-portal/coder-model.alias "qwen"# 聊天中切换 /model qwen /model github-copilot/claude-opus-4.5

七、搭建本地模型（llama.cpp）

如果你想在本地运行模型（无需 API），可以使用 llama.cpp。

1. 安装编译工具

sudoapt update sudoaptinstall -y cmake build-essential

2. 编译 llama.cpp

mkdir -p ~/llama.cpp cd ~/llama.cpp git clone --depth 1 https://github.com/ggerganov/llama.cpp.git src cd src &&mkdir build &&cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc) llama-cli llama-server

3. 下载模型

mkdir -p ~/llama.cpp/models # Qwen2.5-3B（适合 4GB 显存）curl -L -o ~/llama.cpp/models/qwen2.5-3b.gguf \"https://hf-mirror.com/Qwen/Qwen2.5-3B-Instruct-GGUF/resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf"# Qwen2.5-7B（适合 8GB 显存）curl -L -o ~/llama.cpp/models/qwen2.5-7b.gguf \"https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf"

4. 启动本地 API 服务

cd ~/llama.cpp/src/build/bin ./llama-server \ -m ~/llama.cpp/models/qwen2.5-3b.gguf \ --host 0.0.0.0 \ --port 8080\ -c 4096

服务启动后：

  • Web 界面：http://localhost:8080
  • API 端点：http://localhost:8080/v1/chat/completions

5. 在 OpenClaw 中配置本地模型

编辑 ~/.openclaw/openclaw.json，添加自定义 provider：

{"models":{"providers":{"local-llama":{"baseUrl":"http://localhost:8080/v1","apiKey":"not-needed","api":"openai-completions","models":[{"id":"qwen2.5-3b","name":"Qwen 2.5 3B Local","contextWindow":4096,"maxTokens":2048}]}}}}

切换到本地模型：

openclaw models set local-llama/qwen2.5-3b

6. 本地模型 vs 云端模型

对比项本地模型云端模型
成本一次性硬件投入按量付费
隐私数据不出本地需信任提供商
速度取决于硬件通常更快
能力受限于模型大小可用最强模型
可用性需要本地运行7x24 小时

建议：

  • 敏感数据 → 本地模型
  • 复杂任务 → 云端大模型
  • 日常聊天 → 本地 7B 足够

八、总结与资源

快速回顾

  1. 安装 OpenClaw：curl -fsSL https://openclaw.ai/install.sh | bash
  2. 配置模型：openclaw models auth login-github-copilot
  3. 接入钉钉： 安装 clawdbot-dingtalk 插件 + 配置 credentials
  4. 本地模型： llama.cpp + GGUF 模型

常用链接

资源地址
OpenClaw GitHubhttps://github.com/openclaw/openclaw
官方文档https://docs.openclaw.ai
钉钉开放平台https://open.dingtalk.com
llama.cpphttps://github.com/ggerganov/llama.cpp
模型下载（镜像）https://hf-mirror.com
社区 Discordhttps://discord.com/invite/clawd

进阶学习

  • 自定义 Agent 行为：编辑 ~/.openclaw/workspace/SOUL.md
  • 开发自定义插件：参考 /docs/plugins/manifest.md
  • 多 Agent 协作：参考 /docs/multi-agent-sandbox-tools.md

文章整理于 2026-02-03
基于 OpenClaw 2026.2.1 版本
如有问题欢迎交流！

Read more

将现有 REST API 转换为 MCP Server工具 -higress

将现有 REST API 转换为 MCP Server工具 -higress

Higress 是一款云原生 API 网关，集成了流量网关、微服务网关、安全网关和 AI 网关的功能。 它基于 Istio 和 Envoy 开发，支持使用 Go/Rust/JS 等语言编写 Wasm 插件。 提供了数十个通用插件和开箱即用的控制台。 Higress AI 网关支持多种 AI 服务提供商，如 OpenAI、DeepSeek、通义千问等，并具备令牌限流、消费者鉴权、WAF 防护、语义缓存等功能。 MCP Server 插件配置 higress 功能说明 * mcp-server 插件基于 Model Context Protocol (MCP)，专为 AI 助手设计，

By Ne0inhk
MCP 工具速成：npx vs. uvx 全流程安装指南

MCP 工具速成：npx vs. uvx 全流程安装指南

在现代 AI 开发中，Model Context Protocol（MCP）允许通过外部进程扩展模型能力，而 npx（Node.js 生态）和 uvx（Python 生态）则是两种即装即用的客户端工具，帮助你快速下载并运行 MCP 服务器或工具包，无需全局安装。本文将从原理和对比入手，提供面向 Windows、macOS、Linux 的详细安装、验证及使用示例，确保你能在本地或 CI/CD 流程中无缝集成 MCP 服务器。 1. 工具简介 1.1 npx（Node.js/npm） npx 是 npm CLI（≥v5.2.0）

By Ne0inhk
解锁Dify与MySQL的深度融合：MCP魔法开启数据新旅程

解锁Dify与MySQL的深度融合：MCP魔法开启数据新旅程

文章目录 * 解锁Dify与MySQL的深度融合：MCP魔法开启数据新旅程 * 引言：技术融合的奇妙开篇 * 认识主角：Dify、MCP 与 MySQL * （一）Dify：大语言模型应用开发利器 * （二）MCP：连接的桥梁 * （三）MySQL：经典数据库 * 准备工作：搭建融合舞台 * （一）环境搭建 * （二）安装与配置 Dify * （三）安装与配置 MySQL * 关键步骤：Dify 与 MySQL 的牵手过程 * （一）安装必要插件 * （二）配置 MCP SSE * （三）创建 Dify 工作流 * （四）配置 Agent 策略 * （五）搭建MCP

By Ne0inhk
如何在Cursor中使用MCP服务

如何在Cursor中使用MCP服务

前言 随着AI编程助手的普及，越来越多开发者选择在Cursor等智能IDE中进行高效开发。Cursor不仅支持代码补全、智能搜索，还能通过MCP（Multi-Cloud Platform）服务，轻松调用如高德地图API、数据库等多种外部服务，实现数据采集、处理和自动化办公。 本文以“北京一日游自动化攻略”为例，详细讲解如何在 Cursor 中使用 MCP 服务，完成数据采集、数据库操作、文件生成和前端页面展示的全流程。 学习视频：cursor中使用MCP服务 一、什么是MCP服务？ MCP（Multi-Cloud Platform）是Cursor内置的多云服务接口，支持调用地图、数据库、文件系统等多种API。通过MCP，开发者无需手动写HTTP请求或繁琐配置，只需在对话中描述需求，AI助手即可自动调用相关服务，极大提升开发效率。 二、环境准备 2.1 cursor Cursor重置机器码-解决Too many free trials. 2.

By Ne0inhk