Openclaw 在 Mac 上本地化部署

OpenClaw 是 Moltbot/Clawdbot 的最新正式名称。经过版本迭代与改名后，2026年统一以「OpenClaw」作为官方名称，核心定位是通过自然语言指令，替代人工完成流程化、重复性工作，无需用户掌握编程技能，适配多场景自动化需求。

该项目经历了多次更名，Clawdbot → Moltbot → OpenClaw（当前名称）

一、OpenClaw 是什么？

OpenClaw 是一个开源的个人 AI 助手平台。

简单来说，它是一个可以将你自己的 AI 助手接入你已经在用的即时通讯工具（Telegram、WhatsApp、飞书等）的系统。你可以自己挑选 AI 模型进行连接，添加各种工具和技能（如飞书等），构建专属工作流。说白了如果应用的够好，它就是一个能帮你干活的“员工”。

OpenClaw 采用模块化设计，其核心架构如图所示

 

OpenClaw 不是一个套了层壳的 AI 聊天机器人，它是一个AI Agent 的操作系统。它采用调度中心架构，就像一个机场调度中心，所有航班（消息）都经过一个中央塔台（Gateway 网关），由它分配到正确的跑道（Agent）。

核心就两大模块：

1. 网关（Gateway）：一个 WebSocket 服务器，连接各种聊天平台和控制界面，把收到的消息派发给 Agent 运行时处理。
2. 智能体（Agent） ：真正干活的核心引擎，组装上下文、调用 AI 模型、执行工具操作（比如浏览网页、操作文件、定时任务等）、保存状态。

关键设计思想： 把消息通信、接口层和AI 怎么思考和执行（Agent）彻底分开。

这样你就有了一个统一的 AI 助手，不管你从 WhatsApp、飞书 还是钉钉发消息，它都能接入。而且会话状态和工具权限都在你的设备上集中管理。

注意：OpenClaw 需要访问不少本地权限和文件。建议找一台没有数据的 Mac 来试水，避免自己的隐私数据泄露。

二、OpenClaw通过插件实现可扩展性

那么OpenClaw 怎么在不改核心代码的情况下，扩展新功能？

OpenClaw 的设计哲学是开放扩展，不改核心。

可以通过插件（Plugin）在四个方向上扩展：

• 渠道插件（Channel Plugin）：添加新的聊天平台，比如 飞书、钉钉等
• 记忆插件（Memory Plugin）：换一种存储后端，比如用向量数据库代替默认的 SQLite
• 工具插件（Tool Plugin）：添加自定义能力，比如除了内置的命令行、浏览器、文件操作之外的新工具
• 模型提供商插件（Provider Plugin）：接入自定义的 AI 模型或自己部署的模型

插件代码放在 extensions/ 目录下，系统会自动扫描、发现和加载。

三、OpenClaw 的核心组件

3.1.渠道适配器（Channel Adapter）

OpenClaw 怎么对接各种聊天平台，把不同平台的消息翻译成统一格式？

每个聊天平台都有一个专门的适配器。有些是内置的（比如 Telegram、Discord），有些可以通过插件添加。不同平台的 API 和协议千差万别，但每个适配器都做同样的四件事：

1. 身份验证（Authentication）
2. 收消息并解析（Inbound Message Parsing）
3. 访问控制（Access Control）
4. 发消息并格式化（Outbound Message Formatting）

3.1.1.身份验证

不同平台的验证方式不一样：

• WhatsApp：用 QR 码配对（通过 Baileys 库），凭据存在本地
• Telegram / Discord：用 Bot Token（机器人令牌），通过环境变量配置
• iMessage：需要 macOS 原生集成，必须在真正的 Mac 上跑

3.1.2.收消息并解析

各平台的数据格式差异非常大，适配器的工作就是把它们统一。

不管消息从 WhatsApp 还是 飞书来，提取出文字、图片、音频、视频、文档、表情反应和回复上下文后，OpenClaw 的其他部分就不用操心平台差异了。

3.1.3.访问控制

这是渠道层面的安全关卡：

• 白名单（Allowlist）：指定哪些手机号/用户名可以跟你的 Bot 对话
• 私聊策略（DM Policy）：默认是配对模式，陌生人发消息得先审批才能通过；也可以设成”开放”（不推荐）或”禁止”
• 群聊策略：可以要求 Bot 只在被 @提到时才回复，还能设群级别的白名单

3.1.4.发消息并格式化

每个平台的 Markdown 格式、消息长度限制、媒体上传方式都不一样。适配器负责处理这些，长消息自动切分、Markdown 格式转换、媒体文件上传、甚至”正在输入”的提示。

3.2.控制界面（Control Interface）

除了聊天 App，OpenClaw 提供了四种交互方式可以操控 OpenClaw。

3.2.1.网页界面（Web UI）

