OpenClaw Coolify 스킬 가이드

OpenClaw Coolify 스킬 개요

Coolify 스킬은 REST API를 통해 OpenClaw를 Coolify 인스턴스에 연결합니다. 설치가 완료되면 OpenClaw 에이전트가 애플리케이션 배포, 데이터베이스 관리, 환경 변수 구성, 서비스 모니터링을 모두 일반 영어 명령으로 수행할 수 있습니다.

Coolify는 Vercel, Heroku, Netlify를 대체할 수 있는 오픈소스 셀프 호스팅 플랫폼입니다. 정적 사이트, 풀스택 애플리케이션, 데이터베이스 및 280개 이상의 원클릭 서비스를 자체 서버에 배포할 수 있습니다. OpenClaw Coolify 스킬을 사용하면 관리형 플랫폼의 편의성을 누리면서 인프라와 데이터에 대한 완전한 제어권을 유지할 수 있습니다.

일반적인 워크플로:

1. OpenClaw에 최신 변경 사항을 스테이징 서버에 배포해 달라고 요청합니다.
2. 에이전트가 Coolify API를 호출하여 연결된 프로젝트에서 배포를 트리거합니다.
3. 빌드 상태와 로그가 읽기 쉬운 요약 형태로 반환됩니다 — Coolify 대시보드를 열 필요가 없습니다.

Coolify 스킬 사전 요구 사항

Coolify 스킬을 설치하기 전에 다음 사항을 확인하세요:

• OpenClaw가 설치되어 실행 중 (v1.0+)
• Coolify 인스턴스가 서버에서 실행 중 — 설치 가이드
• Coolify 대시보드에서 생성한 Coolify API 토큰
• Coolify에 최소 하나의 애플리케이션 또는 서비스가 구성되어 있어야 함
• 스킬 관리를 위한 clawhub CLI 설치

설정을 확인하세요:

# OpenClaw 버전 확인
openclaw --version

# Coolify 접근 가능 여부 확인 (인스턴스 URL로 교체)
curl -s https://your-coolify-instance.com/api/v1/healthcheck

# clawhub CLI 확인
clawhub --version

Coolify 스킬 설치 방법

단일 명령으로 Coolify 스킬을 설치합니다:

npx clawhub@latest install coolify

설치를 확인하려면:

clawhub list

설치된 스킬 목록에 coolify가 표시되어야 합니다. 처음 사용할 때 Coolify API 엔드포인트와 토큰을 입력하라는 메시지가 표시됩니다.

Coolify 스킬 구성

Coolify 스킬에는 API 토큰과 인스턴스 URL이 필요합니다. Coolify 대시보드의 설정 → API 토큰에서 토큰을 생성하세요.

토큰 권한

Coolify API 토큰은 인스턴스에 대한 전체 액세스를 제공합니다. 최소 권한 원칙을 따르세요:

| 사용 사례 | 권장 사항 | |----------|----------| | 읽기 전용 모니터링 | 뷰어 역할의 팀 멤버 계정에서 토큰 생성 | | 전체 배포 | 관리자 토큰을 사용하되 확인 전에 모든 작업 검토 | | 다중 서버 | 격리를 위해 서버별 별도 토큰 생성 |

환경 설정

# Coolify 인스턴스 URL 설정
export COOLIFY_BASE_URL=https://your-coolify-instance.com

# Coolify API 토큰 설정
export COOLIFY_TOKEN=your_api_token_here

중요: 구성 파일에 토큰을 하드코딩하지 마세요. 환경 변수 또는 1Password나 Bitwarden과 같은 시크릿 관리자를 사용하세요. 보안 패치를 위해 Coolify 인스턴스를 항상 최신 버전으로 유지하세요.

연결 확인

환경 변수를 설정한 후 연결을 확인하세요:

# API 액세스 테스트
curl -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_BASE_URL/api/v1/teams"

Coolify 스킬 사용 예시

1. 애플리케이션 배포

사용자: "Coolify에 내 웹 앱의 최신 버전을 배포해 줘."

에이전트가 이름으로 애플리케이션을 식별하고, Coolify API를 통해 배포를 트리거하며, 빌드 상태를 스트리밍합니다. 배포 URL과 빌드 소요 시간이 포함된 요약이 제공됩니다.

2. 환경 변수 관리

사용자: "내 API 서비스의 스테이징 환경에 DATABASE_URL을 추가해 줘."

