OpenClaw Mac本地部署保姆级教程：手把手教你“养龙虾”

目录

一、部署前必读：你的Mac够格“养虾”吗？

1.1 硬件要求（别担心，要求不高）

1.2 你需要准备的东西

二、Step 1：安装Homebrew（Mac的“应用商店”）

三、Step 2：安装Node.js（OpenClaw的运行环境）

可选但推荐：安装Redis

四、Step 3：安装OpenClaw（核心步骤）

4.1 一键安装脚本（最简单，推荐）

​编辑

4.2 如果一键脚本失败（备用方案：手动安装）

4.3 解决“command not found”问题

五、Step 4：初始化配置（Onboarding向导）

5.1 交互式配置步骤

5.2 验证初始化状态

六、Step 5：配置Gateway服务

6.1 配置Gateway模式

6.2 启动Gateway服务

6.3 配置开机自启（可选）

七、Step 6：配置大模型API（给龙虾装上“大脑”）

7.1 获取阿里云百炼API Key

7.2 配置API Key

7.3 验证模型配置

八、Step 7：访问Web控制台

8.1 启动控制台

8.2 控制台界面介绍

九、可选进阶：安装常用技能（Skills）

9.1 查看可用技能

9.2 安装实用技能

9.3 技能选择黄金法则

十、常用命令速查表

十一、常见问题排查（避坑指南）

问题1：端口18789被占用

问题2：Node.js版本不对

问题3：权限错误（EACCES）

问题4：Redis连接失败

问题5：API调用失败

十二、写在最后：你的“龙虾”养成记

疑问解答：

既然你想在自己的Mac上部署OpenClaw，那我就给你一份2026年最新、最详细、最靠谱的“养龙虾”指南。按照这个教程操作，哪怕你是技术小白，也能在30分钟内让你的Mac“长出”一只能干活的小龙虾。

本文整合了阿里云开发者社区、腾讯云技术百科、Apifox等多方权威教程，所有命令均可直接复制执行。

1.1 硬件要求（别担心，要求不高）

1.2 你需要准备的东西

• 一个API Key：OpenClaw需要大模型“大脑”才能理解指令，推荐使用阿里云百炼（新用户有免费额度）或OpenAI API
• 稳定的网络：安装过程需要下载依赖包
• 耐心：大概15-30分钟

Homebrew是Mac上必备的包管理器，后续很多依赖都要靠它安装。打开终端（Terminal），执行：

bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，根据终端提示运行接下来的两条命令（通常是让你把brew加入环境变量）。

验证安装：

bash

brew --version # 输出版本号即成功，如下图所示： 

OpenClaw基于Node.js开发，需要v22.0.0及以上版本。

bash

# 安装Node.js 24.x LTS（推荐） brew install node@24 # 将node加入PATH echo 'export PATH="/usr/local/opt/node@24/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # 验证安装 node --version # 应显示 v24.x.x npm --version # 应显示 10.x.x

安装成功后，如下图所示：

小贴士：如果你需要管理多个Node版本，可以安装nvm：

bash

brew install nvm nvm install --lts nvm use --lts

可选但推荐：安装Redis

Redis用于提升OpenClaw的记忆和任务队列能力：

bash

brew install redis brew services start redis redis-cli ping # 返回PONG即成功，如下图所示：

4.1 一键安装脚本（最简单，推荐）

OpenClaw官方提供了一键安装脚本，会自动处理所有依赖：

bash

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

或者指定安装beta版（2026年最新版）：

bash

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

安装完成后，需要重新加载终端配置：

bash

source ~/.zshrc

验证安装：

bash

openclaw --version # 应显示 2026.x.x 版本号

安装成功后，如下图所示：

4.2 如果一键脚本失败（备用方案：手动安装）

如果网络原因导致一键脚本失败，可以尝试手动安装：

bash

# 全局安装 npm install -g openclaw@latest # 如果遇到sharp模块报错（常见于M芯片Mac） SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

4.3 解决“command not found”问题

如果安装后输入提示找不到命令，说明npm全局路径没加到环境变量：

bash

# 找到npm全局路径 npm prefix -g # 假设输出是 /usr/local，则二进制路径是 /usr/local/bin # 添加到环境变量 echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

安装完成后，需要运行初始化向导来配置OpenClaw：

bash

openclaw onboard --install-daemon

这个向导会一步步引导你完成关键配置，以下是详细步骤：

5.1 交互式配置步骤

5.2 验证初始化状态

bash

# 健康检查 openclaw doctor 这个命令非常重要，运行后出现下面界面：  选择Yes，后出现下面的界面：  选择Yes,出现下面的界面：  # 查看服务状态 openclaw status

通过openclaw status可以看到非常多的openclaw状态信息：

Gateway是OpenClaw的核心服务，负责消息调度、任务执行和Web控制台。

6.1 配置Gateway模式

bash

