《从零基础到精通：我把 OpenClaw 踩过的坑，都写进了这本操作手册》

⛳️ 从零基础到精通，掌握 OpenClaw 的全流程落地能力

  • 适用人群：AI 领域从业者｜企业 OpenClaw 部署负责人｜初次接触 OpenClaw 的新手
  • 更新时间：2026 年 3 月 9 日
  • 内容出品人：@AGI舰长
  • 核心定位：可落地、全场景、细节拉满的 OpenClaw 操作手册
  • 名称变更：Clawdbot >> Moltbot >> OpenClaw
  • 章节亮点
    • OpenClaw 四种安装方案，步步图解！
    • 钉钉与 OpenClaw 对接完整教程！
    • 飞书与 OpenClaw 对接完整教程！

📌 本指南将持续补充 OpenClaw 产品解读、部署技巧、应用案例等干货，万字长文，永久开放免费阅读。觉得有用请收藏分享。

1、OpenClaw 简介

在 AI 技术加速渗透、实用型工具集中井喷的时代背景下，OpenClaw 以操作门槛低、场景覆盖广、落地成本优三大核心优势，从海量工具中强势突围，迅速成为 AI 发烧友、职场精英、技术开发者及创业者的首选热门。其走红背后，既契合了当下用户对"高效省力、精准提效"的本质诉求，也成功瓦解了 AI 技术的专业高墙，让各类人群都能零障碍上手使用，真正迈入"AI 普惠大众、大众善用 AI"的新纪元。短短不足七日，OpenClaw 在 GitHub 的星标数从 1 万狂飙至 5.97 万，且仍保持指数式攀升势头。截止 2026 年 3 月 9 日已达 286k.

🌐 相关网址

1.1 什么是 OpenClaw

🎯 由于命名争议，它从 Clawdbot 改名为 Moltbot 又改名为 OpenClaw

OpenClaw 是开源且可本地化部署的 AI 智能体（AI Agent），产品定位聚焦于「能实际干活的 AI 助理」。相比 ChatGPT、Claude 等传统 AI 工具仅提供文本建议的局限性，OpenClaw 拥有落地执行的本领——可直接操纵你的计算机、对接各种应用程序，经由聊天平台接收命令并自动化完成任务，真正达成「发出指令，落地成果」的闭环。

1.2 OpenClaw 的核心架构

OpenClaw 通过四个核心部分协同工作，形成「指令捕获-逻辑研判-任务落实-记忆归档」的完整运行闭环：

  • Gateway（网关节点）：系统中枢节点，连通聊天工具（WhatsApp/Telegram 等）与 AI 模型，承担指令传输与任务调度，利用 WebSocket 长连接保证响应时效。
  • Agent（智能体节点）：由 Claude、GPT、MiniMax 等模型支撑，负责指令理解、步骤规划、技能触发，扮演系统的「思维决策中枢」角色。
  • Skills（技能节点）：可无限扩展的功能插件集合，包括网页抓取、邮件管理、文件处理、脚本运行等，鼓励社区参与和个性化开发。
  • Memory（记忆节点）：本地文件储存体系（默认地址：~/.openclaw/memory），保存聊天历史、用户配置、任务日志，支持人工调整与导出备份。

1.3 🔥 OpenClaw 为何一夜爆红？

2026年1月，OpenClaw在GitHub的星标数从10k狂飙至59.7k，引发硅谷技术圈疯狂部署。其走红的根本原因只有一个——它终结了「AI只会动嘴、不会动手」的行业困局。

名人争相背书：Google AI Studio负责人Logan Kilpatrick直接在X上表态「已下单Mac mini」；xAI产品负责人Nikita Bier感叹「AI这波浪潮，一天抵十年」。

标杆案例出圈：博主Alex Finn将OpenClaw打造成「全天候AI员工Henry」，实现：

  • 🖥️ 代码开发：连续48小时自主coding，修复SaaS漏洞、产出大量代码
  • 📱 生活助理：短信订餐失败后，用ElevenLabs语音合成打电话完成预订
  • 📧 自动化办公：通宵读取邮件、自建CRM、分析趋势、撰写爆款视频脚本

场景持续扩张：有用户让OpenClaw与多家车商「邮件博弈」，成功砍价4200美元；还有人用它接管家族茶叶生意，实现排班、库存、B2B跟进的全流程自动化。

📌 OpenClaw不是工具，而是可雇佣的数字员工。

优势：

2、安装部署

2.1 macOS 应用安装

这种方式，首先你得有一个 m 芯片的 macOS 15+ 操作系统，下载 dmg 安装包运行安装

菜单栏访问您的龙虾。与CLI配合使用效果很好。

2.1.1 软件下载

  • 下载

2.1.2 安装

  • 与常规软件安装一样，鼠标左键双击

  • 点 Next

