MacOS 安装 OpenClaw 并接入飞书机器人

OpenClaw 是一个可扩展的 AI Agent 框架，支持接入各种工具、自动执行任务，并且可以和企业协作平台（如飞书）打通，实现 AI 自动回复、自动化工作流。

本文将介绍在 MacOS 上安装 OpenClaw，配置 AI 模型，接入飞书机器人，以及解决终端报错问题的完整流程。

一、环境准备

1. MacOS 系统

建议版本：MacOS 12+。Intel 和 Apple Silicon 均可。

2. 安装 Homebrew

如果没有安装 Homebrew：

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

更新 brew：

brew update

如果更新失败，可切换国内源或使用 VPN。

3. 安装 Node.js

OpenClaw 依赖 Node.js 运行环境。

brew install node

验证：

node -v && npm -v

二、安装 OpenClaw

在官网 https://openclaw.ai/ 选择 npm 安装方式。

npm i -g openclaw

等待安装完成。启动 OpenClaw：

openclaw onboard

按照提示操作，大部分选项可选择跳过或默认设置。后续可在 WebUI 的配置页面调整。

进入配置页面可使用命令：

openclaw dashboard

三、配置 AI 模型

点击'配置'打开配置文件修改。

检查根节点是否有 models 属性，没有则新建，有则修改。示例配置如下：

{
  "models": {
    "mode": "merge",
    "providers": {
      "your-provider": {
        "baseUrl": "你的模型服务地址",
        "apiKey": "你的 API Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "Qwen3.5-397B-A17B",
            "name": "Qwen3.5-397B-A17B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 202752,
            "maxTokens": 16384
          }
        ]
      }
    }
  }
}

修改 agents.defaults（默认模型与工作空间配置）：

{
  "agents": {
    "defaults": {
      "model": { "primary": "your-provider/Qwen3.5-397B-A17B" },
      "models": { "your-provider/Qwen3.5-397B-A17B": {} },
      "workspace": "/Users/当前登录用户/.openclaw/workspace"
    }
  }
}

保存后点击 Update 按钮更新配置。

四、接入飞书机器人

打开飞书开放平台：https://open.feishu.cn
创建企业自建应用，填写应用名称和描述。
记录 App ID 和 App Secret。
配置权限与事件订阅：
- 开通核心权限：左侧菜单栏开发配置 → 权限管理
  - 「应用身份权限」：搜索 im:message，全部选中并开通。
  - 「用户身份权限」：搜索 contact:user.base:readonly，选中并开通。
- 订阅方式选择长连接。
- 添加接收消息事件：搜索 im.message.receive_v1，添加该事件并确认开通对应权限。
创建版本并发布：点击页面顶部应用发布 → 版本管理与发布，创建新版本，填写更新说明后申请线上发布。

五、配置 OpenClaw 的飞书能力

1. 安装插件

openclaw plugins install @m1heng-clawd/feishu

OpenClaw 会自动完成安装、配置、重启。

2. 配置参数

终端执行以下命令，替换为飞书应用的实际信息：

# 配置飞书 App ID
openclaw config set channels.feishu.appId "<App ID>"
# 配置飞书 App Secret
openclaw config set channels.feishu.appSecret "<App Secret>"
# 启用飞书渠道
openclaw config set channels.feishu.enabled true
# 配置长连接模式（飞书推荐）
openclaw config set channels.feishu.connectionMode websocket
# 单聊策略为配对授权
openclaw config set channels.feishu.dmPolicy pairing
# 群聊策略为白名单
openclaw config set channels.feishu.groupPolicy allowlist
# 群聊需@机器人才响应
openclaw config set channels.feishu.requireMention true

配置完成后重启网关：

openclaw gateway restart

六、飞书机器人配对授权

获取配对码：向飞书机器人发送任意消息，机器人会自动回复包含配对码的消息。
终端执行配对命令：

openclaw pairing approve feishu xxxx

重启网关使授权生效：

openclaw gateway restart

验证：再次向飞书机器人发送消息，机器人能正常回答即表示配置成功。

七、配置开机自启

方法 1：官方守护进程（推荐）

openclaw onboard --install-daemon

重启电脑即可自动启动。

方法 2：LaunchAgent 手动配置（备用）

创建 LaunchAgent 目录：

mkdir -p ~/Library/LaunchAgents

创建配置文件：

vim ~/Library/LaunchAgents/com.openclaw.gateway.plist

内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.openclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/openclaw</string>
    <string>gateway</string>
    <string>start</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

加载服务：

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

验证：

launchctl list | grep openclaw

八、常见问题解决

问题 1：compdef: command not found

原因：macOS 默认未启用 zsh 补全系统，而 OpenClaw 的自动补全脚本依赖 compdef。

问题 2：zsh compinit: insecure directories

原因：zsh 补全目录权限不安全。

九、完整解决方案（推荐）

1. 安装补全组件

brew install zsh-completions

2. 修改 .zshrc

nano ~/.zshrc

在文件最顶部添加：

autoload -Uz compinit && compinit -i -u
if type brew &>/dev/null; then
  fpath=($(brew --prefix)/share/zsh-completions $fpath)
fi

3. 修复目录权限

sudo chmod -R go-w $(brew --prefix)/share/zsh-completions
sudo chown -R $(whoami) $(brew --prefix)/share/zsh-completions
sudo chmod -R go-w /usr/share/zsh
sudo chown -R root:wheel /usr/share/zsh

4. 清理缓存

rm -f ~/.zcompdump*
source ~/.zshrc

十、验证是否成功

重新打开终端：

source ~/.zshrc

如果没有任何报错，说明成功。测试：

openclaw + TAB

能看到命令补全。

十一、懒人方案（可选）

如果不需要命令补全，可以直接禁用：

echo 'export OPENCLAW_COMPLETIONS_DISABLE=1' >> ~/.zshrc
rm -f ~/.openclaw/completions/openclaw.zsh
source ~/.zshrc

总结

通过本文，我们完成了 MacOS 安装 OpenClaw、接入飞书机器人、配置开机自启以及解决终端报错。当 AI Agent 与协作工具结合时，很多重复工作都可以自动化，例如自动日报、自动会议总结、自动任务创建等。

MacOS 安装 OpenClaw 并接入飞书机器人