手把手教你构建 OpenClaw 自定义技能：从本地脚本到 API 集成

OpenClaw 的内置技能已经涵盖了大部分常见工作流，ClawHub 社区也提供了成千上万的选择。但对于开发者来说，最有价值的技能往往是那些尚未被定义的——即围绕你特定项目和工具链量身定制的自动化逻辑。

这篇指南将带你开发两个实用的自定义技能：一个是将 Jupyter Notebook 转换为 Word 文档的本地工具，将繁琐的导出过程简化为一个斜杠命令（slash command）；另一个是通过 Replicate API 调用 Nano Banana Pro 模型生成图像，并在此过程中深入探讨凭据管理和环境隔离的最佳实践。

除此之外，我们还会涉及 Docker 沙箱、元数据门控以及如何将你的作品推送到 ClawHub。

深度理解 OpenClaw 技能

在 OpenClaw 的体系中，“技能（Skill）”是扩展 Agent 行为的核心方式。它可以简单到只是一个格式化代码的命令，也可以复杂到是一个跨平台的、包含 PR 评审并同步到 Jira/Slack 的多步流。

如果你接触过 Claude Code 中的 MCP (Model Context Protocol)，可能会好奇两者的区别。简单来说，MCP 服务器是独立的进程，通过标准协议暴露工具，适合需要持久状态或多端点集成的场景。而 OpenClaw 技能则更轻量：你只需编写自然语言指令，Agent 在运行时读取并执行。这种方式极大地降低了构建门槛，尤其适合那些“只想快速自动化某件事”的需求。

另一个容易混淆的概念是 Hooks。Hooks 是自动触发的（例如工具调用完成时），而技能则处于静默状态，直到用户输入斜杠命令或 Agent 判断当前任务需要调用它。

环境准备

开始之前，请确保你已具备：

OpenClaw 环境：建议通过 Telegram 运行，因为它对斜杠命令的支持最为友好。
uv 工具：本文的 Python 依赖管理将全部交给 uv。
API 令牌：图像生成技能需要 Replicate API token。
GitHub 账号：如果计划发布技能到 ClawHub，账号需注册满一周。

实战一：Jupyter Notebook 转 Word 技能

很多开发者习惯在 Notebook 中写方案，但交付时往往需要 .docx 格式。我们将编写一个 Python 脚本并将其封装为技能。

首先，在 OpenClaw 的管理目录中创建技能文件夹：

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

编写 SKILL.md

每个技能的核心都是 SKILL.md。其顶部的 YAML Frontmatter 定义了加载逻辑，下方的 Markdown 则是 Agent 遵循的指令。

在目录中创建 SKILL.md：

---
name: notebook-to-docx
description: 将 Jupyter Notebook 转换为格式规范的 Word 文档
user-invocable: true
metadata: {"openclaw": {"requires": {"bins": ["uv"]}}}
---

这里有几个关键点：

name 决定了命令名（/notebook-to-docx）。
user-invocable: true 确保在聊天界面中可见。
metadata 中的 requires.bins 是一种“静态门控”，如果系统没装 uv，该技能会自动隐藏。

在 Frontmatter 之后，添加指令正文：

# Notebook 转 DOCX 转换器

## 使用方法
运行以下转换脚本：
	uv run --with nbformat --with python-docx --with Pillow python {baseDir}/notebook_to_docx.py <notebook_path> [output_path]

## 功能特性
- 保持 Markdown 样式（加粗、标题等）
- 代码块使用 Courier New 字体并保留语法标识
- 支持图像嵌入及超链接转换

注意 {baseDir} 变量，它在运行时会自动解析为技能文件夹的绝对路径。

脚本逻辑

配套的 Python 脚本 notebook_to_docx.py 需放在同一目录下。你可以从这个 Gist 获取完整源码。核心逻辑是利用 nbformat 解析 JSON 结构，再通过 python-docx 映射到 Word 的样式树。

测试技能

