OpenClaw 本地部署全攻略（小白版）- 创芯观察

📑 目录导航

一、OpenClaw 是什么？二、⚡ 一键部署（最快方式）三、Windows 部署教程（WSL2 方式）四、Linux 部署教程五、打通 AI API 接口（最关键）六、Docker 部署（进阶）七、常见问题排查（必看！）八、QQ 机器人配置九、硬件要求 & 常用命令

📌 一、OpenClaw 是什么？

OpenClaw 是一款开源的个人 AI 助手框架，在你自己的电脑上运行，通过 WhatsApp、Telegram、Discord、飞书、企业微信等聊天工具与 AI 互动，实现全场景自动化。

📧自动整理邮件和日程

📄PDF/Word/Excel 文件解析

🌐浏览器自动化操作

🤖对接 Claude/GPT/DeepSeek

💾数据存本地，隐私安全

🔌丰富插件生态扩展

⚡ 二、一键部署（最快方式）

如果你不想手动安装 Node.js，OpenClaw 提供了一键安装脚本，会自动检测环境、安装依赖、完成初始化，全程无需手动干预！

macOS / Linux 一键部署

打开终端，粘贴这一行命令然后回车：

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

这个脚本会自动：检测 Node.js → 没有的话自动安装 → 安装 OpenClaw → 启动配置向导，真正的一条命令搞定！

Windows 一键部署

以管理员身份打开 PowerShell，粘贴这一行：

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

Windows 用户注意：如果提示执行策略限制，先运行 Set-ExecutionPolicy RemoteSigned 再重试。推荐使用 WSL2 方式获得更好体验（见下方教程）。

安装完成后

一键脚本执行完毕后，会自动进入配置向导。如果没有，手动执行：

openclaw onboard --install-daemon

按照向导提示：✅ 安全确认 → 🎯 Quick Start → 🔑 输入 API Key → 📱 选择消息渠道 → 🔧 安装后台服务 → 🎉 完成！

🖥️ 三、Windows 详细部署教程

Windows 用户强烈推荐通过 WSL2（Windows 子系统 Linux）运行，兼容性和稳定性更好。

1安装 WSL2

以管理员身份打开 PowerShell，运行：

wsl --install

安装完成后电脑会自动重启，重启后弹出 Ubuntu 窗口，设置用户名和密码即可。

2确认 WSL2 版本

重启后打开 PowerShell，确认版本：

wsl --list --verbose

确保 VERSION 列显示 2。

3启用 systemd（推荐）

在 Ubuntu 终端中执行：

sudo nano /etc/wsl.conf

添加以下内容后保存退出：

[boot]
systemd=true

然后在 PowerShell 中执行 wsl --shutdown，再重新打开 Ubuntu。

4安装 Node.js

在 Ubuntu 终端中执行：

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载终端配置
source ~/.bashrc

# 安装 Node.js 22（推荐版本）
nvm install 22

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

5安装 OpenClaw

# 方式一：一键安装脚本（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash

# 方式二：通过 npm 全局安装
npm install -g openclaw

6初始化配置

openclaw onboard --install-daemon

配置向导会依次引导你：

✅ 安全确认 → 🎯 选择 Quick Start → 🔑 配置 API Key → 📱 配置消息渠道 → 🔧 安装后台服务

🐧 四、Linux 部署教程

1更新系统

# Ubuntu / Debian
sudo apt update && sudo apt upgrade -y

# CentOS / RHEL
sudo yum update -y

2安装 Node.js

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

# 安装 Node.js 22
nvm install 22

# 验证
node -v && npm -v

3安装 OpenClaw

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

4初始化配置

openclaw onboard --install-daemon

按照向导完成配置即可，和 Windows 的 Step 6 一样。

🔑 五、打通 AI API 接口

这是最关键的一步！OpenClaw 本身不包含 AI 模型，需要接入外部 API 才能工作。

方案 A：直接对接官方 API

AI 提供商	模型	获取 API Key
Anthropic	Claude 3.5 / 4	console.anthropic.com
OpenAI	GPT-4o / o1	platform.openai.com
智谱 AI	GLM-4	open.bigmodel.cn
阿里云百炼	Qwen	dashscope 控制台
DeepSeek	DeepSeek-V3	platform.deepseek.com

方案 B：使用 API 代理（国内用户推荐）

直接访问海外 API 不稳定？使用国内 API 代理服务，统一管理多个模型接入，解决网络和支付问题。

配置方式一：配置向导

openclaw config

在交互界面中选择 Model Provider，输入 API Key 即可。

配置方式二：手动修改配置文件

编辑 ~/.openclaw/openclaw.json：

{
  "models": {
    "provider": "anthropic",
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-sonnet-4-20250514"
  }
}

安全提醒：建议将 API Key 设置为环境变量，而非明文写入配置文件！

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

重启服务 & 验证

