내 PC/서버에 직접 설치해 텔레그램·디스코드로 제어하는 셀프호스팅 AI 에이전트 플랫폼입니다.
외부 서버 없이 로컬 환경에서 Claude, GPT 등 LLM을 연결해 나만의 AI 직원을 구성할 수 있습니다.
공식으로 준비된 기능만으로는 해결되지 않는 순간이 반드시 옵니다. 회사 내부 API를 호출해야 하거나, 개인 서버에서만 접근 가능한 데이터를 다뤄야 하거나, 딱 우리 팀에 맞는 자동화가 필요할 때가 그렇죠. 이때 필요한 것이 바로 openclaw 커스텀 툴입니다.
이번 19편에서는 openclaw 커스텀 툴을 실제로 만드는 과정을 처음부터 끝까지 정리합니다. Python 스크립트 1개와 SKILL.md 1개만 있으면, 기존 스크립트를 AI 에이전트가 직접 실행하는 도구로 바꿀 수 있습니다.
지난 편(18편: Tools & Plugins 전체 가이드 — AI가 쓸 수 있는 도구 추가하기)에서는 기본 도구 체계를 이해했다면, 오늘은 그 위에 내 업무에 맞는 기능을 직접 얹는 실전 단계로 들어갑니다.
커스텀 툴 구조 이해 — 스크립트와 메타데이터를 함께 설계하기
커스텀 툴은 거대한 프레임워크가 아닙니다. 핵심은 단순합니다. 실제 동작을 수행하는 Python 스크립트와, AI에게 사용 지침을 알려주는 SKILL.md를 한 폴더에 넣으면 됩니다. 즉, 도구의 몸체는 코드이고, 도구의 설명서는 메타데이터입니다.
OpenClaw는 스킬을 우선순위에 따라 로드합니다. 워크스페이스 스킬, 유저 스킬, 빌트인 스킬 순으로 확인하기 때문에 ~/.openclaw/workspace/skills/에 넣은 커스텀 툴은 내 프로젝트 상황에 맞게 빠르게 반영됩니다. 이 구조를 이해하면 공용 기능과 사내 전용 기능을 충돌 없이 병행할 수 있습니다.
커스텀 툴이 실제로 호출되는 흐름
사용자가 자연어로 요청하면 AI는 먼저 요청 의도를 해석하고, 해당 작업에 맞는 스킬을 선택한 뒤 SKILL.md에 적힌 실행 규칙을 참고해 명령을 호출합니다. 결과가 반환되면 그 내용을 다시 사람 친화적인 답변으로 정리해 사용자에게 전달합니다.
# 커스텀 툴 폴더 생성
mkdir -p ~/.openclaw/workspace/skills/crypto-price
cd ~/.openclaw/workspace/skills/crypto-price
name 필드를 일치시키면 관리가 쉬워집니다. 팀 단위 운영 시에는 접두어(예: corp-, team-)를 붙여 충돌을 줄이세요. 📎 공식 문서 원문 보기 →
Python 스크립트 작성 — 코인 가격 조회 예제로 시작하기
첫 실습 예제로, 특정 코인의 현재 USD 가격을 조회하는 간단한 스크립트를 만들어 보겠습니다. 핵심은 화려한 기능보다 “입력값을 받고, 외부 API를 호출하고, 결과를 읽기 쉬운 텍스트로 출력하는 패턴”을 익히는 것입니다. 이 패턴만 익히면 사내 API, DB 조회, 로그 요약 같은 업무형 도구로 바로 확장할 수 있습니다.
예제 스크립트: get_price.py
아래 코드는 urllib만 사용하므로 별도 라이브러리 설치 없이 바로 테스트할 수 있습니다. 장애 대응을 위해 예외 처리도 함께 포함해 두는 것이 좋습니다.
import sys
import json
import urllib.request
def get_crypto_price(coin_id):
url = f"https://api.coingecko.com/api/v3/simple/price?ids={coin_id}&vs_currencies=usd"
try:
req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
with urllib.request.urlopen(req) as response:
data = json.loads(response.read().decode())
if coin_id in data:
print(f"The current price of {coin_id} is ${data[coin_id]['usd']}")
else:
print(f"Error: Coin '{coin_id}' not found.")
except Exception as e:
print(f"Error fetching price: {str(e)}")
if __name__ == "__main__":
if len(sys.argv) > 1:
get_crypto_price(sys.argv[1].lower())
else:
print("Usage: python get_price.py ")
- 입력 파라미터 표준화:
lower()로 소문자 정규화해 사용자 입력 편차를 줄입니다. - 오류 메시지 명확화: 네트워크 실패와 코인 미존재 케이스를 구분하면 디버깅이 쉬워집니다.
- 출력 형식 고정: 에이전트가 후처리하기 쉬운 문장 구조를 유지하세요.
등록과 적용 — SKILL.md 작성부터 게이트웨이 재시작까지
스크립트만 만들어서는 AI가 도구를 이해하지 못합니다. 어떤 상황에서 어떤 명령을 실행해야 하는지 SKILL.md로 설명해야 실제 호출이 가능합니다. 아래 순서대로 진행하면 약 10분 안에 커스텀 툴 테스트까지 완료할 수 있습니다.
- SKILL.md 생성동일 폴더에 메타데이터를 작성합니다.
name,description,bins를 명확히 기입하세요. cat << 'EOF' > SKILL.md --- name: crypto-price description: Fetch the current USD price of a specific cryptocurrency using its coin ID. version: 1.0.0 bins: - python3 --- ### How to use When the user asks for the price of a cryptocurrency, use the exec tool: python3 ~/.openclaw/workspace/skills/crypto-price/get_price.py <coin_id> EOF- 실행 권한/도구 권한 확인
openclaw.json에서tools.exec.enabled가true인지 확인합니다. 운영 환경에서는approval: true도 함께 권장됩니다. chmod +x ~/.openclaw/workspace/skills/crypto-price/get_price.py- 게이트웨이 재시작새 스킬을 로드하려면 게이트웨이를 재시작합니다. 반영 후 채팅 채널에서 실제 질의로 동작 여부를 확인하세요.
openclaw gateway restart- 실사용 테스트“비트코인 가격 확인해줘”처럼 자연어로 요청해 AI가 스크립트를 호출하는지 확인합니다. 실패 시 로그와 권한 설정을 먼저 점검합니다.
운영 안정화 — 권한, 의존성, 보안 체크
커스텀 툴이 한 번 성공했다고 끝이 아닙니다. 장기 운영에서는 권한 범위, 라이브러리 의존성, 비밀정보 관리가 품질을 좌우합니다. 특히 사내 API나 민감한 업무 자동화를 연결할 때는 안전장치를 먼저 세팅해야 사고를 예방할 수 있습니다.
실무에서 먼저 적용할 운영 원칙
API 키는 코드에 하드코딩하지 말고 환경 변수로 분리하고, 필수 라이브러리는 가상환경 기준으로 명시하세요. 또한 실패 재시도 횟수, 타임아웃, 로그 레벨을 초기에 정의하면 장애 복구 시간이 크게 줄어듭니다.
exec 권한을 광범위하게 열어두면 예상치 못한 명령 실행 위험이 커집니다. 운영 서버에서는 승인 정책과 실행 가능한 명령 범위를 반드시 제한하세요.# ~/.openclaw/openclaw.json (개념 예시)
tools:
exec:
enabled: true
approval: true
skills:
autoLoad:
enabled: true
includeWorkspace: true
security:
envAllowlist:
- COINGECKO_API_KEY
- INTERNAL_API_TOKEN
실전 팁과 주의사항
- 작게 시작하고 빠르게 검증: 처음부터 대형 API를 붙이지 말고 입력/출력만 있는 최소 스크립트로 호출 경로를 먼저 확인하세요.
- 의존성은 명시적으로 관리: 라이브러리 버전을 고정하지 않으면 서버별 동작 차이가 생길 수 있습니다. 가상환경 기준으로 관리하세요.
- 민감 정보는 환경 변수 분리: API 키·토큰을 코드나 SKILL.md에 직접 쓰지 말고 안전한 주입 방식으로 운영하세요.
- 권한은 최소 범위 원칙:
exec는 강력한 도구이므로 승인(approval)과 로그 추적을 반드시 켜고 운영하세요.
자주 묻는 질문 (FAQ)
- Python을 잘 몰라도 커스텀 툴을 만들 수 있나요?
- 네, 가능합니다. 입력을 받아 결과를 출력하는 기초 스크립트만 작성해도 충분히 시작할 수 있고, 이후 점진적으로 기능을 확장하면 됩니다.
- 스크립트가 실행되지 않고 권한 오류가 발생합니다. 무엇부터 확인하나요?
- 먼저 파일 실행 권한(
chmod +x)과tools.exec.enabled설정을 확인하세요. 두 항목이 누락되면 호출 자체가 차단됩니다. - requests 같은 외부 라이브러리를 써도 되나요?
- 가능합니다. 다만 실행 환경에 동일한 라이브러리가 설치되어 있어야 하며, 운영 안정성을 위해 버전 고정과 가상환경 사용을 권장합니다.
- 사내 API 연동 시 가장 중요한 보안 포인트는 무엇인가요?
- 토큰 하드코딩 금지와 최소 권한 원칙입니다. 키는 환경 변수로 분리하고, 호출 가능한 명령 범위를 제한해 위험을 줄이세요.
이 글이 도움이 됐다면 댓글로 여러분의 실전 사례를 공유해 주세요! 🙌
openclaw 커스텀 툴 구성에서 막히는 부분은 댓글에 남겨주시면 단계별로 정리해 드리겠습니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
댓글