欢迎来到OpenClaw

OpenClaw是一个强大的个人al助手，可以连接到WhatsApp或Telegram。

⚠️ 安全通知：

连接的人工智能代理(如Claude)可以在您的Mac上触发强大的操作， 包括运行命令、读/写文件和截图- 这取决于您授予的权限。 仅当您了解风险并相信提示和时，才启用OpenClaw 您使用的集成。

  • 点击 Next（当前页面意思如下）

OpenClaw使用保持运行的单一网关。选择这台Mac，连接到发现附近的网关，或稍后配置。

这台Mac

网关在这台Mac上自动启动。

  • 根据需要，点击 Grant 进行授权，然后点击 Next（这里要注意风险问题，看自己需要，不过要想体验好，还是都授权效果更好些）

授予权限

这些macOS权限允许OpenClaw自动运行应用程序，并在这台苹果电脑。

  • 自动化(AppleScript)：控制其他应用程序(如终端)进行自动化操作
  • 通知：显示代理活动的桌面警报
  • 易接近：在操作需要时控制Ul元素
  • 屏幕录制：捕捉上下文或屏幕截图的屏幕
  • 麦克风：允许语音唤醒和音频捕获
  • 语音识别：在设备上转录语音唤醒触发短语
  • 照相机：从相机中捕捉照片和视频
  • 位置：代理请求时共享位置

授权过程中，会涉及到隐私与安全的授权，例如：

  • 最后一步

准备就绪

远程网关清单

在您的网关主机上:安装/更新“openclaw”包并确保

凭证存在 (通常为 ~/.openclaw/credentials/oauth.json)。然后根据需要再次连接。

  • 打开菜单栏面板：点击OpenClaw菜单栏图标，查看快速聊天和状态。
  • 连接WhatsApp或Telegram：打开设置-频道以链接频道和监控状态。
  • 试试语音唤醒：在设置中为免提命令启用语音唤醒，并覆盖一个实时脚本。
  • 使用面板+画布：打开菜单栏面板进行快速聊天；代理可以显示预览和更丰富的画布视觉效果。
  • 给你的代理更多的权力：启用可选技能(Peekaboo、oracle、camsnap、...)来自设置技能。
  • 技能包括

无法从网关加载技能。

确保网关正在运行并已连接，然后点击刷新(或打开设置>技能)。

详细信息:网关未配置

    • 登录时启动（按需勾选）

2026.03.07 官方发布的这个 App 应用， 我是在 3 月 9 号安装，但遇到一个问题，安装后无法打开，已经给官方报了 issues ，等官方回复解决后，大家就可以看到这个页面了。

具体配置，我们继续看用当下通用的命令行配置方式来进行，请继续看 2.2 章节。

2.2 node npm 命令安装

官方文档：https://docs.openclaw.ai/zh-CN/install

系统要求

  • Node >=22
  • Git
  • macOS、Linux 或通过 WSL2 的 Windows
  • pnpm 仅在从源代码构建时需要

除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行新手引导。

快速安装

2.2.1 安装器脚本（推荐）

通过 npm 全局安装 openclaw 并运行新手引导。

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

# 如下俩命令供参考，建议选择上面这个
# 安装器标志：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
# 详情：安装器内部原理。非交互式（跳过新手引导）：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
  • 执行命令前，检查一下 node 版本以及 Git 是否符合要求，然后执行即可

  • 选择 yes 回车

  • 选择安装方式，快速开始还是基于安装指南

  • 网关选择本地

  • 选择工作空间

  • 选择模型厂商

安装结束后会自动出现提示信息，请根据提示信息完成 OpenClaw 配置，参考配置如下：

配置项

配置内容

I understand this is powerful and inherently risky. Continue?

选择 ”Yes”

Onboarding mode

选择 “QuickStart”

Model/auth provider

选择 “Skip for now”，后续可以配置

Filter models by provider

选择 “All providers”

Default model

使用默认配置

Select channel (QuickStart)

选择 “Skip for now”，后续可以配置

Configure skills now? (recommended)

选择 “No”，后续可以配置。

Enable hooks?

按空格键选中，选择“Skip for now”，按回车键进入下一步。

How do you want to hatch your bot?

选择 “Hatch in TUI”。
    • Skip for now

  • All providers

  • 默认配置

  • 一路回车，暂时跳过聊天软件

  • 跳过厂商

  • 跳过 skills 以及 hooks

  • 一路回车，hatch 选择第一个

  • 通过 Web UI 修改配置文件，配置模型厂商（阿里百炼 CoddingPlan）
openclaw dashboard
  • 浏览器，切换Raw模式，配置厂商
    • 也可以直接编辑：~/.openclaw/openclaw.json

单击右上角 Save 保存，然后单击 Update使配置生效。

