本篇记录在 Mac 和 Windows 上部署 OpenClaw 的完整过程，以及配置模型提供商的避坑经验。另一篇姊妹篇 OpenClaw 树莓派 / 香橙派部署实践 则聚焦 ARM 开发板环境，涵盖网络跳转、systemd 服务自启动、常见部署问题等内容。

系列导航：

• ① 部署实践（Mac / Windows，本篇）
• ② 树莓派 / 香橙派部署（ARM 开发板 + 网络跳转）

阅读前提：无，直接跟着步骤走即可。

整体部署流程：

1. 安装 Node.js ≥ 22、git
2. 安装 OpenClaw
3. 运行配置向导，设置偏好
4. 获取 API Key，配置模型
5. 接入飞书（可选）
6. 首次运行，验证效果

---

1 Mac 部署实践

1.1 工具准备

1.1.1 安装 Homebrew

如果已有 Homebrew，可跳过此步。

curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh

安装完成后验证：

brew --version
# 输出版本号即成功

国内加速：如果安装卡在 “Downloading…”，通常是因为 GitHub 访问慢。换国内镜像：

# 方法一：中科院镜像（推荐）
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

# 方法二：手动配置多个镜像
git -C "$(brew --repo)" remote set-url origin https://mirrors.ustc.edu.cn/brew.git
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles' >> ~/.zshrc
source ~/.zshrc
brew update

1.1.2 安装 Node.js

brew install node

验证版本（要求 ≥ 22）：

node --version
# 应输出 v22.x.x 或更高

npm --version

如果版本低于 22：

brew upgrade node
brew unlink node && brew link node --overwrite
node -v   # 再次确认

1.1.3 安装 git

brew install git
git --version

1.2 安装 OpenClaw

方式一：一键脚本（推荐）

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

官方安装脚本，全自动处理依赖和环境配置。

方式二：npm 全局安装

npm install -g openclaw@latest

适合熟悉 Node.js 生态的用户。安装完成后验证：

openclaw --version

国内加速：如果 npm 下载慢，先切换镜像源：

npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest

1.3 配置向导

1.3.1 启动向导

openclaw onboard --install-daemon

--install-daemon 参数会同时安装守护进程，让 OpenClaw 在后台持续运行。

1.3.2 风险认知

第一步是安全提示，建议认真看一下，确认了解风险后继续。

1.3.3 选择模型提供商

向导会列出所有支持的服务商，选一个填入 API Key 即可。

1.3.4 MiniMax API Key 获取与填写

本教程以 MiniMax 为例，其他提供商流程类似。

获取 API Key：

1. 访问 MiniMax 开发者平台：https://platform.minimaxi.com/
2. 注册并完成个人认证
3. 在左侧菜单找到"API Keys"，点击"创建新的 API Key"
4. 给 Key 起个名字（如 “OpenClaw”），确认后会显示 Key 字符串
5. 复制 Key（格式：sk-xxxxxxxx）

重要：Key 只显示一次，确认复制后妥善保管，不要泄露给他人。

MiniMax 有两个 API 端点，注意区分：

端点	协议	适用场景
https://api.minimax.chat/v1	OpenAI 兼容	国内版（platform.minimaxi.com）
https://api.minimax.io/anthropic	Anthropic 兼容	国际版

国内用户：在 minimaxi.com 平台创建的 Key，必须搭配 https://api.minimax.chat/v1 端点使用，不要混用国际版端点。

1.3.5 网关端口

默认 18789，直接回车即可。后续可通过配置文件修改。

1.3.6 通信通道配置

先跳过，OpenClaw 跑通后再说。飞书接入方法见本文第 3 节。

1.3.7 配置摘要确认

向导会显示摘要：模型选择、工作区路径、端口、守护进程状态。过目无误后回车完成。

1.4 验证运行

# 启动网关
openclaw gateway --port 18789

# 另一个终端查看状态
openclaw gateway status

用浏览器访问控制台：

openclaw dashboard
# 或直接打开 http://127.0.0.1:18789/

在对话框里输入：

你好，介绍一下你自己

正常情况下，AI 会回复一段自我介绍。如果回复了，说明 OpenClaw 已经正常运行。

---

2 从 openclaw-cn 迁移到官方 OpenClaw

如果你的 Mac 上已经安装过 openclaw-cn（本工具的第三方中文社区版），想切换到官方版本，按以下步骤操作。

2.1 迁移步骤

第一步：停止 openclaw-cn 服务

