《OpenClaw架构与源码解读》· 第 11 章 Skills 平台：OpenClaw 的「工具说明书」体系

第 11 章 Skills 平台：OpenClaw 的「工具说明书」体系

本章纠正一个常见的误解，并深入讲解 OpenClaw Skills 的真实工作方式——它和大多数人想象中的「TypeScript 插件系统」完全不同。

11.1 Skills 的本质：给 Agent 的 Markdown 说明书

11.1.1 不是代码插件，而是 Prompt 指令文件

OpenClaw 的 Skills 不是以 TypeScript/JavaScript 编写的可执行模块。查看仓库skills/weather/SKILL.md的真实内容：

--- name: weather description: "Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed." homepage: https://wttr.in/:help metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } } --- # Weather Skill Get current weather conditions and forecasts. ## When to Use ✅ USE this skill when: - "What's the weather?" - "Temperature in [city]" - "Weather forecast for the week" ❌ DON'T use this skill when: - Historical weather data → use weather archives/APIs - Severe weather alerts → check official NWS sources ## Commands ### Current Weather \`\`\`bash curl "wttr.in/London?format=3" \`\`\` ### 3-day Forecast \`\`\`bash curl "wttr.in/London" \`\`\`

这就是一个完整的 Skill：一个带 YAML frontmatter 的 Markdown 文件。

11.1.2 Skills 的工作原理

OpenClaw 的 Agent Runtime 在处理用户消息时，会把激活的 Skills 的内容注入到系统提示词里——就像给模型一本「工具手册」。当模型判断用户需要查天气，它会按照weather/SKILL.md里描述的方法，调用bash工具执行curl "wttr.in/..."命令，并把结果整理后回复给用户。

这个设计的核心思路是：Skills 就是「教会 AI 用哪些 shell 命令完成哪类任务」的说明书，而不是「让 AI 调用预先封装好的函数」的插件 SDK。

这个设计极其简洁。任何人都能写 Skill，不需要学习任何 SDK 或 API。Skill 的「工具」就是已有的命令行工具（curl、git、python3 脚本等）。Skill 的「逻辑」完全在 Markdown 里，人类可读、可审计、可 diff。Agent 失败时，你可以在 Skill 文件里直接看到它在尝试做什么。

11.1.3 Skills 与 bash 工具的关系

Agent 执行 Skill 里的命令，依赖的是 OpenClaw 内置的bash工具（也叫exec工具）。流程是：

用户消息 → Agent 加载 Skill 说明 → 模型决定调用 bash → bash 工具执行 curl/python3/等命令 → 结果返回给模型 → 模型整理回复

这意味着只要宿主机上装了对应的命令行工具，Skill 就能工作，完全不依赖 OpenClaw 的任何私有 API。

11.2 Skills 的三种来源

11.2.1 仓库内置 Skills（Bundled）

仓库skills/目录下预置了 50+ 个 Skills，经过社区维护和测试：

skills/ weather/SKILL.md # 天气查询（curl + wttr.in） github/SKILL.md # GitHub CLI 操作 notion/SKILL.md # Notion 笔记操作 obsidian/SKILL.md # Obsidian 知识库 apple-notes/SKILL.md # Apple Notes（macOS） apple-reminders/SKILL.md # Apple Reminders spotify-player/SKILL.md # Spotify 播放控制 things-mac/SKILL.md # Things 3 任务管理 1password/SKILL.md # 1Password CLI openhue/SKILL.md # 飞利浦 Hue 智能灯 tmux/SKILL.md # tmux 终端复用 trello/SKILL.md # Trello 看板 ...

安装命令：openclaw skill install weather

11.2.2 ClawHub 社区 Skills（Managed）

ClawHub 是一个极简的技能注册表，Agent 可以自动搜索并拉取新 Skills。这不是一个有 UI 的「应用商店」——它更像一个公开的 Git 索引：

# 手动安装openclaw skillinstall<skill-name># 让 Agent 自行发现（ClawHub enabled 时）# Agent 在需要时会自动搜索并安装合适的 Skill

11.2.3 Workspace Skills（个人/团队定制）

放在~/.openclaw/workspace/skills/<name>/SKILL.md的 Skills 不需要发布，本地 Agent 直接加载，适合私有自动化或内部系统集成。路径可以通过agents.defaults.workspace配置项修改。

11.3 SKILL.md 文件格式详解

11.3.1 Frontmatter（YAML 元数据）

--- name: my-skill # Skill 的唯一标识名 description: "一句话描述 + 使用时机（given to the model）" homepage: https://example.com # 可选：相关文档链接 metadata: openclaw: emoji: "🔧" # 在 UI 中显示的图标 requires: bins: ["curl", "jq"] # 运行此 Skill 需要的命令行工具 envs: ["MY_API_KEY"] # 需要的环境变量（可选） ---

description字段是写给 Agent（模型）看的：它决定了 Agent 在什么情况下会想到用这个 Skill。写好 description 是 Skill 质量的关键。

11.3.2 Markdown 正文：指导模型的说明书

