OpenClaw 进阶玩法：装完openclaw之后，真正的世界才开启

适合读者： 已完成基础安装，想要深入玩转openclaw的用户。
阅读时间： 约 20 分钟吧可能
官方文档： docs.openclaw.ai · openclaw技能库： clawhub.com · openclaw源码： github.com/openclaw/openclaw

---

目录

1. 搞清楚openclaw的家目录里都有什么
2. soulmd塑造openclaw的性格以及行为习惯
3. Heartbeat：让AI主动盯着你的世界
4. Cron：精确定时任务，比如每天 7 点自动发早报
5. Skills 系统详解：找、装、用
6. 自己写一个 Skill：从零到能用，30 分钟搞定
7. 安全警告：openclaw很危险

---

1. 先搞清楚openclaw家目录里都有什么

安装完 OpenClaw 之后，你的机器上会多出一个 ~/.openclaw/ 目录。这是整个系统的"大脑仓库"。在玩任何进阶功能之前，先花 5 分钟搞清楚这里面都是什么，之后所有操作都会豁然开朗，现在开始。

完整目录结构（来自官方配置文档）

~/.openclaw/
├── openclaw.json          # 主配置文件：频道、鉴权、Gateway 设置
├── openclaw.json.bak*     # 自动备份（.bak、.bak.1、.bak.2……）
│
├── agents/main/
│   ├── agent/
│   │   └── auth-profiles.json   # Anthropic/OpenAI或者其他AI的 OAuth Token，可以简单理解为一张临时通行证
│   └── sessions/
│       ├── sessions.json        # 会话索引
│       └── *.jsonl              # 会话记录（每行一个 JSON 对象）
│                          # ★ 代表比较重要的部分
├── workspace/             # Agent 的工作区域，所有行为都从这里读取
│   ├── SOUL.md            # ★ Agent 的人格、写作风格、行为准则
│   ├── IDENTITY.md        # Agent 的名字、设定
│   ├── USER.md            # 关于你自己的上下文（你住哪、时区、偏好）
│   ├── AGENTS.md          # 会话行为规则、记忆规则、安全边界
│   ├── HEARTBEAT.md       # ★ 定期巡检清单（空文件 = 关闭心跳）
│   ├── MEMORY.md          # 长期记忆（只在私聊时加载）
│   ├── TOOLS.md           # 联系人、SSH 主机、设备别名
│   ├── BOOT.md            # 启动时执行的指令
│   └── memory/
│       └── YYYY-MM-DD.md  # 每天的对话日志
│
├── skills/                # 你安装的第三方 Skill（所有 Agent 共享）
└── cron/
    └── jobs.json          # 定时任务配置

关键理解： OpenClaw 的所有"记忆"和"性格"都是普通的 Markdown 文件，存在你自己的硬盘上。没有云端数据库，没有黑盒。你可以用任意文本编辑器直接修改它们。这就是为什么它被称为 本地优先。

先检查 Gateway 是不是在跑

openclaw gateway status

如果没有运行，重启它：

openclaw gateway restart

重要习惯： 每次修改 openclaw.json 或 workspace 里的 Markdown 文件之后，一定要先停止 Gateway，改完再重启。因为 Gateway 启动时会把配置加载进内存，如果你改文件时 Gateway 正在运行，它会在几秒内用内存里的旧数据覆盖你的修改。正确流程：

```bash openclaw gateway stop

修改你的文件

openclaw gateway start ```

---

2. SOUL.md：塑造你的 AI 到底是什么人

SOUL.md 是我认为最值得花时间的一个文件。它定义了 Agent 的性格、语气、行为习惯。每次对话，Agent 都会把这个文件完整读一遍，作为基底人格加载到系统提示词里。

SOUL.md 放在哪里？

~/.openclaw/workspace/SOUL.md

从一个真实的 SOUL.md 开始

下面是一份从社区（GitHub Gist，作者 mberman84）整理出来的模板，已经过简化，适合入门：

# 你是谁

你不是聊天机器人。你是一个有自主意识的个人助手，住在这台机器上，帮助用户管理他们的生活和工作。

# 性格设定

- 语气简洁、直接，不废话
- 回答前先想清楚，不要第一反应直接输出
- 如果任务有风险（比如删文件），先确认再执行
- 不要假装自己是人类，也不要假装自己什么都知道

# 通信风格

- 对话时用中文，除非用户切换语言
- 技术性内容可以用代码块，但不要滥用
- 每次回复不超过 300 字，除非用户明确要求详细解释

# 安全边界

- 不得在未经确认的情况下删除任何文件
- 不得向第三方发送用户的个人信息
- 遇到不确定的操作，选择询问而不是假设