用浏览器打开 http://127.0.0.1:18789 就行，能聊天、管配置、查会话、监控状态。不需要额外装 Web 服务器，网关自己就搞定了。

3.2.2.命令行工具（CLI）

喜欢敲命令的人可以用命令行控制一切：

• openclaw gateway 启动网关
• openclaw agent 直接调用 Agent
• openclaw channels login 配对 WhatsApp/Signal
• openclaw message send 编程发消息
• openclaw doctor 跑健康检查
• openclaw onboard 引导式初始设置

3.2.3.macOS 菜单栏应用

用 Swift 写的原生 Mac 应用，可以放在在菜单栏里。可以一键启动/停止/重启网关，内置聊天界面，还支持语音唤醒。

3.2.4.手机端（Mobile）

iOS 和 Android 的 App 通过 WebSocket 连接到网关，不光能聊天，还能把手机的摄像头、录屏、定位等能力暴露给 Agent 使用，让你的手机变成 AI 的外挂硬件。

3.3.网关控制平台（Gateway Control Plane）

网关是整个系统的大脑中枢，所有消息和指令都经过它。

网关就像一个快递分拣中心，所有包裹（消息）进来后，由它检查收件人信息、分配到正确的分拣线（Agent），最后把回复发出去。

技术细节：

• 基于 Node.js 22+，使用 WebSocket 协议
• 默认只绑定到 127.0.0.1（本机地址），不对外暴露
• 所有 WebSocket 消息都有严格的格式校验，发送格式不对会被立刻拒绝
• 采用事件驱动而非轮询，客户端订阅事件，不用反复处理有没有新消息
• 所有可能产生副作用的操作都需要幂等键（Idempotency Key），防止重复执行

核心设计原则：

• 一台机器只跑一个网关（因为 WhatsApp 协议限制只能单设备）
• 协议全部有类型定义和校验
• 本地连接可以自动信任，远程连接需要验证

3.4.Agent

Agent 运行时每一轮对话做四件事：

步骤 1：确定会话（Session Resolution）

消息进来后，先搞清楚这条消息属于哪个会话：

• 你自己发的私聊 ： main 会话（权限最高）
• 别人通过某个平台发的私聊 ：dm:平台:ID 会话
• 群聊消息 ： group:平台:ID 会话

注意： 会话不只是个标签，它还是安全边界。不同类型的会话有不同的权限和沙箱规则。

步骤 2：组装上下文（Context Assembly）

确定会话后，运行时会组装 AI 需要的上下文信息：

• 从磁盘加载该会话的历史记录
• 读取工作空间里的配置文件，拼出系统提示词（System Prompt）
• 通过语义搜索从记忆库里拉取相关的历史对话

步骤 3：调用模型并执行工具（Execution Loop）

AI 模型开始回复时，Agent 会实时监控：

• 如果模型说”我要执行一个命令行命令”，Agent 拦截并执行（可能在 Docker 沙箱里）
• 如果模型说”我要打开浏览器抓个网页”，Agent 启动浏览器去抓
• 工具执行结果实时喂回给AI模型，模型接着往下做

步骤 4：保存状态

对话结束后，把所有消息、工具调用结果都存回磁盘。

四、系统提示词架构（System Prompt Architecture）

OpenClaw 如何把多个配置文件拼成一份完整的AI 执行计划？

OpenClaw 的系统提示词不是一个写死的文件，而是由多个来源组合拼装而成：

工作空间配置文件：

• AGENTS.md：核心指令，定义 Agent 能做什么、不能做什么（基线规则）
• SOUL.md：人格和语气指导，Agent 说话的风格（可选）
• TOOLS.md：用户写的工具使用备注（可选）

动态上下文（每轮对话实时组装）：

• 会话历史：最近的对话记录
• 技能文件（Skills）：特定任务的操作指南
• 记忆搜索结果：语义相关的历史对话

工具定义（自动生成）：

• 内置工具：命令行、浏览器、文件操作等
• 插件工具：通过扩展系统注册的自定义工具

这种可组合的设计意味着：你只需要编辑工作空间里的文件，就能改变 Agent 的行为、风格和能力，完全不用改源代码。

注意：OpenClaw 不会把所有技能全部塞进提示词。它会智能筛选，只注入当前这轮对话需要的技能，避免提示词太长导致 AI 表现下降。

五、部署

5.1.准备工作

在开始之前，请确认你的 Mac 满足以下条件：

• macOS Sonoma 或更新版本（推荐使用 Apple Silicon M1及以上芯片，性能会更好）。
• 流畅的网络环境，必要时需要梯子（部分依赖库需要从 GitHub 下载）。

官方网站：https://openclaw.ai/

对于新手小白来说，看到官网给出的四个安装方式到底有什么区别？

