openclaw helloworld 20260304
0. 准备
最近研究怎么在飞书上搞个智能助手，翻了不少教程，发现大家提到的要点五花八门，操作系统、软件版本、安装方式，各有各的说法。干脆自己动手，把这一路上的坑都踩了一遍，整理出来，希望能帮后来的朋友少走点弯路。
先说下我的基础环境：MacOS系统，Node.js、npm、Git这些基础工具都已经就绪。
第一步，得有个“大脑”。找个大模型平台注册一下，拿个API Key。图方便，我先用了智谱AI，新用户送2000万tokens，拿来测试完全够用，跑通了再换成别的模型或者本地部署的都行。
对了，为了安装顺利，最好先把npm源换成国内的，速度会快很多：
npm config set registry https://registry.npmmirror.com
还有一个关键权限问题：在Mac的「系统设置」→「隐私与安全性」→「完全磁盘访问权限」里，务必把VSCode勾选上（前提是你跟我一样，主要在VSCode的终端里操作）。为什么要提这个？因为过程中难免会遇到文件权限问题，一着急可能就用了sudo或者切到root用户。但这样做，在执行openclaw onboard安装网关（Gateway）时反而会报错。经验表明，别用sudo执行onboard，只要给VSCode开了磁盘访问权限，一路绿灯。
1. 安装OpenClaw
基础打好，就可以安装核心框架了：
sudo npm install -g openclaw@latest
2. 初始化OpenClaw
安装完成后，需要初始化配置。记住前面说的，别加sudo：
openclaw onboard --install-daemon
接着会出现一系列交互式配置选项，我的选择如下，供你参考：
I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?: Yes
Onboarding mode: QuickStart
Config handling: Update values
Model/auth provider: Z.AI
（按提示输入api_key）
Default model: keep current
select channel: skip for now
configure skills now?: no
Enable hooks: Skip for now
How do you want to hatch your bot?: Hatch in TUI
配置完，一个基础的OpenClaw机器人就在你的终端里“孵化”出来了，可以直接用文字和它对话测试。
3. 创建飞书机器人
想让机器人在飞书里工作，得先在飞书开放平台（https://open.feishu.cn/）创建一个应用。
流程很直接：进入「开发者后台」→「创建企业自建应用」→ 填好应用信息并创建。
创建后，核心是添加机器人的权限。进入应用的「权限管理」页面，选择「批量导入」，把下面这段JSON粘贴进去：
{"scopes": {"tenant": ["contact:user.base:readonly","im:chat:readonly","im:message","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:message:recall","im:message:send_as_bot","im:message:send_multi_depts","im:message:send_multi_users","im:message:send_sys_msg","im:message:update","im:resource"],"user": []}}
导入成功后，记得去「创建版本」并「发布」。每次修改配置，都需要走一遍这个“创建版本-发布”的流程。完成后，在「凭证与基础信息」里就能拿到关键的 App ID 和 App Secret，后面配置插件要用。
4. 安装飞书插件
OpenClaw本身只是个框架，要接入飞书，需要专门的通道插件。用的是社区开发的这个：https://github.com/m1heng/clawdbot-feishu
安装命令：
openclaw plugins install @m1heng-clawd/feishu
这里可能会遇到一个典型的坑：安装时报告 npm install failed，通常是插件依赖安装权限不足。解决方法有两种：一种是直接给安装命令加sudo（我没试）；另一种是手动进入插件目录安装依赖：
cd ~/.openclaw/extensions/feishu
sudo pnpm install
5. 飞书插件配置
插件装好，接下来是把飞书应用的凭证和机器人行为规则告诉OpenClaw，通过一系列配置命令完成：
openclaw config set channels.feishu.appId ""
openclaw config set channels.feishu.appSecret ""
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.connectionMode websocket
openclaw config set channels.feishu.dmPolicy pairing # 私聊策略设为“需授权”，也可设为 open
openclaw config set channels.feishu.groupPolicy allowlist
openclaw config set channels.feishu.requireMention true
敲黑板：每次修改完OpenClaw的配置，都必须重启网关服务才能生效：
openclaw gateway restart
6. 飞书机器人事件与回调配置
回到飞书开放平台的应用配置页，还有关键两步：
事件订阅：在相应页面，订阅方式选择“长连接”，然后添加以下事件：im.message.receive_v1（接收消息）、im.message.message_read_v1、im.chat.member.bot.added_v1（机器人被加入群聊）、im.chat.member.bot.deleted_v1（机器人被移除）。
回调配置：同样，在回调配置页面，将订阅方式设置为“长连接”。
配置完毕后，别忘记再次「创建版本」并「发布」。
7. 飞书内测试
发布成功后，飞书的「开发小助手」会发来消息通知。点击消息里的“打开应用”按钮，就能跳转到和机器人的聊天窗口。
如果你在第5步将dmPolicy设为了pairing（推荐，更安全），第一次私聊机器人时，它会回复一个授权ID。你需要回到终端，执行批准命令：
openclaw pairing approve feishu
批准后，在飞书里就可以正常和你的OpenClaw机器人对话了。
8. 问题：OpenClaw无法更新记忆文件
用着用着发现，机器人的对话历史没有被保存下来。这是因为初始化时，没有给它开启文件操作相关的工具（Tools）权限。
尝试过直接修改配置文件openclaw.json，在tools部分增加文件操作权限，但实测发现不生效：
{
tools: {
profile: "messaging",
allow: ["group:fs"] // 增加文件相关操作，直接在配置文件中修改，好像是不行的。
},
}
更有效的方式是通过命令行，将工具权限配置文件改为“完全”模式：
openclaw config set tools.profile "full"
执行后重启网关，机器人就能记住对话上下文了。
9. 其他内置技能
除了基础对话，OpenClaw还有一些内置技能。比如定时任务（Scheduler）很好用，可以设置定时提醒起来喝水活动一下。
网页搜索（Web Search）功能暂时没跑通，但内置的查天气技能是正常的。
10. ClawHub：扩展技能库
内置技能不够用？可以上ClawHub看看，这是一个OpenClaw的技能市场。先试一个搜索技能tavily-search。
安装命令：
sudo npx clawhub@latest install tavily-search
注意，这个命令第一次运行时，会先安装ClawHub客户端本身，之后再安装技能就可以直接用clawhub install了。
安装后，需要去Tavily官网注册并获取一个API_KEY。然后在OpenClaw的配置目录下（~/.openclaw/）新建或编辑.env文件，加入一行：
TAVILY_API_KEY="tvly-dev-xxx"
配置完，惯例：openclaw gateway restart。
重启后测试，可能会遇到一点小波折：机器人可能还会说没安装Tavily技能。
别急，可能只是服务加载慢了。我多等了一下，再次重启网关，就恢复正常了。
不过得提个醒：搜索技能非常消耗tokens。我的智谱AI赠送的2000万tokens，主要分配在不同的模型额度下，用起来得心里有数。
11. Todo
至此，一个能在飞书里对话、有记忆、能查资料的基本款智能助手就搭建完成了。当然，这只是起点，后面还有很多可以探索：
- 更换LLM API：换成其他平台（如DeepSeek、Moonshot），或者接入自己用vLLM部署的本地模型。
- 环境迁移：研究如何把配置好的OpenClaw完整地迁移到另一台机器。
- 技能探索：在ClawHub上发掘更多实用技能，比如联网搜索、文档总结等。
- 深度调教：让OpenClaw学习你的习惯，成为更懂你的工作伙伴。
参考文档
过程中参考了一些优秀的文档，也一并列出来，方便你深入查阅：
- OpenClaw 到底怎么装？一篇纯小白也能成功部署的超详细教程：非常详细的基础安装指引。
- OpenClaw GitHub | Docs：官方文档，查询配置项和更新信息最权威。
- 飞书插件 GitHub 仓库：了解插件最新特性和问题反馈。