English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

First steps

온보딩 (CLI)

CLI 온보딩은 macOS, Linux 또는 Windows(WSL2 사용, 강력 권장)에서 OpenClaw를 설정하는 권장 방법입니다. 하나의 안내 흐름에서 로컬 Gateway 또는 원격 Gateway 연결과 채널, skills, 워크스페이스 기본값을 구성합니다.

openclaw onboard

나중에 다시 구성하려면:

openclaw configure
openclaw agents add <name>

QuickStart와 Advanced

온보딩은 QuickStart(기본값) 또는 Advanced(전체 제어)로 시작합니다.

QuickStart(기본값)

  • 로컬 Gateway(루프백)
  • 워크스페이스 기본값(또는 기존 워크스페이스)
  • Gateway 포트 18789
  • Gateway 인증 Token(루프백에서도 자동 생성)
  • 새 로컬 설정의 기본 도구 정책: tools.profile: "coding"(기존의 명시적 프로필은 보존됨)
  • DM 격리 기본값: 로컬 온보딩은 설정되지 않은 경우 session.dmScope: "per-channel-peer"를 씁니다. 자세한 내용: CLI 설정 참고
  • Tailscale 노출 꺼짐
  • Telegram + WhatsApp DM은 기본적으로 허용 목록으로 설정됩니다(전화번호 입력을 요청받게 됩니다)

Advanced(전체 제어)

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

온보딩이 구성하는 항목

**로컬 모드(기본값)**는 다음 단계를 안내합니다.

  1. 모델/인증 — Custom Provider (OpenAI 호환, Anthropic 호환 또는 Unknown 자동 감지)를 포함하여 지원되는 모든 제공자/인증 흐름(API 키, OAuth 또는 제공자별 수동 인증)을 선택합니다. 기본 모델을 선택합니다. 보안 참고: 이 에이전트가 도구를 실행하거나 webhook/hooks 콘텐츠를 처리한다면, 사용 가능한 가장 강력한 최신 세대 모델을 선호하고 도구 정책을 엄격하게 유지하세요. 더 약하거나 오래된 계층은 프롬프트 인젝션에 더 취약합니다. 비대화형 실행에서는 --secret-input-mode ref가 평문 API 키 값 대신 env 기반 참조를 인증 프로필에 저장합니다. 비대화형 ref 모드에서는 제공자 env var가 설정되어 있어야 합니다. 해당 env var 없이 인라인 키 플래그를 전달하면 즉시 실패합니다. 대화형 실행에서 비밀 참조 모드를 선택하면 환경 변수 또는 구성된 제공자 참조(file 또는 exec)를 가리킬 수 있으며, 저장 전에 빠른 사전 검증을 수행합니다. Anthropic의 경우 대화형 온보딩/구성은 선호되는 로컬 경로로 Anthropic Claude CLI를, 권장 프로덕션 경로로 Anthropic API key를 제공합니다. Anthropic setup-token도 지원되는 토큰 인증 경로로 계속 사용할 수 있습니다.
  2. 워크스페이스 — 에이전트 파일 위치(기본값 ~/.openclaw/workspace). 부트스트랩 파일을 시드합니다.
  3. Gateway — 포트, 바인드 주소, 인증 모드, Tailscale 노출. 대화형 토큰 모드에서는 기본 평문 토큰 저장소를 선택하거나 SecretRef를 사용할 수 있습니다. 비대화형 토큰 SecretRef 경로: --gateway-token-ref-env &lt;ENV_VAR&gt;.
  4. 채널 — BlueBubbles, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp 등 기본 제공 및 번들 채팅 채널.
  5. 데몬 — LaunchAgent(macOS), systemd 사용자 유닛(Linux/WSL2) 또는 사용자별 Startup 폴더 대체 경로가 있는 네이티브 Windows Scheduled Task를 설치합니다. 토큰 인증에 토큰이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, 데몬 설치는 이를 검증하지만 해석된 토큰을 supervisor 서비스 환경 메타데이터에 영구 저장하지 않습니다. 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef가 해석되지 않은 경우, 실행 가능한 안내와 함께 데몬 설치가 차단됩니다. gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않은 경우, 모드가 명시적으로 설정될 때까지 데몬 설치가 차단됩니다.
  6. 상태 확인 — Gateway를 시작하고 실행 중인지 확인합니다.
  7. Skills — 권장 skills와 선택적 의존성을 설치합니다.

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

다른 에이전트 추가

자체 워크스페이스, 세션, 인증 프로필을 가진 별도 에이전트를 만들려면 openclaw agents add <name>을 사용하세요. --workspace 없이 실행하면 온보딩이 시작됩니다.

설정되는 항목:

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

참고:

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

전체 참고

자세한 단계별 분석과 설정 출력은 CLI 설정 참고를 참조하세요. 비대화형 예제는 CLI 자동화를 참조하세요. RPC 세부 정보를 포함한 더 깊이 있는 기술 참고는 온보딩 참고를 참조하세요.

관련 문서