OpenClaw AI 助手框架搭建与配置指南

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. 安装编译工具

sudo apt update
sudo apt install -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 云端模型

建议：

• 敏感数据 → 本地模型
• 复杂任务 → 云端大模型
• 日常聊天 → 本地 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 模型

常用链接

进阶学习

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