保存成功后，apiKey将显示为“__OPENCLAW_REDACTED__”。脱敏保护，仅用于前端界面隐藏，不影响实际调用。

复制以下内容到配置文件。将YOUR_API_KEY替换为Coding Plan 专属 API Key。

若需保留已有配置，请勿直接全量替换，详见已有配置如何安全修改？

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "YOUR_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-max-2026-01-23",
            "name": "qwen3-max-2026-01-23",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 262144,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-coder-next",
            "name": "qwen3-coder-next",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 262144,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-coder-plus",
            "name": "qwen3-coder-plus",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax-M2.5",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 204800,
            "maxTokens": 131072
          },
          {
            "id": "glm-5",
            "name": "glm-5",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 202752,
            "maxTokens": 16384
          },
          {
            "id": "glm-4.7",
            "name": "glm-4.7",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 202752,
            "maxTokens": 16384
          },
          {
            "id": "kimi-k2.5",
            "name": "kimi-k2.5",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 262144,
            "maxTokens": 32768
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      },
      "models": {
        "bailian/qwen3.5-plus": {},
        "bailian/qwen3-max-2026-01-23": {},
        "bailian/qwen3-coder-next": {},
        "bailian/qwen3-coder-plus": {},
        "bailian/MiniMax-M2.5": {},
        "bailian/glm-5": {},
        "bailian/glm-4.7": {},
        "bailian/kimi-k2.5": {}
      }
    }
  },
  "gateway": {
    "mode": "local"
  }
}
  • 查看coding plan已配置的模型

在终端输入openclaw tui，进入TUI 界面，接着输入/model查看模型列表。按回车键选中模型，按Esc键退出模型列表。

  • 与你的龙虾聊一聊，试一下吧

  • 按需安装 skills

2.2.2 全局安装（手动）

如果你已经有 Node：

npm install -g openclaw@latest

如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 sharp 安装失败，请强制使用预构建二进制文件：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

如果你看到 sharp: Please add node-gyp to your dependencies，要么安装构建工具（macOS：Xcode CLT + npm install -g node-gyp），要么使用上面的 SHARP_IGNORE_GLOBAL_LIBVIPS=1 变通方法来跳过原生构建。或使用 pnpm：

pnpm add -g openclaw@latest
pnpm approve-builds -g                # 批准 openclaw、node-llama-cpp、sharp 等
pnpm add -g openclaw@latest           # 重新运行以执行 postinstall 脚本

pnpm 需要显式批准带有构建脚本的包。在首次安装显示”Ignored build scripts”警告后，运行 pnpm approve-builds -g 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。然后：

openclaw onboard --install-daemon

2.2.3 从源代码（贡献者/开发）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon

提示：如果你还没有全局安装，请通过 pnpm openclaw ... 运行仓库命令。

2.2.4 CLI 标志

2.2.4.1 常用标志
  • --install-method npm|git
  • --git-dir <path>（默认：~/openclaw）
  • --no-git-update（使用现有 checkout 时跳过 git pull）
  • --no-prompt（禁用提示；CI/自动化中必需）
  • --dry-run（打印将要执行的操作；不做任何更改）
  • --no-onboard（跳过新手引导）
2.2.4.2 环境变量

等效的环境变量（对自动化有用）：

  • OPENCLAW_INSTALL_METHOD=git|npm
  • OPENCLAW_GIT_DIR=...
  • OPENCLAW_GIT_UPDATE=0|1
  • OPENCLAW_NO_PROMPT=1
  • OPENCLAW_DRY_RUN=1
  • OPENCLAW_NO_ONBOARD=1
  • SHARP_IGNORE_GLOBAL_LIBVIPS=0|1（默认：1；避免 sharp 针对系统 libvips 构建）

2.2.5 其他安装选项

2.2.6 安装后检查

  • 运行新手引导：openclaw onboard --install-daemon
  • 快速检查：openclaw doctor
    • 检查 Gateway 网关健康状态：openclaw status + openclaw health
  • 打开仪表板：openclaw dashboard

2.2.7 使用方式

  • TUI 页面（终端执行如下命令）：

openclaw tui

  • Web UI（启动 gateway 后，浏览器访问）：

http://127.0.0.1:18789/

2.2.8 疑惑？如何用聊天软件或者手机控制它给我干活？

到这里，大家可能会疑惑，这不是【命令行 + 网页端】的形式么，我如何通过聊天软件或者手机来控制它给我干活呢？ 当然我们还需要做一些额外配置，如：

  • 配置浏览器插件
    • 让 OpenClaw 可以控制你现有的 Chrome 标签页：看《2.3.1章节》，后续也会在 2.3 章节补充其他工具，也欢迎小伙伴们一起共建 📲 联系我们（AGI舰队）
  • 接入社交软件（第 3 章节介绍）
    • 国内：飞书、钉钉
    • 国外软件：Telegram、WhatsApp

