构建自定义 OpenClaw 技能：实践教程

OpenClaw 内置技能覆盖了常见工作流，ClawHub 上也托管了大量技能。但最重要的往往是那些尚未有人构建的技能：围绕您自己的项目和工具量身定制的自动化。

本教程将演示如何构建两个自定义技能。第一个封装了一个 Python 脚本，用于将 Jupyter 笔记本转换为 Word 文档。如果您在笔记本中写作，但需要向编辑或相关方交付 .docx 文件，这会将原本的手动导出变成一个斜杠命令。第二个则通过 Replicate API 使用 Nano Banana Pro 生成图像，在基础之上叠加了凭证管理与环境范围控制。

教程还涵盖 Docker 沙箱、元数据门控以及将技能发布到 ClawHub。想更全面了解 OpenClaw 平台，请参见 OpenClaw 项目：您可以构建什么以及我们的顶级 Agent 技能指南。

什么是 OpenClaw 技能？

技能是向 OpenClaw Agent 添加新行为的方式。一个技能可以简单到通过斜杠命令重新格式化代码，也可以复杂到多步工作流，例如审查 PR 并向 Jira 或 Slack 发布评论。

如果您在MCP（模型上下文协议）服务器中使用过Claude Code或类似工具，技能扮演的角色并不相同。MCP 服务器是通过标准化协议暴露工具的独立进程，适合需要持久状态或多个工具端点的集成。

技能则跳过这些：您编写自然语言指令，Agent 在运行时读取并遵循，因此当您只需要自动化一件事时，构建速度更快。详见OpenClaw 与 Claude Code 对比中关于权衡的更深入讨论。

Hooks是另一个扩展点，会在某些事件发生时自动触发，例如工具调用完成或模型生成响应。技能则保持空闲，直到用户输入斜杠命令，或 Agent 认为其与当前任务相关。

OpenClaw 自带 49 个技能，涵盖邮件、日历、GitHub、浏览器自动化等。社区还在 ClawHub 上发布了数千个附加技能。关于平台演进的背景，请参见从 MoltBot 到 ClawdBot 的历史。

先决条件

您需要：

• 通过 Telegram 安装并运行 OpenClaw（安装指南）。Telegram 的 BotFather 集成对斜杠命令的支持最佳，本教程将通过斜杠命令触发技能。
• uv 已安装（本教程中的两个技能均用于管理 Python 依赖）
• 熟悉终端、YAML 和 Markdown
• 用于图像生成技能的Replicate API 令牌（免费注册，按用量计费）
• 一个至少注册一周的 GitHub 帐号（如果您要发布到 ClawHub）

如果您更倾向于使用本地模型运行 OpenClaw，请参见OpenClaw 搭配 Ollama 教程中的设置说明。

构建您的第一个 OpenClaw 技能

第一个技能封装了一个 Python 脚本，用于将 Jupyter 笔记本转换为 Word 文档，处理 markdown 格式、代码块、图像、表格和超链接，从而使 .docx 输出保留原始笔记本的结构。如果您经常需要将笔记本内容交付给使用 Word 的人，这会把手动导出变为一个斜杠命令。

在 OpenClaw 的托管技能目录中创建技能文件夹：

mkdir -p ~/.openclaw/skills/notebook-to-docx

位于 ~/.openclaw/skills 的技能可在所有会话中使用。您也可以将其放在项目内的 <project>/skills 下，将其限定到该工作区。当同名技能同时存在于两个位置时，工作区内的副本优先生效，其次是托管副本，最后覆盖任何同名的捆绑技能。

编写 SKILL.md

每个技能都需要一个文件：SKILL.md。顶部的 YAML 前置区（frontmatter）定义 OpenClaw 如何加载该技能，下面的 Markdown 正文包含 Agent 在运行时遵循的指令。

创建 ~/.openclaw/skills/notebook-to-docx/SKILL.md，从前置区开始：

---
name: notebook-to-docx
description: Convert Jupyter notebooks to Word documents with proper formatting
user-invocable: true
metadata: {"openclaw": {"requires": {"bins": ["uv"]}}}
---

name 同时也是斜杠命令（/notebook-to-docx）。description 为 Agent 提供一句话简介，用于判断与当前任务的相关性。设置 user-invocable: true 会在您的 Telegram 聊天中注册该斜杠命令。metadata JSON 负责加载时门控：requires.bins 告诉 OpenClaw 如果系统 PATH 上没有 uv，则跳过该技能，而不是在运行时失败。

如果您希望相反的行为，即除非您明确输入斜杠命令，否则技能绝不触发，请设置 disable-model-invocation: true。

