온보딩 마법사 (CLI)

온보딩 마법사는 macOS, Linux 또는 Windows (WSL2를 통해; 강력히 권장)에서 OpenClaw를 설정하는 권장 방법입니다. 하나의 안내 플로우에서 로컬 Gateway 또는 원격 Gateway 연결, 채널, 스킬 및 워크스페이스 기본값을 구성합니다.

주 진입점:

openclaw onboard

가장 빠른 첫 채팅: Control UI를 엽니다 (채널 설정 불필요). openclaw dashboard를 실행하고 브라우저에서 채팅합니다. 문서: Dashboard.

후속 재구성:

openclaw configure

권장: agent가 web_search를 사용할 수 있도록 Brave Search API 키를 설정합니다 (web_fetch는 키 없이 작동). 가장 쉬운 경로: openclaw configure --section web 이는 tools.web.search.apiKey를 저장합니다. 문서: Web tools.

QuickStart vs Advanced

마법사는 QuickStart (기본값) 대 Advanced (완전 제어)로 시작합니다.

QuickStart는 기본값을 유지합니다:

로컬 Gateway (loopback)
워크스페이스 기본값 (또는 기존 워크스페이스)
Gateway 포트 18789
Gateway 인증 Token (자동 생성, loopback에서도)
Tailscale 노출 Off
Telegram + WhatsApp DM은 기본적으로 allowlist입니다 (전화번호를 입력하라는 메시지가 표시됨)

Advanced는 모든 단계 (모드, 워크스페이스, Gateway, 채널, 데몬, 스킬)를 노출합니다.

마법사가 하는 일

**로컬 모드 (기본값)**는 다음을 안내합니다:

모델/인증 (OpenAI Code (Codex) 구독 OAuth, Anthropic API 키 (권장) 또는 setup-token (붙여넣기), MiniMax/GLM/Moonshot/AI Gateway 옵션)
워크스페이스 위치 + 부트스트랩 파일
Gateway 설정 (포트/바인드/인증/tailscale)
프로바이더 (Telegram, WhatsApp, Discord, Google Chat, Mattermost (플러그인), Signal)
데몬 설치 (LaunchAgent / systemd 사용자 유닛)
상태 확인
스킬 (권장)

원격 모드는 다른 곳에 있는 Gateway에 연결하도록 로컬 클라이언트만 구성합니다. 원격 호스트에 아무것도 설치하거나 변경하지 않습니다.

더 많은 격리된 agent를 추가하려면 (별도의 워크스페이스 + 세션 + 인증) 다음을 사용합니다:

openclaw agents add <name>

팁: --json은 비대화형 모드를 의미하지 않습니다. 스크립트에는 --non-interactive (및 --workspace)를 사용합니다.

플로우 세부 사항 (로컬)

기존 구성 감지
- ~/.openclaw/openclaw.json이 있으면 Keep / Modify / Reset을 선택합니다.
- 마법사를 다시 실행해도 명시적으로 Reset을 선택하지 않는 한 아무것도 지우지 않습니다 (또는 --reset 전달).
- 구성이 유효하지 않거나 레거시 키를 포함하는 경우, 마법사는 중지하고 계속하기 전에 openclaw doctor를 실행하도록 요청합니다.
- Reset은 trash를 사용하며 (rm 사용 안 함) 범위를 제공합니다:
  - Config만
  - Config + 자격 증명 + 세션
  - 전체 재설정 (워크스페이스도 제거)
