openclaw onboard CLI 가이드

새로운 도구를 프로젝트에 도입할 때 가장 번거로운 작업은 역시 초기 설정입니다. 환경 변수를 맞추고 설정 파일을 하나하나 수정하다 보면, 정작 코드를 한 줄도 쓰기 전에 진이 빠지기 마련이죠. 이런 반복적인 설정 과정은 개발자의 생산성을 떨어뜨리는 주요 원인이 됩니다.

openclaw onboard는 이런 불편함을 해결하기 위해 만들어졌습니다. 복잡한 매뉴얼을 뒤지는 대신, CLI 마법사를 통해 프로젝트에 필요한 설정을 직관적으로 마칠 수 있습니다.

필요한 것

openclaw CLI

빠른 시작

5분 안에 설정을 끝내는 방법입니다. 터미널에서 아래 명령어를 실행하세요.

openclaw onboard

이 명령어를 실행하면 대화형 마법사가 시작됩니다. 화면에 나오는 안내에 따라 설정을 진행하면 프로젝트 준비가 완료됩니다.

문제 해결

현재 원본 문서에 보고된 알려진 이슈가 없습니다. 마법사 실행 중 문제가 발생하면 설정 환경을 다시 확인해 보세요. 더 자세한 개요는 Onboarding Wizard 문서에서 확인할 수 있습니다.

설정 과정에서 어려움을 겪고 계신가요? AI Setup Assistant에게 바로 물어보세요.

다음 단계

Onboarding Wizard 개요

새로운 도구를 설치할 때 설정 과정이 블랙박스처럼 느껴져서 답답했던 적 있으시죠? 어떤 파일이 생성되고 내 API Key가 어디에 저장되는지 궁금한 건 개발자로서 당연한 마음이에요. OpenClaw의 로컬 모드 설정 과정을 투명하게 정리해 드릴게요.

OpenClaw 마법사를 실행하면 백엔드에서 어떤 일이 일어나는지, 그리고 각 단계에서 어떤 옵션을 선택할 수 있는지 하나씩 살펴봐요.

What You’ll Need

시작하기 전에 소스 문서에서 언급된 다음 사항들을 확인해 주세요.

Node.js: 권장 런타임이에요. (WhatsApp/Telegram 채널 사용 시 필수)
API Keys: Anthropic, OpenAI, xAI 등 사용하려는 모델의 키가 필요해요.
OS 권한: macOS(LaunchAgent) 또는 Linux(systemd)에서 Daemon 설정을 위한 권한이 필요할 수 있어요.
pnpm / npm: 스킬 설치를 위한 패키지 매니저가 필요해요.

Quick Start

가장 빠르게 설정을 완료하는 5분 경로예요.

설정 감지: openclaw 명령어를 실행해 기존 설정을 확인하거나 초기화(--reset)해요.
모델 인증: Anthropic이나 OpenAI 등 선호하는 Provider의 API Key를 입력해요.
Gateway 설정: 포트와 인증 모드(Token 권장)를 선택해요.
채널 및 검색: 메시징 앱(Discord, Telegram 등)과 웹 검색 엔진을 연결해요.
Daemon 설치: 백그라운드 실행을 위해 LaunchAgent나 systemd 유닛을 등록해요.

상세 단계별 가이드

1. 기존 설정 감지 (Existing config detection)

~/.openclaw/openclaw.json 파일이 이미 있다면, Keep / Modify / Reset 중 하나를 선택할 수 있어요. 마법사를 다시 실행한다고 해서 데이터가 그냥 사라지지는 않으니 안심하세요.

초기화: --reset 플래그를 사용하면 기본적으로 설정, 인증 정보, 세션이 삭제돼요. 워크스페이스까지 지우려면 --reset-scope full을 사용하세요.
복구: 설정이 유효하지 않거나 오래된 키가 포함되어 있다면, 마법사가 멈추고 openclaw doctor 실행을 요청할 거예요.
안전성: 삭제 시 rm 대신 trash를 사용해요.

2. 모델 및 인증 (Model/Auth)

다양한 모델 Provider를 지원하며, 각 환경에 맞는 인증 방식을 제안해요.

Anthropic: ANTHROPIC_API_KEY 환경 변수를 쓰거나 직접 입력해요. macOS라면 Keychain의 “Claude Code-credentials”를 확인해요.
OpenAI: OPENAI_API_KEY를 사용하거나 OpenAI Code (Codex) 구독을 연결할 수 있어요.
기타 Provider: xAI (Grok), OpenCode Zen, Vercel AI Gateway, Cloudflare AI Gateway, MiniMax, Moonshot (Kimi) 등을 지원해요.
저장 방식: 기본은 평문 저장이에요. 보안이 중요하다면 --secret-input-mode ref를 사용해 환경 변수 참조(keyRef) 방식으로 저장하세요.

