OpenClaw VPS 호스팅 — 초기 설정 가이드

OpenClaw VPS 호스팅은 고객님의 안전한 서비스 운영을 위해 초기 접속을 일부 제한하고 있습니다. 기본 방화벽 설정에 따라, 처음 서비스를 신청하셨던 IP에서만 온보딩 및 대시보드 접속이 가능합니다. 만약 다른 IP에서의 접속이 필요하신 경우, OpenClaw 관리 페이지의 안내에 따라 설정을 추가해 주시기 바랍니다.

AI 모델 연결, 메신저 채널 설정, 에이전트 가동까지 완료하는 가이드입니다. 이 단계가 끝나면 메신저에서 AI 에이전트와 대화할 수 있습니다.

설정 경로를 아직 선택하지 않으셨다면 빠른 시작 가이드의 §3을 먼저 확인해 주세요.

💡 요약 정리

OpenClaw VPS 호스팅의 초기 설정을 완료하면 메신저에서 AI 에이전트와 대화할 수 있습니다.
웹 기반 원스톱 온보딩과 SSH 기반 상세 온보딩 두 가지 설정 경로를 제공합니다.
AI 서비스 API Key와 메신저 봇 토큰을 미리 준비해 주세요.
설정 완료 후 메신저에서 봇에게 메시지를 보내 정상 동작을 확인할 수 있습니다.

현재 사용하고 계시는 요금제가 Essential, Basic, Performance, Advanced이시라면 이전 버전의 가이드를 확인해 주세요: 초기설정(구)

섹션	내용	대상
§1	원스톱 온보딩 (웹 기반)	서버/터미널에 익숙하지 않은 분
§2	상세 온보딩 (SSH 기반)	서버 관리에 익숙한 분
§3	사전 준비 상세 — API Key 발급 / 봇 토큰 생성	공통 (두 경로 모두 참조)
§4	연동 완료 확인 및 관리 명령어	공통

1. 원스톱 온보딩 (웹 기반)

SSH나 터미널 없이 웹 브라우저에서 클릭과 입력만으로 초기 설정을 완료합니다. API Key와 메신저 Bot Token을 미리 준비해 주세요. (발급 방법은 §3. 사전 준비 상세 참고)

원스톱 온보딩(웹 브라우저 온보딩)에서 제공하는 모델 리스트는 Openclaw에서 제공하는 모델 리스트로써 실제 AI 서비스 제공사가 구성한 모델 리스트가 아닙니다. 즉, AI 서비스 제공사의 모델 제공 정책과 Openclaw에서 제공하는 모델 리스트가 부합하지 않는다면 관련 모델 사용이 불가하실 수 있습니다. 이 점 참고 부탁드립니다.

1-1. 온보딩 시작

나의 서비스 관리 > OpenClaw 관리 페이지에 접속합니다.
"시작하기" 영역에서 "원스톱 온보딩 시작" 버튼을 클릭합니다.
새 브라우저 탭에서 OpenClaw 온보딩 위자드가 열립니다.

1-2. 로그인 (토큰 인증)

온보딩 위자드에 접속하면 로그인 화면이 표시됩니다.

나의 서비스 관리 페이지에서 확인한 OpenClaw 토큰을 입력합니다.
로그인 버튼을 클릭합니다.

토큰 확인 위치: 나의 서비스 관리 > OpenClaw 관리 > "OpenClaw 현황 정보" 테이블의 "OpenClaw 토큰" 항목에서 복사 버튼으로 복사할 수 있습니다.

인증에 성공하면 온보딩 위자드의 첫 번째 단계로 이동합니다.

1-3. Step 1 — AI 서비스 연결

사용할 AI 서비스를 선택하고 인증 정보를 입력합니다.

AI 서비스 선택

화면에 지원되는 AI 서비스 목록이 표시됩니다. 하나를 선택하세요:

구분	서비스	인증 방식
주요	OpenAI (GPT)	API Key 또는 OAuth
	Anthropic (Claude)	API Key
	Google (Gemini)	API Key
기타	Moonshot (Kimi)	API Key
	MiniMax	API Key
	Z.AI (GLM)	API Key

