Mac 部署安装 OpenClaw 教程:从零搭建个人 AI 助手完整指南
本文详细解析了在 Mac 上从零部署和安装 OpenClaw 个人 AI 助手的完整流程,
OpenClaw 是什么
简单来说,OpenClaw 是一个开源的个人 AI 助手框架。
它本身不提供大语言模型,但可以帮你把 Claude、GPT、DeepSeek、Gemini 这些主流模型串联起来,再对接到 Telegram、WhatsApp、飞书、Discord 等聊天平台上,形成一个真正属于你自己的 AI 助手。
它能做的事情挺多的:
- 多模型调用:同时接入多个 AI 模型(比如 DeepSeek、GPT、Claude),根据需要灵活切换
- 聊天平台对接:把 AI 能力接入你日常使用的通讯工具,比如飞书、Telegram、微信等
- 本地文件管理:让 AI 帮你处理和管理电脑上的文档
- 浏览器自动化:让 AI 帮你完成一些重复性的网页操作
- 对话式操控:用聊天的方式让 AI 帮你在电脑上执行各种操作
- 记忆系统:AI 能记住之前聊过的内容,不会每次都"失忆"
截至 2026 年初,OpenClaw 在 GitHub 上已经有超过 28 万颗星,社区非常活跃。它采用 MIT 开源许可,完全免费使用。

