OpenClaw 本地 AI 助手完全指南：飞书接入 + 远程部署实战

一、概述

OpenClaw（原 Clawdbot / Moltbot）是一款开源的本地 AI 助手，部署在你自己的设备上，通过飞书、钉钉、WhatsApp、Telegram 等聊天工具与你交互。它不仅能回答问题，还能真正操作你的电脑——执行命令、浏览网页、管理文件、编写代码，是一个 24/7 在线的 AI 员工。

核心特点：

• 本地部署，数据完全自主可控
• 支持多种聊天平台（飞书、钉钉、Telegram、Discord、Slack 等）
• 可执行系统命令、浏览器控制、文件管理
• 支持定时任务（Cron Jobs）和心跳唤醒
• 支持多种 AI 模型（Claude、GPT、通义千问、GLM、Kimi、本地模型等）

---

二、环境要求

项目	要求
硬件	Mac Studio / Mac Mini / 任意 Mac 或 Linux 设备
系统	macOS 14+ 或 Linux
Node.js	v22 或更高版本
网络	需要能访问外网（飞书 API + 模型 API）
AI 模型	需要一个 LLM 的 API Key
飞书账号	需要有飞书开发者权限（如需对接飞书）

内网说明： 飞书使用 WebSocket 长连接模式，不需要公网 IP、不需要域名、不需要 ngrok。只要你的设备能访问外网（即能连接飞书服务器）就可以正常工作。

---

三、安装 Node.js

检查是否已安装：

node -v

如果未安装或版本低于 22，使用 nvm 安装：

# 国内用户（推荐，使用 gitee 镜像）
curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash

# 国外用户
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

# 重新加载环境变量
source ~/.zshrc

# 安装 Node.js 22
nvm install 22

# 验证
node -v   # 应输出 v22.x.x

---

四、安装 OpenClaw

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

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

方式二：npm 全局安装

npm install -g openclaw@latest

---

五、初始化配置

运行初始化向导：

openclaw onboard --install-daemon

向导会依次引导你完成以下步骤，以下是每一步的推荐选择：

步骤	提示内容	推荐选择
1	Security warning - Continue?	Yes（按左方向键切换）
2	Generate gateway token?	Yes
3	Tighten permissions to 700?	Yes
4	Select onboarding mode	QuickStart
5	Select AI model provider	国内推荐智谱 GLM / 通义千问
6	Enter API Key	填入你的模型 API Key
7	Select channel	选 Feishu 或 Skip for now
8	Install skill dependencies	Skip for now
9	Set GOOGLE_PLACES_API_KEY?	No
10	Enable Memory?	Yes（推荐）
11	How to hatch your bot?	Open the Web UI

AI 模型选择参考

模型	说明
智谱 GLM-4.7	免费额度充足，国内推荐首选
通义千问 Qwen	阿里云百炼平台，免费额度多
Kimi / MiniMax	国内服务，注意区分国内版和国际版
Anthropic Claude	效果最好，但成本较高
本地模型 (Ollama)	完全免费，需要足够内存

提示： OpenClaw 比较费 token，建议先用国产免费模型入门，熟练后再切换到更强的模型。

验证安装

openclaw doctor    # 检查配置
openclaw status    # 查看网关状态
openclaw dashboard # 打开浏览器管理界面

---

六、远程访问管理面板

如果你的 Mac Studio 没有接显示器（无头模式），需要从其他电脑远程访问。

获取带 token 的访问链接

在 Mac Studio 终端执行：

openclaw dashboard --no-open

会输出带 token 的完整 URL。

从其他电脑通过 SSH 隧道访问

在你的 MacBook / 其他电脑 终端执行（不是在 Mac Studio 上）：

ssh -N -L 18789:127.0.0.1:18789 你的用户名@Mac-Studio的IP地址

然后在浏览器打开：

http://localhost:18789/?token=你的token

注意： SSH 隧道命令要在你要访问的那台电脑上执行，不是在 Mac Studio 上执行，否则会提示端口被占用。

---

七、对接飞书

7.1 创建飞书应用

1. 登录飞书开发者后台：open.feishu.cn
2. 点击「创建企业自建应用」
3. 填写应用名称（如 "OpenClaw 助手"），选择图标，点击创建
4. 在左侧导航栏点击「添加应用能力」→ 添加「机器人」
5. 进入「凭证与基础信息」，复制 App ID 和 App Secret

7.2 配置 OpenClaw

在 Mac Studio 终端执行：

openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.appId "你的AppID"
openclaw config set channels.feishu.appSecret "你的AppSecret"
openclaw config set channels.feishu.sendMarkdownAsCard true
openclaw gateway restart

必须重启网关！ 不重启的话，后面配置飞书事件回调时会提示「未建立连接」。

7.3 配置飞书权限

回到飞书开发者后台 → 「权限管理」→ 「批量导入权限」，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "contact:user.base:readonly",
      "contact:contact.base:readonly",
      "im:chat",
      "im:chat:read",
      "im:chat:update",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": []
  }
}

注意： contact:contact.base:readonly 这个权限容易遗漏，缺少它会导致定时任务无法主动发送消息。

7.4 配置事件与回调

1. 左侧导航栏 →「事件与回调」