Headless 서버 팁: 브라우저가 있는 PC에서 OAuth를 완료한 뒤, ~/.openclaw/credentials/oauth.json 파일을 서버로 복사해서 사용하세요.

3. 워크스페이스 (Workspace)

기본 경로는 ~/.openclaw/workspace예요. 이곳에 에이전트 구동에 필요한 파일들이 준비돼요. 더 자세한 구조는 Agent workspace 가이드를 참고해 보세요.

4. Gateway 설정

Port, Bind 주소, 인증 모드 등을 설정해요.

인증 권장: 로컬에서만 쓰더라도 Token 모드 사용을 권장해요.
SecretRef: 토큰을 직접 저장하지 않고 환경 변수나 파일에서 참조하도록 설정할 수 있어요. 만약 SecretRef가 해결되지 않으면 설정 단계에서 미리 에러 메시지를 보여줘요.
비활성화: 모든 로컬 프로세스를 완전히 신뢰할 수 있을 때만 인증을 끄세요.

5. 채널 (Channels)

에이전트와 대화할 통로를 선택해요.

WhatsApp/Telegram/Discord: 봇 토큰이나 QR 코드로 로그인해요.
BlueBubbles: iMessage를 쓰고 싶다면 이 방식을 추천해요.
보안: 기본적으로 페어링(Pairing) 모드가 동작해요. 첫 DM을 보내면 코드가 오는데, openclaw pairing approve <channel> <code>로 승인해야 해요.

6. 웹 검색 (Web search)

Perplexity, Brave, Gemini 등의 API Key를 연결해 에이전트에게 검색 능력을 줄 수 있어요. --skip-search로 건너뛰고 나중에 openclaw configure --section web으로 설정해도 돼요.

7. Daemon 설치

컴퓨터를 켰을 때 자동으로 실행되도록 설정해요.

OS별: macOS는 LaunchAgent, Linux는 systemd를 사용해요. Linux에서는 로그아웃 후에도 프로세스가 유지되도록 loginctl enable-linger 시도를 해요.
런타임: Node.js를 강력히 추천해요. Bun은 추천하지 않아요.
검증: Daemon 설치 시점에 토큰이나 설정값이 유효한지 미리 체크해서 실패를 방지해요.

8. 상태 체크 및 스킬

마지막으로 Gateway를 띄우고 openclaw health를 실행해 모든 게 정상인지 확인해요. openclaw status --deep을 쓰면 더 상세한 상태를 볼 수 있어요. 또한 pnpm이나 npm을 통해 필요한 추가 스킬들을 설치하며 마무리해요.

Troubleshooting

GUI가 없는 환경인가요?: 마법사가 브라우저를 여는 대신 Control UI 접속을 위한 SSH 포트 포워딩 안내를 출력할 거예요.
UI 에셋이 없나요?: 마법사가 자동으로 빌드를 시도해요. 안 된다면 pnpm ui:build를 직접 실행해 보세요.
인증 모드 충돌: gateway.auth.token과 password가 모두 설정되어 있는데 mode가 비어있다면 Daemon 설치가 차단돼요. 하나를 명시적으로 선택해 주세요.

설정 중에 막히는 부분이 있다면 언제든 AI Setup Assistant에게 물어보세요!

What’s Next

새로운 도구를 설정할 때마다 터미널에서 묻는 말에 일일이 답하는 건 정말 번거로운 일이에요. 특히 여러 대의 서버에 배포하거나 CI/CD 파이프라인을 구축할 때 대화형 인터페이스는 자동화의 걸림돌이 되곤 하죠.

반복되는 설정 과정을 자동화하고 싶은 개발자라면 이 가이드가 큰 도움이 될 거예요. --non-interactive 플래그 하나로 모든 과정을 스크립트로 처리할 수 있습니다.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요. (원문 문서 기준)

openclaw CLI
Anthropic, Gemini 등 각 모델 제공업체의 API 키
Node.js (Daemon 실행 시 필요)
설정할 Gateway 포트 및 바인딩 정보

빠른 시작

가장 빠른 방법은 --non-interactive 플래그를 사용하여 온보딩을 자동화하는 거예요. 아래 명령어를 복사해서 사용하면 5분 안에 설정을 마칠 수 있습니다.

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 플래그를 추가해 보세요.

Gateway 토큰 보안 설정

비대화형 모드에서 Gateway 토큰을 SecretRef로 관리하고 싶다면 아래와 같이 환경 변수를 활용하는 것을 추천해요.

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

다양한 모델 API 키 설정 예시

사용 중인 서비스에 맞춰 아래 명령어 중 하나를 골라 사용하세요.

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

Cloudflare AI Gateway 사용 시:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_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 추가하기

온보딩뿐만 아니라 Agent를 추가할 때도 비대화형 모드를 쓸 수 있어요.

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

문제 해결

설정 중에 문제가 생겼나요? 다음 두 가지만 기억하면 실수를 피할 수 있습니다.