2.3 工具准备

2.3.1 浏览器

官网教程：https://docs.openclaw.ai/zh-CN/tools/chrome-extension

  • Chrome 扩展

OpenClaw Chrome 扩展让智能体控制你现有的 Chrome 标签页（你的正常 Chrome 窗口），而不是启动一个单独的 openclaw 管理的 Chrome 配置文件。附加/分离通过一个单独的 Chrome 工具栏按钮实现。

  • 它是什么（概念）

有三个部分：

    • 浏览器控制服务（Gateway 网关或节点）：智能体/工具调用的 API（通过 Gateway 网关）
    • 本地中继服务器（loopback CDP）：在控制服务器和扩展之间桥接（默认 http://127.0.0.1:18792）
    • Chrome MV3 扩展：使用 chrome.debugger 附加到活动标签页，并将 CDP 消息传送到中继

然后 OpenClaw 通过正常的 browser 工具界面控制附加的标签页（选择正确的配置文件）。

  • 安装/加载（未打包）
# 将扩展安装到稳定的本地路径：
openclaw browser extension install

# 打印已安装扩展的目录路径（~/.openclaw/browser/chrome-extension）：
openclaw browser extension path

# Chrome → chrome://extensions
● 启用”开发者模式”
● “加载已解压的扩展程序” → 选择上面打印的目录
固定扩展。
  • 更新（无构建步骤）

扩展作为静态文件包含在 OpenClaw 发布版（npm 包）中。没有单独的”构建”步骤。升级 OpenClaw 后：

    • 重新运行 openclaw browser extension install 以刷新 OpenClaw 状态目录下的已安装文件。
    • Chrome → chrome://extensions → 点击扩展上的”重新加载”。

  • 试试操作浏览器（之后用它来做自动化测试，跑测试用例，也是很香的）

2.4 各厂商提供的一键式安装

因为 OpenClaw 的火爆，各厂商也都推出了安装包，来吸引流量，下面简单介绍几种渠道供大家参考，如：

  • 阿里云 OpenClaw 套餐
  • MiniMax 的 MaxClaw 套餐

其他厂商也都有各自的一键安装或者相应套餐，大同小异，这里就以阿里云以及 MiniMax 为例演示。

2.4.1 阿里云 OpenClaw 部署

若需要在阿里云部署 OpenClaw，先打开「阿里云服务」，登录账号。

2.4.1.1 第一步、购买 OpenClaw 服务器

使用云厂商的云端部署，你首先要先买一个云服务器，访问 https://swasnext.console.aliyun.com/buy#/

快速进入到 OpenClaw 专属服务器购买界面。

这里一定要看好配置，参考如下：

  • 实例规格：通用型 ｜ 2vCPU ｜ 2GiB
  • 镜像：应用镜像 - OpenClaw
  • 地域：美国（弗吉尼亚）
  • 数量：1（按需选择）
  • 时长：1个月或者1年（按需选择）
  • 是否开启「自动续费」大家按需选择，可以先试用。

如果你是阿里云新账号，会有一个新用户折上折的优惠。

之后直接点击「立即购买」，就进入到付款界面付款即可。

支付成功之后，直接点击进入「管理控制台」，你会见到一个这样的页面，按照页面提示一步一步配置即可

2.4.1.2 关于配置这里有如下几个注意事项

  • 访问控制页面：单击打开网站页面可进入OpenClaw 对话页面。

2.4.1.3 开启 ResponseAPI 访问

为方便后续在阿里云生态下，通过 AppFlow 访问 OpenClaw，需要开启 ResponseAPI 访问。

  • 在 OpenClaw 页面左侧导航栏，单击 Setting（配置） > Gateway。
  • 切换至Gateway HTTP API 页签，在 Responses 区域将 Enabled 切换至开启，单击Save。

到这里，准备工作已就绪

接下来看第三章，接入聊天工具（各个生态渠道），用手机控制 OpenClaw 给我们干活！

2.4.2 MiniMax 的 MaxClaw

  • 网址：https://agent.minimaxi.com/
  • 云端部署，即刻在线： 10 秒内完成OpenClaw云端部署，无需配置服务器，零维护负担。
  • 在你的常用聊天应用里对话： 现已支持接入飞书、钉钉等平台，更多集成即将上线。
  • 由你定义，全心为你： 自定义 Agent 的名称与性格，它会记住每一段对话细节，更懂你的偏好。

  • 优点：配置非常方便
  • 缺点：需要订阅付费

  • 具体操作流程不赘述了，非常简单，按照提示一步一步操作即可！
  • 但接入钉钉、飞书等，还是需要看第3章内容

3、打通生态渠道（接入飞书、钉钉）

3.1 龙虾集成到钉钉！

🎯 前置条件：

