OpenClaw Vercel 스킬 가이드

OpenClaw Vercel 스킬 개요

Vercel 스킬은 공식 Vercel CLI를 통해 OpenClaw를 Vercel 플랫폼에 연결합니다. 설치가 완료되면 OpenClaw 에이전트가 애플리케이션 배포, 환경 변수 관리, 도메인 구성, 빌드 로그 검사를 모두 일반 영어 명령으로 수행할 수 있습니다.

Vercel은 Next.js, React, Svelte 및 기타 최신 프레임워크로 구축된 수백만 개의 웹사이트를 지원하는 선도적인 프론트엔드 클라우드 플랫폼입니다. OpenClaw Vercel 스킬을 사용하면 에디터, 터미널, Vercel 대시보드 간의 컨텍스트 전환을 없앨 수 있습니다. 필요한 것을 설명하기만 하면 OpenClaw가 나머지를 처리합니다.

일반적인 워크플로:

1. OpenClaw에 현재 프로젝트를 Vercel에 배포해 달라고 요청합니다.
2. 에이전트가 내부적으로 vercel deploy를 실행하여 프로젝트 연결 및 빌드 구성을 처리합니다.
3. 프리뷰 URL이 즉시 반환됩니다 — 대시보드를 열 필요가 없습니다.

Vercel 스킬 사전 요구 사항

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

• OpenClaw가 설치되어 실행 중 (v1.0+)
• Vercel CLI 설치 — 공식 설치 가이드
• Vercel 계정 (무료 플랜 사용 가능) 및 최소 하나의 프로젝트
• Node.js 18+ (Vercel CLI에 필요)
• 스킬 관리를 위한 clawhub CLI 설치

설정을 확인하세요:

# OpenClaw 버전 확인
openclaw --version

# Vercel CLI 버전 확인
vercel --version

# Vercel 인증 확인
vercel whoami

Vercel 스킬 설치 방법

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

npx clawhub@latest install vercel

설치를 확인하려면:

clawhub list

설치된 스킬 목록에 vercel이 표시되어야 합니다. 아직 Vercel 프로젝트를 연결하지 않았다면, 처음 사용 시 스킬이 연결을 안내합니다.

Vercel 스킬 구성

Vercel 스킬은 Vercel Access Token 또는 Vercel CLI 로그인 플로우를 통한 인증이 필요합니다. 가장 간단한 설정을 위해 vercel login을 사용하는 것을 권장합니다.

토큰 기반 인증

토큰을 사용하려면 vercel.com/account/tokens에서 생성하세요:

| 설정 | 권장 사항 | |---------|---------------| | 범위 | 전체 계정 또는 특정 팀 | | 만료 | 90일 (정기적으로 갱신) | | 이름 | openclaw-agent와 같은 설명적인 이름 사용 |

환경 설정

# 옵션 1: Vercel CLI 로그인 사용 (권장)
vercel login

# 옵션 2: Vercel Access Token 설정
export VERCEL_TOKEN=your_vercel_token_here

# 선택 사항: 기본 팀/범위 설정
export VERCEL_ORG_ID=team_your_team_id
export VERCEL_PROJECT_ID=prj_your_project_id

중요: 토큰을 구성 파일에 하드코딩하지 마세요. 환경 변수나 1Password 또는 Bitwarden과 같은 시크릿 관리자를 사용하세요.

프로젝트 연결

배포하기 전에 로컬 디렉토리를 Vercel 프로젝트에 연결하세요:

vercel link

이 명령은 프로젝트 구성이 포함된 .vercel 디렉토리를 생성합니다. 스킬은 이 연결을 사용하여 배포할 프로젝트를 결정합니다.

Vercel 스킬 사용 예시

1. 프리뷰에 배포

사용자: "현재 프로젝트를 Vercel에 프리뷰로 배포해 줘."

에이전트가 vercel deploy를 실행하고 프리뷰 URL을 반환합니다. 이 URL을 팀원들과 공유하여 프로덕션 승격 전에 검토할 수 있습니다.

2. 프로덕션으로 승격

