OpenClaw 入门与实践:让 AI 住进你的飞书

❝
一只像素龙虾，正在字节跳动的地盘上横行。

前言：为什么要折腾这个？

你每天工作用飞书，和同事聊天用飞书，处理任务也在飞书。然后需要用 AI 的时候，你切换到另一个 App，或者打开另一个标签页，粘贴一段内容，等待回复，再把结果粘贴回来。

这套"切换-复制-粘贴"的流程，在 2026 年仍然困扰着大多数人。

OpenClaw 想干掉这个流程。 它是一个开源的自托管 AI 网关，让你直接在飞书里和 AI 对话——不只是聊天，还能执行命令、读写文件、操作浏览器、定时推送消息，配合 MiniMax 强悍的国产大模型，这套组合对中国用户来说几乎是量身定制的。

本文用 Why / What / How 的框架，带你从零搭起这套系统。

第一章：Why —— 为什么是 OpenClaw + 飞书 + MiniMax？

1.1 三个单独的好东西，组合在一起更好

为什么选飞书？

中国企业用户最主流的工作通讯工具之一；
开放平台成熟，创建机器人应用有完整的官方文档；
WebSocket 长连接模式：无需公网 IP，部署在任意机器上都能接收消息——这一点很关键，国内服务器配置公网 IP 并不总是方便的；
支持富文本「互动卡片」，AI 的代码块、表格输出可以渲染成好看的卡片，不是一堆 Markdown 符号。

为什么选 MiniMax M2.5？

国内用户访问稳定：使用 api.minimaxi.com（国内端点），不依赖境外网络；
Coding Plan 性价比极高：MiniMax M2.5 在 SWE-Bench Verified 上达到 80.2%，性能媲美顶尖模型，但价格只有约 1/10；官方称其为「第一个可以不计成本使用的顶尖模型」；
原生支持 Anthropic API 格式：OpenClaw 内置适配，切换毫无摩擦；
MiniMax 官方文档里就有 OpenClaw 集成教程，是官方推荐的组合。

为什么选 OpenClaw？

自托管、数据不出境：对话历史、文件、会话记忆都在你自己的机器上；
Skills 生态：轻量化的工具扩展系统，比 MCP 更节省 token；
开源免费：MIT 协议，你只需为 MiniMax API 调用付费。

1.2 这套组合能干什么？

先给你一些真实的使用场景，帮你建立具象感：

在飞书群里 @AI，让它帮你总结上午的会议记录（文件直接发给它）；
出差在外，手机飞书发条消息：「帮我看一下 CI 挂了没」，它自动 SSH 上去看日志；
每天下午 5:30，AI 主动在飞书给你发一条「今日代码提交摘要 + 明日待办」；
在飞书发一个需求描述，AI 直接生成代码、写入文件、提交 PR。

第二章：What —— OpenClaw 的核心概念

2.1 整体架构：四层模型

┌─────────────────────────────────────────────────────┐│                 飞书（Channel 层）                    ││   你的飞书 App → 企业自建应用 → 消息事件              │└──────────────────────┬──────────────────────────────┘                       │ WebSocket 长连接（无需公网IP）┌──────────────────────▼──────────────────────────────┐│                 Gateway（网关层）                     ││   运行在 127.0.0.1:18789                             ││   负责：消息路由、会话管理、鉴权、Web 控制台          │└──────────────────────┬──────────────────────────────┘                       │ 内部调度┌──────────────────────▼──────────────────────────────┐│                 Pi Agent（执行层）                    ││   Agent 运行时，处理 LLM 调用 + 工具执行              ││   读取 AGENTS.md / SKILLS.md 组装上下文              │└──────────────────────┬──────────────────────────────┘                       │ HTTPS API┌──────────────────────▼──────────────────────────────┐│         MiniMax M2.5（Intelligence 层）               ││   api.minimaxi.com（国内）/ api.minimax.io（国际）   │└─────────────────────────────────────────────────────┘

飞书接入的一个好消息：飞书插件使用 WebSocket 长连接接收事件，不需要你把 Gateway 暴露在公网上，这解决了国内用户最头疼的「怎么配公网 IP + Nginx + HTTPS」问题。直接在内网机器或本地跑就行。

2.2 核心概念速查