参考文档:
环境准备工作
安装 Homebrew
bash
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
安装完成后,重新打开终端,查看是否安装成功
bash
brew -v
先安装 Node,如果你还没有的话
bash
brew install node
在终端回车后,应该显示 v22.x.x 或者更高的数字(比如 v22.11.0)。再检查一下附带的包管理工具:
bash
node -v
如果低于这个版本,说明之前安装过,执行以下命令进行更新
bash
brew upgrade node
配置 npm 全局路径(强烈建议做),这一步是为了避免后面安装 OpenClaw 时碰到"权限不够"的报错。只需要执行下面 4 条命令,每条都是复制粘贴然后回车:
bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
说明:上面 4 条命令的作用是告诉电脑"以后安装的全局软件放到你自己的目录里",这样安装时就不会碰到权限问题了。
验证一下配置是否成功:
bash
npm config get prefix
输出里包含 .npm-global 就对了。
安装 OpenClaw
方式1:快速安装
这是官方推荐的方式,也是最省事的。把下面这条命令复制到终端,回车执行:
bash
curl -fsSL https://openclaw.ai/install.sh | bash
如果遇到像我一样的网络问题,可以尝试第二种
安装完成后,验证是否成功:
bash
openclaw --version
方式2:npm安装(国内网络更友好)
如果方式一因为网络原因失败了,或者下载太慢,用 npm 安装反而更顺畅(因为前面已经配好了国内镜像源)。在终端执行:
bash
npm install -g openclaw@latest
安装完成后手动执行引导:
bash
openclaw onboard --install-daemon
方式3:从源码构建
如果想了解其代码和原理,参与贡献,可以通过源码构建。普通用户可以跳过这部分。
bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon
初始化与配置
如果你用的是一键脚本安装,引导流程会自动启动。如果没有自动启动,或者你用的是 npm 安装,在终端执行:
bash
openclaw onboard
接下来屏幕上会出现一个交互式向导,用键盘上的方向键选择选项,按回车键确认。它会依次问你几个问题:
- 启动模式:用方向键选择 QuickStart(快速开始),然后按回车
- AI 模型选择:这里选你打算用的 AI 模型。如果你还没注册任何模型账号,可以先选 Qwen(通义千问)——它可以扫码直接使用,不需要填 Key
- API Key 输入:如果选了需要 Key 的模型(比如 DeepSeek),把你的密钥粘贴进去。没有的话暂时跳过,后面可以再配
- 聊天平台:选你想对接的通讯工具(飞书、Telegram 等),也可以先跳过
什么是 API Key? 简单说就是一个"通行证"。你注册了 AI 模型的账号后,在它的后台可以生成一串字符(通常以
sk-开头),有了这串字符,OpenClaw 才能调用这个 AI 模型。就像你有了门卡才能刷卡进小区一样。
完成后,OpenClaw 会在你的电脑上生成核心配置文件,准备工作就算做好了。
手动配置(一般不需要)
大部分情况下,通过上面的向导就能完成配置。但如果你后续需要修改设置(比如换一个 AI 模型、改端口号等),可以手动编辑配置文件。
配置文件的位置在:~/.openclaw/openclaw.json,我们修改前先备份一下
bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
然后用编辑器打开修改。最简单的方式是在终端输入:
bash
open -e ~/.openclaw/openclaw.json
这样会用 Mac 自带的"文本编辑"应用打开配置文件。
这里给一个接入 DeepSeek 模型的基础配置示例,你可以参考:
json
{
"models": {
"mode": "merge",
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com/v1",
"apiKey": "sk-替换成你自己的Key",
"api": "openai-completions",
"models": [
{
"id": "deepseek-chat",
"name": "DeepSeek Chat",
"input": [
"text"
],
"contextWindow": 128000,
"maxTokens": 8192,
"reasoning": false
}
]
}
}
},
"agents": {
"defaults": {
"maxConcurrent": 4,
"model": {
"primary": "deepseek/deepseek-chat"
}
}
},
"gateway": {
"port": 18789,
"mode": "local"
}
}
如果你想用 Kimi(月之暗面)模型,把 providers 里的内容换成下面这样就行。
Kimi 最大的优势是支持 200 万字的超长上下文,特别适合处理长文档,而且 Kimi 注册有送免费额度,可以试一下:
bash
{
"models": {
"mode": "merge",
"providers": {
"moonshot": {
"baseUrl": "https://api.moonshot.cn/v1",
"apiKey": "sk-替换成你的Kimi Key",
"api": "openai-completions",
"models": [
{
"id": "moonshot-v1-8k",
"name": "Kimi 8K",
"input": [
"text"
],
"contextWindow": 8000,
"maxTokens": 4096,
"reasoning": false
},
{
"id": "moonshot-v1-128k",
"name": "Kimi 128K",
"input": [
"text"
],
"contextWindow": 128000,
"maxTokens": 4096,
"reasoning": false
}
]
}
}
},
"agents": {
"defaults": {
"maxConcurrent": 4,
"model": {
"primary": "moonshot/moonshot-v1-8k"
}
}
},
"gateway": {
"port": 18789,
"mode": "local"
}
}
接入聊天工具(可选)
到这里 OpenClaw 已经可以正常使用,你可以在浏览器的 Web 界面里和 AI 聊天。
如果你还想更进一步,可以把 AI 接入到你日常用的聊天工具里(比如飞书、Telegram),这样就能直接在聊天软件里跟你的 AI 助手对话。
这一步 不是必须的,感兴趣的话可以试试。
飞书接入示例
以 飞书 为例,大致流程如下:
- 安装飞书插件
bash
openclaw plugins install @m1heng-clawd/feishu
- 去 飞书开放平台 注册一个开发者账号,创建一个应用,拿到
App ID和App Secret - 在终端里配置飞书的连接信息(把 cli_你的AppID 和 你的AppSecret 替换成真实的值):
或者bash
openclaw config set channels.feishu '{"enabled":true,"appId":"cli_你的AppID","appSecret":"你的AppSecret"}' --jsonbashopenclaw config set channels.feishu.appId "你的AppID" openclaw config set channels.feishu.appSecret "你的AppSecret" openclaw config set channels.feishu.enabled true openclaw config set channels.feishu.connectionMode websocket openclaw config set channels.feishu.dmPolicy pairing openclaw config set channels.feishu.groupPolicy allowlist openclaw config set channels.feishu.requireMention true - 重启 OpenClaw 让配置生效:
bash
openclaw gateway restart - :配置飞书事件与权限
- 在飞书后台 → 事件与回调 → 选择 长连接模式 并保存。
- 添加事件:选择 接收消息(含私聊和群聊)。
- 在 权限管理 中勾选:
contact:user.base:readonly(获取用户信息)im:message(发送/接收消息)等必要权限3。 - im:chat、im:message、im:message:send_as_bot(消息发送与接收)
contact:user.employee_id:readonly、contact:contact.base:readonly(用户信息访问)
application:bot.menu:write、cardkit:card:write(交互式卡片与菜单)
sheets:spreadsheet、docs:document.content:read(文件与文档访问) - 保存并发布新版本应用。
- 测试连接
- 在飞书搜索并私聊机器人,发送 Hello,若收到 OpenClaw 回复则对接成功。
- 若需群聊支持,将机器人添加进群,并调整:
bash
openclaw config set channels.feishu.dmPolicy open openclaw config set channels.feishu.groupPolicy open - 重启后即可在群中使用。
提示:每次修改配置后需重新发布飞书应用版本,否则新设置不会生效。
配置完成后,你就可以在飞书里直接和你的 AI 助手对话了。Telegram 用户:Telegram 的配置更简单。在 Telegram 里找到 @BotFather 创建一个机器人,它会给你一个 Bot Token,把这个 Token 填到 OpenClaw 配置里就行。
验证配置是否正确
改完配置后,建议验证一下格式是否正确。在终端执行:
bash
openclaw doctor
这个命令会做一次全面检查,包括配置文件格式、Node.js 版本、API Key 是否可用等。如果一切正常,你会看到一连串的绿色对勾。如果有问题,它会告诉你具体哪里出了错。
启动与验证
启动网关服务
一切配置就绪后,就可以启动 OpenClaw 了!在终端执行:
bash
openclaw gateway start
启动成功后,运行以下命令确认状态:
bash
openclaw status
访问 Web 界面
bash
http://127.0.0.1:18789
你应该能看到 OpenClaw 的控制台界面。试着在输入框里发一条消息,比如"你好"或者"帮我写一首诗"。
如果几秒钟内收到了 AI 的回复,恭喜你——部署成功了! 🎉
也可以通过终端命令直接打开控制台:
bash
openclaw dashboard
设置开机自启
每次重启电脑都要手动启动 OpenClaw 肯定很麻烦。你可以设置成开机自动启动:
bash
openclaw gateway install
这样你的 Mac 每次开机,OpenClaw 都会在后台自动运行,不需要你手动操作。
如果以后想取消开机自启:
bash
openclaw gateway uninstall
日常运维管理
部署完成后,日常用到的命令不多,这里列一份 速查表,建议收藏一下:
| 你想做什么 | 在终端输入的命令 |
|---|---|
| 启动 OpenClaw | openclaw gateway start |
| 停止 OpenClaw | openclaw gateway stop |
| 重启 OpenClaw | openclaw gateway restart |
| 查看是否在运行 | openclaw status |
| 做一次全面检查 | openclaw doctor |
| 查看运行日志 | openclaw gateway logs |
| 更新到最新版 | openclaw update |
| 打开 Web 控制台 | openclaw dashboard |
关于更新
OpenClaw 的更新频率挺高的,建议 隔一两周更新一次。
更新前先备份一下配置,以防万一:
bash
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)
然后执行更新:
bash
openclaw update
完全卸载
如果你想 彻底移除 OpenClaw 重新来过,在终端依次执行下面的命令:
bash
openclaw gateway stop
pkill -f openclaw
npm uninstall -g openclaw
rm -rf ~/.openclaw
rm -rf /tmp/openclaw
执行完后,检查一下是否清理干净:
bash
ps -ef | grep openclaw | grep -v grep
如果这条命令没有输出任何内容,说明已经彻底清理干净了。
常见问题
之前某次用了 sudo npm,把 ~/.npm 目录变成 root 权限了,导致以下问题:
bash
$ npm install -g openclaw@latest
npm error code EACCES
npm error syscall open
npm error path /Users/chenxiangwen/.npm/_cacache/index-v5/34/4a/298d33da9456964bcffe222c74d8de9afa4300238688b68d4a2701866fab
npm error errno EACCES
npm error
npm error Your cache folder contains root-owned files, due to a bug in
npm error previous versions of npm which has since been addressed.
npm error
npm error To permanently fix this problem, please run:
npm error sudo chown -R 501:20 "/Users/chenxiangwen/.npm"
npm error A complete log of this run can be found in: /Users/chenxiangwen/.npm/_logs/2026-03-11T01_53_49_892Z-debug-0.log
一步解决
bash
sudo chown -R $(whoami) ~/.npm
重新安装即可
bash
npm install -g openclaw@latest

