在 macOS 系统上从零开始安装 OpenClaw 开源 AI 聊天机器人框架并配置飞书机器人的完整流程。内容涵盖前置环境准备（Xcode Command Line Tools、Node.js）、OpenClaw 的全局安装与验证、交互式配置向导的使用（包括 AI 模型选择、飞书凭证获取、权限配置及事件回调设置）、以及最终的配对批准与功能测试。同时提供了常见问题排查指南和关键命令速查，帮助用户顺利完成部署。
本文面向非程序员用户，详细记录了在一台全新 Mac 电脑上从零开始安装 OpenClaw 并配置飞书机器人的完整流程。
OpenClaw 是一个开源的 AI 聊天机器人框架，可以连接多种聊天平台（WhatsApp、Telegram、飞书、Discord 等），让你在这些平台上拥有一个由 AI 驱动的智能助手。
Mac 上的很多开发工具（包括 git）都依赖 Xcode Command Line Tools。OpenClaw 在安装过程中需要使用 git 拉取依赖，所以必须先装好这个工具包。
xcode-select --install
安装完成后，在终端输入：
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 security audit操作：选择 Yes 继续。
会提示选择配置模式：
操作：选择 QuickStart。
这一步需要配置 OpenClaw 使用的 AI 后端。
选项说明：
本次配置示例（使用 MiraclePlus 代理）：
Custom Providerhttps://openai-proxy.miracleplus.comPaste API key nowAnthropic-compatibleclaude-opus-4-6Verification successful.提示：如果你使用 OpenAI 官方 API，选择 OpenAI 并输入你的 API key 即可。
OpenClaw 支持多种聊天平台：
本次配置示例（飞书）：
Feishu/Lark (飞书)Download from npm (@openclaw/feishu)系统会提示你需要：
详细步骤见下一章节。
配置完成后：
Connected as ou_xxxxx操作：根据你的飞书版本选择（国内用户选第一个）。
操作：
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。
参考官方飞书集成教程进行配置。
在飞书开发者平台创建企业自建应用。
在左侧目录树选择'开发配置 > 权限管理'，单击'批量导入/导出权限'按钮。
在'导入'页签中，将如下权限替换原有示例，单击'下一步，确认新增权限'按钮。
{ "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.
在飞书里给机器人发送消息，比如：
你好
如果机器人正常回复，说明一切配置成功！
可能原因：
排查步骤：
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。
可能原因：
排查步骤：
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
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>
http://127.0.0.1:18789/openclaw skillsopenclaw security audit --deepsudo npm install -g openclaw@latestOpenClaw 的配置和数据存储在：
~/.openclaw/
├── openclaw.json # 主配置文件
├── workspace/ # 工作区（AI 可访问的文件）
├── agents/
│ └── main/
│ └── sessions/ # 会话记录
├── logs/
│ └── gateway.log # Gateway 日志
└── extensions/
└── feishu/ # 飞书插件
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online