방법 A: API Key 입력

AI 서비스를 선택합니다.
인증 방식에서 "API Key"를 선택합니다.
미리 발급받은 API Key를 입력합니다. (발급 방법: §3-1)
"검증" 버튼을 클릭하면 키가 유효한지 자동으로 확인됩니다.
검증 성공 시 다음 단계로 진행됩니다.

현재 OpenAI API의 OpenClaw 권장 모델인 gpt 5.1 codex에서 간헐적인 연결 오류가 발생하고 있습니다. 가급적이면 gpt의 가장 최신 모델을 사용하시는 것을 권장드립니다.

방법 B: OAuth 인증 (OpenAI만 해당)

ChatGPT Plus/Pro 구독자라면 API Key 없이 OpenAI 계정으로 직접 인증할 수 있습니다.

AI 서비스에서 OpenAI를 선택합니다.
인증 방식에서 "OAuth"를 선택합니다.
"OpenAI로 로그인" 버튼을 클릭합니다.
OpenAI 로그인 페이지가 열립니다. ChatGPT 계정으로 로그인합니다.
권한 승인 후 자동으로 온보딩 위자드로 돌아옵니다.
인증 완료 메시지가 표시됩니다.

참고: OAuth 토큰은 자동으로 갱신되므로 별도 관리가 필요하지 않습니다.

OAuth 연동 주의사항:

OAuth 인증은 리스크가 적은 '가벼운 작업'에만 제한적으로 사용하시길 권장합니다.
제공된 화면에서 모두 로그인을 완료하시면 아래와 같은 화면이 제공됩니다. 해당 화면은 오류 화면이 아니라 정상 작동한 결과 화면이오니 화면 주소창의 값을 리다이렉트 URL 입력 칸에 복사 및 붙여넣기 해주세요.

모델 선택

인증이 완료되면 사용 가능한 모델 목록이 표시됩니다.

목록에서 사용할 모델을 선택합니다. (예: gpt-4o, claude-sonnet-4-5)
"선택 확인"을 클릭합니다.

참고: 일부 서비스(MiniMax 등)는 모델 목록이 자동 조회되지 않을 수 있습니다. 이 경우 공식 문서 기준의 모델 목록이 표시되며, "이 목록은 공식 문서 기준이며, 실제 사용 가능한 모델과 다를 수 있습니다." 안내가 함께 나타납니다.

1-4. Step 2 — 메신저 연결

AI 에이전트가 동작할 메신저를 연결합니다. 여기서는 가장 간편한 Telegram 기준으로 설명합니다. (봇 생성 방법: §3-3)

봇 토큰 입력

메신저 선택 화면에서 Telegram을 선택합니다.
BotFather에서 발급받은 봇 토큰을 입력합니다.
"연결" 버튼을 클릭합니다.
시스템이 자동으로 설정을 저장하고 Gateway를 시작합니다.

페어링 승인

Gateway가 시작되면 메신저 봇과의 연결을 승인해야 합니다.

텔레그램에서 본인이 만든 봇을 검색하여 /start를 입력합니다.
봇이 Pairing 코드를 응답합니다.
온보딩 위자드 화면에 페어링 코드 입력란이 표시됩니다.
봇이 알려준 코드를 입력하고 "승인" 버튼을 클릭합니다.

승인이 완료되면 메신저 연결 상태가 "연결됨"으로 표시됩니다.

1-5. 완료 — 홈 대시보드

모든 설정이 완료되면 홈 대시보드로 이동합니다. 여기서 다음 기능을 사용할 수 있습니다:

AI와 대화 시작하기 — 웹에서 직접 AI와 대화할 수 있습니다. 처음 대화를 시작하면 기기 인증 화면이 먼저 등장합니다. 인증이 자동으로 수행되며 몇 초 후면 대화를 시작할 수 있으니 화면에서 잠시 대기해주세요.
메신저 상태 확인 — 연결된 메신저 채널의 상태를 확인합니다.
시스템 관리 — AI 페르소나 설정, Gateway 재시작 등을 수행합니다.

이제부터 텔레그램에서 봇에게 메시지를 보내면 AI가 응답합니다.

