跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.jsAI

OpenClaw 智能体安装部署与 QQ 机器人接入指南

OpenClaw 是一款基于 Node.js 运行的本地 AI 智能体工具，支持文件读写、浏览器操控及 QQ 机器人接入。涵盖系统环境要求、Node.js 与 Git 安装、脚本与手动安装方法、初始化配置、QQ 频道对接、开机自启设置、常用运维命令、技能包扩展、卸载流程及常见报错解决方案。内容旨在提供标准化的部署指南，帮助用户安全高效地管理本地 AI 代理。

PentesterX发布于 2026/4/10更新于 2026/5/2214 浏览
OpenClaw 智能体安装部署与 QQ 机器人接入指南

简介

OpenClaw 是一款基于 Node.js 运行的本地 AI 智能体工具，支持文件读写、浏览器操控及自动化办公。本文整合官方文档与常见问题解决方案，涵盖从环境准备、安装配置、QQ 机器人接入到日常运维及卸载的全流程。

前置准备与安全要求

1. 基础硬件与系统要求

系统类型最低要求推荐配置
WindowsWindows 10 64 位Windows 11 64 位，优先使用 WSL2
macOSmacOS 12+macOS 14+，M 系列芯片
Linux内核 4.15+，1 核 1G 内存Ubuntu 22.04 LTS，2 核 2G 内存

额外要求：稳定的网络环境，用于下载依赖包和模型调用。

2. 核心安全提示

🚨 OpenClaw 拥有本地文件读写、系统命令执行等高权限，切勿安装来源不明的第三方技能包，避免恶意代码风险。 AppID、AppSecret、API Key 等敏感信息切勿泄露、切勿上传到公开代码仓库。 新手优先在虚拟机、云服务器或备用机上测试，避免误操作影响主力机数据。 国内用户务必先配置 npm 国内镜像，90% 的安装失败都源于网络超时。

3. 前置环境安装

OpenClaw 基于 Node.js 运行，必须满足 Node 版本≥v22，Windows 用户还需安装 Git。

步骤 1：安装 Node.js
  1. 官网下载：Node.js 官方网站，选择 LTS 长期支持版本（自动附带 npm 包管理器）
  2. 安装全程默认下一步，自动配置系统环境变量
  3. 验证安装：打开终端 / PowerShell，执行以下命令，输出版本号≥v22 即为成功
node --version
npm --version
步骤 2：Windows 用户必装 Git
  1. 官网下载：Git 官方网站
  2. 安装全程默认下一步，安装程序会自动配置环境变量
  3. 验证安装：PowerShell 执行以下命令，输出版本号即为成功
git --version
步骤 3：配置国内 npm 镜像

国内用户直接访问官方 npm 源极易超时失败，先执行以下命令切换淘宝镜像：

# 切换国内镜像源
npm config set registry https://registry.npmmirror.com
# 清理缓存，避免旧数据干扰
npm cache clean --force
# 验证镜像是否切换成功
npm config get registry

全平台安装教程

方案一：一键脚本安装（新手首选）

Windows 系统安装
  1. 必须右键开始菜单，选择「Windows PowerShell (管理员)」，非管理员权限会导致安装失败
  2. 复制以下命令到 PowerShell 中回车执行，脚本会自动安装所有依赖和 OpenClaw 本体
irm -useb https://openclaw.ai/install.ps1 | iex
  1. 等待安装完成，出现「OpenClaw installed successfully!」即为成功
macOS/Linux/WSL2 系统安装
  1. 打开终端，复制以下命令回车执行
curl -fsSL https://openclaw.ai/install.sh | bash
  1. 等待脚本自动完成安装，出现成功提示即可

方案二：手动安装（脚本失败备用方案）

如果一键脚本执行失败，可通过 pnpm 手动安装，稳定性更高：

  1. 先全局安装 pnpm 包管理器
npm install -g pnpm
  1. 安装 OpenClaw 最新稳定版
pnpm add -g openclaw@latest
# 批准构建脚本（可选，不影响基础功能使用）
pnpm approve-builds -g
  1. 验证安装是否成功
openclaw --version

终端输出版本号（如 2026.3.28），即为安装成功。

初始化配置

安装完成后，必须完成官方引导配置，才能正常使用 OpenClaw。

1. 启动官方引导程序

终端 / PowerShell 执行以下命令，启动引导向导：