推荐使用《2.4.1 阿里云 OpenClaw 部署》章节内容进行配置，用阿里云生态处理！

这步可能流程有点繁琐，特别是没有配置经验的小伙伴，但是相信我，亲手打造自己的贾维斯的感觉还是很爽的...

如果有困难的小伙伴，也可以社群里面联系我～

3.1.1 创建钉钉应用

创建钉钉应用需要你的钉钉账号有开发者权限。

这里需要联系组织管理员获取钉钉开放平台的开发权限，具体操作参考(https://open.dingtalk.com/document/orgapp/obtain-developer-permissions)

3.1.1.1 创建钉钉应用

  • 填写应用名称和应用描述，上传应用图标，完成后点击保存。

3.1.1.2 查看应用 Client ID 和 Client Secret

点击应用名称进入应用，在左侧菜单选择「凭证与基础信息」，复制 Client ID 和 Client Secret，备用

3.1.1.3 创建消息卡片

我们平时在钉钉上看到的推送消息，其实都有卡片样式，所以我们同样通过设置卡片消息来支持流式返回结果，接下来创建一下卡片模板：

  • 点击「开放能力 >> 卡片平台」(https://open-dev.dingtalk.com/fe/card)，点击新建模板。

  • 在创建模板输入框，填入模板信息，单击创建。
    • 卡片类型：消息卡片。
    • 卡片模板场景：AI 卡片。
    • 关联应用：刚刚创建的 OpenClaw 应用爪爪。

  • 在编辑卡片模板页面，不要使用预设模板以及任何额外操作，直接保存并发布模板。然后点击返回模板列表页面。

  • 复制模板ID，用于稍后创建钉钉连接流使用。

3.1.1.4 授权操作

创建卡片后，我们需要给应用授予发送卡片消息的权限。

  • 在左侧菜单选择开发配置 > 权限管理，在左侧搜索框分别输入Card.Streaming.Write和Card.Instance.Write，并点击申请权限。

注意，两个权限都需要申请！！!

3.1.2 创建AppFlow连接流

  • 点击添加新凭证

  • 在连接流的账户授权配置向导页，点击添加新凭证。在创建凭证对话框中，填入步骤：查看应用信息中获取到的 Client ID 和 Client Secret，并设置一个自定义凭证名称。

然后点击下一步

  • 在执行动作配置向导页，填写模型名称、公网地址以及步骤：获取卡片模板ID获取到的模板ID，完成后点击下一步。

  • 在基本信息配置向导页，填写连接流名称和连接流描述（建议保持默认），完成后点击下一步。

  • 界面提示流程配置成功，点击【复制 WebhookUrl】，点击发布

✌️胜利就在前方，坚持一下，马上就能用了

3.1.3 配置钉钉机器人

拿到 Webhook 地址后，接下来就可以在钉钉应用中配置机器人来回答用户问题让龙虾干活了！

3.3.1 配置钉钉机器人

  • 在添加应用能力页面，找到机器人，点击添加（因为我已经添加了显示的是配置）。

在机器人配置页面，打开机器人配置开关，然后关于机器人简介、描述的可以随意填什么之类的都随意填吧。

消息接收模式请选择HTTP模式，消息接收地址为刚刚的 WebhookUrl。然后点击发布。

  • 消息接收模式请选择HTTP模式，目前AppFlow仅支持HTTP模式，选择Stream模式会导致无法返回消息。
3.3.2 发布应用版本

应用创建完成后，如果需要将应用供企业内其他用户使用，则需要发布一个版本。

  • 点击应用开发，在钉钉应用页面，点击目标应用。

  • 点击版本管理与发布，在版本管理与发布页面，点击创建新版本。

  • 进入版本详情页面，输入应用版本号和版本描述信息，选择合适的应用可见范围，完成后点击保存。并在弹窗中点击直接发布。

3.3.3 测试机器人

你可以在群聊中添加机器人，并与机器人对话，并派发任务。

  • 在钉钉群管理中添加机器人。进入钉钉群群设置页面

  • 点击机器人卡片区域

  • 在机器人管理页面，点击添加机器人。

  • 搜索文本框中输入目标机器人名称，并选中要添加的机器人。点击添加，完成后再点击完成添加。

  • 在钉钉群中或私聊时@机器人，进行交流互动。

至此，大功告成！！！

我们可以打开刚才登录的界面，查看它的聊天日志。

包括后续我们有需求，还可以直接用OpenClaw调用IMessage给指定人发消息。

👏 更多实用探索案例，欢迎小伙伴共建（📲 联系我们（AGI舰队））

3.2 龙虾集成到飞书

官方教程：https://docs.openclaw.ai/zh-CN/channels/feishu

3.2.1 内置插件

当前版本的 OpenClaw 已内置 Feishu 插件，因此通常不需要单独安装。如果你使用的是较旧版本，或是没有内置 Feishu 的自定义安装，可手动安装：

openclaw plugins install @openclaw/feishu

3.2.2 快速开始

添加飞书渠道有两种方式如下（完整教程请看 3.2.3 章节）：

方式一：通过安装向导添加（推荐）

如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书：

openclaw onboard

向导会引导您完成：

  1. 创建飞书应用并获取凭证
  2. 配置应用凭证
  3. 启动网关

✅ 完成配置后，您可以使用以下命令检查网关状态：

  • openclaw gateway status - 查看网关运行状态
  • openclaw logs --follow - 查看实时日志
方式二：通过命令行添加

如果您已经完成了初始安装，可以用以下命令添加飞书渠道：

openclaw channels add

然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。✅ 完成配置后，您可以使用以下命令管理网关：

  • openclaw gateway status - 查看网关运行状态
  • openclaw gateway restart - 重启网关以应用新配置
  • openclaw logs --follow - 查看实时日志

3.2.3 创建飞书应用

3.2.3.1 打开飞书开放平台

访问 飞书开放平台，使用飞书账号登录。Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设置 domain: "lark"。

3.2.3.2 创建应用
  1. 点击 创建企业自建应用
  2. 填写应用名称和描述
  3. 选择应用图标

3.2.3.3 获取应用凭证

在应用的 凭证与基础信息 页面，复制：

  • App ID（格式如 cli_xxx）
  • App Secret

❗ 重要：请妥善保管 App Secret，不要分享给他人。

3.2.3.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: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"]
  }
}

