OpenClaw 在 Mac 上的完整安装指南

目录

• 前置说明
• 什么是 OpenClaw？
• 安装环境
• 第一步：安装 Xcode  Command Line Tools
• 为什么需要这一步？
• 操作步骤
• 验证安装
• 可能遇到的问题
• 第二步：验证 Node.js  环境
• 检查 Node.js 版本
• 检查 npm 版本
• 如果没有 Node.js
• 第三步：安装 OpenClaw
• 全局安装 OpenClaw
• 安装过程
• 验证安装
• 常见错误处理
• 第四步：配置 OpenClaw
• 启动配置向导
• 配置流程详解
• 1. 安全提示
• 2. 选择配置模式
• 3. 配置 AI 模型
• 4. 选择聊天渠道
• 5. 配置飞书凭证
• 6. 选择飞书域名
• 7. 配置群聊策略
• 8. 技能配置
• 9. Hooks 配置
• 10. 安装 Gateway 服务
• 11. 查看状态
• 12. 启动 TUI（终端界面）
• 第五步：配置飞书机器人
• 飞书开放平台配置
• 创建飞书机器人
• 开通权限
• 配置事件与回调
• 发布机器人
• 第六步：批准配对并测试
• 配对机制说明
• 批准配对
• 测试对话
• 常见问题排查
• 问题 1：机器人不回复消息
• 问题 2：插件重复警告
• 问题 3：Gateway 启动失败
• 问题 4：API 调用失败
• 问题 5：如何重启 Gateway
• 总结
• 完整流程回顾
• 关键命令速查
• 进阶使用
• 相关资源
• 附录：目录结构

OpenClaw（前身为 Clawdbot/Moltbot）是一款开源、本地优先、可执行任务的 AI 自动化代理引擎，遵循 MIT 协议。它以自然语言指令为驱动，在本地或私有云环境中完成文件操作、流程编排、浏览器自动化、多 IM 平台交互等任务，实现从 “对话式建议” 到 “自动化执行” 的跨越，是面向个人与企业的自托管式 AI 数字员工。

• 操作系统：macOS（本文基于 macOS 11+）
• 前置条件：已安装 Node.js 和 npm（如果没有，需要先从 nodejs.org 下载安装）
• 网络要求：需要稳定的网络连接
• 时间预估：首次安装约 15-30 分钟

Mac 上的很多开发工具（包括 git）都依赖 Xcode Command Line Tools。OpenClaw 在安装过程中需要使用 git 拉取依赖，所以必须先装好这个工具包。

• 打开"终端"应用（在"应用程序" → "实用工具"里，或用 Spotlight 搜索"终端"）
• 在终端中输入以下命令并回车：

xcode-select --install

运行项目并下载源码

• 系统会弹出一个对话框，点击"安装"按钮
• 等待下载和安装完成（可能需要 5-15 分钟，取决于网速）

安装完成后，在终端输入：

git --version

运行项目并下载源码

如果看到类 似 git version 2.x.x 的输出，说明安装成功。

问题 1：提示"Command line tools are already installed"

这说明你的 Mac 已经装过了，可以直接跳到下一步。

问题 2：下载速度很慢

这是正常现象，耐心等待即可。如果实在太慢，可以尝试切换网络或稍后再试。

在终端输入：

node --version

运行项目并下载源码

应该看到类似 v24.14.0 的输出（版本号可能不同，但应该是 v18 或更高）。

在终端输入：

npm --version

运行项目并下载源码

应该看到类似 11.9.0 的输出。

如果上述命令报错"command not found"，说明你的 Mac 还没装 Node.js。请访问 nodejs.org 下载 LTS 版本并安装。

在终端输入以下命令：

sudo npm install -g openclaw@latest

运行项目并下载源码

重要说明：

• sudo 会要求你输入 Mac 的登录密码
• 输入密码时屏幕不会显示任何字符（这是正常的安全机制）
• 输完密码直接按回车即可

安装过程可能需要 2-5 分钟，你会看到：

npm warn deprecated …（一些过时依赖的警告，可以忽略）

…

added 655 packages in 2m

运行项目并下载源码

看到 added XXX packages 就说明安装成功了。

在终端输入：

openclaw --version

运行项目并下载源码

应该看到类似 🦞 OpenClaw 2026.3.1 (2a8ac97) 的输出。

错误 1：EACCES: permission denied

原因：没有使用 sudo 导致权限不足。

解决：在命令前加 sudo：

sudo npm install -g openclaw@latest

运行项目并下载源码

错误 2：xcode-select: note: No developer tools were found