提示：YAML 前置区仅支持单行值。多行字符串或块标量会导致解析错误，这也是为什么 metadata 使用单行 JSON 对象，而非嵌套 YAML。

在前置区下方，添加指令正文：

# Notebook to DOCX Converter
 
Converts Jupyter notebooks (.ipynb) to Word documents (.docx) with proper formatting.
 
## Usage
 
Run the conversion script:
 
	uv run --with nbformat --with python-docx --with Pillow python {baseDir}/notebook_to_docx.py <notebook_path> [output_path]
 
If output_path is not specified, creates a .docx file with the same name as the notebook.
 
## Features
 
- Markdown formatting preserved as Word styles (bold, italics, headings)
- Backticks preserved around inline code with monospace font
- Code blocks show triple backticks and language name, use Courier New font
- Non-code text uses Poppins font
- Images embedded with alt text
- Hyperlinks preserved and clickable
- Markdown tables converted to Word tables
 
## Requirements
 
- nbformat
- python-docx
- Pillow

{baseDir} 是一个模板变量，在运行时解析为技能文件夹路径，因此您无需硬编码位置。当他人在不同目录安装您的技能时，这一点尤为重要。

带有 uv run --with 的标志会拉取脚本所需的三个库，使技能具备自包含性，而非假设用户环境中已安装这些包。

配套脚本

Python 脚本与 SKILL.md 位于同一文件夹。脚本约 490 行，过长不便贴出，请从该 gist 获取完整脚本，并保存为 notebook_to_docx.py，路径为 ~/.openclaw/skills/notebook-to-docx/。它覆盖了上述 SKILL.md 的“功能”部分所列项。

以下是入口函数，便于您从高层了解其用途：

def convert_notebook_to_docx(notebook_path, output_path=None):
	notebook_path = Path(notebook_path)
	if output_path is None:
    	output_path = notebook_path.with_suffix('.docx')
	else:
    	output_path = Path(output_path)
 
	with open(notebook_path, 'r', encoding='utf-8') as f:
    	nb = nbformat.read(f, as_version=4)
 
	doc = Document()
	create_styles(doc)
 
	style = doc.styles['Normal']
	style.font.name = 'Poppins'
	style.font.size = Pt(11)
 
	base_path = notebook_path.parent
 
	for cell in nb.cells:
    	if cell.cell_type == 'markdown':
        	process_markdown_cell(doc, cell.source, base_path)
    	elif cell.cell_type == 'code':
        	process_code_cell(doc, cell.source, cell.get('outputs', []))
 
	doc.save(output_path)
	print(f'Converted: {notebook_path} -> {output_path}')
	return output_path

测试技能

OpenClaw 会在会话开始时快照技能列表，但内置文件监视器会在约 250ms 内捕捉到新的 SKILL.md 文件。如果技能未出现，请重启会话。

以下是我们用于测试的笔记本：

打开与 OpenClaw 的 Telegram 聊天并输入 /notebook-to-docx，然后告知要转换的笔记本路径：

生成的 Word 文档：

标题、代码块、行内格式和超链接都正确映射到了对应的 Word 样式。如果输出看起来有误，请检查您在 SKILL.md 中的功能列表是否与脚本的实际支持一致。

OpenClaw 的安全与沙箱

OpenClaw 可在 Docker 容器内运行工具执行，从而限制异常或受损技能对您机器的影响。该设置位于 ~/.openclaw/openclaw.json 中的 agents.defaults.sandbox，可选三种模式：

• "off" 为默认设置，工具直接在宿主机上运行，无隔离层。
• "non-main" 保持主聊天会话在宿主机上，而将后台与自动化会话移入容器。
• 使用 "all" 时，无论上下文如何，所有会话均在容器内运行。

除此之外，您还需选择一个工作区访问级别，用于决定容器能看到多少文件系统。默认的 "none" 会在 ~/.openclaw/sandboxes 下为沙箱分配一个隔离目录，无法访问您的项目文件。

若设置为 "ro"，您的工作区将以只读方式挂载到 /agent，Agent 可读取代码但无法更改。"rw" 则进一步授予在 /workspace 的完全读写访问。

一个在沙箱中运行后台会话、并授予写入权限的可用配置如下：

{
  "agents": {
	"defaults": {
  	"sandbox": {
    	"mode": "non-main",
    	"scope": "session",
    	"workspaceAccess": "rw"
  	}
	}
  }
}

一旦您的技能开始调用 API 或处理凭证，这就会变得相关。

当技能在容器内运行时，宿主机的环境变量不会自动可用。您在 .bashrc 中导出的 REPLICATE_API_TOKEN 在沙箱内并不存在，因此密钥需要通过 OpenClaw 的配置系统传递。我们将在下一节中完成相关设置。

