前置准备与安全红线
1. 基础硬件 & 系统要求
| 系统类型 | 最低要求 | 推荐配置 |
|---|---|---|
| Windows | Windows 10 64 位 | Windows 11 64 位，优先使用 WSL2 |
| macOS | macOS 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
- 官网下载：Node.js 官方网站，选择LTS 长期支持版本（自动附带 npm 包管理器）
- 安装全程默认下一步，自动配置系统环境变量
- 验证安装：打开终端 / PowerShell，执行以下命令，输出版本号≥v22 即为成功
node --version
npm --version
步骤 2：Windows 用户必装 Git
- 官网下载：Git 官方网站
- 安装全程默认下一步，安装程序会自动配置环境变量
- 验证安装：PowerShell 执行以下命令，输出版本号即为成功
git --version
步骤 3：配置国内 npm 镜像（关键避坑）
国内用户直接访问官方 npm 源极易超时失败，先执行以下命令切换淘宝镜像：
# 切换国内镜像源
npm config set registry https://registry.npmmirror.com
# 清理缓存，避免旧数据干扰
npm cache clean --force
# 验证镜像是否切换成功
npm config get registry
全平台安装教程（官方推荐方案）
方案一：一键脚本安装（新手首选，自动处理所有依赖）
🔹 Windows 系统安装
- 必须右键开始菜单，选择「Windows PowerShell (管理员)」，非管理员权限会导致安装失败
- 复制以下命令到 PowerShell 中回车执行，脚本会自动安装所有依赖和 OpenClaw 本体
irm -useb https://openclaw.ai/install.ps1 | iex
- 等待安装完成，出现「OpenClaw installed successfully!」即为成功
🔹 macOS/Linux/WSL2 系统安装
- 打开终端，复制以下命令回车执行
curl -fsSL https://openclaw.ai/install.sh | bash
- 等待脚本自动完成安装，出现成功提示即可
方案二：手动安装（脚本失败备用方案）
如果一键脚本执行失败，可通过 pnpm 手动安装，稳定性更高：
- 先全局安装 pnpm 包管理器
npm install -g pnpm
- 安装 OpenClaw 最新稳定版
pnpm add -g openclaw@latest
# 批准构建脚本（可选，不影响基础功能使用）
pnpm approve-builds -g
- 验证安装是否成功
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 机器人
- 访问 QQ 开放平台 OpenClaw 专属快捷通道（QQ 扫码即可进入）
- 扫码登录后，点击「创建机器人」，秒级完成创建，无需审核
- 创建完成后，手机 QQ 会收到机器人的打招呼消息，可自行修改机器人头像、昵称
步骤 2：OpenClaw 端配置接入
- 开放平台页面会自动生成 3 条专属配置命令（包含你的 AppID 和 AppSecret）
- 复制命令，依次粘贴到终端 / 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：验证接入成功
- 打开 OpenClaw 网页控制台，进入「频道」页面，可见 QQ 机器人状态为「已连接」
- 打开手机 QQ，给机器人发送消息（如「写一篇 Python 入门教程」「查看我的电脑配置」），机器人会快速响应
- 支持 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
解决方案：
- 先执行
openclaw gateway status查看网关是否正常运行 - 若网关未运行，执行
openclaw gateway手动启动 - 若提示端口被占用，更换端口启动：
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 机器人发送消息无响应
排查步骤：
- 检查 AppID 和 AppSecret 是否填写正确，有无多余空格
- 执行
openclaw channel status --probe查看 QQ 频道是否正常连接 - 确认电脑防火墙已放行 18789 端口，无杀毒软件拦截
- 执行
openclaw gateway restart重启网关，重新加载配置