原因：Xcode Command Line Tools 没装好。

解决：回到第一步重新安装。

错误 3：git command not found

原因：Xcode Command Line Tools 安装不完整。

解决：

xcode-select --install

运行项目并下载源码

在终端输入：

openclaw onboard

运行项目并下载源码

这会启动一个交互式配置向导，按照提示一步步操作即可。

首先会看到一段安全警告，大意是：

• OpenClaw 默认是个人使用的工具
• 如果多人共用或开放给陌生人，需要做安全加固
• 建议定期运行 openclaw security audit

操作：选择 Yes 继续。

会提示选择配置模式：

• QuickStart（快速开始）：推荐新手使用
• Custom（自定义）：适合有经验的用户

操作：选择 QuickStart。

这一步需要配置 OpenClaw 使用的 AI 后端。

选项说明：

• OpenAI：使用 OpenAI 官方 API（需要 OpenAI API key）
• Anthropic：使用 Claude API（需要 Anthropic API key）
• Custom Provider：使用自定义 API 端点（比如代理服务）

本次配置示例（使用 MiraclePlus 代理）：

• 选择 Custom Provider
• 输入 API Base URL：https://openai-proxy.miracleplus.com
• 选择如何提供 API Key：Paste API key now
• 输入你的 API Key（输入时不会显示，这是正常的）
• 选择兼容性：Anthropic-compatible
• 输入模型 ID：claude-opus-4-6
• 系统会验证配置，成功后显示 Verification successful.

提示：如果你使用 OpenAI 官方 API，选择 OpenAI 并输入你的 API key 即可。

OpenClaw 支持多种聊天平台：

• Telegram：最简单，只需一个 Bot Token
• WhatsApp：需要独立手机号
• Discord：需要 Bot Token
• 飞书/Lark：需要企业应用配置
• Slack、Signal、iMessage 等

本次配置示例（飞书）：

• 选择 Feishu/Lark (飞书)
• 系统会提示安装飞书插件，选择 Download from npm (@openclaw/feishu)
• 等待插件下载和安装完成

系统会提示你需要：

• 访问飞书开放平台（open.feishu.cn）
• 创建自建应用
• 获取 App ID 和 App Secret
• 启用必要权限
• 发布应用或添加到测试群

详细步骤见下一章节。

配置完成后：

• 输入 Feishu App ID
• 输入 Feishu App Secret
• 系统会测试连接，成功后显示 Connected as ou_xxxxx

• Feishu (feishu.cn) – China：国内版飞书
• Lark (larksuite.com) – International：国际版 Lark

操作：根据你的飞书版本选择（国内用户选第一个）。

• Open：所有群都能使用机器人
• Allowlist：只在指定群里响应

操作：

• 如果选 Allowlist，需要输入群 chat_id（可以先留空，后续再配置）
• 如果选 Open，所有群都能用

建议：个人使用选 Open；公司环境选 Allowlist 更安全。

系统会显示可用的技能（Skills）数量。

操作：选择 No（跳过，后续可以按需配置）。

Hooks 可以在特定事件发生时自动执行操作。

操作：选择 Skip for now（跳过）。

Gateway 是 OpenClaw 的核心服务，负责消息路由和 AI 处理。

系统会自动安装并启动 Gateway 服务：

Installing Gateway service...
Installed LaunchAgent: /Users/xxx/Library/LaunchAgents/ai.openclaw.gateway.plist
Logs: /Users/xxx/.openclaw/logs/gateway.log
Gateway service installed.

运行项目并下载源码

配置完成后会显示：

Feishu: ok
Agents: main (default)
Gateway WS: ws://127.0.0.1:18789
Web UI: http://127.0.0.1:18789/

运行项目并下载源码

最后会提示是否启动 TUI（Terminal User Interface）：

操作：选择 Hatch in TUI (recommended)

这会打开一个终端聊天界面，你可以直接和 AI 对话，完成机器人的"初始化"（设置名字、风格等）。

示例对话：

Wake up, my friend!
> 你好
你好！我刚刚启动。看起来这是一个全新的工作空间...

运行项目并下载源码

按 Ctrl+C 可以退出 TUI。

参考资料： https://www.volcengine.com/docs/6396/2189942?lang=zh

参考官方飞书集成教程进行配置

在飞书开发者平台创建企业自建应用。

添加机器人

在左侧目录树选择“开发配置 > 权限管理”，单击“批量导入/导出权限”按钮。

在“导入”页签中，将如下权限替换原有示例，单击“下一步，确认新增权限”按钮。

{
  "scopes": {
    "tenant": [
      "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"
    ],
    "user": [
      "contact:user.employee_id:readonly"
    ]
  }
}

 