에이전트가 Coolify API를 호출하여 지정된 애플리케이션에 환경 변수를 생성합니다. 환경 간 변수의 조회, 업데이트, 일괄 업데이트를 요청할 수도 있습니다. 스킬은 출력에서 민감한 값을 마스킹 처리합니다.

3. 애플리케이션 로그 확인

사용자: "결제 서비스의 마지막 100줄 로그를 보여 줘."

에이전트가 Coolify API를 통해 컨테이너 로그를 가져와 읽기 쉬운 형식으로 표시합니다. 오류를 강조 표시하고 일반적인 패턴을 기반으로 수정 사항을 제안할 수도 있습니다.

4. 서비스 재시작

사용자: "프로덕션 서버의 PostgreSQL 데이터베이스를 재시작해 줘."

에이전트가 지정된 서비스에 재시작 명령을 전송합니다. OpenClaw는 프로덕션 서비스에서 재시작 또는 중지 작업을 실행하기 전에 확인을 요청합니다.

5. 리소스 사용량 확인

사용자: "스테이징 서버의 CPU와 메모리 사용량이 얼마나 돼?"

에이전트가 Coolify API에서 서버 메트릭을 조회하고 CPU, 메모리, 디스크 사용량 요약을 제공합니다. 리소스가 한계에 도달하고 있는 경우 알림을 보낼 수 있습니다.

보안 및 모범 사례

Coolify 스킬은 서버 및 애플리케이션에 대해 쓰기 작업을 수행할 수 있습니다. 안전을 위해 다음 지침을 따르세요:

• 최소 권한을 사용하세요. 최소한의 권한을 가진 전용 API 토큰을 생성하세요. 자동화 작업에 메인 관리자 토큰을 사용하지 마세요.
• 프로덕션 배포 전 검토하세요. 항상 스테이징에서 먼저 배포를 테스트하세요. OpenClaw는 프로덕션 배포 전에 확인을 요청합니다.
• Coolify를 최신 상태로 유지하세요. 최신 보안 패치를 적용하기 위해 Coolify 인스턴스를 정기적으로 업데이트하세요 — Coolify 대시보드에서 업데이트를 실행하거나 공식 업데이트 가이드를 사용하세요.
• 인스턴스를 보호하세요. Coolify를 방화벽 또는 VPN 뒤에 배치하세요. 강력한 비밀번호를 사용하고 이중 인증을 활성화하세요.
• API 토큰을 주기적으로 교체하세요. 정기적으로 토큰을 재생성하고 사용하지 않는 토큰은 대시보드에서 폐기하세요.
• 정기적으로 백업하세요. Coolify의 내장 S3 백업 기능을 사용하여 구성 및 데이터베이스 데이터를 보호하세요.

일반적인 오류 해결

"Connection refused" 또는 "ECONNREFUSED"

스킬이 Coolify 인스턴스에 연결할 수 없습니다.

1. COOLIFY_BASE_URL이 올바르고 프로토콜(https://)이 포함되어 있는지 확인하세요.
2. Coolify 인스턴스가 실행 중인지 확인하세요: 서버에서 systemctl status coolify를 실행하세요.
3. 방화벽이 Coolify 포트(기본값: 8000)의 트래픽을 허용하는지 확인하세요.
4. VPN 또는 Tailscale을 사용하는 경우 터널이 활성화되어 있는지 확인하세요.

"Unauthorized" 또는 "401 Error"

API 토큰이 유효하지 않거나 만료되었습니다.

1. Coolify 대시보드 → 설정 → API 토큰에서 토큰을 확인하세요.
2. 토큰이 폐기된 경우 재생성하세요.
3. COOLIFY_TOKEN 환경 변수가 올바르게 설정되어 있는지 확인하세요.

# 토큰 설정 확인
echo $COOLIFY_TOKEN

# 인증 테스트
curl -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "$COOLIFY_BASE_URL/api/v1/teams"

"Application not found"

스킬이 참조한 애플리케이션을 찾을 수 없습니다.

1. 모든 애플리케이션 목록 확인: OpenClaw에 "내 Coolify 애플리케이션 목록을 보여 줘"라고 요청하세요.
2. 애플리케이션 이름 또는 UUID가 Coolify 대시보드의 것과 일치하는지 확인하세요.
3. API 토큰이 해당 애플리케이션을 소유한 팀에 대한 액세스 권한이 있는지 확인하세요.