飞书相关权限
参考文章:https://www.feishu.cn/content/article/7613711414611463386
json
{
"scopes": {
"tenant": [
"contact:contact.base:readonly",
"docx:document:readonly",
"im:chat:read",
"im:chat:update",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message.pins:read",
"im:message.pins:write_only",
"im:message.reactions:read",
"im:message.reactions:write_only",
"im:message:readonly",
"im:message:recall",
"im:message:send_as_bot",
"im:message:send_multi_users",
"im:message:send_sys_msg",
"im:message:update",
"im:resource",
"application:application:self_manage",
"cardkit:card:write",
"cardkit:card:read",
"contact:user.basic_profile:readonly"
],
"user": [
"contact:user.employee_id:readonly",
"offline_access","base:app:copy",
"base:field:create",
"base:field:delete",
"base:field:read",
"base:field:update",
"base:record:create",
"base:record:delete",
"base:record:retrieve",
"base:record:update",
"base:table:create",
"base:table:delete",
"base:table:read",
"base:table:update",
"base:view:read",
"base:view:write_only",
"base:app:create",
"base:app:update",
"base:app:read",
"sheets:spreadsheet.meta:read",
"sheets:spreadsheet:read",
"sheets:spreadsheet:create",
"sheets:spreadsheet:write_only",
"docs:document:export",
"docs:document.media:upload",
"board:whiteboard:node:create",
"board:whiteboard:node:read",
"calendar:calendar:read",
"calendar:calendar.event:create",
"calendar:calendar.event:delete",
"calendar:calendar.event:read",
"calendar:calendar.event:reply",
"calendar:calendar.event:update",
"calendar:calendar.free_busy:read",
"contact:contact.base:readonly",
"contact:user.base:readonly",
"contact:user:search",
"docs:document.comment:create",
"docs:document.comment:read",
"docs:document.comment:update",
"docs:document.media:download",
"docs:document:copy",
"docx:document:create",
"docx:document:readonly",
"docx:document:write_only",
"drive:drive.metadata:readonly",
"drive:file:download",
"drive:file:upload",
"im:chat.members:read",
"im:chat:read",
"im:message",
"im:message.group_msg:get_as_user",
"im:message.p2p_msg:get_as_user",
"im:message:readonly",
"search:docs:read",
"search:message",
"space:document:delete",
"space:document:move",
"space:document:retrieve",
"task:comment:read",
"task:comment:write",
"task:task:read",
"task:task:write",
"task:task:writeonly",
"task:tasklist:read",
"task:tasklist:write",
"wiki:node:copy",
"wiki:node:create",
"wiki:node:move",
"wiki:node:read",
"wiki:node:retrieve",
"wiki:space:read",
"wiki:space:retrieve",
"wiki:space:write_only",
"contact:user.basic_profile:readonly"
]
}
}