# 重启服务使配置生效
openclaw gateway restart

# 打开终端界面验证
openclaw tui

在终端界面发送一条消息，看到 AI 回复就说明配置成功了！🎉

🐳 六、Docker 部署（进阶用户可选）

# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

Docker 方式更安全，天然隔离，适合在服务器上长期运行。

⚠️ 七、常见问题排查（必看！）

我们在 Windows 和 Linux 多平台实测过程中踩过的所有坑，都整理在这里了👇

🔧 安装阶段问题

问题	解决方案
`node: command not found`	执行 `source ~/.bashrc` 或重新打开终端。如果用了 nvm，确保 nvm 初始化脚本已写入 `~/.bashrc`
`openclaw: command not found`	安装路径未加入 PATH。重启终端，或手动将 OpenClaw 安装目录加入 `PATH` 环境变量
Node.js 版本过低报错	OpenClaw 要求 Node.js v22+。运行 `nvm install 22 && nvm use 22` 升级
Linux 缺少编译工具	安装 build-essential：`sudo apt install build-essential`（Ubuntu）或 `sudo yum groupinstall "Development Tools"`（CentOS）
安装脚本卡住无反应	检查网络连接。可以用 `openclaw logs --follow` 查看实时日志定位问题
`EACCES: permission denied`	权限不足。Linux/Mac 加 `sudo`，Windows 以管理员身份运行 PowerShell
技能安装卡在 "Installing skill"	通常是 Node.js 版本不匹配导致，确认使用 v22+ 后重试

🪟 Windows 专属问题

问题	解决方案
WSL2 安装失败	确保 Windows 版本 ≥ Win10 2004，在 BIOS 中开启 CPU 虚拟化（VT-x/AMD-V）
PowerShell 执行策略限制	运行 `Set-ExecutionPolicy RemoteSigned` 后重试安装脚本
install.sh 在 Windows 无法执行	Windows 不能直接用 bash 脚本！用 PowerShell 专用命令：`iwr -useb https://openclaw.ai/install.ps1 \| iex`
`spawn EINVAL` 错误	Windows 原生环境已知问题，建议切换到 WSL2 环境下运行 OpenClaw
`systemctl is-enabled unavailable`	WSL 中需启用 systemd，编辑 `/etc/wsl.conf` 添加 `[boot] systemd=true`，然后 `wsl --shutdown` 重启

🔑 API 和网络问题

问题	解决方案
API 连接超时 / 无响应	① 检查网络 ② 切换到国内 API 代理 ③ 确认 API Key 未过期
`No API key found for provider`	重新运行 `openclaw onboard` 或 `openclaw config` 配置向导
`Authentication failed / Invalid API key`	API Key 错误或过期。登录对应平台重新生成 Key，注意复制时不要有多余空格
Telegram/WhatsApp 机器人不回复	Telegram：检查是否开启了 Privacy Mode（到 BotFather 关闭）。WhatsApp：清除旧会话 credentials 重新配对

⚙️ 配置和运行问题

问题	解决方案
配置文件不存在	先运行一次 `openclaw`，系统会在 `~/.openclaw/` 自动创建配置文件
Gateway 启动失败	运行 `openclaw doctor --fix` 自动修复，或手动设置 `openclaw config set gateway.mode local`
端口 18789 被占用	查找占用进程：`lsof -i :18789`（Linux/Mac）或 `netstat -ano \| findstr 18789`（Windows），kill 掉后重试
升级后功能异常	新版本可能有配置变更。升级后立即运行 `openclaw doctor` 检查兼容性
插件导致崩溃	暂时禁用所有非核心插件，逐个重新启用来定位问题插件
Docker 构建内存不足（OOM）	在 1GB 内存 VPS 上需先创建 2GB 交换分区：`sudo fallocate -l 2G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile`

🛡️ 安全注意事项

OpenClaw 已曝出 "ClawJacked" 等安全漏洞，务必保持更新到最新版本！运行 openclaw update 立即升级。

建议	说明
不要以 root 运行	创建专用非 root 用户运行 OpenClaw，限制权限范围
API Key 不要明文存储	使用环境变量存储 Key，定期轮换（建议每 90 天）
谨慎安装第三方 Skills	ClawHub 上已出现过恶意 Skill，安装前仔细审查来源和代码
开启防火墙	默认拒绝所有入站，仅开放必要端口（SSH / 18789）
使用 Docker 隔离	在服务器部署建议用 Docker，天然沙箱隔离更安全

🔍 万能排查三板斧

openclaw status --all全面诊断报告（OS、Gateway、Provider 状态一览）

openclaw doctor --fix自动检测并修复常见配置问题

openclaw logs --follow实时查看日志输出，定位具体错误

🤖 八、QQ 机器人配置

8.1 申请 QQ 机器人

访问 QQ 开放平台，使用 QQ 号登录。

