OpenClaw VPS 호스팅 — 초기 설정

SSH 접속 후 openclaw-setup 명령어로 AI 모델 연결, 메신저 채널 설정, 대시보드 접속까지 완료하는 가이드입니다. 이 단계가 끝나면 메신저에서 AI 에이전트와 대화할 수 있습니다.

💡 요약 정리

SSH로 서버에 접속한 후 openclaw-setup 명령어를 실행하여 설정 마법사를 시작합니다.
Claude / GPT / Gemini 중 하나의 LLM 모델을 연결합니다.
Telegram / Discord / Slack 등 메신저 채널을 연결합니다.
SSH 터널을 설정하여 대시보드에 접속합니다.
설정이 완료되면 메신저에서 AI 에이전트와 대화할 수 있습니다.

설정 마법사 실행 — openclaw-setup 명령 및 Security 경고
LLM 모델 연결 — Claude / GPT / Gemini API 연결 (OAuth 포함)
메신저 채널 연결 — Telegram / Discord / Slack 설정
추가 설정 — Skills, Hooks, 웹 검색
SSH 터널 및 대시보드 접속
관리 명령어

1. 설정 마법사 실행

1-1. openclaw-setup 실행

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

openclaw-setup

설정 마법사가 3단계로 진행됩니다:

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

1-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 격리 환경 안에서 실행되므로 서버 본체에 대한 영향이 최소화됩니다.

권장 보안 설정 (참고):

Pairing/Allowlist + Mention 게이팅을 활용하세요.
Sandbox + 최소 권한 원칙으로 도구를 설정하세요.
에이전트가 접근할 수 있는 파일 시스템에 시크릿(API Key 등)을 두지 마세요.
보안 감사 명령어: openclaw security audit --deep

1-3. Onboarding 모드 선택 — QuickStart

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

◇  Onboarding mode
│  QuickStart

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

항목	기본값	설명
Gateway port	50000	관리 콘솔이 동작하는 포트
Gateway bind	Loopback (127.0.0.1)	서버 내부에서만 접근 가능 (보안)
Gateway auth	Token (default)	토큰 기반 인증
Tailscale exposure	Off	외부 노출 비활성화

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

2. LLM 모델 연결

AI 에이전트가 사용할 LLM(대규모 언어 모델)을 연결합니다. Claude, GPT, Gemini 중 하나를 선택하세요.

2-1. 모델 제공사 선택

◇  Model/auth provider
│  Anthropic / OpenAI / Google

제공사	모델 예시	인증 방식	특징
Anthropic	Claude Sonnet / Opus	API Key 직접 입력	한국어 성능 우수
OpenAI	GPT-4o / GPT-5	API Key 또는 Codex OAuth	가장 범용적, ChatGPT Plus 구독으로 OAuth 가능
Google	Gemini Pro / Ultra	API Key 또는 Antigravity OAuth	Google 생태계 연동

2-2. Claude (Anthropic) 연결 — API Key 방식

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

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

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

2-3. GPT (OpenAI) 연결 — Codex OAuth 방식

OpenAI는 API Key 직접 입력 외에 Codex OAuth를 통해 ChatGPT 계정으로 인증할 수 있습니다. ChatGPT Plus/Pro 구독자라면 OAuth가 가장 간편합니다.

Model/auth provider에서 OpenAI 선택
인증 방식에서 OpenAI Codex (ChatGPT OAuth) 선택
VPS 환경에서는 아래와 같은 안내가 표시됩니다:

◇  OpenAI Codex OAuth ──────────────────────────────────╮
│  You are running in a remote/VPS environment.         │
│  A URL will be shown for you to open in your LOCAL    │
│  browser. After signing in, paste the redirect URL    │
│  back here.                                           │
├───────────────────────────────────────────────────────╯

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...

인증이 완료되면 모델이 자동으로 설정됩니다:

◇  Model configured ──────────────────────╮
│  Default model set to openai-codex/...  │
├─────────────────────────────────────────╯

참고: OAuth 토큰은 자동으로 갱신됩니다. 만료 시 자동으로 refresh되므로 수동 관리가 불필요합니다.

2-4. Gemini (Google) 연결 — Antigravity OAuth 방식

Gemini도 API Key 직접 입력 외에 Antigravity OAuth를 통해 Google 계정으로 인증할 수 있습니다.

Model/auth provider에서 Google 선택
인증 방식에서 Google Antigravity OAuth 선택
GPT OAuth와 동일한 방식으로 진행합니다:
- 표시되는 URL을 내 PC 브라우저에서 열기
- Google 계정으로 로그인 및 권한 승인
- 리다이렉트된 URL을 복사하여 터미널에 붙여넣기

주의: Google OAuth는 간혹 HTTP localhost 리다이렉트를 차단할 수 있습니다. 이 경우 API Key 직접 입력 방식(aistudio.google.com)을 사용하세요.

2-5. 기본 모델 확인

모델 연결 후 기본 사용 모델을 확인하거나 변경할 수 있습니다:

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

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

