MIJ Kakao Local API (PowerShell)

PowerShell skill for calling Kakao Local API to normalize addresses and search places with keyword, location, radius, and category filters.

Security Scan

The skill appears to implement a straightforward Kakao Local PowerShell client, but the package metadata omits the fact that it requires a Kakao REST API key (and the runtime reads/writes files in the skill data folder), which is an incoherence you should understand before installing.

Purpose & Capability

The SKILL.md and included PowerShell script implement Kakao Local address normalization and place search and legitimately require a Kakao REST API key and access to a local data directory. However the registry metadata claims no required environment variables or primary credential — that is inconsistent with the actual runtime behavior (the script explicitly reads KAKAO_REST_API_KEY from User/Process env or a config.json).

Instruction Scope

The instructions and script stay within the stated purpose: they call only Kakao API endpoints, use curl.exe, parse responses, and read/write files under the skill's data directory (places.json, cache.json, data/config.json). The script reads environment variables (User, Process, and process env) and reads/writes files under skills/kakao-local/data; these actions are expected for a local client but should be noted (it does not attempt to read system-wide secrets or other unrelated paths).

Install Mechanism

This is an instruction-only skill with no install spec and no external downloads. No code is installed by an automated installer beyond running the included PowerShell script, which is lower risk in the installer dimension.

Credentials

The script requires a Kakao REST API key (KAKAO_REST_API_KEY) via environment variable or config.json, which is proportional to the functionality. The concern is that the skill registry metadata did not declare this required env var or primary credential, creating an information mismatch that could lead users to overlook storing/protecting the key appropriately.

Persistence & Privilege

The skill does not request elevated platform privileges, does not set always:true, and only writes to its own skill data directory. Persisting data (places.json, cache.json, config.json) in the skill folder is normal for this type of skill.

What to consider before installing

This skill implements a Kakao Local API client in PowerShell and requires a Kakao REST API key, but the package metadata omits that requirement — treat that as a red flag. Before installing: (1) verify you obtain and store a Kakao REST API key with appropriate scope and rotate/revoke it if compromised; (2) prefer setting the key as a User-scoped environment variable rather than committing a config.json into source control (the SKILL.md also warns to add config.json to .gitignore); (3) review and control files under skills/kakao-local/data (places.json, cache.json) because they may contain saved locations or query history; (4) run the script in a constrained/test environment (or with a limited account) first to confirm behavior; and (5) ask the publisher to update registry metadata to declare KAKAO_REST_API_KEY as a required credential so automated gating and audits can catch it.

Kakao Local API Skill

OpenClaw Skill for Kakao Local (Places & Address) API

개요

카카오 로컬 API를 호출하여 주소 정규화 및 장소 검색을 수행하는 OpenClaw Skill입니다.

요구사항

• Windows
• PowerShell 5.0+
• curl.exe (Windows 10+ 기본 포함)
• Kakao Developers REST API Key

API Key 설정

중요: API Key는 스킬 파라미터로 전달하지 않습니다 (로그 노출 방지).

방법 1: 환경변수 (권장)

# 사용자 환경변수로 영구 설정
[Environment]::SetEnvironmentVariable("KAKAO_REST_API_KEY", "your_rest_api_key_here", "User")

# 또는 현재 세션에만 임시 설정
$env:KAKAO_REST_API_KEY = "your_rest_api_key_here"

방법 2: Config 파일

skills/kakao-local/data/config.json (create this file) 생성:

{
  "api_key": "your_rest_api_key_here"
}

⚠️ 주의: config.json은 .gitignore에 추가하여 커밋 금지

API Key 발급

1. Kakao Developers 접속
2. 내 애플리케이션 → 앱 추가
3. 앱 키 → REST API 키 복사

스킬 함수

1. NormalizeAddress (주소 정규화)

사용자가 입력한 주소를 정규화하여 도로명/지번 주소와 좌표로 변환합니다.

API 엔드포인트: GET https://dapi.kakao.com/v2/local/search/address.json