# 停止服务
openclaw-cn gateway stop

# 确认已停止
openclaw-cn gateway status 2>/dev/null || echo "已停止"

第二步：备份配置文件

cp ~/.openclaw/openclaw.json ~/openclaw-cn-backup-$(date +%Y%m%d).json

第三步：卸载 openclaw-cn

npm uninstall -g openclaw-cn

第四步：安装官方 openclaw

# 一键脚本方式
curl -fsSL https://openclaw.ai/install.sh | bash

# 或 npm 方式（国内建议先切换镜像）
npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest

第五步：验证安装

openclaw --version
# 应输出 2026.x.x 或更高版本

第六步：重启服务

openclaw gateway start
openclaw gateway status

2.2 配置文件迁移

openclaw-cn 和官方 openclaw 的配置文件格式兼容，位置均为 ~/.openclaw/openclaw.json，可以直接复用，无需重新配置。

如果重启后飞书连接异常，参考本文第 3 节重新走一遍飞书接入流程。

2.3 exec 白名单设置（避免每次执行命令都需要审批）

openclaw approvals allowlist add --agent main "*"

生产环境建议替换 * 为具体的命令路径 glob 模式。

---

3 Windows 部署实践

3.1 WSL2 方式（推荐）

在 Windows 上运行 OpenClaw，最推荐的方式是使用 WSL2（Windows Subsystem for Linux）。它提供一个完整的 Linux 环境，OpenClaw 的所有脚本和工具都能无缝运行。

3.1.1 启用 WSL2

以管理员身份打开 PowerShell，运行：

wsl --install

重启电脑后，WSL2 自动安装 Ubuntu。

3.1.2 在 WSL2 中安装 OpenClaw

打开 Ubuntu 终端，后面的步骤与 Mac/Linux 完全一致：

# 安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

# 启动配置向导
openclaw onboard --install-daemon

3.1.3 访问控制台

WSL2 中启动网关后，在 Windows 浏览器直接访问：

http://127.0.0.1:18789/

WSL2 会自动将 localhost 端口映射到 Windows 宿主机。

3.2 原生 Windows（PowerShell）

如果没有 WSL2，也可以直接用 PowerShell 安装 Node.js 后运行 OpenClaw，但部分 Skills（尤其是依赖 Unix 工具的）可能不兼容，体验不如 WSL2 完整。

# 安装 Node.js（通过 winget 或官网下载）
winget install OpenJS.NodeJS.LTS

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

推荐优先使用 WSL2，很多社区 Skills 基于 Linux 环境开发，在 Windows 原生环境可能遇到各种路径、换行符、权限问题。

---

4 接入飞书聊天

OpenClaw 可以接入飞书、Telegram、Discord 等平台，让你在手机上随时唤起 AI 助手去执行任务。本节介绍飞书接入。

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

4.1.1 登录开放平台

访问 https://open.feishu.cn/app，登录飞书账号。

4.1.2 创建企业自建应用

点击右上角"创建应用" → 选择"企业自建应用"。

填写：

• 应用名称：如"我的 AI 助手"
• 应用描述：随意
• 应用图标：跳过，使用默认

点击"创建"。

4.1.3 获取 App ID 和 App Secret

进入应用后，左侧菜单 → 凭证与基础信息。

复制：

• App ID：cli_xxxxxxxxxxxxxx 格式
• App Secret：点击"查看"后复制

4.1.4 配置权限

左侧菜单 → 权限管理 → 批量导入，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

点击提交。个人账号权限通常即时生效；企业账号可能需要管理员审批。

4.1.5 启用机器人能力

左侧菜单 → 应用能力 → 机器人，点击启用。

可设置机器人在飞书聊天中显示的名称。

4.2 在 OpenClaw 中配置飞书

顺序很重要：必须先完成本节（配置写入 + gateway 重启），再去飞书开放平台保存事件订阅。如果网关没跑起来就保存长连接，飞书会连不上，保存失败。

4.2.1 配置飞书渠道

两种方式任选其一：

方式一：命令行

openclaw channels add
# 选择 Feishu → 输入 App ID → 输入 App Secret

方式二：直接编辑配置文件

编辑 ~/.openclaw/openclaw.json，在 channels 下添加：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxxxxx",
          "appSecret": "你的AppSecret"
        }
      }
    }
  }
}

注意：appId 和 AppSecret 必须写在 accounts.main 下面，写错位置会导致飞书静默连接失败。

4.2.2 重启网关

systemctl --user restart openclaw-gateway

确认服务正常：

