소개
나만의 OpenClaw Skill을 개발하는 것은 재미있고 가치 있는 일입니다. 이 튜토리얼에서는 처음부터 날씨 조회 Skill을 완성하며, 이 실전 프로젝트를 통해 Skill 개발의 핵심 개념과 전체 과정을 익히게 됩니다.
Skill 기본 개념
OpenClaw의 Skill은 본질적으로 SKILL.md 파일로, 자연어를 사용하여 AI 어시스턴트가 특정 시나리오에서 어떻게 동작해야 하는지를 정의합니다. Skill 파일은 ~/.openclaw/skills/ 디렉토리에 저장됩니다.
Skill은 주로 다음 요소로 구성됩니다:
| 요소 | 설명 | 필수 여부 |
|---|---|---|
| 이름과 설명 | Skill의 식별 정보 | 예 |
| 트리거 조건 | 어떤 상황에서 이 Skill을 활성화할지 | 예 |
| 동작 정의 | 활성화 후 어떻게 실행할지 | 예 |
| 출력 형식 | 응답의 형식과 스타일 | 권장 |
| MCP 도구 | 호출해야 할 외부 도구 | 필요 시 |
SKILL.md 파일 구조
표준 SKILL.md 파일 구조는 다음과 같습니다:
---
name: skill-name
version: 1.0.0
description: Brief description of the skill
triggers:
- keyword1
- keyword2
mcp_tools:
- tool_name
---
# Skill Title
## Description
Detailed description of what this skill does.
## Behavior
Instructions for how the AI should behave when this skill is activated.
## Output Format
How the response should be formatted.
1단계: 날씨 Skill 기획
코드를 작성하기 전에 먼저 스킬의 기능을 기획합니다:
- 기능: 지정 도시의 날씨 정보 조회 (현재 날씨 + 일기 예보)
- 트리거 키워드: 天气, weather, 气温, 温度, 下雨
- 데이터 소스: MCP 도구를 통해 OpenWeatherMap API 호출
- 출력: 포맷된 날씨 정보 카드
2단계: MCP 날씨 도구 준비
날씨 API를 사용하기 전에 OpenClaw 설정에서 MCP 도구를 설정해야 합니다. ~/.config/openclaw/openclaw.json5를 편집합니다:
{
mcp: {
servers: {
"weather-api": {
// HTTP 타입의 MCP 서비스 사용
command: "npx",
args: ["-y", "@openclaw-mcp/http-fetch"],
env: {
// OpenWeatherMap API 키
OPENWEATHER_API_KEY: "your-api-key-here"
}
}
}
}
}
OpenWeatherMap API 키가 아직 없다면 https://openweathermap.org/api 에서 무료로 등록하여 발급받으십시오.
3단계: SKILL.md 작성
~/.openclaw/skills/ 디렉토리에 weather.SKILL.md 파일을 생성합니다:
---
name: weather
version: 1.0.0
description: 查询全球城市天气信息，支持当前天气和未来预报
triggers:
- 天气
- weather
- 气温
- 温度
- 下雨
- 下雪
- 预报
- forecast
mcp_tools:
- http_fetch
---
# 天气查询技能
## Description
这是一个天气查询技能，当用户询问任何与天气相关的问题时激活。
支持查询全球任意城市的当前天气和未来天气预报。
## Behavior
当用户询问天气信息时，按以下步骤执行：
1. **提取城市名称**：从用户消息中识别出目标城市。如果用户没有指定城市，
询问用户想查询哪个城市的天气。
2. **调用天气 API**：使用 http_fetch 工具调用 OpenWeatherMap API：
- 当前天气：`https://api.openweathermap.org/data/2.5/weather?q={city}&appid={OPENWEATHER_API_KEY}&units=metric&lang=zh_cn`
- 未来预报：`https://api.openweathermap.org/data/2.5/forecast?q={city}&appid={OPENWEATHER_API_KEY}&units=metric&lang=zh_cn&cnt=24`
3. **解析数据**：从 API 返回的 JSON 中提取关键信息。
4. **格式化输出**：按照下方输出格式模板返回结果。
## Data Parsing
从 API 响应中提取以下字段：
- `main.temp` - 当前温度（摄氏度）
- `main.feels_like` - 体感温度
- `main.humidity` - 湿度百分比
- `weather[0].description` - 天气描述
- `wind.speed` - 风速（m/s）
- `main.temp_min` - 最低温度
- `main.temp_max` - 最高温度
- `sys.sunrise` - 日出时间（Unix时间戳，转换为当地时间）
- `sys.sunset` - 日落时间
## Output Format
使用以下格式回复用户：
### 当前天气查询
🌤️ {城市名} 天气
📍 当前天气：{天气描述} 🌡️ 温度：{当前温度}°C（体感 {体感温度}°C） 📊 温度范围：{最低温}°C ~ {最高温}°C 💧 湿度：{湿度}% 💨 风速：{风速} m/s 🌅 日出：{日出时间} 🌇 日落：{日落时间}
### 未来预报查询
📅 {城市名} 未来天气预报
| 时间 | 天气 | 温度 | 湿度 |
|---|---|---|---|
| {时间1} | {天气1} | {温度1}°C | {湿度1}% |
| {时间2} | {天气2} | {温度2}°C | {湿度2}% |
| ... |
## Additional Instructions
- 如果城市名称不明确（如"长安"可能指西安），列出可能的选项让用户选择
- 如果 API 返回错误或城市不存在，友好地告知用户并建议检查城市名称
- 温度使用摄氏度，风速使用 m/s
- 根据天气情况给出简短的生活建议（如带伞、防晒、添衣等）
- 时间显示使用 24 小时制
4단계: Skill 테스트
방법 1: 로컬 테스트
OpenClaw를 재시작하고 테스트합니다:
# 재시작하여 새 스킬 로드
openclaw restart
# 스킬 로드 확인
openclaw skill list
그런 다음 연결된 아무 채팅 채널에서 메시지를 보내 테스트합니다:
北京今天天气怎么样？
방법 2: 디버그 모드 사용
OpenClaw는 스킬 개발을 돕는 디버그 모드를 제공합니다:
# 상세 로그 활성화
openclaw logs --level debug
디버그 로그에서 스킬의 트리거 및 실행 과정을 확인할 수 있습니다:
[DEBUG] Message received: "北京今天天气怎么样？"
[DEBUG] Skill matching: checking triggers...
[DEBUG] Skill 'weather' matched by trigger: "天气"
[DEBUG] Activating skill: weather
[DEBUG] MCP tool call: http_fetch -> openweathermap API
[DEBUG] API response: 200 OK
[DEBUG] Skill 'weather' execution complete
방법 3: Gateway를 통한 직접 테스트
채팅 채널을 거치지 않고 Gateway API를 직접 호출합니다:
curl -X POST http://localhost:18789/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "上海明天会下雨吗？",
"context": []
}'
5단계: 출력 최적화
생활 조언 로직 추가
SKILL.md의 Behavior 부분에 날씨 조언 규칙을 추가합니다:
## Weather Advice Rules
根据天气数据给出对应建议：
- 温度 > 35°C：提醒防暑降温，多饮水
- 温度 < 0°C：提醒注意保暖，路面可能结冰
- 湿度 > 80%：可能会感觉闷热
- 天气描述包含"雨"：建议携带雨具
- 天气描述包含"雪"：注意出行安全
- 风速 > 10 m/s：注意防风
- UV 指数 > 6：建议涂防晒霜
퍼지 검색 지원
트리거 조건에 더 많은 자연어 패턴을 추가합니다:
triggers:
- 天气
- 要不要带伞
- 穿什么衣服
- 会不会下雨
- 冷不冷
- 热不热
6단계: 다국어 지원 추가
사용자의 언어에 따라 자동으로 출력을 전환하도록 합니다:
SKILL.md에 다음을 추가합니다:
## Multilingual Support
- 检测用户消息的语言
- 如果用户使用中文提问，用中文回复
- 如果用户使用英文提问，用英文回复
- API 调用时使用对应的 `lang` 参数：
- 中文：`lang=zh_cn`
- 英文：`lang=en`
- 日文：`lang=ja`
완성 후 파일 목록
개발 완료 후 프로젝트 구조는 다음과 같아야 합니다:
~/.openclaw/skills/
└── weather.SKILL.md # 스킬 정의 파일
~/.config/openclaw/
└── openclaw.json5 # MCP 날씨 도구 설정 포함
ClawHub에 게시
이 스킬에 만족한다면 ClawHub 스킬 마켓플레이스에 게시할 수 있습니다:
# 게시 디렉토리 생성
mkdir ~/weather-skill && cd ~/weather-skill
# 스킬 파일 복사
cp ~/.openclaw/skills/weather.SKILL.md ./SKILL.md
# 메타데이터 생성
cat > clawhub.json << 'EOF'
{
"name": "weather-forecast-cn",
"version": "1.0.0",
"description": "中英文天气查询技能，支持全球城市",
"author": "your-username",
"license": "MIT",
"keywords": ["weather", "forecast", "天气"],
"category": "信息查询"
}
EOF
# 검증 및 게시
npx clawhub@latest validate
npx clawhub@latest publish
자주 묻는 질문
API 호출 실패
API 키가 올바르게 설정되었는지 확인합니다:
# API 키 테스트
curl "https://api.openweathermap.org/data/2.5/weather?q=Beijing&appid=YOUR_KEY"
스킬이 트리거되지 않는 경우
- 트리거 키워드 목록에 사용자 메시지에 포함된 키워드가 있는지 확인합니다
- 다른 스킬의 트리거 키워드와 충돌이 없는지 확인합니다
- 디버그 로그를 확인하여 매칭 상세 정보를 파악합니다
출력 형식이 이상적이지 않은 경우
SKILL.md의 출력 형식은 AI에 대한 지시이지 템플릿이 아니므로, AI가 의미를 이해하지만 정확히 따르지 않을 수 있습니다. 형식 설명을 더 구체적으로 하거나 예시 출력을 추가할 수 있습니다.
마무리
이 튜토리얼을 통해 완전한 날씨 조회 Skill 개발을 완료하셨습니다. 핵심 포인트는 SKILL.md의 구조적 작성, MCP 도구의 설정 및 호출, 트리거 조건 설계, 그리고 출력 형식 최적화입니다. 이러한 지식은 다른 모든 유형의 Skill 개발에도 활용할 수 있습니다.