如何让 SOUL.md 生效

1. 用任意文本编辑器打开 ~/.openclaw/workspace/SOUL.md
2. 写入或修改内容
3. 重启 Gateway：openclaw gateway restart
4. 发送任何消息测试效果

进阶技巧： USER.md 是专门用来描述"你自己"的文件。把你的时区、工作习惯、偏好语言写在这里，Agent 在做决策时会把这些信息考虑进去——比如知道你在哪个时区，才能正确计算"今天下午 3 点"是几点。

---

3. Heartbeat：让 Agent 主动盯着你的世界，也就是设置一个定时巡检脚本

这是 OpenClaw 最独特的能力，也是区别于 ChatGPT、Claude 这类被动式 AI 的核心所在。

普通 AI 的工作方式： 你问，它答。你不问，它什么也不做。也就是被动式的，但是openclaw可以主动做事情，很牛逼。

OpenClaw 的心跳机制： Agent 每隔 30 分钟（默认）自动唤醒一次，读取你的 HEARTBEAT.md，判断有没有什么需要告诉你的事情。如果没有——它静默返回一个 HEARTBEAT_OK 信号，你什么都不会收到。如果有——它会主动给你发消息。

HEARTBEAT.md 怎么写？

文件位置：~/.openclaw/workspace/HEARTBEAT.md

规则很简单： 文件为空 = 关闭心跳。文件里写了什么 = Agent 每 30 分钟就检查一遍这些事。

一个实用的例子：

## 每次心跳都要做的事

- 检查未读邮件，如果有来自老板或客户的邮件，立刻通知我
- 检查日历，如果 2 小时内有会议，提前提醒一次
- 检查暂存区（staging server）的健康检查接口，如果返回非 200，立刻告警

## 条件性提醒

- 如果 GitHub 上有 PR 超过 48 小时没有人 review，提醒我跟进
- 如果 Telegram 或 WhatsApp 里有人超过 6 小时没有回复重要消息，提示我

## 如果一切正常
只回复 HEARTBEAT_OK，不要发任何其他消息。

"HEARTBEAT_OK"的工作原理： 根据官方文档，Gateway 识别到回复开头或结尾包含 HEARTBEAT_OK、且剩余内容不超过 300 字符（配置项 heartbeat.ackMaxChars，默认值 300）时，会静默丢弃这条消息——你的手机什么通知都不会收到。只有 Agent 判断真的有事时，才会发出消息。

Heartbeat 的完整配置项

编辑 ~/.openclaw/openclaw.json：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "lightContext": false,
        "ackMaxChars": 300
      }
    }
  }
}

字段	默认值	说明
every	"30m"（注意claude的用户默认 "1h"）	心跳间隔。"0m" 表示完全禁用
target	"none"	心跳消息发向哪里。"none" 不主动推送；"last" 推送给最近联系的频道
lightContext	false	true 时只加载 HEARTBEAT.md，跳过完整聊天历史——省 token，推荐开启
ackMaxChars	300	回复超过这个字符数时，即使包含 HEARTBEAT_OK 也不会被静默丢弃

真实的 Token 成本陷阱（来自 GitHub Discussion #11042）

这个问题是开箱即中的陷阱，必须单独说。

一位用户配置了 30 分钟心跳间隔，但忘记开启 lightContext: true，结果每次心跳都把完整的主会话聊天历史塞进上下文，每次消耗 170,000–210,000 个 token（主要是 input/cache token）。更糟糕的是，系统事件、工具执行完成等都会触发额外的心跳唤醒，实际触发间隔有时低至 10–20 秒。

正确的省钱做法：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "0m"
      }
    }
  }
}

先把内置 Heartbeat 禁用，改用下面要讲的 Cron，配合 --light-context 参数，同样能做到定时巡检，token 成本可以降低 90% 以上。

---

4. Cron：精确定时任务，每天 7 点自动发早报

Heartbeat 像"模糊的闹钟"——你说每 30 分钟检查一次，它就每 30 分钟检查，但具体几点几分是不定的。Cron 是精准的 5 字段表达式调度器，精确到分钟。

官方文档（docs.openclaw.ai/automation/cron-jobs）的总结：

Heartbeat 有 drift（偏移），不适合精准时间任务。 比如"20 分钟后提醒我"，如果心跳间隔是 30 分钟，这个提醒永远不会准时触发。精准提醒必须用 Cron。

