// TÀI LIỆU AI

🧩 OpenClaw Skills Development

Tạo skills & plugins tùy chỉnh cho OpenClaw — mở rộng khả năng AI agent từ web search đến database, từ API đến IoT.

TypeScript Plugin AI Agent Development

Sau bài này bạn sẽ

Hiểu 3 loại extension: Skills, Plugins, Custom Tools
Tạo Skill đầu tiên bằng SKILL.md (Markdown)
Tạo Plugin TypeScript xử lý logic phức tạp
Biết cách test và debug skills
Publish skill lên ClawHub

Dành cho

Developers đã setup OpenClaw, muốn mở rộng

Yêu cầu trước

Đọc bài OpenClaw, TypeScript cơ bản

⏱️ Thời gian

~20 phút

📑 Mục lục

Tổng quan hệ thống mở rộng
Tạo Skill bằng Markdown
Tạo Plugin TypeScript
Custom Tool via API
Testing & Debugging
Publish lên ClawHub
Best Practices & Bước tiếp

1. Tổng quan hệ thống mở rộng

Loại	Format	Khi nào dùng	Ví dụ
Skills	SKILL.md (Markdown)	Prompt engineering, hướng dẫn LLM cách dùng API sẵn có	Weather skill, Translator
Plugins	TypeScript module	Logic phức tạp, cần code xử lý dữ liệu, auth, stateful	Database connector, OAuth handler
Custom Tools	REST API endpoint	Wrap API bên ngoài thành tool cho agent	Jira, Notion, CRM

Chọn nào? Bắt đầu với Skill (SKILL.md) — không cần code, nhanh 5 phút. Cần phức tạp hơn → Plugin TypeScript. Đã có API → Custom Tool.

2. Tạo Skill bằng Markdown

Skills dạng Markdown là cách đơn giản nhất — bạn viết hướng dẫn cho LLM bằng Markdown, kèm API key và format trả về.

Ví dụ: Weather Skill

skills/weather/SKILL.md

---
name: weather
description: "Lấy thông tin thời tiết thành phố"
trigger: "thời tiết|weather|nhiệt độ"
---

# Weather Skill

## Cách sử dụng
Khi user hỏi về thời tiết, gọi API:

```
GET https://api.openweathermap.org/data/2.5/weather
  ?q={city_name}
  &appid=${WEATHER_API_KEY}
  &units=metric
  &lang=vi
```

## Format trả lời
Trả lời theo format:
🌤️ Thời tiết {city}:
- Nhiệt độ: {temp}°C (cảm giác: {feels_like}°C)
- Tình trạng: {description}
- Độ ẩm: {humidity}%
- Gió: {wind_speed} km/h

## Lưu ý
- Nếu user không nói thành phố, hỏi lại
- Nếu API lỗi, nói "Không lấy được thông tin"

terminal

# Thêm API key vào .env
echo "WEATHER_API_KEY=your_key" >> .env

# Restart agent
npm run dev

📤 Test trên Telegram

You: Thời tiết Hà Nội
Bot: 🌤️ Thời tiết Hà Nội:
     - Nhiệt độ: 24°C (cảm giác: 26°C)
     - Tình trạng: Mây rải rác
     - Độ ẩm: 78%
     - Gió: 12 km/h

3. Tạo Plugin TypeScript

Khi cần logic phức tạp (database queries, auth, data processing), viết Plugin TypeScript:

plugins/todo/index.ts

import { Plugin, ToolDefinition } from '@openclaw/core';

interface Todo {
  id: number;
  text: string;
  done: boolean;
}

export class TodoPlugin extends Plugin {
  private todos: Todo[] = [];
  private nextId = 1;

  name = 'todo';
  description = 'Quản lý danh sách todo';

  tools(): ToolDefinition[] {
    return [
      {
        name: 'add_todo',
        description: 'Thêm todo mới',
        parameters: {
          text: { type: 'string', required: true }
        },
        handler: async ({ text }) => {
          const todo = { 
            id: this.nextId++, text, done: false 
          };
          this.todos.push(todo);
          return ` Đã thêm: "${text}" (#${todo.id})`;
        }
      },
      {
        name: 'list_todos',
        description: 'Xem danh sách todos',
        parameters: {},
        handler: async () => {
          if (this.todos.length === 0) 
            return ' Danh sách trống!';
          return this.todos.map(t => 
            `${t.done ? '' : '⬜'} #${t.id}: ${t.text}`
          ).join('\n');
        }
      }
    ];
  }
}

Đăng ký plugin

config/plugins.ts

import { TodoPlugin } from '../plugins/todo';

export const plugins = [
  new TodoPlugin(),
  // ... other plugins
];

4. Custom Tool via API

Nếu bạn đã có REST API, wrap nó thành tool:

tools/jira.json

{
  "name": "create_jira_ticket",
  "description": "Tạo Jira ticket mới",
  "endpoint": "https://your-domain.atlassian.net/rest/api/3/issue",
  "method": "POST",
  "headers": {
    "Authorization": "Basic ${JIRA_TOKEN}",
    "Content-Type": "application/json"
  },
  "body_template": {
    "fields": {
      "project": { "key": "{{project}}" },
      "summary": "{{summary}}",
      "issuetype": { "name": "Task" }
    }
  }
}

5. Testing & Debugging

terminal

# Test skill riêng lẻ (không cần Telegram)
npx openclaw test-skill weather "thời tiết Đà Nẵng"

# Test plugin
npx openclaw test-plugin todo "thêm mua sữa"

# Debug mode (log mọi LLM interaction)
DEBUG=openclaw:* npm run dev

6. Publish lên ClawHub

terminal

# Đăng nhập ClawHub
npx clawhub login

# Validate skill/plugin
npx clawhub validate ./skills/weather

# Publish
npx clawhub publish ./skills/weather

7. Best Practices & Bước tiếp

Best Practices

Description rõ ràng — LLM quyết định dùng tool nào dựa trên description
Error handling — luôn trả message thân thiện khi lỗi
Rate limiting — giới hạn API calls trong plugin
Idempotent — cùng input → cùng output

❌ Sai lầm

Description quá dài — tốn tokens, LLM confused
Không validate input — user gửi gì LLM forward thẳng
Hardcode secrets — luôn dùng env variables

🔜 Đọc tiếp

OpenClaw — nếu chưa setup agent
AI Security — bảo mật skills & plugins
RAG — tạo RAG skill cho agent

← Bài trước Embedding Bài tiếp theo → 🛡️ AI Security