彻底告别“说明书”!OpenClaw 保姆级教程,Mac/Win终极部署指南

最近 AI 圈最火的莫过于“养龙虾”（OpenClaw）了！看着大佬们一个个玩得风生水起，自己一装就报错卡麻了？想砸键盘？

别慌！这篇是融合了市面上所有踩坑血泪史的终极保姆教程。不管是 Mac 还是 Windows，原生直装还是 Docker 隔离，照着抄作业，闭眼入，保准你的“赛博小龙虾”今天就活蹦乱跳！

第一步：保命要紧的“避坑基建” (装前必看)

在开始敲键盘前，先把这几条底线查清楚，能帮你省去 99% 掉头发的时间：

• 硬件底线：CPU 至少双核，强烈建议四核，保障运行流畅度。内存最低 4GB，推荐 8GB 及以上，运行模型才稳定。硬盘必须腾出至少 50GB 可用空间。
• Windows 系统要求：要求 Windows 10 (2004版本及以上) 或 Windows 11，且必须是 64 位。
• 致命路径地雷：Windows 所有的操作目录、安装路径、哪怕是你电脑的用户名，绝对绝对不能有中文、空格或特殊字符！这是引发各种玄学报错的万恶之源。
• 必备 Node.js 环境：必须是 Node.js 18.x 或是 22 及以上版本。没装的去官网下载：
  https://nodejs.org/zh-cn/download。安装时一路默认，务必勾选“Add to PATH”添加到环境变量。装完在终端输入 node --version 和 npm --version 验证。强烈推荐使用 nvm-windows 来管理 Node.js 版本。
• 可选神兵 Git：强烈建议安装 Git，后续用于技能管理和版本控制。下载地址：
  https://git-scm.com/download/win。装完输入git --version 验货。
• 网络环境：部署全程必须保持联网。干活前最好把第三方杀毒软件和防火墙关掉，防止误杀进程或拦截对应端口。

第二步：Windows 玩家双通道 (二选一)

Windows 玩家有两条路，看你的需求入座！

方案 A：原生 PowerShell 一键部署（小白首选，10分钟搞定）

纯新手、只想赶紧体验、不想折腾额外环境的，选这个！缺点是环境无隔离，可能跟本地其他 Node.js 项目冲突。

1. 解锁权限封印（极其重要）：Windows 默认禁止运行远程脚本。如果不做这一步，一会安装必报错！按 Win+S 搜 PowerShell，右键选择“以管理员身份运行”。输入下面这行咒语并回车，提示是否更改执行策略时，输入 Y 确认，这就等于给你发了通行证： 

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2. 一键安装：关掉刚才那个管理员窗口，防止权限导致后续配置异常，重新开一个普通的 PowerShell 窗口。输入官方一键安装命令： 

   iwr -useb [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) | iex

   命令大揭秘：iwr
   是下载内容的缩写，-useb 代表基础解析兼容更好，iex 代表把下载的东西直接执行。 安装过程大概 3 到 10 分钟，脚本会自动检测系统并安装依赖，千万别关窗口，长时间没反应可以按回车刷新一下。看到提示 OpenClaw installed successfully 就稳了！

方案 B：WSL2 + Docker 隔离部署（硬核老鸟，纯净稳定）

不想搞乱本地环境，打算长期养虾的，走这条纯净隔离路线，彻底避免版本冲突。

1. 召唤 Linux 子系统：用管理员身份打开 PowerShell，输入命令开启 WSL2 和虚拟机平台： 

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestartdism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestartwsl --set-default-version 2

    搞定后必须重启电脑生效！
2. 安装 Ubuntu 22.04：重启后继续在管理员 PowerShell 里敲： 

   wsl --install -d Ubuntu-22.04

    装完按提示随便设个账号和密码。注意，输入密码时屏幕是不会显示任何字符的，这是正常的，盲打完回车就行。装完输入 wsl -l -v，显示版本为 2 即代表成功。