提示：如果您的技能在元数据中使用 requires.bins 对 CLI 工具做门控，该检查会在加载时于宿主机上运行。但当 Agent 处于沙箱中时，该二进制也必须存在于容器内。请通过 sandbox.docker.setupCommand 安装，或将其烘焙进自定义 Docker 镜像。

沙箱还能在文件操作或 shell 命令出错时缩小影响范围。一个意外运行 rm -rf / 的技能将命中容器文件系统，而非您的真实机器。这是即便您信任自己的代码，也值得开启沙箱的充分理由。

关于 AI Agent 工作流如何处理安全边界的更多内容，请参见使用 Claude CoWork 的 AI Agent 工作流。

构建一个连接 API 的技能

第二个技能通过 Replicate API 使用 Google 的Nano Banana Pro（Gemini 3 Pro Image）模型生成图像，这意味着在 SKILL.md 基础之上接入凭证管理与环境门控。

创建技能文件夹：

mkdir -p ~/.openclaw/skills/nano-banana-pro

创建 ~/.openclaw/skills/nano-banana-pro/SKILL.md，从前置区开始：

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image on Replicate
user-invocable: true
metadata: {"openclaw": {"emoji": "🎨", "requires": {"env": ["REPLICATE_API_TOKEN"], "bins": ["uv"]}, "primaryEnv": "REPLICATE_API_TOKEN"}}
---

其结构与第一个技能相同，但 metadata 字段承担了更多职责。它现在包含两个门控：requires.env 会在加载技能前检查 REPLICATE_API_TOKEN 是否存在，requires.bins 会检查 uv。任一缺失，技能都会被静默跳过。

emoji 字段会在 Telegram 的斜杠命令列表中设置一个图标。而 primaryEnv 则将 REPLICATE_API_TOKEN 映射到配置中的 apiKey 快捷字段（详见下文凭证部分）。

如果您希望 macOS 的 Skills UI 提供必需二进制的一键安装，请在元数据中添加 install 数组：

metadata: {"openclaw": {"requires": {"bins": ["uv"]}, "install": [{"id": "brew", "kind": "brew", "formula": "uv", "bins": ["uv"], "label": "Install uv (brew)"}]}}

在 Linux 上，请手动处理安装或通过 sandbox.docker.setupCommand 完成。

在前置区下方，添加指令正文：

# Nano Banana Pro Image Generator
 
Generate and edit images using Google's Nano Banana Pro model via the Replicate API.
 
## Usage
 
Run the generation script:
 
	uv run --with replicate python {baseDir}/generate.py --prompt "<user prompt>" [--aspect-ratio 1:1] [--output image.png]
 
## Options
 
- --prompt: The image description (required)
- --aspect-ratio: Ratio like 1:1, 4:3, 16:9 (default: 1:1)
- --output: Output file path (default: generated_image.png)
 
## Tips
 
- For text in images, be specific about fonts, size, and placement
- The model supports resolutions up to 2K
- Safety filtering is on by default

该正文比第一个技能更短，因为生成脚本承担了大部分复杂性。{baseDir} 模板变量同样会在运行时解析为技能文件夹路径。

生成脚本

添加 ~/.openclaw/skills/nano-banana-pro/generate.py：

import replicate
import urllib.request
import argparse
 
def main():
	parser = argparse.ArgumentParser()
	parser.add_argument("--prompt", required=True)
    parser.add_argument("--aspect-ratio", default="1:1")
	parser.add_argument("--output", default="generated_image.png")
	args = parser.parse_args()
 
	output = replicate.run(
    	"google/nano-banana-pro",
    	input={
        	"prompt": args.prompt,
        	"aspect_ratio": args.aspect_ratio,
        	"output_format": "png",
        	"safety_filter_level": "block_only_high",
    	},
	)
 
	# Replicate returns a FileOutput; download the image
	url = str(output[0]) if isinstance(output, list) else str(output)
	urllib.request.urlretrieve(url, args.output)
	print(f"Image saved to {args.output}")
 
if __name__ == "__main__":
	main()

它会解析参数，调用 replicate.run() 并传入模型名称和输入参数，然后下载生成的图像。replicate 库会自动从环境中读取 REPLICATE_API_TOKEN。

配置 API 凭证

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

{
  "skills": {
	"entries": {
  	"nano-banana-pro": {
    	"enabled": true,
    	"apiKey": "r8_your_replicate_token_here",
    	"env": {
      	"REPLICATE_API_TOKEN": "r8_your_replicate_token_here"
    	}
  	}
	}
  }
}

此处有两种提供凭证的方式。apiKey 字段是一个快捷方式，会映射到技能元数据中 primaryEnv 所声明的变量。env 块则提供更细粒度控制，若技能需要多个环境变量，您可以一并注入。