입력 파라미터:

• -Action "NormalizeAddress" (필수)
• -Query "주소 문자열" (필수)
• -Size 3 (선택, 기본값: 3)

출력 형식:

{
  "ok": true,
  "action": "NormalizeAddress",
  "query": "서울 강남구 테헤란로 152",
  "count": 2,
  "candidates": [
    {
      "roadAddress": "서울 강남구 테헤란로 152",
      "jibunAddress": "서울 강남구 역삼동 737",
      "x": "127.036557561809",
      "y": "37.4985995780801",
      "region": {
        "region1": "서울",
        "region2": "강남구",
        "region3": "역삼동"
      },
      "buildingName": "강남파이낸스센터",
      "zoneNo": "06236"
    }
  ],
  "raw": {}
}

사용 예시:

.\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "판교역로 235"
.\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "서울 강남구" -Size 5

2. SearchPlace (키워드 장소 검색)

키워드로 장소를 검색합니다. 위치 기반 반경 검색과 카테고리 필터링을 지원합니다.

API 엔드포인트: GET https://dapi.kakao.com/v2/local/search/keyword.json

입력 파라미터:

• -Action "SearchPlace" (필수)
• -Query "검색 키워드" (필수)
• -Size 5 (선택, 기본값: 5, 최대: 15)
• -Page 1 (선택, 기본값: 1, 최대: 45)
• -X "127.027" (선택, 중심 경도)
• -Y "37.498" (선택, 중심 위도)
• -Radius 1000 (선택, 검색 반경(m), 최대: 20000)
• -CategoryGroupCode "CE7" (선택, 카테고리 그룹 코드)

카테고리 그룹 코드:

• MT1: 대형마트
• CS2: 편의점
• PS3: 어린이집, 유치원
• SC4: 학교
• AC5: 학원
• PK6: 주차장
• OL7: 주유소, 충전소
• SW8: 지하철역
• BK9: 은행
• CT1: 문화시설
• AG2: 중개업소
• PO3: 공공기관
• AT4: 관광명소
• AD5: 숙박
• FD6: 음식점
• CE7: 카페
• HP8: 병원
• PM9: 약국

출력 형식:

{
  "ok": true,
  "action": "SearchPlace",
  "query": "대형카페",
  "count": 5,
  "totalCount": 128,
  "isEnd": false,
  "items": [
    {
      "id": "8739036",
      "name": "스타벅스 강남점",
      "roadAddress": "서울 강남구 테헤란로 152",
      "jibunAddress": "서울 강남구 역삼동 737",
      "x": "127.036557561809",
      "y": "37.4985995780801",
      "phone": "02-1234-5678",
      "categoryName": "음식점 > 카페",
      "placeUrl": "http://place.map.kakao.com/8739036",
      "distance": "245"
    }
  ],
  "raw": {}
}

사용 예시:

# 기본 검색
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "대형카페"

# 개수 지정
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "브런치 맛집" -Size 10

# 위치 기반 반경 검색
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페" -X "127.027" -Y "37.498" -Radius 1000

# 카테고리 필터링
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페" -CategoryGroupCode "CE7" -Size 15

# 페이지네이션
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "주차 가능한 카페" -Page 2 -Size 10

에러 처리

API Key 없음

{
  "ok": false,
  "errorType": "MissingApiKey",
  "message": "Set KAKAO_REST_API_KEY env var or create config.json",
  "setupGuide": "https://developers.kakao.com/"
}

API Key 잘못됨 (401/403)

{
  "ok": false,
  "errorType": "InvalidApiKey",
  "message": "Invalid or expired API key",
  "statusCode": 401
}

API 호출 실패

{
  "ok": false,
  "errorType": "ApiError",
  "message": "Failed to call Kakao API",
  "details": "..."
}

결과 없음

{
  "ok": true,
  "action": "SearchPlace",
  "query": "존재하지않는장소12345",
  "count": 0,
  "items": []
}