systemctl --user status openclaw-gateway
# 应显示 active (running)

4.2.3 配置事件订阅（飞书开放平台）

回到飞书开放平台，左侧菜单 → 事件订阅：

1. 选择使用长连接接收事件（WebSocket 模式）
   • 不需要公网 IP 或域名，适合家庭/公司内网部署
2. 点击添加事件，搜索添加：

   im.message.receive_v1
   

保存后，飞书服务器会主动连接你本地运行中的 OpenClaw 网关，建立长连接。

4.2.4 发布应用

左侧菜单 → 版本管理与发布 → 创建版本 → 填写版本号和说明 → 申请发布。

（应用不发布，机器人在飞书里搜索不到。）

4.3 验证与配对

4.3.1 发送测试消息

在飞书搜索应用名称，找到机器人，发送：

你好

机器人会回复一段介绍。初次使用，默认需要配对码。

4.3.2 批准配对（安全机制）

首次给机器人发消息的用户会收到一个配对码。在你的电脑上运行：

# 查看待审批列表
openclaw pairing list

# 批准某个配对请求
openclaw pairing approve <配对码>

批准后，该用户就能正常使用机器人了。

4.3.3 跳过配对（单人使用）

如果只有你自己用，嫌每次审批麻烦，可以改配置文件：

{
  "channels": {
    "feishu": {
      "dmPolicy": "open"
    }
  }
}

这样所有发消息的用户都能直接使用，不需要配对。

4.4 飞书配置常见问题

Q：长连接保存失败？

→ 一定是顺序错了。先让 OpenClaw gateway 跑起来（systemctl --user status openclaw-gateway 确认 active），再去飞书开放平台保存。

Q：消息完全没有反应？

→ 先 journalctl --user -u openclaw-gateway -n 50 看日志。然后检查配置文件里 appId / AppSecret 是否写在 accounts.main 下面。

Q：App Secret 泄露了？

→ 在飞书开放平台重置 App Secret → 更新配置文件中的值 → systemctl --user restart openclaw-gateway

---

5 进阶配置

5.1 切换或添加模型

OpenClaw 支持同时配置多个模型，按需切换。

openclaw configure

这会重新运行配置向导，添加新的模型提供商。其他已有配置不会丢失。

5.2 安装 Skills 扩展

Skills 是能力包，让 OpenClaw 学会新技能。

# 搜索 Skills
openclaw skills search <关键词>

# 安装 Skill
openclaw skills install <技能名>

ClawdHub Skills 市场：https://clawhub.ai

5.3 常用命令速查

命令	功能
openclaw gateway --port 18789	启动网关
openclaw gateway status	查看网关状态
openclaw dashboard	打开浏览器控制台
openclaw configure	重新配置向导
openclaw doctor	自检诊断
openclaw channels add	添加聊天渠道
openclaw pairing list	查看配对请求
openclaw plugins list	查看已装插件
openclaw approvals allowlist add --agent main "*"	设置 exec 白名单（开发用）

5.4 安全建议

定期运行安全审计：

openclaw security audit --deep
openclaw security audit --fix

---

6 排查问题

6.1 gateway 无法启动

# 查看详细日志
journalctl --user -u openclaw-gateway -n 100 --no-pager

# 用 doctor 做全面体检
openclaw doctor

常见原因：

• 缺少 gateway.mode 配置 → 添加 "gateway": {"mode": "local"}
• 端口被占用 → netstat -tlnp | grep 18789 查看谁在用

6.2 飞书完全无反应

1. 确认 gateway 正在运行：systemctl --user status openclaw-gateway
2. 确认配置结构正确：appId 和 AppSecret 必须在 accounts.main 下
3. 确认飞书事件订阅已配置长连接 + im.message.receive_v1
4. 确认应用已发布（版本管理与发布）

6.3 模型返回 401

通常是 API Key 无效或端点配置错误。

1. 确认 Key 本身有效（在 MiniMax 平台检查）
2. 确认 baseUrl 和 Key 类型匹配（国内版用 api.minimax.chat/v1）
3. 确认 Key 没有超过用量限额

---

附录：资源链接

• OpenClaw 官网：https://openclaw.ai
• OpenClaw GitHub：https://github.com/openclaw/openclaw
• OpenClaw 文档：https://docs.openclaw.ai
• ClawdHub Skills 市场：https://clawhub.ai
• MiniMax 开发者平台：https://platform.minimaxi.com/
• 飞书开放平台：https://open.feishu.cn/app