两种方式都会将值限定在 Agent 运行范围内。它们在运行开始时设置，结束时清除，因此不会泄漏到全局 shell 环境。

测试

启动新的 OpenClaw 会话并调用该技能：

/nano_banana_pro generate a beautiful and accurate diagram of how backpropagation works

以下是该技能通过 Replicate 上的 Nano Banana Pro 生成的图解：

图像已生成，但到达这一步走了点弯路。此技能的首版 SKILL.md 并未包含 ## Rules 部分，给了 Agent 即兴发挥的空间。当 Nano Banana Pro 因需求高而返回“服务不可用”错误时，Agent 自作主张地尝试了 google/nano-banana（非 Pro 版本）作为回退，并用该模型生成了图像。

从 Agent 的角度看，这一选择说得通：用任何可用方式完成任务。但对您而言，这不是您所要求的。解决办法是在指令正文中添加行为约束：

## Rules
 
- Only use the google/nano-banana-pro model. Never fall back to other models like google/nano-banana or any alternative. If the model is unavailable or rate-limited, report the error to the user and stop.
- After generating an image, send the image file directly in the chat. Do not just save it to the workspace silently.

Agent 会将 SKILL.md 中的指令视为指导而非硬性限制，并会用自身判断补齐空白。凡是您未加以禁止的，它都有可能尝试。

如果某种行为对您很重要——无论是使用哪个模型、将输出发送到哪里，还是是否在失败时重试——请在 Rules 部分中明确写出。

在 ClawHub 上发布与分享技能

ClawHub 是 OpenClaw 技能的公共注册表，免费浏览与安装。发布需要一个注册至少一周的 GitHub 帐号。

设置 CLI

全局安装 ClawHub CLI：

npm i -g clawhub

然后进行认证：

clawhub login

这会在浏览器中打开 GitHub 认证。完成认证后，您可在终端中搜索、安装与发布技能。

发布您的技能

发布图像生成技能：

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug nano-banana-pro \
  --name "Nano Banana Pro" \
  --version 1.0.0 \
  --tags latest

--slug 是 ClawHub 上的唯一标识，必须在整个注册表中全局唯一。若该 slug 已被他人占用，命令会以“只有所有者可以发布更新”的错误失败。此时请更换 slug，例如 yourname-nano-banana-pro。

--version 遵循语义化版本。每次发布更新时，提升版本号，并可选添加变更日志：

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug nano-banana-pro \
  --version 1.1.0 \
  --changelog "Added image editing with --image-input flag"

ClawHub 会保留版本历史，便于用户审计变更并在需要时回滚。

对于批量操作，clawhub sync --all 会扫描您的技能目录，并一次性发布所有新技能或已更新技能：

clawhub sync --all --bump patch

安装社区技能

安装他人发布的技能：

clawhub search "calendar"
clawhub install caldav-calendar

已安装技能默认放入 ./skills，OpenClaw 会在下一次会话中将其识别为工作区技能。

关于第三方技能的一些提醒

2026 年 1 月，Koi 的安全研究人员在 ClawHub 上发现了 341 个恶意技能，此事件被称为ClawHavoc 事件。攻击者使用拼写近似的技能名和伪造的“前置条件”安装步骤来分发 Atomic macOS Stealer（AMOS）、反向 shell，以及凭证渗出载荷。

到 2026 年 2 月中旬，被标记的技能数量已增长到数十个分类中的 824 个以上。

在安装任何社区技能之前，请阅读其 SKILL.md 和配套文件。警惕可疑的“前置条件”安装步骤、混淆代码或 base64 编码命令。ClawHub 会自动隐藏被 3 个或以上用户举报的技能，但新出现的恶意技能可能比审核更快。

像Clawdex 这样的工具可以将您已安装的技能与已知恶意包数据库进行比对扫描。

对第三方技能应保持与任何第三方代码相同的谨慎：运行前先审查。

结语

借助 SKILL.md 格式、通过 openclaw.json 实现的凭证范围控制，以及 ClawHub CLI，您即可完成从本地自动化到共享包的完整生命周期。

构建新 OpenClaw 技能的大部分工作，在于为 Markdown 正文撰写清晰的指令，并决定在元数据中做哪些门控。实际代码——无论是转换脚本还是 API 调用——都放在独立文件中，便于您单独测试与迭代。

若要超出本教程所覆盖的范围，OpenClaw 仓库中的捆绑技能展示了核心团队如何组织更复杂的工作流。Claude Opus 4.6 概览更深入地探讨了模型选择如何影响 Agent 行为，Claude 模型入门课程则提供了对 OpenClaw 等 Agent 背后模型的上手实践。