概念	是什么	一句话记忆
Gateway	整个系统的控制中心，单进程运行	家里的路由器
Channel	接入的聊天平台（飞书就是一个 Channel）	路由器上插的网线
Session	每个对话窗口对应的独立会话	不同的聊天窗口，记忆互相隔离
Workspace	Agent 的工作目录，存放文件和记忆	Agent 的「桌面文件夹」
Skill	一个 SKILL.md 文件，教 Agent 用某个工具	操作手册，按需取用
Pi	底层的 Agent 运行时框架（处理 LLM 循环）	发动机，OpenClaw 是车壳
Heartbeat	定时运行的自检清单，Agent 可主动推消息	闹钟 + 汇报机制

2.3 Skills 系统：「按需加载」的设计哲学

这是 OpenClaw 最值得深入理解的设计。

每个 Skill 是一个 Markdown 文件，带有 YAML 元信息。Agent 启动时只加载所有 Skill 的名称和描述（平均约 97 个字符/个）。当用户消息命中某个 Skill 的触发词时，才把完整的 Skill 内容注入到当前 context 中。

用户: "帮我搜一下..."         ↓Agent 扫描所有 Skill 描述，发现 web-search Skill 被触发         ↓完整的 web-search Skill 内容（含详细使用指令）被注入 context         ↓MiniMax M2.5 看到完整指令后调用搜索工具

这种渐进式披露避免了一个常见问题：如果把所有工具定义一股脑塞进 system prompt，一个典型的 Playwright 工具集就要占用约 13,700 个 token——还没开口说话，上下文窗口就浪费了一大截。

对于国内用户来说，节省 token = 直接省钱。

第三章：How —— 手把手安装配置

3.1 环境准备

# 检查 Node 版本，需要 22.16+，推荐 Node 24node --version# 如果版本不符，用 nvm 安装nvm install 24 && nvm use 24

3.2 一键安装 OpenClaw

# macOS / Linuxcurl -fsSL https://openclaw.ai/install.sh | bash# Windows (PowerShell)iwr -useb https://openclaw.ai/install.ps1 | iex

3.3 初始化向导 + 配置 MiniMax

MiniMax 官方在其 Coding Plan 文档中提供了官方的 OpenClaw 接入教程，步骤非常清晰：

openclaw onboard --install-daemon

--install-daemon 参数让 Gateway 注册为系统服务，开机自启。

向导步骤（按提示依次操作）：

选择「QuickStart」模式（快速引导）；
模型提供商选择「MiniMax」；
认证方式选择「MiniMax OAuth」（推荐，Token 自动刷新，无需手动管理 API Key 的过期问题）；
区域选择「CN」（中国用户选这个，使用 api.minimaxi.com 国内端点，访问更稳定）；
浏览器自动打开 MiniMax 平台，登录并点击「授权」；
回到终端，确认模型选择（M2.5 默认已选中），回车继续；
Channel 接入先跳过，后面专门配置飞书。

验证安装：

openclaw gateway status    # 检查 Gateway 是否运行openclaw dashboard         # 打开浏览器控制台，快速验证是否可以对话

如果浏览器能打开 http://127.0.0.1:18789/ 并能聊天，说明 Gateway + MiniMax 都正常了。

也可以手动配置 API Key 方式（如果你更喜欢显式管理密钥）：

在 ~/.openclaw/openclaw.json 中添加：

{"env": {"MINIMAX_API_KEY": "你的MiniMax API Key"  },"agents": {"defaults": {"model": {"primary": "minimax/MiniMax-M2.5"      }    }  },"models": {"mode": "merge","providers": {"minimax": {"baseUrl": "https://api.minimaxi.com/anthropic","apiKey": "MINIMAX_API_KEY","api": "anthropic-messages"      }    }  }}

注意：apiKey 的值是环境变量的名称字符串（"MINIMAX_API_KEY"），不是 shell 风格的 ${VAR} 语法。写成 "${MINIMAX_API_KEY}" 会被当作字面字符串，导致鉴权失败。这是文档中明确标注的常见错误。

3.4 接入飞书：手把手配置

这是本文的核心环节。飞书接入分为三步：在飞书开放平台创建应用 → 运行 openclaw channels add → CLI 配对。

Step 1：在飞书开放平台创建机器人应用

❝
📖 官方中文配置文档：openclawlab.com/zh-cn/docs/channels/feishu/

访问 open.feishu.cn/app，登录飞书账号；
点击「创建企业自建应用」，填写名称（比如「我的 AI 助手」）和描述；
进入应用，打开「凭证与基础信息」，复制 App ID（格式 cli_xxx）和 App Secret，找个地方先记下来；

