Getting Started

목표: 제로 → 첫 작동하는 채팅 (합리적인 기본값으로)으로 최대한 빠르게 진행.

가장 빠른 채팅: Control UI를 엽니다 (채널 설정 불필요). openclaw dashboard를 실행하고 브라우저에서 채팅하거나, gateway 호스트에서 http://127.0.0.1:18789/를 엽니다. 문서: Dashboard 및 Control UI.

권장 경로: CLI 온보딩 마법사 (openclaw onboard) 사용. 설정 내용:

  • 모델/인증 (OAuth 권장)
  • gateway 설정
  • 채널 (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
  • 페어링 기본값 (보안 DM)
  • 워크스페이스 부트스트랩 + skills
  • 선택적 백그라운드 서비스

더 깊은 참조 페이지를 원하면 다음으로 이동하세요: Wizard, Setup, Pairing, Security.

샌드박싱 참고사항: agents.defaults.sandbox.mode: "non-main"은 session.mainKey (기본값 "main")를 사용하므로, 그룹/채널 세션이 샌드박스됩니다. main 에이전트가 항상 호스트에서 실행되도록 하려면, 명시적인 에이전트별 오버라이드를 설정하세요:

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) 사전 요구사항

  • Node >=22
  • pnpm (선택사항; 소스에서 빌드하는 경우 권장)
  • 권장: 웹 검색을 위한 Brave Search API 키. 가장 쉬운 경로: openclaw configure --section web (tools.web.search.apiKey 저장). Web tools 참조.

macOS: 앱을 빌드할 계획이면 Xcode / CLT를 설치하세요. CLI + gateway만 사용하려면 Node만 충분합니다. Windows: WSL2 사용 (Ubuntu 권장). WSL2를 강력히 권장합니다; 네이티브 Windows는 테스트되지 않았고, 더 문제가 많으며, 도구 호환성이 낮습니다. 먼저 WSL2를 설치한 다음, WSL 내부에서 Linux 단계를 실행하세요. Windows (WSL2) 참조.

1) CLI 설치 (권장)

curl -fsSL https://openclaw.bot/install.sh | bash

설치 프로그램 옵션 (설치 방법, 비대화형, GitHub에서): Install.

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

대안 (전역 설치):

npm install -g openclaw@latest

pnpm add -g openclaw@latest

2) 온보딩 마법사 실행 (및 서비스 설치)

openclaw onboard --install-daemon

선택할 내용:

  • Local vs Remote gateway
  • Auth: OpenAI Code (Codex) 구독 (OAuth) 또는 API 키. Anthropic의 경우 API 키를 권장합니다; claude setup-token도 지원됩니다.
  • Providers: WhatsApp QR 로그인, Telegram/Discord bot 토큰, Mattermost plugin 토큰 등.
  • Daemon: 백그라운드 설치 (launchd/systemd; WSL2는 systemd 사용)
    • Runtime: Node (권장; WhatsApp/Telegram 필수). Bun은 권장하지 않습니다.
  • Gateway token: 마법사는 기본적으로 하나를 생성하고 (루프백에서도) gateway.auth.token에 저장합니다.

마법사 문서: Wizard

Auth: 저장 위치 (중요)

  • 권장 Anthropic 경로: API 키 설정 (마법사가 서비스 사용을 위해 저장 가능). claude setup-token도 Claude Code 자격 증명을 재사용하려는 경우 지원됩니다.

  • OAuth 자격 증명 (레거시 가져오기): ~/.openclaw/credentials/oauth.json

  • Auth 프로필 (OAuth + API 키): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

헤드리스/서버 팁: 먼저 일반 머신에서 OAuth를 수행한 다음, oauth.json을 gateway 호스트로 복사하세요.

3) Gateway 시작

온보딩 중 서비스를 설치했다면, Gateway가 이미 실행 중이어야 합니다:

openclaw gateway status

수동 실행 (포그라운드):

openclaw gateway --port 18789 --verbose

Dashboard (로컬 루프백): http://127.0.0.1:18789/ 토큰이 구성되어 있으면, Control UI 설정에 붙여넣으세요 (connect.params.auth.token으로 저장).

⚠️ Bun 경고 (WhatsApp + Telegram): Bun은 이러한 채널에 알려진 문제가 있습니다. WhatsApp 또는 Telegram을 사용하는 경우, Node로 Gateway를 실행하세요.

3.5) 빠른 검증 (2분)

openclaw status
openclaw health
openclaw security audit --deep

4) 첫 채팅 인터페이스 페어링 + 연결

WhatsApp (QR 로그인)

openclaw channels login

WhatsApp → 설정 → 연결된 디바이스를 통해 스캔하세요.

WhatsApp 문서: WhatsApp

Telegram / Discord / 기타

마법사가 토큰/구성을 작성할 수 있습니다. 수동 구성을 선호하면 다음으로 시작하세요:

Telegram DM 팁: 첫 번째 DM은 페어링 코드를 반환합니다. 승인하세요 (다음 단계 참조) 그렇지 않으면 bot이 응답하지 않습니다.

5) DM 안전 (페어링 승인)

기본 자세: 알려지지 않은 DM은 짧은 코드를 받고 승인될 때까지 메시지가 처리되지 않습니다. 첫 번째 DM이 응답이 없으면, 페어링을 승인하세요:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

페어링 문서: Pairing

소스에서 (개발)

OpenClaw 자체를 해킹하는 경우, 소스에서 실행:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 첫 실행 시 UI 의존성 자동 설치
pnpm build
openclaw onboard --install-daemon

전역 설치가 없으면, 리포지토리에서 pnpm openclaw ...를 통해 온보딩 단계를 실행하세요. pnpm build도 A2UI 에셋을 번들합니다; 해당 단계만 실행해야 하는 경우, pnpm canvas:a2ui:bundle을 사용하세요.

Gateway (이 리포지토리에서):

node openclaw.mjs gateway --port 18789 --verbose

7) 엔드투엔드 검증

새 터미널에서 테스트 메시지 전송:

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

openclaw health가 "no auth configured"를 표시하면, 마법사로 돌아가 OAuth/키 인증을 설정하세요 — 에이전트가 없으면 응답할 수 없습니다.

팁: openclaw status --all은 최고의 붙여넣기 가능한 읽기 전용 디버그 보고서입니다. Health 프로브: openclaw health (또는 openclaw status --deep)는 실행 중인 gateway에 health 스냅샷을 요청합니다.

다음 단계 (선택사항, 하지만 훌륭함)

← 문서로 돌아가기