openclaw onboard --install-daemon

关键参数说明：--install-daemon 会自动安装后台网关服务，实现开机自启，不用每次手动输命令启动。

2. 引导配置分步指南

配置步骤推荐选项说明
用户协议选 Yes必须同意才能继续使用
安装模式快速开始新手无需自定义，快速模式自动配置最优参数
大模型选择千问通义千问国内用户首选，免费 OSS 授权，无需额外申请 API Key，无网络限流问题
聊天渠道暂时跳过后续单独配置 QQ 机器人，更稳定
搜索服务暂时跳过需额外申请 API Key，新手后续按需配置
技能市场开启 ClawHub官方技能商店，后续可扩展功能
防火墙提示全部允许必须允许公共 + 专用网络访问，否则网关无法正常通信

3. 启动网页控制台

引导完成后，会自动打开 OpenClaw 网页控制台，若未自动打开，执行以下命令手动启动：

openclaw dashboard

控制台默认地址：http://127.0.0.1:18789/，浏览器打开即可看到可视化操作界面。

QQ 机器人接入

腾讯为 OpenClaw 提供了专属快捷接入通道，无需申请白名单，3 步即可搞定。

步骤 1：创建 QQ 机器人

  1. 访问 QQ 开放平台 OpenClaw 专属快捷通道
  2. 扫码登录后，点击「创建机器人」，秒级完成创建，无需审核
  3. 创建完成后，手机 QQ 会收到机器人的打招呼消息，可自行修改机器人头像、昵称

步骤 2：OpenClaw 端配置接入

  1. 开放平台页面会自动生成 3 条专属配置命令（包含你的 AppID 和 AppSecret）
  2. 复制命令，依次粘贴到终端 / PowerShell 中执行：
# 示例命令，请勿直接复制，以平台生成的专属命令为准
# 1. 添加 QQ 频道配置
openclaw channel add qq --app-id "你的专属 AppID" --app-secret "你的专属 AppSecret"
# 2. 启用 QQ 频道
openclaw channel enable qq
# 3. 重启网关生效配置
openclaw gateway restart

🚨 重要提醒：AppID 和 AppSecret 是你的机器人专属密钥，切勿泄露给他人！

步骤 3：验证接入成功

  1. 打开 OpenClaw 网页控制台，进入「频道」页面，可见 QQ 机器人状态为「已连接」
  2. 打开手机 QQ，给机器人发送消息（如「写一篇 Python 入门教程」「查看我的电脑配置」），机器人会快速响应
  3. 支持 Markdown 格式输出，代码、表格均可完美渲染

日常运维指南

1. 开机自启配置

如果初始化时没有加 --install-daemon 参数，执行以下命令安装后台服务，实现开机自动启动：

# 1. 安装网关系统服务（管理员权限执行）
openclaw gateway install
# 2. 启用开机自启
openclaw gateway enable
# 3. 手动启动一次服务
schtasks /Run /TN "OpenClaw Gateway"

配置完成后，电脑开机 OpenClaw 会自动在后台运行，直接打开网页控制台 / QQ 机器人即可使用，无需输任何命令。

2. 手动启动方法

如果不想开机自启，每次使用时执行以下命令即可启动网关：

# 前台启动（终端窗口不能关闭，关了网关就停）
openclaw gateway

3. 关闭 / 停止 OpenClaw

场景 1：临时停止后台服务
# Windows 停止计划任务
schtasks /End /TN "OpenClaw Gateway"
# macOS/Linux 停止服务
openclaw gateway stop
场景 2：前台运行的网关

直接在运行的终端窗口按下 Ctrl + C 组合键，即可优雅停止；或直接关闭终端窗口。

场景 3：禁用开机自启（保留服务）
schtasks /Change /TN "OpenClaw Gateway" /DISABLE
场景 4：彻底卸载后台服务
openclaw gateway uninstall

4. 状态查看 & 故障排查

执行以下命令，即可查看网关运行状态，快速定位问题：

# 查看 OpenClaw 全局状态
openclaw status
# 查看网关详细运行状态
openclaw gateway status
# 实时查看运行日志，排查报错
openclaw logs --follow

5. 核心问题解答