进入「权限管理」，点击右上角「批量导入」按钮，粘贴以下 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"    ]  }}

进入「应用功能 → 机器人」，开启机器人能力；
进入「事件订阅」，选择「使用长连接接收事件」（⚠️ 最容易漏的一步！不选就收不到任何消息），添加事件 im.message.receive_v1；
发布应用：「版本管理与发布」→ 创建版本 → 申请发布（企业内部应用基本秒过）。

Step 2：运行 `openclaw channels add`（推荐方式）

打开终端，运行：

openclaw channels add

这是一个全交互式向导，全程跟着提示走，不需要手动编辑任何文件：

◇ Select a channel│ Feishu/Lark (飞书)            ← 选这个◇ Install Feishu plugin?│ Download from npm (@openclaw/feishu)   ← 选这个，自动下载安装插件◇ App ID│ cli_你的AppID                ← 粘贴 App ID◇ App Secret│ ********************************      ← 粘贴 App Secret（会打码显示）◇ Domain│ feishu (China)               ← 国内用户选这个；Lark 国际版选 lark

向导完成后，OpenClaw 会自动把所有配置写入 ~/.openclaw/openclaw.json，并下载好飞书插件。然后重启网关让配置生效：

openclaw gateway restart

❝
已知 bug 提示：如果在插件下载步骤报错 EUNSUPPORTEDPROTOCOL，这是 @openclaw/feishu npm 包里 workspace:* 依赖写法的问题（已有 GitHub issue #14042 跟踪）。临时解决方案：手动进入插件目录安装依赖：
cd ~/.openclaw/extensions/feishunpm install --legacy-peer-depsopenclaw gateway restart

Step 3：CLI 配对——这步不一样，别跳过！

❝
⚠️ 和其他 Channel 不同：飞书的配对不是「在聊天框里发回配对码」，而是需要在终端里用 CLI 命令审批。

配置完成并重启后，在飞书里找到你的机器人，发一条消息。机器人会回复一串配对码（类似 PAIR-a1b2c3），同时你的终端里也会打印出等待审批的提示。

在终端执行以下命令完成配对：

# 查看所有待配对请求openclaw pairing list# 批准指定的配对请求（把 <code> 替换成实际的配对码）openclaw pairing approve <code>

配对成功后，飞书里机器人会发送确认消息，从此你的每条私信都会被 Agent 处理。

验证一切正常：

# 实时查看网关日志，确认消息收发正常openclaw logs --follow

想调整更多参数？ 向导完成后，用 config set 追加配置：

# 私聊策略：pairing（需配对，默认）| open（所有人可用）| allowlist（白名单）openclaw config set channels.feishu.dmPolicy "pairing"# 流式卡片回复标题openclaw config set channels.feishu.streamingCard.title "正在思考..."

每次修改后 openclaw gateway restart 生效。

完整配置长什么样？channels add 向导会自动生成，你也可以在 ~/.openclaw/openclaw.json 中查看和手动微调：

{"channels": {"feishu": {"enabled": true,"domain": "feishu","connectionMode": "websocket","dmPolicy": "pairing","streaming": true,"streamingCard": {"enabled": true,"title": "正在思考..."      },"accounts": {"main": {"appId": "cli_你的AppID","appSecretFile": "~/.secrets/feishu_app_secret","botName": "我的AI助手"        }      }    }  }}

安全提示：JSON 里建议用 appSecretFile 代替明文 appSecret，防止密钥随配置文件误传到 Git。

第四章：进阶实践

4.1 飞书群聊：让 AI 成为团队助手

把机器人加入飞书群后，建议配置「@提及才响应」：

{"channels": {"feishu": {"groups": {"oc_你的群ID": {"requireMention": true,"groupPolicy": "allowlist"        }      }    }  }}

怎么找到群 ID？ 启动 Gateway 后，在目标群里 @一下机器人，然后运行 openclaw logs --follow，日志里会打出 oc_xxx 格式的群 ID。

groupPolicy: "allowlist" 表示只有白名单用户才能触发机器人，在团队场景下非常有用——研发群里只有技术同学能发指令，避免误触发。

4.2 流式卡片输出

配置好 streamingCard 后，AI 的回复会以飞书互动卡片的形式展示，代码块会有语法高亮，表格会正确渲染，而不是一堆 Markdown 原始符号。

如果你想让 AI 主动发送一个结构化卡片（比如汇报、状态更新），可以在 Skill 中使用 feishu_card 工具：