3. 给 Ubuntu 装 Node.js：打开 Ubuntu 终端，依次跑这三行，把 Linux 版的环境搭好： 

   sudo apt updatecurl -fsSL [https://deb.nodesource.com/setup_22.x](https://deb.nodesource.com/setup_22.x) | sudo -E bash -sudo apt install -y nodejs

4. 上 Docker 起飞：去 Docker 官网下载 Windows 版本：
   https://www.docker.com/products/docker-desktop。全程默认安装，装完重启。打开 Docker Desktop，进设置 (Settings) -> Resources -> WSL Integration 里，把 Ubuntu 22.04 集成勾上。
5. 打开 Ubuntu 终端，建个全英文目录，弄个 docker-compose.yml 文件跑起来： 

   mkdir -p ~/openclaw && cd ~/openclaw

    把下面这段配置塞进 docker-compose.yml 里： 

   version:'3.8'services:openclaw:image:openclaw/openclaw:latestcontainer_name:openclawrestart:alwaysports:-"18789:18789"volumes:-./data:/app/data-./config:/app/configenvironment:-TZ=Asia/Shanghai

   最后执行 docker-compose up -d。等 1 到 2 分钟，输入 docker ps，看到容器状态为 Up 就彻底通关！

第三步：Mac 玩家专属通道 (丝滑直通)

Mac 的部署最省心，终端敲几个命令的事儿。

1. 查户口：终端输入 node -v
   ，检查是否满足 22 及以上版本。再查 Homebrew (brew --version)，如果没有，用这个国内镜像一键秒装，速度更快且自动配环境变量： 

   /bin/zsh -c "$(curl -fsSL [https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh](https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh))"

    按提示输入 Mac 密码（不显示是正常的），镜像直接选 1 或 2 都可以，等它自己跑完。
2. 正片开始：终端直接运行官方推荐的拉取命令： 

   curl -fsSL [https://openclaw.ai/install.sh](https://openclaw.ai/install.sh) | bash

3. 权限报错终结者（小白必看）：如果在 Mac 上遇到满屏红字提示 EACCES 权限不足报错，别慌！直接复制下面这三行命令，依次执行解决权限问题，然后再重新执行上面的安装命令就成了： 

   sudochown -R $(whoami) /usr/local/lib/node_modulessudochown -R $(whoami) /usr/local/binsudochown -R 501:20 "/Users/你的用户名/.npm"

   如果还不行，技术大佬强烈推荐先安装 nvm 来管理 npm 环境，再执行安装命令。

   1. 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash2. 让 nvm 立即生效source ~/.zshrc3. 验证是否成功nvm --version

第四步：验明正身与初始化配置 (Onboarding)

安装完别急着关窗口，先看看活没活。终端敲 openclaw --version 或 openclaw help，能吐出版本号就说明主程序到位了。（注：部分环境或版本可能需要敲 openclaw-cn，本文通用）

接下来输入配置向导命令，带上守护进程参数，让它能在后台默默打工：

openclaw onboard --install-daemon

小白直接无脑抄下面的通关选项：

浏览器会自动弹到 http://127.0.0.1:18789。

找授权令牌：首次进网页提示“未授权：令牌缺失”？Windows 用户去打开“显示隐藏文件夹”，顺着路径找 C:\Users\你的Windows用户名\.clawdbot\clawdbot.json。右键用记事本打开，找到 "token" 字段，把引号里的超长字符串原封不动贴进网页授权。

发个消息测试对话，有回复即配置成功。

第五步：让虾长嘴 —— 极速接入飞书当小秘

光在网页里玩不够爽，我们把它接到飞书上！

openclaw channels add

{"scopes":{"tenant":["aily:file:read","aily:file:write","application:application.app_message_stats.overview:readonly","application:application:self_manage","application:bot.menu:write","cardkit:card:write","contact:contact.base:readonly","contact:user.employee_id:readonly","corehr:file:download","docs:document.content:read","event:ip_list","im:chat","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","im:message","im:message.group_at_msg:readonly","im:message.group_msg","im:message.p2p_msg:readonly","im:message.reactions:read","im:message:readonly","im:message:recall","im:message:send_as_bot","im:message:update","im:resource","sheets:spreadsheet","wiki:wiki:readonly"],"user":["aily:file:read","aily:file:write","docx:document:readonly","im:chat.access_event.bot_p2p_chat:read"]}}

1. 拿通关密码：去“凭证与基础信息”，把你的 App ID 和 App Secret 抄下来，千万保密别泄露。
2. 把密码喂给 OpenClaw：回到刚才暂停的电脑终端，把抄来的 ID 和 Secret 填进去。
3. 接收消息 (事件订阅)：回到飞书网页，左边找“事件与回调”，订阅方式绝对要选长连接，保存。然后点击添加事件，搜 im.message.receive_v1
   并勾选添加。这步的作用是建立长连接，不搞它跟死虾一样不回你。
4. 发布应用 (极其关键)：左侧找“版本管理与发布” -> “创建版本”。随便填个版本号比如 1.0.0，更新说明随便写，保存后点击确认发布申请上线。没有发布的应用机器人绝对不会响应。
5. 最后对暗号：打开飞书客户端或网页版，在开发者小助手里打开你创建的应用，发个测试消息。机器人回复后，根据终端里的提示，复制那串代码跑配对命令： 

   openclaw pairing approve feishu <配对码>

    打通全关，大功告成！

还能接啥？ OpenClaw 支持 20 多个平台，国内有钉钉、企业微信、QQ、个人微信；国际有 Telegram、Discord、Slack、WhatsApp、Line、Matrix、Signal，甚至 iMessage。套路都一样：装插件 -> 平台建应用 -> 拿 Token -> 配进 OpenClaw。

强烈推荐：Discord或者Telegram

第六步：进阶扩展，安装技能包

想让它干活？用终端命令给它装技能：

openclaw skill install file-organizeropenclaw skill install web-search

分别对应文件管理和联网搜索能力。

终极避坑指南：老中医急救箱 (必看排错大全)

卡壳了不要慌，对着症状直接抓药！

症状一：Windows 部署与基础报错

• 报错提示“脚本无法运行”：绝对是跳过了第一步的解锁权限。用管理员身份打开 PowerShell，重新执行 Set-ExecutionPolicy
   那行命令。
• Node.js 版本过低导致安装失败：手动去控制面板卸载旧版 Node.js，官网下 v22+ 安装包，务必勾选 Add to PATH，装完重启 PowerShell 再干。
• 网页端死活打不开，提示 18789 端口被占用：有其他进程抢位了。PowerShell 输入 netstat -ano | findstr "18789"
  找出占用进程的 PID 并结束它，或者去修改配置文件换个端口。
• Docker 部署容器启动失败：检查 WSL2 是不是真跑起来了，Docker 设置里 WSL 集成有没有勾上，重启 Docker Desktop 后重新执行启动命令。
• 授权令牌缺失，死活找不到 clawdbot.json 配置文件：显示隐藏文件夹，路径是 C:\Users\用户名\.clawdbot
  。如果还是没有，说明初始化失败，重新执行 onboard 命令生成。

症状二：OpenClaw 跑起来了，但对话没反应/报错

• API Key 输错了：复制时多带了空格或换行符。运行 openclaw configure
   重新输入。
• 网络问题：选了 Claude、GPT 等海外模型，国内直连不通，请配置代理或老实换国内模型。
• Token 额度被榨干了：去阿里云百炼后台查调用量。Agent 多轮调用极耗额度。
• 模型服务宕机：API 服务商偶尔短暂波动（比如 MiniMax），等几分钟重试或看官方状态页。
• 自检大招：遇到问题第一个运行 openclaw doctor
  ，让它自己诊断配置和状态。

症状三：飞书机器人像个哑巴，不收也不回

严格按照这 5 点顺藤摸瓜排查：

1. 应用发布了吗？
    “版本管理与发布” -> “创建版本”，否则机器人无响应。

1. 事件订阅配了吗？
    检查是否勾选 im.message.receive_v1。
2. 接收方式选对了吗？
    必须选长连接，不能是 URL 回调。
3. 权限批了吗？
    检查 im:message 权限是否通过审核。
4. 网关跑着吗？
    运行 openclaw gateway status 检查状态。 如果 5 项都没问题，查看底层实时日志抓虫，寻找红色的 ERROR 信息：

openclaw logs --follow

• 发消息失败，提示权限不足：专门去检查 im:message:send_as_bot
   权限有没有申请通过，这是机器人发消息的命脉，缺了就只能收不能回。
• 终极惨案：App Secret 泄露了怎么办？ 立刻去飞书开放平台 -> 凭证与基础信息，重置 App Secret。重置后旧的立刻失效。然后去更新 OpenClaw 配置文件里的 appSecret
  ，最后必须重启网关。

附录：网关服务高频命令速查表