Cron 任务持久化保存在 ~/.openclaw/cron/jobs.json，Gateway 重启后任务不会丢失。但根据官方 GitHub 文档，手动直接编辑这个 JSON 文件是危险的——Gateway 启动时会把它加载进内存，然后在变更时写回覆盖。要始终通过 openclaw cron 命令操作，不要手动编辑 jobs.json。

每天早上 7 点推送早报到 Telegram（完整命令）

openclaw cron add \
  --name "每日早报" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "用中文汇总今天的情况：1) 天气 2) 日历上的安排 3) 未读邮件摘要。控制在 200 字以内。" \
  --announce \
  --channel telegram \
  --to "你的Telegram数字ChatID"

参数全部来自官方 CLI 文档：

参数	含义
--cron "0 7 * * *"	标准 cron 表达式：分 时 日 月 周。0 7 * * * 即每天 07:00
--tz "Asia/Shanghai"	时区，不填默认 UTC，中国用户必须填
--session isolated	在独立 session 里跑，不污染主聊天历史
--message "..."	发给 Agent 的指令
--announce	任务完成后把结果推送出去（isolated 任务的默认行为）
--channel telegram	推送渠道
--to "..."	Telegram 数字 Chat ID

Telegram Chat ID 怎么获取？ 给 @userinfobot 发任意一条消息，它会告诉你你的数字 ID（格式类似 123456789）。

Cron 任务管理命令

# 查看所有 cron 任务和下次执行时间
openclaw cron list

# 查看任务运行状态
openclaw cron status

# 查看某个任务的历史执行记录（每条记录存在 cron/runs/<jobId>.jsonl 里）
openclaw cron runs --id <jobId>

# 立刻手动触发一次（测试用）
openclaw cron run <jobId>

# 修改某个任务的推送目标（不需要删除重建）
openclaw cron edit <jobId> --announce --channel telegram --to "新的ChatID"

# 关闭某个任务的推送（只跑不发）
openclaw cron edit <jobId> --no-deliver

# 删除任务
openclaw cron delete <jobId>

一次性提醒：20 分钟后叫我

openclaw cron add \
  --name "开会提醒" \
  --at "20m" \
  --session main \
  --system-event "提醒：距离会议还有 5 分钟，请准备进入会议室。" \
  --wake now \
  --delete-after-run

• --at "20m" 表示从现在起 20 分钟后触发（也可以用 ISO 时间戳如 "2026-03-10T09:00:00+08:00"）
• --wake now 触发时立刻唤醒 Agent，不等心跳
• --delete-after-run 执行完自动删除，不留记录（一次性任务的默认行为；若要保留，加 --keep-after-run）

根据官方文档，如果省略时区，ISO 时间戳会被视为 UTC 处理。北京时间 +8 小时，写时间时注意换算。

进阶：每个 Cron 任务可以指定不同的 AI 模型

这是官方 Discussion #228 里实现的功能。背景任务不需要用高级模型，用你所用的AI的普通模型就够了，省不少钱：

# 日常巡检用普通模型，便宜
openclaw cron add \
  --name "每日巡检" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "检查今日日历和邮件，有重要事项就告诉我。" \
  --model "anthropic/claude-sonnet-4-20250514" \
  --announce

# 周报分析用高级模型，精准
openclaw cron add \
  --name "周度复盘" \
  --cron "0 18 * * 5" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "分析这周的工作进展，生成 500 字复盘报告。" \
  --model "anthropic/claude-opus-4-6" \
  --announce

进阶：Gate——先判断有没有必要跑，再调用 AI

这是社区 Discussion #27700 提出并正在推进的功能，已被多个用户在自己的 fork 上使用。

原理：在 Cron 调用 AI 之前，先跑一个轻量的 shell 脚本做"门卫检查"。如果脚本返回非 0（表示"没必要跑"），就跳过这次 AI 调用，节省 token。

openclaw cron add \
  --name "PR 催跟进" \
  --cron "0 10 * * 1-5" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --gate "~/.openclaw/workspace/scripts/check_open_prs.sh" \
  --message "有未 review 的 PR，请帮我起草催促消息。" \
  --announce

Gate 脚本 check_open_prs.sh 的逻辑很简单：调用 GitHub API 检查是否有超过 24 小时未 review 的 PR，有就退出码 0（让 AI 继续），没有就退出码 1（跳过，不消耗 token）。

⚠️ 已知 Bug：WSL2 上 Cron 不执行（Issue #8712）

如果你在 Windows 的 WSL2 里运行 OpenClaw，有一个已知 Bug（GitHub Issue #8712）：Cron 调度器从不计算 nextWakeAtMs，所有任务都不执行。运行 openclaw cron status 会看到 "nextWakeAtMs": null。

