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

逗松

1430人浏览 · 2026-03-10 10:40:33

逗松 · 2026-03-10 10:40:33 发布

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

一、什么是 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 -
sudo apt install -y nodejs

macOS：

brew install node@22

## 验证安装：
node -v  # 应显示 v22.x.x
npm -v

3. 安装 OpenClaw

推荐方式（一键安装）：

Linux / macOS ：

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

Windows PowerShell：

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

手动安装：

npm install -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

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

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

设置默认模型：

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 次请求：

启用插件：

openclaw plugins enable qwen-portal-auth
openclaw gateway restart

登录认证：

 openclaw models auth login --provider qwen-portal --set-default #按提示在浏览器中完成登录。

设置默认模型：

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

四、接入钉钉机器人

创建钉钉应用打开钉钉开放平台：https://open.dingtalk.com进入「应用开发」→「企业内部开发」→「创建应用」填写应用名称和描述进入应用详情，获取：
1. Client ID（AppKey）
2. Client Secret（AppSecret）
配置应用权限在应用的「权限管理」中，申请以下权限：
1. qyapi_chat_manage — 群会话管理
2. qyapi_robot_sendmsg — 机器人发送消息
3. contact_user_mobile_read — 读取用户手机号（可选）
配置消息接收地址在「开发配置」→「事件与回调」中：⚠️ 钉钉要求 HTTPS，本地开发可以用 ngrok 或 Cloudflare Tunnel
1. 消息接收模式： HTTP
2. 消息接收地址： https://你的域名/webhook/dingtalk

安装钉钉插件

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

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

#编辑配置文件 ~/.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"

重启服务
```
 openclaw gateway restart
```
测试连接在钉钉中 @机器人或私聊机器人，发送消息测试。

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

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

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

解决方案：

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

代码层面的修复：

// 错误：使用用户名
message.send({ to: "maple", message: "hello" })

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

问题 2：Webhook 签名验证失败

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

解决方案：

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

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

原因：

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

解决方案：

# 检查服务状态
openclaw status
openclaw health

# 查看日志
openclaw logs -f

# 重启服务
openclaw gateway restart

问题 4：无法接收群消息

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

解决方案：

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

问题 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。

安装编译工具

sudo apt update
sudo apt install -y cmake build-essential

编译 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

下载模型

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"

启动本地 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

在 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 足够

八、总结与资源

快速回顾

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

常用链接

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

进阶学习

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

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

Codex详细入门指南

龙虾开发者社区

AI Agent 入门与实战：从对话到干活，理解下一代AI工作方式

你告诉Agent一个目标，它会自己拆解成步骤，调用工具（文件操作、命令行、API接口），逐步执行，遇到问题会自己尝试修复，最后给你交付结果。第一，Agent写的代码不是100%可靠的。对于一个已经在写代码的开发者来说，现在最重要的事情不是"学什么新语言或新框架"，而是学会怎么让Agent帮你干活、提高你不可替代的那部分能力——业务理解、架构设计、技术判断。用Agent的做法是：你告诉它需求，它自己