OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

시작하기

온보딩 참조 자료

이는 openclaw onboard에 대한 전체 참조입니다. 개괄적인 내용은 온보딩(CLI)을 참조하십시오. 단계별 동작과 출력은 CLI 설정 참조를 참조하십시오.

흐름 세부 정보(로컬 모드)

  • 재설정(선택 사항)

    • --reset는 설정을 실행하기 전에 상태를 재설정합니다. 이 옵션 없이 온보딩을 다시 실행하면 기존 구성을 유지하고 이를 기본값으로 재사용합니다.
    • --reset-scope는 --reset에서 제거할 항목을 제어합니다. config(구성 파일 만), config+creds+sessions(기본값) 또는 full(워크스페이스도 제거)입니다.
    • 구성 파일이 유효하지 않으면 온보딩이 중지되고 먼저 openclaw doctor을 실행한 다음 설정을 다시 실행하라는 메시지가 표시됩니다.
    • 재설정은 상태를 휴지통으로 이동합니다(직접 삭제하지 않습니다).

  • 위험 확인

    • 첫 실행 시(또는 wizard.securityAcknowledgedAt이 설정되기 전의 모든 실행 시) 에이전트가 강력하며 전체 시스템 액세스에는 위험이 따른다는 사실을 이해했는지 확인하도록 요청합니다.
    • --non-interactive에는 --accept-risk을 명시적으로 지정해야 합니다. 지정하지 않으면 온보딩은 메시지를 표시하는 대신 오류와 함께 종료됩니다.
    • 대화형 실행에서는 플래그 대신 확인 메시지가 표시되며, 거부하면 설정이 취소됩니다.

  • 모델/인증

    • Anthropic API 키: ANTHROPIC_API_KEY이 있으면 사용하고, 없으면 키를 입력하라는 메시지를 표시한 다음 데몬에서 사용할 수 있도록 저장합니다.
    • Anthropic Claude CLI: Claude CLI 로그인이 이미 존재할 때 선호되는 로컬 경로입니다. OpenClaw는 대안으로 Anthropic 설정 토큰 인증도 계속 지원합니다.
    • OpenAI Code(Codex) 구독(OAuth): 브라우저 흐름이며, code#state을 붙여 넣습니다.
      • 기본 모델이 없는 새 설정에서는 Codex 런타임을 통해 agents.defaults.model을 openai/gpt-5.6-sol으로 설정합니다.
    • OpenAI Code(Codex) 구독(기기 페어링): 수명이 짧은 기기 코드를 사용하는 브라우저 페어링 흐름입니다.
      • 기본 모델이 없는 새 설정에서는 Codex 런타임을 통해 agents.defaults.model을 openai/gpt-5.6-sol으로 설정합니다.
    • OpenAI API 키: OPENAI_API_KEY이 있으면 사용하고, 없으면 키를 입력하라는 메시지를 표시한 다음 인증 프로필에 저장합니다.
      • 기본 모델이 없는 새 설정에서는 agents.defaults.model을 openai/gpt-5.6으로 설정합니다. 한정자가 없는 직접 API 모델 ID는 Sol 티어로 해석됩니다.
    • OpenAI를 추가하거나 재인증할 때는 openai/gpt-5.5을 포함하여 명시적으로 지정한 기존 기본 모델을 유지합니다. 계정에서 GPT-5.6을 제공하지 않으면 openai/gpt-5.5을 명시적으로 선택하십시오. OpenClaw는 모델을 자동으로 다운그레이드하지 않습니다.
    • xAI OAuth: localhost 콜백이 필요 없는 기기 코드 브라우저 로그인이므로 SSH/Docker/VPS에서도 작동합니다(--auth-choice xai-oauth).
    • xAI API 키: XAI_API_KEY을 입력하라는 메시지를 표시합니다(--auth-choice xai-api-key).
    • --auth-choice xai-device-code은 동일한 xAI OAuth 기기 코드 흐름의 수동 전용 호환성 별칭으로 계속 작동합니다. 새 스크립트에는 xai-oauth을 사용하십시오.
    • OpenCode: OPENCODE_API_KEY(또는 OPENCODE_ZEN_API_KEY, https://opencode.ai/auth 에서 발급)을 입력하라는 메시지를 표시하고 Zen 또는 Go 카탈로그를 선택할 수 있게 합니다.
    • Ollama: 먼저 클라우드 + 로컬, 클라우드만 또는 로컬만을 제공합니다. Cloud only은 OLLAMA_API_KEY을 입력하라는 메시지를 표시하고 https://ollama.com을 사용합니다. 호스트 기반 모드에서는 Ollama 기본 URL(기본값 http://127.0.0.1:11434)을 입력하라는 메시지를 표시하고, 사용 가능한 모델을 검색하며, 필요할 때 선택한 로컬 모델을 자동으로 가져옵니다. Cloud + Local은 해당 Ollama 호스트가 클라우드 액세스를 위해 로그인되어 있는지도 확인합니다.
    • 자세한 내용: Ollama
    • API 키: 키를 저장합니다.
    • Vercel AI Gateway(다중 모델 프록시): AI_GATEWAY_API_KEY을 입력하라는 메시지를 표시합니다.
    • 자세한 내용: Vercel AI Gateway
    • Cloudflare AI Gateway: Account ID, Gateway ID 및 CLOUDFLARE_AI_GATEWAY_API_KEY을 입력하라는 메시지를 표시합니다.
    • 자세한 내용: Cloudflare AI Gateway
    • MiniMax: 구성이 자동으로 작성되며, 호스팅 기본값은 MiniMax-M3입니다. API 키 설정에서는 minimax/...을 사용하고, OAuth 설정에서는 minimax-portal/...을 사용합니다.
    • 자세한 내용: MiniMax
    • StepFun: 중국 또는 글로벌 엔드포인트의 StepFun 표준이나 Step Plan에 맞게 구성이 자동으로 작성됩니다.
    • 현재 표준의 기본값은 step-3.5-flash이며, Step Plan에는 step-3.5-flash-2603도 포함됩니다.
    • 자세한 내용: StepFun
    • Synthetic(Anthropic 호환): SYNTHETIC_API_KEY을 입력하라는 메시지를 표시합니다.
    • 자세한 내용: Synthetic
    • Moonshot(Kimi K2): 구성이 자동으로 작성됩니다.
    • Kimi Coding: 구성이 자동으로 작성됩니다.
    • 자세한 내용: Moonshot AI(Kimi + Kimi Coding)
    • 사용자 지정 제공자: OpenAI 호환, OpenAI Responses 호환 또는 Anthropic 호환 엔드포인트에서 작동합니다. 비대화형 플래그: --auth-choice custom-api-key, --custom-base-url, --custom-model-id, --custom-api-key(선택 사항, CUSTOM_API_KEY로 대체), --custom-provider-id(선택 사항, 기본 URL에서 자동 파생), --custom-compatibility openai|openai-responses|anthropic(기본값 openai), --custom-image-input / --custom-text-input(추론된 비전 모델 감지를 재정의)입니다.
    • 건너뛰기: 아직 인증을 구성하지 않습니다.
    • 감지된 옵션에서 기본 모델을 선택하거나 제공자/모델을 직접 입력합니다. 최상의 품질과 더 낮은 프롬프트 인젝션 위험을 위해 제공자 스택에서 사용할 수 있는 가장 강력한 최신 세대 모델을 선택하십시오.
    • 온보딩은 모델 검사를 실행하고 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고합니다.
    • API 키 저장 모드의 기본값은 평문 인증 프로필 값입니다. 대신 환경 변수 기반 참조를 저장하려면 --secret-input-mode ref을 사용하십시오(예: keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }). 참조되는 환경 변수는 이미 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
    • 인증 프로필은 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json(API 키 + OAuth)에 있습니다. ~/.openclaw/credentials/oauth.json은 레거시 가져오기 전용입니다.
    • 자세한 내용: OAuth

  • 워크스페이스

    • 기본값은 ~/.openclaw/workspace입니다(구성 가능).
    • 에이전트 부트스트랩 절차에 필요한 워크스페이스 파일을 초기 생성합니다.
    • 전체 워크스페이스 레이아웃 및 백업 안내서: 에이전트 워크스페이스

  • Gateway

    • 포트(기본값 18789), 바인드, 인증 모드, Tailscale 노출을 구성합니다.
    • 인증 권장 사항: 로컬 WS 클라이언트도 인증해야 하도록 루프백에서도 토큰을 유지하십시오.
    • 토큰 모드에서 대화형 설정은 다음 옵션을 제공합니다.
      • 평문 토큰 생성/저장(기본값)
      • SecretRef 사용(선택 사항)
      • 빠른 시작은 온보딩 프로브/대시보드 부트스트랩을 위해 env, file 및 exec 제공자에서 기존 gateway.auth.token SecretRef를 재사용합니다.
      • 해당 SecretRef가 구성되어 있지만 확인할 수 없는 경우 온보딩은 런타임 인증을 조용히 저하시키는 대신 명확한 해결 메시지와 함께 조기에 실패합니다.
    • 비밀번호 모드에서도 대화형 설정은 평문 또는 SecretRef 저장을 지원합니다.
    • 비대화형 토큰 SecretRef 경로: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다.
      • --gateway-token과 함께 사용할 수 없습니다.
    • 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하십시오.
    • 루프백 이외의 바인드에는 여전히 인증이 필요합니다.

  • 채널

    • WhatsApp: 선택적 QR 로그인입니다.
    • Telegram: 봇 토큰입니다.
    • Discord: 봇 토큰입니다.
    • Google Chat: 서비스 계정 JSON + Webhook 대상입니다.
    • Mattermost(Plugin): 봇 토큰 + 기본 URL입니다.
    • Signal(Plugin): 선택적 signal-cli 설치 + 계정 구성입니다.
    • iMessage: imsg CLI 경로 + Messages DB 액세스입니다. Gateway가 Mac 외부에서 실행될 때는 SSH 래퍼를 사용하십시오.
    • Discord, Feishu, Microsoft Teams, QQ Bot, Slack 및 기타 채널은 온보딩에서 설치할 수 있는 Plugin으로 제공됩니다. 전체 카탈로그: 채널.
    • DM 보안: 기본값은 페어링입니다. 첫 DM에서 코드를 전송합니다. openclaw pairing approve <channel> <code>을 통해 승인하거나 허용 목록을 사용하십시오.

  • 웹 검색

    • Brave, Codex(호스팅 검색), DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Parallel, Perplexity, SearXNG 또는 Tavily와 같은 지원 제공자를 선택하거나 건너뜁니다.
    • API 기반 제공자는 빠른 설정을 위해 환경 변수나 기존 구성을 사용할 수 있습니다. 키가 필요 없는 제공자는 대신 제공자별 사전 요구 사항을 사용합니다.
    • --skip-search을 사용하여 건너뜁니다.
    • 나중에 구성: openclaw configure --section web.

  • 데몬 설치

    • macOS: LaunchAgent
      • 로그인한 사용자 세션이 필요합니다. 헤드리스 환경에서는 사용자 지정 LaunchDaemon을 사용하십시오(제공되지 않음).
    • Linux(및 WSL2를 통한 Windows): systemd 사용자 유닛
      • 온보딩은 로그아웃 후에도 Gateway가 계속 실행되도록 loginctl enable-linger <user>을 통해 lingering 활성화를 시도합니다.
      • sudo를 요청할 수 있습니다(/var/lib/systemd/linger에 씀). 먼저 sudo 없이 시도합니다.
    • 네이티브 Windows: 먼저 예약된 작업을 사용합니다. 작업 생성이 거부되면 OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 대체하고 Gateway를 즉시 시작합니다.
    • 런타임 선택: 표준 런타임 상태 저장소가 node:sqlite을 사용하므로 Node가 필요합니다. 레거시 Bun 서비스는 복구 중 Node로 마이그레이션됩니다.
    • 토큰 인증에 토큰이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, 데몬 설치는 이를 검증하지만 확인된 평문 토큰 값을 감독자 서비스 환경 메타데이터에 영구 저장하지 않습니다.
    • 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef를 확인할 수 없는 경우, 실행 가능한 안내와 함께 데몬 설치가 차단됩니다.
    • gateway.auth.token과 gateway.auth.password이 모두 구성되어 있고 gateway.auth.mode이 설정되지 않은 경우, 모드를 명시적으로 설정할 때까지 데몬 설치가 차단됩니다.

  • 상태 검사

    • 필요한 경우 Gateway를 시작하고 openclaw health을 실행합니다.
    • 팁: openclaw status --deep은 지원되는 경우 채널 프로브를 포함하여 실시간 Gateway 상태 프로브를 상태 출력에 추가합니다(연결 가능한 Gateway 필요).

  • Skills(권장)

    • 사용 가능한 스킬을 읽고 요구 사항을 확인합니다.
    • Node 관리자를 선택할 수 있습니다: npm / pnpm / bun.
    • 신뢰할 수 있는 번들 Skills의 선택적 종속성을 자동으로 설치합니다(일부는 macOS에서 Homebrew 사용).
    • Homebrew, uv 또는 Go 설치 프로그램 사전 요구 사항을 사용할 수 없는 Skills를 건너뛰고, 수동 설정 안내와 함께 그룹화하며, 사전 요구 사항이 설치되면 openclaw doctor을 안내합니다.

  • 완료

    • 요약 + 다음 단계입니다. Terminal, Browser 또는 나중에 진행할지 묻는 에이전트를 어떻게 부화시키시겠습니까? 메시지를 포함합니다.

    • 비대화형 모드

    온보딩을 자동화하거나 스크립트로 실행하려면 --non-interactive --accept-risk을 사용하십시오(이 플래그는 필수 위험 승인 항목이며, 이 플래그가 없으면 온보딩이 오류와 함께 종료됩니다).

    bash
    openclaw onboard --non-interactive --accept-risk \  --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 토큰 SecretRef:

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

    --gateway-token과 --gateway-token-ref-env은 함께 사용할 수 없습니다.

    공급자별 명령 예시는 CLI 자동화에 있습니다. 플래그의 의미와 단계 순서는 이 참조 페이지를 확인하십시오.

    에이전트 추가(비대화형)

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

    main은 예약된 에이전트 ID이므로 openclaw agents add에 사용할 수 없습니다.

    Gateway 마법사 RPC

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

    Signal 설정(signal-cli)

    온보딩은 signal-cli이 PATH에 있는지 감지하고, 없으면 설치를 제안합니다.

    • Linux x86-64: signal-cli GitHub 릴리스에서 공식 네이티브 GraalVM 빌드를 다운로드하여 ~/.openclaw/tools/signal-cli/<version>/ 아래에 저장합니다.
    • macOS 및 기타 아키텍처: 대신 Homebrew를 통해 설치합니다.
    • 네이티브 Windows: 아직 지원되지 않습니다. Linux 설치 경로를 사용하려면 WSL2 내에서 온보딩을 실행하십시오.
    • 어떤 경우든 channels.signal.cliPath을 구성에 기록합니다.

    마법사가 기록하는 항목

    ~/.openclaw/openclaw.json의 일반적인 필드는 다음과 같습니다.

    • agents.defaults.workspace
    • --skip-bootstrap이 전달된 경우 agents.defaults.skipBootstrap
    • agents.defaults.model / models.providers(Minimax를 선택한 경우)
    • tools.profile(설정되지 않은 경우 로컬 온보딩의 기본값은 "coding"이며, 기존의 명시적 값은 유지됩니다)
    • gateway.*(모드, 바인딩, 인증, Tailscale)
    • session.dmScope(설정되지 않은 경우 로컬 온보딩에서는 기본값을 "per-channel-peer"로 지정하며, 기존의 명시적 값은 유지됩니다. 자세한 내용은 CLI 설정 참조를 확인하십시오)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • 채널 프롬프트에서 사용을 선택한 경우 채널 DM 허용 목록. Discord, Matrix, Microsoft Teams 및 Slack은 가능한 경우 이름을 ID로 변환하며, 다른 채널에는 ID를 직접 입력합니다(예: 숫자로 된 Telegram 발신자 ID 또는 WhatsApp 전화번호).
    • skills.install.nodeManager
      • setup --node-manager은 npm, pnpm 또는 bun을 허용합니다.
      • 수동 구성에서는 skills.install.nodeManager을 직접 설정하여 계속 yarn을 사용할 수 있습니다.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode
    • wizard.securityAcknowledgedAt

    openclaw agents add은 agents.list[] 및 선택적 bindings을 기록합니다.

    WhatsApp 자격 증명은 ~/.openclaw/credentials/whatsapp/<accountId>/ 아래에 저장됩니다. 활성 세션과 대화 기록은 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite에 저장됩니다. ~/.openclaw/agents/<agentId>/sessions/ 디렉터리는 레거시 마이그레이션 입력과 보관/지원 산출물에 사용됩니다.

    일부 채널은 Plugin으로 제공됩니다. 설정 중 하나를 선택하면 온보딩에서 구성하기 전에 설치(npm 또는 로컬 경로)하라는 메시지를 표시합니다.

    관련 문서

    Was this useful?
    On this page

    On this page