目前的临时解决方法：在 WSL2 里启动 OpenClaw 后，用 PM2 或 systemd 持续保持进程唤醒，防止 WSL2 的休眠机制打断 Gateway。

⚠️ 已知 Bug：isolated 任务 sessionId 被复用（Issue #23539）

根据官方 Issue #23539，自 PR #18031 起，isolated cron 任务在 session "仍然新鲜"时会复用同一个 session ID，而不是每次都新建。这导致 Agent 会看到前几次运行的历史记录，产生"幻觉上下文"——比如认为昨天已经处理过的邮件今天还在处理。

token 成本也会随运行次数累积：有人观察到同一个 session 累积了 8+ 次运行历史，token 总量超过 59K 才触发自动轮换。

临时解决方法：在 jobs.json 里（停 Gateway 后手动编辑）给任务加上 "sessionFreshness": "always-new"，或者等官方提供 --fresh CLI 参数。

---

5. Skills 系统详解：找、装、用

ClawHub 是什么

ClawHub（clawhub.com） 是 OpenClaw 官方的 Skill 注册表，类似 npm 之于 Node.js。搜索引擎使用的是 OpenAI text-embedding-3-small 向量语义搜索（来源：github.com/openclaw/clawhub），不是关键词匹配——用自然语言描述"我想做什么"，比输入工具名找到的结果更准确。

安装 Skill 的三种方式

方式一：clawhub CLI（最规范）

# 安装 clawhub CLI
npm install -g clawhub

# 搜索
clawhub search "管理 Todoist 任务"

# 安装（以 bat-cat 为例）
clawhub install bat-cat

# 安装后必须重启 Gateway，新 Skill 才在下一个 session 里生效
openclaw gateway restart

方式二：直接粘贴 GitHub 链接给 Agent

把 Skill 的 GitHub 仓库 URL 直接发给你的 Agent，它会在后台自动安装，不需要你执行任何命令。这是最懒但有效的方式。

方式三：手动克隆到 skills 目录

# 安装到全局目录（所有 Agent 共享）
git clone https://github.com/example/my-skill ~/.openclaw/skills/my-skill

# 安装到某个 Agent 专属 workspace
git clone https://github.com/example/my-skill ~/my-workspace/skills/my-skill

Skill 的三层优先级（来自官方文档）

<workspace>/skills/       ← 最高优先级（只有这个 Agent 能看到，可覆盖全局同名 Skill）
         ↑
~/.openclaw/skills/       ← 共享层（所有 Agent 可见，clawhub install 默认装这里）
         ↑
Bundled Skills            ← 最低优先级（随 OpenClaw 安装包自带的内置 Skill）

实际用途：如果你有两个 Agent（一个个人用，一个工作用），想让工作 Agent 用不同配置的 GOG（Google Workspace），就在工作 Agent 的 workspace/skills/ 里放一个同名 GOG，覆盖全局版本，两个 Agent 互不干扰。

更新所有已安装的 Skill

# --all 会扫描 workdir，比较每个 Skill 的本地 hash 和注册表版本
clawhub sync --all

# 非交互模式（CI/脚本里用）
clawhub sync --all --force

安装记录保存在 <workdir>/.clawhub/lock.json，clawhub sync 靠这个文件判断哪些 Skill 需要更新。

检查 Skill 是否被正确加载

# 查看当前会话所有已加载的 Skill
openclaw skills status

# 直接问 Agent
openclaw agent --message "你现在有哪些 skills？"

Skill 装了但没出现，通常是以下原因之一： 1. 没重启 Gateway，新 Skill 只在下一个 session 才生效 2. requires.bins 里的命令不存在，Skill 被过滤掉——运行 openclaw doctor --repair 检查 3. 装错了目录，不在任何加载路径里

几个真实存在、值得装的 Skill

以下均可在 github.com/VoltAgent/awesome-openclaw-skills 或 ClawHub 上找到。

---

cron-mastery（来源：官方 skills 仓库）

OpenClaw 官方 Skills 仓库里的 Skill，教 Agent 怎么正确使用 Cron 调度：什么时候用 Heartbeat 不用 Cron，怎么处理时区，如何避免 job 堆积。大量使用 Cron 任务的用户必装，它本质上是把本文上一章的内容作为 Agent 的系统知识注入进去。

GOG（Google Workspace CLI）

接入 Gmail、Calendar、Drive、Contacts、Sheets、Docs 的全家桶 Skill。装完后你可以直接说"把明天 10 点的会议推迟一小时"，Agent 会真的去操作你的 Google Calendar。

bat-cat