正文是给模型读的操作说明，通常包含使用时机说明（When to Use / When NOT to Use，帮助模型准确判断调用时机）、前置条件（Prerequisites，告诉模型执行前需要确认什么，例如登录状态）、命令示例（Commands，带注释的 bash 命令，模型会参照这些生成实际命令）、参数变体（Format Options，不同场景下命令参数的变体）、以及注意事项（Notes，速率限制、权限要求等）。

11.4 与 MCP 工具协议的关系

11.4.1 MCP 协议简述

MCP（Model Context Protocol）是一套开放协议，用 JSON-RPC 2.0 在「大模型所在的应用（Host）」和「外部工具/数据源（Server）」之间建立有状态的会话。核心流程是 Host 通过 MCP Client 连接 MCP Server，Server 返回工具列表，Host 把工具描述注入给模型，模型在需要时输出 tool_calls，Client 调用 Server 执行，结果回传模型。

需要注意的是，大模型本身不需要「理解」MCP 协议。MCP 是 Host 和 Server 之间的约定；模型只负责「看到工具描述就在合适的时候输出工具调用」，这一能力在主流大模型的指令微调阶段已经具备，与具体是不是 MCP 无关。

11.4.2 Skills vs MCP

OpenClaw Skills 和 MCP 在目标上有交集，但实现路径完全不同：

11.4.3mcporterSkill：桥接 MCP

仓库中有一个名为mcporter的特殊 Skill，它的作用是把外部 MCP Server 接入 OpenClaw。在 OpenClaw 的架构里，mcporter 在模型使用 MCP 工具时扮演的是 MCP Client：Gateway/Agent 加载 mcporter 后，mcporter 按配置连接到指定的 MCP Server，拉取工具列表并交给 Agent；当模型决定调用某个 MCP 工具时，mcporter 向对应 Server 发起tools/call，把结果返回给模型。

这样，你在本机或远程起的任何 MCP Server（文件、Git、数据库、自定义 API 等），都可以被 OpenClaw 的模型当作「工具」使用，而无需为每个工具写一份 SKILL.md。

反向来说，OpenClaw 的 bash 工具能力也可以通过类似的适配器暴露给其他 MCP 客户端（如 Claude Desktop、Cursor 等），那样 OpenClaw 就相当于一个「提供 shell/脚本能力的 MCP Server」。

11.4.4 接入 MCP 是否等于接入 OpenClaw？

结论先说：不是。二者是不同层面的「接入」。

MCP 是「工具协议」，定义的是模型和工具服务之间的调用约定。接入 MCP 表示你的进程会按 MCP 规范暴露或消费工具，不表示你可以直接作为用户或客户端和 OpenClaw 聊天。OpenClaw 的「被接入」指的是谁可以发消息进来、拿到回复，这一层由 Channels、CLI、Web UI 以及 Gateway 的会话与鉴权机制决定。

简单记：MCP 解决的是「模型用什么工具」；OpenClaw 的 Channels/API 解决的是「谁在跟 OpenClaw 说话」。接入 MCP 不等于接入 OpenClaw；若你要 OpenClaw 用上你的 MCP 工具，用 mcporter 即可；若你要让自己的系统或用户和 OpenClaw 对话，走 Channels 或 Gateway API。

11.5 ClawHub 的工作方式

ClawHub 是一个 Skill 的注册表，不是 UI 商店。当 Agent 遇到需要某个能力但没有对应 Skill 时，如果 ClawHub 已启用，Agent 可以自动搜索合适的 Skill，找到后安装到~/.openclaw/workspace/skills/并立即使用。整个过程对用户是透明的——Agent 只需在回复里提及「我安装了 X Skill 来完成这个任务」。

# 手动安装openclaw skillinstallweather# 列出所有已安装 Skillsopenclaw skill list# 查看某个 Skill 的状态openclaw skill status weather

11.6 源码走读导向

阅读 Skills 相关源码时的关键路径：Skill 加载逻辑在src/agents/中（查找扫描和读取 SKILL.md 的代码），提示词注入在src/gateway/agent-prompt.ts中（查找如何把 Skills 内容插入系统提示词），ClawHub 客户端在skills/clawhub/SKILL.md中（它本身也是一个 Skill），依赖检查方面查找对requires.bins和requires.envs的运行时检查逻辑（关键词：bins、skill-status）。

11.7 小结

本章揭示了 OpenClaw Skills 的真实设计。Skills 是 Markdown 说明文件（SKILL.md），而非 TypeScript 插件模块。工作原理是把 Skill 内容注入 Agent 的系统提示词，让模型学会用 bash 命令完成对应任务。三种来源分别是仓库内置（50+ 个）、ClawHub 社区注册表、Workspace 个人 Skills。创建 Skill 的门槛极低——写 Markdown 加 bash 命令即可。MCP 是 Host 和 Server 之间的工具协议，模型本身不需要「理解」MCP。mcporter 是 OpenClaw 里的 MCP Client，把外部 MCP Server 的工具桥接进来。接入 MCP 不等于接入 OpenClaw，和 OpenClaw 对话要走 Channels/CLI/Web，MCP 只解决「模型用什么工具」。

这个设计的精妙之处在于：让 AI 的「工具」扩展和 AI 的「使用方式」保持一致——都是自然语言（Markdown），而不是另一套编程范式。

下一章，我们来看另一条自动化路径：Cron 定时任务、Webhooks 触发和 Gmail Pub/Sub 事件源。