OpenClaw 小白搭建全攻略（macOS 版）

本指南基于真实的搭建过程整理，涵盖从零开始安装 OpenClaw、配置飞书机器人、接入阿里千问模型的每一步。无论你是技术新手还是老手，按照本指南操作，都能顺利跑起来。

📦 一、环境准备

1.1 安装 Homebrew（可选）

如果你还没有安装 Homebrew，打开终端执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1.2 安装 Node.js 和 nvm（推荐）

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 # 应输出 v22.x.x npm -v # 应输出 10.x.x

可能的问题：nvm: command not found
解决：重新打开终端，或执行 source ~/.zshrc。

1.3 安装 Xcode 命令行工具（编译 native 模块需要）

xcode-select --install

如果已安装，会提示“已经安装”。

🚀 二、安装 OpenClaw

推荐使用 本地源码安装（避免全局权限问题，方便调试）。

2.1 下载源码

有两种方式：

• 下载 ZIP：
  访问 https://github.com/openclaw/openclaw，点击“Code” → “Download ZIP”，解压到 ~/openclaw。

Git 克隆（推荐）：

git clone https://github.com/openclaw/openclaw.git

2.2 安装依赖

cd ~/openclaw npm install

可能的问题：网络慢或失败
解决：设置 npm 国内镜像

npm config set registry https://registry.npmmirror.com npm install

2.3 创建全局命令链接（可选）

如果你想在任何目录直接使用 openclaw 命令：

npm link

之后就可以直接输入 openclaw 了。

2.4 验证安装

openclaw --version

应显示版本号（如 2026.3.3）。

🧠 三、配置千问模型（阿里百炼）

OpenClaw 需要一个大模型作为“大脑”。我们以阿里云百炼平台的千问模型为例。

3.1 获取阿里百炼 API Key

1. 登录 阿里云百炼平台。
2. 左侧导航栏进入 密钥管理 → 创建 API Key，复制生成的 sk-xxxx。

3.2 确定模型 Base URL

根据你的地域选择：

• 北京：https://dashscope.aliyuncs.com/compatible-mode/v1
• 新加坡：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
• 美国：https://dashscope-us.aliyuncs.com/compatible-mode/v1

3.3 配置 OpenClaw

执行以下命令，将 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 中配置。

4.1 在飞书开放平台创建应用

1. 访问 飞书开放平台，点击“创建应用” → “企业自建应用”。
2. 填写应用名称、描述，创建成功后进入应用管理页。
3. 记录 App ID 和 App Secret（在“凭证与基础信息”中）。

4.2 安装飞书插件（如果未安装）

openclaw plugins install @openclaw/feishu

检查插件状态：

openclaw plugins list | grep feishu

应显示 loaded。

4.3 配置飞书频道

# 启用飞书频道 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

4.4 启动网关（关键步骤）

必须遵守顺序：先启动网关，再去飞书后台保存长连接。

openclaw gateway

保持此终端窗口打开，观察日志。当看到类似以下信息时，表示飞书插件已成功连接：

text

[feishu] successfully obtained token [feishu] connected to Feishu long-living gateway

4.5 在飞书后台完成最终配置

不要关闭网关终端，打开浏览器进入你的飞书应用后台：

1. 事件与回调 → 事件配置：
   • 将“订阅方式”从 HTTP 切换为 “使用长连接接收事件”。
   • 点击 保存（此时应该成功，不会报错）。
   • 添加事件：im.message.receive_v1。
2. 权限管理：
4. 版本管理与发布：
   • 创建一个新版本（如 1.0.1），填写更新说明，点击“发布”。

使用“批量导入/导出权限”功能，导入以下权限列表：

{ "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": [] } }

4.6 验证飞书状态

在另一个终端窗口（或标签页）执行：

openclaw status

如果 Feishu 频道显示 ON 和 OK，说明配置成功。

✅ 五、测试对话

1. 打开飞书客户端，找到你刚刚配置的机器人。

在终端输入配对信息，完成后即可使用。

openclaw pairing approve feishu 配对码

发送一条消息，例如“hi”。

❗ 六、常见问题及解决办法

6.1 安装 OpenClaw 时 npm install 失败

• 现象：卡住或报网络错误。

解决：设置国内镜像源：

npm config set registry https://registry.npmmirror.com

再重新安装。

6.2 飞书后台保存长连接时提示“未检测到应用连接信息”

• 原因：网关未运行，或 App ID/Secret 错误。
• 解决：确保网关已启动（openclaw gateway）并保持运行，App ID/Secret 正确。必须先在 OpenClaw 中配置并启动网关，再去飞书后台保存。

6.3 飞书插件提示 failed to obtain token (400 错误)

• 原因：App Secret 错误，或应用未发布/未启用。
• 解决：
  • 重新核对 App ID 和 Secret。
  • 在飞书后台检查应用状态，确保至少有一个已发布的版本。
  • 添加必要的权限（尤其是 contact:user.base:readonly）。

6.4 调用模型时返回 Range of input length should be [1, 258048]

• 原因：发送给模型的提示总长度超过模型限制（258048 tokens），可能是历史消息累积过长。
• 解决：
  • 修改模型配置中的 contextWindow 为 258000。
  • 重启网关清空历史会话。
  • 限制飞书插件发送的历史消息数量（尝试 openclaw config set channels.feishu.maxHistoryMessages 3）。
  • 检查并精简代理的技能列表（openclaw skills list）。

6.5 网关启动时报 Gateway already running / 端口占用

• 原因：另一个终端或后台进程已运行网关。
• 解决：
  • 找到占用端口的进程：lsof -i :18789。
  • 终止进程：kill -9 <PID>。
  • 或直接找到运行网关的终端，按 Ctrl+C 停止。

6.6 飞书插件出现重复 ID 警告

• 现象：duplicate plugin id detected: feishu
• 原因：在多个插件目录（如 ~/openclaw/extensions 和 ~/.openclaw/extensions）同时存在飞书插件。

解决：删除项目源码内的插件副本：

rm -rf ~/openclaw/extensions/feishu

6.7 模型返回 400 错误，提示缺少某些权限（如 contact 权限）

• 原因：飞书应用未添加必要的通讯录权限。
• 解决：按错误信息中的链接添加权限，并发布新版本。

📚 七、参考资源

• OpenClaw 官方文档：https://docs.openclaw.ai
• 飞书开放平台：https://open.feishu.cn
• 阿里云百炼：https://bailian.console.aliyun.com