Xây dựng kỹ năng OpenClaw tùy chỉnh: Hướng dẫn thực hành

Các kỹ năng tích hợp sẵn của OpenClaw bao phủ những quy trình phổ biến và ClawHub còn có rất nhiều kỹ năng khác. Nhưng những kỹ năng quan trọng nhất thường lại là những kỹ năng chưa ai xây dựng: các tự động hóa được thiết kế quanh dự án và công cụ của chính bạn.

Hướng dẫn này sẽ chỉ bạn cách xây dựng hai kỹ năng tùy chỉnh. Kỹ năng đầu tiên bao bọc một script Python chuyển đổi Jupyter notebook sang tài liệu Word. Nếu bạn viết trong notebook nhưng bàn giao tệp .docx cho biên tập viên hoặc các bên liên quan, thao tác này biến việc xuất thủ công thành một lệnh gạch chéo. Kỹ năng thứ hai tạo ảnh bằng Nano Banana Pro thông qua Replicate API, bổ sung quản lý thông tin xác thực và giới hạn môi trường lên phần nền tảng.

Hướng dẫn cũng đề cập đến sandbox Docker, ràng buộc bằng metadata và xuất bản kỹ năng lên ClawHub. Để có cái nhìn tổng quan hơn về nền tảng OpenClaw, xem OpenClaw Projects: Bạn có thể xây dựng gì và hướng dẫn của chúng tôi về các kỹ năng hàng đầu cho agent. 

OpenClaw Skills là gì?

Skills là cách bạn bổ sung hành vi mới cho agent OpenClaw. Một skill có thể đơn giản là lệnh gạch chéo định dạng lại mã, hoặc phức tạp như một quy trình nhiều bước rà soát PR và đăng bình luận lên Jira hay Slack.

Nếu bạn đã dùng máy chủ MCP (Model Context Protocol) trong Claude Code hoặc công cụ tương tự, skills đảm nhận vai trò khác. Máy chủ MCP là các tiến trình riêng, phơi lộ công cụ qua một giao thức tiêu chuẩn, phù hợp cho tích hợp cần trạng thái bền và nhiều điểm cuối công cụ. 

Skills bỏ qua tất cả những điều đó: bạn viết hướng dẫn bằng ngôn ngữ tự nhiên để agent đọc và làm theo khi chạy, giúp xây dựng nhanh hơn khi bạn chỉ cần tự động hóa một việc. Bài so sánh OpenClaw và Claude Code phân tích sâu hơn về các đánh đổi.

Hooks, điểm mở rộng còn lại, sẽ kích hoạt tự động khi có sự kiện xảy ra, như một lệnh gọi công cụ hoàn tất hoặc mô hình sinh phản hồi. Skills thì ở trạng thái chờ cho đến khi người dùng gõ lệnh gạch chéo hoặc agent cho rằng nó phù hợp với tác vụ hiện tại.

OpenClaw đi kèm 49 kỹ năng bao phủ email, lịch, GitHub, tự động hóa trên trình duyệt và hơn thế nữa. Cộng đồng đã xuất bản hàng nghìn kỹ năng bổ sung trên ClawHub. Để tìm hiểu bối cảnh sự phát triển của nền tảng, xem lịch sử từ MoltBot đến ClawdBot.

Yêu cầu tiên quyết

Bạn sẽ cần:

• Cài đặt và chạy OpenClaw qua Telegram (hướng dẫn cài đặt). Tích hợp BotFather của Telegram hỗ trợ lệnh gạch chéo tốt nhất, đây là cách bạn kích hoạt skills trong suốt hướng dẫn này.
• uv đã được cài đặt (cả hai kỹ năng trong hướng dẫn này đều dùng nó cho phụ thuộc Python)
• Thành thạo terminal, YAML và Markdown
• Một token API Replicate cho kỹ năng tạo ảnh (đăng ký miễn phí, trả phí theo mức sử dụng)
• Tài khoản GitHub ít nhất một tuần tuổi, nếu bạn muốn xuất bản lên ClawHub

