name: kma-weather
description: 从韩国气象厅获取天气信息。提供当前天气状况、预报（3-10天）以及天气警报/预警。当用户需要韩国天气数据、天气预警或精确的本地预报（5公里网格）时使用。需要 KMA_SERVICE_KEY。
metadata:
openclaw:
emoji: "🌦️"
homepage: "https://www.data.go.kr/data/15084084/openapi.do"
requires:
bins: ["python3"]
env: ["KMA_SERVICE_KEY"]
primaryEnv: "KMA_SERVICE_KEY"

kma-weather

快速开始

# 当前天气 + 6小时预报
python3 skills/kma-weather/scripts/forecast.py brief --lat 37.5665 --lon 126.9780

# 所有预报的 JSON 格式输出（当前 + 超短期 + 短期）
python3 skills/kma-weather/scripts/forecast.py all --lat 37.5665 --lon 126.9780 --json

# 短期预报（3天）
python3 skills/kma-weather/scripts/forecast.py shortterm --lat 37.5665 --lon 126.9780 --days all

# 全国天气警报/预警
python3 skills/kma-weather/scripts/weather_warnings.py

# 中期预报（3-10天）
python3 skills/kma-weather/scripts/midterm.py --region 서울

设置

1. 获取 API 密钥

1. 访问 공공데이터포털
2. 申请以下 3 个 API 的访问权限（它们使用同一个密钥）：
   • 기상청 단기예보 조회서비스 (15084084)
   • 기상청 기상특보 조회서비스 (15000415)
   • 기상청 중기예보 조회서비스 (15059468)
3. 从“我的页面” → “API密钥管理”复制你的 ServiceKey

2. 设置环境变量

在 ~/.openclaw/openclaw.json 文件中配置：

沙盒环境（添加到 agents.defaults.sandbox.docker.env）：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "env": {
            "KMA_SERVICE_KEY": "你的密钥"
          }
        }
      }
    }
  }
}

主机环境（添加到 env.vars）：

{
  "env": {
    "vars": {
      "KMA_SERVICE_KEY": "你的密钥"
    }
  }
}

使用说明

forecast.py

选项：
- --lat, --lon：坐标（必需）
- --days：针对短期预报 - 1（明天，默认）、2、3 或 all
- --json：输出原始 JSON 数据

输出示例 (current)：

🌤️ 현재 날씨 (초단기실황)
🌡️  기온: 5.2°C
💧 습도: 65%
🌧️  강수량: 0mm (1시간)
💨 풍속: 2.3m/s
🧭 풍향: NW (315°)

weather_warnings.py

返回当前全国范围的天气预警：

🚨 기상특보 현황
발표시각: 2026-02-01 10:00
발효시각: 2026-02-01 10:00

📍 현재 발효 중인 특보
  • 건조경보 : 강원도, 경상북도, ...
  • 풍랑주의보 : 동해중부안쪽먼바다, ...

⚠️  예비특보
  • (1) 강풍 예비특보 : 02월 02일 새벽(00시~06시) : 울릉도.독도

midterm.py

按地区提供 3-10 天预报。

python3 skills/kma-weather/scripts/midterm.py --region 서울
python3 skills/kma-weather/scripts/midterm.py --stn-id 109

支持地区：서울, 인천, 경기, 부산, 대구, 광주, 대전, 울산, 세종, 강원, 충북, 충남, 전북, 전남, 경북, 경남, 제주

grid_converter.py

将经纬度坐标转换为 KMA 5公里网格坐标（其他脚本会自动处理）：

python3 skills/kma-weather/scripts/grid_converter.py 37.5665 126.9780
# 输出: Grid: (60, 127)

API 说明

• 数据发布时间表：
  • 当前天气：每小时第 40 分钟（基准时间：HH00）
  • 超短期预报：每小时第 45 分钟（基准时间：HH30）
  • 短期预报：02:10, 05:10, 08:10, 11:10, 14:10, 17:10, 20:10, 23:10 (KST)
  • 中期预报：06:00, 18:00 (KST)
• 覆盖范围：仅限韩国
• 自动分页：脚本会自动获取所有分页数据

与 weather skill 对比

建议搭配使用：weather 用于全球天气，kma-weather 用于详细的韩国预报和天气预警。

故障排除

参考文档（原始 API 文档）

• references/api-forecast.md - 短期预报 API 端点、参数、响应格式
• references/api-warnings.md - 天气预警 API 端点、参数、响应格式
• references/api-midterm.md - 中期预报 API 端点、参数、响应格式
• references/category-codes.md - KMA 类别代码（SKY, PTY 等）
• implement-status.md - 实现状态