问：在 QQ 里用 OpenClaw，是不是必须一直开着安装的电脑？ 答：是的。OpenClaw 的核心网关服务运行在你的电脑上，电脑关机、睡眠、断网，网关就会停止，QQ 机器人就无法响应。解决方案：可以把 OpenClaw 安装在 24 小时运行的云服务器 / 迷你主机上，就能实现随时随地不间断使用。

技能包扩展

通过官方 ClawHub 技能市场，可以扩展 OpenClaw 的功能，安装命令统一格式：npx clawhub@latest install 技能名

技能包名称核心功能适用场景
skill-vetter扫描第三方技能包恶意代码，安全校验安装任何第三方技能前必装，保障安全
tavily-search联网搜索能力，获取全网最新数据查资讯、找资料、实时信息获取
automation-workflows多技能流程编排，实现复杂自动化任务办公自动化、定时任务、多步骤工作流
github对接 GitHub 仓库，管理代码、PR、Issue程序员开发、开源项目维护
self-improving-agent记忆用户使用习惯，自优化响应逻辑长期使用，越用越贴合你的需求
email-tools邮件收发、自动回复、邮件摘要职场邮件处理、自动提醒

实用技巧：执行 npx clawhub@latest search 关键词，即可搜索更多相关技能包。

卸载教程

Windows 系统彻底卸载

# 1. 停止网关服务
openclaw gateway stop
# 2. 卸载网关系统服务
openclaw gateway uninstall
# 3. 全局卸载 OpenClaw
pnpm remove -g openclaw
# 4. 删除配置文件、缓存和数据
rm -rf $env:USERPROFILE\.openclaw
rm -rf $env:APPDATA\npm\node_modules\openclaw

macOS/Linux 系统彻底卸载