통합 예시 (상위 에이전트/챗봇)

# 주소 정규화 후 즐겨찾기 저장
$result = .\skills\kakao-local\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "홍대입구역"
$data = $result | ConvertFrom-Json

if ($data.ok -and $data.count -gt 0) {
    $best = $data.candidates[0]

    # 즐겨찾기에 추가
    $places = Get-Content ".\skills\kakao-local\data\places.json" -Raw | ConvertFrom-Json
    $places | Add-Member -NotePropertyName "홍대" -NotePropertyValue @{
        roadAddress = $best.roadAddress
        x = $best.x
        y = $best.y
        savedAt = (Get-Date -Format "yyyy-MM-dd HH:mm:ss")
    } -Force
    $places | ConvertTo-Json -Depth 10 | Out-File ".\skills\kakao-local\data\places.json" -Encoding UTF8

    Write-Host "✅ 즐겨찾기 저장: 홍대 → $($best.roadAddress)"
}

# 장소 검색 후 상위 3개 추천
$result = .\skills\kakao-local\scripts\kakao_local.ps1 -Action SearchPlace -Query "주차 가능한 카페" -Size 10
$data = $result | ConvertFrom-Json

if ($data.ok -and $data.count -gt 0) {
    Write-Host "`n🌟 추천 장소 TOP 3:"
    $top3 = $data.items | Select-Object -First 3
    $index = 1
    foreach ($place in $top3) {
        Write-Host "`n[$index] $($place.name)"
        Write-Host "    📍 $($place.roadAddress)"
        Write-Host "    📞 $($place.phone)"
        Write-Host "    🔗 $($place.placeUrl)"
        $index++
    }

    # 캐시에 저장 (중복 검색 방지)
    $cache = @{
        query = $data.query
        timestamp = (Get-Date -Format "yyyy-MM-dd HH:mm:ss")
        ttl = 3600  # 1시간
        results = $data.items
    }
    $cache | ConvertTo-Json -Depth 10 | Out-File ".\skills\kakao-local\data\cache.json" -Encoding UTF8
}

테스트 시나리오

1. 주소 정규화 테스트

.\scripts\kakao_local.ps1 -Action NormalizeAddress -Query "서울 강남구 테헤란로 152"
# 기대: 도로명/지번 주소와 좌표 출력

2. 장소 검색 테스트

.\scripts\kakao_local.ps1 -Action SearchPlace -Query "대형카페" -Size 5
# 기대: 5개 카페 목록 출력

3. API Key 미설정 테스트

# 환경변수 임시 제거
$backup = $env:KAKAO_REST_API_KEY
$env:KAKAO_REST_API_KEY = $null

.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페"
# 기대: {"ok": false, "errorType": "MissingApiKey", ...}

# 복구
$env:KAKAO_REST_API_KEY = $backup

4. 잘못된 API Key 테스트

$env:KAKAO_REST_API_KEY = "invalid_key_12345"
.\scripts\kakao_local.ps1 -Action SearchPlace -Query "카페"
# 기대: {"ok": false, "errorType": "InvalidApiKey", ...}

파일 구조

skills/kakao-local/
  ├── SKILL.md                    # 이 파일 (스킬 명세)
  ├── README.md                   # Quick Start
  ├── .gitignore                  # config.json 보호
  ├── scripts/
  │   └── kakao_local.ps1         # 메인 스킬 스크립트
  └── data/
      ├── config.json.template    # API Key 설정 템플릿
      ├── places.json             # 즐겨찾기 (선택)
      └── cache.json              # 검색 캐시 (선택)

라이선스

MIT License

---

Publish-safe packaging note

This registry upload is "text-only" compatible: script sources are embedded under references/ as Markdown.

To use the skill locally:

1. Copy references/kakao_local.ps1.md content into a file: scripts/kakao_local.ps1
2. Copy references/config.json.template.md content into: data/config.json.template
3. Set API key via env var KAKAO_REST_API_KEY (recommended) or create data/config.json (gitignored).