옵션 충돌: --gateway-token과 --gateway-token-ref-env는 동시에 사용할 수 없어요. 둘 중 하나만 선택해 주세요.
플래그 오해: --json을 쓴다고 해서 자동으로 비대화형 모드가 되는 건 아니에요. 스크립트에서 사용할 때는 반드시 --non-interactive(그리고 필요한 경우 --workspace)를 함께 명시해야 합니다.

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요!

다음 단계

새로운 클라이언트를 개발할 때마다 온보딩 로직을 처음부터 다시 만드는 일은 정말 번거로워요. macOS 앱이나 Control UI처럼 서로 다른 환경에서 똑같은 설정 과정을 반복해서 구현하다 보면 금방 지치기 마련이죠.

Gateway는 이런 불편함을 줄이기 위해 온보딩 로직을 직접 구현하지 않고도 단계별 화면을 렌더링할 수 있는 기능을 제공해요.

What You’ll Need

이 기능을 제대로 활용하기 위해 다음 사항을 미리 확인해 주세요.

Java 21: JVM build를 사용하는 경우 반드시 필요해요.
WSL2: Windows 환경에서 사용한다면 WSL2가 설치되어 있어야 해요.

Quick Start

Gateway는 RPC를 통해 위저드 플로우를 외부에 노출해요. 클라이언트는 다음 메서드들을 호출해서 온보딩 과정을 제어할 수 있습니다.

wizard.start
wizard.next
wizard.cancel
wizard.status

이 RPC를 사용하면 클라이언트 앱에서 복잡한 로직을 관리할 필요가 없어져요. 또한, 위저드는 signal-cli 설정을 자동으로 처리해 주는데, 구체적인 동작 방식은 다음과 같아요.

GitHub releases에서 시스템에 맞는 릴리스 에셋을 다운로드합니다.
다운로드한 파일을 ~/.openclaw/tools/signal-cli/<version>/ 경로에 저장합니다.
설정 파일의 channels.signal.cliPath 항목에 해당 경로를 기록합니다.
가능한 경우 Native build를 우선적으로 사용합니다.

Troubleshooting

설정 과정에서 문제가 발생한다면 다음 내용을 확인해 보세요.

Java 버전 오류: JVM build를 사용 중인데 실행이 안 된다면 Java 21이 설치되어 있는지 확인이 필요해요.
Windows 설치 이슈: Windows 사용자는 반드시 WSL2 내에서 Linux 플로우를 따라 설치를 진행해야 합니다.

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 질문해 보세요.

What’s Next

CLI 도구를 쓰다 보면 “위저드가 내 설정 파일에 도대체 무슨 짓을 한 거지?” 싶을 때가 있죠. 수동으로 설정을 고치고 싶거나, 백업을 위해 데이터가 어디에 저장되는지 명확히 알고 싶은 개발자분들을 위해 정리했습니다.

위저드가 자동으로 생성하고 관리하는 파일들의 구조를 파악하면 OpenClaw를 훨씬 편하게 다룰 수 있어요.

필요한 것

~/.openclaw/openclaw.json 파일에 대한 접근 권한
OpenClaw CLI 설치 및 실행 환경

빠른 시작

위저드를 실행하면 주로 ~/.openclaw/openclaw.json 파일에 다음과 같은 필드들이 작성됩니다.

agents.defaults.workspace
agents.defaults.model / models.providers (Minimax를 선택한 경우)
tools.profile (따로 설정하지 않으면 기본값인 "coding"으로 지정되며, 이미 명시적인 값이 있다면 그 값을 유지해요)
gateway.* (mode, bind, auth, tailscale 관련 설정)
session.dmScope (상세 동작은 CLI Onboarding Reference를 참고하세요)
channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
채널 allowlists (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이나 로컬 경로를 통해 플러그인을 설치하라고 친절하게 안내해 줄 거예요.

문제 해결

문제: 특정 채널 설정을 시작할 수 없습니다.
- 해결: 해당 채널이 플러그인 방식인지 확인해 보세요. 위저드가 요청하는 npm 설치 또는 로컬 경로 지정 단계를 먼저 완료해야 설정을 이어갈 수 있습니다.
문제: 기존에 직접 수정한 tools.profile이 초기화될까 봐 걱정됩니다.
- 해결: 위저드는 tools.profile에 이미 명시적인 값이 설정되어 있다면 이를 덮어쓰지 않고 그대로 보존합니다.

설정 과정에서 막히는 부분이 있다면 AI Setup Assistant에게 바로 물어봐 주세요.

다음 단계

위저드 개요: Onboarding Wizard
macOS 앱 온보딩: Onboarding
설정 레퍼런스: Gateway configuration
Providers: WhatsApp, Telegram, Discord, Google Chat, Signal, BlueBubbles (iMessage), iMessage (legacy)
Skills: Skills, Skills config

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.