3.2.3.5 启用机器人能力

在 应用能力 > 机器人 页面：

  1. 开启机器人能力
  2. 配置机器人名称

3.2.3.6 配置事件订阅

⚠️ 重要提醒：在配置事件订阅前，请务必确保已完成以下步骤：

  1. 运行 openclaw channels add 添加了 Feishu 渠道
  2. 网关处于启动状态（可通过 openclaw gateway status 检查状态）

在 事件订阅 页面：

  1. 选择 使用长连接接收事件（WebSocket 模式）
  2. 添加事件：im.message.receive_v1（接收消息）

⚠️ 注意：如果网关未启动或渠道未添加，长连接设置将保存失败。

3.2.3.7 发布应用
  1. 在 版本管理与发布 页面创建版本
  2. 提交审核并发布
  3. 等待管理员审批（企业自建应用通常自动通过）

3.2.4 配置 OpenClaw

3.2.4.1 通过向导配置（推荐）

运行以下命令，根据提示粘贴 App ID 和 App Secret：

openclaw channels add

选择 Feishu，然后输入您在第一步获取的凭证即可。

3.2.4.2 通过配置文件配置

编辑 ~/.openclaw/openclaw.json：

"channels": {
    "feishu": {
      "enabled": true,
      "typingIndicator": true,
      "resolveSenderNames": false,
      "accounts": {
        "main": {
          "appId": "cli_xxxxx",
          "appSecret": "xxxxxxxxx",
          "botName": "爪爪"
        },
        "default": {
          "dmPolicy": "pairing"
        }
      }
    }
  },
  • 测试一下吧

若使用 connectionMode: "webhook"，需设置 verificationToken。飞书 Webhook 服务默认绑定 127.0.0.1；仅在需要不同监听地址时设置 webhookHost。

3.2.4.3 获取 Verification Token（仅 Webhook 模式）

使用 Webhook 模式时，需在配置中设置 channels.feishu.verificationToken。获取方式：

  1. 在飞书开放平台打开您的应用
  2. 进入 开发配置 → 事件与回调
  3. 打开 加密策略 选项卡
  4. 复制 Verification Token（校验令牌）

3.2.4.4 通过环境变量配置
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
3.2.4.5 Lark（国际版）域名

如果您的租户在 Lark（国际版），请设置域名为 lark（或完整域名），可配置 channels.feishu.domain 或 channels.feishu.accounts.<id>.domain：

"channels": {
    "feishu": {
      "domain: "lark",
      "accounts": {
        "main": {
          "appId": "cli_xxxxx",
          "appSecret": "xxxxxxxxx",
          "botName": "爪爪"
        },
        "default": {
          "dmPolicy": "pairing"
        }
      }
    }
  },
3.2.4.6 配额优化

可通过以下可选配置减少飞书 API 调用：

  • typingIndicator（默认 true）：设为 false 时不发送“正在输入”状态。
  • resolveSenderNames（默认 true）：设为 false 时不拉取发送者资料。

可在渠道级或账号级配置：

"channels": {
    "feishu": {
      "enabled": true,
      "typingIndicator": true,
      "resolveSenderNames": false,
      "domain: "lark",
      "accounts": {
        "main": {
          "appId": "cli_xxxxx",
          "appSecret": "xxxxxxxxx",
          "botName": "爪爪"
        },
        "default": {
          "dmPolicy": "pairing"
        }
      }
    }
  },