3. 메신저 채널 연결

AI 에이전트가 동작할 메신저 채널을 설정합니다. 이 가이드에서는 가장 간편한 텔레그램 기준으로 설명합니다.

3-1. 1단계: 텔레그램 봇 생성 (BotFather)

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

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

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

3-2. 2단계: openclaw-setup에서 토큰 입력

openclaw-setup TUI 과정에서 채널 선택 화면이 나옵니다:

◇  Select channels to configure
│  Telegram                        ← 선택

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

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

3-3. 3단계: 봇에서 Pairing Code 받기

텔레그램에서 본인이 만든 봇(예: @my_openclaw_bot)을 검색
/start 명령어 입력
봇이 다음 정보를 응답합니다:

OpenClaw: access not configured.
Your Telegram user id: [유저아이디]

Pairing code: E5V4S5JW
Ask the bot owner to approve with:
  openclaw pairing approve telegram

Pairing 코드는 매번 달라집니다.

3-4. 4단계: 서버에서 승인

서버에서 다음 명령어로 텔레그램 계정을 승인합니다:

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"

명령어 구조 설명:

su - openclaw: openclaw 사용자로 전환
podman exec -u node openclaw-svc: 컨테이너 내부에서 node 사용자로 실행
openclaw pairing approve telegram: 실제 승인 명령어

승인 완료 시:

Approved sender [유저아이디]

3-5. 5단계: 연동 완료 확인

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

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

전체 플로우

BotFather 봇 생성 → openclaw-setup 토큰 입력 → 봇에서 /start → Pairing Code 확인 → 서버에서 승인 → 연동 완료!

3-6. 기타 지원 채널

텔레그램 외에도 다음 메신저를 연결할 수 있습니다:

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

OpenClaw의 정책 변경 및 자체 서비스 이슈에 따라 메신저 연결이 정상 동작하다가 갑자기 안 될 수 있습니다. 이는 OpenClaw 측의 업데이트나 메신저 API 변경에 의한 것이므로, 문제 발생 시 OpenClaw 커뮤니티(Discord)를 확인하세요.

4. 추가 설정

4-1. Skills 설정 (선택)

에이전트가 사용할 수 있는 스킬(도구) 목록이 표시됩니다:

◇  Skills status ────────────╮
│  Eligible: 4               │
│  Missing requirements: 45  │
├────────────────────────────╯

◇  Configure skills now? (recommended)
│  No

Eligible: 현재 바로 사용 가능한 스킬 수
Missing requirements: 추가 설치가 필요한 스킬 수

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

4-2. Hooks 설정 (선택)

Hooks는 에이전트 이벤트 발생 시 자동으로 동작을 실행하는 기능입니다.

◇  Enable hooks?
│  Skip for now

처음에는 Skip for now를 선택하세요. 나중에 필요 시 설정할 수 있습니다.

4-3. 웹 검색 설정 (선택)

에이전트가 웹 검색을 할 수 있게 하려면 Brave Search API Key가 필요합니다.

◇  Web search (optional) ──────────────────────────╮
│  OpenClaw uses Brave Search for the web_search   │
│  tool. Without a Brave Search API key, web       │
│  search won't work.                              │
├──────────────────────────────────────────────────╯

나중에 openclaw configure --section web으로 설정하거나, 환경 변수 BRAVE_API_KEY를 설정할 수 있습니다.

5. SSH 터널 및 대시보드 접속

설정이 완료되면 대시보드 접속 정보가 표시됩니다.

5-1. 설정 완료 화면

============================================================
   설정이 완료되었습니다!
============================================================

화면에 표시되는 SSH 터널 명령어와 대시보드 URL을 기록해 두세요.

5-2. SSH 터널 설정

대시보드는 보안을 위해 서버 내부에서만 접근 가능합니다. 내 PC에서 접속하려면 SSH 터널을 설정해야 합니다.

Mac / Linux

새 터미널 창을 열고 아래 명령어를 실행합니다:

ssh -N -L {포트}:127.0.0.1:{포트} root@{서버IP}

예시 (설정 완료 화면에 표시된 값 사용):

ssh -N -L 50000:127.0.0.1:50000 root@172.235.211.131

명령 실행 후 아무 메시지가 안 나오고 멈춘 것처럼 보이는 게 정상입니다. (터널 유지 중)
이 터미널 창은 닫지 마세요. 닫으면 터널이 끊깁니다.

Windows (PuTTY)

PuTTY 실행 → Session → Host Name에 서버 IP 입력
Connection → SSH → Tunnels
Source port: 설정 화면에 표시된 포트 (예: 50000)
Destination: 127.0.0.1:{포트} (예: 127.0.0.1:50000)
Add 클릭 → Open

팁: 다음부터 편하게 쓰려면 Session에서 이름 저장 후 Save 해두세요.

5-3. 브라우저에서 대시보드 접속

터널이 연결된 상태에서 브라우저 주소창에 설정 완료 화면에 표시된 URL을 입력합니다:

http://127.0.0.1:{포트}/#token={토큰값}