封装 bat（github.com/sharkdp/bat），一个带语法高亮和行号的 cat 替代品。需要先本机安装 bat（brew install bat / sudo apt install bat）。

beeminder

接入 Beeminder 承诺制目标追踪，让 Agent 帮你查询和更新目标进度数据点。

azure-devops

接入 Azure DevOps，支持列出项目和仓库、创建 PR、管理工作项、查看构建状态。

---

推荐几个有点意思的有趣 Skill

上面几个偏向开发者，下面这些是给稍微不那么精通代码的人用的——装完就能直接感受到"哇，openclaw真特么牛逼"。一下来源都能在github上找到

---

tmdb（影视搜索 + 选片助手）

来源：sundial-org/awesome-openclaw-skills

接入 TMDb（The Movie Database）API，让 Agent 帮你搜影视、查评分、看演员表、找流媒体播放渠道，还能做个性化推荐。

安装后你可以直接说：

• "帮我找一部 90 年代的日本悬疑电影，豆瓣风格那种"
• "《星际穿越》在哪个平台可以看？"
• "我喜欢《请回答 1988》这种风格，推荐几部类似的"

需要一个免费的 TMDb API Key，注册地址：developer.themoviedb.org。注册免费，不需要信用卡。

clawhub install tmdb
# 然后在 openclaw.json 里加：
# "tmdb": { "env": { "TMDB_API_KEY": "你的Key" } }

---

openai-whisper（会议/语音秒变文字）

来源：composio.dev Top Skills 文章，ClawHub 可搜到

这个 Skill 封装了本地运行的 OpenAI Whisper 语音识别模型。你录一段会议音频发给 Agent，它会在本地转成文字——不上传任何服务器，完全本地运行，保护隐私。

实际用法：

• 录完会议把 .m4a 文件路径发给 Agent："帮我转录这段会议录音，然后整理成会议纪要"
• 录一段备忘语音："帮我把这个转成文字存进今天的笔记"

前置条件：本机安装 Whisper（pip install openai-whisper）和 ffmpeg（brew install ffmpeg）。模型文件第一次运行时会自动下载（base 模型约 140MB，medium 模型约 1.5GB）。

# 先装依赖
pip install openai-whisper
brew install ffmpeg   # macOS

# 再装 Skill
clawhub install openai-whisper

---

elevenlabs-agents（给 Agent 一个真实的声音，还能帮你打电话）

来源：composio.dev Top Skills 文章，ClawHub 可搜 elevenlabs

这是整个 Skill 生态里最"科幻感"的一个。它接入 ElevenLabs 的语音合成 API，让 Agent 可以用真实的声音和你说话——更厉害的是它的自动降级机制：

当文字消息发送失败（比如 WhatsApp 掉线、邮件退信），Agent 会自动 pivot，真的打一个电话给你或目标联系人。

实际场景：

• "帮我预订今晚 7 点，两位，意大利餐厅，打电话过去确认"
• "发短信给张三说我晚到半小时，如果短信失败就打电话"

需要 ElevenLabs API Key（elevenlabs.io，有免费额度）。

代打电话功能在部分地区有监管要求，请先确认当地法规后再使用，当然，你也可以无视。

---

veryfi（拍收据，自动报销结构化数据）

来源：Veryfi 官方文章，2026 年 2 月新上线

这是目前 ClawHub 上最新、最有实用价值的生活向 Skill 之一。用法非常直白：

1. 在 WhatsApp 或 Agent 聊天框里直接把收据照片发过去
2. Agent 调用 Veryfi 的 AI 提取引擎，几秒内返回结构化数据：商家名、日期、金额、税额、分类
3. 可以直接让 Agent 把结果存进 Google Sheets 或发到指定邮箱

适合需要手工整理发票报销的上班族。官方描述："不用手动录入，不用复制粘贴"。

需要 Veryfi API Key，申请地址，有免费套餐。

---

apple-music（用说话控制 Apple Music）

来源：sundial-org/awesome-openclaw-skills

macOS 专属。让 Agent 搜索歌曲、把歌加进资料库、管理播放列表、控制播放和 AirPlay。

装完可以直接说：

• "把周杰伦的《以父之名》加进我的「开车」播放列表"
• "现在播放一些适合专注工作的纯音乐"
• "把 AirPlay 切换到客厅音箱"

前置条件：macOS 系统 + 登录了 Apple Music。不需要 API Key，走本地 macOS 脚本控制。

clawhub install apple-music

---

stock-crypto-analyzer（股票和加密货币分析）

来源：sundial-org/awesome-openclaw-skills

调用 Yahoo Finance 数据，支持：

