OpenClaw Mac 安装与配置飞书机器人完整指南

重要说明：

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

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。

第五步：配置飞书机器人

飞书开放平台配置

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

创建飞书机器人

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

开通权限

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

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

{ "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：机器人不回复消息

可能原因：

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

排查步骤：

1. 检查 Gateway 状态：

openclaw status

2. 查看日志：

openclaw logs

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

openclaw config get channels.feishu.groupPolicy

4. 如果是 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 错误

排查步骤：

1. 检查配置：

openclaw config get models

2. 重新配置模型：

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