一、环境准备
1.1 安装 Homebrew(可选)
如果你还没有安装 Homebrew,打开终端执行:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
介绍在 macOS 系统下从零搭建 OpenClaw 智能体框架的完整流程。主要步骤包括安装 Node.js 环境、克隆源码并配置依赖;接入阿里云百炼平台的千问模型作为核心大脑;创建飞书企业自建应用并配置长连接网关以实现消息收发。最后通过配对码验证机器人状态,解决常见安装及配置问题,确保服务正常运行。
如果你还没有安装 Homebrew,打开终端执行:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
OpenClaw 需要 Node.js,建议使用 nvm 管理版本,并安装 LTS 版本。
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重新加载配置
source ~/.zshrc
# 安装 Node.js v22 LTS
nvm install 22
nvm use 22
nvm alias default 22
# 设为默认
# 验证
node -v
npm -v
可能的问题:
nvm: command not found解决:重新打开终端,或执行source ~/.zshrc。
xcode-select --install
如果已安装,会提示'已经安装'。
推荐使用本地源码安装(避免全局权限问题,方便调试)。
有两种方式:
~/openclaw。git clone https://github.com/openclaw/openclaw.git
cd ~/openclaw
npm install
可能的问题:网络慢或失败 解决:设置 npm 国内镜像
npm config set registry https://registry.npmmirror.com
npm install
如果你想在任何目录直接使用 openclaw 命令:
npm link
之后就可以直接输入 openclaw 了。
openclaw --version
应显示版本号(如 2026.3.3)。
OpenClaw 需要一个大模型作为'大脑'。我们以阿里云百炼平台的千问模型为例。
sk-xxxx。根据你的地域选择:
https://dashscope.aliyuncs.com/compatible-mode/v1https://dashscope-intl.aliyuncs.com/compatible-mode/v1https://dashscope-us.aliyuncs.com/compatible-mode/v1执行以下命令,将 sk-xxxx 替换为你的真实 API Key,并根据地域修改 baseUrl。
# 一次性设置整个 provider(注意 JSON 格式)
openclaw config set models.providers.bailian --json '{ "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-你的API密钥", "api": "openai-completions", "models": [ { "id": "qwen3-max-2026-01-23", "name": "qwen3-max", "reasoning": false, "input": ["text"], "contextWindow": 258000, "maxTokens": 65536 } ] }'
# 设置模型合并模式
openclaw config set models.mode "merge"
# 设置默认代理使用的模型
openclaw config set agents.defaults.model.primary "bailian/qwen3-max-2026-01-23"
验证配置:
openclaw config get models.providers.bailian
可能的问题:
Error: Config validation failed原因:配置必须一次性提供完整对象,不能分步设置。请确保使用上面的--json完整命令。
飞书作为消息收发渠道,需要先在飞书开放平台创建应用,然后在 OpenClaw 中配置。
openclaw plugins install @openclaw/feishu
检查插件状态:
openclaw plugins list | grep feishu
应显示 loaded。
# 启用飞书频道
openclaw config set channels.feishu.enabled true --json
# 设置 App ID 和 Secret(替换为你的真实值)
openclaw config set channels.feishu.appId "cli_你的 AppID"
openclaw config set channels.feishu.appSecret "你的 AppSecret"
验证:
openclaw config get channels.feishu
必须遵守顺序:先启动网关,再去飞书后台保存长连接。
openclaw gateway
保持此终端窗口打开,观察日志。当看到类似以下信息时,表示飞书插件已成功连接:
[feishu] successfully obtained token
[feishu] connected to Feishu long-living gateway
不要关闭网关终端,打开浏览器进入你的飞书应用后台:
im.message.receive_v1。{ "scopes": { "tenant": [ "contact:user.base:readonly", "im:message", "im:message.group_at_msg:readonly", "im:message.p2p_msg:readonly", "im:message:send_as_bot", "im:resource" ], "user": [] } }
1.0.1),填写更新说明,点击'发布'。在另一个终端窗口(或标签页)执行:
openclaw status
如果 Feishu 频道显示 ON 和 OK,说明配置成功。
在终端输入配对信息,完成后即可使用。
openclaw pairing approve feishu 配对码
发送一条消息,例如'hi'。

npm install 失败解决:设置国内镜像源:
npm config set registry https://registry.npmmirror.com
再重新安装。
openclaw gateway)并保持运行,App ID/Secret 正确。必须先在 OpenClaw 中配置并启动网关,再去飞书后台保存。failed to obtain token (400 错误)contact:user.base:readonly)。Range of input length should be [1, 258048]contextWindow 为 258000。openclaw config set channels.feishu.maxHistoryMessages 3)。openclaw skills list)。Gateway already running / 端口占用lsof -i :18789。kill -9 <PID>。Ctrl+C 停止。duplicate plugin id detected: feishu~/openclaw/extensions 和 ~/.openclaw/extensions)同时存在飞书插件。解决:删除项目源码内的插件副本:
rm -rf ~/openclaw/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