Nếu bạn muốn chạy OpenClaw với mô hình cục bộ, bài hướng dẫn OpenClaw với Ollama sẽ bao quát thiết lập đó.

Xây dựng kỹ năng OpenClaw đầu tiên của bạn

Kỹ năng đầu tiên này bao bọc một script Python chuyển đổi Jupyter notebook sang tài liệu Word, xử lý định dạng markdown, khối mã, hình ảnh, bảng và siêu liên kết để đầu ra .docx giữ nguyên cấu trúc của notebook gốc. Nếu bạn thường xuyên bàn giao nội dung notebook cho những người làm việc bằng Word, thao tác này biến việc xuất thủ công thành một lệnh gạch chéo duy nhất.

Tạo thư mục kỹ năng trong thư mục kỹ năng được quản lý của OpenClaw:

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

Các kỹ năng trong ~/.openclaw/skills khả dụng trên mọi phiên của bạn. Bạn cũng có thể đặt chúng trong một dự án tại <project>/skills để giới hạn trong không gian làm việc đó, và khi một tên xuất hiện ở cả hai vị trí, bản trong workspace sẽ được ưu tiên hơn bản quản lý, vốn lại ghi đè bất kỳ kỹ năng đi kèm nào trùng tên.

Viết SKILL.md

Mỗi kỹ năng cần một tệp: SKILL.md. YAML frontmatter ở đầu xác định cách OpenClaw tải kỹ năng, và phần thân markdown bên dưới chứa hướng dẫn mà agent sẽ làm theo khi chạy.

Tạo ~/.openclaw/skills/notebook-to-docx/SKILL.md, bắt đầu với frontmatter:

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

name đồng thời là lệnh gạch chéo (/notebook-to-docx). description cung cấp cho agent một dòng mô tả để đánh giá mức độ liên quan đến tác vụ hiện tại. Đặt user-invocable: true sẽ đăng ký lệnh gạch chéo trong cuộc trò chuyện Telegram của bạn. Trường metadata xử lý ràng buộc lúc tải: requires.bins yêu cầu OpenClaw bỏ qua kỹ năng này nếu uv không có trong PATH của hệ thống thay vì lỗi khi chạy. 

Nếu bạn muốn chiều ngược lại, nơi kỹ năng không bao giờ kích hoạt trừ khi bạn gõ lệnh gạch chéo, hãy đặt disable-model-invocation: true.

Mẹo: YAML frontmatter chỉ hỗ trợ giá trị một dòng. Chuỗi nhiều dòng hoặc block scalar sẽ gây lỗi phân tích, đó là lý do metadata là một đối tượng JSON một dòng thay vì YAML lồng nhau.

Bên dưới frontmatter, thêm phần hướng dẫn:

# 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} là biến mẫu được thay bằng đường dẫn thư mục kỹ năng khi chạy, vì vậy bạn không cần mã hóa cứng vị trí. Điều này quan trọng khi người khác cài kỹ năng của bạn ở thư mục khác. 

Các cờ uv run --with sẽ kéo ba thư viện mà script cần, giúp kỹ năng tự chứa thay vì giả định các gói đó đã tồn tại trong môi trường của người dùng.

Script hỗ trợ

Script Python đặt trong cùng thư mục với SKILL.md. Dài khoảng 490 dòng, quá dài để đưa vào đây, vì vậy hãy tải toàn bộ script từ gist này và đặt là notebook_to_docx.py trong ~/.openclaw/skills/notebook-to-docx/. Nó bao quát mọi thứ được liệt kê trong mục Tính năng của SKILL.md ở trên.

Đây là điểm vào để bạn thấy tổng quan hoạt động của nó:

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

Kiểm thử kỹ năng

OpenClaw chụp nhanh danh sách kỹ năng khi bắt đầu phiên, nhưng một bộ theo dõi tệp tích hợp sẽ phát hiện tệp SKILL.md mới trong khoảng 250ms. Nếu kỹ năng không xuất hiện, hãy khởi động lại phiên.

Đây là notebook chúng ta sẽ dùng để thử nghiệm:

Mở cuộc trò chuyện Telegram với OpenClaw và gõ /notebook-to-docx, sau đó cho biết notebook cần chuyển:

Tài liệu Word thu được:

Tiêu đề, khối mã, định dạng nội dòng và siêu liên kết đều được đưa về đúng kiểu Word. Nếu có gì đó trông không ổn trong đầu ra của bạn, hãy kiểm tra danh sách tính năng trong SKILL.md có khớp với những gì script hỗ trợ hay không.

Bảo mật và Sandboxing của OpenClaw

OpenClaw có thể chạy thực thi công cụ bên trong các container Docker, giúp giới hạn phạm vi tác động của một kỹ năng hoạt động sai hoặc bị xâm phạm trên máy của bạn. Thiết lập này nằm trong agents.defaults.sandbox bên trong ~/.openclaw/openclaw.json, và có ba chế độ để chọn:

• "off" là mặc định, công cụ chạy trực tiếp trên host, không có lớp cách ly.
• "non-main" giữ phiên chat chính của bạn trên host nhưng chuyển các phiên nền và tự động vào container.
• Với "all", mọi phiên đều chạy trong container bất kể ngữ cảnh.

Bên cạnh chế độ, bạn chọn mức truy cập workspace để quyết định container nhìn thấy bao nhiêu hệ thống tệp của bạn. Mặc định, "none" cấp cho sandbox một thư mục riêng biệt dưới ~/.openclaw/sandboxes và không cho phép truy cập tệp dự án của bạn. 

Với "ro", workspace của bạn được mount chỉ đọc tại /agent, vì vậy agent có thể đọc mã của bạn nhưng không thể thay đổi gì. "rw" tiến xa hơn và cấp quyền đọc-ghi đầy đủ tại /workspace.

Một cấu hình hoạt động, cô lập các phiên nền trong khi vẫn cấp quyền ghi trông như sau:

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

Điều này trở nên quan trọng ngay khi kỹ năng của bạn bắt đầu gọi API hoặc xử lý thông tin xác thực. 

Khi một kỹ năng chạy trong container, các biến môi trường từ host không tự động có sẵn. Một REPLICATE_API_TOKEN bạn đã export trong .bashrc sẽ không tồn tại trong sandbox, vì vậy các bí mật cần truyền qua hệ thống cấu hình của OpenClaw, điều mà chúng ta sẽ thiết lập ở phần tiếp theo.

Mẹo: Nếu kỹ năng của bạn dùng requires.bins trong metadata để ràng buộc một công cụ CLI, việc kiểm tra đó chạy trên host khi tải. Nhưng khi agent bị sandbox, binary đó cũng cần tồn tại trong container. Hãy cài qua sandbox.docker.setupCommand hoặc đóng gói vào một image Docker tùy chỉnh.

Sandboxing cũng giới hạn phạm vi thiệt hại khi thao tác tệp hoặc lệnh shell gặp sự cố. Một kỹ năng vô tình chạy rm -rf / sẽ tác động lên hệ thống tệp của container thay vì máy thật của bạn, đây là lý do hợp lý để bật tính năng này ngay cả khi bạn tin tưởng mã của mình. 

Để biết thêm cách các quy trình làm việc của AI agent xử lý ranh giới an toàn, xem AI Agent Workflows with Claude CoWork.

Xây dựng một kỹ năng kết nối API

Kỹ năng thứ hai tạo ảnh bằng mô hình Nano Banana Pro (Gemini 3 Pro Image) của Google thông qua Replicate API, đồng nghĩa với việc nối kết quản lý thông tin xác thực và ràng buộc môi trường lên phần cơ bản của SKILL.md.

Tạo thư mục kỹ năng:

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

Tạo ~/.openclaw/skills/nano-banana-pro/SKILL.md, bắt đầu với frontmatter:

---
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"}}
---

