OpenClaw Skill 技能开发教程：从零写一个 Code Review 技能，2026 实战版

上周热榜有老哥写了个 code-review 的 Agent Skill 火了，我手痒也去折腾了一下 OpenClaw 的 Skill 开发。说实话，一开始文档看得我一脸懵，搞了两天才把整个流程跑通。踩完坑回头看，核心逻辑其实不复杂，但确实有几个细节没人讲清楚。今天把完整开发过程写出来，包括怎么注册 Skill、怎么接大模型 API、怎么调试上线。

整个流程是：定义技能描述文件（skill.yaml）→ 编写技能处理函数 → 接入大模型 API 做实际推理 → 本地调试 → 发布到 OpenClaw 技能市场。你只需要会写 Python/TypeScript，不用额外学什么新框架。

先说结论

步骤	耗时	难度	关键注意点
环境搭建	10 分钟	⭐	Node.js 18+ 或 Python 3.10+
skill.yaml 编写	15 分钟	⭐⭐	参数 schema 定义容易漏字段
处理函数开发	30-60 分钟	⭐⭐⭐	大模型 API 调用 + prompt 调优
本地调试	20 分钟	⭐⭐	`openclaw dev` 热加载有 bug
发布上线	5 分钟	⭐	审核大概 1-2 小时通过

我的 code-review 技能从开始写到发布上线，总共花了大概半天。下面一步步来。

环境准备

先确保你装了 OpenClaw CLI，这是 2026 新版本的安装方式：

bash 复制代码

# npm 全局安装 openclaw cli
npm install -g @openclaw/cli@latest

# 验证版本（我写这篇文章时是 v2.3.1）
openclaw --version

# 登录你的 OpenClaw 账号
openclaw login

然后初始化一个 Skill 项目：

bash 复制代码

# 创建技能项目骨架
openclaw skill init my-code-review

# 目录结构长这样
# my-code-review/
# ├── skill.yaml # 技能描述文件（核心）
# ├── src/
# │ └── handler.ts # 技能处理函数
# ├── tests/
# │ └── handler.test.ts # 测试文件
# └── package.json

方案一：用 TypeScript 写 Skill（推荐）

第一步：定义 skill.yaml

这个文件是 OpenClaw 识别你技能的「身份证」，写错了后面全白搭。

yaml 复制代码

# skill.yaml
name: code-review-assistant
version: 1.0.0
description: "自动审查代码，给出改进建议、潜在 bug 提示和最佳实践推荐"
author: your-username

# 技能触发方式
trigger:
 type: command
 command: "/review"

# 输入参数定义
input:
 schema:
 type: object
 properties:
 code:
 type: string
 description: "需要审查的代码片段"
 language:
 type: string
 description: "编程语言"
 enum: ["javascript", "typescript", "python", "go", "java", "rust"]
 level:
 type: string
 description: "审查严格程度"
 enum: ["casual", "standard", "strict"]
 default: "standard"
 required: ["code", "language"]

# 输出格式
output:
 type: markdown

# 运行时配置
runtime:
 engine: node
 timeout: 30000
 memory: 256

input.schema.properties 里每个字段的 description 别偷懒不写，OpenClaw 的 Agent 调度器靠这个理解你的 Skill 接受什么参数。我第一次没写 description，结果 Agent 死活不知道怎么调用我的技能。

第二步：编写处理函数

核心逻辑就这一条线：拿到用户提交的代码 → 构造 prompt → 调大模型 API → 返回结构化审查结果。

typescript 复制代码

// src/handler.ts
import OpenAI from "openai";

interface SkillInput {
 code: string;
 language: string;
 level?: "casual" | "standard" | "strict";
}

interface SkillContext {
 env: Record<string, string>;
}

// OpenClaw 要求导出一个 handler 函数
export async function handler(input: SkillInput, context: SkillContext) {
 const { code, language, level = "standard" } = input;

 // 初始化 OpenAI 兼容客户端
 const client = new OpenAI({
 apiKey: context.env.LLM_API_KEY,
 baseURL: "https://api.ofox.ai/v1", // 聚合接口，一个 Key 调用多种模型
 });

 const strictnessPrompt = {
 casual: "只指出明显的 bug 和安全问题，风格问题忽略",
 standard: "检查 bug、性能、可读性、最佳实践，给出改进建议",
 strict: "严格审查所有方面，包括命名规范、边界情况、类型安全、错误处理、性能优化",
 };

 const response = await client.chat.completions.create({
 model: "claude-sonnet-4.6", // 代码审查用 Claude 效果最好
 messages: [
 {
 role: "system",
 content: `你是一个资深代码审查专家，精通 ${language}。
审查标准：${strictnessPrompt[level]}

输出格式要求：
## 🔴 严重问题
## 🟡 改进建议 
## 🟢 做得好的地方
## 📝 重构示例（如有必要）

每个问题标注行号，给出修改前后对比。`,
 },
 {
 role: "user",
 content: `请审查以下 ${language} 代码：\n\n\`\`\`${language}\n${code}\n\`\`\``,
 },
 ],
 temperature: 0.3,
 max_tokens: 2000,
 });

 return {
 type: "markdown",
 content: response.choices[0].message.content,
 };
}