§4. 연동 완료 확인에서 정상 동작을 확인해 보세요.

2. 상세 온보딩 (SSH 기반)

SSH로 서버에 접속한 상태에서 openclaw-setup 명령어로 설정합니다. API Key와 메신저 Bot Token을 미리 준비해 주세요. (발급 방법: §3. 사전 준비 상세)

사전 조건: 빠른 시작 가이드 §4의 SSH 접속이 완료된 상태여야 합니다.

원스톱 온보딩과 TUI의 관계: 카페24 OpenClaw VPS 호스팅은 원스톱 온보딩(웹 브라우저)과 TUI 온보딩(SSH 터미널) 두 가지 설정 경로를 모두 제공하며, 각 설정은 서로 연결되어 작동합니다. 원스톱 온보딩으로 초기 설정을 완료한 후에도, TUI에서 상세 설정(모델 변경, 메신저 추가, 스킬 구성 등)을 수정하거나 전체 초기화를 진행할 수 있습니다.

2-1. openclaw-setup 실행

SSH로 서버에 접속한 상태에서 아래 명령어를 입력합니다.

openclaw-setup

실행하면 먼저 설정 방법 선택 메뉴가 표시됩니다:

설정 방법을 선택하세요:

[1] 터미널에서 직접 설정 (TUI 온보딩)
    └ API Key, 메신저, 스킬 등 전체 설정

[2] 웹 브라우저로 설정
    └ 접속 URL + 토큰 안내

선택 (1/2): 1

[1]을 선택하면 TUI 온보딩이 시작됩니다. [2]를 선택하면 웹 브라우저 접속 정보가 안내됩니다.

기존 설정이 있는 경우 (재설정)

원스톱 온보딩을 이미 완료했거나 이전에 설정한 적이 있는 경우, TUI 진입 시 기존 설정 감지 화면이 표시됩니다:

◇  Existing config detected ─╮
│                            │
│  model: openai/gpt-4.1     │
│  gateway.mode: local       │
│                            │
├────────────────────────────╯

◇  Config handling
│  Reset / Keep existing

Reset → 전체 초기화 후 처음부터 다시 설정합니다.
Keep existing → 현재 설정을 유지한 채로 스킬 추가, 메신저 등록, AI 모델(Provider) 변경 등 개별 항목만 수정할 수 있습니다.

TUI 온보딩은 3단계로 진행됩니다:

STEP	내용	설명
STEP 1/3	컨테이너 실행 상태 확인	OpenClaw 컨테이너가 정상 실행 중인지 자동 확인
STEP 2/3	OpenClaw 초기 설정 (TUI)	대화형 화면에서 모델, 메신저, 옵션 설정
STEP 3/3	컨테이너 재시작	설정 반영을 위해 자동 재시작

2-2. Security 경고 — 반드시 Yes 선택

설정이 시작되면 첫 화면에 Security 경고가 표시됩니다. 반드시 Yes를 선택하세요.

◇  Security ──────────────────────────────────────────────╮
│  Security warning — please read.                        │
│                                                         │
│  OpenClaw is a hobby project and still in beta.         │
│  This bot can read files and run actions if tools are   │
│  enabled. A bad prompt can trick it into doing unsafe   │
│  things.                                                │
├─────────────────────────────────────────────────────────╯
◇  I understand this is powerful and inherently risky. Continue?
│  Yes

이 경고의 의미:

OpenClaw는 AI 에이전트가 파일을 읽고 쓰거나, 셸 명령을 실행할 수 있는 강력한 도구입니다.
잘못된 프롬프트(prompt injection)가 위험한 동작을 유발할 수 있으므로 보안에 주의해야 합니다.
OpenClaw VPS 호스팅에서는 Podman 격리 환경 안에서 실행되므로 서버 본체에 대한 영향이 최소화됩니다.

2-3. Onboarding 모드 선택 — QuickStart

Security 경고를 승인하면 온보딩 모드를 선택합니다. QuickStart를 선택하세요.

◇  Onboarding mode
│  QuickStart

QuickStart는 아래 기본값이 자동 적용됩니다:

항목	기본값	설명
Gateway port	자동 할당	시스템이 사용 가능한 포트를 자동 배정
Gateway bind	Loopback (127.0.0.1)	서버 내부에서만 접근 가능 (보안)
Gateway auth	Token (default)	토큰 기반 인증
Tailscale exposure	Off	외부 노출 비활성화

참고: Gateway 포트는 시스템이 자동으로 할당합니다. TUI 화면에 표시되는 포트 번호는 설정 시마다 달라질 수 있으며, 최종 접속 정보는 설정 완료 후 안내됩니다.

Advanced 모드를 선택하면 Gateway 포트, 바인딩 등이 변경되어 컨테이너 내부 프록시 설정과 충돌하여 정상 동작하지 않습니다. 반드시 QuickStart를 선택하세요.

2-4. LLM 모델 연결

AI 에이전트가 사용할 LLM을 연결합니다.

모델 제공사 선택

◇  Model/auth provider
│  Anthropic / OpenAI / Google

제공사	모델 예시	인증 방식
Anthropic	Claude Sonnet / Opus	API Key 직접 입력
OpenAI	GPT-4o / GPT-5	API Key 또는 Codex OAuth
Google	Gemini Pro / Ultra	API Key 직접 입력

API Key 발급 방법은 §3-1. LLM API Key 발급 방법을 참고하세요.

Claude (Anthropic) — API Key 방식

Model/auth provider에서 Anthropic 선택
인증 방식에서 API Key 선택
console.anthropic.com에서 발급받은 API Key 입력

◇  Anthropic API Key
│  sk-ant-api03-xxxx...xxxx

GPT (OpenAI) — Codex OAuth 방식

ChatGPT Plus/Pro 구독자라면 OAuth가 가장 간편합니다.

Model/auth provider에서 OpenAI 선택
인증 방식에서 OpenAI Codex (ChatGPT OAuth) 선택
화면에 표시되는 OAuth URL을 복사합니다.
내 PC의 브라우저에서 해당 URL을 엽니다. (서버가 아닌 내 PC의 브라우저)
OpenAI(ChatGPT) 계정으로 로그인하고 권한을 승인합니다.
로그인 완료 후 브라우저가 http://localhost:1455/auth/callback?code=... 형태의 URL로 이동합니다.
이 URL이 에러 페이지를 보여주는 것은 정상입니다. (VPS에서는 로컬 콜백 서버가 없기 때문)
브라우저 주소창의 전체 URL을 복사하여 터미널에 붙여넣기합니다.

◇  OAuth URL ready
Open this URL in your LOCAL browser:
https://auth.openai.com/oauth/authorize?response_type=code&client_id=app_EMoam...

◇  Paste the redirect URL (or authorization code)
│  http://localhost:1455/auth/callback?code=ac_v_DhhpTKFYPD8gwYCks67m...

기본 모델 확인

◇  Default model
│  Keep current (openai-codex/gpt-5.3-codex)

특별한 이유가 없다면 Keep current를 선택하여 기본 모델을 유지합니다.

OAuth 연동 주의사항:

OAuth 인증은 리스크가 적은 '가벼운 작업'에만 제한적으로 사용하시길 권장합니다.

GPT를 제외한 나머지 모델의 OAuth 인증 연동은 지양하시는 것을 권고합니다.

Claude: Anthropic 측에서 제3자 서비스의 OAuth 연동을 공식 금지하고 있습니다.

Gemini: 최근 OAuth 연동으로 인한 계정 정지 사례가 발생하였습니다.

2-5. 메신저 채널 연결

AI 에이전트가 동작할 메신저 채널을 설정합니다. 봇 생성 방법은 §3-3을 참고하세요.

토큰 입력

◇  Select channels to configure
│  Telegram                        ← 선택

◇  Enter Telegram bot token
│  1234567890:AAHxxxxxxxxxxxxx     ← BotFather 토큰 붙여넣기

설정 완료 후 자동으로 Gateway가 재시작됩니다.

Pairing Code 승인

텔레그램에서 본인이 만든 봇을 검색하여 /start 입력
봇이 Pairing 코드를 응답합니다.
서버에서 다음 명령어로 승인합니다:

su - openclaw -c "podman exec -u node openclaw-svc openclaw pairing approve telegram <pairing_code>"

예시:

su - openclaw -c "podman exec -u node openclaw-svc openclaw pairing approve telegram E5V4S5JW"

승인 완료 시:

Approved sender [유저아이디]

2-6. 추가 설정 (선택)

Skills 설정

◇  Configure skills now? (recommended)
│  No

처음에는 No를 선택하여 스킵하고, 기본 설정을 완료한 후 필요에 따라 추가하세요. 나중에 openclaw configure --section skills로 설정할 수 있습니다.

Hooks 설정

◇  Enable hooks?
│  Skip for now

처음에는 Skip for now를 선택하세요.

웹 검색 설정

에이전트가 웹 검색을 하려면 Brave Search API Key가 필요합니다. 나중에 openclaw configure --section web으로 설정하거나, 환경 변수 BRAVE_API_KEY를 설정할 수 있습니다.

2-7. 봇 시작 방식 선택(리셋이 아닌 재설정시)

추가 설정이 완료되면 봇 시작 방식을 선택하는 화면이 표시됩니다:

◆  How do you want to hatch your bot?
│  ● Hatch in TUI (recommended)
│  ○ Open the Web UI
│  ○ Do this later

"Open the Web UI" 또는 "Do this later"를 선택하세요. 설정 완료 후 자동으로 웹 브라우저 접속 정보가 안내되므로, TUI에서 별도로 봇을 시작할 필요가 없습니다.

2-8. 완료 — 웹 대시보드 접속

TUI 온보딩이 완료되면 컨테이너가 자동 재시작되고, 웹 대시보드 접속 정보가 표시됩니다:

[1. 웹 브라우저 접속]

    브라우저에서 아래 주소로 접속하세요:

        https://{URL}:{포트}

    접속하면 토큰 입력 화면이 나옵니다.
    아래 토큰을 입력하세요:

        {토큰값}

접속 방법

방법 A: 로그인 화면에서 토큰 입력

브라우저에서 https://{URL}:{포트} 주소로 접속합니다.
로그인 화면이 나타나면 화면에 안내된 토큰을 입력합니다.

방법 B: URL에 토큰 포함하여 바로 접속

브라우저 주소창에 토큰을 포함한 URL을 직접 입력하면 로그인 과정 없이 바로 접속됩니다:

https://{URL}:{포트}/#token={토큰값}

보안 주의: 토큰은 접속 권한 역할을 합니다. 토큰이 포함된 URL을 슬랙, 메일, 문서 등에 그대로 공유하지 마세요.

대시보드 접속이 안 될 때

문제	확인 사항
브라우저 접속 안 됨	서버 방화벽에서 해당 포트가 열려 있는지 확인. `su - openclaw` → `podman ps`로 컨테이너 상태 확인
토큰이 틀렸다고 나옴	`cat /opt/openclaw/gateway-token.txt`로 토큰 재확인
API 키 변경 후 반영 안 됨	`su - openclaw` → `podman restart openclaw-svc`로 재시작
화면이 이상하거나 권한 오류	서버 로그 확인: `su - openclaw` → `podman logs -f openclaw-svc`

§4. 연동 완료 확인에서 정상 동작을 확인해 보세요.

3. 사전 준비 상세

이 섹션은 원스톱 온보딩과 상세 온보딩 모두에서 참조하는 공통 내용입니다.

3-1. LLM API Key 발급 방법

Anthropic (Claude)

console.anthropic.com에 접속하여 회원가입 또는 로그인
좌측 메뉴에서 API Keys 클릭
Create Key 클릭 → 이름 입력 → Key 생성
생성된 Key를 즉시 복사하여 안전한 곳에 저장 (다시 확인 불가)

Key 형식: sk-ant-api03-xxxx...xxxx

OpenAI (GPT)

platform.openai.com/api-keys에 접속하여 로그인
Create new secret key 클릭
이름 입력 → Key 생성
생성된 Key를 즉시 복사하여 안전한 곳에 저장

Key 형식: sk-xxxx...xxxx