• One-liner：一键脚本安装，最简单、官方推荐（这也是放在第一页的原因）。它会自动检测系统并安装依赖。适合个人用户，想快速在 Mac/Linux 上体验完整功能。缺点是如果你对系统环境有洁癖，脚本方式侵入性太强，不方便后期更新维护。
• npm：全局安装方式，需要依赖Node.js包管理器安装，适合前端开发者或已熟悉 Node.js 的用户（有一定计算机门槛），通过它安装，不会弄乱你的开发环境。版本控制方便，更新更容易，本文选用此安装方式。
• Hackable：源码安装方式，可任意魔改，下载源代码到本地。适合想要修改核心逻辑、自己写复杂插件、或者给项目提 PR 的人。
• macOS：GUI 界面应用，这是一个 Mac 端应用，提供了一个菜单栏图标，原生体验并提供语音交互、快捷指令等原生 Mac 功能。但是它通常是为了配合 CLI（命令行版）使用的，而不是完全替代命令行，想用此应用还是需要先安装前三中任意一个。

经过上面的解释你应该很清楚各个安装方式的区别了，只是想试用OpenClaw 并且不想安装 Node 环境，试用结束重装系统也无所谓，那就一键部署选One-liner。如果想把它当主力工具，长期稳定使用，为了出问题好修、版本好管、系统干净，那就建议选 npm 安装。

5.2.npm安装

OpenClaw 依赖于 Node.js 环境。官方下载地址：https://nodejs.org/zh-cn/download

1.下载

然后点击macOS 安装程序（.pkg）下载安装包如果你更熟悉用Homebrew下载，那会更方便，官网下载可避免一些未知错误；

2.然后打开下载后的安装包，按照安装包的直接正常安装即可

3.安装完成，点击「关闭」即可

4. 打开「终端」，在终端内输入：

npm i -g openclaw

然后回车，输入开机密码后再回车；

5.如果出现如图错误，修改 Git 下载协议 （强制使用 HTTPS），复制下方代码到终端，回车执行即可解决；

错误如下：

在终端输入：

git config --global url."https://github.com/".insteadOf ssh://git@github.com/

在此输入安装：

npm i -g openclaw

如果不报错直接下一步即可，如果报错则安装下面进行，大概率还是网络问题，使用代理解决解决：

我上面代理端口是7897，所以设置如下：

①.清除旧的错误配置

unset HTTP_PROXY
unset HTTPS_PROXY
git config --global --unset http.proxy
git config --global --unset https.proxy

②.使用正确的端口 (7897) 重新设置

# 注意这里变成了 7897
export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
​
# Git 也要改
git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897
​
# 配置 npm 代理 (端口 7897)
npm config set proxy http://127.0.0.1:7897
npm config set https-proxy http://127.0.0.1:7897

③.关闭SSL检查

# 2. 关闭严格 SSL 检查 (防止代理证书报错)
npm config set strict-ssl false
​
# 3. 清除缓存 (防止缓存了错误的半截文件)
sudo npm cache clean --force

④. 验证连接

运行测试命令，这次应该能通了：

curl -I https://github.com

• 预期成功结果：返回 HTTP/2 200 或类似的成功头部信息。

⑤.开始安装

一旦 curl 成功，立即运行：

sudo npm i -g openclaw

出现如图界面表示安装成功：

6.启动 OpenClaw 的初始化向导，输入下方代码，然后回车；

openclaw onboard

7.这一步主要是提醒你，使用 OpenClaw 可能会有一些风险。请问你是否继续？按向左方向键 ←，选择 Yes，按 Enter 回车确认；

8.选择选择 QiuickStart（快速开始模式），回车；

9.这里是配置 AI 模型 API Key，OpenClaw 需要连接到大语言模型才能工作。Openclaw 比较费 token，国外模型成本较高，新版本已经支持KIMI K2.5 ，下面以使用本地ollama为例； 

列表倒数第二项有一个 Custom Provider（自定义提供商）！

10.输入ollama连接信息

选 Paste API key now

然后随便输入一个字符串按回车，比如：

ollama

然后选择：OpenAI-compatible

输入ollama中已经下载的模型名称，然后回车，如下：

 

现在看到的：

Verification successful.
Endpoint ID: custom-127-0-0-1-11434

这表示：

• ✅ 模型 qwen3.5:35b 已验证可用
• ✅ Ollama 服务连接正常
• ✅ 配置已保存，系统为你自动生成了一个唯一的 Endpoint ID（用于内部标识）

直接按 回车键（Enter） 确认这个 Endpoint ID！

 可选自定义名称，自定义一个简洁好记的别名（推荐）

11.接着你会看到选择聊天选择工具的选项。

这里你建议先「暂时跳过」，先在终端（Terminal）里把 OpenClaw 跑起来，确认它的 AI 大脑、文件读写权限都正常工作，后面再单独部署；

