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

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

sinat_24608097

1460人浏览 · 2026-03-06 17:43:57

sinat_24608097 · 2026-03-06 17:43:57 发布

📦 一、环境准备

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 下载源码

有两种方式：

Git 克隆（推荐）：

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

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

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

登录阿里云百炼平台。
左侧导航栏进入 密钥管理 → 创建 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 在飞书开放平台创建应用

访问飞书开放平台，点击“创建应用” → “企业自建应用”。
填写应用名称、描述，创建成功后进入应用管理页。
记录 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 在飞书后台完成最终配置

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

事件与回调 → 事件配置：
- 将“订阅方式”从 HTTP 切换为 “使用长连接接收事件”。
- 点击保存（此时应该成功，不会报错）。
- 添加事件：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），填写更新说明，点击“发布”。

4.6 验证飞书状态

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

openclaw status

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

✅ 五、测试对话

打开飞书客户端，找到你刚刚配置的机器人。
发送一条消息，例如“hi”。
在终端输入配对信息，完成后即可使用。
```
openclaw pairing approve feishu 配对码
```

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

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）。