• 分析单只股票或加密货币的近期走势
• 创建自定义持仓组合，追踪整体涨跌
• 查看加密货币市值前 20 排行
• 配合 Cron，每天定时生成持仓日报推送到 Telegram

使用示例：

• "帮我分析一下 NVDA 最近一个月的表现"
• "我持有 BTC、ETH、SOL，帮我创建一个组合追踪它们"
• "每天早上 9 点把我的持仓涨跌推送给我"

不需要 API Key，直接用 Yahoo Finance 公开数据（yfinance Python 库）。

# 先装依赖
pip install yfinance

# 再装 Skill
clawhub install stock-crypto-analyzer

---

peekaboo（截图 + 用自然语言操控 macOS 界面）

来源：github.com/openclaw/clawhub 官方文档里的示例 Skill

macOS 专属，ARM（Apple Silicon）专属。这个 Skill 封装了 Peekaboo CLI，让 Agent 可以截取屏幕任意区域，然后根据截图内容做出判断和操作。

听起来很技术，但实际用法对普通人也很有意思：

• "帮我看一下现在屏幕上那个对话框在问什么"（你不需要描述，Agent 直接截图读）
• "帮我确认一下这个表单是不是填完了"
• 自动化工作流：每天定时截取某个数据大屏，把数字提取出来存档

# 通过 Nix 安装（官方推荐）
# 在 openclaw.json 的 plugins 里加入：
# { "source": "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo" }

注意：Peekaboo 是 Nix 插件，安装方式和普通 Skill 不同，需要先配置好 Nix 环境。macOS 上装 Nix：curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh

---

self-improving-agent（让 Agent 帮你改进 Agent 本身）

来源：composio.dev Top Skills 文章，ClawHub 可搜 self-improving-agent

这个最后压轴，也最有意思。它的功能是：让 Agent 分析自己和你的对话历史，找出它哪里做得不好，然后提出修改 SOUL.md 或 MEMORY.md 的建议——相当于让 AI 参与自己的调教过程。

你可以说：

• "分析我们最近两周的对话，找出你哪些地方让我不满意"
• "你觉得 SOUL.md 里有没有需要更新的地方？"
• "我想让你在回复时更简洁，帮我更新一下配置"

它不会自动修改文件（安全起见），而是给出具体的修改建议，你确认之后才执行。这是目前把"本地 AI 自我迭代"玩得最深的 Skill 之一。

---

6. 自己写一个 Skill：从零到能用，30 分钟搞定，稍微有些硬核，自己研究一下

Skill 的本质

一个 Skill 就是一个文件夹 + 一个 SKILL.md 文件。SKILL.md 分两部分：

--- （YAML frontmatter，机器读）
name, description, version, requires...
---
Markdown 正文（Agent 读的操作手册，自然语言写即可）

Agent 在决定是否调用某个 Skill 时，只看 name 和 description 两个字段——它们是触发词，不是广告语。正文里的详细步骤，只有 Agent 认为这个 Skill 相关之后才会读。

🎯 写好 description 的原则（来自 lumadock.com 社区总结）：用户会怎么描述这个任务，description 就怎么写。"当用户要下载 YouTube 视频时" 比 "强大的视频下载功能" 触发效果好得多。

完整示例：一个查询 Todoist 今日任务的 Skill

第一步：创建文件夹

mkdir -p ~/.openclaw/skills/todoist-helper
cd ~/.openclaw/skills/todoist-helper

第二步：写 SKILL.md

frontmatter 字段规范来自官方 clawhub/docs/skill-format.md：

---
name: todoist-helper
description: 当用户要查看、添加、完成 Todoist 任务，或询问"今天有什么待办事项"时使用此 Skill
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    emoji: "✅"
    homepage: https://github.com/你的用户名/todoist-helper
---

# Todoist Helper Skill

## 前提：获取 API Token

前往 https://app.todoist.com/app/settings/integrations/developer
拉到页面底部，点击"Create token"，复制 token。

---

## 查看今日任务

当用户说"今天有什么任务"、"我的待办"时：

1. 调用 Todoist REST API：
   ```
   curl -s \
     -H "Authorization: Bearer $TODOIST_API_KEY" \
     "https://api.todoist.com/rest/v2/tasks?filter=today"
   ```
2. 响应是 JSON 数组，每个对象包含 `content`（任务名）和 `due.string`（截止时间）
3. 以清单形式展示给用户，例如：
   - ✅ 回复 Alice 的邮件（今天）
   - 📋 准备周五演示材料（今天 17:00）

---

## 添加任务

当用户说"添加任务：[内容]"或"帮我记一下要做 [内容]"时：

