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

OpenClaw 本地 AI 智能体安装与使用指南：QQ 机器人接入、运维及故障排查

介绍开源 AI 智能体 OpenClaw 的完整部署流程。涵盖系统环境准备（Node.js、Git）、一键脚本或手动安装方法、初始化配置及网页控制台启动。详细说明了如何接入 QQ 机器人实现远程调用，包括服务开机自启、状态查看与停止操作。此外提供常用技能包推荐列表，以及彻底卸载步骤。最后汇总了脚本执行策略、命令未找到、端口占用等常见报错的解决方案，帮助用户快速上手并稳定运行本地 AI 服务。

菩提发布于 2026/4/6更新于 2026/10/26137 浏览
OpenClaw 本地 AI 智能体安装与使用指南：QQ 机器人接入、运维及故障排查

引言

OpenClaw 是一款本地 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 步即可搞定，让你在 QQ 里随时随地调用 OpenClaw。

步骤 1：创建 QQ 机器人
  1. 访问 QQ 开放平台创建机器人
  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 格式输出，代码、表格均可完美渲染，阅读体验拉满

日常运维核心指南（解决你 90% 的使用问题）

这部分专门解决大家高频提问的「每次怎么启动」「怎么关闭」「要不要一直开电脑」等核心问题。

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 重启网关，重新加载配置

总结与进阶玩法

OpenClaw 作为目前最火的开源 AI 智能体，上限极高：

  • 新手可以用它实现自动化办公、文件处理、QQ 私人助手，大幅提升效率
  • 技术爱好者可以深度自定义，开发专属技能、搭建多 Agent 协作系统、接入本地化大模型、对接微信 / 飞书 / 钉钉等更多平台
  • 本文覆盖了 OpenClaw 从安装到运维的全流程，解决了 90% 的新手踩坑问题，后续可更新更多进阶教程，比如自定义技能开发、多 Agent 协作、云服务器部署等内容。

目录

  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. 日常运维核心指南（解决你 90% 的使用问题）
  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 机器人发送消息无响应
  74. 总结与进阶玩法

更多推荐文章

查看全部
  • Rust 异步并发安全与内存管理实战指南
  • Spring Web MVC 核心概念与实战指南
  • 66 个机器人开源项目合集：科研、教育、工业与医疗资源整理
  • Stable Diffusion XL 1.0 部署与 Noto Serif SC 中文字体渲染教程
  • 从零开始：如何使用 Python 训练 AI 模型
  • C++ 模板编程基础：泛型编程入门与实践
  • NPlayer 开源视频播放器使用指南
  • Python 异步编程：深入理解 asyncio 核心原理与实战
  • SQLAlchemy 核心用法与实战案例解析
  • Qt 与 Python 混合架构：嵌入、交互与工程化实践
  • DeepSeek 各版本演进与核心能力对比
  • Flutter 三方库 llm_json_stream 的鸿蒙化适配指南
  • AI 大模型学习路径与行业转型指南
  • Ant 构建报错“非法字符：\65279”的解决方案
  • LLM 技术图谱解析：从基础设施到应用的全景指南
  • Open WebUI Docker 部署：容器化最佳实践
  • 基于大模型的自然语言数据库查询与数据分析
  • C++ unordered_map 与 unordered_set 的实现思路
  • 腾讯位置服务AI+地图征文：实战选题与高分写法
  • 基于大疆 MSDK 的无人机视觉引导自适应降落实现

相关免费在线工具

  • RSA密钥对生成器

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

  • Mermaid 预览与可视化编辑

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

  • 随机西班牙地址生成器

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

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown转HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online