# 设置Gateway为本地模式 openclaw config set gateway.mode local

运行命令openclaw config set gateway.mode local后，出现下面界面：

上图的意思是：你已经成功设置了Gateway的本地模式，现在只需要重启Gateway服务就能让配置生效了。立即执行：

openclaw gateway restart

openclaw 龙虾

看到这个输出说明OpenClaw的Gateway服务已经以LaunchAgent（macOS后台服务）的形式重新启动了。 表示它是在你的用户权限下运行的，501是你的用户ID

6.2 启动Gateway服务

bash

# 启动服务 openclaw gateway start 成功如下图所示：  看到这个友好的输出——“I'm not magic—I'm just extremely persistent with retries and coping strategies”（我不是魔法，我只是对重试和应对策略极其执着）——这是OpenClaw的特色幽默，说明它已经成功重启了。 # 查看服务状态（应显示Running） openclaw gateway status

出现下面的界面，即为成功：

6.3 配置开机自启（可选）

bash

# 安装为系统服务（开机自动启动） sudo openclaw gateway install

执行sudo openclaw gateway install出现下面内容：

看到这个错误提示，别担心！这是macOS权限管理的常见问题。错误  通常是因为 sudo 和 LaunchAgent 权限冲突。

OpenClaw Gateway 是以用户级服务（LaunchAgent） 运行的，而  是系统级权限，两者不在同一个“域”里，所以会报错。快速解决方案，去掉sudo可以成功：

OpenClaw本身没有推理能力，需要对接大模型API。这里以阿里云百炼为例（推荐，国内访问稳定且有免费额度）。

7.1 获取阿里云百炼API Key

1. 访问阿里云百炼控制台
2. 进入“密钥管理”页面
3. 点击“创建API-Key”，复制生成的密钥（仅显示一次，务必保存）

可以看到API密钥

核心结论：API Key = accessKeyId（不需要accessKeySecret）

查看模型的用量：

7.2 配置API Key

bash

# 配置API凭证 openclaw config set models.providers.bailian.accessKeyId "你的AccessKeyId" 报错了：  查看OpenClaw配置文件：vim ~/.openclaw/openclaw.json

直接找到文件绝对路径修改更快：echo ~/.openclaw/openclaw.json 

/Users/linfawei/.openclaw/openclaw.json  上图是阿里云官方提供的配置。 # 重启Gateway使配置生效 openclaw gateway restart 

网关重启成功，可以看到下面的界面：

7.3 验证模型配置

bash

# 检查模型状态 openclaw models status 模型配置成功，会出现下面的界面：

配置完成后，可以通过Web界面与你的“龙虾”对话。

8.1 启动控制台

bash

openclaw dashboard 

运行命令openclaw dashboard后，可以打开上面面板，但是报错：

disconnected (1008): unauthorized: gateway token missing (open a tokenized dashboard URL or paste token in Control UI settings)

【修复步骤】

text
– Main session transcript missing (~/.openclaw/agents/main/sessions/bea1d1ae-a758-4660-9ea2-ea565a16f37f.jsonl)
这个缺失的会话文件可能是导致连接问题的原因。我们可以用自动修复功能：
openclaw doctor –fix
这个命令会尝试自动修复检测到的问题，包括那个缺失的会话文件。

第二步：重启网关服务
修复完成后，重启网关让所有配置生效：
openclaw gateway restart
第三步：重新获取并访问带令牌的URL
现在重新生成带令牌的访问链接：
openclaw dashboard –no-open

网关界面：

http://127.0.0.1:18789/chat?session=agent%3Amain%3Amain

这个命令会自动：

1. 生成一个临时登录Token
2. 用默认浏览器打开 

如果浏览器没自动打开，手动访问  并输入以下命令查看Token：

bash

# 查看Token cat ~/.openclaw/openclaw.json | grep '"token"' | awk -F'"' '{print $4}'

8.2 控制台界面介绍

进入Web控制台后，你可以：

• 聊天：直接与AI助理对话

问你好后，AI回复下图内容：

可以命令OpenClaw自动完成改名操作。

• 管理技能：安装/卸载各种功能扩展
• 查看日志：实时监控运行状态
• 配置定时任务：让龙虾自动干活

Skills是OpenClaw的“双手”，让它能执行具体任务。ClawHub社区已有超过1.3万个技能。

9.1 查看可用技能

bash

# 列出已安装技能 openclaw skills list 

【系统默认安装】

1、 ✓ ready   │ 📦 bluebubbles    │ Build or update the BlueBubbles external channel plugin for OpenClaw  

为 OpenClaw 构建或更新一个名为 “BlueBubbles” 的外部通信渠道插件 。

简单来说，它是在帮你打通 iMessage 和 OpenClaw 的连接

2、 的意思是：

skill-creator 是一个由 OpenClaw 官方预置（bundled） 的元技能，它的作用是帮助你创建、设计、结构化和打包其他的 Agent 技能。