3.2.5 启动并测试

3.2.5.1 启动网关
openclaw gateway
3.2.5.2 发送测试消息

在飞书中找到您创建的机器人，发送一条消息。

3.2.5.3 配对授权

默认情况下，机器人会回复一个 配对码。您需要批准此代码：

openclaw pairing approve feishu <配对码>

批准后即可正常对话。

  • 也可以在群里中通过艾特机器人的方式聊天

3.2.5.4 介绍
  • 飞书机器人渠道：由网关管理的飞书机器人
  • 确定性路由：回复始终返回飞书，模型不会选择渠道
  • 会话隔离：私聊共享主会话；群组独立隔离
  • WebSocket 连接：使用飞书 SDK 的长连接模式，无需公网 URL

3.2.6 访问控制

3.2.6.1 私聊访问
  • 默认：dmPolicy: "pairing"，陌生用户会收到配对码
  • 批准配对：
openclaw pairing list feishu      # 查看待审批列表
openclaw pairing approve feishu <CODE>  # 批准
  • 白名单模式：通过 channels.feishu.allowFrom 配置允许的用户 Open ID
3.2.6.2 群组访问

1. 群组策略（channels.feishu.groupPolicy）：

  • "open" = 允许群组中所有人（默认）
  • "allowlist" = 仅允许 groupAllowFrom 中的群组
  • "disabled" = 禁用群组消息

2. @提及要求（channels.feishu.groups.<chat_id>.requireMention）：

  • true = 需要 @机器人才响应（默认）
  • false = 无需 @也响应
3.2.6.3 群组配置示例
  • 允许所有群组，需要 @提及（默认行为）
{
  channels: {
    feishu: {
      groupPolicy: "open",
      // 默认 requireMention: true
    },
  },
}
  • 允许所有群组，无需 @提及，需要为特定群组配置：
{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}
  • 仅允许特定群组
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // 群组 ID 格式为 oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}
  • 仅允许特定成员在群组中发信（发送者白名单）

除群组白名单外，该群组内所有消息均按发送者 open_id 校验：仅 groups.<chat_id>.allowFrom 中列出的用户消息会被处理，其他成员的消息会被忽略（此为发送者级白名单，不仅针对 /reset、/new 等控制命令）。

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // 用户 open_id 格式为 ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}
3.2.6.4 获取群组/用户 ID
  • 获取群组 ID（chat_id）

群组 ID 格式为 oc_xxx，可以通过以下方式获取：方法一（推荐）：

    1. 启动网关并在群组中 @机器人发消息
    2. 运行 openclaw logs --follow 查看日志中的 chat_id

方法二： 使用飞书 API 调试工具获取机器人所在群组列表。

  • 获取用户 ID（open_id）

用户 ID 格式为 ou_xxx，可以通过以下方式获取：方法一（推荐）：

    1. 启动网关并给机器人发消息
    2. 运行 openclaw logs --follow 查看日志中的 open_id

方法二： 查看配对请求列表，其中包含用户的 Open ID：

openclaw pairing list feishu

3.2.7 常用命令

命令

说明

/status

查看机器人状态

/reset

重置对话会话

/model

查看/切换模型

注意：飞书目前不支持原生命令菜单，命令需要以文本形式发送。

3.2.8 网关管理命令

在配置和使用飞书渠道时，您可能需要使用以下网关管理命令：

命令

说明

openclaw gateway status

查看网关运行状态

openclaw gateway install

安装/启动网关服务

openclaw gateway stop

停止网关服务

openclaw gateway restart

重启网关服务

openclaw logs --follow

实时查看日志输出

3.2.9 故障排除

3.2.9.1 机器人在群组中不响应
  1. 检查机器人是否已添加到群组
  2. 检查是否 @了机器人（默认需要 @提及）
  3. 检查 groupPolicy 是否为 "disabled"
  4. 查看日志：openclaw logs --follow
3.2.9.2 机器人收不到消息
  1. 检查应用是否已发布并审批通过
  2. 检查事件订阅是否配置正确（im.message.receive_v1）
  3. 检查是否选择了 长连接 模式
  4. 检查应用权限是否完整
  5. 检查网关是否正在运行：openclaw gateway status
  6. 查看实时日志：openclaw logs --follow
3.2.9.3 App Secret 泄露怎么办
  1. 在飞书开放平台重置 App Secret
  2. 更新配置文件中的 App Secret
  3. 重启网关
3.2.9.4 发送消息失败
  1. 检查应用是否有 im:message:send_as_bot 权限
  2. 检查应用是否已发布
  3. 查看日志获取详细错误信息

3.2.10 高级配置

3.2.10.1 多账号配置

