OpenClaw（Mac版）安装与飞书对接完整教程

本文档基于Mac系统（Intel/M1/M2/M3通用），完整记录OpenClaw安装、配置到飞书对接的全流程，所有选项均为「新手友好+实测可用」版本，适配国内飞书环境。

一、环境准备：升级Python 3.11（Mac）

1. 为什么升级

OpenClaw要求Python版本≥3.11，Mac默认Python 3.9需升级，且不建议直接升级系统Python（会导致macOS核心工具异常）。

2. 推荐方案：Homebrew安装Python 3.11

# 1. 更新Homebrew（无Homebrew先执行：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"）
brew update

# 2. 安装Python 3.11
brew install python@3.11

# 3. 配置Python 3.11为默认（M芯片/Intel通用）
echo 'export PATH="/opt/homebrew/opt/python@3.11/bin:$PATH"' >> ~/.zshrc
echo 'alias python3="/opt/homebrew/opt/python@3.11/bin/python3.11"' >> ~/.zshrc
source ~/.zshrc

# 4. 验证版本
python3 --version # 输出Python 3.11.x即成功

关键说明

• 不建议直接升级系统Python：会导致xcode-select等macOS核心工具异常，Homebrew安装为独立环境，完全隔离；
• 若用Conda：可选conda create -n openclaw_env python=3.11创建专属环境，激活后使用。

二、安装OpenClaw核心程序

1. 执行官方安装脚本

curl -fsSL https://openclaw.ai/install.sh | bash

2. 安装过程关键说明

安装阶段	现象	处理方式
Node.js未找到	脚本自动通过Homebrew安装Node.js 22	无需操作，等待安装完成
npm install失败	权限不足/网络问题	手动执行：sudo npm install -g openclaw@latest
提示Node路径配置	输出echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc	执行该命令并source ~/.zshrc

3. 验证OpenClaw安装

openclaw --version # 输出版本号即安装成功

三、OpenClaw首次启动与安全引导

1. 启动OpenClaw

openclaw

2. 安全风险告知界面

配置项	解释	推荐选项	操作
安全警告	OpenClaw为beta版，个人使用默认安全，多用户需加固；可读取文件/执行命令，存在误操作风险	Yes（确认理解风险）	方向键←/→切换到● Yes，按回车

3. 新手安全加固（可选）

# 深度安全审计
openclaw security audit --deep
# 自动修复安全问题
openclaw security audit --fix

四、首次配置模式选择

配置项	解释	推荐选项	操作
Onboarding mode	QuickStart：快速启动，后续补配置；Manual：全手动配置（新手易卡壳）	QuickStart	已默认选中● QuickStart，按回车

五、LLM模型对接（阿里云/Kimi）

对接AI大模型（OpenClaw无内置AI能力，需对接外部LLM），以下为阿里云通义千问（兼容Kimi）配置：

配置项	解释	推荐值/选项	操作
Model/auth provider	选择LLM服务商，自定义提供商适配阿里云/Kimi	Custom Provider	无需修改，按回车
API Base URL	LLM接口根地址	https://coding.dashscope.aliyuncs.com/v1	无需修改，按回车
How do you want to provide this API key?	API密钥提供方式	Paste API key now	无需修改，按回车
API Key	阿里云/Kimi的API密钥（身份认证）	你的sk-sp-xxxx格式密钥	粘贴后按回车（注意保密）
Endpoint compatibility	接口协议兼容类型，阿里云支持OpenAI兼容模式	● OpenAI-compatible	无需修改，按回车
Model ID	具体调用的LLM模型	kimi-k2.5（或qwen-turbo）	输入后按回车
Endpoint ID	OpenClaw自动生成的接口唯一标识	默认值	无需修改，按回车
Model alias	模型简化别名（可选）	跳过（不填）	直接按回车

六、飞书渠道配置

配置项	解释	推荐选项	操作
Select channel (QuickStart)	选择OpenClaw对接的聊天软件	● Feishu/Lark (飞书)	方向键↑/↓切换到飞书，按回车

七、飞书插件与凭证配置

1. 飞书插件安装方式

配置项	解释	推荐选项	操作
Install Feishu plugin?	飞书插件来源：npm下载/本地自带/跳过	● Use local plugin path	已默认选中，按回车（本地插件与OpenClaw版本匹配）

2. 飞书App Secret提供方式

配置项	解释	推荐选项	操作
How do you want to provide this App Secret?	飞书App Secret（机器人密码）存储方式	● Enter App Secret	已默认选中，按回车
App Secret输入框	飞书开发者后台的App Secret	你的飞书App Secret	粘贴后按回车（保密！）

八、飞书连接与群聊策略配置

1. 飞书基础连接配置

配置项	解释	推荐选项	操作
Feishu connection mode	飞书机器人连接方式	WebSocket (default)	无需修改，按回车
Which Feishu domain?	飞书域名（国内/国际版）	Feishu (feishu.cn) - China	无需修改，按回车

2. 飞书群聊策略配置

配置项	解释	推荐选项	操作
Group chat policy	群聊回复策略：白名单/全开放/禁用	● Allowlist - only respond in specific groups	已默认选中，按回车
Group chat allowlist (chat_ids)	允许回复的飞书群ID（多个用英文逗号分隔）	跳过（后续配置）	直接按回车（无需填示例值）

九、高级功能配置（新手跳过）

1. 联网搜索配置

配置项	解释	推荐选项	操作
Search provider	AI联网搜索服务商（需额外API密钥）	● Skip for now	方向键↓切换到Skip for now，按回车

2. 技能配置

配置项	解释	推荐选项	操作
Configure skills now?	配置AI技能（文件读取/命令执行等）	● No	方向键→切换到No，按回车

3. 钩子（hooks）配置

配置项	解释	推荐选项	操作
Enable hooks?	启动辅助插件（日志/上下文记忆等）	● Skip for now	空格选中Skip for now，按回车

十、启动机器人与飞书授权

1. 机器人启动方式

配置项	解释	推荐选项	操作
How do you want to hatch your bot?	启动方式：终端(TUI)/网页UI/稍后启动	● Hatch in TUI	已默认选中，按回车（终端启动最稳定）

2. 飞书授权（核心步骤）

现象

飞书发送消息后显示：

OpenClaw: access not configured.
Your Feishu user id: ou_d7e1b6a12dccbdff2d104fc67bb5ba24
Pairing code: ZHG5B3YD
Ask the bot owner to approve with:
openclaw pairing approve feishu ZHG5B3YD

授权操作

在终端执行配对命令（替换为你的配对码）：

openclaw pairing approve feishu ZHG5B3YD

验证

授权成功后，飞书重新发送消息，即可收到OpenClaw的AI回复。

十一、验证使用

1. 飞书私聊发送任意消息（如“你好”）；
2. 收到OpenClaw的AI回复，即全流程配置完成。

关键注意事项

1. 密钥保密：API Key、App Secret等凭证切勿泄露，避免被盗用；
2. 版本兼容：Node.js 22、Python 3.11为实测兼容版本；
3. 安全加固：个人使用无需开放公网端口，仅保留飞书私聊/指定群聊回复；
4. 后续配置：如需修改参数，执行openclaw configure重新进入配置界面。