참고: OpenAI는 API Key 방식 외에 ChatGPT Plus/Pro 구독 계정으로 OAuth 인증도 가능합니다.

Google (Gemini)

aistudio.google.com/apikey에 접속하여 로그인
API 키 만들기 클릭
생성된 Key를 복사하여 저장

Key 형식: AIzaSy...

기타 프로바이더

서비스	발급 사이트
Moonshot (Kimi)	platform.moonshot.ai
MiniMax	platform.minimax.io
Z.AI (GLM)	docs.z.ai

주의: API Key는 절대 다른 사람에게 공유하지 마세요. 이 키로 요금이 청구됩니다.

3-2. OAuth 연동 주의사항

OAuth를 통한 인증은 API Key를 직접 발급하지 않아도 되어 편리하지만, 아래 사항을 반드시 확인하세요:

안전한 사용을 위해 OAuth 인증은 리스크가 적은 '가벼운 작업'에만 제한적으로 사용하시길 권장합니다.

3-3. 텔레그램 봇 생성 (BotFather)

텔레그램에서 @BotFather에게 메시지를 보내 새 봇을 만듭니다.

/newbot 명령어 입력
봇 이름 설정 (예: My OpenClaw Bot)
봇 유저네임 설정 — 반드시 bot으로 끝나야 함 (예: my_openclaw_bot)
생성 완료 시 HTTP API 토큰이 발급됨

토큰 형식: 1234567890:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

주의: 토큰은 절대 외부에 노출하지 마세요! 토큰이 있으면 누구나 봇을 제어할 수 있습니다.

3-4. 기타 메신저 설정

채널	설명
Discord	Discord Developer Portal에서 봇 생성 후 Token 입력. MESSAGE CONTENT INTENT 활성화 필요
Slack	Socket Mode 방식. Bot Token(`xoxb-`) + App Token(`xapp-`) 두 개 필요
WhatsApp	QR 코드 인증 방식. 별도 전화번호/eSIM 권장
LINE	별도 플러그인 설치 필요. 현재 연결이 불안정할 수 있음

주의: OpenClaw의 정책 변경 및 자체 서비스 이슈에 따라 메신저 연결이 정상 동작하다가 갑자기 안 될 수 있습니다. 문제 발생 시 OpenClaw 커뮤니티(Discord)를 확인하세요.

4. 연동 완료 확인

어떤 경로로 설정했든, 아래 항목을 확인하면 정상 완료된 것입니다.

4-1. 메신저 봇 응답 테스트

텔레그램 봇에게 아무 메시지를 보내면 AI가 응답합니다:

You:  안녕하세요
Bot:  안녕하세요! 무엇을 도와드릴까요?

응답이 오면 설정이 정상 완료된 것입니다. 이제부터 메신저에서 대화하는 것만으로 AI 에이전트를 사용할 수 있습니다.

4-2. 관리 명령어 (참고)

root 사용자에서 실행

명령어	용도
`openclaw-setup`	설정 재실행 (문제 발생 시 초기화 겸 재구성)

openclaw 사용자에서 실행

컨테이너 관리 명령어는 openclaw 사용자로 전환한 후 실행합니다:

su - openclaw

명령어	용도
`podman ps`	컨테이너 상태 확인
`podman logs -f openclaw-svc`	컨테이너 실시간 로그 확인
`podman restart openclaw-svc`	컨테이너 재시작

메신저에서 봇 사용하기

모든 설정이 완료되면, 평소에는 메신저에서 대화만 하면 됩니다. SSH 접속이나 터미널 조작은 설정 변경할 때만 필요합니다.

오늘 일정 정리해줘
/ask 이 문서 요약해줘

설정 중 문제가 발생했나요?

API Key 검증 실패 → §3-1. LLM API Key 발급 방법에서 키를 재발급해 보세요.
메신저 봇이 응답하지 않음 → Pairing 코드 승인 여부를 확인하세요.
그 외 문제 → 운영 가이드의 트러블슈팅 섹션을 참고하세요.

다음 단계: 운영 중 설정을 변경하거나 문제를 해결하는 방법을 알아보려면 → 운영 가이드