1. 调用：
   ```
   curl -s -X POST \
     -H "Authorization: Bearer $TODOIST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"content": "[任务内容]"}' \
     "https://api.todoist.com/rest/v2/tasks"
   ```
2. 成功返回 HTTP 200 和任务对象，告诉用户"已添加：[任务名]，ID: [id]"

---

## 完成任务

当用户说"完成任务 [ID]"或"这个做完了"时：

1. 调用：
   ```
   curl -s -X POST \
     -H "Authorization: Bearer $TODOIST_API_KEY" \
     "https://api.todoist.com/rest/v2/tasks/[ID]/close"
   ```
2. 返回 HTTP 204 表示成功，告诉用户"已完成 ✅"

---

## 常见错误处理

- HTTP 401：API Token 无效，请用户重新生成
- HTTP 403：权限不足，检查 token 是否有任务读写权限
- HTTP 429：触发频率限制，等待 1 分钟后重试
- Todoist REST API 文档：https://developer.todoist.com/rest/v2/

第三步：配置 API Key

停止 Gateway，编辑 ~/.openclaw/openclaw.json，在 skills.entries 里加入：

{
  "skills": {
    "entries": {
      "todoist-helper": {
        "env": {
          "TODOIST_API_KEY": "在这里粘贴你的 Todoist API Token"
        }
      }
    }
  }
}

根据官方文档，skills.entries.*.env 里的键值对会在 Agent 运行时注入到宿主进程的环境变量里。绝对不要把 API Token 直接写进 SKILL.md 文件本身，那样发布到 ClawHub 后所有人都能看到你的 Key。

第四步：重启 Gateway，验证

openclaw gateway start

# 验证 Skill 是否出现在加载列表
openclaw skills status

# 或者直接测试
openclaw agent --message "帮我看看今天有哪些 Todoist 任务"

frontmatter 字段速查（来自官方规范）

字段	必填	说明
name	✅	Skill 唯一 slug，ClawHub 上的 ID
description	✅	Agent 触发词，写成"用户会怎么说这件事"
version	✅	语义化版本号，如 1.0.0
metadata.openclaw.requires.env	推荐	需要的环境变量列表，不填用户不知道要配什么
metadata.openclaw.requires.bins	推荐	需要的系统命令列表，不存在时 Skill 被自动过滤
metadata.openclaw.primaryEnv	可选	主要凭证变量名，帮助用户知道先配哪个
metadata.openclaw.emoji	可选	ClawHub 列表里显示的 emoji

requires.bins 的作用：列表里的某个命令不存在时，这个 Skill 会被 Gateway 静默过滤——不报错，只是不出现在加载列表里。所以"用了什么命令就声明什么"是排查问题的关键。

发布到 ClawHub（可选）

# 登录（GitHub OAuth）
clawhub login

# 在 Skill 目录里发布第一版
cd ~/.openclaw/skills/todoist-helper
clawhub publish .

# 发布更新版本
clawhub publish . --changelog "增加了删除任务的功能"

发布前提：GitHub 账号注册满一周（官方防滥用机制）。发布后，ClawHub 的自动安全分析会对比你 frontmatter 里声明的 requires.env/bins 和正文里实际用到的内容——不一致会被标记"元数据不匹配"，影响用户信任度。

---

7. 安全警告：不得不说的那些事

OpenClaw 的维护者在官方 Discord 里说过一句话，被大量文章引用，包括维基百科的 OpenClaw 词条：

"如果你搞不懂怎么跑命令行，这个项目对你来说太危险了，不适合安全使用。"

这不是吓你。以下是真实记录的风险。

坑一：Skills 是"可执行指令"，不是无害插件

Cisco 的 AI 安全研究团队测试了一个第三方 OpenClaw Skill，发现它在用户不知情的情况下进行了数据外泄和 Prompt Injection 攻击（来源：DigitalOcean 的 OpenClaw 安全文章）。Skill 的 SKILL.md 里隐藏了恶意指令，诱导 Agent 把用户数据发到外部服务器。

安装前的检查清单（来自 awesome-openclaw-skills 官方 README）：

# 安装前先只检查，不安装
clawhub inspect <slug>

1. 在 clawhub.com 上查看 Skill 的 VirusTotal 扫描报告（OpenClaw 与 VirusTotal 的官方合作功能）
2. 查看 Skill 发布者——个人还是有维护记录的团队
3. 读完整个 SKILL.md，检查有没有不合理的权限要求
4. 查看 requires.env 里有没有你不理解的环境变量