모델/인증
- Anthropic API 키 (권장): 있으면 ANTHROPIC_API_KEY를 사용하거나 키를 묻고, 데몬 사용을 위해 저장합니다.
- Anthropic OAuth (Claude Code CLI): macOS에서 마법사는 Keychain 항목 "Claude Code-credentials"를 확인합니다 (launchd 시작이 차단되지 않도록 "항상 허용" 선택); Linux/Windows에서는 있으면 ~/.claude/.credentials.json을 재사용합니다.
- Anthropic 토큰 (setup-token 붙여넣기): 모든 머신에서 claude setup-token을 실행한 다음 토큰을 붙여넣습니다 (이름을 지정할 수 있음; 공백 = 기본값).
- OpenAI Code (Codex) 구독 (Codex CLI): ~/.codex/auth.json이 있으면 마법사가 재사용할 수 있습니다.
- OpenAI Code (Codex) 구독 (OAuth): 브라우저 플로우; code#state를 붙여넣습니다.
  - 모델이 설정되지 않았거나 openai/*일 때 agents.defaults.model을 openai-codex/gpt-5.2로 설정합니다.
- OpenAI API 키: 있으면 OPENAI_API_KEY를 사용하거나 키를 묻고, launchd가 읽을 수 있도록 ~/.openclaw/.env에 저장합니다.
- OpenCode Zen (다중 모델 프록시): OPENCODE_API_KEY (또는 OPENCODE_ZEN_API_KEY, https://opencode.ai/auth에서 받기)를 묻습니다.
- API 키: 키를 저장합니다.
- Vercel AI Gateway (다중 모델 프록시): AI_GATEWAY_API_KEY를 묻습니다.
- 자세한 내용: Vercel AI Gateway
- MiniMax M2.1: 구성이 자동으로 작성됩니다.
- 자세한 내용: MiniMax
- Synthetic (Anthropic 호환): SYNTHETIC_API_KEY를 묻습니다.
- 자세한 내용: Synthetic
- Moonshot (Kimi K2): 구성이 자동으로 작성됩니다.
- Kimi Code: 구성이 자동으로 작성됩니다.
- 자세한 내용: Moonshot AI (Kimi + Kimi Code)
- Skip: 아직 인증이 구성되지 않았습니다.
- 감지된 옵션에서 기본 모델을 선택합니다 (또는 provider/model을 수동으로 입력).
- 마법사는 모델 검사를 실행하고 구성된 모델이 알 수 없거나 인증이 누락된 경우 경고합니다.

OAuth 자격 증명은 ~/.openclaw/credentials/oauth.json에 있으며; 인증 프로필은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (API 키 + OAuth)에 있습니다.
자세한 내용: /concepts/oauth

워크스페이스
- 기본값 ~/.openclaw/workspace (구성 가능).
- agent 부트스트랩 의식에 필요한 워크스페이스 파일을 시드합니다.
- 전체 워크스페이스 레이아웃 + 백업 가이드: Agent workspace
Gateway
- 포트, 바인드, 인증 모드, tailscale 노출.
- 인증 권장 사항: 로컬 WS 클라이언트가 인증해야 하도록 loopback에도 Token을 유지합니다.
- 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화합니다.
- 비 loopback 바인드는 여전히 인증이 필요합니다.
채널

WhatsApp: 선택적 QR 로그인.
Telegram: 봇 토큰.
Discord: 봇 토큰.
Google Chat: 서비스 계정 JSON + 웹훅 대상.
Mattermost (플러그인): 봇 토큰 + 기본 URL.
Signal: 선택적 signal-cli 설치 + 계정 구성.
iMessage: 로컬 imsg CLI 경로 + DB 액세스.
DM 보안: 기본값은 페어링입니다. 첫 번째 DM은 코드를 보냅니다; openclaw pairing approve <channel> <code>로 승인하거나 허용 목록을 사용합니다.

데몬 설치
- macOS: LaunchAgent
  - 로그인된 사용자 세션이 필요합니다; 헤드리스의 경우 맞춤 LaunchDaemon을 사용합니다 (제공되지 않음).
- Linux (및 WSL2를 통한 Windows): systemd 사용자 유닛
  - 마법사는 로그아웃 후 Gateway가 유지되도록 loginctl enable-linger <user>를 통해 lingering을 활성화하려고 시도합니다.
  - sudo를 묻을 수 있습니다 (/var/lib/systemd/linger 작성); sudo 없이 먼저 시도합니다.
- 런타임 선택: Node (권장; WhatsApp/Telegram에 필요). Bun은 권장되지 않습니다.
상태 확인
- Gateway를 시작하고 (필요한 경우) openclaw health를 실행합니다.
- 팁: openclaw status --deep은 상태 출력에 Gateway 상태 프로브를 추가합니다 (도달 가능한 Gateway 필요).
스킬 (권장)
- 사용 가능한 스킬을 읽고 요구 사항을 확인합니다.
- 노드 관리자를 선택할 수 있습니다: npm / pnpm (bun 권장되지 않음).
- 선택적 종속성을 설치합니다 (일부는 macOS에서 Homebrew 사용).
완료
- 요약 + 다음 단계, iOS/Android/macOS 앱 추가 기능 포함.

GUI가 감지되지 않으면 마법사는 브라우저를 여는 대신 Control UI에 대한 SSH 포트 포워드 지침을 인쇄합니다.
Control UI 에셋이 누락된 경우 마법사는 빌드를 시도합니다; 대체는 pnpm ui:build입니다 (UI 종속성 자동 설치).

원격 모드

원격 모드는 다른 곳에 있는 Gateway에 연결하도록 로컬 클라이언트를 구성합니다.

설정할 사항:

원격 Gateway URL (ws://...)
원격 Gateway가 인증을 요구하는 경우 토큰 (권장)

참고:

원격 설치 또는 데몬 변경은 수행되지 않습니다.
Gateway가 loopback 전용인 경우 SSH 터널링 또는 tailnet을 사용합니다.
검색 힌트:
- macOS: Bonjour (dns-sd)
- Linux: Avahi (avahi-browse)

다른 agent 추가

openclaw agents add <name>을 사용하여 자체 워크스페이스, 세션 및 인증 프로필이 있는 별도의 agent를 만듭니다. --workspace 없이 실행하면 마법사가 시작됩니다.

설정 사항:

agents.list[].name
agents.list[].workspace
agents.list[].agentDir

참고:

기본 워크스페이스는 ~/.openclaw/workspace-<agentId>를 따릅니다.
인바운드 메시지를 라우팅하려면 bindings를 추가합니다 (마법사가 할 수 있음).
비대화형 플래그: --model, --agent-dir, --bind, --non-interactive.

비대화형 모드

--non-interactive를 사용하여 온보딩을 자동화하거나 스크립트화합니다:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

머신 판독 가능한 요약을 위해 --json을 추가합니다.

Gemini 예제:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI 예제:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI Gateway 예제:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot 예제:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic 예제:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zen 예제:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Agent 추가 (비대화형) 예제:

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway 마법사 RPC

Gateway는 RPC를 통해 마법사 플로우를 노출합니다 (wizard.start, wizard.next, wizard.cancel, wizard.status). 클라이언트 (macOS 앱, Control UI)는 온보딩 로직을 다시 구현하지 않고 단계를 렌더링할 수 있습니다.

Signal 설정 (signal-cli)

마법사는 GitHub 릴리스에서 signal-cli를 설치할 수 있습니다:

적절한 릴리스 에셋을 다운로드합니다.
~/.openclaw/tools/signal-cli/<version>/ 아래에 저장합니다.
구성에 channels.signal.cliPath를 작성합니다.

참고:

JVM 빌드에는 Java 21이 필요합니다.
사용 가능한 경우 네이티브 빌드가 사용됩니다.
Windows는 WSL2를 사용합니다; signal-cli 설치는 WSL 내부의 Linux 플로우를 따릅니다.

마법사가 작성하는 것

~/.openclaw/openclaw.json의 일반적인 필드:

agents.defaults.workspace
agents.defaults.model / models.providers (Minimax 선택 시)
gateway.* (모드, 바인드, 인증, tailscale)
channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
프롬프트 중에 선택할 때 채널 허용 목록 (Slack/Discord/Matrix/Microsoft Teams) (가능한 경우 이름이 ID로 해결됨).
skills.install.nodeManager
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode

openclaw agents add는 agents.list[] 및 선택적 bindings를 작성합니다.

WhatsApp 자격 증명은 ~/.openclaw/credentials/whatsapp/<accountId>/ 아래에 있습니다. 세션은 ~/.openclaw/agents/<agentId>/sessions/ 아래에 저장됩니다.

일부 채널은 플러그인으로 제공됩니다. 온보딩 중에 하나를 선택하면 마법사는 구성하기 전에 설치를 묻습니다 (npm 또는 로컬 경로).