如果需要管理多个飞书机器人，可配置 defaultAccount 指定出站未显式指定 accountId 时使用的账号：

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "主机器人",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "备用机器人",
          enabled: false, // 暂时禁用
        },
      },
    },
  },
}
3.2.10.2 消息限制
  • textChunkLimit：出站文本分块大小（默认 2000 字符）
  • mediaMaxMb：媒体上传/下载限制（默认 30MB）
3.2.10.3 流式输出

飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容显示生成进度。默认配置：

{
  channels: {
    feishu: {
      streaming: true, // 启用流式卡片输出（默认 true）
      blockStreaming: true, // 启用块级流式（默认 true）
    },
  },
}

如需禁用流式输出（等待完整回复后一次性发送），可设置 streaming: false。

3.2.10.4 消息引用

在群聊中，机器人的回复可以引用用户发送的原始消息，让对话上下文更加清晰。配置选项：

{
  channels: {
    feishu: {
      // 账户级别配置（默认 "all"）
      replyToMode: "all",
      groups: {
        oc_xxx: {
          // 特定群组可以覆盖
          replyToMode: "first",
        },
      },
    },
  },
}

replyToMode 值说明：

值

行为

"off"

不引用原消息（私聊默认值）

"first"

仅在第一条回复时引用原消息

"all"

所有回复都引用原消息（群聊默认值）

注意：消息引用功能与流式卡片输出（streaming: true）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。

3.2.10.5 多 Agent 路由

通过 bindings 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent。配置示例：

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      // 用户 A 的私聊 → main agent
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_28b31a88..." },
      },
    },
    {
      // 用户 B 的私聊 → clawd-fan agent
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_0fe6b1c9..." },
      },
    },
    {
      // 某个群组 → clawd-xi agent
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_xxx..." },
      },
    },
  ],
}

匹配规则说明：

字段

说明

agentId

目标 Agent 的 ID，需要在 agents.list中定义

match.channel

渠道类型，这里固定为 "feishu"

match.peer.kind

对话类型："dm"（私聊）或 "group"（群组）

match.peer.id

用户 Open ID（ou_xxx）或群组 ID（oc_xxx）

获取 ID 的方法：参见上文 获取群组/用户 ID 章节。

3.2.11 配置参考

完整配置请参考：网关配置主要选项：

配置项

说明

默认值

channels.feishu.enabled

启用/禁用渠道

true

channels.feishu.domain

API 域名（feishu

或 lark

）

feishu

channels.feishu.connectionMode

事件传输模式（websocket/webhook）

websocket

channels.feishu.defaultAccount

出站路由默认账号 ID

default

channels.feishu.verificationToken

Webhook 模式必填

-

channels.feishu.webhookPath

Webhook 路由路径

/feishu/events

channels.feishu.webhookHost

Webhook 监听地址

127.0.0.1

channels.feishu.webhookPort

Webhook 监听端口

3000

channels.feishu.accounts.<id>.appId

应用 App ID

-

channels.feishu.accounts.<id>.appSecret

应用 App Secret

-

channels.feishu.accounts.<id>.domain

单账号 API 域名覆盖

feishu

channels.feishu.dmPolicy

私聊策略

pairing

channels.feishu.allowFrom

私聊白名单（open_id 列表）

-

channels.feishu.groupPolicy

群组策略

open

channels.feishu.groupAllowFrom

群组白名单

-

channels.feishu.groups.<chat_id>.requireMention

是否需要 @提及

true

channels.feishu.groups.<chat_id>.enabled

是否启用该群组

true

channels.feishu.textChunkLimit

消息分块大小

2000

channels.feishu.mediaMaxMb

媒体大小限制

30

channels.feishu.streaming

启用流式卡片输出

true

channels.feishu.blockStreaming

启用块级流式

true

3.2.12 dmPolicy 策略说明

值

行为

"pairing"

默认。未知用户收到配对码，管理员批准后才能对话

"allowlist"

仅 allowFrom

列表中的用户可对话，其他静默忽略

"open"

允许所有人对话（需在 allowFrom 中加 "*"）

"disabled"

完全禁止私聊

3.2.13 支持的消息类型

3.2.13.1 接收
  • ✅ 文本消息
  • ✅ 富文本（帖子）
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ✅ 视频
  • ✅ 表情包
3.2.13.2 发送
  • ✅ 文本消息
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ⚠️ 富文本（部分支持）

更多推荐

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

WorkBuddy 伙伴 Agent 上线审计清单：权限与出口流量管控要点

avatar 龙虾开发者社区
cover

本地 Agent 网关中 Istio 与 Linkerd 的出站策略对比与选型

avatar 龙虾开发者社区
cover

LangSmith Dataset 离线评测在 Agent 质量门禁中的实践

avatar 龙虾开发者社区