进入「机器人」→「创建机器人」，填写基本信息：

字段	说明
机器人名称	自定义名称，如"我的AI助手"
机器人简介	简短描述机器人功能
沙箱频道	用于测试，选择一个已有频道或创建新频道

创建成功后，在「开发设置」页面获取以下关键信息：

BotAppID:   你的 AppID（数字）
Token:      你的 Token
AppSecret:  你的 Secret

⚠️ 请妥善保管 Token 和 AppSecret，不要泄露给他人！

8.2 配置 OpenClaw 连接 QQ 机器人

编辑 OpenClaw 配置文件 ~/.openclaw/openclaw.json，添加 QQ 机器人适配器：

{
  "adapters": {
    "qq": {
      "enabled": true,
      "type": "qqbot",
      "appid": "你的BotAppID",
      "token": "你的Token",
      "secret": "你的AppSecret",
      "sandbox": true,
      "intents": ["GROUP_AT_MESSAGE_CREATE", "C2C_MESSAGE_CREATE"]
    }
  }
}

配置字段说明：

字段	说明
`enabled`	是否启用，设为 `true`
`appid`	QQ 开放平台获取的 BotAppID
`token`	QQ 开放平台获取的 Token
`secret`	QQ 开放平台获取的 AppSecret
`sandbox`	沙箱模式，测试时设 `true`，正式上线改 `false`
`intents`	监听的事件类型：群@消息和私聊消息

重启 OpenClaw 使配置生效：

openclaw gateway restart

8.3 测试验证

在沙箱频道中 @你的机器人 发送一条消息，如：

@我的AI助手 你好，请介绍一下你自己

如果机器人正常回复 → 配置成功 ✅

查看实时日志排查问题：

openclaw logs --follow --filter adapter:qq

常见问题

问题	解决方案
机器人不回复消息	检查 `sandbox` 是否为 `true`，确认在沙箱频道测试；检查 AppID/Token 是否正确
连接超时 / 鉴权失败	确认 AppSecret 正确无误，重新生成 Token 再试
群消息无响应	确认 `intents` 中包含 `GROUP_AT_MESSAGE_CREATE`，且机器人已被添加到目标群
上线后沙箱正常但正式不行	需在 QQ 开放平台提交审核，通过后将 `sandbox` 改为 `false`

更多详情请参考 QQ 开放平台 OpenClaw 文档。

📋 九、硬件要求 & 常用命令

硬件要求

项目	最低要求	推荐配置
操作系统	Win10+, Ubuntu 20.04+	同左
Node.js	v18+	v22+ LTS
内存	8GB	16GB+
磁盘	5GB	20GB+（本地模型）
GPU	无（云端 API）	RTX 4060+（本地模型）

常用命令速查

openclaw onboard初始化配置

openclaw config修改配置

openclaw gateway start启动后台服务

openclaw gateway restart重启后台服务

openclaw tui打开终端交互界面

openclaw update更新到最新版本

openclaw skills list查看已安装技能

日常维护：建议每周执行 openclaw update 保持最新，定期轮换 API Key（每 90 天）。

🔐 注册后解锁完整教程

您正在阅读的是免费预览部分。
注册账号即可查看全部 8 个章节的完整内容，包括
Windows/Linux 详细部署、AI API 配置、常见问题排查等。

✨ 免费注册已有账号？登录

免费注册完整教程持续更新社群答疑

📣 加入 OpenClaw 学习交流群

纯公益分享，0 费用，0 套路。群内资深用户实时答疑，手把手带你从零完成部署！

👆 微信扫码加入 · 名额有限

⚠️ 二维码 7 天内有效，过期请关注公众号「创芯观察」获取最新入群方式

🚀 OpenClaw 本地部署全攻略

📑 目录导航

📌 一、OpenClaw 是什么？

⚡ 二、一键部署（最快方式）

macOS / Linux 一键部署

Windows 一键部署

安装完成后

🖥️ 三、Windows 详细部署教程

🐧 四、Linux 部署教程

🔑 五、打通 AI API 接口

方案 A：直接对接官方 API

方案 B：使用 API 代理（国内用户推荐）

配置方式一：配置向导

配置方式二：手动修改配置文件

重启服务 & 验证

🐳 六、Docker 部署（进阶用户可选）

⚠️ 七、常见问题排查（必看！）

🔧 安装阶段问题

🪟 Windows 专属问题

🔑 API 和网络问题

⚙️ 配置和运行问题

🛡️ 安全注意事项

🔍 万能排查三板斧

🤖 八、QQ 机器人配置

8.1 申请 QQ 机器人

8.2 配置 OpenClaw 连接 QQ 机器人

8.3 测试验证

常见问题

📋 九、硬件要求 & 常用命令

硬件要求

常用命令速查

🔐 注册后解锁完整教程

📣 加入 OpenClaw 学习交流群