Cấu trúc giống với kỹ năng đầu tiên, nhưng trường metadata làm nhiều việc hơn. Giờ đây nó gồm hai lớp ràng buộc: requires.env kiểm tra REPLICATE_API_TOKEN tồn tại trước khi tải kỹ năng, và requires.bins kiểm tra cho uv. Nếu thiếu một trong hai, kỹ năng sẽ bị bỏ qua trong im lặng. 

Trường emoji đặt biểu tượng trong danh sách lệnh gạch chéo của Telegram. Và primaryEnv ánh xạ REPLICATE_API_TOKEN tới lối tắt apiKey trong cấu hình (chi tiết ở phần thông tin xác thực bên dưới).

Nếu bạn muốn giao diện Skills trên macOS cung cấp cài đặt một chạm cho các binary bắt buộc, hãy thêm mảng install vào metadata:

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

Trên Linux, hãy xử lý cài đặt thủ công hoặc qua sandbox.docker.setupCommand.

Bên dưới frontmatter, thêm phần hướng dẫn:

# 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

Phần thân ngắn hơn kỹ năng đầu tiên vì script tạo ảnh xử lý hầu hết độ phức tạp. Biến mẫu {baseDir} hoạt động tương tự, được thay bằng thư mục kỹ năng khi chạy.

Script tạo ảnh

Thêm ~/.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()

Script phân tích tham số, gọi replicate.run() với tên mô hình và tham số đầu vào, rồi tải ảnh kết quả. Thư viện replicate tự động đọc REPLICATE_API_TOKEN từ môi trường.

Cấu hình thông tin xác thực API

Thêm một mục vào ~/.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"
    	}
  	}
	}
  }
}

Có hai cách cung cấp thông tin xác thực ở đây. Trường apiKey là lối tắt ánh xạ tới biến do primaryEnv khai báo trong metadata của kỹ năng. Khối env cho phép bạn kiểm soát chi tiết hơn, đưa vào nhiều biến môi trường nếu kỹ năng cần. 

Cả hai cách đều giới hạn giá trị trong lần chạy của agent. Chúng được thiết lập khi phiên bắt đầu và xóa khi kết thúc, nên sẽ không rò rỉ vào môi trường shell toàn cục của bạn.

Kiểm thử

Khởi động một phiên OpenClaw mới và gọi kỹ năng:

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

Đây là sơ đồ kỹ năng đã tạo bằng Nano Banana Pro trên Replicate:

Ảnh đã được tạo, nhưng để đến được đây chúng ta phải vòng qua một bước. Phiên bản đầu tiên của SKILL.md này không có mục ## Rules, điều này cho phép agent ứng biến. Khi Nano Banana Pro trả về lỗi "service unavailable" do nhu cầu cao, agent đã tự quyết định thử google/nano-banana (biến thể không Pro) làm phương án dự phòng và tạo ảnh bằng mô hình đó.

Từ góc nhìn của agent, lựa chọn này có lý: hoàn thành tác vụ bằng bất kỳ phương tiện sẵn có nào. Từ góc nhìn của bạn, đó không phải điều bạn yêu cầu. Cách khắc phục là thêm các ràng buộc hành vi vào phần hướng dẫn:

## 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 xem hướng dẫn trong SKILL.md là chỉ dẫn thay vì giới hạn cứng, và nó sẽ tự điền vào khoảng trống bằng phán đoán của mình. Bất cứ điều gì bạn không cấm, nó có thể quyết định thử. 

Nếu một hành vi là quan trọng với bạn, dù là chọn mô hình nào, gửi đầu ra đi đâu, hay có thử lại khi lỗi hay không, hãy nêu rõ trong mục Rules.

Xuất bản và chia sẻ kỹ năng trên ClawHub

ClawHub là sổ đăng ký công khai cho các kỹ năng OpenClaw, miễn phí để duyệt và cài đặt. Xuất bản yêu cầu tài khoản GitHub ít nhất một tuần tuổi.

Thiết lập CLI

Cài đặt ClawHub CLI toàn cục:

npm i -g clawhub

Sau đó xác thực:

clawhub login

Lệnh này sẽ mở trình duyệt để xác thực với GitHub. Sau khi xác thực, bạn có thể tìm kiếm, cài đặt và xuất bản kỹ năng từ terminal.