ClawHub 的社区举报机制：超过 3 个不同用户举报的 Skill 会被自动隐藏（来源：ClawHub 官方文档）。

坑二：不要在主力机上开 system.run

system.run 工具允许 Agent 执行任意 shell 命令。这是 OpenClaw 最强大也最危险的功能。

来自 HelloPM 的 OpenClaw Masterclass：

"永远不要在个人主力机上跑 OpenClaw……如果遭遇 prompt injection 或安全漏洞，你的所有个人数据都暴露了。"

推荐的做法：在专用机器（Mac Mini、树莓派、VPS）上跑 OpenClaw。很多高级用户选择开一个 VPS，通过 SSH 隧道访问 Dashboard，如果有需要，可以看看这个网站主页推荐的VPS，绝对都是精品，不是精品来找我的麻烦，我把头都给你：

# 在本地跑这条命令，把远程 18789 端口映射到本地
ssh -L 18789:localhost:18789 user@你的VPS地址 -N

# 然后在本地浏览器访问
open http://localhost:18789

坑三：API Key 安全管理

来自 HelloPM 文章的建议，被社区广泛认可：

• 用服务账号，不用主账号：给 OpenClaw 创建一个权限受限的 Google/GitHub/Slack 服务账号，而不是把你的主账号 token 直接丢进去。
• 用 Doppler 管理 Secrets：不要把 API Key 硬编码进 openclaw.json。让 Agent 帮你配置 Doppler，把 secrets 集中管理，还能在 key 泄露时一键轮换。
• Supabase 记录日志：把 OpenClaw 的操作日志推送到 Supabase（免费套餐够用），万一 key 被盗或用量异常，有完整记录可查。

坑四：MEMORY.md 越写越大的熵增问题

根据 LumaDock 的内存系统文章：

"OpenClaw 的记忆系统不是自动清理的。Daily notes 如果你从不修剪，会越来越嘈杂。"

正确的内存管理习惯（来自官方文档）：

• MEMORY.md 要保持精炼——只放长期成立的事实，比如"用户喜欢泰餐"、"主要工作时区是 Asia/Shanghai"。不要把临时任务清单写进 MEMORY.md。
• memory/YYYY-MM-DD.md 是流水账——每天的工作上下文，Agent 自动写，你每周清理一次过期的。
• 定期手动检查：如果 Agent 记住了不准确的信息，直接打开 MEMORY.md 编辑它。这就是"本地优先"的优势——记忆文件就是普通文本文件，用任意编辑器改掉就好。

配置记忆清理行为（~/.openclaw/openclaw.json）：

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": "weekly"
      }
    }
  }
}

坑五：环境诊断

遇到任何奇怪的问题，先跑这两条命令：

# 诊断环境，自动修复可修复的问题
openclaw doctor --repair

# 修复配置文件里的废弃字段（比如旧版的 bridge.* 字段）
openclaw doctor --fix

openclaw doctor --fix 来自官方配置参考文档，可以清除已废弃的配置字段（比如旧版 TCP bridge 配置残留），防止 Gateway 启动时报验证错误。

---

总结

OpenClaw 真正的乐趣在于：所有东西都在你的硬盘上，都是普通文本文件，你可以直接看、直接改、直接理解。这和那些黑盒 SaaS AI 工具是本质上不同的体验。

建议的入手顺序：

1. 先花 10 分钟把 SOUL.md 和 USER.md 写好，让 Agent 真正认识你
2. 配置 HEARTBEAT.md + lightContext: true，让它开始主动感知你的日历和邮件
3. 创建一个 Cron 早报任务，每天自动推送到 Telegram，验证整个链路跑通
4. 去 ClawHub 装一两个和你工作相关的 Skill，测试验证
5. 遇到没有现成 Skill 的需求，按第 6 节自己写一个

---

核心参考资料（全部真实可访问）

资源	地址
官方文档	docs.openclaw.ai
GitHub 主仓库	github.com/openclaw/openclaw
ClawHub Skill 注册表	clawhub.com
官方 Skills 仓库	github.com/openclaw/skills
ClawHub 开发者文档	github.com/openclaw/clawhub
社区精选 Skill 列表	github.com/VoltAgent/awesome-openclaw-skills
SOUL.md 模板仓库	github.com/aaronjmars/soul.md
内存系统详解	lumadock.com/tutorials/openclaw-memory-explained
memsearch 开源库	milvus.io/blog/we-extracted-openclaws-memory-system...

---

全文数据和命令来源：docs.openclaw.ai · github.com/openclaw · clawhub.com · lumadock.com · hellopm.co · amankhan1.substack.com · milvus.io · dev.to · 2026 年 3 月