# 1. 停止网关服务
openclaw gateway stop
# 2. 卸载网关系统服务
openclaw gateway uninstall
# 3. 全局卸载 OpenClaw
pnpm remove -g openclaw
# 4. 删除配置文件、缓存和数据
rm -rf ~/.openclaw
rm -rf ~/.pnpm-store/*/openclaw

常见报错与解决方案

1. 执行安装脚本提示「无法加载.ps1 文件，因为在此系统上禁止运行脚本」

解决方案：管理员 PowerShell 执行以下命令，修改执行策略，输入 Y 确认即可：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2. 执行命令提示「openclaw: command not found」

原因：npm 全局路径未添加到系统环境变量

解决方案：

# 1. 查看 npm 全局安装路径
npm config get prefix
# 2. 将输出的路径添加到系统环境变量的 PATH 中
# 3. 关闭终端，重新打开即可生效

3. 启动网关提示「Gateway service missing」

原因：未安装网关系统服务

解决方案：管理员权限执行以下命令，安装并启动服务：

openclaw gateway install
schtasks /Run /TN "OpenClaw Gateway"

4. 网页控制台打不开，提示「URL 拼写错误」/ 网关 unreachable

解决方案：

  1. 先执行 openclaw gateway status 查看网关是否正常运行
  2. 若网关未运行，执行 openclaw gateway 手动启动
  3. 若提示端口被占用，更换端口启动：openclaw gateway --port 18790，然后访问 http://127.0.0.1:18790/

5. 网关启动提示「端口 18789 被占用」

解决方案：

# Windows 查看占用端口的进程 PID
netstat -ano | findstr :18789
# macOS/Linux 查看占用端口的进程 PID
lsof -i :18789
# 结束占用进程（替换为实际的 PID）
taskkill /PID 进程 PID /F # Windows
kill -9 进程 PID # macOS/Linux

6. QQ 机器人发送消息无响应

排查步骤：

  1. 检查 AppID 和 AppSecret 是否填写正确，有无多余空格
  2. 执行 openclaw channel status --probe 查看 QQ 频道是否正常连接
  3. 确认电脑防火墙已放行 18789 端口，无杀毒软件拦截
  4. 执行 openclaw gateway restart 重启网关，重新加载配置

目录

  1. 简介
  2. 前置准备与安全要求
  3. 1. 基础硬件与系统要求
  4. 2. 核心安全提示
  5. 3. 前置环境安装
  6. 步骤 1：安装 Node.js
  7. 步骤 2：Windows 用户必装 Git
  8. 步骤 3：配置国内 npm 镜像
  9. 切换国内镜像源
  10. 清理缓存，避免旧数据干扰
  11. 验证镜像是否切换成功
  12. 全平台安装教程
  13. 方案一：一键脚本安装（新手首选）
  14. Windows 系统安装
  15. macOS/Linux/WSL2 系统安装
  16. 方案二：手动安装（脚本失败备用方案）
  17. 批准构建脚本（可选，不影响基础功能使用）
  18. 初始化配置
  19. 1. 启动官方引导程序
  20. 2. 引导配置分步指南
  21. 3. 启动网页控制台
  22. QQ 机器人接入
  23. 步骤 1：创建 QQ 机器人
  24. 步骤 2：OpenClaw 端配置接入
  25. 示例命令，请勿直接复制，以平台生成的专属命令为准
  26. 1. 添加 QQ 频道配置
  27. 2. 启用 QQ 频道
  28. 3. 重启网关生效配置
  29. 步骤 3：验证接入成功
  30. 日常运维指南
  31. 1. 开机自启配置
  32. 1. 安装网关系统服务（管理员权限执行）
  33. 2. 启用开机自启
  34. 3. 手动启动一次服务
  35. 2. 手动启动方法
  36. 前台启动（终端窗口不能关闭，关了网关就停）
  37. 3. 关闭 / 停止 OpenClaw
  38. 场景 1：临时停止后台服务
  39. Windows 停止计划任务
  40. macOS/Linux 停止服务
  41. 场景 2：前台运行的网关
  42. 场景 3：禁用开机自启（保留服务）
  43. 场景 4：彻底卸载后台服务
  44. 4. 状态查看 & 故障排查
  45. 查看 OpenClaw 全局状态
  46. 查看网关详细运行状态
  47. 实时查看运行日志，排查报错
  48. 5. 核心问题解答
  49. 技能包扩展
  50. 卸载教程
  51. Windows 系统彻底卸载
  52. 1. 停止网关服务
  53. 2. 卸载网关系统服务
  54. 3. 全局卸载 OpenClaw
  55. 4. 删除配置文件、缓存和数据
  56. macOS/Linux 系统彻底卸载
  57. 1. 停止网关服务
  58. 2. 卸载网关系统服务
  59. 3. 全局卸载 OpenClaw
  60. 4. 删除配置文件、缓存和数据
  61. 常见报错与解决方案
  62. 1. 执行安装脚本提示「无法加载.ps1 文件，因为在此系统上禁止运行脚本」
  63. 2. 执行命令提示「openclaw: command not found」
  64. 1. 查看 npm 全局安装路径
  65. 2. 将输出的路径添加到系统环境变量的 PATH 中
  66. 3. 关闭终端，重新打开即可生效
  67. 3. 启动网关提示「Gateway service missing」
  68. 4. 网页控制台打不开，提示「URL 拼写错误」/ 网关 unreachable
  69. 5. 网关启动提示「端口 18789 被占用」
  70. Windows 查看占用端口的进程 PID
  71. macOS/Linux 查看占用端口的进程 PID
  72. 结束占用进程（替换为实际的 PID）
  73. 6. QQ 机器人发送消息无响应
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • 字节跳动发布豆包大模型，行业价格进入厘时代
  • 12 个 AI 免费一键生成 PPT 网站推荐
  • TSDK 淘宝开放平台及登录爬虫 SDK
  • AG-UI：构建 AI 前端交互的统一协议
  • Qwen3-VL-WEBUI 游戏 NPC 视觉交互部署实践
  • Python 合并两个字典的 8 种常用方法
  • Spring Integration Kafka XML 配置示例
  • Whisper-Large-V3-Turbo 语音识别模型一键部署指南
  • 3 个实用技术工具网站推荐：黑客模拟、威胁地图与粒子生成
  • Java 泛型详解：语法、擦除与通配符
  • AI 音乐生成技术解析：开源 YuE 与闭源 Suno.ai 对比
  • 知识图谱基础概念详解：实体、关系与属性构建指南
  • 大模型前沿：13 篇必读论文精选
  • YOLO-DRONE：无人机低空巡检模型实测与电力部署解析
  • 前端代码分割与懒加载实战指南
  • 二分查找算法原理与常见变体实战
  • 金融领域自然语言处理（NLP）应用与实战
  • Effective Modern C++ 条款 37：确保 std::thread 在所有路径上不可结合
  • 容器适配器深度解析：STL 栈、队列与优先队列底层实现
  • 前端调用后端接口实战：HTML+JS 与 Vue 集成 Go 示例

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online