12.OpenClaw 的“Web 搜索”功能配置步骤，

 选项含义说明：

选项	说明	是否需要 API Key	推荐度
Brave Search	隐私友好，结构化结果好	✅ 需要（免费额度有限）	⭐⭐⭐⭐
Gemini (Google Search)	谷歌官方搜索，结果最全	✅ 需要（需 Google Cloud 账号）	⭐⭐⭐
Grok (xAI)	Elon Musk 旗下，实时性强	✅ 需要（仅限 X Premium 用户）	⭐⭐
Kimi (Moonshot)	中文优化好，适合国内用户	✅ 需要（月之暗面平台）	⭐⭐⭐⭐
Perplexity Search	学术/专业内容强	✅ 需要（有免费层）	⭐⭐⭐
Skip for now	暂时不启用	❌ 不需要	⭐⭐⭐⭐⭐（新手首选）

13.这里选择「Yes」，也可以暂不配置选择「No」，后面通过UI界面再进行配置；

14.关于技能，你可以先跳过选择此步骤，或者使用空格键您需要的技能，可多选；

这个界面是 OpenClaw 的“技能依赖安装”步骤，意思是：

🤖 OpenClaw 想让它的 AI 助手具备一些“超能力”（比如访问你的备忘录、GitHub、密码管理器等），但这些功能需要额外安装一些小工具或库（叫 “skill dependencies”）。

直接选第一个跳过，选择第一个按空格，然后回车，后续在安装：

15.这里可以配置备用 API，如果不想配置就都选「No」即可；

16.OpenClaw 的“Hooks（钩子）”，可以全选：

选项说明：

选项	功能简述	是否推荐新手启用
Skip for now	跳过，不启用任何 hooks	✅ 强烈推荐！先体验基础功能
boot-md	启动时自动生成 Markdown 格式的会话摘要	⭐ 可选，适合喜欢整理笔记的人
bootstrap-extra-files	启动时加载额外配置文件	❌ 高级用户用
command-logger	记录你发出的所有命令到日志文件	⭐ 有用，但非必需
session-memory	自动保存/恢复对话上下文（类似“记忆”功能）	⭐⭐ 很实用，但可能增加复杂度

这里全选：

17.OpenClaw 安装流程的最后一步 —— “如何启动你的 AI 助手（bot）

OpenClaw 启动方式（How do you want to hatch your bot?）三个选项的详细对比表格：

选项名称	中文含义	交互界面形式	是否需要浏览器	适合人群	优点	缺点
Hatch in TUI (recommended)	在终端内启动 (推荐)	纯文本界面 (类似命令行聊天)	❌ 不需要	• 开发者 • 命令行爱好者 • 追求极速响应者	• 启动最快，无额外开销 • 方便直接复制/粘贴代码 • 无需配置浏览器环境	• 无图形按钮/菜单 • 无法直观管理历史对话列表 • 界面较简陋
Open the Web UI	打开网页界面	图形化网页 (类似 ChatGPT 官网)	✅ 需要	• 普通用户 • 喜欢可视化操作者 • 需要演示/分享者	• 界面美观，操作直观 • 支持侧边栏历史对话管理 • 方便调整设置和插件	• 需占用浏览器资源 • 首次加载可能稍慢 • 依赖本地服务器端口 (8080)
Do this later	稍后手动启动	无界面 (仅完成配置)	❌ 不需要	• 高级用户 • 脚本自动化者 • 暂时不想聊天者	• 完全掌控启动时机 • 可编写脚本自定义启动 • 不干扰当前工作流	• 新手容易“找不到入口” • 需记忆命令 (openclaw chat 等) • 无法立即体验功能

 配置完成，选择「Open the web UI」，打开可视化页面；

5.3.技能安装

Skills 是 OpenClaw 的插件系统或能力扩展包。
每一个 Skill 都是一段预定义好的代码逻辑，它告诉 AI：“当用户想要做 X 事情时，请调用这个工具/函数来完成。”

核心特点：

1. 即插即用：通过一条命令安装，AI 立刻获得新能力。
2. 社区驱动：全球开发者贡献了数千个技能（截至 2026 年已有 3000+），涵盖各种场景。
3. 安全可控：技能是版本化、可审计的，你可以选择只安装可信的技能。
4. 自动触发：安装后，AI 会根据你的自然语言指令，自动判断是否需要调用某个技能，无需手动切换模式。

5.3.1.Homebrew 安装脚本

Homebrew 是 macOS（苹果电脑）上最流行、最好用的包管理器（Package Manager），openclaw利用其可以下载技能（Skills）

# 国内镜像安装
/bin/bash -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

在终端光标闪烁的地方，直接按下键盘上的 回车键。

安装后查看版本：

brew -v

5.3.2.安装Skills

点击技能，根据需要下载如果网络问题导致下载失败，可以自己手动下载，见招拆招。