OpenClaw-Mac安装完整指南本文面向非程序员用户，详细记录了在一台全新 Mac 电脑上从零开始安装 OpenCl

OpenClaw 在 Mac 上的完整安装指南

本文面向非程序员用户，详细记录了在一台全新 Mac 电脑上从零开始安装 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 拉取依赖，所以必须先装好这个工具包。

操作步骤

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

xcode-select --install

系统会弹出一个对话框，点击"安装"按钮
等待下载和安装完成（可能需要 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 分钟，你会看到：

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

启动配置向导

在终端输入：

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 代理）：

选择 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 即可。

4. 选择聊天渠道

OpenClaw 支持多种聊天平台：

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

本次配置示例（飞书）：

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

5. 配置飞书凭证

系统会提示你需要：

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

详细步骤见下一章节。

配置完成后：

输入 Feishu App ID
输入 Feishu App Secret
系统会测试连接，成功后显示 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。

第五步：配置飞书机器人

飞书开放平台配置

参考资料： www.volcengine.com/docs/6396/2…

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

创建飞书机器人

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

添加机器人

开通权限

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

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

{
  "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.

测试对话

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

你好

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

常见问题排查

问题 1：机器人不回复消息

可能原因：

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

排查步骤：

检查 Gateway 状态：

openclaw status

查看日志：

openclaw logs

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

openclaw config get channels.feishu.groupPolicy

如果是 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 调用失败

可能原因：

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

排查步骤：

检查配置：

openclaw config get models

重新配置模型：

openclaw configure

问题 5：如何重启 Gateway

# 停止
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

附录：目录结构

OpenClaw 的配置和数据存储在：

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

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

OpenClaw-Mac安装完整指南

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

总结

完整流程回顾

关键命令速查

进阶使用

相关资源

附录：目录结构