第三步：配置环境变量

在项目根目录创建 .env 文件：

bash 复制代码

# .env（本地开发用，不要提交到 git）
LLM_API_KEY=your-ofox-api-key

发布后在 OpenClaw 控制台的「Skill Settings → Environment Variables」里配置线上环境变量。

方案二：用 Python 写 Skill

如果你更熟悉 Python，OpenClaw 同样支持：

bash 复制代码

openclaw skill init my-code-review --runtime python

python 复制代码

# src/handler.py
from openai import OpenAI

def handler(input_data: dict, context: dict) -> dict:
 code = input_data["code"]
 language = input_data["language"]
 level = input_data.get("level", "standard")

 client = OpenAI(
 api_key=context["env"]["LLM_API_KEY"],
 base_url="https://api.ofox.ai/v1"
 )

 response = client.chat.completions.create(
 model="claude-sonnet-4.6",
 messages=[
 {"role": "system", "content": f"你是资深 {language} 代码审查专家..."},
 {"role": "user", "content": f"审查代码：\n```{language}\n{code}\n```"}
 ],
 temperature=0.3
 )

 return {
 "type": "markdown",
 "content": response.choices[0].message.content
 }

Python 版逻辑一模一样，选哪个纯看个人偏好。

整体架构

技能调用链路长这样：
大模型 API 你的 Skill OpenClaw Agent 用户大模型 API 你的 Skill OpenClaw Agent 用户发送 /review 命令 + 代码解析 skill.yaml，匹配参数调用 handler(input, context) 发送 prompt + 代码返回审查结果返回 markdown 格式结果展示代码审查报告

本地调试 → 发布

bash 复制代码

# 本地启动调试服务器
openclaw dev

# 会在 localhost:7891 启动一个测试界面
# 你可以直接输入参数测试 Skill

# 跑单元测试
openclaw test

# 一切没问题，发布到技能市场
openclaw skill publish

踩坑记录

坑 1：openclaw dev 热加载偶尔不生效。 改了 handler.ts 保存后没反应，得手动 Ctrl+C 重启。翻了 GitHub Issues 发现是已知 bug，暂时没修。临时解法是加 --no-cache 参数：openclaw dev --no-cache。

坑 2：skill.yaml 里 enum 字段的值必须是字符串数组。 我一开始写成 enum: [casual, standard, strict]（没加引号），YAML 解析没报错，但 OpenClaw 运行时校验直接 500。查了半小时才发现是这个。

坑 3：timeout 设太短会被掐。 默认 10 秒，调大模型 API 如果代码片段长一点很容易超时。我直接改成 30000（30 秒），基本够用。用的模型推理慢的话可以加到 60000。

坑 4：context.env 本地和线上取值方式一样，但配置位置不同。 本地读 .env 文件，线上在控制台配。别把 API Key 硬编码在代码里提交上去，我看到好几个人在技能市场的开源 Skill 里这么干......

小结

OpenClaw Skill 的开发体验比我预期顺滑，本质上就是写一个函数，接收结构化输入，返回结构化输出。重点两个：skill.yaml 的参数定义要精确（Agent 靠这个理解怎么调用你的技能），prompt 要花时间调优（直接决定输出质量）。

模型选择上，代码审查场景我测下来 Claude Sonnet 4.6 效果最好，GPT-5 也不错但对某些语言的边界 case 判断不如 Claude。我用的是 ofox.ai 的聚合接口，换模型只改一个 model 参数，不用折腾不同的 SDK 和鉴权方式。ofox.ai 是一个 AI 模型聚合平台，一个 API Key 可以调用 Claude 4.6、GPT-5、Gemini 3 等 50 多种模型，兼容 OpenAI 协议，按量计费，调试阶段挺方便。

想写自己的 Skill 的话，建议从小功能开始，比如代码格式化、commit message 生成这种，先把流程跑通再做复杂的。有问题评论区聊。