简单来说，这是一个“制造技能的技能”。

3、✓ ready   │ 🌤️ weather       │ Get current weather and forecasts (no API key required). 

weather 是一个无需 API 密钥就能使用的天气查询工具，可以获取当前天气和天气预报。

【系统扩展安装】

4、Self-Improving Agent 自我进化Agent skill。

5、Word / Docx

• ✅ 读取 Word (.docx) 文档结构
• ✅ 生成格式正确的 Word 文档
• ✅ 处理样式、列表、页眉页脚
• ✅ 跨平台兼容（Windows/Mac/Linux）

6、Feishu Doc Manager | 飞书文档管理器

核心功能：

• ✅ 将 Markdown 内容发布到飞书文档
• ✅ 自动渲染格式（标题、列表、粗体等）
• ✅ Markdown 表格自动转换为格式化列表
• ✅ 一键协作者权限管理
• ✅ 长内容自动分段（避免 400 错误）

解决的痛点：

9.2 安装实用技能

报错：

# 安装浏览器自动化技能

✖ Rate limit exceeded

Error: Rate limit exceeded

看到  这个错误，说明你遇到了 GitHub API 的访问频率限制。这是因为在没有正确配置 GitHub Token 的情况下，clawhub 使用的是匿名访问，每小时只有 60 次请求的额度，很容易就被用完了，可以通过设置gittoken的方式解决。

查询已经安装的技能：

openclaw skills list | grep browser # 安装日程管理技能 openclaw skills install calendar

9.3 技能选择黄金法则

• 痛点优先：缺什么装什么，别贪多
• 安全第一：安装前审阅技能脚本，警惕过度索权
• 轻量化：同类功能二选一，避免冲突

问题1：端口18789被占用

bash

# 查找占用端口的进程 lsof -i :18789 # 杀死进程（替换PID） kill -9 PID

问题2：Node.js版本不对

bash

# 使用nvm切换版本 nvm install 24 nvm use 24

问题3：权限错误（EACCES）

bash

# 修复npm权限 sudo chown -R $(whoami) ~/.npm

问题4：Redis连接失败

bash

# 启动Redis服务 brew services start redis # 测试连接 redis-cli ping

问题5：API调用失败

• 检查API Key是否正确
• 确认网络能访问API服务
• 查看日志：

恭喜！现在你的Mac上已经有了一只功能强大的“小龙虾”。你可以通过Web界面或终端与它对话，让它帮你处理邮件、管理日程、编写代码，甚至控制智能家居。

记住几个核心原则：

1. 把它当实习生：初期多检查它的工作成果
2. 给最小权限：只授予完成任务所需权限
3. 定期审计：查看行为日志，发现异常及时处理
4. 及时更新：保持最新版本

OpenClaw的魅力在于它的可扩展性——你可以教它新技能，让它自己编写代码来改进自己。欢迎来到个人AI助理的新时代！

13.1 OpenClaw集成飞书

阿里云为了卖token提供官方指导：【这个方案不太行】

https://help.aliyun.com/zh/simple-application-server/use-cases/openclaw-integrated-fly-book?spm=a2c4g..help-menu-58607.d_3_0_0_2.30ca36bchgv5k0&scm=.H_._.OR_help-T_cn~zh-V_1

【飞书插件方案】

安装飞书插件

openclaw plugins install @openclaw/feishu

openclaw gateway restart

运行  添加了 Feishu 渠道

openclaw gateway restart

查看插件列表，插件状态

openclaw plugins list

飞书插件安装小结：

非常不顺利，装了3.2，3.7 两个版本，删掉了一个3.7。

只有当OpenClaw飞书插件安装成功后，飞书开发者后台才能够成功保存长连接的配置，否则报错无法保存。

把机器人配置到群里面。

@配置好的机器人，就可以从天涯海角操作自己的Mac了。

14.1 可以自动的在CSDN写文章

只能写到草稿的状态。

14.2 可以布置任务，帮你安软件、安模型、大软件。

14.3 可以写各种代码、脚本。

1、OpenClaw中文社区

https://www.moltcn.com/start/wizard.html#_3-%E5%B7%A5%E4%BD%9C%E5%8C%BA

2、阿里云百练

https://bailian.console.aliyun.com/

3、阿里云官方模型配置指引，OpenClaw模型配置

https://help.aliyun.com/zh/model-studio/openclaw#step-config-manual-title

4、OpenClaw源码地址

https://github.com/openclaw/openclaw

5、飞书配置比较详细的方法

https://docs.openclaw.ai/zh-CN/channels/feishu

6、官网，看起来没啥内容

https://openclaw.ai/

安装命令：npm i -g openclaw

7、中文官网，一些安装指导

https://clawcn.net/platforms/ios.html

8、skills市场，技能社区

https://clawhub.ai/skills?sort=downloads

9、阿里云自己搞了个集成引导，必须得买服务器