Xuất bản kỹ năng của bạn

Để xuất bản kỹ năng tạo ảnh:

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

Tham số --slug là định danh duy nhất trên ClawHub và phải là duy nhất trên toàn bộ sổ đăng ký. Nếu ai đó đã xuất bản một kỹ năng với slug đó, lệnh sẽ thất bại với lỗi "chỉ chủ sở hữu mới có thể xuất bản bản cập nhật". Lúc đó, hãy chọn một slug khác, chẳng hạn yourname-nano-banana-pro.

Tham số --version theo phiên bản ngữ nghĩa. Mỗi lần xuất bản bản cập nhật, hãy tăng số phiên bản và tùy chọn thêm ghi chú thay đổi:

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

ClawHub lưu lịch sử phiên bản để người dùng kiểm tra thay đổi và quay lui nếu cần.

Với các thao tác hàng loạt, clawhub sync --all quét thư mục kỹ năng của bạn và xuất bản mọi kỹ năng mới hoặc đã cập nhật cùng lúc:

clawhub sync --all --bump patch

Cài đặt kỹ năng từ cộng đồng

Để cài đặt một kỹ năng do người khác xuất bản:

clawhub search "calendar"
clawhub install caldav-calendar

Theo mặc định, kỹ năng được cài vào ./skills, OpenClaw sẽ nhận diện như các kỹ năng của workspace ở phiên tiếp theo.

Lưu ý về kỹ năng bên thứ ba

Tháng 1/2026, các nhà nghiên cứu bảo mật tại Koi phát hiện 341 kỹ năng độc hại trên ClawHub trong sự kiện được biết đến với tên ClawHavoc. Kẻ tấn công dùng các tên kỹ năng đánh máy sai và các bước cài đặt "tiền đề" giả để phân phối Atomic macOS Stealer (AMOS), reverse shell và payload đánh cắp thông tin xác thực. 

Đến giữa tháng 2/2026, số lượng đã tăng lên hơn 824 kỹ năng bị gắn cờ trên hàng chục danh mục.

Trước khi cài bất kỳ kỹ năng cộng đồng nào, hãy đọc SKILL.md và các tệp hỗ trợ của nó. Cảnh giác với các bước cài đặt "tiền đề" đáng ngờ, mã bị làm rối hoặc lệnh mã hóa base64. ClawHub tự động ẩn các kỹ năng có từ ba báo cáo người dùng trở lên, nhưng kỹ năng độc hại mới có thể xuất hiện nhanh hơn tốc độ kiểm duyệt. 

Các công cụ như Clawdex có thể quét các kỹ năng đã cài của bạn đối chiếu với cơ sở dữ liệu các gói độc hại đã biết.

Hãy xử lý kỹ năng bên thứ ba với mức độ thận trọng như với bất kỳ mã của bên thứ ba nào: xem xét trước khi chạy.

Kết luận

Giữa định dạng SKILL.md, phạm vi thông tin xác thực qua openclaw.json và ClawHub CLI, bạn có đầy đủ vòng đời từ tự động hóa cục bộ đến gói chia sẻ. 

Phần lớn công việc khi xây dựng một kỹ năng OpenClaw mới là viết hướng dẫn rõ ràng trong phần thân markdown và quyết định ràng buộc nào đưa vào metadata. Phần mã thực tế, dù là script chuyển đổi hay lời gọi API, nằm trong những tệp riêng, nơi bạn có thể kiểm thử và lặp lại độc lập.

Để đi xa hơn phạm vi hướng dẫn này, các kỹ năng đi kèm trong repo OpenClaw cho thấy cách đội ngũ cốt lõi cấu trúc các quy trình phức tạp hơn. Bài tổng quan Claude Opus 4.6 phân tích sâu hơn cách lựa chọn mô hình ảnh hưởng tới hành vi của agent, và khóa học Introduction to Claude Models cung cấp thực hành trực tiếp với các mô hình đứng sau những agent như OpenClaw.