OpenClaw 在 Mac 上的完整安装指南

本文面向非程序员用户，详细记录了在一台全新 Mac 电脑上从零开始安装 OpenClaw 并配置飞书机器人的完整流程。

目录

• 前置说明
• 第一步：安装 Xcode Command Line Tools
• 第二步：验证 Node.js 环境
• 第三步：安装 OpenClaw
• 第四步：配置 OpenClaw
• 第五步：配置飞书机器人
• 第六步：批准配对并测试
• 常见问题排查
• 总结

前置说明

什么是 OpenClaw？

OpenClaw 是一个开源的 AI 聊天机器人框架，可以连接多种聊天平台（WhatsApp、Telegram、飞书、Discord 等），让你在这些平台上拥有一个由 AI 驱动的智能助手。

安装环境

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

第一步：安装 Xcode Command Line Tools

为什么需要这一步？

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

操作步骤

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

xcode-select --install

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

验证安装

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

git --version

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

可能遇到的问题问题 1：提示”Command line tools are already installed”

这说明你的 Mac 已经装过了，可以直接跳到下一步。问题 2：下载速度很慢

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

第二步：验证 Node.js 环境

检查 Node.js 版本

在终端输入：

node --version

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

检查 npm 版本

在终端输入：

npm --version

应该看到类似 11.9.0 的输出。

如果没有 Node.js

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

第三步：安装 OpenClaw

全局安装 OpenClaw

在终端输入以下命令：

sudo npm install -g openclaw@latest
```**重要说明**：

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

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

```plain
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 安装不完整。**解决**：

```plain
xcode-select --install

第四步：配置 OpenClaw

启动配置向导

在终端输入：

openclaw onboard

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

配置流程详解

1. 安全提示

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

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

2. 选择配置模式

会提示选择配置模式：

+QuickStart（快速开始）：推荐新手使用 +Custom（自定义）：适合有经验的用户操作：选择 QuickStart。

3. 配置 AI 模型

这一步需要配置 OpenClaw 使用的 AI 后端。选项说明：

+OpenAI：使用 OpenAI 官方 API（需要 OpenAI API key） +Anthropic：使用 Claude API（需要 Anthropic API key） +Custom Provider：使用自定义 API 端点（比如代理服务）本次配置示例（使用 MiraclePlus 代理）：

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

4. 选择聊天渠道

OpenClaw 支持多种聊天平台：

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

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

5. 配置飞书凭证

系统会提示你需要：

1. 访问飞书开放平台（open.feishu.cn）
2. 创建自建应用
3. 获取 App ID 和 App Secret
4. 启用必要权限
5. 发布应用或添加到测试群详细步骤见下一章节。

配置完成后：

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

6. 选择飞书域名

+Feishu (feishu.cn) - China：国内版飞书 +Lark (larksuite.com) - International：国际版 Lark操作：根据你的飞书版本选择（国内用户选第一个）。

7. 配置群聊策略

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

• 如果选 Allowlist，需要输入群 chat_id（可以先留空，后续再配置）
• 如果选 Open，所有群都能用建议：个人使用选 Open；公司环境选 Allowlist 更安全。

8. 技能配置

系统会显示可用的技能（Skills）数量。操作：选择 No（跳过，后续可以按需配置）。

9. Hooks 配置

Hooks 可以在特定事件发生时自动执行操作。操作：选择 Skip for now（跳过）。

10. 安装 Gateway 服务

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.

11. 查看状态

配置完成后会显示：

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

12. 启动 TUI（终端界面）

最后会提示是否启动 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 <配对码>
```**示例**：

```plain
openclaw pairing approve feishu XXXXXXX

成功后会显示：

Approved feishu sender ou_xxxxx.

测试对话

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

你好

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

常见问题排查

问题 1：机器人不回复消息可能原因：

1. Gateway 服务没有运行

2. 配对没有批准

3. 群聊策略配置错误排查步骤：

4. 检查 Gateway 状态：

openclaw status

1. 查看日志：

openclaw logs

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

openclaw config get channels.feishu.groupPolicy

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

openclaw config set channels.feishu.groupPolicy "open"

问题 2：插件重复警告

如果看到：

plugin feishu: duplicate plugin id detected

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

openclaw config get plugins.entries

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

问题 3：Gateway 启动失败可能原因：端口被占用解决方法：

openclaw gateway --force

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

问题 4：API 调用失败可能原因：

1. API Key 错误

2. 网络问题

3. 模型 ID 错误排查步骤：

4. 检查配置：

openclaw config get models

1. 重新配置模型：

openclaw configure

问题 5：如何重启 Gateway

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

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

或者直接：

openclaw gateway --force

总结

完整流程回顾

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

关键命令速查

# 安装
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/            # 飞书插件

---文档版本：v1.0更新日期：2026-03-03适用版本：OpenClaw 2026.3.1+