点击申请开通

可以看到已获取相应权限

进入创建的飞书应用详情页，并在左侧目录树选择“开发配置 > 事件与回调”。选择“事件配置”页签，单击“订阅方式”旁的编辑按钮。

选择“使用 长连接 接收事件”，并单击“保存”按钮。

在“已添加事件”区域，单击“添加事件”按钮。

在添加事件对话框中，选择“应用身份订阅”页签，并勾选“接收消息”及其它需要订阅的事件，单击“确认添加”按钮。

可以看到当前具备了接收消息权限。

选择“回调配置”页签，单击“订阅方式”旁的编辑按钮。

选择“使用 长连接 接收回调”，并单击“保存”按钮。

复制这里的APP  ID和App Secret，用于填写到OpenClaw的飞书集成配置中。

单击顶部的“创建版本”按钮，填写信息，发布应用。

成功发布修改。将该飞书机器人的APP ID和App Secret，填写到OpenClaw的飞书集成配置中。

OpenClaw 默认使用"配对码"机制保护隐私：

• 当有人第一次给机器人发消息时，机器人会生成一个配对码
• 你需要在终端手动批准这个配对码
• 批准后，该用户才能正常使用机器人

当有人（包括你自己）第一次给飞书机器人发消息时，在终端输入：

openclaw pairing approve feishu <配对码>

运行项目并下载源码

示例：

openclaw pairing approve feishu XXXXXXX

运行项目并下载源码

成功后会显示：

Approved feishu sender ou_xxxxx.

运行项目并下载源码

在飞书里给机器人发送消息，比如：

你好

运行项目并下载源码

如果机器人正常回复，说明一切配置成功！

可能原因：

• Gateway 服务没有运行
• 配对没有批准
• 群聊策略配置错误

排查步骤：

检查 Gateway 状态：

openclaw status

运行项目并下载源码

查看日志：

openclaw logs

运行项目并下载源码

如果是群聊不回复，检查群聊策略：

openclaw config get channels.feishu.groupPolicy

运行项目并下载源码

如果是 allowlist 但白名单为空，改为 open：

openclaw config set channels.feishu.groupPolicy "open"

运行项目并下载源码

如果看到：

plugin feishu: duplicate plugin id detected

运行项目并下载源码

这是配置文件中飞书插件被注册了两次。虽然不影响使用，但可以清理：

openclaw config get plugins.entries

运行项目并下载源码

查看配置，手动编辑 ~/.openclaw/openclaw.json 删除重复项。

可能原因：端口被占用

解决方法：

openclaw gateway --force

运行项目并下载源码

这会强制杀掉占用端口的进程并重启 Gateway。

可能原因：

• API Key 错误
• 网络问题
• 模型 ID 错误

排查步骤：

检查配置：

openclaw config get models

运行项目并下载源码

重新配置模型：

openclaw configure

运行项目并下载源码

# 停止
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 启动
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

运行项目并下载源码

或者直接：

openclaw gateway --force

运行项目并下载源码

• ✅ 安装 Xcode Command Line Tools
• ✅ 验证 Node.js 环境
• ✅ 全局安装 OpenClaw
• ✅ 运行 openclaw onboard 配置
• ✅ 配置飞书开放平台
• ✅ 批准配对码
• ✅ 测试对话

# 安装
sudo npm install -g openclaw@latest
# 配置
openclaw onboard
# 查看状态
openclaw status
# 批准配对
openclaw pairing approve feishu <配对码>
# 查看日志
openclaw logs
# 重启 Gateway
openclaw gateway --force
# 配置管理
openclaw config get <key>
openclaw config set <key> <value>

• Web 控制面板：访问 http://127.0.0.1:18789/
• 技能管理：openclaw skills
• 安全审计：openclaw security audit --deep
• 更新 OpenClaw：sudo npm install -g openclaw@latest

• 官方文档：https://docs.openclaw.ai/
• GitHub 仓库：https://github.com/openclaw/openclaw
• 飞书开放平台：https://open.feishu.cn/

OpenClaw 的配置和数据存储在：

~/.openclaw/
├── openclaw.json          # 主配置文件
├── workspace/             # 工作区（AI 可访问的文件）
├── agents/
│   └── main/
│       └── sessions/      # 会话记录
├── logs/
│   └── gateway.log        # Gateway 日志
└── extensions/
    └── feishu/            # 飞书插件

到此这篇关于OpenClaw 在 Mac 上的完整安装指南的文章就介绍到这了,更多相关OpenClaw安装完整指南内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！