OpenClaw 拥有文件监听机制，通常在保存 SKILL.md 后 250ms 内即可生效。在 Telegram 中输入 /notebook-to-docx 并指向你的 .ipynb 文件，Agent 就会自动调用脚本完成转换。

安全与 Docker 沙箱

在运行第三方或自定义脚本时，安全性是绕不开的话题。OpenClaw 允许你在 Docker 容器中执行工具，防止恶意代码污染宿主机。

在 ~/.openclaw/openclaw.json 中，你可以通过 agents.defaults.sandbox 进行配置：

"off"：直接在宿主机运行（默认）。
"non-main"：主对话在宿主机，后台/自动化任务进容器。
"all"：全量沙箱化。

配置示例：

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

专家提示：开启沙箱后，宿主机的环境变量不会自动透传。像 REPLICATE_API_TOKEN 这样的密钥需要通过 OpenClaw 的配置系统注入，而非简单的 export。

实战二：对接 Replicate 图像生成 API

第二个技能我们将调用 Google 的 Nano Banana Pro 模型。这涉及如何优雅地管理 API 凭据。

创建文件夹：~/.openclaw/skills/nano-banana-pro。

增强型元数据

在 SKILL.md 中，我们需要处理 API 令牌的门控：

---
name: nano-banana-pro
description: 通过 Replicate 调用 Gemini 3 Pro Image 生成图像
user-invocable: true
metadata: {"openclaw": {"emoji": "🎨", "requires": {"env": ["REPLICATE_API_TOKEN"], "bins": ["uv"]}, "primaryEnv": "REPLICATE_API_TOKEN"}}
---

primaryEnv 的作用是将特定的环境变量映射到配置中的 apiKey 快捷方式。

编写生成脚本

创建 generate.py：

import replicate
import urllib.request
import argparse

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt", required=True)
    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": "1:1"}
    )
    
    url = str(output[0])
    urllib.request.urlretrieve(url, args.output)
    print(f"图像已保存至 {args.output}")

if __name__ == "__main__":
    main()

配置凭据

在 ~/.openclaw/openclaw.json 中安全地注入密钥：

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

这些环境变量仅在技能执行期间有效，运行结束即销毁。

避坑指南：Agent 的“过度发挥”

在测试图像生成技能时，我发现如果不加约束，当 API 报错（如服务过载）时，Agent 会自作聪明地尝试切换到其他模型（如非 Pro 版）。

这种“自主性”有时会违背用户的初衷。解决办法是在 SKILL.md 中显式添加 Rules 章节：

## 行为准则
- 仅允许使用 google/nano-banana-pro 模型，严禁自动降级或切换模型。
- 如果 API 报错或限流，请直接向用户报告错误并停止。
- 生成图像后，必须直接在对话中发送文件，不得仅静默保存到工作区。

Agent 会将这些规则视为高优先级指令。记住：你没禁止的行为，它都可能尝试。

发布到 ClawHub

ClawHub 是技能的公共集市。发布前需安装 CLI：

npm i -g clawhub
clawhub login

执行发布命令：

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug my-nano-banana-pro \
  --version 1.0.0

警惕供应链安全

在 2026 年初的 ClawHavoc 事件中，安全研究员发现了数百个恶意技能，它们利用拼写错误的名称（typosquatting）分发木马。因此，在安装社区技能前，务必审查其 SKILL.md 和配套脚本，警惕任何可疑的 Base64 编码命令或非必要的安装步骤。

结语

构建 OpenClaw 技能的本质并非编写复杂的代码，而是编写清晰、有边界感的 Markdown 指令。通过将逻辑解耦到脚本、将凭据收敛到配置、将运行环境隔离到沙箱，你可以构建出一套既强大又安全的 Agent 军械库。

下一步，你可以尝试查看 OpenClaw 官方库中的源码，学习如何处理更复杂的流式输出和多轮交互逻辑。

关于

关注我获取更多资讯

📢 公众号

💬 个人号