{"tool": "feishu_card","args": {"title": "每日代码巡检报告","titleTemplate": "green","elements": [      { "tag": "markdown", "content": "**状态**: 全部通过 ✅\n**覆盖率**: 87%" }    ]  }}

卡片标题颜色支持：blue、green、yellow、orange、red、purple 等，可以用颜色区分不同类型的通知。

4.3 自定义 Skill：打造你的专属工具

在 ~/.openclaw/workspace/skills/ 下创建一个文件夹，放入 SKILL.md：

---name: feishu-daily-reportdescription: 生成并发送飞书日报，汇总代码提交、任务完成和明日计划triggers:  - 日报  - 日报总结  - daily report  - 发日报---# 飞书日报 Skill当用户请求生成日报时：1. 运行 `git log --oneline --since=yesterday --author=$(git config user.email)` 获取今日提交；2. 读取工作区 `TODO.md` 中标注了 `[x]` 的已完成任务；3. 用中文生成日报，格式：   - **今日完成**：列出提交和任务；   - **明日计划**：读取未完成的 `[ ]` 任务前三条；   - **风险与阻塞**：如无，写「暂无」；4. 用 `feishu_card` 工具以绿色标题卡片的形式发送。

保存后约 250ms 热重载生效，无需重启 Gateway。

4.4 心跳任务：AI 主动找你

在 Workspace 根目录创建 HEARTBEAT.md，Gateway 默认每 30 分钟运行一次：

# 心跳任务清单- 检查 `/var/log/app/error.log` 最后 50 行，如有 ERROR 级别日志，立即通过飞书推送告警- 如果当前时间是工作日 17:30，自动调用「日报 Skill」生成并发送日报- 每周一 09:00，读取本周 OKR 文档，生成本周关键任务摘要并推送到飞书

这是 OpenClaw 和「普通 AI 聊天机器人」最本质的区别：它能主动工作，不只是被动等你问。

4.5 多 Agent 路由：私人助手 vs 工作助手

你可以把不同的飞书对话（私信、群聊）路由到不同的 Agent，彼此会话历史和记忆完全隔离：

{"agents": {"list": [      { "id": "personal", "workspace": "~/.openclaw/workspace-personal" },      { "id": "work",     "workspace": "~/.openclaw/workspace-work" }    ]  },"bindings": [    {"agentId": "personal","match": { "channel": "feishu", "peer": { "kind": "direct", "id": "ou_你的飞书用户ID" } }    },    {"agentId": "work","match": { "channel": "feishu", "peer": { "kind": "group", "id": "oc_工作群ID" } }    }  ]}

私信走「个人助手 Agent」，工作群走「工作 Agent」，两套记忆互不干扰，就像公私两个手机分开用一样清爽。

第五章：常见误区

❌ 误区一：OpenClaw 会把我的数据上传到 MiniMax

真相：只有你和 AI 的对话内容会发送给 MiniMax API（用于推理），这和直接调用任何大模型 API 没有区别。你的文件、会话历史、配置、Skill 都存在本地，不经过 MiniMax 服务器。

❌ 误区二：飞书接入必须有公网 IP

真相：飞书的 WebSocket 长连接模式（connectionMode: "websocket"）是由你的机器主动连接飞书服务器，不需要飞书服务器来访问你。只要你的机器能访问公网，飞书就能接收消息。内网机器、家里的电脑、公司没有公网 IP 的服务器，都可以。

❌ 误区三：`apiKey` 要写成 `"${MINIMAX_API_KEY}"`

真相：OpenClaw 的配置里，apiKey 的值应该是环境变量的名称本身（例如 "MINIMAX_API_KEY"），不是 shell 风格的 ${VAR} 语法。写成 "${MINIMAX_API_KEY}" 会被当作字面字符串，导致鉴权失败。这是官方文档中特别标注的常见错误。

❌ 误区四：飞书群里不设置 `requireMention`

如果群里 100 个人在聊天，你的 Bot 对每条消息都响应，API 费用会在你不知情的情况下飞涨，会话历史也会变成一锅粥。**群聊一定要开启 requireMention: true**，只在被 @ 时才响应。

❌ 误区五：把 AppSecret 硬编码在配置文件里然后上传 Git

飞书的 appSecret 是高权限凭证，一旦泄露，任何人都可以用你的机器人发消息。正确做法：

{"channels": {"feishu": {"accounts": {"main": {"appId": "cli_xxx","appSecretFile": "~/.secrets/feishu_app_secret"        }      }    }  }}