2. 订阅方式选择「使用长连接接收事件」→ 保存

3. 点击「添加事件」，添加：

   • im.message.receive_v1（接收消息，必需）
   • im.message.message_read_v1（消息已读，可选）

4. 回调配置同样选择「使用长连接」

7.5 发布应用

进入「版本管理与发布」→ 创建新版本 → 发布

每次修改权限或配置后都需要重新发布版本。

7.6 验证

打开飞书客户端，找到你的机器人，发一条消息。收到回复就说明对接成功。

---

八、已知问题与修复

问题 1：定时任务状态为 skipped，飞书收不到消息

原因： v2026.2.3 存在定时任务调度 Bug，且 HEARTBEAT.md 为空会导致任务被跳过。

修复：

# 给 HEARTBEAT.md 加内容
echo "Check and run pending cron tasks." > ~/.openclaw/agents/main/agent/HEARTBEAT.md

# 重启网关
openclaw gateway restart

问题 2：飞书插件冲突（duplicate plugin id）

原因： 手动安装的飞书插件与内置插件冲突。

修复：

rm -rf ~/.openclaw/extensions/feishu
openclaw gateway restart

问题 3：openclaw config set gateway.host 0.0.0.0 报错

原因： 当前版本不支持 gateway.host 配置项。

修复： 使用 SSH 隧道方式从其他电脑访问（见第六节）。

问题 4：飞书提示「未建立连接」

排查：

• 检查 App ID / App Secret 是否正确
• 检查是否执行了 openclaw gateway restart
• 用 openclaw status 确认网关在运行

---

九、使用手册

9.1 常用命令速查

命令	说明
openclaw doctor	检查配置是否正常
openclaw status	查看网关运行状态
openclaw dashboard	打开浏览器管理界面
openclaw dashboard --no-open	输出带 token 的访问链接
openclaw gateway restart	重启网关
openclaw gateway stop	停止网关
openclaw gateway start	启动网关
openclaw config	进入交互式配置界面
openclaw logs --tail 100	查看最近 100 条日志
openclaw plugins list	查看已安装插件
openclaw security audit --deep	安全审计
openclaw update	更新 OpenClaw

9.2 模型管理

# 查看当前模型
openclaw model

# 列出可用模型
openclaw models

# 切换默认模型
openclaw models set <提供商/模型名>
# 示例：
openclaw models set zhipu/glm-4.7-flash

# 添加备用模型（主模型不可用时自动切换）
openclaw models fallbacks add <提供商/模型名>

9.3 定时任务（Cron Jobs）

# 查看所有定时任务
openclaw cron list

# 添加周期性定时任务（每天早上 8 点发早报）
openclaw cron add \
  --name "早报" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "生成今日早报并发送给我" \
  --delivery-channel feishu \
  --delivery-to "ou_你的飞书用户ID"

# 添加一次性提醒
openclaw cron add \
  --name "会议提醒" \
  --at "2026-02-10T14:00:00+08:00" \
  --session main \
  --system-event "提醒：下午2点有会议" \
  --wake now \
  --delete-after-run

# 手动触发执行
openclaw cron run <job-id> --force

# 查看运行历史
openclaw cron runs --id <job-id>

# 删除任务
openclaw cron remove <job-id>

获取飞书用户 ID： 执行 openclaw logs --tail 200 | grep "ou_" 从日志中查找。

9.4 在飞书中直接使用

对接成功后，直接在飞书中跟机器人聊天即可，例如：

• "帮我查看一下服务器上 pm2 运行了哪些服务"
• "帮我写一个 Python 脚本，每天备份数据库"
• "30 秒后发条消息提醒我"
• "每天早上 8 点给我发一份新闻摘要"
• "帮我搜索一下最近的 AI 新闻"

9.5 技能包管理（Skills）

# 搜索可用技能
npx clawhub search <关键词>

# 安装技能
npx clawhub install <技能名>

# 在管理界面查看
# 左侧导航栏 → Skills

9.6 目录限制与安全

OpenClaw 的工作目录通过 workspace 配置控制：

# 查看当前 workspace
cat ~/.openclaw/openclaw.json | grep workspace

# 修改 workspace（限制 agent 可访问的目录）
openclaw config set agents.defaults.workspace "/Users/你的用户名/openclaw-workspace"
openclaw gateway restart

安全建议：

• 定期运行 openclaw security audit --deep
• 不要在存有重要数据的机器上开放过多权限
• 使用 Docker 部署可以实现更严格的容器级隔离
• 保管好 gateway token，不要泄露

---

十、卸载

# 停止服务
openclaw gateway stop

# 卸载 OpenClaw
npm uninstall -g openclaw

# 清理配置和数据
rm -rf ~/.openclaw

如果安装了 macOS 菜单栏 Companion App，记得从应用程序文件夹中删除。

---

附录：对接钉钉（简要）

OpenClaw 2026.2.3+ 内置了飞书支持。如需对接钉钉，使用社区插件：

openclaw plugins install https://github.com/soimy/clawdbot-channel-dingtalk.git

或使用 openclaw-china 统一插件集（支持飞书、钉钉、企业微信、QQ）： github.com/BytePioneer…

---

💡 提示： 遇到问题可以查看官方文档 docs.openclaw.ai 或在 Discord 社区提问。