사용자: "최신 프리뷰 배포를 프로덕션으로 승격해 줘."

에이전트가 가장 최근의 프리뷰 배포를 식별하고 vercel promote를 실행하여 라이브 프로덕션 버전으로 만듭니다. OpenClaw는 진행하기 전에 작업을 확인합니다.

3. 환경 변수 관리

사용자: "프로덕션용으로 DATABASE_URL 환경 변수를 postgres://... 값으로 추가해 줘."

에이전트가 vercel env add DATABASE_URL production을 실행하고 값을 안전하게 저장합니다. 프리뷰, 개발, 프로덕션 환경 전반에 걸쳐 환경 변수를 목록 조회, 업데이트 또는 제거할 수도 있습니다.

4. 빌드 로그 검사

사용자: "마지막으로 실패한 배포의 빌드 로그를 보여 줘."

에이전트가 vercel ls로 최근 배포를 가져오고, 실패한 배포를 식별한 후, vercel inspect로 빌드 출력을 조회합니다. 그런 다음 오류를 요약하고 수정 방법을 제안합니다.

5. 커스텀 도메인 구성

사용자: "내 Vercel 프로젝트에 app.example.com 도메인을 추가해 줘."

에이전트가 vercel domains add app.example.com을 실행하고 도메인 등록 기관에서 구성해야 할 DNS 레코드를 제공합니다. 도메인 구성 상태도 확인할 수 있습니다.

보안 및 모범 사례

Vercel 스킬은 배포 및 프로젝트 설정에 대해 쓰기 작업을 수행할 수 있습니다. 안전하게 사용하려면 다음 지침을 따르세요:

• 최소 권한 원칙을 사용하세요. 팀에서 작업하는 경우 전체 계정 접근 대신 특정 프로젝트로 토큰 범위를 제한하세요.
• 프로덕션 배포 전에 검토하세요. 항상 먼저 프리뷰 배포를 사용하세요. OpenClaw는 프로덕션 승격 전에 확인을 요청합니다.
• 환경 변수를 보호하세요. 데이터베이스 URL 및 API 키와 같은 민감한 값은 vercel env를 통해 설정하세요 — 소스 코드에 커밋하지 마세요.
• 토큰을 정기적으로 갱신하세요. Vercel Access Token에 90일 만료를 설정하고 사전에 갱신하세요.
• 배포를 감사하세요. Vercel 대시보드 활동 탭을 정기적으로 확인하여 CLI를 통해 수행된 배포를 검토하세요.
• 팀 범위를 사용하세요. 다중 팀 환경에서는 잘못된 팀에 배포하지 않도록 VERCEL_ORG_ID를 명시적으로 설정하세요.

일반적인 오류 해결

"Error: No Project linked"

로컬 디렉토리가 아직 Vercel 프로젝트에 연결되지 않았습니다.

# 기존 프로젝트에 연결
vercel link

# 또는 배포하면서 새 프로젝트 생성
vercel deploy

계정에 여러 프로젝트가 있는 경우 스킬이 프로젝트 선택을 안내합니다.

"Error: Invalid token"

Vercel Access Token이 누락되었거나, 만료되었거나, 취소되었습니다.

1. vercel.com/account/tokens에서 토큰을 확인하세요.
2. 만료된 경우 새 토큰을 생성하고 환경 변수를 업데이트하세요.
3. 또는 vercel login으로 다시 인증하세요.

# 재인증
vercel login

# 또는 토큰 업데이트
export VERCEL_TOKEN=your_new_token_here

"Build Failed: Command 'npm run build' exited with 1"

배포 중 빌드 명령이 실패했습니다. 이는 보통 스킬 문제가 아닌 코드 문제입니다.

1. 먼저 로컬에서 빌드를 실행하세요: npm run build
2. 누락된 환경 변수를 확인하세요 — 스킬이 vercel env ls로 목록을 조회할 수 있습니다
3. vercel inspect <deployment-url>로 전체 빌드 로그를 검토하세요
4. package.json 스크립트와 프레임워크 설정이 Vercel의 빌드 구성과 일치하는지 확인하세요