使用 appSecretFile 从外部文件读取 Secret，然后把 ~/.secrets/ 加入 .gitignore。

❌ 误区六：MiniMax M2.5 不适合「轻量任务」

真相：M2.5 有一个高速版 MiniMax-M2.5-highspeed，响应更快，适合简单问答。可以配置 fallback 策略，让 OpenClaw 根据需要自动切换：

{"agents": {"defaults": {"model": {"primary": "minimax/MiniMax-M2.5","fallbacks": ["minimax/MiniMax-M2.5-highspeed"]      }    }  }}

第六章：安全配置 Checklist

# 快速诊断安全配置问题openclaw doctor

然后对照以下清单手动核查：

[ ] 飞书私信访问限制：配置 dmPolicy: "pairing" 或 "allowlist"，防止陌生人触发你的 Agent；
[ ] 群聊 @提及限制：所有群都设置 requireMention: true；
[ ] AppSecret 不入 Git：使用 appSecretFile 从文件读取；
[ ] MiniMax API Key 用环境变量：放在 env 块或系统环境变量中，不硬编码明文；
[ ] Gateway 不暴露公网：飞书用 WebSocket 模式，无需开放端口；如需远程访问 Web 控制台，用 SSH 隧道；
[ ] 定期更新：npm update -g openclaw，关注安全更新；
[ ] 备份配置：定期备份 ~/.openclaw 目录（包含所有配置、Skill、记忆）。

第七章：完整配置文件示例

以下是一个面向中国用户的「开箱即用」完整配置参考：

{"env": {"MINIMAX_API_KEY": "sk-你的MiniMax密钥"  },"agents": {"defaults": {"model": {"primary": "minimax/MiniMax-M2.5","fallbacks": ["minimax/MiniMax-M2.5-highspeed"]      }    }  },"models": {"mode": "merge","providers": {"minimax": {"baseUrl": "https://api.minimaxi.com/anthropic","apiKey": "MINIMAX_API_KEY","api": "anthropic-messages"      }    }  },"channels": {"feishu": {"enabled": true,"domain": "feishu","connectionMode": "websocket","dmPolicy": "pairing","streaming": true,"streamingCard": {"enabled": true,"title": "正在思考..."      },"accounts": {"main": {"appId": "cli_你的AppID","appSecretFile": "~/.secrets/feishu_app_secret","botName": "我的AI助手"        }      },"groups": {"oc_你的工作群ID": {"requireMention": true,"groupPolicy": "allowlist"        }      }    }  }}

结语：龙虾的国产化之路

OpenClaw 在 2026 年初以惊人速度冲到 20 万+ GitHub Star，成为有史以来增长最快的开源项目之一。在国内，它的别名叫「养龙虾」，MiniMax 也因此跟着火了一把——两者之间的热度形成了正反馈，MiniMax 甚至专门推出了 MaxClaw，一个基于 OpenClaw 的云托管版本。

这说明一件事：解决了真实痛点的东西，最终都会被人找到。

对中国用户来说，飞书 + MiniMax M2.5 这个组合几乎是最顺畅的起点：飞书是你本来就在用的工具，MiniMax 是国内访问最稳定、性价比最高的顶尖模型之一，WebSocket 长连接意味着零公网 IP 烦恼，而 OpenClaw 把它们优雅地粘合在一起。

去吧，打开终端，一条命令，让你的飞书变成真正的 AI 工作台。🦞

快速参考

命令	用途
`openclaw onboard --install-daemon`	初始化 + 安装系统服务
`openclaw gateway status`	查看 Gateway 运行状态
`openclaw gateway restart`	修改配置后重启
`openclaw dashboard`	打开浏览器控制台
`openclaw plugins install @openclaw/feishu`	安装飞书插件
`openclaw logs --follow`	实时查看日志（调试用）
`openclaw doctor`	安全配置诊断
`openclaw configure`	交互式修改配置

官方资源：

OpenClaw 文档：https://docs.openclaw.ai
飞书 Channel 文档：https://docs.openclaw.ai/channels/feishu
MiniMax Coding Plan：https://platform.minimax.io/docs/coding-plan/intro
MiniMax × OpenClaw 官方教程：https://platform.minimax.io/docs/coding-plan/openclaw
OpenClaw GitHub：https://github.com/openclaw/openclaw

本文基于 OpenClaw 2026.x + MiniMax M2.5 + 飞书开放平台当前版本编写。部分配置项可能随版本更新变化，请以官方文档为准。